Fix doc error for mlt_playlist_is_blank().

[mlt] / docs / melt.txt

diff --git a/docs/melt.txt b/docs/melt.txt
index 854c1c12d086422134297247b1b15f4543565ff8..5add3545b1c1e12cfdad6f89beb4e9590676ef36 100644 (file)
--- a/docs/melt.txt
+++ b/docs/melt.txt
@@ -1,16 +1,17 @@
-Inigo Documentation
+Melt Documentation

 
 Copyright (C) 2004-2009 Ushodaya Enterprised Limited
 Author: Charles Yates <charles.yates@pandora.be>
 
 Copyright (C) 2004-2009 Ushodaya Enterprised Limited
 Author: Charles Yates <charles.yates@pandora.be>

-Last Revision: 2009-01-21
+Author: Dan Dennedy <dan@dennedy.org>
+Last Revision: 2011-04-03

 
 
 
 

-INIGO
+MELT

 -----
 
 Preamble:
 
 -----
 
 Preamble:
 

-       inigo was developed as a test tool for the MLT framework. It can be thought
+       Melt was developed as a test tool for the MLT framework. It can be thought

        of as a powerful, if somewhat obscure, multitrack command line oriented 
        video editor.
 
        of as a powerful, if somewhat obscure, multitrack command line oriented 
        video editor.
 


@@ -20,7 +21,7 @@ Preamble:
 
 Usage:
 
 
 Usage:
 

-    inigo [options] [producer [name=value]* ]+
+    melt [options] [producer [name=value]* ]+

     Options:
       -attach filter[:arg] [name=value]*       Attach a filter to the output
       -attach-cut filter[:arg] [name=value]*   Attach a filter to a cut
     Options:
       -attach filter[:arg] [name=value]*       Attach a filter to the output
       -attach-cut filter[:arg] [name=value]*   Attach a filter to a cut


@@ -33,6 +34,7 @@ Usage:
       -filter filter[:arg] [name=value]*       Add a filter to the current track
       -group [name=value]*                     Apply properties repeatedly
       -help                                    Show this message
       -filter filter[:arg] [name=value]*       Add a filter to the current track
       -group [name=value]*                     Apply properties repeatedly
       -help                                    Show this message

+      -jack                                    Enable JACK transport synchronization

       -join clips                              Join multiple clips into one cut
       -mix length                              Add a mix between the last two cuts
       -mixer transition                        Add a transition to the mix
       -join clips                              Join multiple clips into one cut
       -mix length                              Add a mix between the last two cuts
       -mixer transition                        Add a transition to the mix


@@ -46,6 +48,11 @@ Usage:
       -query "filters" | "filter"=id           List filters or show info about one
       -query "producers" | "producer"=id       List producers or show info about one
       -query "transitions" | "transition"=id   List transitions or show info about one
       -query "filters" | "filter"=id           List filters or show info about one
       -query "producers" | "producer"=id       List producers or show info about one
       -query "transitions" | "transition"=id   List transitions or show info about one

+      -query "profiles" | "profile"=id         List profiles or show info about one
+      -query "presets" | "preset"=id           List presets or show info about one
+      -query "formats"                         List audio/video formats
+      -query "audio_codecs"                    List audio codecs
+      -query "video_codecs"                    List video codecs

       -serialise [filename]                    Write the commands to a text file
       -silent                                  Do not display position/transport help
       -split relative-frame                    Split the last cut into two cuts
       -serialise [filename]                    Write the commands to a text file
       -silent                                  Do not display position/transport help
       -split relative-frame                    Split the last cut into two cuts


@@ -65,7 +72,7 @@ General rules:
 
        3. Please refer to services.txt for details on services available;
 
 
        3. Please refer to services.txt for details on services available;
 

-       4. The MLT framework, from which inigo has inherited its naming convention,
+       4. The MLT framework, from which melt has inherited its naming convention,

        is very mlt-centric. Producers produce MLT frame objects and consumers 
        consume MLT frame objects.  The distinction is important - a DV producer 
        does not produce DV, it produces MLT frames from a DV source, and similarly
        is very mlt-centric. Producers produce MLT frame objects and consumers 
        consume MLT frame objects.  The distinction is important - a DV producer 
        does not produce DV, it produces MLT frames from a DV source, and similarly


