Constness changes
[melted] / demo / README
1 MLT Demo Notes
2
3 Before running the demo script, make sure you '. setenv' from the parent
4 directory. Also, please create clips clip1.dv, clip2.dv, clip3.dv, clip1.mpeg,
5 clip2.mpeg, clip3.mpeg, and music1.ogg. Please make sure clips are at least 500 
6 frames duration.
7
8 These notes explain the the concepts presented in each demonstration and
9 what details to look for.
10
11 First, a note on consumers. When you start the script, the main menu asks
12 you to choose a consumer. A consumer is like a viewer, but it could also
13 write to a stream/file. The "SDL" consumer is the popular Simple DirectMedia
14 Layer audio and video output. The "Westley" consumer generates an XML
15 representation of the service network. That can be played directly due to the
16 westley producer plugin. See docs/westley.txt for more information. The
17 "MainConcept DV" consumer refers to the proprietary MLT plugin required to
18 use MLT with MainConcept DV, DVCPro, and MPEG codecs. "/dev/dv1394/0" refers
19 to a device file for transmitting DV over FireWire using the Linux dv1394 kernel
20 module. The "BlueFish444" consumer is another proprietary plugin to use
21 the BlueFish444 manufactured SDI video/audio output cards with MLT.
22
23 And now the demos...
24
25 All clips
26
27         Simply builds a playlist containing each video clip, and you can transport
28         between them using j and k keys.
29
30 Filter in/out
31
32         A video filter can be applied to a portion of a producer (clip, playlist,
33         or multitrack). This examples shows the greyscale filter.
34
35 Watermark
36
37         A graphic can overlay video in realtime with support for alpha channel.
38         This example uses a PNG file with an alpha channel. Distortion is explicitly
39         enabled here so the otherwise circular graphic is scaled to fill the 
40         compositing region. By default, compositing honours the aspect ratio of the
41         overlay.
42
43 My name is...
44
45         Titles are very easy to composite in realtime. The titler uses Pango
46         with the FreeType2 rendering backend. This means it supports high
47         quality scalable font rendering with anti-aliasing, unicode (UTF-8),
48         and Pango markup capabilities. The compsiting here respects the aspect
49         ratio of the rendered title in the first two title pieces but distorts
50         the final one. This demo also shows the motion and scaling capabilities
51         of the compositor in conjunction with honouring aspect. The compositor
52         is doing field-based rendering. So, when displayed non-progressively
53         with SDL, you can see motion artifacts during animation. 
54         
55 A composite transition
56
57         The compositor also handles video over video as demonstrated in this
58         usage of the compositor to create a special transition. This demonstration
59         also crossfades the audio during the transition! Progressive rendering
60         is explicitly enabled on the compositor due to the poor results that
61         would otherwise occur due to scaling an interleaved video frame and moving
62         the video in a reverse direction horizontally.
63         
64 Fade in and out
65
66         A simple series of transitions betwen 3 clips using dissolves and audio 
67         crossfades. This is easy :-).
68
69 Clock in and out
70         
71         Wipe transitions are very easy and highly extensible as they are generated 
72         using a very convenient lookup table based upon the luma of an image.
73         This image can be a 16 bit PGM (grayscale bitmap) or the luma channel of
74         any video producer. A number of high quality wipes can be downloaded from
75         http://mlt.sf.net/. It also performs field rendering.
76         The second wipe demonstrates the ability to control the direction of the
77         wipe as well.
78         
79 Obscure
80
81         A popular requirement in news production is to obscure a face, obscenity,
82         or trademarked logo. This demonstrates using a simple rectangular 
83         obscure filter applied to a region of the image. The second example is more
84         advanced and shows using the "region" filter to select the image area and a 
85         property of the region filter to "shape" the region using the alpha channel
86         of another image (circle.png) and another property to "filter" the region
87         using the obscure filter.
88
89 Audio Stuff
90
91         A music bed sound track can be mixed with a video. The sound track of the
92         video clip has a "floating" amplitude normalisation filter applied.
93         Typically, audio normalisation applies a constant gain factor across the
94         entire duration of an audio segment from a single source where the 
95         gain factor is automatically determined by anaylsing the maximum "power"
96         or peak levels. However, in news production, a popular requirement is to
97         to dynamically boost the amplitude in soft areas and reduce the amplitude
98         in louder areas. Thus, the gain analysis is performed using a "sliding
99         window" approach. This example also applies a constant gain factor of 
100         0.5 (50%) to the normalised audio of the video clip (to get a nicer
101         mix level).
102         
103 Audio and Video Levels
104
105         Audio can be normalised by setting a target amplitude level in decibels.
106         A gamma curve can be applied to the luma channel of video.
107
108 Shadowed Title and Watermark
109
110         Two instances of the titler are used to create a shadow effect.
111         The aspect ratio of the watermark in this example is not distorted. Since
112         the original image is a circle with square pixels--a computer-generated
113         image--and ITU BT.601 video is not composed of square samples. Therefore,
114         the compositor normalises the pixel aspect ratio of the overlay to the 
115         destination image, and the circular image remains circular on the analog
116         video output. Finally, a greyscale filter is applied to the watermark
117         while its opacity is set at 30%.
118
119 Station Promo into Story?
120
121         Here is fun demo that might show using a still graphic with some music
122         to introduce a show. A luma wipe with an audio crossfade transitions from
123         the show title or station promotional material.
124
125 Voiceover 2 clips with title
126
127         A common news production requirement to have a "voiceover" audio track
128         to a clip or even multiple clips as demonstrated here. Likewise, it is 
129         common to place a title caption on the video at the same time! This
130         demo has a little fun with the titler at the sake of practicality :-)
131         The foreground of the title is transparent while the opacity of the 
132         background is reduced to blend with the video. Meanwhile, the compositor
133         stretches the image to fill the bottom slice of the video--not suitable
134         for overscan displays ;-)
135         
136         Also, pay close attention to the mixing levels of the audio tracks.
137         The audio of the video fades out as the voiceover track (just music
138         in this demo) fades in. Then, the voiceover remains mixed with the 
139         ambient audio at a 60% level. Finally, the voiceover fades out smoothly 
140         from the 60% level to nothing.
141
142 GJ-TTAvantika title
143
144         This demo requires a special TrueType font called Avantika. If you have the
145         font, register it with fontconfig using the fc-cache utility. This 
146         demonstrates i18n capabilities of the titler and the alignment capabilities 
147         of both the titler and the compositor. The titler centre aligns
148         the two lines of text, and the compositor centre aligns the title 
149         horizontally on the frame. 
150
151 Title over graphic
152
153         You can superimpose a title over a graphic over video! Also,
154         you can apply a luma wipe to the compositor!
155
156 Slideshow
157
158         This demo requires any number of JPEG images with the extension ".jpg"
159         in a subdirectory named "Scotland."
160
161 Bouncy, Bouncy
162
163         The "watermark" filter encapsulates the compositor, and you have full
164         control over the compositor properties. Who says a watermark can not 
165         also be a video?!
166
167 Bouncy, Bouncy Ball
168
169         A variation on the above Bouncy, Bouncy demo that applies a shape, or
170         alpha producer, to the the compositing region.
171         
172 Breaking News
173
174         This demonstrates layout capabilities of the compositor.
175
176 Squeeze Transitions
177
178         This demonstrates a distorting barndoor-like wipe.
179
180
181 J Cut
182
183         A J cut is an edit where the audio cuts before the video.
184         It gets its name from the way it looks on a NLE timeline user interface.
185         When the audio cuts over, it does an audio crossfade over the duration of 
186         one frame. This makes the audio cut slightly less abrupt and avoids any 
187         "click" due to mismatched sample levels at the edit point. The video edit
188         is a hard cut.
189
190 L Cut
191
192         An L cut is an edit where the video cuts before the audio.
193         It gets its name from the way it looks on a NLE timeline user interface.
194         This demo shows a very quick dissolve over 5 frames for a soft video cut.
195         Like the J Cut demo, an audio crossfade for the duration of one frame makes
196         an audio edit nearly instantaneous while being slightly softened and 
197         avoiding aberrations.
198
199 Fade from/to black/silence
200
201         Of course, it is possible using MLT to fade from black on video and silence
202         on audio as well fade to black and silence.
203         
204 Push wipe
205
206         A push wipe is a somewhat fancier transition than most standard wipes
207         because it involves motion. The new video clip "pushes" the old video
208         clip off one edge. If you can preview on an analog monitor you will notice
209         how smooth the motion is due to field-based rendering.
210         
211 Ticker tape
212
213         A very minimal reverse crawling title neard the bottom of the screen.
214         The goal of the demo is show fluid motion of the field-based rendering of
215         the compositor when viewed on an analog monitor using a DV or BlueFish444
216         consumer. The demo also shows the potientional for using and extending the
217         existing set of services for a full blown news ticker implementation.