6 inigo was developed as a test tool for the MLT framework. It can
7 be thought of as a powerful, if somewhat obscure, multitrack
8 command line oriented video editor.
10 The following details the usage of the tool and as a result,
11 provides a lot of insight into the workings of the MLT framework.
16 inigo [ -group [ name=value ]* ]
17 [ -consumer id[:arg] [ name=value ]* ]
18 [ -filter id[:arg] [ name=value ] * ]
19 [ -transition id[:arg] [ name=value ] * ]
22 [ producer [ name=value ] * ]+
23 [ -serialise file.inigo ]
28 1. Order is incredibly important;
30 2. Error checking on command line parsing is weak;
32 3. Please refer to services.txt for details on services
35 4. The MLT framework, from which inigo has inherited its
36 naming convention, is very mlt-centric. Producers produce
37 MLT frame objects and consumers consume MLT frame objects.
38 The distinction is important - a DV producer does not produce
39 DV, it produces MLT frames from a DV source, and similarly a
40 DV consumer does not consume DV, it consumes MLT frames and
46 'Producers' typically refer to files but may also indicate
47 devices (such as dv1394 input or video4linux). Hence, the more
48 generic term is used [yes, the more generic usage is out of
51 'Filters' are frame modifiers - they always guarantee that for
52 every frame they receive, they output *precisely* one frame.
53 Never more, never less, ever.
55 'Transitions' collect frames from two tracks (a and b) and
56 output 1 modified frame on their 'a track', and 1 unmodified
57 frame on their 'b track'. Never more, never less, ever.
59 'Consumers' collect frames from a producer, do something with
60 them and destroy them.
62 Collectively, these are known as 'services'.
64 All services have 'properties' associated to them. These are
65 typically defaulted or evaluated and may be overriden on a case
68 All services except consumers obey in and out properties.
70 Consumers have no say in the flow of frames [though they may
71 give the illusion that they do]. They get frames from a
72 connected producer, use them, destroy them and get more.
77 To play a file with the default SDL PAL consumer, usage is:
81 Note that 'file' can be anything that inigo has a known
82 'producer' mapping for (so this can be anything from .dv to
88 Properties can be assigned to the producer by adding additional
89 name=value pairs after the producer:
91 $ inigo file in=50 out=100 something="something else"
93 Note that while some properties have meaning to all producers (for
94 example: in, out and length are guaranteed to be valid for all, though
95 typically, length is determined automatically), the validity of others
96 are dependent on the producer - however, properties will always be
97 assigned and silently ignored if they won't be used.
102 Multiple files of different types can be used:
104 $ inigo a.dv b.mpg c.png
106 Properties can be assigned to each file:
108 $ inigo a.dv in=50 out=100 b.mpg out=500 c.png out=500
110 MLT will take care of 'normalising' the output of a producer to ensure
111 that the consumer gets what it needs. So, in the case above, the mlt
112 framework will ensure that images are rescaled and audio resampled to meet
113 the requirements of your configuration (which, by default, will be PAL).
114 See 'Appendix A: Normalisation Rules' below.
119 Filters are frame modifiers - they can change the contents of the audio or
120 the images associated to a frame.
122 $ inigo a.dv -filter greyscale
124 As with producers, properties may be specified on filters too.
126 Again, in and out properties are common to all, so to apply a filter to a
127 range of frames, you would use something like:
129 $ inigo a.dv -filter greyscale in=0 out=50
131 Again, filters have their own set of rules about properties and will
132 silently ignore properties that do not apply.
137 The -group switch is provided to force default properties on the
138 following 'services'. For example:
140 $ inigo -group in=0 out=49 clip*
142 would play the first 50 frames of all clips that match the wild
145 Note that the last -group settings also apply to the following
146 filters, transitions and consumers, so:
148 $ inigo -group in=0 out=49 clip* -filter greyscale
150 is *probably not* what you want (ie: the greyscale filter would
151 only be applied to the first 50 frames).
153 To shed the group properties, you can use any empty group:
155 $ inigo -group in=0 out=49 clip* -group -filter greyscale
158 Introducing Tracks and Blanks:
160 So far, all of the examples have shown the definition of a single
161 playlist, or more accurately, track.
163 When multiple tracks exist, the consumer will receive a frame
164 from the 'lowest numbered' track that is generating a non-blank
167 It is best to visualise a track arrangement, so we'll start with
170 $ inigo a.dv in=0 out=49 -track b.dv
172 This can be visualised as follows:
180 Playout will show the first 50 frames of a and the 51st frame
181 shown will be the 51st frame of b.
183 To have the 51st frame be the first frame of b, we can use the
186 $ inigo a.dv out=49 -track -blank 49 b.dv
188 Which we can visualise as:
192 +-------+-------------------+
194 +-------------------+
196 Now playout will continue as though a and b clips are on the
197 same track (which on its own, is about as useful as reversing the
198 process of slicing bread).
203 Where tracks become useful is in the placing of transitions.
205 Here we need tracks to overlap, so a useful multitrack
206 definition could be given as:
208 $ inigo a.dv out=49 \
211 -transition luma in=25 out=49 a_track=0 b_track=1
213 Now we're cooking - our visualisation would be something like:
217 +---+---+--------------+
221 Playout will now show the first 25 frames of a and then a fade
222 transition for 25 frames between a and b, and will finally
223 playout the remainder of b.
226 Reversing a Transition:
228 When we visualise a track definition, we also see situtations
231 +-------+ +----------+
233 +---+---+--------------+----+-----+
235 +-----------------------+
237 In this case, we have two transitions, a1 to b and b to a2.
239 In this scenario, we define a command line as follows:
241 $ inigo a.dv out=49 -blank 49 a2.dv \
243 -blank 24 b.dv out=99 \
244 -transition luma in=25 out=49 a_track=0 b_track=1 \
245 -transition luma in=100 out=124 reverse=1 a_track=0 b_track=1
250 Inigo has a built in serialisation mechanism - you can build up
251 your command, test it via any consumer and then add a -serialise
252 file.inigo switch to save it.
254 The saved file can be subsequently used as a clip by either
255 miracle or inigo. Take care though - paths to files are saved as
256 provided on the command line....
258 A more expressive serialisation can be obtained with the westley consumer
259 - this will provide an xml document which can be used freely in inigo and
262 See westley.txt for more information.
267 Some filters/transitions should be applied on the output frame regardless
268 of which track it comes from - for example, you might have a 3rd text
269 track or a watermark which you want composited on every frame, and of
270 course, there's the obscure filter....
272 inigo only supports this in two invocations - as a simple example:
274 $ inigo a.dv -track -blank 100 b.dv -consumer westley:basic.westley
275 $ inigo basic.westley -filter watermark:watermark.png