@@ -106,14 +113,14 @@ Basics:
 
        To play a file with the default SDL PAL consumer, usage is:
        
 
        To play a file with the default SDL PAL consumer, usage is:
        

-       $ inigo file
+       $ melt file

 
 

-       Note that 'file' can be anything that inigo has a known 'producer' mapping 
+       Note that 'file' can be anything that melt has a known 'producer' mapping 

        for (so this can be anything from .dv to .txt).
 
        You can also specify the producer directly, for example:
 
        for (so this can be anything from .dv to .txt).
 
        You can also specify the producer directly, for example:
 

-       $ inigo avformat:file.mpeg
+       $ melt avformat:file.mpeg

 
        Would force the direct use of avformat for loading the file.
 
 
        Would force the direct use of avformat for loading the file.
 


@@ -123,7 +130,7 @@ Properties:
        Properties can be assigned to the producer by adding additional name=value
        pairs after the producer:
        
        Properties can be assigned to the producer by adding additional name=value
        pairs after the producer:
        

-       $ inigo file in=50 out=100 something="something else"
+       $ melt file in=50 out=100 something="something else"

        
        Note that while some properties have meaning to all producers (for example:
        in, out and length are guaranteed to be valid for all, though typically, 
        
        Note that while some properties have meaning to all producers (for example:
        in, out and length are guaranteed to be valid for all, though typically, 


@@ -136,11 +143,11 @@ Multiple Files:
 
        Multiple files of different types can be used:
        
 
        Multiple files of different types can be used:
        

-       $ inigo a.dv b.mpg c.png
+       $ melt a.dv b.mpg c.png

        
        Properties can be assigned to each file:
        
        
        Properties can be assigned to each file:
        

-       $ inigo a.dv in=50 out=100 b.mpg out=500 c.png out=500
+       $ melt a.dv in=50 out=100 b.mpg out=500 c.png out=500

 
        MLT will take care of 'normalising' the output of a producer to ensure
        that the consumer gets what it needs. So, in the case above, the mlt
 
        MLT will take care of 'normalising' the output of a producer to ensure
        that the consumer gets what it needs. So, in the case above, the mlt


@@ -154,14 +161,14 @@ Filters:
        Filters are frame modifiers - they can change the contents of the audio or
        the images associated to a frame.
 
        Filters are frame modifiers - they can change the contents of the audio or
        the images associated to a frame.
 

-       $ inigo a.dv -filter greyscale
+       $ melt a.dv -filter greyscale

 
        As with producers, properties may be specified on filters too.
        
        Again, in and out properties are common to all, so to apply a filter to a
        range of frames, you would use something like:
        
 
        As with producers, properties may be specified on filters too.
        
        Again, in and out properties are common to all, so to apply a filter to a
        range of frames, you would use something like:
        

-       $ inigo a.dv -filter greyscale in=0 out=50
+       $ melt a.dv -filter greyscale in=0 out=50

        
        Again, filters have their own set of rules about properties and will
        silently ignore properties that do not apply.
        
        Again, filters have their own set of rules about properties and will
        silently ignore properties that do not apply.


@@ -172,7 +179,7 @@ Groups:
        The -group switch is provided to force default properties on the following
        'services'. For example:
        
        The -group switch is provided to force default properties on the following
        'services'. For example:
        

-       $ inigo -group in=0 out=49 clip*
+       $ melt -group in=0 out=49 clip*

        
        would play the first 50 frames of all clips that match the wild card
        pattern.
        
        would play the first 50 frames of all clips that match the wild card
        pattern.


@@ -180,14 +187,14 @@ Groups:
        Note that the last -group settings also apply to the following filters, 
        transitions and consumers, so:
        
        Note that the last -group settings also apply to the following filters, 
        transitions and consumers, so:
        

-       $ inigo -group in=0 out=49 clip* -filter greyscale
+       $ melt -group in=0 out=49 clip* -filter greyscale

        
        is *probably not* what you want (ie: the greyscale filter would only be 
        applied to the first 50 frames).
        
        To shed the group properties, you can use any empty group:
        
        
        is *probably not* what you want (ie: the greyscale filter would only be 
        applied to the first 50 frames).
        
        To shed the group properties, you can use any empty group:
        

-       $ inigo -group in=0 out=49 clip* -group -filter greyscale
+       $ melt -group in=0 out=49 clip* -group -filter greyscale

 
 
 Attached Filters:
 
 
 Attached Filters:


@@ -201,20 +208,20 @@ Attached Filters:
        The -attach family of switches simplify things enormously. By default, -attach
        will attach a filter to the last service created, so:
 
        The -attach family of switches simplify things enormously. By default, -attach
        will attach a filter to the last service created, so:
 

-       $ inigo clip1.dv clip2.dv -attach greyscale clip3.dv
+       $ melt clip1.dv clip2.dv -attach greyscale clip3.dv

 
        would only apply the filter to clip2.dv. You can further narrow down the area of
        the effect by specifying in/out points on the attached filter.
 
        This might seem simple so far, but there is a catch... consider the following:
 
 
        would only apply the filter to clip2.dv. You can further narrow down the area of
        the effect by specifying in/out points on the attached filter.
 
        This might seem simple so far, but there is a catch... consider the following:
 

-       $ ingo clip1.dv -attach watermark:+hello.txt -attach invert
+       $ melt clip1.dv -attach watermark:+hello.txt -attach invert

 
        The second attached filter is actually attached to the watermark. You might 
        think, yay, nice (and it is :-)), but, it might not be what you want. For example
        you might want to attach both to clip1.dv. To do that, you can use:
 
 
        The second attached filter is actually attached to the watermark. You might 
        think, yay, nice (and it is :-)), but, it might not be what you want. For example
        you might want to attach both to clip1.dv. To do that, you can use:
 

