6 Westley is the MLT projects XML serialisation/deserialisation format -
7 as such, it closely mirrors the internal structure of the MLT API.
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
16 There are 3 types of producer:
18 * Basic Producers - these are typically file or device oriented feeds;
19 * Playlists - these are arrangements of multiple producers;
20 * Multitracks - these are the fx encapsulators.
22 In the mlt model, producers are created and attached to 'consumers' -
23 consumers are software playback components (such as SDL), or wrappers for
24 hardware drivers (such as bluefish) or even the westley serialising
25 consumer itself (the latter doesn't receive frames - it merely
26 interrogates the connected producer for its configuration).
28 Although westley was defined as a serialisation mechanism for instantiated
29 MLT components, this document will concentrate on the hand authoring of
35 As shall become apparent through the remainder of this document, the basic
36 tenet of westley authoring is to organise the document in the following
39 1) create producer elements for each unique media clip in the project;
40 2) create playlists for each track;
41 3) create a multitrack and specify filters and transitions;
42 4) adding global filters.
44 While other uses of westley exist, the approach taken here is to maximise
45 efficiency for complex projects.
50 The simplest westley document is:
53 <producer id="producer0">
54 <property name="resource">clip1.dv</property>
58 The westley wrapping is of course superfluous here - loading this document
59 with MLT is identical to loading the clip directly.
61 Of course, you can specify additional properties. For example, consider an
62 MPEG file with multiple soundtracks - you could define a westley document to
63 ensure that the second audio track is loaded:
66 <producer id="producer0">
67 <property name="resource">clip1.mpeg</property>
68 <property name="audio_track">1</property>
72 NB: This relies on the mpeg being handled by the avformat producer, rather
73 than the mcmpeg one. See services.txt for more details.
75 A more useful example comes with the pango producer for a text producer.
77 TODO: pango example...
81 1) It is better not to specify in/out points when defining basic producers
82 as these can be specified in the playlists. The reasoning is that in/out
83 restricts the amount of the clip available, and could lead to the same clip
84 being loaded multiple times if you need different regions of the clip
86 2) A westley can be specified as a resource, so westleys can naturally
87 encapsulate other westleys.
92 Playlists provide a 'collection' structure for producers. These can be used
93 to define 'tracks' in the multitrack approach, or simple playlists for
94 sequential, single track playout.
96 As an example, the following defines two basic producers and a playlist with 3
100 <producer id="producer0">
101 <property name="resource">clip1.dv</property>
103 <producer id="producer1">
104 <property name="resource">clip2.dv</property>
106 <playlist id="playlist0">
107 <entry producer="producer0" in="0" out="2999"/>
108 <entry producer="producer1" in="0" out="999"/>
109 <entry producer="producer0" in="3000" out="6999"/>
113 Here we see how the playlist defines the in/out points of the basic
118 1) All in/out points are absolute frame positions relative to the producer
119 being appended to the playlist;
120 2) Westley documents are currently authored for a specific normalisation;
121 3) The last 'producer' in the document is the default for play out;
122 4) Playlists can reference the same producer multiple times. In/out regions
123 do not need to be contiguous - duplication and skipping is acceptable.
126 Interlude - Introducing Multitracks:
129 So far we've defined basic producers and playlists/tracks - the tractor is
130 the element that allows us to arrange our tracks and specify filters and
131 transitions. Similarly to a playlist, a tractor is a container.
133 Note that MLT doesn't see a filter or a transition as a producer in the
134 normal sense - filters and transitions are passive when it comes to seeking.
135 Internally, seeks are carried out on the producers. This is an important
136 point - MLT does not follow a traditional graph oriented model.
138 Visualising an MLT tractor and it's interaction with the consumer will
141 +----------------------------------------------+
143 | +----------+ +-+ +-+ +-+ +-+ |
144 | |multitrack| |f| |f| |t| |t| |
145 | | +------+ | |i| |i| |r| |r| |
146 | | |track0|-|--->|l|- ->|l|- ->|a|--->|a|\ |
147 | | +------+ | |t| |t| |n| |n| \ |
148 | | | |e| |e| |s| |s| \ |
149 | | +------+ | |r| |r| |i| |i| \ | +--------+
150 | | |track1|-|- ->|0|--->|1|--->|t|--->|t|-----|--->|consumer|
151 | | +------+ | | | | | |i| |i| / | +--------+
152 | | | | | | | |o| |o| / | ^
153 | | +------+ | | | | | |n| |n| / | |
154 | | |track2|-|- ->| |- ->| |--->|0|- ->|1|/ | |
155 | | +------+ | | | | | | | | | | |
156 | +----------+ +-+ +-+ +-+ +-+ | |
157 +----------------------------------------------+ |
161 |APPLICATION|--------------------------------------------+
164 Internally, all frames from all tracks pass through all the filters and
165 transitions - these are told which tracks to deal and which regions of the
168 Note that the application communicates with the producer - it can alter
169 playback speed, position, or even which producer is connected to which
172 The consumer receives the first non-blank frame (see below). It has no say
173 in the order in which gets them (the sdl consumer when used with inigo might
174 appear to be an exception - it isn't - it simply has a route back to the
175 application to allow the application to interpret key presses).
177 Whether this is better or worse than a traditional graph approach is a moot
178 point. The author of this document likes it anyway :-).
183 To create a multitrack westley, we can use two playlists and introduce a
184 tractor. For the purposes of demonstration, I'll add a filter here too:
187 <producer id="producer0">
188 <property name="resource">clip1.dv</property>
190 <producer id="producer1">
191 <property name="resource">clip2.dv</property>
193 <playlist id="playlist0">
194 <entry producer="producer0" in="0" out="2999"/>
195 <blank length="1000"/>
196 <entry producer="producer0" in="3000" out="6999"/>
197 <playlist id="playlist1">
198 <blank length="3000"/>
199 <entry producer="producer1" in="0" out="999"/>
201 <tractor id="tractor0">
203 <track producer="playlist0"/>
204 <track producer="playlist1"/>
207 <property name="track">0</property>
208 <property name="mlt_service">greyscale</property>
213 Here we see that blank frames are inserted into the first playlist and a
214 blank is provided at the beginning of the second - this can be visualised in
215 the traditional timeline widget as follows:
217 +-------+ +-------------+
219 +-------+---+-------------+
223 Adding the filter on the top track, gives us:
225 +-------+ +-------------+
227 +-------+---+-------------+
229 --------+---+-------------+
233 Note that it's only applied to the visible parts of the top track.
235 The requirement to apply a filter to the output, as opposed to a specific track
236 leads us to the final item in the Rules section above. As an example, let's
237 assume we wish to watermark all output, then we could use the following:
240 <producer id="producer0">
241 <property name="resource">clip1.dv</property>
243 <producer id="producer1">
244 <property name="resource">clip2.dv</property>
246 <playlist id="playlist0">
247 <entry producer="producer0" in="0" out="2999"/>
248 <blank length="1000"/>
249 <entry producer="producer0" in="3000" out="6999"/>
250 <playlist id="playlist1">
251 <blank length="3000"/>
252 <entry producer="producer1" in="0" out="999"/>
254 <tractor id="tractor0">
256 <track producer="playlist0"/>
257 <track producer="playlist1"/>
260 <property name="track">0</property>
261 <property name="mlt_service">greyscale</property>
264 <tractor id="tractor1">
266 <track producer="tractor0"/>
269 <property name="mlt_service">watermark</property>
270 <property name="resource">watermark1.png</property>
275 Here we employ another tractor and we define a single track (being the
276 tractor we previously defined) and apply a watermarking filter there.
278 This is simply provided as an example - the watermarking functionality could
279 be better handled at the playout stage itself (ie: as a filter automatically
280 placed between all producers and the consumer).
282 TODO: transition example