git.sesse.net Git - mlt/blob - docs/westley.txt

   1 WESTLEY
   2 -------
   3
   4 Preamble:
   5
   6         Westley is the MLT projects XML serialisation/deserialisation format -
   7         as such, it closely mirrors the internal structure of the MLT API.
   8
   9
  10 Introduction:
  11
  12         A westley document is essentially a list of 'producers' - a producer is
  13         an mlt object which generates mlt frames (images and associated audio
  14         samples).
  15
  16         There are 3 types of producer:
  17
  18         * Basic Producers - these are typically file or device oriented feeds;
  19         * Playlists - these are arrangements of multiple producers;
  20         * Tractors - these are multitrack fx encapsulators.
  21
  22         Although westley was defined as a serialisation mechanism for running MLT
  23         components, this document will concentrate on the hand authoring of westley
  24         documents.
  25
  26
  27 Rules:
  28
  29         As shall become apparent through the remainder of this document, the basic
  30         tenet of westley authoring is to organise the document in the following
  31         manner:
  32
  33         1) create producer elements for each unique media clip in the project;
  34         2) create playlists for each track;
  35         3) create a tractor for track specific filters and transitions;
  36         4) create another tractor for filters that are common to the output.
  37
  38         While other uses of westley exist, the approach taken here is to maximise
  39         efficiency for complex projects.
  40
  41
  42 Basic Producers:
  43
  44         The simplest westley document is:
  45
  46         <westley>
  47           <producer id="producer0">
  48             <property name="resource">clip1.dv</property>
  49           </producer>
  50         </westley>
  51
  52         The westley wrapping is of course superfluous here - loading this document
  53         with MLT is identical to loading the clip directly.
  54
  55         Of course, you can specify additional properties. For example, consider an
  56         MPEG file with multiple soundtracks - you could define a westley document to
  57         ensure that the second audio track is loaded:
  58
  59         <westley>
  60           <producer id="producer0">
  61             <property name="resource">clip1.mpeg</property>
  62             <property name="audio_track">1</property>
  63           </producer>
  64         </westley>
  65
  66         NB: This relies on the mpeg being handled by the avformat producer, rather
  67         than the mcmpeg one. See services.txt for more details.
  68
  69         A more useful example comes with the pango producer for a text producer.
  70
  71         TODO: pango example...
  72
  73         Notes:
  74
  75         1) It is better not to specify in/out points when defining basic producers
  76         as these can be specified in the playlists. The reasoning is that in/out
  77         restricts the amount of the clip available, and could lead to the same clip
  78         being loaded multiple times if you need different regions of the clip
  79         elsewhere;
  80         2) A westley can be specified as a resource, so westleys can naturally
  81         encapsulate other westleys.
  82
  83
  84 Playlists:
  85
  86         Playlists provide a 'collection' structure for producers. These can be used
  87         to define 'tracks' in the multitrack approach, or simple playlists for
  88         sequential, single track playout.
  89
  90         As an example, the following defines two basic producers and a playlist with 3
  91         items:
  92
  93         <westley>
  94           <producer id="producer0">
  95             <property name="resource">clip1.dv</property>
  96           </producer>
  97           <producer id="producer1">
  98             <property name="resource">clip2.dv</property>
  99           </producer>
 100           <playlist id="playlist0">
 101             <entry producer="producer0" in="0" out="2999"/>
 102             <entry producer="producer1" in="0" out="999"/>
 103             <entry producer="producer0" in="3000" out="6999"/>
 104           </playlist>
 105         </westley>
 106
 107         Here we see how the playlist defines the in/out points of the basic
 108         producers.
 109
 110         Notes:
 111
 112         1) All in/out points are absolute frame positions - we support PAL and
 113         NTSC at a system level, but westley documents are currently authored
 114         for a specific normalisation;
 115         2) The last 'producer' in the document is the default for play out;
 116         3) Playlists can reference the same producer multiple times. In/out regions
 117         do not need to be contiguous - duplication and skipping is acceptable.
 118
 119
 120 Interlude - Introducing Tractors:
 121
 122         So far, we've defined basic producers and playlists/tracks - the tractor is
 123         the element that allows us to arrange our tracks and specify filters and
 124         transitions. Similarly to a playlist, a tractor is a container.
 125
 126         Note that MLT doesn't see a filter or a transition as a producer in the
 127         normal sense - filters and transitions are passive when it comes to seeking.
 128         Internally, seeks are carried out on the producers. This is an important
 129         point - MLT does not follow a traditional graph oriented model.
 130
 131         Visualising an MLT tractor and it's interaction with the consumer will
 132         assist here:
 133
 134         +----------------------------------------------+
 135         |tractor                                       |
 136         | +----------+    +-+    +-+    +-+    +-+     |
 137         | |multitrack|    |f|    |f|    |t|    |t|     |
 138         | | +------+ |    |i|    |i|    |r|    |r|     |
 139         | | |track0|-|--->|l|- ->|l|- ->|a|--->|a|\    |
 140         | | +------+ |    |t|    |t|    |n|    |n| \   |
 141         | |          |    |e|    |e|    |s|    |s|  \  |
 142         | | +------+ |    |r|    |r|    |i|    |i|   \ |    +--------+
 143         | | |track1|-|- ->|0|--->|1|--->|t|--->|t|-----|--->|consumer|
 144         | | +------+ |    | |    | |    |i|    |i|   / |    +--------+
 145         | |          |    | |    | |    |o|    |o|  /  |         ^
 146         | | +------+ |    | |    | |    |n|    |n| /   |         |
 147         | | |track2|-|- ->| |- ->| |--->|0|- ->|1|/    |         |
 148         | | +------+ |    | |    | |    | |    | |     |         |
 149         | +----------+    +-+    +-+    +-+    +-+     |         |
 150         +----------------------------------------------+         |
 151                ^                                                 |
 152                |                                                 |
 153         +-----------+                                            |
 154         |APPLICATION|--------------------------------------------+
 155         +-----------+
 156
 157         Internally, all frames from all tracks pass through all the filters and
 158         transitions - these are told which tracks to deal and which regions of the
 159         tracks to work on.
 160
 161         Note that the application communicates with the producer - it can alter
 162         playback speed, position, or even which producer is connected to which
 163         consumer.
 164
 165         In a later phase of MLT development, the application will be able to
 166         manipulate the tractors make up, by adding and removing tracks, filters
 167         and transitions. The consumer itself remains connected to the same object
 168         (the tractor).
 169
 170         The consumer receives the first non-blank frame (see below). It has no say
 171         in the order in which gets them (the sdl consumer when used with inigo might
 172         appear to be an exception - it isn't - it simply has a route back to the
 173         application to allow the application to interpret key presses).
 174
 175         Whether this is better or worse than a traditional graph approach is a moot
 176         point. The author of this document likes it anyway :-).
 177
 178
 179 Tractors:
 180
 181         To create a multitrack westley, we can use two playlists and introduce a
 182         tractor. For the purposes of demonstration, I'll add a filter here too:
 183
 184         <westley>
 185           <producer id="producer0">
 186             <property name="resource">clip1.dv</property>
 187           </producer>
 188           <producer id="producer1">
 189             <property name="resource">clip2.dv</property>
 190           </producer>
 191           <playlist id="playlist0">
 192             <entry producer="producer0" in="0" out="2999"/>
 193             <blank length="1000"/>
 194             <entry producer="producer0" in="3000" out="6999"/>
 195           <playlist id="playlist1">
 196             <blank length="3000"/>
 197             <entry producer="producer1" in="0" out="999"/>
 198           </playlist>
 199           <tractor id="tractor0">
 200             <multitrack>
 201               <track producer="playlist0"/>
 202               <track producer="playlist1"/>
 203             </multitrack>
 204             <filter>
 205               <property name="track">0</property>
 206               <property name="mlt_service">greyscale</property>
 207             </filter>
 208           </tractor>
 209         </westley>
 210
 211         Here we see that blank frames are inserted into the first playlist and a
 212         blank is provided at the beginning of the second - this can be visualised in
 213         the traditional timeline widget as follows:
 214
 215         +-------+   +-------------+
 216         |a      |   |a            |
 217         +-------+---+-------------+
 218                 |b  |
 219                 +---+
 220
 221         Adding the filter on the top track, gives us:
 222
 223         +-------+   +-------------+
 224         |a      |   |a            |
 225         +-------+---+-------------+
 226         |greyscale                |
 227         --------+---+-------------+
 228                 |b  |
 229                 +---+
 230
 231         Note that it's only applied to the visible parts of the top track.
 232
 233         The requirement to apply a filter to the output, as opposed to a specific track
 234         leads us to the final item in the Rules section above. As an example, let's
 235         assume we wish to watermark all output, then we could use the following:
 236
 237         <westley>
 238           <producer id="producer0">
 239             <property name="resource">clip1.dv</property>
 240           </producer>
 241           <producer id="producer1">
 242             <property name="resource">clip2.dv</property>
 243           </producer>
 244           <playlist id="playlist0">
 245             <entry producer="producer0" in="0" out="2999"/>
 246             <blank length="1000"/>
 247             <entry producer="producer0" in="3000" out="6999"/>
 248           <playlist id="playlist1">
 249             <blank length="3000"/>
 250             <entry producer="producer1" in="0" out="999"/>
 251           </playlist>
 252           <tractor id="tractor0">
 253             <multitrack>
 254               <track producer="playlist0"/>
 255               <track producer="playlist1"/>
 256             </multitrack>
 257             <filter>
 258               <property name="track">0</property>
 259               <property name="mlt_service">greyscale</property>
 260             </filter>
 261           </tractor>
 262           <tractor id="tractor1">
 263             <multitrack>
 264               <track producer="tractor0"/>
 265             </multitrack>
 266             <filter>
 267               <property name="mlt_service">watermark</property>
 268               <property name="resource">watermark1.png</property>
 269             </filter>
 270           </tractor>
 271         </westley>
 272
 273         Here we employ another tractor and we define a single track (being the
 274         tractor we previously defined) and apply a watermarking filter there.
 275
 276         This is simply provided as an example - the watermarking functionality could
 277         be better handled at the playout stage itself (ie: as a filter automatically
 278         placed between all producers and the consumer).
 279
 280         TODO: transition example