-       $ ingo clip1.dv -attach-cut watermark:+hello.txt -attach-cut invert
+       $ melt clip1.dv -attach-cut watermark:+hello.txt -attach-cut invert

 
        As you shall see below, there are still another couple of gotchas associated to 
        -attach, and even another variant :-).
 
        As you shall see below, there are still another couple of gotchas associated to 
        -attach, and even another variant :-).


@@ -227,17 +234,17 @@ Mixes:
 
        For example:
 
 
        For example:
 

-       $ inigo clip1.dv clip2.dv -mix 25 -mixer luma -mixer mix:-1
+       $ melt clip1.dv clip2.dv -mix 25 -mixer luma -mixer mix:-1

 
        would provide both an audio and video transition between clip1 and clip2.
 
        This functionality supercedes the enforced use of the -track and -transition
 
        would provide both an audio and video transition between clip1 and clip2.
 
        This functionality supercedes the enforced use of the -track and -transition

-       switches from earlier versions of inigo and makes life a lot easier :-).
+       switches from earlier versions of melt and makes life a lot easier :-).

 
        These can be used in combination, so you can for example do a fade from black
        and to black using the following:
 
 
        These can be used in combination, so you can for example do a fade from black
        and to black using the following:
 

-       $ inigo colour:black out=24 clip1.dv -mix 25 -mixer luma \
+       $ melt colour:black out=24 clip1.dv -mix 25 -mixer luma \

                colour:black out=24 -mix 25 -mixer luma 
        
        while this may not be immediately obvious, consider what's happening as the 
                colour:black out=24 -mix 25 -mixer luma 
        
        while this may not be immediately obvious, consider what's happening as the 


@@ -264,7 +271,7 @@ Mix and Attach:
        As noted, -attach normally applies to the last created service - so, you can 
        attach a filter to the transition region using:
 
        As noted, -attach normally applies to the last created service - so, you can 
        attach a filter to the transition region using:
 

-       $ inigo clip1.dv clip2.dv -mix 25 -mixer luma -attach watermark:+Transition.txt
+       $ melt clip1.dv clip2.dv -mix 25 -mixer luma -attach watermark:+Transition.txt

 
        Again, nice, but take care - if you want the attached filter to be associated
        to the region following the transition, use -attach-cut instead.
 
        Again, nice, but take care - if you want the attached filter to be associated
        to the region following the transition, use -attach-cut instead.


