3 Copyright (C) 2004-2009 Ushodaya Enterprised Limited
4 Author: Charles Yates <charles.yates@pandora.be>
5 Author: Dan Dennedy <dan@dennedy.org>
6 Last Revision: 2011-04-03
14 Melt was developed as a test tool for the MLT framework. It can be thought
15 of as a powerful, if somewhat obscure, multitrack command line oriented
18 The following details the usage of the tool and as a result, provides a lot
19 of insight into the workings of the MLT framework.
24 melt [options] [producer [name=value]* ]+
26 -attach filter[:arg] [name=value]* Attach a filter to the output
27 -attach-cut filter[:arg] [name=value]* Attach a filter to a cut
28 -attach-track filter[:arg] [name=value]* Attach a filter to a track
29 -attach-clip filter[:arg] [name=value]* Attach a filter to a producer
30 -audio-track | -hide-video Add an audio-only track
31 -blank frames Add blank silence to a track
32 -consumer id[:arg] [name=value]* Set the consumer (sink)
33 -debug Set the logging level to debug
34 -filter filter[:arg] [name=value]* Add a filter to the current track
35 -group [name=value]* Apply properties repeatedly
36 -help Show this message
37 -jack Enable JACK transport synchronization
38 -join clips Join multiple clips into one cut
39 -mix length Add a mix between the last two cuts
40 -mixer transition Add a transition to the mix
41 -null-track | -hide-track Add a hidden track
42 -profile name Set the processing settings
43 -progress Display progress along with the position
44 -remove Remove the most recent cut
45 -repeat times Repeat the last cut
46 -query List all of the registered services
47 -query "consumers" | "consumer"=id List consumers or show info about one
48 -query "filters" | "filter"=id List filters or show info about one
49 -query "producers" | "producer"=id List producers or show info about one
50 -query "transitions" | "transition"=id List transitions or show info about one
51 -query "profiles" | "profile"=id List profiles or show info about one
52 -query "presets" | "preset"=id List presets or show info about one
53 -query "formats" List audio/video formats
54 -query "audio_codecs" List audio codecs
55 -query "video_codecs" List video codecs
56 -serialise [filename] Write the commands to a text file
57 -silent Do not display position/transport help
58 -split relative-frame Split the last cut into two cuts
59 -swap Rearrange the last two cuts
61 -transition id[:arg] [name=value]* Add a transition
62 -verbose Set the logging level to verbose
63 -version Show the version and copyright message
64 -video-track | -hide-audio Add a video-only track
69 1. Order is incredibly important;
71 2. Error checking on command line parsing is weak;
73 3. Please refer to services.txt for details on services available;
75 4. The MLT framework, from which melt has inherited its naming convention,
76 is very mlt-centric. Producers produce MLT frame objects and consumers
77 consume MLT frame objects. The distinction is important - a DV producer
78 does not produce DV, it produces MLT frames from a DV source, and similarly
79 a DV consumer does not consume DV, it consumes MLT frames and produces DV
85 'Producers' typically refer to files but may also indicate devices (such as
86 dv1394 input or video4linux). Hence, the more generic term is used [the more
87 generic usage is out of scope for now...].
89 'Filters' are frame modifiers - they always guarantee that for every frame
90 they receive, they output *precisely* one frame. Never more, never less,
91 ever. Nothing says that a filter cannot generate frames though
93 'Transitions' collect frames from two tracks (a and b) and output 1
94 modified frame on their 'a track', and 1 unmodified frame on their 'b track'.
95 Never more, never less, ever.
97 'Consumers' collect frames from a producer, do something with them and
100 Collectively, these are known as 'services'.
102 All services have 'properties' associated to them. These are typically
103 defaulted or evaluated and may be overriden on a case by case basis.
105 All services except consumers obey in and out properties.
107 Consumers have no say in the flow of frames [though they may give the
108 illusion that they do]. They get frames from a connected producer, use them,
109 destroy them and get more.
114 To play a file with the default SDL PAL consumer, usage is:
118 Note that 'file' can be anything that melt has a known 'producer' mapping
119 for (so this can be anything from .dv to .txt).
121 You can also specify the producer directly, for example:
123 $ melt avformat:file.mpeg
125 Would force the direct use of avformat for loading the file.
130 Properties can be assigned to the producer by adding additional name=value
131 pairs after the producer:
133 $ melt file in=50 out=100 something="something else"
135 Note that while some properties have meaning to all producers (for example:
136 in, out and length are guaranteed to be valid for all, though typically,
137 length is determined automatically), the validity of others are dependent on
138 the producer - however, properties will always be assigned and silently
139 ignored if they won't be used.
144 Multiple files of different types can be used:
146 $ melt a.dv b.mpg c.png
148 Properties can be assigned to each file:
150 $ melt a.dv in=50 out=100 b.mpg out=500 c.png out=500
152 MLT will take care of 'normalising' the output of a producer to ensure
153 that the consumer gets what it needs. So, in the case above, the mlt
154 framework will ensure that images are rescaled and audio resampled to meet
155 the requirements of your configuration (which, by default, will be PAL).
156 See 'Appendix A: Normalisation Rules' below.
161 Filters are frame modifiers - they can change the contents of the audio or
162 the images associated to a frame.
164 $ melt a.dv -filter greyscale
166 As with producers, properties may be specified on filters too.
168 Again, in and out properties are common to all, so to apply a filter to a
169 range of frames, you would use something like:
171 $ melt a.dv -filter greyscale in=0 out=50
173 Again, filters have their own set of rules about properties and will
174 silently ignore properties that do not apply.
179 The -group switch is provided to force default properties on the following
180 'services'. For example:
182 $ melt -group in=0 out=49 clip*
184 would play the first 50 frames of all clips that match the wild card
187 Note that the last -group settings also apply to the following filters,
188 transitions and consumers, so:
190 $ melt -group in=0 out=49 clip* -filter greyscale
192 is *probably not* what you want (ie: the greyscale filter would only be
193 applied to the first 50 frames).
195 To shed the group properties, you can use any empty group:
197 $ melt -group in=0 out=49 clip* -group -filter greyscale
202 As described above, the -filter switch applies filters to an entire track. To
203 localise filters to a specific clip on a track, you have to know information
204 about the lengths of the clip and all clips leading up to it. In practise,
205 this is horrifically impractical, especially at a command line level (and not
206 even that practical from a programing point of view...).
208 The -attach family of switches simplify things enormously. By default, -attach
209 will attach a filter to the last service created, so:
211 $ melt clip1.dv clip2.dv -attach greyscale clip3.dv
213 would only apply the filter to clip2.dv. You can further narrow down the area of
214 the effect by specifying in/out points on the attached filter.
216 This might seem simple so far, but there is a catch... consider the following:
218 $ melt clip1.dv -attach watermark:+hello.txt -attach invert
220 The second attached filter is actually attached to the watermark. You might
221 think, yay, nice (and it is :-)), but, it might not be what you want. For example
222 you might want to attach both to clip1.dv. To do that, you can use:
224 $ melt clip1.dv -attach-cut watermark:+hello.txt -attach-cut invert
226 As you shall see below, there are still another couple of gotchas associated to
227 -attach, and even another variant :-).
232 The -mix switch provides the simplest means to introduce transitions between
237 $ melt clip1.dv clip2.dv -mix 25 -mixer luma -mixer mix:-1
239 would provide both an audio and video transition between clip1 and clip2.
241 This functionality supercedes the enforced use of the -track and -transition
242 switches from earlier versions of melt and makes life a lot easier :-).
244 These can be used in combination, so you can for example do a fade from black
245 and to black using the following:
247 $ melt colour:black out=24 clip1.dv -mix 25 -mixer luma \
248 colour:black out=24 -mix 25 -mixer luma
250 while this may not be immediately obvious, consider what's happening as the
251 command line is being parsed from left to right:
254 ----------------------- -----------------------------------------------------
255 colour:black out=24 [black]
256 clip1.dv [black][clip1.dv]
257 -mix 25 [black+clip1.dv][clip1.dv]
258 -mixer luma [luma:black+clip1.dv][clip1.dv]
259 colour:black out=24 [luma:black+clip1.dv][clip1.dv][black]
260 -mix 25 [luma:black+clip1.dv][clip1.dv][clip1.dv+black]
261 -mixer luma [luma:black+clip1.dv][clip1.dv][luma:clip1.dv+black]
263 Obviously, the clip1.dv instances refer to different parts of the clip, but
264 hopefully that will demonstrate what happens as we construct the track.
266 You will find more details on the mix in the framework.txt.
271 As noted, -attach normally applies to the last created service - so, you can
272 attach a filter to the transition region using:
274 $ melt clip1.dv clip2.dv -mix 25 -mixer luma -attach watermark:+Transition.txt
276 Again, nice, but take care - if you want the attached filter to be associated
277 to the region following the transition, use -attach-cut instead.
280 Splits, Joins, Removes and Swaps:
282 COMPLEX - needs simplification....
285 Introducing Tracks and Blanks:
287 So far, all of the examples have shown the definition of a single
288 playlist, or more accurately, track.
290 When multiple tracks exist, the consumer will receive a frame
291 from the 'highest numbered' track that is generating a non-blank
294 It is best to visualise a track arrangement, so we'll start with
297 $ melt a.dv -track b.dv in=0 out=49
299 This can be visualised as follows:
307 Playout will show the first 50 frames of b and the 51st frame shown will be
310 This rule also applies to audio only producers on the second track, for
311 example, the following would show the video from the a track, but the audio
312 would come from the second track:
314 $ melt a.dv -track b.mp3 in=0 out=49
316 To have the 51st frame be the first frame of b, we can use the -blank switch:
318 $ melt a.dv out=49 -track -blank 49 b.dv
320 Which we can visualise as:
324 +-------+-------------------+
326 +-------------------+
328 Now playout will continue as though a and b clips are on the
329 same track (which on its own, is about as useful as reversing the
330 process of slicing bread).
335 Where tracks become useful is in the placing of transitions.
337 Here we need tracks to overlap, so a useful multitrack
338 definition could be given as:
343 -transition luma in=25 out=49 a_track=0 b_track=1
345 Now we're cooking - our visualisation would be something like:
349 +---+---+--------------+
353 Playout will now show the first 25 frames of a and then a fade
354 transition for 25 frames between a and b, and will finally
355 playout the remainder of b.
358 Reversing a Transition:
360 When we visualise a track definition, we also see situations
363 +-------+ +----------+
365 +---+---+--------------+----+-----+
367 +-----------------------+
369 In this case, we have two transitions, a1 to b and b to a2.
371 In this scenario, we define a command line as follows:
373 $ melt a.dv out=49 -blank 49 a2.dv \
375 -blank 24 b.dv out=99 \
376 -transition luma in=25 out=49 a_track=0 b_track=1 \
377 -transition luma in=100 out=124 reverse=1 a_track=0 b_track=1
382 Melt has a built in serialisation mechanism - you can build up
383 your command, test it via any consumer and then add a -serialise
384 file.melt switch to save it.
386 The saved file can be subsequently used as a clip by melt or other
387 MLT applications. Take care though - paths to files are saved as
388 provided on the command line....
390 A more expressive serialisation can be obtained with the xml consumer
391 - this will provide an xml document which can be used freely in melt and
392 other MLT applications.
394 See mlt-xml.txt for more information.
399 Some filters/transitions should be applied on the output frame regardless
400 of which track it comes from - for example, you might have a 3rd text
401 track or a watermark which you want composited on every frame, and of
402 course, there's the obscure filter....
404 melt only supports this in two invocations - as a simple example:
406 $ melt a.dv -track -blank 100 b.dv -consumer xml:basic.mlt
407 $ melt basic.mlt -filter watermark:watermark.png