]> git.sesse.net Git - mlt/blob - docs/inigo.txt
Merge mlt++/README into docs/mlt++.txt.
[mlt] / docs / inigo.txt
1 Inigo Documentation
2
3 Copyright (C) 2004-2009 Ushodaya Enterprised Limited
4 Author: Charles Yates <charles.yates@pandora.be>
5 Last Revision: 2009-01-21
6
7
8 INIGO
9 -----
10
11 Preamble:
12
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 
15         video editor.
16
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.
19
20
21 Usage:
22
23     inigo [options] [producer [name=value]* ]+
24     Options:
25       -attach filter[:arg] [name=value]*       Attach a filter to the output
26       -attach-cut filter[:arg] [name=value]*   Attach a filter to a cut
27       -attach-track filter[:arg] [name=value]* Attach a filter to a track
28       -attach-clip filter[:arg] [name=value]*  Attach a filter to a producer
29       -audio-track | -hide-video               Add an audio-only track
30       -blank frames                            Add blank silence to a track
31       -consumer id[:arg] [name=value]*         Set the consumer (sink)
32       -debug                                   Set the logging level to debug
33       -filter filter[:arg] [name=value]*       Add a filter to the current track
34       -group [name=value]*                     Apply properties repeatedly
35       -help                                    Show this message
36       -join clips                              Join multiple clips into one cut
37       -mix length                              Add a mix between the last two cuts
38       -mixer transition                        Add a transition to the mix
39       -null-track | -hide-track                Add a hidden track
40       -profile name                            Set the processing settings
41       -progress                                Display progress along with the position
42       -remove                                  Remove the most recent cut
43       -repeat times                            Repeat the last cut
44       -query                                   List all of the registered services
45       -query "consumers" | "consumer"=id       List consumers or show info about one
46       -query "filters" | "filter"=id           List filters or show info about one
47       -query "producers" | "producer"=id       List producers or show info about one
48       -query "transitions" | "transition"=id   List transitions or show info about one
49       -serialise [filename]                    Write the commands to a text file
50       -silent                                  Do not display position/transport help
51       -split relative-frame                    Split the last cut into two cuts
52       -swap                                    Rearrange the last two cuts
53       -track                                   Add a track
54       -transition id[:arg] [name=value]*       Add a transition
55       -verbose                                 Set the logging level to verbose
56       -version                                 Show the version and copyright message
57       -video-track | -hide-audio               Add a video-only track
58
59
60 General rules:
61
62         1. Order is incredibly important;
63
64         2. Error checking on command line parsing is weak;
65
66         3. Please refer to services.txt for details on services available;
67
68         4. The MLT framework, from which inigo has inherited its naming convention,
69         is very mlt-centric. Producers produce MLT frame objects and consumers 
70         consume MLT frame objects.  The distinction is important - a DV producer 
71         does not produce DV, it produces MLT frames from a DV source, and similarly
72         a DV consumer does not consume DV, it consumes MLT frames and produces DV
73         frames.
74
75
76 Terminology:
77
78         'Producers' typically refer to files but may also indicate devices (such as
79         dv1394 input or video4linux). Hence, the more generic term is used [the more 
80         generic usage is out of scope for now...].
81
82         'Filters' are frame modifiers - they always guarantee that for every frame 
83         they receive, they output *precisely* one frame.  Never more, never less, 
84         ever. Nothing says that a filter cannot generate frames though
85         
86         'Transitions' collect frames from two tracks (a and b) and output 1 
87         modified frame on their 'a track', and 1 unmodified frame on their 'b track'.
88         Never more, never less, ever.
89         
90         'Consumers' collect frames from a producer, do something with them and
91         destroy them.
92         
93         Collectively, these are known as 'services'. 
94         
95         All services have 'properties' associated to them. These are typically
96         defaulted or evaluated and may be overriden on a case by case basis.
97         
98         All services except consumers obey in and out properties.
99         
100         Consumers have no say in the flow of frames [though they may give the
101         illusion that they do]. They get frames from a connected producer, use them, 
102         destroy them and get more.
103
104
105 Basics:
106
107         To play a file with the default SDL PAL consumer, usage is:
108         
109         $ inigo file
110
111         Note that 'file' can be anything that inigo has a known 'producer' mapping 
112         for (so this can be anything from .dv to .txt).
113
114         You can also specify the producer directly, for example:
115
116         $ inigo avformat:file.mpeg
117
118         Would force the direct use of avformat for loading the file.
119
120
121 Properties:
122
123         Properties can be assigned to the producer by adding additional name=value
124         pairs after the producer:
125         
126         $ inigo file in=50 out=100 something="something else"
127         
128         Note that while some properties have meaning to all producers (for example:
129         in, out and length are guaranteed to be valid for all, though typically, 
130         length is determined automatically), the validity of others are dependent on 
131         the producer - however, properties will always be assigned and silently 
132         ignored if they won't be used.
133
134
135 Multiple Files:
136
137         Multiple files of different types can be used:
138         
139         $ inigo a.dv b.mpg c.png
140         
141         Properties can be assigned to each file:
142         
143         $ inigo a.dv in=50 out=100 b.mpg out=500 c.png out=500
144
145         MLT will take care of 'normalising' the output of a producer to ensure
146         that the consumer gets what it needs. So, in the case above, the mlt
147         framework will ensure that images are rescaled and audio resampled to meet
148         the requirements of your configuration (which, by default, will be PAL).
149         See 'Appendix A: Normalisation Rules' below.
150
151
152 Filters:
153
154         Filters are frame modifiers - they can change the contents of the audio or
155         the images associated to a frame.
156
157         $ inigo a.dv -filter greyscale
158
159         As with producers, properties may be specified on filters too.
160         
161         Again, in and out properties are common to all, so to apply a filter to a
162         range of frames, you would use something like:
163         
164         $ inigo a.dv -filter greyscale in=0 out=50
165         
166         Again, filters have their own set of rules about properties and will
167         silently ignore properties that do not apply.
168
169
170 Groups:
171
172         The -group switch is provided to force default properties on the following
173         'services'. For example:
174         
175         $ inigo -group in=0 out=49 clip*
176         
177         would play the first 50 frames of all clips that match the wild card
178         pattern.
179         
180         Note that the last -group settings also apply to the following filters, 
181         transitions and consumers, so:
182         
183         $ inigo -group in=0 out=49 clip* -filter greyscale
184         
185         is *probably not* what you want (ie: the greyscale filter would only be 
186         applied to the first 50 frames).
187         
188         To shed the group properties, you can use any empty group:
189         
190         $ inigo -group in=0 out=49 clip* -group -filter greyscale
191
192
193 Attached Filters:
194
195         As described above, the -filter switch applies filters to an entire track. To
196         localise filters to a specific clip on a track, you have to know information
197         about the lengths of the clip and all clips leading up to it. In practise, 
198         this is horrifically impractical, especially at a command line level (and not
199         even that practical from a programing point of view...).
200
201         The -attach family of switches simplify things enormously. By default, -attach
202         will attach a filter to the last service created, so:
203
204         $ inigo clip1.dv clip2.dv -attach greyscale clip3.dv
205
206         would only apply the filter to clip2.dv. You can further narrow down the area of
207         the effect by specifying in/out points on the attached filter.
208
209         This might seem simple so far, but there is a catch... consider the following:
210
211         $ ingo clip1.dv -attach watermark:+hello.txt -attach invert
212
213         The second attached filter is actually attached to the watermark. You might 
214         think, yay, nice (and it is :-)), but, it might not be what you want. For example
215         you might want to attach both to clip1.dv. To do that, you can use:
216
217         $ ingo clip1.dv -attach-cut watermark:+hello.txt -attach-cut invert
218
219         As you shall see below, there are still another couple of gotchas associated to 
220         -attach, and even another variant :-).
221
222
223 Mixes:
224
225         The -mix switch provides the simplest means to introduce transitions between
226         adjacent clips.
227
228         For example:
229
230         $ inigo clip1.dv clip2.dv -mix 25 -mixer luma -mixer mix:-1
231
232         would provide both an audio and video transition between clip1 and clip2.
233
234         This functionality supercedes the enforced use of the -track and -transition
235         switches from earlier versions of inigo and makes life a lot easier :-).
236
237         These can be used in combination, so you can for example do a fade from black
238         and to black using the following:
239
240         $ inigo colour:black out=24 clip1.dv -mix 25 -mixer luma \
241                 colour:black out=24 -mix 25 -mixer luma 
242         
243         while this may not be immediately obvious, consider what's happening as the 
244         command line is being parsed from left to right:
245
246         Input:                  Track
247         ----------------------- -----------------------------------------------------
248         colour:black out=24     [black]
249         clip1.dv                [black][clip1.dv]
250         -mix 25                 [black+clip1.dv][clip1.dv]
251         -mixer luma             [luma:black+clip1.dv][clip1.dv]
252         colour:black out=24     [luma:black+clip1.dv][clip1.dv][black]
253         -mix 25                 [luma:black+clip1.dv][clip1.dv][clip1.dv+black]
254         -mixer luma             [luma:black+clip1.dv][clip1.dv][luma:clip1.dv+black]
255
256         Obviously, the clip1.dv instances refer to different parts of the clip, but 
257         hopefully that will demonstrate what happens as we construct the track.
258
259         You will find more details on the mix in the framework.txt.
260
261
262 Mix and Attach:
263
264         As noted, -attach normally applies to the last created service - so, you can 
265         attach a filter to the transition region using:
266
267         $ inigo clip1.dv clip2.dv -mix 25 -mixer luma -attach watermark:+Transition.txt
268
269         Again, nice, but take care - if you want the attached filter to be associated
270         to the region following the transition, use -attach-cut instead.
271
272
273 Splits, Joins, Removes and Swaps:
274
275         COMPLEX - needs simplification....
276
277
278 Introducing Tracks and Blanks:
279
280         So far, all of the examples have shown the definition of a single
281         playlist, or more accurately, track.
282
283         When multiple tracks exist, the consumer will receive a frame
284         from the 'highest numbered' track that is generating a non-blank
285         frame.
286         
287         It is best to visualise a track arrangement, so we'll start with
288         an example:
289         
290         $ inigo a.dv -track b.dv in=0 out=49
291         
292         This can be visualised as follows:
293         
294         +------------------+
295         |a                 |
296         +-------+----------+
297         |b      |
298         +-------+
299
300         Playout will show the first 50 frames of b and the 51st frame shown will be
301         the 51st frame of a.
302
303         This rule also applies to audio only producers on the second track, for
304         example, the following would show the video from the a track, but the audio
305         would come from the second track:
306
307         $ inigo a.dv -track b.mp3 in=0 out=49
308
309         To have the 51st frame be the first frame of b, we can use the -blank switch:
310         
311         $ inigo a.dv out=49 -track -blank 49 b.dv
312         
313         Which we can visualise as:
314         
315         +-------+
316         |a      |
317         +-------+-------------------+
318                 |b                  |
319                 +-------------------+
320         
321         Now playout will continue as though a and b clips are on the
322         same track (which on its own, is about as useful as reversing the 
323         process of slicing bread).
324
325
326 Transitions:
327
328         Where tracks become useful is in the placing of transitions.
329         
330         Here we need tracks to overlap, so a useful multitrack
331         definition could be given as:
332         
333         $ inigo a.dv out=49 \
334                 -track \
335                 -blank 24 b.dv \
336                 -transition luma in=25 out=49 a_track=0 b_track=1
337         
338         Now we're cooking - our visualisation would be something like:
339         
340         +-------+
341         |a      |
342         +---+---+--------------+
343             |b                 |
344             +------------------+
345         
346         Playout will now show the first 25 frames of a and then a fade
347         transition for 25 frames between a and b, and will finally
348         playout the remainder of b.
349
350
351 Reversing a Transition:
352
353         When we visualise a track definition, we also see situations
354         like:
355         
356         +-------+              +----------+
357         |a1     |              |a2        |
358         +---+---+--------------+----+-----+
359             |b                      |
360             +-----------------------+
361         
362         In this case, we have two transitions, a1 to b and b to a2. 
363         
364         In this scenario, we define a command line as follows:
365         
366         $ inigo a.dv out=49 -blank 49 a2.dv \
367                 -track \
368                 -blank 24 b.dv out=99 \
369                 -transition luma in=25 out=49 a_track=0 b_track=1 \
370                 -transition luma in=100 out=124 reverse=1 a_track=0 b_track=1
371
372
373 Serialisation:
374
375         Inigo has a built in serialisation mechanism - you can build up
376         your command, test it via any consumer and then add a -serialise
377         file.inigo switch to save it.
378         
379         The saved file can be subsequently used as a clip by either
380         miracle or inigo. Take care though - paths to files are saved as
381         provided on the command line....
382
383         A more expressive serialisation can be obtained with the westley consumer
384         - this will provide an xml document which can be used freely in inigo and
385         miracle.
386
387         See westley.txt for more information.
388
389
390 Missing Features:
391
392         Some filters/transitions should be applied on the output frame regardless
393         of which track it comes from - for example, you might have a 3rd text 
394         track or a watermark which you want composited on every frame, and of 
395         course, there's the obscure filter.... 
396         
397         inigo only supports this in two invocations - as a simple example:
398
399         $ inigo a.dv -track -blank 100 b.dv -consumer westley:basic.westley
400         $ inigo basic.westley -filter watermark:watermark.png
401