@@ -287,7 +294,7 @@ Introducing Tracks and Blanks:
        It is best to visualise a track arrangement, so we'll start with
        an example:
        
        It is best to visualise a track arrangement, so we'll start with
        an example:
        

-       $ inigo a.dv -track b.dv in=0 out=49
+       $ melt a.dv -track b.dv in=0 out=49

        
        This can be visualised as follows:
        
        
        This can be visualised as follows:
        


@@ -304,11 +311,11 @@ Introducing Tracks and Blanks:
        example, the following would show the video from the a track, but the audio
        would come from the second track:
 
        example, the following would show the video from the a track, but the audio
        would come from the second track:
 

-       $ inigo a.dv -track b.mp3 in=0 out=49
+       $ melt a.dv -track b.mp3 in=0 out=49

 
        To have the 51st frame be the first frame of b, we can use the -blank switch:
        
 
        To have the 51st frame be the first frame of b, we can use the -blank switch:
        

-       $ inigo a.dv out=49 -track -blank 49 b.dv
+       $ melt a.dv out=49 -track -blank 49 b.dv

        
        Which we can visualise as:
        
        
        Which we can visualise as:
        


@@ -330,7 +337,7 @@ Transitions:
        Here we need tracks to overlap, so a useful multitrack
        definition could be given as:
        
        Here we need tracks to overlap, so a useful multitrack
        definition could be given as:
        

-       $ inigo a.dv out=49 \
+       $ melt a.dv out=49 \

                -track \
                -blank 24 b.dv \
                -transition luma in=25 out=49 a_track=0 b_track=1
                -track \
                -blank 24 b.dv \
                -transition luma in=25 out=49 a_track=0 b_track=1


@@ -363,7 +370,7 @@ Reversing a Transition:
        
        In this scenario, we define a command line as follows:
        
        
        In this scenario, we define a command line as follows:
        

-       $ inigo a.dv out=49 -blank 49 a2.dv \
+       $ melt a.dv out=49 -blank 49 a2.dv \

                -track \
                -blank 24 b.dv out=99 \
                -transition luma in=25 out=49 a_track=0 b_track=1 \
                -track \
                -blank 24 b.dv out=99 \
                -transition luma in=25 out=49 a_track=0 b_track=1 \


@@ -372,19 +379,19 @@ Reversing a Transition:
 
 Serialisation:
 
 
 Serialisation:
 

-       Inigo has a built in serialisation mechanism - you can build up
+       Melt has a built in serialisation mechanism - you can build up

        your command, test it via any consumer and then add a -serialise
        your command, test it via any consumer and then add a -serialise

-       file.inigo switch to save it.
+       file.melt switch to save it.

        
        

-       The saved file can be subsequently used as a clip by either
-       miracle or inigo. Take care though - paths to files are saved as
+       The saved file can be subsequently used as a clip by melt or other
+       MLT applications. Take care though - paths to files are saved as

        provided on the command line....
 
        provided on the command line....
 

-       A more expressive serialisation can be obtained with the westley consumer
-       - this will provide an xml document which can be used freely in inigo and
-       miracle.
+       A more expressive serialisation can be obtained with the xml consumer
+       - this will provide an xml document which can be used freely in melt and
+       other MLT applications.

 
 

-       See westley.txt for more information.
+       See mlt-xml.txt for more information.

 
 
 Missing Features:
 
 
 Missing Features:


@@ -394,8 +401,8 @@ Missing Features:
        track or a watermark which you want composited on every frame, and of 
        course, there's the obscure filter.... 
        
        track or a watermark which you want composited on every frame, and of 
        course, there's the obscure filter.... 
        

-       inigo only supports this in two invocations - as a simple example:
+       melt only supports this in two invocations - as a simple example:

 
 

-       $ inigo a.dv -track -blank 100 b.dv -consumer westley:basic.westley
-       $ inigo basic.westley -filter watermark:watermark.png
+       $ melt a.dv -track -blank 100 b.dv -consumer xml:basic.mlt
+       $ melt basic.mlt -filter watermark:watermark.png