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
94 (for example: in, out and length are guaranteed to be valid for
95 all, though typically, length is determined automatically), the
96 validity of others are dependent on the producer - however,
97 properties will always be assigned, but it doesn't mean they
103 Multiple files of different types can be used:
105 $ inigo a.dv b.mpg c.png
107 Properties can be assigned to each file:
109 $ inigo a.dv in=50 out=100 b.mpg out=500 c.png out=500
114 The Multiple Files examples above will logically playout one
117 However, inigo doesn't care too much about changes in frame
118 dimensions or audio specification, so you may need to add
119 additional normalising filters to that, ie:
121 $ inigo a.dv b.mpg c.png -filter resize -filter resample
123 These filters are designed to guarantee that the consumer gets
126 It should also be stressed that filters are applied in the order
127 in which they're specified.
132 As with producers, properties may be specified on filters too.
134 Again, in and out properties are common to all, so to apply a
135 filter to a range of frames, you would use something like:
137 $ inigo a.dv -filter greyscale in=0 out=50
139 Again, filters have their own set of rules about properties and
140 will silently ignore properties that do not apply.
145 The -group switch is provided to force default properties on the
146 following 'services'. For example:
148 $ inigo -group in=0 out=49 clip*
150 would play the first 50 frames of all clips that match the wild
153 Note that the last -group settings also apply to the following
154 filters, transitions and consumers, so:
156 $ inigo -group in=0 out=49 clip* -filter greyscale
158 is *probably not* what you want (ie: the greyscale filter would
159 only be applied to the first 50 frames).
161 To shed the group properties, you can use any empty group:
163 $ inigo -group in=0 out=49 clip* -group -filter greyscale
166 Introducing Tracks and Blanks:
168 So far, all of the examples have shown the definition of a
169 single playlist, or more accurately, track.
171 When multiple tracks exist, the consumer will receive a frame
172 from the 'lowest numbered' track that is generating a non-blank
175 It is best to visualise a track arrangement, so we'll start with
178 $ inigo a.dv in=0 out=49 -track b.dv
180 This can be visualised as follows:
188 Playout will show the first 50 frames of a and the 51st frame
189 shown will be the 51st frame of b.
191 To have the 51st frame be the first frame of b, we can use the
194 $ inigo a.dv out=49 -track -blank 49 b.dv
196 Which we can visualise as:
200 +-------+-------------------+
202 +-------------------+
204 Now playout will continue as though a and b clips are on the
205 same track (which is about as useful as reversing the process of
211 Where tracks become useful is in the placing of transitions.
213 Here we need tracks to overlap, so a useful multitrack
214 definition could be given as:
216 $ inigo a.dv out=49 -transition luma in=25 out=49 \
220 Now we're cooking - our visualisation would be something like:
224 +---+---+--------------+
228 Playout will now show the first 25 frames of a and then a fade
229 transition for 25 frames between a and b, and will finally
230 playout the remainder of b.
233 Reversing a Transition:
235 When we visualise a track definition, we also see situtations
238 +-------+ +----------+
240 +---+---+--------------+----+-----+
242 +-----------------------+
244 In this case, we have two transitions, a1 to b and b to a2.
246 In this scenario, we define a command line as follows:
248 $ inigo a.dv out=49 -blank 49 a2.dv \
249 -transition luma in=25 out=49 \
250 -transition luma in=100 out=124 reverse=1 \
252 -blank 24 b.dv out=99
257 A filter applies to a [specified region of a] single track, so
258 normalisation filters need to be applied to each track when
261 This user specification is a necessary evil (you do not want to
262 resize a text or png overlay to be the size of the frame that
263 the consumer is requesting, and you may not want to unecessarily
264 resize a video track if you will be later rescaling it for
270 Inigo has a built in serialisation mechanism - you can build up
271 your command, test it via any consumer and then add a -serialise
272 file.inigo switch to save it.
274 The saved file can be subsequently used as a clip by either
275 miracle or inigo. Take care though - paths to files are saved as
276 provided on the command line....
281 Some filters/transitions should be applied on the output frame
282 regardless of which track it comes from - for example, you might
283 have a 3rd text track or a watermark which you want composited
284 on every frame, and of course, there's the obscure feature....
286 A -post switch will be added to provided this feature at some