3 Copyright (C) 2004 Ushodaya Enterprised Limited
4 Author: Charles Yates <charles.yates@pandora.be>
5 Last Revision: 2004-03-20
13 inigo was developed as a test tool for the MLT framework. It can be thought
14 of as a powerful, if somewhat obscure, multitrack command line oriented
17 The following details the usage of the tool and as a result, provides a lot
18 of insight into the workings of the MLT framework.
23 inigo [ -group [ name=value ]* ]
24 [ -consumer id[:arg] [ name=value ]* ]
25 [ -filter filter[:arg] [ name=value ] * ]
26 [ -attach filter[:arg] [ name=value ] * ]
27 [ -mix length [ -mixer transition ]* ]
28 [ -transition id[:arg] [ name=value ] * ]
31 [ -split relative-frame ]
34 [ producer [ name=value ] * ]+
39 1. Order is incredibly important;
41 2. Error checking on command line parsing is weak;
43 3. Please refer to services.txt for details on services available;
45 4. The MLT framework, from which inigo has inherited its naming convention,
46 is very mlt-centric. Producers produce MLT frame objects and consumers
47 consume MLT frame objects. The distinction is important - a DV producer
48 does not produce DV, it produces MLT frames from a DV source, and similarly
49 a DV consumer does not consume DV, it consumes MLT frames and produces DV
55 'Producers' typically refer to files but may also indicate devices (such as
56 dv1394 input or video4linux). Hence, the more generic term is used [the more
57 generic usage is out of scope for now...].
59 'Filters' are frame modifiers - they always guarantee that for every frame
60 they receive, they output *precisely* one frame. Never more, never less,
61 ever. Nothing says that a filter cannot generate frames though
63 'Transitions' collect frames from two tracks (a and b) and output 1
64 modified frame on their 'a track', and 1 unmodified frame on their 'b track'.
65 Never more, never less, ever.
67 'Consumers' collect frames from a producer, do something with them and
70 Collectively, these are known as 'services'.
72 All services have 'properties' associated to them. These are typically
73 defaulted or evaluated and may be overriden on a case by case basis.
75 All services except consumers obey in and out properties.
77 Consumers have no say in the flow of frames [though they may give the
78 illusion that they do]. They get frames from a connected producer, use them,
79 destroy them and get more.
84 To play a file with the default SDL PAL consumer, usage is:
88 Note that 'file' can be anything that inigo has a known 'producer' mapping
89 for (so this can be anything from .dv to .txt).
91 You can also specify the producer directly, for example:
93 $ inigo avformat:file.mpeg
95 Would force the direct use of avformat for loading the file.
100 Properties can be assigned to the producer by adding additional name=value
101 pairs after the producer:
103 $ inigo file in=50 out=100 something="something else"
105 Note that while some properties have meaning to all producers (for example:
106 in, out and length are guaranteed to be valid for all, though typically,
107 length is determined automatically), the validity of others are dependent on
108 the producer - however, properties will always be assigned and silently
109 ignored if they won't be used.
114 Multiple files of different types can be used:
116 $ inigo a.dv b.mpg c.png
118 Properties can be assigned to each file:
120 $ inigo a.dv in=50 out=100 b.mpg out=500 c.png out=500
122 MLT will take care of 'normalising' the output of a producer to ensure
123 that the consumer gets what it needs. So, in the case above, the mlt
124 framework will ensure that images are rescaled and audio resampled to meet
125 the requirements of your configuration (which, by default, will be PAL).
126 See 'Appendix A: Normalisation Rules' below.
131 Filters are frame modifiers - they can change the contents of the audio or
132 the images associated to a frame.
134 $ inigo a.dv -filter greyscale
136 As with producers, properties may be specified on filters too.
138 Again, in and out properties are common to all, so to apply a filter to a
139 range of frames, you would use something like:
141 $ inigo a.dv -filter greyscale in=0 out=50
143 Again, filters have their own set of rules about properties and will
144 silently ignore properties that do not apply.
149 The -group switch is provided to force default properties on the following
150 'services'. For example:
152 $ inigo -group in=0 out=49 clip*
154 would play the first 50 frames of all clips that match the wild card
157 Note that the last -group settings also apply to the following filters,
158 transitions and consumers, so:
160 $ inigo -group in=0 out=49 clip* -filter greyscale
162 is *probably not* what you want (ie: the greyscale filter would only be
163 applied to the first 50 frames).
165 To shed the group properties, you can use any empty group:
167 $ inigo -group in=0 out=49 clip* -group -filter greyscale
172 As described above, the -filter switch applies filters to an entire track. To
173 localise filters to a specific clip on a track, you have to know information
174 about the lengths of the clip and all clips leading up to it. In practise,
175 this is horrifically impractical, especially at a command line level (and not
176 even that practical from a programing point of view...).
178 The -attach family of switches simplify things enormously. By default, -attach
179 will attach a filter to the last service created, so:
181 $ inigo clip1.dv clip2.dv -attach greyscale clip3.dv
183 would only apply the filter to clip2.dv. You can further narrow down the area of
184 the effect by specifying in/out points on the attached filter.
186 This might seem simple so far, but there is a catch... consider the following:
188 $ ingo clip1.dv -attach watermark:+hello.txt -attach invert
190 The second attached filter is actually attached to the watermark. You might
191 think, yay, nice (and it is :-)), but, it might not be what you want. For example
192 you might want to attach both to clip1.dv. To do that, you can use:
194 $ ingo clip1.dv -attach-cut watermark:+hello.txt -attach-cut invert
196 As you shall see below, there are still another couple of gotchas associated to
197 -attach, and even another variant :-).
202 The -mix switch provides the simplest means to introduce transitions between
207 $ inigo clip1.dv clip2.dv -mix 25 -mixer luma -mixer mix:-1
209 would provide both an audio and video transition between clip1 and clip2.
211 This functionality supercedes the enforced use of the -track and -transition
212 switches from earlier versions of inigo and makes life a lot easier :-).
214 These can be used in combination, so you can for example do a fade from black
215 and to black using the following:
217 $ inigo colour:black out=24 clip1.dv -mix 25 -mixer luma \
218 colour:black out=24 -mix 25 -mixer luma
220 while this may not be immediately obvious, consider what's happening as the
221 command line is being parsed from left to right:
224 ----------------------- -----------------------------------------------------
225 colour:black out=24 [black]
226 clip1.dv [black][clip1.dv]
227 -mix 25 [black+clip1.dv][clip1.dv]
228 -mixer luma [luma:black+clip1.dv][clip1.dv]
229 colour:black out=24 [luma:black+clip1.dv][clip1.dv][black]
230 -mix 25 [luma:black+clip1.dv][clip1.dv][clip1.dv+black]
231 -mixer luma [luma:black+clip1.dv][clip1.dv][luma:clip1.dv+black]
233 Obviously, the clip1.dv instances refer to different parts of the clip, but
234 hopefully that will demonstrate what happens as we construct the track.
236 You will find more details on the mix in the framework.txt.
241 As noted, -attach normally applies to the last created service - so, you can
242 attach a filter to the transition region using:
244 $ inigo clip1.dv clip2.dv -mix 25 -mixer luma -attach watermark:+Transition.txt
246 Again, nice, but take care - if you want the attached filter to be associated
247 to the region following the transition, use -attach-cut instead.
250 Splits, Joins, Removes and Swaps:
252 COMPLEX - needs simplification....
255 Introducing Tracks and Blanks:
257 So far, all of the examples have shown the definition of a single
258 playlist, or more accurately, track.
260 When multiple tracks exist, the consumer will receive a frame
261 from the 'highest numbered' track that is generating a non-blank
264 It is best to visualise a track arrangement, so we'll start with
267 $ inigo a.dv -track b.dv in=0 out=49
269 This can be visualised as follows:
277 Playout will show the first 50 frames of b and the 51st frame shown will be
280 This rule also applies to audio only producers on the second track, for
281 example, the following would show the video from the a track, but the audio
282 would come from the second track:
284 $ inigo a.dv -track b.mp3 in=0 out=49
286 To have the 51st frame be the first frame of b, we can use the -blank switch:
288 $ inigo a.dv out=49 -track -blank 49 b.dv
290 Which we can visualise as:
294 +-------+-------------------+
296 +-------------------+
298 Now playout will continue as though a and b clips are on the
299 same track (which on its own, is about as useful as reversing the
300 process of slicing bread).
305 Where tracks become useful is in the placing of transitions.
307 Here we need tracks to overlap, so a useful multitrack
308 definition could be given as:
310 $ inigo a.dv out=49 \
313 -transition luma in=25 out=49 a_track=0 b_track=1
315 Now we're cooking - our visualisation would be something like:
319 +---+---+--------------+
323 Playout will now show the first 25 frames of a and then a fade
324 transition for 25 frames between a and b, and will finally
325 playout the remainder of b.
328 Reversing a Transition:
330 When we visualise a track definition, we also see situations
333 +-------+ +----------+
335 +---+---+--------------+----+-----+
337 +-----------------------+
339 In this case, we have two transitions, a1 to b and b to a2.
341 In this scenario, we define a command line as follows:
343 $ inigo a.dv out=49 -blank 49 a2.dv \
345 -blank 24 b.dv out=99 \
346 -transition luma in=25 out=49 a_track=0 b_track=1 \
347 -transition luma in=100 out=124 reverse=1 a_track=0 b_track=1
352 Inigo has a built in serialisation mechanism - you can build up
353 your command, test it via any consumer and then add a -serialise
354 file.inigo switch to save it.
356 The saved file can be subsequently used as a clip by either
357 miracle or inigo. Take care though - paths to files are saved as
358 provided on the command line....
360 A more expressive serialisation can be obtained with the westley consumer
361 - this will provide an xml document which can be used freely in inigo and
364 See westley.txt for more information.
369 Some filters/transitions should be applied on the output frame regardless
370 of which track it comes from - for example, you might have a 3rd text
371 track or a watermark which you want composited on every frame, and of
372 course, there's the obscure filter....
374 inigo only supports this in two invocations - as a simple example:
376 $ inigo a.dv -track -blank 100 b.dv -consumer westley:basic.westley
377 $ inigo basic.westley -filter watermark:watermark.png