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 id[:arg] [ name=value ] * ]
26 [ -transition id[:arg] [ name=value ] * ]
28 [ -track | -hide-track | -hide-video | -hide-audio ]
29 [ producer [ name=value ] * ]+
30 [ -serialise file.inigo ]
35 1. Order is incredibly important;
37 2. Error checking on command line parsing is weak;
39 3. Please refer to services.txt for details on services available;
41 4. The MLT framework, from which inigo has inherited its naming convention,
42 is very mlt-centric. Producers produce MLT frame objects and consumers
43 consume MLT frame objects. The distinction is important - a DV producer
44 does not produce DV, it produces MLT frames from a DV source, and similarly
45 a DV consumer does not consume DV, it consumes MLT frames and produces DV
51 'Producers' typically refer to files but may also indicate devices (such as
52 dv1394 input or video4linux). Hence, the more generic term is used [the more
53 generic usage is out of scope for now...].
55 'Filters' are frame modifiers - they always guarantee that for every frame
56 they receive, they output *precisely* one frame. Never more, never less,
57 ever. Nothing says that a filter cannot generate frames though
59 'Transitions' collect frames from two tracks (a and b) and output 1
60 modified frame on their 'a track', and 1 unmodified frame on their 'b track'.
61 Never more, never less, ever.
63 'Consumers' collect frames from a producer, do something with them and
66 Collectively, these are known as 'services'.
68 All services have 'properties' associated to them. These are typically
69 defaulted or evaluated and may be overriden on a case by case basis.
71 All services except consumers obey in and out properties.
73 Consumers have no say in the flow of frames [though they may give the
74 illusion that they do]. They get frames from a connected producer, use them,
75 destroy them and get more.
80 To play a file with the default SDL PAL consumer, usage is:
84 Note that 'file' can be anything that inigo has a known 'producer' mapping
85 for (so this can be anything from .dv to .txt).
87 You can also specify the producer directly, for example:
89 $ inigo avformat:file.mpeg
91 Would force the direct use of avformat for loading the file.
96 Properties can be assigned to the producer by adding additional name=value
97 pairs after the producer:
99 $ inigo file in=50 out=100 something="something else"
101 Note that while some properties have meaning to all producers (for example:
102 in, out and length are guaranteed to be valid for all, though typically,
103 length is determined automatically), the validity of others are dependent on
104 the producer - however, properties will always be assigned and silently
105 ignored if they won't be used.
110 Multiple files of different types can be used:
112 $ inigo a.dv b.mpg c.png
114 Properties can be assigned to each file:
116 $ inigo a.dv in=50 out=100 b.mpg out=500 c.png out=500
118 MLT will take care of 'normalising' the output of a producer to ensure
119 that the consumer gets what it needs. So, in the case above, the mlt
120 framework will ensure that images are rescaled and audio resampled to meet
121 the requirements of your configuration (which, by default, will be PAL).
122 See 'Appendix A: Normalisation Rules' below.
127 Filters are frame modifiers - they can change the contents of the audio or
128 the images associated to a frame.
130 $ inigo a.dv -filter greyscale
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 filter to a
135 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 will
140 silently ignore properties that do not apply.
145 The -group switch is provided to force default properties on the following
146 '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 card
153 Note that the last -group settings also apply to the following filters,
154 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 only be
159 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 single
169 playlist, or more accurately, track.
171 When multiple tracks exist, the consumer will receive a frame
172 from the 'highest 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 -track b.dv in=0 out=49
180 This can be visualised as follows:
188 Playout will show the first 50 frames of b and the 51st frame shown will be
191 This rule also applies to audio only producers on the second track, for
192 example, the following would show the video from the a track, but the audio
193 would come from the second track:
195 $ inigo a.dv -track b.mp3 in=0 out=49
197 To have the 51st frame be the first frame of b, we can use the -blank switch:
199 $ inigo a.dv out=49 -track -blank 49 b.dv
201 Which we can visualise as:
205 +-------+-------------------+
207 +-------------------+
209 Now playout will continue as though a and b clips are on the
210 same track (which on its own, is about as useful as reversing the
211 process of slicing bread).
216 Where tracks become useful is in the placing of transitions.
218 Here we need tracks to overlap, so a useful multitrack
219 definition could be given as:
221 $ inigo a.dv out=49 \
224 -transition luma in=25 out=49 a_track=0 b_track=1
226 Now we're cooking - our visualisation would be something like:
230 +---+---+--------------+
234 Playout will now show the first 25 frames of a and then a fade
235 transition for 25 frames between a and b, and will finally
236 playout the remainder of b.
239 Reversing a Transition:
241 When we visualise a track definition, we also see situtations
244 +-------+ +----------+
246 +---+---+--------------+----+-----+
248 +-----------------------+
250 In this case, we have two transitions, a1 to b and b to a2.
252 In this scenario, we define a command line as follows:
254 $ inigo a.dv out=49 -blank 49 a2.dv \
256 -blank 24 b.dv out=99 \
257 -transition luma in=25 out=49 a_track=0 b_track=1 \
258 -transition luma in=100 out=124 reverse=1 a_track=0 b_track=1
263 Inigo has a built in serialisation mechanism - you can build up
264 your command, test it via any consumer and then add a -serialise
265 file.inigo switch to save it.
267 The saved file can be subsequently used as a clip by either
268 miracle or inigo. Take care though - paths to files are saved as
269 provided on the command line....
271 A more expressive serialisation can be obtained with the westley consumer
272 - this will provide an xml document which can be used freely in inigo and
275 See westley.txt for more information.
280 Some filters/transitions should be applied on the output frame regardless
281 of which track it comes from - for example, you might have a 3rd text
282 track or a watermark which you want composited on every frame, and of
283 course, there's the obscure filter....
285 inigo only supports this in two invocations - as a simple example:
287 $ inigo a.dv -track -blank 100 b.dv -consumer westley:basic.westley
288 $ inigo basic.westley -filter watermark:watermark.png