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 ego-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 and a DV consumer does not consume DV.
44 'Producers' typically refer to files but may also indicate
45 devices (such as dv1394 input or video4linux). Hence, the more
46 generic term is used [yes, the more generic usage is out of
49 'Filters' are frame modifiers - they always guarantee that for
50 every frame they receive, they output *precisely* one frame.
51 Never more, never less, ever.
53 'Transitions' collect frames from two tracks (a and b) and
54 output 1 modified frame on their 'a track', and 1 unmodified
55 frame on their 'b track'. Never more, never less, ever.
57 'Consumers' collect frames from a producer, do something with
58 them and destroy them.
60 Collectively, these are known as 'services'.
62 All services have 'properties' associated to them. These are
63 typically defaulted or evaluated and may be overriden on a case
66 All services except consumers obey in and out properties.
68 Consumers have no say in the flow of frames [though they may
69 give the illusion that they do]. They get frames from a
70 connected producer, use them, destroy them and get more.
75 To play a file with the default SDL PAL consumer, usage is:
79 Note that 'file' can be anything that inigo has a known
80 'producer' mapping for (so this can be anything from .dv to
86 Properties can be assigned to the producer by adding additional
87 name=value pairs after the producer:
89 $ inigo file in=50 out=100 something="something else"
91 Note that while some properties have meaning to all producers
92 (for example: in, out and length are guaranteed to be valid for
93 all, though typically, length is determined automatically), the
94 validity of others are dependent on the producer - however,
95 properties will always be assigned, but it doesn't mean they
101 Multiple files of different types can be used:
103 $ inigo a.dv b.mpg c.png
105 Properties can be assigned to each file:
107 $ inigo a.dv in=50 out=100 b.mpg out=500 c.png out=500
112 The Multiple Files examples above will logically playout one
115 However, inigo doesn't care too much about changes in frame
116 dimensions or audio specification, so you may need to add
117 additional normalising filters to that, ie:
119 $ inigo a.dv b.mpg c.png -filter resize -filter resample
121 These filters are designed to guarantee that the consumer gets
124 It should also be stressed that filters are applied in the order
125 in which they're specified.
130 As with producers, properties may be specified on filters too.
132 Again, in and out properties are common to all, so to apply a
133 filter to a range of frames, you would use something like:
135 $ inigo a.dv -filter greyscale in=0 out=50
137 Again, filters have their own set of rules about properties and
138 will silently ignore properties that do not apply.
143 The -group switch is provided to force default properties on the
144 following 'services'. For example:
146 $ inigo -group in=0 out=49 clip*
148 would play the first 50 frames of all clips that match the wild
151 Note that the last -group settings also apply to the following
152 filters, transitions and consumers, so:
154 $ inigo -group in=0 out=49 clip* -filter greyscale
156 is *probably not* what you want (ie: the greyscale filter would
157 only be applied to the first 50 frames).
159 To shed the group properties, you can use any empty group:
161 $ inigo -group in=0 out=49 clip* -group -filter greyscale
164 Introducing Tracks and Blanks:
166 So far, all of the examples have shown the definition of a
167 single playlist, or more accurately, track.
169 When multiple tracks exist, the consumer will receive a frame
170 from the 'lowest numbered' track that is generating a non-blank
173 It is best to visualise a track arrangement, so we'll start with
176 $ inigo a.dv out=49 -track b.dv
178 This can be visualised as follows:
186 Playout will show the first 50 frames of a and the 51st frame
187 shown will be the 51st frame of b.
189 To have the 51st frame be the first frame of b, we can use the
192 $ inigo a.dv out=49 -track -blank 49 b.dv
194 Which we can visualise as:
198 +-------+-------------------+
200 +-------------------+
202 Now playout will continue as though a and b clips are on the
203 same track (which is about as useful as reversing the process of
209 Where tracks become useful is in the placing of transitions.
211 Here we need tracks to overlap, so a useful multitrack
212 definition could be given as:
214 $ inigo a.dv out=49 -transition luma in=25 out=49 \
218 Now we're cooking - our visualisation would be something like:
222 +---+---+--------------+
226 Playout will now show the first 25 frames of a and then a fade
227 transition for 25 frames between a and b, and will finally
228 playout the remainder of b.
231 Reversing a Transition:
233 When we visualise a track definition, we also see situtations
236 +-------+ +----------+
238 +---+---+--------------+----+-----+
240 +-----------------------+
242 In this case, we have two transitions, a1 to b and b to a2.
244 In this scenario, we define a command line as follows:
246 $ inigo a.dv out=49 -blank 49 a2.dv \
247 -transition luma in=25 out=49 \
248 -transition luma in=100 out=124 reverse=1 \
250 -blank 24 b.dv out=99
255 A filter applies to a [specified region of a] single track, so
256 normalisation filters need to be applied to each track when
259 This user specification is a necessary evil (you do not want to
260 resize a text or png overlay to be the size of the frame that
261 the consumer is requesting, and you may not want to unecessarily
262 resize a video track if you will be later rescaling it for
268 Inigo has a built in serialisation mechanism - you can build up
269 your command, test it via any consumer and then add a -serialise
270 file.inigo switch to save it.
272 The saved file can be subsequently used as a clip by either
273 miracle or inigo. Take care though - paths to files are saved as
274 provided on the command line....
279 Some filters/transitions should be applied on the output frame
280 regardless of which track it comes from - for example, you might
281 have a 3rd text track or a watermark which you want composited
282 on every frame, and of course, there's the obscure feature....
284 A -post switch will be added to provided this feature at some