cinelerra-5.0/doc/cinelerra.html

   1 <html lang="en">
   2 <head>
   3 <title>SECRETS OF CINELERRA</title>
   4 <meta http-equiv="Content-Type" content="text/html">
   5 <meta name="description" content="SECRETS OF CINELERRA">
   6 <meta name="generator" content="makeinfo 4.13">
   7 <link title="Top" rel="top" href="#Top">
   8 <link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
   9 <meta http-equiv="Content-Style-Type" content="text/css">
  10 <style type="text/css"><!--
  11   pre.display { font-family:inherit }
  12   pre.format  { font-family:inherit }
  13   pre.smalldisplay { font-family:inherit; font-size:smaller }
  14   pre.smallformat  { font-family:inherit; font-size:smaller }
  15   pre.smallexample { font-size:smaller }
  16   pre.smalllisp    { font-size:smaller }
  17   span.sc    { font-variant:small-caps }
  18   span.roman { font-family:serif; font-weight:normal; }
  19   span.sansserif { font-family:sans-serif; font-weight:normal; }
  20 --></style>
  21 </head>
  22 <body>
  23 <div class="node">
  24 <a name="Top"></a>
  25 <p><hr>
  26 Next:&nbsp;<a rel="next" accesskey="n" href="#ABOUT-CINELERRA">ABOUT CINELERRA</a>,
  27 Up:&nbsp;<a rel="up" accesskey="u" href="#dir">(dir)</a>
  28
  29 </div>
  30
  31 <h2 class="unnumbered">SECRETS OF CINELERRA</h2>
  32
  33 <div align="center"></div>
  34
  35    <p>Version 4.1
  36
  37    <p>by Adam Williams
  38
  39    <p>Copyright &copy; 2011
  40
  41 <h2 class="chapter">1 SHORT CONTENTS</h2>
  42
  43 <ul class="menu">
  44 <li><a accesskey="1" href="#ABOUT-CINELERRA">ABOUT CINELERRA</a>:           Cinelerra in brief.
  45 <li><a accesskey="2" href="#INSTALLATION">INSTALLATION</a>:              Making Cinelerra work on your system.
  46 <li><a accesskey="3" href="#CONFIGURATION">CONFIGURATION</a>:             Adjusting the behavior of Cinelerra.
  47 <li><a accesskey="4" href="#CREATING-A-NEW-PROJECT">CREATING A NEW PROJECT</a>:    Creating a new project
  48 <li><a accesskey="5" href="#THE-MAIN-WINDOWS">THE MAIN WINDOWS</a>:          The most often used user interfaces.
  49 <li><a accesskey="6" href="#LOADING-AND-SAVING-FILES">LOADING AND SAVING FILES</a>:  Moving media between disk and Cinelerra.
  50 <li><a accesskey="7" href="#NAVIGATING-THE-PROJECT">NAVIGATING THE PROJECT</a>:    Moving around the media.
  51 <li><a accesskey="8" href="#EDITING">EDITING</a>:                   Moving the media in time.
  52 <li><a accesskey="9" href="#USING-EFFECTS">USING EFFECTS</a>:             Altering the media.
  53 <li><a href="#SETTING-PROJECT-ATTRIBUTES">SETTING PROJECT ATTRIBUTES</a>:  Changing the way the media is displayed.
  54 <li><a href="#COMPOSITING">COMPOSITING</a>:               Overlaying different sources of video.
  55 <li><a href="#KEYFRAMES">KEYFRAMES</a>:                 Making effects change over time.
  56 <li><a href="#CAPTURING-MEDIA">CAPTURING MEDIA</a>:           Moving media from the real world to disk.
  57 <li><a href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>:     Making Cinelerra run better on Linux.
  58 <li><a href="#TROUBLESHOOTING">TROUBLESHOOTING</a>:           Problems with Cinelerra.
  59 <li><a href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>:      Unusual applications of Cinelerra to common problems.
  60 <li><a href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>:       Secrets of the more complicated effects.
  61 <li><a href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>:          How to write new effects.
  62 <li><a href="#KEYBOARD-SHORTCUTS">KEYBOARD SHORTCUTS</a>:        How to accelerate most commands with the keyboard.
  63 </ul>
  64
  65    <div class="contents">
  66 <h2>Table of Contents</h2>
  67 <ul>
  68 <li><a name="toc_Top" href="#Top">SECRETS OF CINELERRA</a>
  69 <li><a name="toc_Top" href="#Top">1 SHORT CONTENTS</a>
  70 <li><a name="toc_ABOUT-CINELERRA" href="#ABOUT-CINELERRA">2 ABOUT CINELERRA</a>
  71 <ul>
  72 <li><a href="#ABOUT-THIS-MANUAL">2.1 ABOUT THIS MANUAL</a>
  73 </li></ul>
  74 <li><a name="toc_INSTALLATION" href="#INSTALLATION">3 INSTALLATION</a>
  75 <ul>
  76 <li><a href="#INSTALLING-AN-RPM">3.1 INSTALLING AN RPM</a>
  77 <li><a href="#COMPILING-FROM-SCRATCH">3.2 COMPILING FROM SCRATCH</a>
  78 <li><a href="#RUNNING-CINELERRA">3.3 RUNNING CINELERRA</a>
  79 </li></ul>
  80 <li><a name="toc_CONFIGURATION" href="#CONFIGURATION">4 CONFIGURATION</a>
  81 <ul>
  82 <li><a href="#ENVIRONMENT-VARIABLES">4.1 ENVIRONMENT VARIABLES</a>
  83 <li><a href="#AUDIO-DRIVERS">4.2 AUDIO DRIVERS</a>
  84 <ul>
  85 <li><a href="#COMMON-SOUND-DRIVER-ATTRIBUTES">4.2.1 COMMON SOUND DRIVER ATTRIBUTES</a>
  86 <li><a href="#OSS">4.2.2 OSS</a>
  87 <li><a href="#OSS-Envy24">4.2.3 OSS Envy24</a>
  88 <li><a href="#ALSA">4.2.4 ALSA</a>
  89 <li><a href="#ESOUND">4.2.5 ESOUND</a>
  90 <li><a href="#RAW-1394">4.2.6 RAW 1394</a>
  91 <li><a href="#DV-1394">4.2.7 DV 1394</a>
  92 <li><a href="#IEC-61883">4.2.8 IEC 61883</a>
  93 </li></ul>
  94 <li><a href="#VIDEO-DRIVERS">4.3 VIDEO DRIVERS</a>
  95 <ul>
  96 <li><a href="#COMMON-VIDEO-DRIVER-ATTRIBUTES">4.3.1 COMMON VIDEO DRIVER ATTRIBUTES</a>
  97 <li><a href="#X11">4.3.2 X11</a>
  98 <li><a href="#X11_002dXV">4.3.3 X11-XV</a>
  99 <li><a href="#X11_002dOPENGL">4.3.4 X11-OPENGL</a>
 100 <li><a href="#BUZ">4.3.5 BUZ</a>
 101 <li><a href="#RAW-1394-VIDEO-PLAYBACK">4.3.6 RAW 1394 VIDEO PLAYBACK</a>
 102 <li><a href="#DV-1394-VIDEO-PLAYBACK">4.3.7 DV 1394 VIDEO PLAYBACK</a>
 103 <li><a href="#IEC-61883-VIDEO-PLAYBACK">4.3.8 IEC 61883 VIDEO PLAYBACK</a>
 104 </li></ul>
 105 <li><a href="#PLAYBACK">4.4 PLAYBACK</a>
 106 <ul>
 107 <li><a href="#AUDIO-OUT">4.4.1 AUDIO OUT</a>
 108 <li><a href="#VIDEO-OUT">4.4.2 VIDEO OUT</a>
 109 </li></ul>
 110 <li><a href="#RECORDING">4.5 RECORDING</a>
 111 <ul>
 112 <li><a href="#FILE-FORMAT">4.5.1 FILE FORMAT</a>
 113 <li><a href="#AUDIO-IN">4.5.2 AUDIO IN</a>
 114 <li><a href="#VIDEO-IN">4.5.3 VIDEO IN</a>
 115 </li></ul>
 116 <li><a href="#PERFORMANCE">4.6 PERFORMANCE</a>
 117 <ul>
 118 <li><a href="#BACKGROUND-RENDERING">4.6.1 BACKGROUND RENDERING</a>
 119 <li><a href="#RENDERFARM">4.6.2 RENDERFARM</a>
 120 </li></ul>
 121 <li><a href="#INTERFACE">4.7 INTERFACE</a>
 122 <li><a href="#ABOUT">4.8 ABOUT</a>
 123 </li></ul>
 124 <li><a name="toc_CREATING-A-NEW-PROJECT" href="#CREATING-A-NEW-PROJECT">5 CREATING A NEW PROJECT</a>
 125 <ul>
 126 <li><a href="#USING-THE-NEW-PROJECT-DIALOG">5.1 USING THE NEW PROJECT DIALOG</a>
 127 <li><a href="#CHANGING-PARAMETERS-AFTER-LOADING">5.2 CHANGING PARAMETERS AFTER LOADING</a>
 128 </li></ul>
 129 <li><a name="toc_THE-MAIN-WINDOWS" href="#THE-MAIN-WINDOWS">6 THE MAIN WINDOWS</a>
 130 <ul>
 131 <li><a href="#VIEWER">6.1 VIEWER</a>
 132 <li><a href="#COMPOSITOR">6.2 COMPOSITOR</a>
 133 <ul>
 134 <li><a href="#PROTECT-VIDEO">6.2.1 PROTECT VIDEO</a>
 135 <li><a href="#MAGNIFYING-GLASS">6.2.2 MAGNIFYING GLASS</a>
 136 <li><a href="#MASKS-TOOL">6.2.3 MASKS TOOL</a>
 137 <li><a href="#CAMERA">6.2.4 CAMERA</a>
 138 <li><a href="#PROJECTOR">6.2.5 PROJECTOR</a>
 139 <li><a href="#CROP-TOOL">6.2.6 CROP TOOL</a>
 140 <li><a href="#EYEDROPPER">6.2.7 EYEDROPPER</a>
 141 <li><a href="#TOOL-INFO">6.2.8 TOOL INFO</a>
 142 <li><a href="#SAFE-REGIONS-TOOL">6.2.9 SAFE REGIONS TOOL</a>
 143 </li></ul>
 144 <li><a href="#PROGRAM">6.3 PROGRAM</a>
 145 <li><a href="#RESOURCES">6.4 RESOURCES</a>
 146 <li><a href="#SOUND-LEVEL-METERS">6.5 SOUND LEVEL METERS</a>
 147 <li><a href="#OTHER-WINDOWS">6.6 OTHER WINDOWS</a>
 148 </li></ul>
 149 <li><a name="toc_LOADING-AND-SAVING-FILES" href="#LOADING-AND-SAVING-FILES">7 LOADING AND SAVING FILES</a>
 150 <ul>
 151 <li><a href="#SUPPORTED-FILE-FORMATS">7.1 SUPPORTED FILE FORMATS</a>
 152 <ul>
 153 <li><a href="#QUICKTIME">7.1.1 QUICKTIME</a>
 154 <li><a href="#MPEG_002d4-AUDIO">7.1.2 MPEG-4 AUDIO</a>
 155 <li><a href="#IMAGE-SEQUENCES">7.1.3 IMAGE SEQUENCES</a>
 156 <li><a href="#STILL-IMAGES">7.1.4 STILL IMAGES</a>
 157 <ul>
 158 <li><a href="#OPEN-EXR-IMAGES">7.1.4.1 OPEN EXR IMAGES</a>
 159 <li><a href="#RAW-DIGITAL-CAMERA-IMAGES">7.1.4.2 RAW DIGITAL CAMERA IMAGES</a>
 160 </li></ul>
 161 <li><a href="#AVI">7.1.5 AVI</a>
 162 <li><a href="#MPEG-FILES-CONTAINING-VIDEO">7.1.6 MPEG FILES CONTAINING VIDEO</a>
 163 <li><a href="#DVD-MOVIES">7.1.7 DVD MOVIES</a>
 164 <li><a href="#MPEG-1-AUDIO">7.1.8 MPEG 1 AUDIO</a>
 165 <li><a href="#OGG-THEORA_002fVORBIS">7.1.9 OGG THEORA/VORBIS</a>
 166 <li><a href="#EDIT-DECISION-LIST">7.1.10 EDIT DECISION LIST</a>
 167 </li></ul>
 168 <li><a href="#LOADING-FILES">7.2 LOADING FILES</a>
 169 <ul>
 170 <li><a href="#INSERTION-STRATEGY">7.2.1 INSERTION STRATEGY</a>
 171 <li><a href="#LOADING-MULTIPLE-FILES">7.2.2 LOADING MULTIPLE FILES</a>
 172 </li></ul>
 173 <li><a href="#LOADING-THE-BACKUP">7.3 LOADING THE BACKUP</a>
 174 <li><a href="#SAVING-FILES">7.4 SAVING FILES</a>
 175 <li><a href="#RENDERING-FILES">7.5 RENDERING FILES</a>
 176 <ul>
 177 <li><a href="#SINGLE-FILE-RENDERING">7.5.1 SINGLE FILE RENDERING</a>
 178 <li><a href="#BATCH-RENDERING">7.5.2 BATCH RENDERING</a>
 179 <li><a href="#THE-RENDER-FARM">7.5.3 THE RENDER FARM</a>
 180 <li><a href="#COMMAND-LINE-RENDERING">7.5.4 COMMAND LINE RENDERING</a>
 181 </li></ul>
 182 </li></ul>
 183 <li><a name="toc_NAVIGATING-THE-PROJECT" href="#NAVIGATING-THE-PROJECT">8 NAVIGATING THE PROJECT</a>
 184 <ul>
 185 <li><a href="#NAVIGATING-THE-PROGRAM-WINDOW">8.1 NAVIGATING THE PROGRAM WINDOW</a>
 186 <ul>
 187 <li><a href="#THE-INSERTION-POINT">8.1.1 THE INSERTION POINT</a>
 188 <li><a href="#THE-IN_002fOUT-POINTS">8.1.2 THE IN/OUT POINTS</a>
 189 <li><a href="#USING-LABELS-IN-THE-PROGRAM-WINDOW">8.1.3 USING LABELS IN THE PROGRAM WINDOW</a>
 190 </li></ul>
 191 <li><a href="#NAVIGATING-THE-VIEWER-AND-COMPOSITOR">8.2 NAVIGATING THE VIEWER AND COMPOSITOR</a>
 192 <li><a href="#NAVIGATING-THE-RESOURCES">8.3 NAVIGATING THE RESOURCES</a>
 193 <li><a href="#USING-THE-TRANSPORT-CONTROLS">8.4 USING THE TRANSPORT CONTROLS</a>
 194 <li><a href="#USING-BACKGROUND-RENDERING">8.5 USING BACKGROUND RENDERING</a>
 195 </li></ul>
 196 <li><a name="toc_EDITING" href="#EDITING">9 EDITING</a>
 197 <ul>
 198 <li><a href="#THE-PATCHBAY">9.1 THE PATCHBAY</a>
 199 <li><a href="#NUDGING-TRACKS">9.2 NUDGING TRACKS</a>
 200 <li><a href="#PANNING-TRACKS">9.3 PANNING TRACKS</a>
 201 <li><a href="#AUTOMATIC-TRACK-PANNING">9.4 AUTOMATIC TRACK PANNING</a>
 202 <li><a href="#STANDARD-AUDIO-MAPPINGS">9.5 STANDARD AUDIO MAPPINGS</a>
 203 <li><a href="#MANIPULATING-TRACKS">9.6 MANIPULATING TRACKS</a>
 204 <li><a href="#TWO-SCREEN-EDITING">9.7 TWO SCREEN EDITING</a>
 205 <li><a href="#DRAG-AND-DROP-EDITING">9.8 DRAG AND DROP EDITING</a>
 206 <li><a href="#CUT-AND-PASTE-EDITING">9.9 CUT AND PASTE EDITING</a>
 207 <li><a href="#TRIMMING">9.10 TRIMMING</a>
 208 </li></ul>
 209 <li><a name="toc_USING-EFFECTS" href="#USING-EFFECTS">10 USING EFFECTS</a>
 210 <ul>
 211 <li><a href="#REALTIME-EFFECTS">10.1 REALTIME EFFECTS</a>
 212 <ul>
 213 <li><a href="#REALTIME-EFFECT-TYPES">10.1.1 REALTIME EFFECT TYPES</a>
 214 <li><a href="#EDITING-REALTIME-EFFECTS">10.1.2 EDITING REALTIME EFFECTS</a>
 215 </li></ul>
 216 <li><a href="#RENDERED-EFFECTS">10.2 RENDERED EFFECTS</a>
 217 <li><a href="#TRANSITIONS">10.3 TRANSITIONS</a>
 218 <li><a href="#LADSPA-EFFECTS">10.4 LADSPA EFFECTS</a>
 219 <li><a href="#EFFECT-PRESETS">10.5 EFFECT PRESETS</a>
 220 </li></ul>
 221 <li><a name="toc_SETTING-PROJECT-ATTRIBUTES" href="#SETTING-PROJECT-ATTRIBUTES">11 SETTING PROJECT ATTRIBUTES</a>
 222 <ul>
 223 <li><a href="#AUDIO-CHANNEL-POSITIONS">11.1 AUDIO CHANNEL POSITIONS</a>
 224 <li><a href="#COLOR-MODEL">11.2 COLOR MODEL</a>
 225 <li><a href="#ASPECT-RATIO">11.3 ASPECT RATIO</a>
 226 </li></ul>
 227 <li><a name="toc_COMPOSITING" href="#COMPOSITING">12 COMPOSITING</a>
 228 <ul>
 229 <li><a href="#THE-CAMERA-AND-PROJECTOR">12.1 THE CAMERA AND PROJECTOR</a>
 230 <li><a href="#MASKS">12.2 MASKS</a>
 231 <li><a href="#CROPPING">12.3 CROPPING</a>
 232 <li><a href="#SAFE-REGIONS">12.4 SAFE REGIONS</a>
 233 <li><a href="#OVERLAY-MODES">12.5 OVERLAY MODES</a>
 234 <li><a href="#TRACK-AND-OUTPUT-SIZES">12.6 TRACK AND OUTPUT SIZES</a>
 235 </li></ul>
 236 <li><a name="toc_KEYFRAMES" href="#KEYFRAMES">13 KEYFRAMES</a>
 237 <ul>
 238 <li><a href="#CURVE-KEYFRAMES">13.1 CURVE KEYFRAMES</a>
 239 <li><a href="#CHANGING-BEZIER-_0026-LINEAR-MODE">13.2 CHANGING BEZIER &amp; LINEAR MODE</a>
 240 <li><a href="#SNAPPING-TO-NEIGHBOR-KEYFRAMES">13.3 SNAPPING TO NEIGHBOR KEYFRAMES</a>
 241 <li><a href="#NAVIGATING-CURVE-KEYFRAMES">13.4 NAVIGATING CURVE KEYFRAMES</a>
 242 <li><a href="#TOGGLE-KEYFRAMES">13.5 TOGGLE KEYFRAMES</a>
 243 <li><a href="#AUTOMATIC-KEYFRAMES">13.6 AUTOMATIC KEYFRAMES</a>
 244 <li><a href="#COMPOSITOR-KEYFRAMES">13.7 COMPOSITOR KEYFRAMES</a>
 245 <li><a href="#EDITING-KEYFRAMES">13.8 EDITING KEYFRAMES</a>
 246 <li><a href="#KEYFRAME-SPANNING">13.9 KEYFRAME SPANNING</a>
 247 </li></ul>
 248 <li><a name="toc_CAPTURING-MEDIA" href="#CAPTURING-MEDIA">14 CAPTURING MEDIA</a>
 249 <ul>
 250 <li><a href="#BATCHES">14.1 BATCHES</a>
 251 <li><a href="#EDITING-TUNER-INFORMATION">14.2 EDITING TUNER INFORMATION</a>
 252 </li></ul>
 253 <li><a name="toc_IMPROVING-PERFORMANCE" href="#IMPROVING-PERFORMANCE">15 IMPROVING PERFORMANCE</a>
 254 <ul>
 255 <li><a href="#DISABLING-SWAP-SPACE">15.1 DISABLING SWAP SPACE</a>
 256 <li><a href="#ENLARGING-SOUND-BUFFERS">15.2 ENLARGING SOUND BUFFERS</a>
 257 <li><a href="#FREEING-MORE-SHARED-MEMORY">15.3 FREEING MORE SHARED MEMORY</a>
 258 <li><a href="#SPEEDING-UP-THE-HARD-DRIVE">15.4 SPEEDING UP THE HARD DRIVE</a>
 259 <li><a href="#DISABLING-CRON">15.5 DISABLING CRON</a>
 260 <li><a href="#REDUCING-USB-MOUSE-SENSITIVITY">15.6 REDUCING USB MOUSE SENSITIVITY</a>
 261 <li><a href="#ASSORTED-X-TWEEKS">15.7 ASSORTED X TWEEKS</a>
 262 <li><a href="#SPEEDING-UP-THE-FILE-SYSTEM">15.8 SPEEDING UP THE FILE SYSTEM</a>
 263 <li><a href="#IMPROVING-ZORAN-VIDEO">15.9 IMPROVING ZORAN VIDEO</a>
 264 <ul>
 265 <li><a href="#IMPROVING-ZORAN-VIDEO">15.9.1 NEW IN 2.6.5</a>
 266 </li></ul>
 267 </li></ul>
 268 <li><a name="toc_TROUBLESHOOTING" href="#TROUBLESHOOTING">16 TROUBLESHOOTING</a>
 269 <ul>
 270 <li><a href="#BUZ-DRIVER-CRASHES">16.1 BUZ DRIVER CRASHES</a>
 271 <li><a href="#DRAGGING-IN-AND-OUT-POINTS-DOESN_0027T-WORK">16.2 DRAGGING IN AND OUT POINTS DOESN'T WORK</a>
 272 <li><a href="#LOCKING-UP-WHEN-LOADING-FILES">16.3 LOCKING UP WHEN LOADING FILES</a>
 273 <li><a href="#SYNCHRONIZATION-LOST-WHILE-RECORDING">16.4 SYNCHRONIZATION LOST WHILE RECORDING</a>
 274 <li><a href="#APPLYING-LINEARIZE-FOLLOWED-BY-BLUR-DOESN_0027T-WORK">16.5 APPLYING LINEARIZE FOLLOWED BY BLUR DOESN'T WORK</a>
 275 </li></ul>
 276 <li><a name="toc_SECRETS-OF-CINELERRA" href="#SECRETS-OF-CINELERRA">17 SECRETS OF CINELERRA</a>
 277 <ul>
 278 <li><a href="#DOLBY-PRO-LOGIC-ENCODING">17.1 DOLBY PRO LOGIC ENCODING</a>
 279 <li><a href="#ANALOG-TV-CLEANING">17.2 ANALOG TV CLEANING</a>
 280 <li><a href="#DEFEATING-INTERLACING">17.3 DEFEATING INTERLACING</a>
 281 <li><a href="#MAKING-VIDEO-LOOK-LIKE-FILM">17.4 MAKING VIDEO LOOK LIKE FILM</a>
 282 <li><a href="#CLEARING-OUT-HAZE">17.5 CLEARING OUT HAZE</a>
 283 <li><a href="#MAKING-A-DVD">17.6 MAKING A DVD</a>
 284 <li><a href="#MAKING-A-RINGTONE">17.7 MAKING A RINGTONE</a>
 285 <li><a href="#TIME-STRETCHING-AUDIO">17.8 TIME STRETCHING AUDIO</a>
 286 <li><a href="#PITCH-SHIFTING-AUDIO">17.9 PITCH SHIFTING AUDIO</a>
 287 <li><a href="#TEXT-TO-MOVIE">17.10 TEXT TO MOVIE</a>
 288 </li></ul>
 289 <li><a name="toc_SECRETS-OF-CINELERRA-EFFECTS" href="#SECRETS-OF-CINELERRA-EFFECTS">18 SECRETS OF CINELERRA EFFECTS</a>
 290 <ul>
 291 <li><a href="#1080-TO-480">18.1 1080 TO 480</a>
 292 <li><a href="#CHROMA-KEY">18.2 CHROMA KEY</a>
 293 <li><a href="#COMPRESSOR">18.3 COMPRESSOR</a>
 294 <li><a href="#DECIMATE">18.4 DECIMATE</a>
 295 <li><a href="#DEINTERLACE">18.5 DEINTERLACE</a>
 296 <li><a href="#DIFFERENCE-KEY">18.6 DIFFERENCE KEY</a>
 297 <li><a href="#FIELDS-TO-FRAMES">18.7 FIELDS TO FRAMES</a>
 298 <li><a href="#FREEZE-FRAME">18.8 FREEZE FRAME</a>
 299 <li><a href="#HISTOGRAM">18.9 HISTOGRAM</a>
 300 <li><a href="#INVERSE-TELECINE">18.10 INVERSE TELECINE</a>
 301 <li><a href="#INTERPOLATE-VIDEO">18.11 INTERPOLATE VIDEO</a>
 302 <li><a href="#LENS">18.12 LENS</a>
 303 <li><a href="#LINEARIZE">18.13 LINEARIZE</a>
 304 <li><a href="#LIVE-AUDIO">18.14 LIVE AUDIO</a>
 305 <li><a href="#LIVE-VIDEO">18.15 LIVE VIDEO</a>
 306 <li><a href="#LOOP">18.16 LOOP</a>
 307 <li><a href="#MOTION">18.17 MOTION</a>
 308 <ul>
 309 <li><a href="#SECRETS-OF-MOTION-TRACKING">18.17.1 SECRETS OF MOTION TRACKING</a>
 310 <li><a href="#2-PASS-MOTION-TRACKING">18.17.2 2 PASS MOTION TRACKING</a>
 311 <li><a href="#USING-BLUR-TO-IMPROVE-MOTION-TRACKING">18.17.3 USING BLUR TO IMPROVE MOTION TRACKING</a>
 312 <li><a href="#USING-HISTOGRAM-TO-IMPROVE-MOTION-TRACKING">18.17.4 USING HISTOGRAM TO IMPROVE MOTION TRACKING</a>
 313 <li><a href="#INTERPOLATING-MOTION-BETWEEN-FRAMES">18.17.5 INTERPOLATING MOTION BETWEEN FRAMES</a>
 314 <li><a href="#FILLING-IN-THE-BLACK-AREAS">18.17.6 FILLING IN THE BLACK AREAS</a>
 315 </li></ul>
 316 <li><a href="#MOTION-2-POINT">18.18 MOTION 2 POINT</a>
 317 <li><a href="#REFRAMERT">18.19 REFRAMERT</a>
 318 <li><a href="#REFRAME">18.20 REFRAME</a>
 319 <li><a href="#RESAMPLE">18.21 RESAMPLE</a>
 320 <li><a href="#REVERSE-VIDEO_002fAUDIO">18.22 REVERSE VIDEO/AUDIO</a>
 321 <li><a href="#SWAP-FRAMES">18.23 SWAP FRAMES</a>
 322 <li><a href="#THRESHOLD">18.24 THRESHOLD</a>
 323 <li><a href="#TIME-AVERAGE">18.25 TIME AVERAGE</a>
 324 <li><a href="#TITLER">18.26 TITLER</a>
 325 <ul>
 326 <li><a href="#ADDING-FONTS-TO-THE-TITLER">18.26.1 ADDING FONTS TO THE TITLER</a>
 327 <li><a href="#THE-TITLE_002dSAFE-REGION">18.26.2 THE TITLE-SAFE REGION</a>
 328 <li><a href="#MAKING-TITLES-LOOK-GOOD">18.26.3 MAKING TITLES LOOK GOOD</a>
 329 </li></ul>
 330 <li><a href="#VIDEO-SCOPE">18.27 VIDEO SCOPE</a>
 331 </li></ul>
 332 <li><a name="toc_PLUGIN-AUTHORING" href="#PLUGIN-AUTHORING">19 PLUGIN AUTHORING</a>
 333 <ul>
 334 <li><a href="#INTRODUCING-THE-PULL-METHOD">19.1 INTRODUCING THE PULL METHOD</a>
 335 <li><a href="#COMMON-PLUGIN-FUNCTIONS">19.2 COMMON PLUGIN FUNCTIONS</a>
 336 <ul>
 337 <li><a href="#THE-PROCESSING-OBJECT">19.2.1 THE PROCESSING OBJECT</a>
 338 <li><a href="#THE-CONFIGURATION-OBJECT">19.2.2 THE CONFIGURATION OBJECT</a>
 339 <li><a href="#THE-USER-INTERFACE-OBJECT">19.2.3 THE USER INTERFACE OBJECT</a>
 340 </li></ul>
 341 <li><a href="#REALTIME-PLUGINS">19.3 REALTIME PLUGINS</a>
 342 <li><a href="#NONREALTIME-PLUGINS">19.4 NONREALTIME PLUGINS</a>
 343 <li><a href="#AUDIO-PLUGINS">19.5 AUDIO PLUGINS</a>
 344 <li><a href="#VIDEO-PLUGINS">19.6 VIDEO PLUGINS</a>
 345 <li><a href="#TRANSITION-PLUGINS">19.7 TRANSITION PLUGINS</a>
 346 <li><a href="#PLUGIN-GUI_0027S-WHICH-UPDATE-DURING-PLAYBACK">19.8 PLUGIN GUI'S WHICH UPDATE DURING PLAYBACK</a>
 347 <li><a href="#PLUGIN-QUERIES">19.9 PLUGIN QUERIES</a>
 348 <ul>
 349 <li><a href="#SYSTEM-QUERIES">19.9.1 SYSTEM QUERIES</a>
 350 <li><a href="#TIMING-QUERIES">19.9.2 TIMING QUERIES</a>
 351 </li></ul>
 352 <li><a href="#USING-OPENGL">19.10 USING OPENGL</a>
 353 <ul>
 354 <li><a href="#GETTING-OPENGL-DATA">19.10.1 GETTING OPENGL DATA</a>
 355 <li><a href="#DRAWING-USING-OPENGL">19.10.2 DRAWING USING OPENGL</a>
 356 <li><a href="#USING-SHADERS">19.10.3 USING SHADERS</a>
 357 <li><a href="#AGGREGATING-PLUGINS">19.10.4 AGGREGATING PLUGINS</a>
 358 </li></ul>
 359 </li></ul>
 360 <li><a name="toc_KEYBOARD-SHORTCUTS" href="#KEYBOARD-SHORTCUTS">20 KEYBOARD SHORTCUTS</a>
 361 <ul>
 362 <li><a href="#KEYBOARD-SHORTCUTS">20.1 PROGRAM WINDOW</a>
 363 <ul>
 364 <li><a href="#KEYBOARD-SHORTCUTS">20.1.1 Editing Media</a>
 365 <li><a href="#KEYBOARD-SHORTCUTS">20.1.2 Editing Labels &amp; In/Out Points</a>
 366 <li><a href="#KEYBOARD-SHORTCUTS">20.1.3 Navigation</a>
 367 <li><a href="#KEYBOARD-SHORTCUTS">20.1.4 File operations</a>
 368 <li><a href="#KEYBOARD-SHORTCUTS">20.1.5 Key Frame Editing</a>
 369 <li><a href="#KEYBOARD-SHORTCUTS">20.1.6 Track Manipulation</a>
 370 <li><a href="#KEYBOARD-SHORTCUTS">20.1.7 What's drawn on the timeline</a>
 371 </li></ul>
 372 <li><a href="#KEYBOARD-SHORTCUTS">20.2 VIEWER &amp; COMPOSITOR WINDOWS</a>
 373 <li><a href="#KEYBOARD-SHORTCUTS">20.3 PLAYBACK TRANSPORT</a>
 374 <li><a href="#KEYBOARD-SHORTCUTS">20.4 RECORD WINDOW</a>
 375 </li></ul>
 376 </li></ul>
 377 </div>
 378
 379 <div class="node">
 380 <a name="ABOUT-CINELERRA"></a>
 381 <p><hr>
 382 Next:&nbsp;<a rel="next" accesskey="n" href="#INSTALLATION">INSTALLATION</a>,
 383 Previous:&nbsp;<a rel="previous" accesskey="p" href="#Top">Top</a>,
 384 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
 385
 386 </div>
 387
 388 <h2 class="chapter">2 ABOUT CINELERRA</h2>
 389
 390 <p><b>BROADCAST 1.0</b>
 391
 392    <p>In 1996 our first editor came out: Broadcast 1.0.  It was just a window
 393 with a waveform in it, it could cut and paste stereo audio waveforms on
 394 a UNIX box, except unlike other audio editors it could handle files up
 395 to 2 gigabytes with only 64 megs of RAM.  That was a feature normally
 396 only accessible to the highest end professional audio houses.
 397
 398    <p><b>BROADCAST 2.0</b>
 399
 400    <p>In 1997 Broadcast 1.0 was replaced by Broadcast 2.0.  This time the
 401 window had a menubar, patchbay, console, and transport control.
 402 Broadcast 2.0 still only handled audio but this time it handled
 403 unlimited tracks, and it could perform effects on audio and save the
 404 resulting waveform to disk.  More notably a few effects could be
 405 performed as the audio was playing back, in realtime.  A user could mix
 406 unlimited numbers of tracks, adjust fade, pan, and EQ, and hear the
 407 result instantly.   Amazingly this real time tweeking is still
 408 unavailable on most audio programs.
 409
 410    <p><b>BROADCAST 2000</b>
 411
 412    <p>But Broadcast 2.0 still didn't handle video and it wasn't very graceful
 413 at audio either.  In 1999 video broke into the story with Broadcast
 414 2000.  This iteration of the Broadcast series could do wonders with
 415 audio and offered a pretty good video feature set.  It could edit video
 416 files up to 64 terabytes.  It could do everything Broadcast 2.1 did
 417 with audio except now all effects for video and audio could be chained
 418 and performed on the fly, with instant feedback as a user tweeked
 419 parameters during playback.  Broadcast 2000 made it very easy to do a
 420 lot of processing and editing on video and audio that would otherwise
 421 involve many hours setting up command line sequences and writing to
 422 disk. For a time it seemed as if the original dream of immersive movie
 423 making for everyone regardless of income level had arrived.
 424
 425    <p><b>CINELERRA</b>
 426
 427    <p>Later on Broadcast 2000 began to come short.  Its audio and video was
 428 graceful if you knew how to use it efficiently, but quality issues and
 429 new user interface techniques were emerging.  Broadcast 2000 kept the
 430 audio interface from its ancestors, which didn't apply well to video.
 431 Users likewise were maturing.  No longer would it be sufficient to just
 432 edit video on a UNIX box.  Most users expected on UNIX the same thing
 433 they got in Win or Mac. In mid 2000 designs for a Broadcast 2000
 434 replacement were drafted.  The Broadcast name was officially retired
 435 from the series and the software would now be called Cinelerra.
 436 Cinelerra would allow users to configure certain effects in much less
 437 time than required with Broadcast 2000.  It would begin to emulate some
 438 of the features found in Win and Mac software while not attempting to
 439 become a clone.  It's interface would be designed for video from the
 440 ground up, while supplementing that with the Broadcast audio
 441 interface.  As always, quality improvements would happen.
 442
 443    <p><b>LINUX DERIVATIVES</b>
 444
 445    <p>Linux became more and more fragmented after corporations adopted it.
 446 Threading once worked the same on all derivatives.  Today there are more
 447 threading models than days of the week.  We try to focus on 1 of the
 448 most popular Linux derivatives at any moment.  The threading model is
 449 ported to that Linux derivative shortly before a release, but Linux
 450 derivatives quickly evolve to new threading models and everything
 451 breaks.
 452
 453    <p>Also, there is no consistent behaviour for sound and video drivers.  The
 454 situation with video capture has improved in that modern video sources
 455 can all be mounted like disk drives.  The audio capture drivers have
 456 been a bit more reliable.
 457
 458 <ul class="menu">
 459 <li><a accesskey="1" href="#ABOUT-THIS-MANUAL">ABOUT THIS MANUAL</a>
 460 </ul>
 461
 462 <div class="node">
 463 <a name="ABOUT-THIS-MANUAL"></a>
 464 <p><hr>
 465 Up:&nbsp;<a rel="up" accesskey="u" href="#ABOUT-CINELERRA">ABOUT CINELERRA</a>
 466
 467 </div>
 468
 469 <h3 class="section">2.1 ABOUT THIS MANUAL</h3>
 470
 471 <p>This is the original manual for Cinelerra.  This manual has been copied
 472 and translated into many languages on many websites in varying degrees
 473 of completeness.
 474
 475    <p>Organizing information in the easiest manner for users to find out what
 476 they need to know is sort of like cataloging the internet.  They've
 477 been trying to get it right for 30 years and will probably keep trying
 478 until the end of time.
 479
 480    <p>There a lot of fragments of documentation scattered throughout the
 481 internet about Cinelerra.  This document attempts to combine all the
 482 pieces of information in one piece.
 483
 484    <p>Like the operating system and compiler for a piece of software, the
 485 document writing format is the most important thing in choosing our
 486 document format.  We wanted a format which would be readable regardless
 487 of corporate whims and fads.  A piece of software which compiles on GCC
 488 and Linux will be usable as long as there are C compilers.  Documents
 489 written in Texinfo will be readable as long as there's a C compiler.
 490
 491    <p>After many years of searching for the perfect documentation format
 492 we've arrived at TexInfo.  This format can be converted to HTML,
 493 printed, automatically indexed, but most importantly is not bound to
 494 any commercial word processor.
 495
 496    <p>There are no screenshots in this manual.  Screenshots become obsolete
 497 quickly and as a result confuse the users.  What looks one way in a
 498 screenshot will always look different in the real program because the
 499 real program and the manual are always evolving, never perfectly
 500 synchronized.  It is true that manuals should have screenshots, but our
 501 objective in omitting screenshots is to keep the software costs minimal
 502 so you don't have to pay for it.  That includes additional labor to
 503 synchronize the manual with the software.
 504
 505    <p>In addition to telling you the basic editing features of Cinelerra this
 506 manual covers tricks that won't be described anywhere else.  We're
 507 going to try to come up with certain things you can do with Cinelerra
 508 that you wouldn't think of on your own.
 509
 510 <div class="node">
 511 <a name="INSTALLATION"></a>
 512 <p><hr>
 513 Next:&nbsp;<a rel="next" accesskey="n" href="#CONFIGURATION">CONFIGURATION</a>,
 514 Previous:&nbsp;<a rel="previous" accesskey="p" href="#ABOUT-CINELERRA">ABOUT CINELERRA</a>,
 515 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
 516
 517 </div>
 518
 519 <h2 class="chapter">3 INSTALLATION</h2>
 520
 521 <p>The Cinelerra package contains Cinelerra and most of the libraries
 522 needed to run it.  We try to include all the dependancies because of
 523 the difficulty in tracking down the right versions.  Also included are
 524 some utilities for handling files.  The following are the general
 525 contents of all Cinelerra packages.
 526
 527      <ul>
 528 <li>
 529 <b>Foreign language translations</b> - These go into /usr/share/locale.
 530
 531      <li>
 532 <b>Cinelerra executable</b> - This goes into /usr/bin
 533
 534      <li>
 535 <b>Cinelerra plugins</b> - These go into /usr/lib/cinelerra in 32 bit
 536 systems and /usr/lib64/cinelerra in 64 bit systems.
 537
 538      <li>
 539 <b>soundtest</b> - Utility for determining sound card buffer size.
 540
 541      <li>
 542 <b>mplexlo</b> - Multiplexing of MPEG elementary streams without standards
 543 conformance but more efficiently.
 544
 545      <li>
 546 <b>mpeg3cat</b> - Utility for reading an MPEG file from a certain standard
 547 and outputting it to stdout.
 548
 549      <li>
 550 <b>mpeg3toc, mpeg3cat, mpeg3dump</b> - Utilities/ for indexing and reading MPEG files.
 551
 552      <li>
 553 <b>mpeg3peek</b> - Utility for displaying the byte offset of a frame in an
 554 MPEG file.
 555
 556    </ul>
 557
 558 <ul class="menu">
 559 <li><a accesskey="1" href="#INSTALLING-AN-RPM">INSTALLING AN RPM</a>
 560 <li><a accesskey="2" href="#COMPILING-FROM-SCRATCH">COMPILING FROM SCRATCH</a>
 561 <li><a accesskey="3" href="#RUNNING-CINELERRA">RUNNING CINELERRA</a>
 562 </ul>
 563
 564 <div class="node">
 565 <a name="INSTALLING-AN-RPM"></a>
 566 <p><hr>
 567 Next:&nbsp;<a rel="next" accesskey="n" href="#COMPILING-FROM-SCRATCH">COMPILING FROM SCRATCH</a>,
 568 Up:&nbsp;<a rel="up" accesskey="u" href="#INSTALLATION">INSTALLATION</a>
 569
 570 </div>
 571
 572 <h3 class="section">3.1 INSTALLING AN RPM</h3>
 573
 574 <p>Cinelerra is easiest installed by downloading an RPM and running
 575
 576 <pre class="example">     rpm -U --force --nodeps hvirtual*.rpm
 577 </pre>
 578    <p>on a Fedora 4 system.
 579
 580    <p>On systems which don't support RPM look for a utility called
 581 <b>rpm2cpio</b>.  Download a Cinelerra RPM and from the /
 582 directory run
 583
 584 <pre class="example">     rpm2cpio hvirtual*.rpm | cpio -i --make-directories
 585 </pre>
 586    <p>This doesn't always work because there are many forks of the C library,
 587 each incompatible with the others.  This is the biggest reason to
 588 compile from scratch.
 589
 590 <div class="node">
 591 <a name="COMPILING-FROM-SCRATCH"></a>
 592 <p><hr>
 593 Next:&nbsp;<a rel="next" accesskey="n" href="#RUNNING-CINELERRA">RUNNING CINELERRA</a>,
 594 Previous:&nbsp;<a rel="previous" accesskey="p" href="#INSTALLING-AN-RPM">INSTALLING AN RPM</a>,
 595 Up:&nbsp;<a rel="up" accesskey="u" href="#INSTALLATION">INSTALLATION</a>
 596
 597 </div>
 598
 599 <h3 class="section">3.2 COMPILING FROM SCRATCH</h3>
 600
 601 <p>It should be noted that the compiler used in building Cinelerra
 602 binaries is the free GNU compiler and very conservative optimization
 603 flags.  Alternative optimization flags and compilers produce varying
 604 results.  Compiling the source is hard and there's no warranty if the
 605 source code fails to compile, but the method for compiling starts by
 606 downloading the source code and decompressing.
 607
 608    <p>The compilation is verified on a vanilla Fedora 4 installation,
 609 workstation mode.  Fedora doesn't install a lot of dependancies like
 610 <b>nasm</b> and <b>yasm</b>.  Yes, 3 assemblers are now required to assemble
 611 x86 code.  Compiling the source is hard and there's no warranty if the
 612 source code fails to compile, but the method for compiling starts by
 613 downloading the source code and decompressing.
 614
 615 <pre class="example">     tar jxf cinelerra*.tar.bz2
 616 </pre>
 617    <p>The compilation is verified on a Fedora 4 installation.  Fedora 4
 618 doesn't install a lot of the reqiured compilers.  Mainly <b>nasm</b> and
 619 <b>yasm</b>, 2 of the 3 assemblers.  These have to be installed manually
 620 for compilation to succeed.
 621
 622    <p>Enter the hvirtual directory
 623
 624 <pre class="example">     cd cinelerra
 625 </pre>
 626    <p>Then run
 627
 628 <pre class="example">     ./configure
 629 </pre>
 630    <p>This checks the build environment for the right tools and should give
 631 you an error if a tool is missing.  Once that succeeds run
 632
 633 <pre class="example">     make
 634 </pre>
 635    <p>The make procedure should run through all the directories and put
 636 binaries in the <b>i686</b> or <b>x86_64</b> directories.  When NFS was
 637 a lot faster, we compiled Alpha and i686 binaries in the same
 638 filesystem with the objects in different subdirectories, so all the
 639 binaries are still put in subdirectories.
 640
 641    <p>A lot of libraries are included to get the version numbers right.  Some
 642 of the libraries don't compile on SMP systems.  One solution is to
 643 disable SMP when rebooting and reenable it when compilation is
 644 finished.  Another solution is to rerun make over and over until it
 645 gets through the offending libraries.
 646
 647    <p>Once finished, make sure you are root and run
 648
 649 <pre class="example">     make install
 650 </pre>
 651    <p>to install the binaries.  If installation fails it means something
 652 failed to compile or you weren't root.  Run <b>make</b> again and watch
 653 for errors.
 654
 655    <p>Sometimes you'll want to run <b>make clean</b> if you're programming
 656 something or the system libraries change.  In this case, you'll
 657 probably need to run <b>configure</b> again because some libraries delete
 658 their configuration files in <b>make clean</b>.
 659
 660 <div class="node">
 661 <a name="RUNNING-CINELERRA"></a>
 662 <p><hr>
 663 Previous:&nbsp;<a rel="previous" accesskey="p" href="#COMPILING-FROM-SCRATCH">COMPILING FROM SCRATCH</a>,
 664 Up:&nbsp;<a rel="up" accesskey="u" href="#INSTALLATION">INSTALLATION</a>
 665
 666 </div>
 667
 668 <h3 class="section">3.3 RUNNING CINELERRA</h3>
 669
 670 <p>The simplest way to run Cinelerra is by running
 671
 672 <pre class="example">     /usr/bin/cinelerra
 673 </pre>
 674    <p>This command hides a much more capable command line interface.  Run
 675 <b>cinelerra -h</b> to get a listing of command line options.  The use of
 676 these options is described in several sections.
 677
 678    <p>For rendering from the command line See <a href="#RENDERING-FILES">RENDERING FILES</a>.
 679
 680 <div class="node">
 681 <a name="CONFIGURATION"></a>
 682 <p><hr>
 683 Next:&nbsp;<a rel="next" accesskey="n" href="#CREATING-A-NEW-PROJECT">CREATING A NEW PROJECT</a>,
 684 Previous:&nbsp;<a rel="previous" accesskey="p" href="#INSTALLATION">INSTALLATION</a>,
 685 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
 686
 687 </div>
 688
 689 <h2 class="chapter">4 CONFIGURATION</h2>
 690
 691 <p>Because of the variety of uses, Cinelerra cannot be run optimally
 692 without some intimate configuration for your specific needs. Very few
 693 parameters are adjustible at compile time.  Runtime configuration is
 694 the only option for most configuration because of the multitude of
 695 parameters.
 696
 697    <p>Here we discuss not only the configuration options but which of the
 698 different API's in Linux are supported.
 699
 700    <p>Go to <b>settings-&gt;preferences</b> and to see the options.
 701
 702 <ul class="menu">
 703 <li><a accesskey="1" href="#ENVIRONMENT-VARIABLES">ENVIRONMENT VARIABLES</a>:   These environment variables are recognized by Cinelerra
 704 <li><a accesskey="2" href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>:           Information about the audio drivers
 705 <li><a accesskey="3" href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>:           Information about the video drivers
 706 <li><a accesskey="4" href="#PLAYBACK">PLAYBACK</a>:                Configuring parameters related to playback.
 707 <li><a accesskey="5" href="#RECORDING">RECORDING</a>:               Configuring parameters related to recording.
 708 <li><a accesskey="6" href="#PERFORMANCE">PERFORMANCE</a>:             Configuring parameters related to how fast things go.
 709 <li><a accesskey="7" href="#INTERFACE">INTERFACE</a>:               Configuring the user interface.
 710 <li><a accesskey="8" href="#ABOUT">ABOUT</a>:                   Viewing information about the program.
 711 </ul>
 712
 713 <div class="node">
 714 <a name="ENVIRONMENT-VARIABLES"></a>
 715 <p><hr>
 716 Next:&nbsp;<a rel="next" accesskey="n" href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>,
 717 Up:&nbsp;<a rel="up" accesskey="u" href="#CONFIGURATION">CONFIGURATION</a>
 718
 719 </div>
 720
 721 <h3 class="section">4.1 ENVIRONMENT VARIABLES</h3>
 722
 723 <p>In UNIX derivatives, environment variables are global variables in the
 724 shell which all applications can read.  They are set with a command
 725 like <b>set VARIABLE=value</b>.  All the environment variables can be
 726 viewed with a command like <b>env</b>.  Cinelerra recognizes the following
 727 environment variables:
 728
 729      <ul>
 730 <li><b>LADSPA_PATH</b> - If you want to use LADSPA plugins, this must be
 731 defined: a colon separated list of directories to search for LADSPA
 732 plugins.  These are not native Cinelerra plugins.  See <a href="#LADSPA-EFFECTS">LADSPA EFFECTS</a>.
 733
 734    </ul>
 735
 736 <div class="node">
 737 <a name="AUDIO-DRIVERS"></a>
 738 <p><hr>
 739 Next:&nbsp;<a rel="next" accesskey="n" href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>,
 740 Previous:&nbsp;<a rel="previous" accesskey="p" href="#ENVIRONMENT-VARIABLES">ENVIRONMENT VARIABLES</a>,
 741 Up:&nbsp;<a rel="up" accesskey="u" href="#CONFIGURATION">CONFIGURATION</a>
 742
 743 </div>
 744
 745 <h3 class="section">4.2 AUDIO DRIVERS</h3>
 746
 747 <p>The audio drivers are used for both recording and playback to get data
 748 to and from the hardware.  Since the same drivers are used for both
 749 recording and playback, their functionality is described here in a
 750 separate section.
 751
 752 <ul class="menu">
 753 <li><a accesskey="1" href="#COMMON-SOUND-DRIVER-ATTRIBUTES">COMMON SOUND DRIVER ATTRIBUTES</a>:  Attributes used for more than one sound driver.
 754 <li><a accesskey="2" href="#OSS">OSS</a>:  Notes about the OSS driver
 755 <li><a accesskey="3" href="#OSS-Envy24">OSS Envy24</a>:  Notes about the OSS driver for the Envy24 chip
 756 <li><a accesskey="4" href="#ALSA">ALSA</a>:  Notes about the ALSA driver
 757 <li><a accesskey="5" href="#ESOUND">ESOUND</a>:  Notes about the ESound driver
 758 <li><a accesskey="6" href="#RAW-1394">RAW 1394</a>:  Notes about the Raw1394 driver
 759 <li><a accesskey="7" href="#DV-1394">DV 1394</a>:  Notes about the DV1394 driver
 760 <li><a accesskey="8" href="#IEC-61883">IEC 61883</a>:  Notes about the IEC 61883 driver
 761 </ul>
 762
 763 <div class="node">
 764 <a name="COMMON-SOUND-DRIVER-ATTRIBUTES"></a>
 765 <p><hr>
 766 Next:&nbsp;<a rel="next" accesskey="n" href="#OSS">OSS</a>,
 767 Up:&nbsp;<a rel="up" accesskey="u" href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>
 768
 769 </div>
 770
 771 <h4 class="subsection">4.2.1 COMMON SOUND DRIVER ATTRIBUTES</h4>
 772
 773      <ul>
 774 <li>DEVICE PATH
 775
 776      <p>Usually a file in the <b>/dev/</b> directory which controls the
 777 device.
 778
 779      <li>
 780 BITS
 781
 782      <p>The number of bits of precision Cinelerra should set the device for.
 783 This sometimes has a figuritive meaning.  Some sound drivers need to be
 784 set to 32 bits to perform 24 bit playback and won't play anything when
 785 set to 24 bits.  Some sound drivers need to be set to 24 bits for 24
 786 bit playback.
 787
 788 </ul>
 789
 790 <div class="node">
 791 <a name="OSS"></a>
 792 <p><hr>
 793 Next:&nbsp;<a rel="next" accesskey="n" href="#OSS-Envy24">OSS Envy24</a>,
 794 Previous:&nbsp;<a rel="previous" accesskey="p" href="#COMMON-SOUND-DRIVER-ATTRIBUTES">COMMON SOUND DRIVER ATTRIBUTES</a>,
 795 Up:&nbsp;<a rel="up" accesskey="u" href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>
 796
 797 </div>
 798
 799 <h4 class="subsection">4.2.2 OSS</h4>
 800
 801 <p>This was the first Linux sound driver.  It had an open source
 802 implementation and a commercial implementation with more sound cards
 803 supported.  It was the standard sound driver up to linux 2.4.  It still
 804 is the only sound driver which an i386 binary can use when running on
 805 an x86_64 system.
 806
 807 <div class="node">
 808 <a name="OSS-Envy24"></a>
 809 <p><hr>
 810 Next:&nbsp;<a rel="next" accesskey="n" href="#ALSA">ALSA</a>,
 811 Previous:&nbsp;<a rel="previous" accesskey="p" href="#OSS">OSS</a>,
 812 Up:&nbsp;<a rel="up" accesskey="u" href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>
 813
 814 </div>
 815
 816 <h4 class="subsection">4.2.3 OSS Envy24</h4>
 817
 818 <p>The commercial version of OSS had a variant for 24 bit 96 Khz
 819 soundcards.  This variant required significant changes to the way the
 820 sound drivers were used, which is what the OSS Envy24 variant is for.
 821
 822 <div class="node">
 823 <a name="ALSA"></a>
 824 <p><hr>
 825 Next:&nbsp;<a rel="next" accesskey="n" href="#ESOUND">ESOUND</a>,
 826 Previous:&nbsp;<a rel="previous" accesskey="p" href="#OSS-Envy24">OSS Envy24</a>,
 827 Up:&nbsp;<a rel="up" accesskey="u" href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>
 828
 829 </div>
 830
 831 <h4 class="subsection">4.2.4 ALSA</h4>
 832
 833 <p>ALSA is the most common sound driver in Linux 2.6.  It supports the
 834 most sound cards now.  It takes advantage of low latency features in
 835 Linux 2.6 to get better performance than OSS had in 2.4 but roughly the
 836 same performance that OSS had in 2.0.  Unfortunately ALSA is constantly
 837 changing.  A program which works with it one day may not the next day.
 838 New wrappers are being developed on top of ALSA at such a pace, we plan
 839 to support them at regular intervals, not at every new release of a new
 840 wrapper.
 841
 842    <p>ALSA is no longer portable between i386 and x86_64.  If an i386 binary
 843 tries to play back on an x86_64 kernel it'll crash.  For this scenario,
 844 use OSS.
 845
 846 <div class="node">
 847 <a name="ESOUND"></a>
 848 <p><hr>
 849 Next:&nbsp;<a rel="next" accesskey="n" href="#RAW-1394">RAW 1394</a>,
 850 Previous:&nbsp;<a rel="previous" accesskey="p" href="#ALSA">ALSA</a>,
 851 Up:&nbsp;<a rel="up" accesskey="u" href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>
 852
 853 </div>
 854
 855 <h4 class="subsection">4.2.5 ESOUND</h4>
 856
 857 <p>ESOUND was a sound server that sat on top of OSS.  It was written for a
 858 window manager called Enlightenment.  It supported a limited number of
 859 bits and had high latency compared to modern times but multiplexed
 860 multiple audio sources.  It's unknown whether it still works.
 861
 862 <div class="node">
 863 <a name="RAW-1394"></a>
 864 <p><hr>
 865 Next:&nbsp;<a rel="next" accesskey="n" href="#DV-1394">DV 1394</a>,
 866 Previous:&nbsp;<a rel="previous" accesskey="p" href="#ESOUND">ESOUND</a>,
 867 Up:&nbsp;<a rel="up" accesskey="u" href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>
 868
 869 </div>
 870
 871 <h4 class="subsection">4.2.6 RAW 1394</h4>
 872
 873 <p>The first interface between linux software and firewire camcorders.
 874 This was the least reliable way to play audio to a camcorder.  It
 875 consisted of a library on top of the kernel commands.
 876
 877 <div class="node">
 878 <a name="DV-1394"></a>
 879 <p><hr>
 880 Next:&nbsp;<a rel="next" accesskey="n" href="#IEC-61883">IEC 61883</a>,
 881 Previous:&nbsp;<a rel="previous" accesskey="p" href="#RAW-1394">RAW 1394</a>,
 882 Up:&nbsp;<a rel="up" accesskey="u" href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>
 883
 884 </div>
 885
 886 <h4 class="subsection">4.2.7 DV 1394</h4>
 887
 888 <p>The second rewrite of DV camcorder support in Linux.  This was the most
 889 reliable way to play audio to a camcorder.  This consisted of direct
 890 kernel commands.
 891
 892 <div class="node">
 893 <a name="IEC-61883"></a>
 894 <p><hr>
 895 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DV-1394">DV 1394</a>,
 896 Up:&nbsp;<a rel="up" accesskey="u" href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>
 897
 898 </div>
 899
 900 <h4 class="subsection">4.2.8 IEC 61883</h4>
 901
 902 <p>The third rewrite of DV camcorder support in Linux.  This is a library
 903 on top of RAW 1394 which is a library on top of the kernel commands.
 904 It's less reliable than DV 1394 but more reliable than RAW 1394.  The
 905 next rewrite ought to fix that.
 906
 907 <div class="node">
 908 <a name="VIDEO-DRIVERS"></a>
 909 <p><hr>
 910 Next:&nbsp;<a rel="next" accesskey="n" href="#PLAYBACK">PLAYBACK</a>,
 911 Previous:&nbsp;<a rel="previous" accesskey="p" href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>,
 912 Up:&nbsp;<a rel="up" accesskey="u" href="#CONFIGURATION">CONFIGURATION</a>
 913
 914 </div>
 915
 916 <h3 class="section">4.3 VIDEO DRIVERS</h3>
 917
 918 <p>The audio drivers are used for both recording and playback to get data
 919 to and from the hardware.  Since the same drivers are used for both
 920 recording and playback, their functionality is described here in a
 921 separate section.
 922
 923 <ul class="menu">
 924 <li><a accesskey="1" href="#COMMON-VIDEO-DRIVER-ATTRIBUTES">COMMON VIDEO DRIVER ATTRIBUTES</a>:  Parameters used by more than one driver.
 925 <li><a accesskey="2" href="#X11">X11</a>
 926 <li><a accesskey="3" href="#X11_002dXV">X11-XV</a>
 927 <li><a accesskey="4" href="#X11_002dOPENGL">X11-OPENGL</a>
 928 <li><a accesskey="5" href="#BUZ">BUZ</a>
 929 <li><a accesskey="6" href="#RAW-1394-VIDEO-PLAYBACK">RAW 1394 VIDEO PLAYBACK</a>
 930 <li><a accesskey="7" href="#DV-1394-VIDEO-PLAYBACK">DV 1394 VIDEO PLAYBACK</a>
 931 <li><a accesskey="8" href="#IEC-61883-VIDEO-PLAYBACK">IEC 61883 VIDEO PLAYBACK</a>
 932 </ul>
 933
 934 <div class="node">
 935 <a name="COMMON-VIDEO-DRIVER-ATTRIBUTES"></a>
 936 <p><hr>
 937 Next:&nbsp;<a rel="next" accesskey="n" href="#X11">X11</a>,
 938 Up:&nbsp;<a rel="up" accesskey="u" href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>
 939
 940 </div>
 941
 942 <h4 class="subsection">4.3.1 COMMON VIDEO DRIVER ATTRIBUTES</h4>
 943
 944      <ul>
 945 <li>
 946 DISPLAY
 947
 948      <p>The is intended for dual monitor
 949 displays.  Depending on the value of Display, the Compositor window
 950 will appear on a different monitor from the rest of the windows.
 951
 952      <li>
 953 DEVICE PATH
 954
 955      <p>Usually a file in the <b>/dev/</b> directory
 956 which controls the device.
 957
 958      <li>
 959 SWAP FIELDS
 960
 961      <p>Make the even lines odd and the odd lines even
 962 when sending to the device.  On an NTSC or 1080i monitor the fields may
 963 need to be swapped to prevent jittery motion.
 964
 965      <li>
 966 OUTPUT CHANNEL
 967
 968      <p>Devices with multiple outputs may need a
 969 specific connector to send video on.
 970
 971      <li>
 972 PORT
 973
 974      <p>The IEEE1394 standard specifies something known as the
 975 <b>port</b>.  This is probably the firewire card number in the system
 976 to use.
 977
 978      <li>
 979 CHANNEL
 980
 981      <p>The IEEE1394 standard specifies something known as the
 982 <b>channel</b>.  For DV cameras it's always <b>63</b>.
 983
 984 </ul>
 985
 986 <div class="node">
 987 <a name="X11"></a>
 988 <p><hr>
 989 Next:&nbsp;<a rel="next" accesskey="n" href="#X11_002dXV">X11-XV</a>,
 990 Previous:&nbsp;<a rel="previous" accesskey="p" href="#COMMON-VIDEO-DRIVER-ATTRIBUTES">COMMON VIDEO DRIVER ATTRIBUTES</a>,
 991 Up:&nbsp;<a rel="up" accesskey="u" href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>
 992
 993 </div>
 994
 995 <h4 class="subsection">4.3.2 X11</h4>
 996
 997 <p>This was the first method of video playback on any UNIX system, valid
 998 all the way until 1999.  It just writes the RGB triplet for each pixel
 999 directly to the window.  It's the slowest playback method.  It's still
1000 useful as a fallback when graphics hardware can't handle very large
1001 frames.
1002
1003 <div class="node">
1004 <a name="X11-XV"></a>
1005 <a name="X11_002dXV"></a>
1006 <p><hr>
1007 Next:&nbsp;<a rel="next" accesskey="n" href="#X11_002dOPENGL">X11-OPENGL</a>,
1008 Previous:&nbsp;<a rel="previous" accesskey="p" href="#X11">X11</a>,
1009 Up:&nbsp;<a rel="up" accesskey="u" href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>
1010
1011 </div>
1012
1013 <h4 class="subsection">4.3.3 X11-XV</h4>
1014
1015 <p>This was the second big method of video playback in UNIX starting in
1016 1999.  It converts YUV to RGB in hardware with scaling.  It's the
1017 preferred playback method but can't handle large frame sizes.  The
1018 maximum video size for XV is usually 1920x1080.
1019
1020 <div class="node">
1021 <a name="X11-OPENGL"></a>
1022 <a name="X11_002dOPENGL"></a>
1023 <p><hr>
1024 Next:&nbsp;<a rel="next" accesskey="n" href="#BUZ">BUZ</a>,
1025 Previous:&nbsp;<a rel="previous" accesskey="p" href="#X11_002dXV">X11-XV</a>,
1026 Up:&nbsp;<a rel="up" accesskey="u" href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>
1027
1028 </div>
1029
1030 <h4 class="subsection">4.3.4 X11-OPENGL</h4>
1031
1032 <p>The most powerful video playback method is OpenGL.  With this driver,
1033 most effects are done in hardware.  OpenGL allows video sizes up to the
1034 maximum texture size, which is usually larger than what XV supports,
1035 depending on the graphics driver.
1036
1037    <p>OpenGL doesn't affect rendering.  It just accelerates playback.  OpenGL
1038 relies on PBuffers and shaders to do video rendering.  The graphics
1039 driver must support OpenGL 2 and Cinelerra needs to be explicitely
1040 compiled with OpenGL 2 support.  This requires compiling it on a system
1041 with the OpenGL 2 headers.
1042
1043    <p>PBuffers are known to be fickle.  If the graphics card doesn't have
1044 enough memory or doesn't have the right visuals, PBuffers won't work.
1045 Try seeking several frames or restarting Cinelerra if OpenGL doesn't
1046 work.
1047
1048    <p>Because of OpenGL limitations, X11-OpenGL processes everything in 8 bit
1049 colormodels, although the difference between YUV and RGB is retained.
1050
1051    <p>The <b>scaling equation</b> in Preferences is ignored by OpenGL.  OpenGL
1052 always uses linear scaling.
1053
1054    <p>Project and track sizes need to be multiples of 4 for OpenGL to work.
1055
1056    <p>To get the most acceleration, OpenGL-enabled effects must be placed
1057 after software-only effects.  All rendering before the last
1058 software-only effect is done in software.  The core Cinelerra
1059 operations like camera and projector are of course OpenGL.
1060
1061 <div class="node">
1062 <a name="BUZ"></a>
1063 <p><hr>
1064 Next:&nbsp;<a rel="next" accesskey="n" href="#RAW-1394-VIDEO-PLAYBACK">RAW 1394 VIDEO PLAYBACK</a>,
1065 Previous:&nbsp;<a rel="previous" accesskey="p" href="#X11_002dOPENGL">X11-OPENGL</a>,
1066 Up:&nbsp;<a rel="up" accesskey="u" href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>
1067
1068 </div>
1069
1070 <h4 class="subsection">4.3.5 BUZ</h4>
1071
1072 <p>This is a method for playing motion JPEG-A files directly to a
1073 composite analog signal.  It uses a popular hack of the Video4Linux 1
1074 driver from 2000 to decompress JPEG in hardware.  Sadly, even though
1075 analog output is largely obsolete, newer drivers have replaced BUZ.
1076
1077 <div class="node">
1078 <a name="RAW-1394-VIDEO-PLAYBACK"></a>
1079 <p><hr>
1080 Next:&nbsp;<a rel="next" accesskey="n" href="#DV-1394-VIDEO-PLAYBACK">DV 1394 VIDEO PLAYBACK</a>,
1081 Previous:&nbsp;<a rel="previous" accesskey="p" href="#BUZ">BUZ</a>,
1082 Up:&nbsp;<a rel="up" accesskey="u" href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>
1083
1084 </div>
1085
1086 <h4 class="subsection">4.3.6 RAW 1394 VIDEO PLAYBACK</h4>
1087
1088 <p>The first interface between linux software and firewire camcorders.
1089 This was the least reliable way to play video to a camcorder.  It
1090 consisted of a library on top of the kernel commands.
1091
1092 <div class="node">
1093 <a name="DV-1394-VIDEO-PLAYBACK"></a>
1094 <p><hr>
1095 Next:&nbsp;<a rel="next" accesskey="n" href="#IEC-61883-VIDEO-PLAYBACK">IEC 61883 VIDEO PLAYBACK</a>,
1096 Previous:&nbsp;<a rel="previous" accesskey="p" href="#RAW-1394-VIDEO-PLAYBACK">RAW 1394 VIDEO PLAYBACK</a>,
1097 Up:&nbsp;<a rel="up" accesskey="u" href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>
1098
1099 </div>
1100
1101 <h4 class="subsection">4.3.7 DV 1394 VIDEO PLAYBACK</h4>
1102
1103 <p>The second rewrite of DV camcorder support in Linux.  This was the most
1104 reliable way to play video to a camcorder.  This consisted of direct
1105 kernel commands.
1106
1107 <div class="node">
1108 <a name="IEC-61883-VIDEO-PLAYBACK"></a>
1109 <p><hr>
1110 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DV-1394-VIDEO-PLAYBACK">DV 1394 VIDEO PLAYBACK</a>,
1111 Up:&nbsp;<a rel="up" accesskey="u" href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>
1112
1113 </div>
1114
1115 <h4 class="subsection">4.3.8 IEC 61883 VIDEO PLAYBACK</h4>
1116
1117 <p>The third rewrite of DV camcorder support in Linux.  This is a library
1118 on top of RAW 1394 which is a library on top of the kernel commands.
1119 It's less reliable than DV 1394 but more reliable than RAW 1394.  The
1120 next rewrite ought to fix that.
1121
1122 <div class="node">
1123 <a name="PLAYBACK"></a>
1124 <p><hr>
1125 Next:&nbsp;<a rel="next" accesskey="n" href="#RECORDING">RECORDING</a>,
1126 Previous:&nbsp;<a rel="previous" accesskey="p" href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>,
1127 Up:&nbsp;<a rel="up" accesskey="u" href="#CONFIGURATION">CONFIGURATION</a>
1128
1129 </div>
1130
1131 <h3 class="section">4.4 PLAYBACK</h3>
1132
1133 <ul class="menu">
1134 <li><a accesskey="1" href="#AUDIO-OUT">AUDIO OUT</a>
1135 <li><a accesskey="2" href="#VIDEO-OUT">VIDEO OUT</a>
1136 </ul>
1137
1138 <div class="node">
1139 <a name="AUDIO-OUT"></a>
1140 <p><hr>
1141 Next:&nbsp;<a rel="next" accesskey="n" href="#VIDEO-OUT">VIDEO OUT</a>,
1142 Up:&nbsp;<a rel="up" accesskey="u" href="#PLAYBACK">PLAYBACK</a>
1143
1144 </div>
1145
1146 <h4 class="subsection">4.4.1 AUDIO OUT</h4>
1147
1148 <p>These determine what happens when you play sound from the timeline.
1149
1150      <ul>
1151 <li>SAMPLES TO SEND TO CONSOLE:
1152
1153      <p>For playing audio, small fragments of sound are read from disk and
1154 processed in a virtual console sequentially.  A larger value here
1155 causes more latency when you change mixing parameters but gives more
1156 reliable playback.
1157
1158      <p>Some sound drivers don't allow changing of the console fragment so
1159 latency is unchanged no matter what this value is.
1160
1161      <p>A good way of ensuring high quality playback was to read bigger
1162 fragments from the disk and break them into smaller fragments for the
1163 soundcard.  That changed when the virtual console moved from the push
1164 model to the pull model.  Since different stages of the rendering
1165 pipeline can change the rate of the incoming data, it would now be real
1166 hard to disconnect size of the console fragments from the size of the
1167 fragments read from disk.
1168
1169      <li>
1170 AUDIO OFFSET:
1171
1172      <p>The ability to tell the exact playback position on Linux sound drivers
1173 is pretty bad if it's provided at all.  Since this information is
1174 required for proper video synchronization, it has to be accurate.  The
1175 <b>AUDIO OFFSET</b> allows users to adjust the position returned by the
1176 sound driver to reflect reality.  The audio offset doesn't affect the
1177 audio playback or rendering at all.  It merely changes the
1178 synchronization of video playback.
1179
1180      <p>The easiest way to set the audio offset is to create a timeline with 1
1181 video track and one audio track.  Expand the audio track and center the
1182 audio pan.  The frame rate should be something over 24fps and the
1183 sampling rate should be over 32000.  The frame size should be small
1184 enough for your computer to render it at the full framerate.  Highlight
1185 a region of the timeline starting at 10 seconds and ending at 20
1186 seconds.  Drop a <b>gradient</b> effect on the video track and configure
1187 it to be clearly visible.  Drop a <b>synthesizer</b> effect on the audio
1188 and configure it to be clearly audible.
1189
1190      <p>Play the timeline from 0 and watch to see if the gradient effect starts
1191 exactly when the audio starts.  If it doesn't, expand the audio track
1192 and adjust the nudge.  If the audio starts ahead of the video, decrease
1193 the nudge value.  If the audio starts after the video, increase the
1194 nudge value.  Once the tracks play back synchronized, copy the nudge
1195 value to the <b>AUDIO OFFSET</b> value in preferences.
1196
1197      <p><b>Note:</b> if you change sound drivers or you change the value of <b>USE
1198 SOFTWARE FOR POSITIONING INFORMATION</b>, you'll need to change the audio
1199 offset because different sound drivers are unequally inaccurate.
1200
1201      <li>
1202 VIEW FOLLOWS PLAYBACK
1203
1204      <p>Causes the timeline window to scroll when the playback cursor moves.
1205 This can bog down the X Server or cause the timeline window to lock up
1206 for long periods of time while drawing the assetse.
1207
1208      <li>USE SOFTWARE FOR POSITIONING INFORMATION
1209
1210      <p>Most soundcards and sound drivers don't give reliable information on
1211 the number of samples the card has played. When playing video you need
1212 this information for synchronization. This option causes the sound
1213 driver to be ignored and a software timer to be used for
1214 synchronization.
1215
1216      <li>AUDIO PLAYBACK IN REALTIME:
1217
1218      <p>Back in the days when 150Mhz was the maximum, this allowed
1219 uninterrupted playback on heavy loads.  It forces the audio playback to
1220 the highest priority in the kernel.  Today it's most useful for
1221 achieving very low latency between console tweeks and soundcard
1222 output.  You must be root to get realtime priority.
1223
1224      <li>AUDIO DRIVER
1225
1226      <p>There are many sound drivers for Linux.  This allows selecting one
1227 sound driver and setting parameters specific to it.  The sound drivers
1228 and their parameters are described in the sound driver section.
1229 See <a href="#AUDIO-DRIVERS">AUDIO DRIVERS</a>.
1230
1231    </ul>
1232
1233 <div class="node">
1234 <a name="VIDEO-OUT"></a>
1235 <p><hr>
1236 Previous:&nbsp;<a rel="previous" accesskey="p" href="#AUDIO-OUT">AUDIO OUT</a>,
1237 Up:&nbsp;<a rel="up" accesskey="u" href="#PLAYBACK">PLAYBACK</a>
1238
1239 </div>
1240
1241 <h4 class="subsection">4.4.2 VIDEO OUT</h4>
1242
1243 <p>These determine how video gets from the timeline to your eyes.
1244
1245      <ul>
1246 <li>PLAY EVERY FRAME
1247
1248      <p>Causes every frame of video to be displayed even if it means falling
1249 behind the audio.  This should always be on unless you use mostly
1250 uncompressed codecs.  Most compressed codecs don't support frame
1251 dropping anymore.
1252
1253      <li>
1254 FRAMERATE ACHIEVED
1255
1256      <p>The number of frames per second being displayed during playback.  This
1257 is only updated during playback.
1258
1259      <li>DECODE FRAMES ASYNCHRONOUSLY
1260
1261      <p>If you have lots of memory and more than one CPU, this option can
1262 improve playback performance by decoding video on one CPU as fast as
1263 possible while dedicating other CPU to displaying video only.  It
1264 assumes all playback operations are forward and no frames are dropped.
1265 Operations involving reverse playback or frame dropping are negatively
1266 impacted.
1267
1268      <p>Since this option requires enourmous amounts of memory, it may crash if
1269 the input frames are very large.
1270
1271      <li>
1272 SCALING EQUATION
1273
1274      <p>When video playback involves any kind of scaling or translation, this
1275 algorithm is used.  This doesn't affect 1:1 playback.
1276
1277           <ul>
1278 <li>NEAREST NEIGHBOR ENLARGE AND REDUCE
1279
1280           <p>lowest but fastest
1281 quality.  Produces jagged edges and uneven motion.
1282
1283           <li>
1284 BICUBIC ENLARGE AND BILINEAR REDUCE
1285
1286           <p>highest but slowest
1287 quality.  For enlarging a bicubic interpolation is used, which blurs
1288 slightly but doesn't reveal stair steps.  For reduction a bilinear
1289 interpolation is used, which produces very sharp images and reduces
1290 noise.  The bilinear reduced images can be sharpened with a sharpen
1291 effect with less noise than a normal sized image.
1292
1293           <li>
1294 BILINEAR ENLARGE AND BILINEAR REDUCE
1295
1296           <p>when slight enlargement
1297 is needed a bilinear enlargement looks better than a bicubic
1298 enlargement.
1299
1300      </ul>
1301
1302      <li>
1303 PRELOAD BUFFER FOR QUICKTIME
1304
1305      <p>The Quicktime/AVI decoder can handle DVD sources better when this is
1306 around 10000000.  This reduces the amount of seeking required.
1307 Unfortunately when reading high bitrate sources from a hard drive, this
1308 tends to slow it down.  For normal use this should be 0.
1309
1310      <li>
1311 DVD SUBTITLE TO DISPLAY
1312
1313      <p>DVD IFO files usually contain subtitle tracks.  These must be decoded
1314 with by the MPEG decoder.  Select <b>Enable subtitles</b> to enable
1315 subtitle decoding.  There are usually multiple subtitle tracks starting
1316 from 0.  The subtitle track to be decoded for all MPEG streams goes in
1317 the DVD subtitlee to display text box.  Go to the asset corresponding
1318 to the MPEG file in the Resources window and right click.  Click on
1319 Info.  The number of subtitle tracks is given at the bottom.
1320
1321      <li>
1322 INTERPOLATE CR2 IMAGES
1323
1324      <p>Enables interpolation of CR2 images.  This is required since the raw
1325 image in a CR2 file is a bayer pattern.  The interpolation uses dcraw's
1326 built-in interpolation and is very slow.  This operation can be
1327 disabled and the <b>Interpolate Pixels</b> effect used instead for fast
1328 previewing.
1329
1330      <li>
1331 WHITE BALANCE CR2 IMAGES
1332
1333      <p>This enables white balancing for CR2 images if interpolation is also
1334 enabled.  It uses the camera's matrix which is contained in the CR2
1335 file.  White balancing is not performed if interpolation is not
1336 performed because white balancing needs a blending of all 3 primary
1337 colors.
1338
1339      <p>Disabling white balancing is useful for operations involving dark frame
1340 subtraction.  The dark frame and the long exposure need to have the
1341 same color matrix.
1342
1343      <p>If you disable <b>Interpolate CR2 Images</b> and use the <b>Interpolate
1344 Pixels</b> effect, be aware the <b>Interpolate Pixels</b> effect always does
1345 both interpolation and white balancing using the camera's matrix,
1346 regardless of the settings in Preferences.  Dark frame subtraction
1347 needs to be performed before <b>Interpolate Pixels</b>.
1348
1349      <li>
1350
1351      <p>VIDEO DRIVER
1352
1353      <p>Normally video on the timeline goes to the compositor window during
1354 continuous playback and when the insertion point is repositioned.
1355 Instead of sending video to the Compositor window the video driver can
1356 be set to send video to another output device during continuous
1357 playback.  This doesn't affect where video goes when the insertion
1358 point is repositioned, however.
1359
1360      <p>The video drivers and their parameters are described in the video
1361 driver section.  See <a href="#VIDEO-DRIVERS">VIDEO DRIVERS</a>.
1362
1363    </ul>
1364
1365 <div class="node">
1366 <a name="RECORDING"></a>
1367 <p><hr>
1368 Next:&nbsp;<a rel="next" accesskey="n" href="#PERFORMANCE">PERFORMANCE</a>,
1369 Previous:&nbsp;<a rel="previous" accesskey="p" href="#PLAYBACK">PLAYBACK</a>,
1370 Up:&nbsp;<a rel="up" accesskey="u" href="#CONFIGURATION">CONFIGURATION</a>
1371
1372 </div>
1373
1374 <h3 class="section">4.5 RECORDING</h3>
1375
1376 <ul class="menu">
1377 <li><a accesskey="1" href="#FILE-FORMAT">FILE FORMAT</a>
1378 <li><a accesskey="2" href="#AUDIO-IN">AUDIO IN</a>
1379 <li><a accesskey="3" href="#VIDEO-IN">VIDEO IN</a>
1380 </ul>
1381
1382 <p>The parameters here affect what happens when you go to
1383 <b>File-&gt;Record...</b>.  The intention was to make <b>File-&gt;Record...</b> go
1384 as fast as possible into the record monitoring window, without a
1385 lengthy dialog to configure the file format.  Instead the file format
1386 for recording is set here and it is applied to all recordings.  Also
1387 set here is the hardware for recording, since the hardware determines
1388 the supported file format in most cases.
1389
1390 <div class="node">
1391 <a name="FILE-FORMAT"></a>
1392 <p><hr>
1393 Next:&nbsp;<a rel="next" accesskey="n" href="#AUDIO-IN">AUDIO IN</a>,
1394 Up:&nbsp;<a rel="up" accesskey="u" href="#RECORDING">RECORDING</a>
1395
1396 </div>
1397
1398 <h4 class="subsection">4.5.1 FILE FORMAT</h4>
1399
1400 <p>This determines the output file format for recordings.  It depends
1401 heavily on the type of driver used.  The interface is the same as the
1402 rendering interface.  The <b>Record audio tracks</b> toggle must be
1403 enabled to record audio.  The <b>Record video tracks</b> toggle must be
1404 enabled to record video.  The wrench button left of each toggle opens a
1405 configuration dialog to set the codec corresponding to audio and
1406 video.  The audio and video is wrapped in a wrapper defined by the
1407 <b>File Format</b> menu.  Different wrappers may record audio only, video
1408 only, or both.
1409
1410    <p>Some video drivers can only record to a certain wrapper.  DV, for
1411 example, can only record to Quicktime with DV as the video compression.
1412 If the video driver is changed, the file format may be updated to give
1413 the supported output.  If you change the file format to an unsupported
1414 format, it may not work with the video driver.
1415
1416 <div class="node">
1417 <a name="AUDIO-IN"></a>
1418 <p><hr>
1419 Next:&nbsp;<a rel="next" accesskey="n" href="#VIDEO-IN">VIDEO IN</a>,
1420 Previous:&nbsp;<a rel="previous" accesskey="p" href="#FILE-FORMAT">FILE FORMAT</a>,
1421 Up:&nbsp;<a rel="up" accesskey="u" href="#RECORDING">RECORDING</a>
1422
1423 </div>
1424
1425 <h4 class="subsection">4.5.2 AUDIO IN</h4>
1426
1427 <p>These determine what happens when you record audio.
1428
1429      <ul>
1430 <li>
1431 RECORD DRIVER
1432
1433      <p>This is used for recording audio in the Record window.  It may be
1434 shared with the Record Driver for video if the audio and video are
1435 wrapped in the same stream.  It takes variable parameters depending on
1436 the driver.  The parameters have the same meaning as they do for
1437 playback.
1438
1439           <ul>
1440 <li>
1441 DEVICE PATH
1442
1443           <p>Usually a file in the <b>/dev/</b> directory which controls the
1444 device.
1445
1446           <li>
1447 BITS
1448
1449           <p>The number of bits of precision Cinelerra should set the device for.
1450 This sometimes has a figuritive meaning.  Some sound drivers need to be
1451 set to 32 bits to perform 24 bit recording and won't record anything
1452 when set to 24 bits.  Some sound drivers need to be set to 24 bits for
1453 24 bit recording.
1454
1455      </ul>
1456
1457      <li>
1458 SAMPLES TO WRITE AT A TIME
1459
1460      <p>Audio is first read in small fragments from the device.  Many small
1461 fragments are combined into a large fragment before writing to disk.
1462 The disk writing process is done in a different thread.  The value here
1463 determines how large the combination of fragments is for each disk
1464 write.
1465
1466      <li>
1467 SAMPLE RATE FOR RECORDING
1468
1469      <p>Regardless of what the project settings are.  This is the sample rate
1470 used for recording.  This should be the highest the audio device
1471 supports.
1472
1473    </ul>
1474
1475 <div class="node">
1476 <a name="VIDEO-IN"></a>
1477 <p><hr>
1478 Previous:&nbsp;<a rel="previous" accesskey="p" href="#AUDIO-IN">AUDIO IN</a>,
1479 Up:&nbsp;<a rel="up" accesskey="u" href="#RECORDING">RECORDING</a>
1480
1481 </div>
1482
1483 <h4 class="subsection">4.5.3 VIDEO IN</h4>
1484
1485 <p>These determine what happens when you record video.
1486
1487      <ul>
1488 <li>
1489 RECORD DRIVER
1490
1491      <p>This is used for recording video in the Record window.  It may be
1492 shared with the Record Driver for audio if the audio and video are
1493 wrapped in the same stream.  It takes variable parameters depending on
1494 the driver.  The parameters have the same meaning as they do for
1495 playback.
1496
1497      <li>
1498 FRAMES TO RECORD TO DISK AT A TIME
1499
1500      <p>Frames are recorded in a pipeline.  First frames are buffered in the
1501 device.  Then they're read into a larger buffer for writing to disk.
1502 The disk writing is done in a different thread as the device reading.
1503 For certain codecs the disk writing uses multiple processors.  This
1504 value determines how many frames are written to disk at a time.
1505
1506      <li>
1507 FRAMES TO BUFFER IN DEVICE
1508
1509      <p>The number of frames to store in the device before reading.  This
1510 determines how much latency there can be in the system before frames
1511 are dropped.
1512
1513      <li>USE SOFTWARE FOR POSITIONING INFORMATION
1514
1515      <p>Video uses audio for
1516
1517      <p>synchronization but most soundcards don't give accurate position
1518 information.  This calculates an estimation of audio position in
1519 software instead of the hardware for synchronization.
1520
1521      <li>
1522 SYNC DRIVES AUTOMATICALLY
1523
1524      <p>For high bitrate recording the drives may be fast enough to store the
1525 data but Linux may wait several minutes and stall as it writes several
1526 minutes of data at a time.  This forces Linux to flush its buffers
1527 every second instead of every few minutes and produce slightly better
1528 realtime behavior.
1529
1530      <li>
1531 SIZE OF CAPTURED FRAME
1532
1533      <p>This is the size of the frames recorded.  It is independant of the
1534 project frame size because most video devices only record a fixed frame
1535 size.  If the frame size given here isn't supported by the device it
1536 might crash Cinelerra.
1537
1538      <li>FRAME RATE FOR RECORDING
1539
1540      <p>The frame rate recorded is different from the project settings.  This
1541 sets the recorded frame rate.
1542
1543    </ul>
1544
1545 <div class="node">
1546 <a name="PERFORMANCE"></a>
1547 <p><hr>
1548 Next:&nbsp;<a rel="next" accesskey="n" href="#INTERFACE">INTERFACE</a>,
1549 Previous:&nbsp;<a rel="previous" accesskey="p" href="#RECORDING">RECORDING</a>,
1550 Up:&nbsp;<a rel="up" accesskey="u" href="#CONFIGURATION">CONFIGURATION</a>
1551
1552 </div>
1553
1554 <h3 class="section">4.6 PERFORMANCE</h3>
1555
1556 <p>You'll spend most of your time configuring this section.  The main
1557 focus of performance is rendering parameters not available in the
1558 rendering dialog.
1559
1560      <ul>
1561 <li>CACHE ITEMS
1562
1563      <p>To speed up rendering, several assets are kept open simultaneously.
1564 This determines how many are kept open.  A number too large may exhaust
1565 your memory pretty fast and result in a crash.  A number too small may
1566 result in slow playback as assets need to be reopened more frequently.
1567
1568      <li>
1569 SECONDS TO PREROLL RENDERS
1570
1571      <p>Some effects need a certain amount of time to settle in.  This sets a
1572 number of seconds to render without writing to disk before the selected
1573 region is rendered.  When using the renderfarm you'll sometimes need to
1574 preroll to get seemless transitions between the jobs.  Every job in a
1575 renderfarm is prerolled by this value.  This does not affect background
1576 rendering, however.  Background rendering uses a different preroll
1577 value.
1578
1579      <li>
1580 FORCE SINGLE PROCESSOR USE
1581
1582      <p>Cinelerra tries to use all processors on the system by default but
1583 sometimes you'll only want to use one processor, like in a renderfarm
1584 client.  This forces only one processer to be used.  The operating
1585 system, however, usually uses the second processor anyway for disk
1586 access so this option is really a 1.25 processor mode.  The value of
1587 this parameter is used in renderfarm clients.
1588
1589    </ul>
1590
1591 <ul class="menu">
1592 <li><a accesskey="1" href="#BACKGROUND-RENDERING">BACKGROUND RENDERING</a>
1593 <li><a accesskey="2" href="#RENDERFARM">RENDERFARM</a>
1594 </ul>
1595
1596 <div class="node">
1597 <a name="BACKGROUND-RENDERING"></a>
1598 <p><hr>
1599 Next:&nbsp;<a rel="next" accesskey="n" href="#RENDERFARM">RENDERFARM</a>,
1600 Up:&nbsp;<a rel="up" accesskey="u" href="#PERFORMANCE">PERFORMANCE</a>
1601
1602 </div>
1603
1604 <h4 class="subsection">4.6.1 BACKGROUND RENDERING</h4>
1605
1606 <p>Background rendering was originally concieved to allow HDTV effects to
1607 be displayed in realtime.  Background rendering causes temporary output
1608 to constantly be rendered while the timeline is being modified.  The
1609 temporary output is played during playack whenever possible.  It's very
1610 useful for transitions and previewing effects which are too slow to
1611 display in a reasonable amount of time.  If renderfarm is enabled, the
1612 renderfarm is used for background rendering, giving you the potential
1613 for realtime effects if enough network bandwidth and CPU nodes exist.
1614
1615      <ul>
1616 <li>FRAMES PER BACKGROUND RENDERING JOB
1617
1618      <p>This only works if renderfarm is being used, otherwise background
1619 rendering creates a single job for the entire timeline.  The number of
1620 frames specified here is scaled to the relative CPU speed of rendering
1621 nodes and used in a single renderfarm job.  The optimum number is 10 -
1622 30 since network bandwidth is used to initialize each job.
1623
1624      <li>FRAMES TO PREROLL BACKGROUND
1625
1626      <p>This is the number of frames to render ahead of each background
1627 rendering job.  Background rendering is degraded when preroll is used
1628 since the jobs are small.  When using background rendering, this number
1629 is ideally 0.  Some effects may require 3 frames of preroll.
1630
1631      <li>OUTPUT FOR BACKGROUND RENDERING
1632
1633      <p>Background rendering generates a sequence of image files in a certain
1634 directory.  This parameter determines the filename prefix of the image
1635 files.  It should be on a fast disk, accessible to every node in the
1636 renderfarm by the same path.  Since hundreds of thousands of image
1637 files are usually created, <b>ls</b> commands won't work in the
1638 background rendering directory.  The <img src="magnify.png" alt="magnify.png"> browse button for
1639 this option normally won't work either, but the <img src="wrench.png" alt="wrench.png">
1640 configuration button for this option works.
1641
1642      <li>FILE FORMAT
1643
1644      <p>The file format for background rendering has to be a sequence of
1645 images. The format of the image sequence determines the quality and
1646 speed of playback.  JPEG is good most of the time.
1647
1648    </ul>
1649
1650 <div class="node">
1651 <a name="RENDERFARM"></a>
1652 <p><hr>
1653 Previous:&nbsp;<a rel="previous" accesskey="p" href="#BACKGROUND-RENDERING">BACKGROUND RENDERING</a>,
1654 Up:&nbsp;<a rel="up" accesskey="u" href="#PERFORMANCE">PERFORMANCE</a>
1655
1656 </div>
1657
1658 <h4 class="subsection">4.6.2 RENDERFARM</h4>
1659
1660 <p>To use the renderfarm set these options.  Ignore them for a standalone
1661 system
1662
1663      <ul>
1664 <li>
1665 USE RENDER FARM FOR RENDERING
1666
1667      <p>When selected, all the
1668 <b>file-&gt;render</b> operations use the renderfarm.
1669
1670      <li>
1671 NODES
1672
1673      <p>Displays all the nodes on the renderfarm and which ones are active.
1674
1675      <p>Nodes are added by entering the host name of the node, verifying the
1676 value of <b>port</b> and hitting <b>add node</b>.
1677
1678      <p>Computer freaks may be better off editing the
1679 <b>~/.bcast/.Cinelerra_rc</b> file than this if they have hundreds of
1680 nodes.  Remember that .Cinelerra_rc is overwritten whenever a copy of
1681 Cinelerra exits.
1682
1683      <p>Select the <b>ON</b> column to activate and deactivate nodes once they
1684 are created.
1685
1686      <p>Nodes may be edited by highlighting a row and hitting <b>apply changes</b>.
1687
1688      <li>
1689 HOSTNAME
1690
1691      <p>Edit the hostname of an existing node or enter the hostname of a new
1692 node here.
1693
1694      <li>
1695 PORT
1696
1697      <p>Edit the port of an existing node or enter the port of a new node here.
1698
1699      <li>
1700 REPLACE NODE
1701
1702      <p>When editing an existing node, hit this to commit the changes to
1703 <b>HOSTNAME</b> and <b>PORT</b>.  The changes won't be committed if you
1704 don't hit this button.
1705
1706      <li>
1707 ADD NODE
1708
1709      <p>Create a new node with the <b>HOSTNAME</b> and <b>PORT</b> settings.
1710
1711      <li>
1712 DELETE NODE
1713
1714      <p>Deletes whatever node is highlighted in the <b>NODES</b> list.
1715
1716      <li>
1717 SORT NODES
1718
1719      <p>Sorts the <b>NODES</b> list based on the hostname.
1720
1721      <li>
1722 RESET RATES
1723
1724      <p>This sets the framerate for all the nodes to 0.  Frame rates are used
1725 to scale job sizes based on CPU speed of the node.  Frame rates are
1726 only calculated when renderfarm is enabled.
1727
1728      <li>
1729 TOTAL JOBS TO CREATE
1730
1731      <p>Determines the number of jobs to dispatch to the renderfarm.  The more
1732 jobs you create, the more finely balanced the renderfarm becomes.
1733
1734      <p>Determine the total jobs to create by multiplying the number of nodes
1735 including the master node by some number.  Multiply them by 1 to have
1736 one job dispatched for every node.  Multiply them by 3 to have 3 jobs
1737 dispatched for every node.  If you have 10 slave nodes and one master
1738 node, specify 33 to have a well balanced renderfarm.
1739
1740    </ul>
1741
1742 <div class="node">
1743 <a name="INTERFACE"></a>
1744 <p><hr>
1745 Next:&nbsp;<a rel="next" accesskey="n" href="#ABOUT">ABOUT</a>,
1746 Previous:&nbsp;<a rel="previous" accesskey="p" href="#PERFORMANCE">PERFORMANCE</a>,
1747 Up:&nbsp;<a rel="up" accesskey="u" href="#CONFIGURATION">CONFIGURATION</a>
1748
1749 </div>
1750
1751 <h3 class="section">4.7 INTERFACE</h3>
1752
1753 <p>These parameters affect purely how the user interface works.
1754
1755      <ul>
1756 <li>
1757 INDEX FILES GO HERE
1758
1759      <p>Back in the days when 4 MB/sec was unearthly speed for a hard drive,
1760 index files were introduced to speed up drawing the audio tracks.  This
1761 option determines where index files are placed on the hard drive.
1762
1763      <li>
1764 SIZE OF INDEX FILE
1765
1766      <p>Determines the size of an index file. Larger index sizes allow smaller
1767 files to be drawn faster while slowing down the drawing of large files.
1768 Smaller index sizes allow large files to be drawn faster while slowing
1769 down small files.
1770
1771      <li>
1772 NUMBER OF INDEX FILES TO KEEP
1773
1774      <p>To keep the index directory from becoming unruly, old index files are
1775 deleted. This determines the maximum number of index files to keep in
1776 the directory.
1777
1778      <li>
1779 DELETE ALL INDEXES
1780
1781      <p>When you change the index size or you want to clean out excessive index
1782 files, this deletes all the index files.
1783
1784      <li>USE HOURS:MINUTES:SECONDS.XXX
1785
1786      <p>Various representations of time are given.  Select the most convenient
1787 one.  The time representation can also be changed by <b>CTRL</b>
1788 clicking on the time ruler.
1789
1790      <li>USE THUMBNAILS
1791
1792      <p>The Resource Window displays thumbnails of assets by default.  This can
1793 take a long time to set up.  This option disables the thumbnails.
1794
1795      <li>CLICKING IN/OUT POINTS DOES WHAT
1796
1797      <p>Cinelerra not only allows you to perform editing by dragging in/out
1798 points but also defines three seperate operations which occur when you
1799 drag an in/out point. For each mouse button you select the behavior in
1800 this window. The usage of each editing mode is described in editing.
1801
1802      <li>MIN DB FOR METER
1803
1804      <p>Some sound sources have a lower noise threshold than others.
1805 Everything below the noise threshold is meaningless.  This option sets
1806 the meters to clip below a certain level.  Consumer soundcards usually
1807 bottom out at -65.  Professional soundcards bottom out at -90.
1808 See <a href="#SOUND-LEVEL-METERS">SOUND LEVEL METERS</a>.
1809
1810      <li>MAX DB FOR METER
1811
1812      <p>This sets the maximum sound level represented by the sound meters.  No
1813 matter what this value is, no soundcard can play sound over 0 db.  This
1814 value is presented merely to show how far over the limit a sound wave
1815 is.
1816 See <a href="#SOUND-LEVEL-METERS">SOUND LEVEL METERS</a>.
1817
1818      <li>THEME
1819
1820      <p>Cinelerra supports variable themes.  Select one here and restart
1821 Cinelerra to see it.
1822
1823    </ul>
1824
1825 <div class="node">
1826 <a name="ABOUT"></a>
1827 <p><hr>
1828 Previous:&nbsp;<a rel="previous" accesskey="p" href="#INTERFACE">INTERFACE</a>,
1829 Up:&nbsp;<a rel="up" accesskey="u" href="#CONFIGURATION">CONFIGURATION</a>
1830
1831 </div>
1832
1833 <h3 class="section">4.8 ABOUT</h3>
1834
1835 <p>This section gives you information about the copyright, the time of the
1836 current build, the lack of a warranty, and the versions of some of the
1837 libraries.  Be sure to agree to the terms of the lack of the warranty.
1838
1839 <div class="node">
1840 <a name="CREATING-A-NEW-PROJECT"></a>
1841 <p><hr>
1842 Next:&nbsp;<a rel="next" accesskey="n" href="#THE-MAIN-WINDOWS">THE MAIN WINDOWS</a>,
1843 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CONFIGURATION">CONFIGURATION</a>,
1844 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1845
1846 </div>
1847
1848 <h2 class="chapter">5 CREATING A NEW PROJECT</h2>
1849
1850 <p>There are 2 ways to create a new project: going to <b>File-&gt;New</b> or
1851 loading new files See <a href="#LOADING-FILES">LOADING FILES</a>.  Once a new project is
1852 created, all the parameters can be changed later without creating a new
1853 project.
1854
1855 <ul class="menu">
1856 <li><a accesskey="1" href="#USING-THE-NEW-PROJECT-DIALOG">USING THE NEW PROJECT DIALOG</a>
1857 <li><a accesskey="2" href="#CHANGING-PARAMETERS-AFTER-LOADING">CHANGING PARAMETERS AFTER LOADING</a>
1858 </ul>
1859
1860 <div class="node">
1861 <a name="USING-THE-NEW-PROJECT-DIALOG"></a>
1862 <p><hr>
1863 Next:&nbsp;<a rel="next" accesskey="n" href="#CHANGING-PARAMETERS-AFTER-LOADING">CHANGING PARAMETERS AFTER LOADING</a>,
1864 Up:&nbsp;<a rel="up" accesskey="u" href="#CREATING-A-NEW-PROJECT">CREATING A NEW PROJECT</a>
1865
1866 </div>
1867
1868 <h3 class="section">5.1 USING THE NEW PROJECT DIALOG</h3>
1869
1870 <p>One way is to go to <b>File-&gt;New</b>.  This dialog contains the parameters
1871 for the new project.  The sections of the <b>New</b> dialog are described
1872 here:
1873
1874      <ul>
1875 <li>
1876 <b>Presets</b> - Select an option from this menu to have all the project
1877 settings set to one of the known standards.
1878
1879      <li><b>Audio -&gt; Tracks</b> - Sets the number of audio tracks the new project
1880 should have.  Tracks can be added or deleted later, but options are
1881 provided here for convenience.
1882
1883      <li><b>Audio -&gt; Channels</b> - Sets the number of audio channels the new
1884 project should have.  The number of audio channels doesn't have to be
1885 the same as the number of tracks.
1886
1887      <li><b>Audio -&gt; Samplerate</b> - Sets the samplerate of the audio.  The
1888 project samplerate doesn't have to be the same as the media sample rate
1889 that you load.  Media is resampled to match the project sample rate.
1890
1891      <li><b>Video -&gt; Tracks</b> - Sets the number of video tracks the new project
1892 should have.  Tracks can be added or deleted later, but options are
1893 provided here for convenience.
1894
1895      <li><b>Video -&gt; Framerate</b> - Sets the framerate of the video.  The project
1896 framerate doesn't have to be the same as the media frame rate that you
1897 load.  Media is reframed to match the project framerate.
1898
1899      <li><b>Video -&gt; Canvas size</b> - Sets the size of the video output.  Each
1900 track also has its own frame size.  Initially the <b>New</b> dialog
1901 creates video tracks whose sizes all match the video output, but the
1902 video track sizes can be changed later without changing the video
1903 output.
1904
1905      <li><b>Video -&gt; Aspect ratio</b> - Sets the aspect ratio.  The aspect ratio is
1906 applied to the video output.  The aspect ratio can be different than
1907 the number of horizontal pixels / the number of vertical pixels.
1908 Setting a different aspect ratio than the number of pixels results in
1909 nonsquare pixels.
1910
1911      <li><b>Video -&gt; Auto aspect ratio</b> - If this is checked, the <b>New</b> dialog
1912 always recalculates the <b>Aspect ratio</b> setting when the <b>Canvas
1913 size</b> is changed.  This ensures pixels are always square.
1914
1915      <li><b>Video -&gt; Color model</b> - This sets the color model video intermediates
1916 in the project will be stored in.  Color models are described in a
1917 separate section See <a href="#COLOR-MODEL">COLOR MODEL</a>.
1918
1919    </ul>
1920
1921 <div class="node">
1922 <a name="CHANGING-PARAMETERS-AFTER-LOADING"></a>
1923 <p><hr>
1924 Previous:&nbsp;<a rel="previous" accesskey="p" href="#USING-THE-NEW-PROJECT-DIALOG">USING THE NEW PROJECT DIALOG</a>,
1925 Up:&nbsp;<a rel="up" accesskey="u" href="#CREATING-A-NEW-PROJECT">CREATING A NEW PROJECT</a>
1926
1927 </div>
1928
1929 <h3 class="section">5.2 CHANGING PARAMETERS AFTER LOADING</h3>
1930
1931 <p>After a project is created, you have to use the set format dialog to
1932 change parameters without deleting the project.  Go to <b>Settings-&gt;Set
1933 format</b>.
1934
1935    <p>Most of the options are identical to the <b>File-&gt;New</b>
1936 options except the lack of a number of tracks to create and the
1937 addition of audio channel locations.
1938
1939    <p>This section is discussed in See <a href="#SETTING-PROJECT-ATTRIBUTES">SETTING PROJECT ATTRIBUTES</a>.
1940
1941 <div class="node">
1942 <a name="THE-MAIN-WINDOWS"></a>
1943 <p><hr>
1944 Next:&nbsp;<a rel="next" accesskey="n" href="#LOADING-AND-SAVING-FILES">LOADING AND SAVING FILES</a>,
1945 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CREATING-A-NEW-PROJECT">CREATING A NEW PROJECT</a>,
1946 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
1947
1948 </div>
1949
1950 <h2 class="chapter">6 THE MAIN WINDOWS</h2>
1951
1952 <p>When Cinelerra first starts, you'll get four main windows.  Hitting
1953 <b>CTRL-w</b> in any window closes it.
1954
1955 <ul class="menu">
1956 <li><a accesskey="1" href="#VIEWER">VIEWER</a>
1957 <li><a accesskey="2" href="#COMPOSITOR">COMPOSITOR</a>
1958 <li><a accesskey="3" href="#PROGRAM">PROGRAM</a>
1959 <li><a accesskey="4" href="#RESOURCES">RESOURCES</a>
1960 <li><a accesskey="5" href="#SOUND-LEVEL-METERS">SOUND LEVEL METERS</a>
1961 <li><a accesskey="6" href="#OTHER-WINDOWS">OTHER WINDOWS</a>
1962 </ul>
1963
1964 <div class="node">
1965 <a name="VIEWER"></a>
1966 <p><hr>
1967 Next:&nbsp;<a rel="next" accesskey="n" href="#COMPOSITOR">COMPOSITOR</a>,
1968 Up:&nbsp;<a rel="up" accesskey="u" href="#THE-MAIN-WINDOWS">THE MAIN WINDOWS</a>
1969
1970 </div>
1971
1972 <h3 class="section">6.1 VIEWER</h3>
1973
1974 <p>In here you'll scrub around source media and clips, selecting regions
1975 to paste into the project.  Operations done in the viewer affect a
1976 temporary EDL or a clip but not the timeline.
1977
1978 <div class="node">
1979 <a name="COMPOSITOR"></a>
1980 <p><hr>
1981 Next:&nbsp;<a rel="next" accesskey="n" href="#PROGRAM">PROGRAM</a>,
1982 Previous:&nbsp;<a rel="previous" accesskey="p" href="#VIEWER">VIEWER</a>,
1983 Up:&nbsp;<a rel="up" accesskey="u" href="#THE-MAIN-WINDOWS">THE MAIN WINDOWS</a>
1984
1985 </div>
1986
1987 <h3 class="section">6.2 COMPOSITOR</h3>
1988
1989 <p>This window displays the output of the timeline.  It's the interface
1990 for most compositing operations or operations that affect the
1991 appearance of the timeline output.  Operations done in the Compositor
1992 affect the timeline but don't affect clips.
1993
1994    <p>The video output has several navigation functions.  The video output
1995 size is either locked to the window size or unlocked with scrollbars
1996 for navigation.  The video output can be zoomed in and out and panned.
1997 Navigating the video output this way doesn't affect the rendered
1998 output, it just changes the point of view in the compositor window.
1999
2000    <p>If it is unlocked from the window size, middle clicking and dragging
2001 anywhere in the video pans the point of view.
2002
2003    <p>Hitting the + and - keys zooms in and out of the video output.
2004
2005    <p>Underneath the video output are copies of many of the functions
2006 available in the main window.  In addition there is a
2007 <img src="cwindow_zoom.png" alt="cwindow_zoom.png"> zoom menu and a <img src="cwindow_light.png" alt="cwindow_light.png"> tally light.
2008
2009    <p>The zoom menu jumps to all the possible zoom settings and, through the
2010 <b>Auto</b> option, locks the video to the window size.  The zoom menu
2011 does not affect the window size.
2012
2013    <p>The tally light turns red when rendering is happening.  This is useful
2014 for knowing if the output is current.
2015
2016    <p>Right clicking anywhere in the video output brings up a menu with all
2017 the zoom levels and some other options.  In this particular case the
2018 zoom levels resize the entire window and not just the video.
2019
2020    <p>The <b>reset camera</b> and <b>reset projector</b> options center the camera
2021 and projector See <a href="#COMPOSITING">COMPOSITING</a>.
2022
2023    <p>The <b>Hide controls</b> option hides everything except the video.
2024
2025    <p>On the left of the video output is a toolbar specific to the compositor
2026 window.  Here are the functions in the toolbar:
2027
2028 <ul class="menu">
2029 <li><a accesskey="1" href="#PROTECT-VIDEO">PROTECT VIDEO</a>
2030 <li><a accesskey="2" href="#MAGNIFYING-GLASS">MAGNIFYING GLASS</a>
2031 <li><a accesskey="3" href="#MASKS-TOOL">MASKS TOOL</a>
2032 <li><a accesskey="4" href="#CAMERA">CAMERA</a>
2033 <li><a accesskey="5" href="#PROJECTOR">PROJECTOR</a>
2034 <li><a accesskey="6" href="#CROP-TOOL">CROP TOOL</a>
2035 <li><a accesskey="7" href="#EYEDROPPER">EYEDROPPER</a>
2036 <li><a accesskey="8" href="#TOOL-INFO">TOOL INFO</a>
2037 <li><a accesskey="9" href="#SAFE-REGIONS-TOOL">SAFE REGIONS TOOL</a>
2038 </ul>
2039
2040 <div class="node">
2041 <a name="PROTECT-VIDEO"></a>
2042 <p><hr>
2043 Next:&nbsp;<a rel="next" accesskey="n" href="#MAGNIFYING-GLASS">MAGNIFYING GLASS</a>,
2044 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITOR">COMPOSITOR</a>
2045
2046 </div>
2047
2048 <h4 class="subsection">6.2.1 PROTECT VIDEO</h4>
2049
2050 <div class="block-image"><img src="protect.png" alt="protect.png"></div>
2051
2052    <p>This disables changes to the compositor output from clicks in it.  It
2053 is an extra layer on top of the track arming toggle to prevent
2054 unwanted changes.
2055
2056 <div class="node">
2057 <a name="MAGNIFYING-GLASS"></a>
2058 <p><hr>
2059 Next:&nbsp;<a rel="next" accesskey="n" href="#MASKS-TOOL">MASKS TOOL</a>,
2060 Previous:&nbsp;<a rel="previous" accesskey="p" href="#PROTECT-VIDEO">PROTECT VIDEO</a>,
2061 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITOR">COMPOSITOR</a>
2062
2063 </div>
2064
2065 <h4 class="subsection">6.2.2 MAGNIFYING GLASS</h4>
2066
2067 <div class="block-image"><img src="magnify.png" alt="magnify.png"></div>
2068
2069    <p>This zooms in and out of the compositor output without resizing the
2070 window.  If the video output is currently locked to the size of the
2071 window, clicking in it with the magnifying glass unlocks it and
2072 creates scrollbars for navigation.
2073
2074    <p>Left clicking in the video zooms in.
2075
2076    <p>Ctrl clicking in the video zooms out.
2077
2078    <p>Rotating the wheel on a wheel mouse zooms in and out.
2079
2080 <div class="node">
2081 <a name="MASKS-TOOL"></a>
2082 <p><hr>
2083 Next:&nbsp;<a rel="next" accesskey="n" href="#CAMERA">CAMERA</a>,
2084 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MAGNIFYING-GLASS">MAGNIFYING GLASS</a>,
2085 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITOR">COMPOSITOR</a>
2086
2087 </div>
2088
2089 <h4 class="subsection">6.2.3 MASKS TOOL</h4>
2090
2091 <div class="block-image"><img src="mask.png" alt="mask.png"></div>
2092
2093    <p>This brings up the mask editing tool See <a href="#MASKS">MASKS</a>.  Enable the
2094 <img src="toolwindow.png" alt="toolwindow.png"> tool window to see options for this tool.
2095
2096 <div class="node">
2097 <a name="CAMERA"></a>
2098 <p><hr>
2099 Next:&nbsp;<a rel="next" accesskey="n" href="#PROJECTOR">PROJECTOR</a>,
2100 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MASKS-TOOL">MASKS TOOL</a>,
2101 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITOR">COMPOSITOR</a>
2102
2103 </div>
2104
2105 <h4 class="subsection">6.2.4 CAMERA</h4>
2106
2107 <div class="block-image"><img src="camera.png" alt="camera.png"></div>
2108
2109    <p>This brings up the camera editing tool See <a href="#THE-CAMERA-AND-PROJECTOR">THE CAMERA AND PROJECTOR</a>.  Enable the <img src="toolwindow.png" alt="toolwindow.png"> tool window to see options
2110 for this tool.
2111
2112 <div class="node">
2113 <a name="PROJECTOR"></a>
2114 <p><hr>
2115 Next:&nbsp;<a rel="next" accesskey="n" href="#CROP-TOOL">CROP TOOL</a>,
2116 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CAMERA">CAMERA</a>,
2117 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITOR">COMPOSITOR</a>
2118
2119 </div>
2120
2121 <h4 class="subsection">6.2.5 PROJECTOR</h4>
2122
2123 <div class="block-image"><img src="projector.png" alt="projector.png"></div>
2124
2125    <p>This brings up the projector editing tool See <a href="#THE-CAMERA-AND-PROJECTOR">THE CAMERA AND PROJECTOR</a>.  Enable the <img src="toolwindow.png" alt="toolwindow.png"> tool window to see options
2126 for this tool.
2127
2128 <div class="node">
2129 <a name="CROP-TOOL"></a>
2130 <p><hr>
2131 Next:&nbsp;<a rel="next" accesskey="n" href="#EYEDROPPER">EYEDROPPER</a>,
2132 Previous:&nbsp;<a rel="previous" accesskey="p" href="#PROJECTOR">PROJECTOR</a>,
2133 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITOR">COMPOSITOR</a>
2134
2135 </div>
2136
2137 <h4 class="subsection">6.2.6 CROP TOOL</h4>
2138
2139 <div class="block-image"><img src="crop.png" alt="crop.png"></div>
2140
2141    <p>This brings up the cropping tool See <a href="#CROPPING">CROPPING</a>.  The
2142 <img src="toolwindow.png" alt="toolwindow.png"> tool window must be enabled to use this tool.
2143
2144 <div class="node">
2145 <a name="EYEDROPPER"></a>
2146 <p><hr>
2147 Next:&nbsp;<a rel="next" accesskey="n" href="#TOOL-INFO">TOOL INFO</a>,
2148 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CROP-TOOL">CROP TOOL</a>,
2149 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITOR">COMPOSITOR</a>
2150
2151 </div>
2152
2153 <h4 class="subsection">6.2.7 EYEDROPPER</h4>
2154
2155 <div class="block-image"><img src="eyedrop.png" alt="eyedrop.png"></div>
2156
2157    <p>This brings up the eyedropper.  The eyedropper detects whatever color
2158 is under it and stores it in a temporary area.  Enabling the
2159 <img src="toolwindow.png" alt="toolwindow.png"> tool info shows the currently selected color.  Click
2160 anywhere in the video output to select the color at that point.
2161
2162    <p>The eyedropper not only lets you see areas which are clipped, but its
2163 value can be applied to many effects.  Different effects handle the
2164 eyedropper differently.
2165
2166 <div class="node">
2167 <a name="TOOL-INFO"></a>
2168 <p><hr>
2169 Next:&nbsp;<a rel="next" accesskey="n" href="#SAFE-REGIONS-TOOL">SAFE REGIONS TOOL</a>,
2170 Previous:&nbsp;<a rel="previous" accesskey="p" href="#EYEDROPPER">EYEDROPPER</a>,
2171 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITOR">COMPOSITOR</a>
2172
2173 </div>
2174
2175 <h4 class="subsection">6.2.8 TOOL INFO</h4>
2176
2177 <div class="block-image"><img src="toolwindow.png" alt="toolwindow.png"></div>
2178
2179    <p>This brings up a window containing options for the currently selected
2180 tool.
2181
2182 <div class="node">
2183 <a name="SAFE-REGIONS-TOOL"></a>
2184 <p><hr>
2185 Previous:&nbsp;<a rel="previous" accesskey="p" href="#TOOL-INFO">TOOL INFO</a>,
2186 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITOR">COMPOSITOR</a>
2187
2188 </div>
2189
2190 <h4 class="subsection">6.2.9 SAFE REGIONS TOOL</h4>
2191
2192 <div class="block-image"><img src="titlesafe.png" alt="titlesafe.png"></div>
2193
2194    <p>This draws the safe regions in the video output.  This doesn't affect
2195 the rendered output See <a href="#SAFE-REGIONS">SAFE REGIONS</a>.
2196
2197 <div class="node">
2198 <a name="PROGRAM"></a>
2199 <p><hr>
2200 Next:&nbsp;<a rel="next" accesskey="n" href="#RESOURCES">RESOURCES</a>,
2201 Previous:&nbsp;<a rel="previous" accesskey="p" href="#COMPOSITOR">COMPOSITOR</a>,
2202 Up:&nbsp;<a rel="up" accesskey="u" href="#THE-MAIN-WINDOWS">THE MAIN WINDOWS</a>
2203
2204 </div>
2205
2206 <h3 class="section">6.3 PROGRAM</h3>
2207
2208 <p>This contains the timeline and the entry point for all menu driven
2209 operations.  The timeline consists of a vertical stack of tracks with
2210 horizontal representation of time.  This defines the output of
2211 rendering operations and what is saved when you save files.  Left of
2212 the timeline is the patchbay which contains options affecting each
2213 track.
2214
2215    <p>Under the <b>Window</b> menu you'll find options affecting the main
2216 windows.  <b>default positions</b> repositions all the windows to a 4
2217 screen editing configuration.  On dual headed displays, the
2218 <b>default positions</b> operation fills only one monitor with windows.
2219
2220 <div class="node">
2221 <a name="RESOURCES"></a>
2222 <p><hr>
2223 Next:&nbsp;<a rel="next" accesskey="n" href="#SOUND-LEVEL-METERS">SOUND LEVEL METERS</a>,
2224 Previous:&nbsp;<a rel="previous" accesskey="p" href="#PROGRAM">PROGRAM</a>,
2225 Up:&nbsp;<a rel="up" accesskey="u" href="#THE-MAIN-WINDOWS">THE MAIN WINDOWS</a>
2226
2227 </div>
2228
2229 <h3 class="section">6.4 RESOURCES</h3>
2230
2231 <p>Effects, transitions, clips, and assets are accessed here.  Most of the
2232 resources are inserted into the project by dragging them out of the
2233 resource window.  Management of resource allocation is also performed
2234 here.
2235
2236 <div class="node">
2237 <a name="SOUND-LEVEL-METERS"></a>
2238 <p><hr>
2239 Next:&nbsp;<a rel="next" accesskey="n" href="#OTHER-WINDOWS">OTHER WINDOWS</a>,
2240 Previous:&nbsp;<a rel="previous" accesskey="p" href="#RESOURCES">RESOURCES</a>,
2241 Up:&nbsp;<a rel="up" accesskey="u" href="#THE-MAIN-WINDOWS">THE MAIN WINDOWS</a>
2242
2243 </div>
2244
2245 <h3 class="section">6.5 SOUND LEVEL METERS</h3>
2246
2247 <p>An additional window, the <b>levels window</b> can be brought up from
2248 the <b>Window</b> menu.  The <b>levels</b> window displays the output
2249 audio levels after all mixing is done.
2250
2251    <p>Sound level meters appear in many locations.  They can be toggled in
2252 the viewer and compositor windows with the <img src="show_meters.png" alt="show_meters.png"> level
2253 toggle. They appear in the patchbay when a track is expanded (See <a href="#THE-PATCHBAY">THE PATCHBAY</a>.)  They appear in the recording monitor when audio is being
2254 recorded.
2255
2256    <p>The sound levels in the <b>levels window, compositor, and viewer</b>
2257 correspond to the final output levels before they are clipped to the
2258 soundcard range.  In the <b>record monitor</b> they are the input values
2259 from the sound card.  In the <b>patchbay</b> they are the sound levels for
2260 each track after all effects are processed and before downmixing for
2261 the output.
2262
2263    <p>Most of the time, audio levels have numerical markings in DB but in the
2264 patchbay there isn't enough room.
2265
2266    <p>The sound level is color coded as an extra means of determining the
2267 sound level.  Even without numerical markings, the sound level color
2268 can distinguish between several ranges and overload.  Look at the color
2269 codings in a meter with numerical markings to see what colors
2270 correspond to what sound level.  Then for meters in the patchbay in
2271 expanded audio tracks, use the color codings to see if it's overloading.
2272
2273    <p>Be aware that sound levels in Cinelerra can go above 0DB.  This allows
2274 not only seeing if a track is overloading but how much information is
2275 being lost by the overloading.  Overloading by less than 3DB is usually
2276 acceptable.  While overloading is treated as positive numbers in
2277 Cinelerra, it is clipped to 0 when sent to a sound card or file.
2278
2279    <p>The visible range of the sound level meters is configurable in
2280 <b>settings-&gt;preferences-&gt;interface</b> (See <a href="#INTERFACE">INTERFACE</a>.)
2281
2282 <div class="node">
2283 <a name="OTHER-WINDOWS"></a>
2284 <p><hr>
2285 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SOUND-LEVEL-METERS">SOUND LEVEL METERS</a>,
2286 Up:&nbsp;<a rel="up" accesskey="u" href="#THE-MAIN-WINDOWS">THE MAIN WINDOWS</a>
2287
2288 </div>
2289
2290 <h3 class="section">6.6 OTHER WINDOWS</h3>
2291
2292 <p>The <b>Overlays window</b> can be brought up from the <b>Window</b>
2293 menu.  This is a quick way to toggle what is drawn in the timeline.
2294 Every option in the <b>View</b> menu is available here.
2295
2296 <div class="node">
2297 <a name="LOADING-AND-SAVING-FILES"></a>
2298 <p><hr>
2299 Next:&nbsp;<a rel="next" accesskey="n" href="#NAVIGATING-THE-PROJECT">NAVIGATING THE PROJECT</a>,
2300 Previous:&nbsp;<a rel="previous" accesskey="p" href="#THE-MAIN-WINDOWS">THE MAIN WINDOWS</a>,
2301 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
2302
2303 </div>
2304
2305 <h2 class="chapter">7 LOADING AND SAVING FILES</h2>
2306
2307 <ul class="menu">
2308 <li><a accesskey="1" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>:      What formats Cinelerra can import and export
2309 <li><a accesskey="2" href="#LOADING-FILES">LOADING FILES</a>:               Loading all types of files
2310 <li><a accesskey="3" href="#LOADING-THE-BACKUP">LOADING THE BACKUP</a>:          Recovering the session from before a crash
2311 <li><a accesskey="4" href="#SAVING-FILES">SAVING FILES</a>:                Saving edit decision lists
2312 <li><a accesskey="5" href="#RENDERING-FILES">RENDERING FILES</a>:             Saving media files
2313 </ul>
2314
2315 <div class="node">
2316 <a name="SUPPORTED-FILE-FORMATS"></a>
2317 <p><hr>
2318 Next:&nbsp;<a rel="next" accesskey="n" href="#LOADING-FILES">LOADING FILES</a>,
2319 Up:&nbsp;<a rel="up" accesskey="u" href="#LOADING-AND-SAVING-FILES">LOADING AND SAVING FILES</a>
2320
2321 </div>
2322
2323 <h3 class="section">7.1 SUPPORTED FILE FORMATS</h3>
2324
2325 <p>Here are most of the supported file formats and notes regarding their
2326 compression.  You may be able to load other formats not described here.
2327
2328    <p>The format of the file affects what Cinelerra does with it.  Edit
2329 decision lists replace the project settings.  Formats which contain
2330 media but no edit decisions just add data to the tracks.  If your
2331 project sample rate is 48khz and you load a sound file with 96khz,
2332 you'll still be playing it at 48khz.   If you load an EDL file at 96khz
2333 and the current project sample rate is 48khz, you'll change it to
2334 96khz.
2335
2336    <p>Some file formats are very slow to display on the timeline.  These
2337 usually have video which is highly compressed.  Drawing highly
2338 compressed video picons can be very slow.  Disable picon drawing for
2339 these files with the <b>draw media</b> toggle to speed up operations.
2340
2341    <pre class="sp">
2342
2343 </pre>
2344 <img src="track_attributes.png" alt="track_attributes.png">
2345 <b>Track attributes</b>
2346
2347    <p>Supported file formats are currently:
2348
2349      <ul>
2350 <li>WAV
2351 <li>FLAC
2352 <li>PCM
2353 <li>AIFF
2354 <li>AC3 audio
2355 </ul>
2356
2357 <ul class="menu">
2358 <li><a accesskey="1" href="#QUICKTIME">QUICKTIME</a>
2359 <li><a accesskey="2" href="#MPEG_002d4-AUDIO">MPEG-4 AUDIO</a>
2360 <li><a accesskey="3" href="#IMAGE-SEQUENCES">IMAGE SEQUENCES</a>
2361 <li><a accesskey="4" href="#STILL-IMAGES">STILL IMAGES</a>
2362 <li><a accesskey="5" href="#AVI">AVI</a>
2363 <li><a accesskey="6" href="#MPEG-FILES-CONTAINING-VIDEO">MPEG FILES CONTAINING VIDEO</a>
2364 <li><a accesskey="7" href="#DVD-MOVIES">DVD MOVIES</a>
2365 <li><a accesskey="8" href="#MPEG-1-AUDIO">MPEG 1 AUDIO</a>
2366 <li><a accesskey="9" href="#OGG-THEORA_002fVORBIS">OGG THEORA/VORBIS</a>
2367 <li><a href="#EDIT-DECISION-LIST">EDIT DECISION LIST</a>
2368 </ul>
2369
2370 <div class="node">
2371 <a name="QUICKTIME"></a>
2372 <p><hr>
2373 Next:&nbsp;<a rel="next" accesskey="n" href="#MPEG_002d4-AUDIO">MPEG-4 AUDIO</a>,
2374 Up:&nbsp;<a rel="up" accesskey="u" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>
2375
2376 </div>
2377
2378 <h4 class="subsection">7.1.1 QUICKTIME</h4>
2379
2380 <p>Quicktime is not the standard for UNIX but we use it because it's well
2381 documented.  All of the Quicktime movies on the internet are
2382 compressed.  Cinelerra doesn't support most compressed Quicktime movies
2383 but does support some.  If it crashes when loading a Quicktime movie,
2384 that means the format probably wasn't supported.
2385
2386    <p><b>NOTES ON QUICKTIME ENCODING</b>
2387
2388    <p>Here are some notes regarding making Quicktime movies in Cinelerra:
2389
2390    <p>Quicktime is a wrapper for 2 codecs, a video codec and an audio codec.
2391 The video and audio codecs are picked separately.  The preferred
2392 encoding for Quicktime output is MPEG-4 Video and MPEG-4 Audio.  This
2393 format plays in the commercial players for Windows and has good
2394 compression quality.  For better compression, use H-264 Video.
2395 Unfortunately H-264 decoding is so slow it can't play very large frame
2396 sizes.
2397
2398    <p>Cinelerra supports 2 nonstandard codecs: Dual MPEG-4 video and dual
2399 H.264 video.  These won't play in anything but Cinelerra and XMovie.
2400 They are designed for movies where the frames have been divided into 2
2401 fields, each field displayed sequentially.  The dual codecs interleave
2402 2 video streams to improve efficiency without requiring major changes
2403 to the player.
2404
2405 <div class="node">
2406 <a name="MPEG-4-AUDIO"></a>
2407 <a name="MPEG_002d4-AUDIO"></a>
2408 <p><hr>
2409 Next:&nbsp;<a rel="next" accesskey="n" href="#IMAGE-SEQUENCES">IMAGE SEQUENCES</a>,
2410 Previous:&nbsp;<a rel="previous" accesskey="p" href="#QUICKTIME">QUICKTIME</a>,
2411 Up:&nbsp;<a rel="up" accesskey="u" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>
2412
2413 </div>
2414
2415 <h4 class="subsection">7.1.2 MPEG-4 AUDIO</h4>
2416
2417 <p>This is the same as Quicktime with MPEG-4 Audio as the audio codec.
2418
2419 <div class="node">
2420 <a name="IMAGE-SEQUENCES"></a>
2421 <p><hr>
2422 Next:&nbsp;<a rel="next" accesskey="n" href="#STILL-IMAGES">STILL IMAGES</a>,
2423 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MPEG_002d4-AUDIO">MPEG-4 AUDIO</a>,
2424 Up:&nbsp;<a rel="up" accesskey="u" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>
2425
2426 </div>
2427
2428 <h4 class="subsection">7.1.3 IMAGE SEQUENCES</h4>
2429
2430 <p>Rendering an image sequence is not the same as rendering a single
2431 image.  When rendering an image sequence Cinelerra generates a table of
2432 contents file for the image sequence and makes a different image file
2433 for every timeline position.  The table of contents can be loaded
2434 instead of the individual images to get better performance.  To learn
2435 more about the different image formats supported in an image sequence,
2436 read about still images.
2437
2438 <div class="node">
2439 <a name="STILL-IMAGES"></a>
2440 <p><hr>
2441 Next:&nbsp;<a rel="next" accesskey="n" href="#AVI">AVI</a>,
2442 Previous:&nbsp;<a rel="previous" accesskey="p" href="#IMAGE-SEQUENCES">IMAGE SEQUENCES</a>,
2443 Up:&nbsp;<a rel="up" accesskey="u" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>
2444
2445 </div>
2446
2447 <h4 class="subsection">7.1.4 STILL IMAGES</h4>
2448
2449 <p>Rendering a single image causes the image file to be overwritten for
2450 every timeline position.  No table of contents is created.  When
2451 loaded, the image takes up one frame in length and doesn't change the
2452 project attributes.
2453
2454    <p>Several still image formats not normally found in other programs are
2455 described here.
2456
2457 <ul class="menu">
2458 <li><a accesskey="1" href="#OPEN-EXR-IMAGES">OPEN EXR IMAGES</a>
2459 <li><a accesskey="2" href="#RAW-DIGITAL-CAMERA-IMAGES">RAW DIGITAL CAMERA IMAGES</a>
2460 </ul>
2461
2462 <div class="node">
2463 <a name="OPEN-EXR-IMAGES"></a>
2464 <p><hr>
2465 Next:&nbsp;<a rel="next" accesskey="n" href="#RAW-DIGITAL-CAMERA-IMAGES">RAW DIGITAL CAMERA IMAGES</a>,
2466 Up:&nbsp;<a rel="up" accesskey="u" href="#STILL-IMAGES">STILL IMAGES</a>
2467
2468 </div>
2469
2470 <h5 class="subsubsection">7.1.4.1 OPEN EXR IMAGES</h5>
2471
2472 <p>You may not know about Open EXR.  This format stores floating point RGB
2473 images.  It also supports a small amount of compression.  Projects
2474 which render to EXR should be in a floating point color model to take
2475 advantage of it See <a href="#SETTING-PROJECT-ATTRIBUTES">SETTING PROJECT ATTRIBUTES</a>.  Several compression
2476 options are available for EXR.
2477
2478      <ul>
2479 <li>
2480 <b>PIZ</b> Lossless wavelet compression.  This is the best compression.
2481
2482      <li><b>ZIP</b> Lossless gzip algorithm.
2483
2484      <li><b>RLE</b> Lossless run length encoding.  This is the fastest and worst
2485 compression.
2486
2487      <li><b>PXR24</b> Lossy compression where the floating point numbers are
2488 converted to 24 bits and compressed with gzip.
2489
2490    </ul>
2491
2492    <p>Select <b>Use Alpha</b> if the project colormodel has an alpha channel and
2493 you want to retain it in the file.  Otherwise the primary colors are
2494 multiplied by the alpha channel.
2495
2496 <div class="node">
2497 <a name="RAW-DIGITAL-CAMERA-IMAGES"></a>
2498 <p><hr>
2499 Previous:&nbsp;<a rel="previous" accesskey="p" href="#OPEN-EXR-IMAGES">OPEN EXR IMAGES</a>,
2500 Up:&nbsp;<a rel="up" accesskey="u" href="#STILL-IMAGES">STILL IMAGES</a>
2501
2502 </div>
2503
2504 <h5 class="subsubsection">7.1.4.2 RAW DIGITAL CAMERA IMAGES</h5>
2505
2506 <p>RAW digital camera images are a special kind of image file which
2507 Cinelerra only imports.  These must be processed in a floating point
2508 color space once they are on the timeline.  Raw images from Canon
2509 cameras are the only ones tested.  They need to have the <b>Linearize</b>
2510 effect applied to correct gamma.  Because raw images take a long time
2511 to interpolate, they are usually viewed first in a proxy file and then
2512 touched up.
2513
2514    <p>First apply the Linearize effect to a track of raw images and set it to
2515 <b>automatic</b> with <b>0.6</b> gamma.  Then render the timeline to a
2516 Quicktime JPEG file.  Append the Quicktime JPEG file in a new track and
2517 disable playback of the old track.  Now the gamma corrected copy of
2518 each raw image can be previewed relatively fast in the same timeline
2519 position as the original image.
2520
2521 <div class="node">
2522 <a name="AVI"></a>
2523 <p><hr>
2524 Next:&nbsp;<a rel="next" accesskey="n" href="#MPEG-FILES-CONTAINING-VIDEO">MPEG FILES CONTAINING VIDEO</a>,
2525 Previous:&nbsp;<a rel="previous" accesskey="p" href="#STILL-IMAGES">STILL IMAGES</a>,
2526 Up:&nbsp;<a rel="up" accesskey="u" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>
2527
2528 </div>
2529
2530 <h4 class="subsection">7.1.5 AVI</h4>
2531
2532 <p>AVI with assorted audio and video codecs.  Because AVI is so
2533 fragmented, your luck will vary.
2534
2535 <div class="node">
2536 <a name="MPEG-FILES-CONTAINING-VIDEO"></a>
2537 <p><hr>
2538 Next:&nbsp;<a rel="next" accesskey="n" href="#DVD-MOVIES">DVD MOVIES</a>,
2539 Previous:&nbsp;<a rel="previous" accesskey="p" href="#AVI">AVI</a>,
2540 Up:&nbsp;<a rel="up" accesskey="u" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>
2541
2542 </div>
2543
2544 <h4 class="subsection">7.1.6 MPEG FILES CONTAINING VIDEO</h4>
2545
2546 <p>MPEG files containing video can be loaded directly into Cinelerra.  If
2547 the file is supported, a table of contents is built.  If the file is
2548 unsupported, it usually crashes or shows very short tracks.
2549 Unfortunately, this method of loading MPEG files isn't good enough if
2550 you intend to use the files in a renderfarm.
2551
2552    <p>To use MPEG files in a renderfarm you need to run <b>mpeg3toc</b> to
2553 generate a table of contents for the file, then load the table of
2554 contents.  Mpeg3toc needs the absolute path of the MPEG file.  If you
2555 don't use an absolute path, it assumes the MPEG file is in the same
2556 directory that Cinelerra is run from.
2557
2558    <p>MPEG streams are structured into multiple tracks.  Each track can be
2559 video or audio.  Each audio track can have 1-6 channels.  Cinelerra
2560 converts each channel of audio into a track.
2561
2562    <p><b>NOTES ON MPEG VIDEO ENCODING</b>
2563
2564    <p>MPEG video encoding is done separately from MPEG audio encoding.  In
2565 MPEG video there are 2 colormodels.  The YUV 4:2:0 colormodel is
2566 encoded by a highly optimized version of mpeg2enc with presets for
2567 standard consumer electronics.  In the process of optimizing mpeg2enc,
2568 they got rid of YUV 4:2:2 encoding.  The YUV 4:2:2 colormodel is
2569 encoded by a less optimized version of mpeg2enc.
2570
2571    <p>YUV 4:2:2 encoding was kept around because the NTSC version of DV video
2572 loses too much quality when transferred to YUV 4:2:0.  This DV video
2573 must be transferred to YUV 4:2:2.
2574
2575    <p>When encoding YUV 4:2:0, the bitrate parameter changes meaning
2576 depending on whether the bitrate or quantization is fixed.  If the
2577 bitrate is fixed, it's the target bitrate.  If the quantization is
2578 fixed, it's the maximum bitrate allowed.  This is a quirk of the
2579 mpeg2enc version.
2580
2581 <div class="node">
2582 <a name="DVD-MOVIES"></a>
2583 <p><hr>
2584 Next:&nbsp;<a rel="next" accesskey="n" href="#MPEG-1-AUDIO">MPEG 1 AUDIO</a>,
2585 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MPEG-FILES-CONTAINING-VIDEO">MPEG FILES CONTAINING VIDEO</a>,
2586 Up:&nbsp;<a rel="up" accesskey="u" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>
2587
2588 </div>
2589
2590 <h4 class="subsection">7.1.7 DVD MOVIES</h4>
2591
2592 <p>DVD's are spit into a number of programs, each identified by a unique
2593 <b>IFO</b> file.  If you want to load a DVD, find the corresponding
2594 <b>IFO</b> file for the program of interest.  Load the IFO file directly
2595 and a table of contents will be built.  Alternatively for renderfarm
2596 usage, a table of contents can be created separately.
2597
2598    <p>Run
2599
2600 <pre class="example">     mpeg3toc -v /cdrom/video_ts/vts_01_0.ifo dvd.toc
2601 </pre>
2602    <p>or something similar.  Then load <b>dvd.toc</b>.
2603
2604 <div class="node">
2605 <a name="MPEG-1-AUDIO"></a>
2606 <p><hr>
2607 Next:&nbsp;<a rel="next" accesskey="n" href="#OGG-THEORA_002fVORBIS">OGG THEORA/VORBIS</a>,
2608 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DVD-MOVIES">DVD MOVIES</a>,
2609 Up:&nbsp;<a rel="up" accesskey="u" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>
2610
2611 </div>
2612
2613 <h4 class="subsection">7.1.8 MPEG 1 AUDIO</h4>
2614
2615 <p>These are .mp2 and .mp3 files.  If fixed bitrate, they can be loaded
2616 directly with no table of contents.  Variable bitrate streams need to
2617 have a table of contents created with <b>mpeg3toc</b>.
2618
2619 <div class="node">
2620 <a name="OGG-THEORA%2fVORBIS"></a>
2621 <a name="OGG-THEORA_002fVORBIS"></a>
2622 <p><hr>
2623 Next:&nbsp;<a rel="next" accesskey="n" href="#EDIT-DECISION-LIST">EDIT DECISION LIST</a>,
2624 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MPEG-1-AUDIO">MPEG 1 AUDIO</a>,
2625 Up:&nbsp;<a rel="up" accesskey="u" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>
2626
2627 </div>
2628
2629 <h4 class="subsection">7.1.9 OGG THEORA/VORBIS</h4>
2630
2631 <p>The OGG format is an antiquated but supposedly unpatented way of
2632 compressing audio and video.  The quality isn't as good as H.264 or
2633 MPEG-4 Audio.  In reality, anyone with enough money and desire can find
2634 a patent violation so the justification for OGG is questionable.
2635
2636 <div class="node">
2637 <a name="EDIT-DECISION-LIST"></a>
2638 <p><hr>
2639 Previous:&nbsp;<a rel="previous" accesskey="p" href="#OGG-THEORA_002fVORBIS">OGG THEORA/VORBIS</a>,
2640 Up:&nbsp;<a rel="up" accesskey="u" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>
2641
2642 </div>
2643
2644 <h4 class="subsection">7.1.10 EDIT DECISION LIST</h4>
2645
2646 <p>Edit decision lists are generated by Cinelerra for storing projects.
2647 They end in .xml.  They change project attributes when loaded.
2648
2649    <p>Because edit decision lists consist of text, they can be edited in a
2650 text editor.
2651
2652 <div class="node">
2653 <a name="LOADING-FILES"></a>
2654 <p><hr>
2655 Next:&nbsp;<a rel="next" accesskey="n" href="#LOADING-THE-BACKUP">LOADING THE BACKUP</a>,
2656 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SUPPORTED-FILE-FORMATS">SUPPORTED FILE FORMATS</a>,
2657 Up:&nbsp;<a rel="up" accesskey="u" href="#LOADING-AND-SAVING-FILES">LOADING AND SAVING FILES</a>
2658
2659 </div>
2660
2661 <h3 class="section">7.2 LOADING FILES</h3>
2662
2663 <p>All data that you work with in Cinelerra is acquired either by
2664 <b>recording from a device</b> or by <b>loading from disk</b>.  This
2665 section describes loading.
2666
2667    <p>The loading and playing of files is just as you would expect. Just go
2668 to <b>file-&gt;Load</b>, select a file for loading, and hit <b>ok</b>. Hit
2669 the forward play button and it should start playing, regardless of
2670 whether a progress bar has popped up.
2671
2672    <p>Another way to load files is to pass the filenames as arguments on the
2673 command line.  This creates new tracks for every file and starts the
2674 program with all the arguments loaded.
2675
2676    <p>If the file is a still image, the project's attributes are not changed
2677 and the first frame of the track becomes the image.  If the file has
2678 audio, Cinelerra may build an index file for it to speed up drawing.
2679 You can edit and play the file while the index file is being built.
2680
2681 <ul class="menu">
2682 <li><a accesskey="1" href="#INSERTION-STRATEGY">INSERTION STRATEGY</a>
2683 <li><a accesskey="2" href="#LOADING-MULTIPLE-FILES">LOADING MULTIPLE FILES</a>
2684 </ul>
2685
2686 <div class="node">
2687 <a name="INSERTION-STRATEGY"></a>
2688 <p><hr>
2689 Next:&nbsp;<a rel="next" accesskey="n" href="#LOADING-MULTIPLE-FILES">LOADING MULTIPLE FILES</a>,
2690 Up:&nbsp;<a rel="up" accesskey="u" href="#LOADING-FILES">LOADING FILES</a>
2691
2692 </div>
2693
2694 <h4 class="subsection">7.2.1 INSERTION STRATEGY</h4>
2695
2696 <p>Usually three things happen when you load a file.  First the existing
2697 project is cleared from the screen, second the project's attributes are
2698 changed to match the file's, and finally the new file's tracks are
2699 created in the timeline.
2700
2701    <p>But Cinelerra lets you change what happens when you load a file.
2702
2703    <p>In the file selection box there is a range of options for <b>Insertion
2704 strategy</b>.  Each of these options loads the file a different way.
2705
2706    <div class="block-image"><img src="insertion_strategy.png" alt="insertion_strategy.png"></div>
2707
2708      <ul>
2709 <li><b>Replace current project</b>
2710 <img src="loadmode_new.png" alt="loadmode_new.png">
2711
2712      <p>All tracks in the current project are deleted and new tracks are
2713 created to match the source.  Project attributes are only changed when
2714 loading XML.  If multiple files are selected it adds new tracks for
2715 every file.
2716
2717      <li><b>Replace current project and concatenate tracks</b>
2718 <img src="loadmode_newcat.png" alt="loadmode_newcat.png">
2719
2720      <p>Same as replace current project except if multiple files are selected
2721 it concatenates the tracks of every file after the first.
2722
2723      <li><b>Append in new tracks</b>
2724 <img src="loadmode_newtracks.png" alt="loadmode_newtracks.png">
2725
2726      <p>The current project is not deleted and new tracks are created for the
2727 source.
2728
2729      <li><b>Concatenate to existing tracks</b>
2730 <img src="loadmode_cat.png" alt="loadmode_cat.png">
2731
2732      <p>The current project is not deleted and new files are concatenated to
2733 the existing tracks.
2734
2735      <li><b>Paste at insertion point</b>
2736 <img src="loadmode_paste.png" alt="loadmode_paste.png">
2737
2738      <p>The file is pasted in like a normal paste operation.
2739
2740      <li><b>Create new resources only</b>
2741 <img src="loadmode_resource.png" alt="loadmode_resource.png">
2742
2743      <p>The timeline is unchanged and new resources are created in the Resource
2744 Window.
2745
2746      <li><b>Nested EDL</b>
2747 <img src="loadmode_nested.png" alt="loadmode_nested.png">
2748
2749      <p>If the file is an EDL, the output of the EDL is pasted in like a media
2750 file.  Nested EDLs have 1 video track &amp; a number of audio tracks
2751 corresponding to the number of output channels.  They allow larger
2752 sequences composed of many smaller sequences, transitions to be applied
2753 to the output of another EDL, &amp; global processing on the output of an
2754 EDL without having to manipulate each track.
2755
2756    </ul>
2757
2758    <p>The insertion strategy is a recurring option in many of Cinelerra's
2759 functions.  In each place the options do the same thing.  With these
2760 options you can almost do all your editing by loading files.
2761
2762    <p>If you load files by passing command line arguments to Cinelerra, the
2763 files are loaded with <b>Replace current project</b> rules.
2764
2765 <div class="node">
2766 <a name="LOADING-MULTIPLE-FILES"></a>
2767 <p><hr>
2768 Previous:&nbsp;<a rel="previous" accesskey="p" href="#INSERTION-STRATEGY">INSERTION STRATEGY</a>,
2769 Up:&nbsp;<a rel="up" accesskey="u" href="#LOADING-FILES">LOADING FILES</a>
2770
2771 </div>
2772
2773 <h4 class="subsection">7.2.2 LOADING MULTIPLE FILES</h4>
2774
2775 <p>In the file selection box go to the list of files.  Select a file.  Go
2776 to another file and select it while holding down <b>CTRL</b>.  This
2777 selects one additional file.  Go to another file and select it while
2778 holding down <b>SHIFT</b>.  This selects every intervening file.  This
2779 behavior is available in most every list box.
2780
2781    <p>Select a bunch of mp3 files and <b>Replace current project and
2782 concatenate tracks</b> in the insertion strategy to create a song
2783 playlist.
2784
2785 <div class="node">
2786 <a name="LOADING-THE-BACKUP"></a>
2787 <p><hr>
2788 Next:&nbsp;<a rel="next" accesskey="n" href="#SAVING-FILES">SAVING FILES</a>,
2789 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LOADING-FILES">LOADING FILES</a>,
2790 Up:&nbsp;<a rel="up" accesskey="u" href="#LOADING-AND-SAVING-FILES">LOADING AND SAVING FILES</a>
2791
2792 </div>
2793
2794 <h3 class="section">7.3 LOADING THE BACKUP</h3>
2795
2796 <p>There is one special XML file on disk at all times.  After every
2797 editing operation Cinelerra saves the current project to a backup in
2798 <b>$HOME/.bcast/backup.xml</b>.  In the event of a crash go to
2799 <b>file-&gt;load backup</b> to load the backup.  It is important after a
2800 crash to reboot Cinelerra without performing any editing operations.
2801 Loading the backup should be the first operation or you'll overwrite
2802 the backup.
2803
2804 <div class="node">
2805 <a name="SAVING-FILES"></a>
2806 <p><hr>
2807 Next:&nbsp;<a rel="next" accesskey="n" href="#RENDERING-FILES">RENDERING FILES</a>,
2808 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LOADING-THE-BACKUP">LOADING THE BACKUP</a>,
2809 Up:&nbsp;<a rel="up" accesskey="u" href="#LOADING-AND-SAVING-FILES">LOADING AND SAVING FILES</a>
2810
2811 </div>
2812
2813 <h3 class="section">7.4 SAVING FILES</h3>
2814
2815 <p>When Cinelerra saves a file it saves an edit decision list of the
2816 current project but doesn't save any media.  Go to <b>File-&gt;save
2817 as...</b>.  Select a file to overwrite or enter a new file.  Cinelerra
2818 automatically concatenates <b>.xml</b> to the filename if no
2819 <b>.xml</b> extension is given.
2820
2821    <p>The saved file contains all the project settings and locations of every
2822 edit but instead of media it contains pointers to the original media
2823 files on disk.
2824
2825    <p>For each media file the XML file stores either an absolute path or just
2826 the relative path.  If the media is in the same directory as the XML
2827 file a relative path is saved.  If it's in a different directory an
2828 absolute path is saved.
2829
2830    <p>In order to move XML files around without breaking the media linkages
2831 you either need to keep the media in the same directory as XML file
2832 forever or save the XML file in a different directory than the media
2833 and not move the media ever again.
2834
2835    <p>If you want to create an audio playlist and burn it on CD-ROM, save the
2836 XML file in the same directory as the audio files and burn the entire
2837 directory.  This keeps the media paths relative.
2838
2839    <p>XML files are useful for saving the current state before going to sleep
2840 and saving audio playlists but they're limited in that they're specific
2841 to Cinelerra.  You can't play XML files in a dedicated movie player.
2842 Realtime effects in an XML file have to be resynthesized every time you
2843 play it back.  The XML file also requires you to maintain copies of all
2844 the source assets on hard drives, which can take up space and cost a
2845 lot of electricity to spin.  For a more persistent storage of the
2846 output there's rendering.
2847
2848 <div class="node">
2849 <a name="RENDERING-FILES"></a>
2850 <p><hr>
2851 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SAVING-FILES">SAVING FILES</a>,
2852 Up:&nbsp;<a rel="up" accesskey="u" href="#LOADING-AND-SAVING-FILES">LOADING AND SAVING FILES</a>
2853
2854 </div>
2855
2856 <h3 class="section">7.5 RENDERING FILES</h3>
2857
2858 <p>Rendering takes a section of the timeline, performs all the editing,
2859 effects and compositing, and stores it in a pure movie file.  You can
2860 then delete all the source assets, play the rendered file in a movie
2861 player, or bring it back into Cinelerra for more editing.  It's very
2862 difficult to retouch any editing decisions in the pure movie file,
2863 however, so keep the original assets and XML file around several days
2864 after you render it.
2865
2866    <p>All rendering operations are based on a region of the timeline to be
2867 rendered.  You need to define this region on the timeline.  The
2868 navigation section describes methods of defining regions.
2869 See <a href="#NAVIGATING-THE-PROJECT">NAVIGATING THE PROJECT</a>.  The rendering functions define the
2870 region based on a set of rules.  When a region is highlighted or in/out
2871 points are set, the affected region is rendered.  When no region is
2872 highlighted, everything after the insertion point is rendered.  Merely
2873 by positioning the insertion point at the beginning of a track and
2874 unsetting all in/out points, the entire track is rendered.
2875
2876 <ul class="menu">
2877 <li><a accesskey="1" href="#SINGLE-FILE-RENDERING">SINGLE FILE RENDERING</a>:       Rendering a single file
2878 <li><a accesskey="2" href="#BATCH-RENDERING">BATCH RENDERING</a>:             Rendering several files unattended
2879 <li><a accesskey="3" href="#THE-RENDER-FARM">THE RENDER FARM</a>:             Rendering using many computers
2880 <li><a accesskey="4" href="#COMMAND-LINE-RENDERING">COMMAND LINE RENDERING</a>:      Rendering from the command line without a GUI
2881 </ul>
2882
2883 <div class="node">
2884 <a name="SINGLE-FILE-RENDERING"></a>
2885 <p><hr>
2886 Next:&nbsp;<a rel="next" accesskey="n" href="#BATCH-RENDERING">BATCH RENDERING</a>,
2887 Up:&nbsp;<a rel="up" accesskey="u" href="#RENDERING-FILES">RENDERING FILES</a>
2888
2889 </div>
2890
2891 <h4 class="subsection">7.5.1 SINGLE FILE RENDERING</h4>
2892
2893 <p>The fastest way to get media to disk is to use the single file
2894 rendering function.
2895
2896    <p>Go to <b>File-&gt;render</b> to bring up the render dialog.  Select the
2897 magnifying glass <img src="magnify.png" alt="magnify.png"> to bring up a file selection dialog.  This determines
2898 the filename to write the rendered file to and the encoding parameters.
2899
2900    <p>In the render dialog select a format from the <b>File Format</b> menu.
2901 The format of the file determines whether you can render audio or video
2902 or both.  Select the <b>Render audio tracks</b> toggle to generate
2903 audio tracks and <b>Render video tracks</b> to generate video tracks.
2904
2905    <p>Select the wrench <img src="wrench.png" alt="wrench.png"> next to each toggle to set compression
2906 parameters.  If the file format can't store audio or video the
2907 compression parameters will be blank.  If <b>Render audio tracks</b> or
2908 <b>Render video tracks</b> is selected and the file format doesn't
2909 support it, trying to render will pop up an error.
2910
2911    <p>The <b>Create new file at each label</b> option causes a new file to be
2912 created when every label in the timeline is encountered.  This is
2913 useful for dividing long audio recordings into individual tracks.  When
2914 using the renderfarm, <b>Create new file at each label</b> causes one
2915 renderfarm job to be created at every label instead of using the
2916 internal load balancing algorithm to space jobs.
2917
2918    <p>When <b>Create new file at each label</b> is selected, a new filename
2919 is created for every output file.  If the filename given in the render
2920 dialog has a 2 digit number in it, the 2 digit number is overwritten
2921 with a different incremental number for every output file.  If no 2
2922 digit number is given, Cinelerra automatically concatenates a number to
2923 the end of the given filename for every output file.
2924
2925    <p>In the filename <b>/hmov/track01.wav</b> the <b>01</b> would be
2926 overwritten for every output file.  The filename
2927 <b>/hmov/track.wav</b>; however, would become <b>/hmov/track.wav001</b>
2928 and so on and so forth.  Filename regeneration is only used when either
2929 renderfarm mode is active or creating new files for every label is
2930 active.
2931
2932    <p>Finally the render dialog lets you select an insertion mode.  The
2933 insertion modes are the same as with loading files.  In this case if
2934 you select <b>insert nothing</b> the file will be written out to disk
2935 without changing the current project.  For other insertion strategies
2936 be sure to prepare the timeline to have the output inserted at the
2937 right position before the rendering operation is finished.
2938 See <a href="#EDITING">EDITING</a>.  Editing describes how to cause output to be inserted
2939 at the right position.
2940
2941    <p>It should be noted that even if you only have audio or only have video
2942 rendered, a <b>paste</b> insertion strategy will behave like a normal
2943 paste operation, erasing any selected region of the timeline and
2944 pasting just the data that was rendered.  If you render only audio and
2945 have some video tracks armed, the video tracks will get truncated while
2946 the audio output is pasted into the audio tracks.
2947
2948 <div class="node">
2949 <a name="BATCH-RENDERING"></a>
2950 <p><hr>
2951 Next:&nbsp;<a rel="next" accesskey="n" href="#THE-RENDER-FARM">THE RENDER FARM</a>,
2952 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SINGLE-FILE-RENDERING">SINGLE FILE RENDERING</a>,
2953 Up:&nbsp;<a rel="up" accesskey="u" href="#RENDERING-FILES">RENDERING FILES</a>
2954
2955 </div>
2956
2957 <h4 class="subsection">7.5.2 BATCH RENDERING</h4>
2958
2959 <p>If you want to render many projects to media files without having to
2960 repeatedly attend to the <b>Render</b> dialog, <b>batch rendering</b> is the
2961 function to use.  In this function, you specify many EDL files to
2962 render and the unique output files for each.  Then Cinelerra loads each
2963 EDL file and renders it automatically, without any user intervention.
2964 Each EDL file and its output to be rendered is called a <b>batch</b>.
2965 This allows a huge amount of media to be processed and greatly
2966 increases the value of an expensive computer.
2967
2968    <p>The first thing to do when preparing to do batch rendering is define
2969 projects to be rendered.  The batch renderer requires a separate EDL
2970 file for every batch to be rendered.  Set up a project and define the
2971 region to be rendered either by highlighting it, setting in/out points
2972 around it, or positioning the insertion point before it.  Then save the
2973 project as an EDL.  Define as many projects as needed this way.  The
2974 batch renderer takes the active region from the EDL file for rendering.
2975
2976    <p>With all the EDL files prepared with active regions, go to
2977 <b>File-&gt;batch render</b>.  This brings up the batch rendering dialog.
2978 The interface for batch rendering is a bit more complex than for single
2979 file rendering.
2980
2981    <p>A list of batches must be defined before starting a batch rendering
2982 operation.  The table of batches appears on the bottom of the batch
2983 render dialog and is called <b>batches to render</b>.  Above this are
2984 the configuration parameters for a single batch.
2985
2986    <p>Set the <b>output path</b>, <b>file format</b>, <b>Audio</b>, <b>Video</b>, and
2987 <b>Create new file at each label</b> parameters as if it was a single
2988 file.  These parameters apply to only one batch.  In addition to the
2989 standard rendering parameters, you must select the source EDL to use in
2990 the batch.  Do this by setting the <b>EDL path</b>.
2991
2992    <p>If the <b>batches to render</b> list is empty or nothing is highlighted,
2993 click <b>New</b> to create a new batch.  The new batch will contain all
2994 the parameters you just set.
2995
2996    <p>Repeatedly press the <b>New</b> button to create more batches with the
2997 same parameters.  Highlight any batch and edit the configuration on the
2998 top of the batch render window.  The highlighted batch is always
2999 synchronized to the information displayed.
3000
3001    <p>Click and drag batches to change the order in which they're rendered.
3002 Hit <b>delete</b> to permanently remove the highlighted batch.
3003
3004    <p>In the list box is a column which enables or disables the batch.  This
3005 way batches can be skipped without being deleted.  Click on the
3006 <b>Enabled</b> column in the list box to enable or disable a batch.  If it
3007 is checked, the batch is rendered.  If it is blank, the batch is
3008 skipped.
3009
3010    <p>The other columns in the batch list are informative.
3011
3012      <ul>
3013 <li><b>Output</b> The output path of the batch.
3014 <li><b>EDL</b> The source EDL of the batch.
3015 <li><b>Elapsed</b> The amount of time taken to render the batch if it is finished.
3016
3017    </ul>
3018
3019    <p>To start rendering from the first enabled batch, hit <b>Start</b>.
3020
3021    <p>Once rendering, the main window shows the progress of the batch.  Once
3022 the batch finishes, the elapsed column in the batch list is updated and
3023 the next batch is rendered until all the enabled batches are finished.
3024 The currently rendering batch is always highlighted red.
3025
3026    <p>To stop rendering before the batches are finished without closing the
3027 batch render dialog, hit <b>Stop</b>.
3028
3029    <p>To stop rendering before the batches are finished and close the batch
3030 render dialog, hit <b>Cancel</b>.
3031
3032    <p>To exit the batch render dialog whether or not anything is being
3033 rendered, hit <b>Cancel</b>.
3034
3035 <div class="node">
3036 <a name="THE-RENDER-FARM"></a>
3037 <p><hr>
3038 Next:&nbsp;<a rel="next" accesskey="n" href="#COMMAND-LINE-RENDERING">COMMAND LINE RENDERING</a>,
3039 Previous:&nbsp;<a rel="previous" accesskey="p" href="#BATCH-RENDERING">BATCH RENDERING</a>,
3040 Up:&nbsp;<a rel="up" accesskey="u" href="#RENDERING-FILES">RENDERING FILES</a>
3041
3042 </div>
3043
3044 <h4 class="subsection">7.5.3 THE RENDER FARM</h4>
3045
3046 <p>When bicubic interpolation and HDTV was first done on Cinelerra, the
3047 time needed to produce the simplest output became unbearable even on
3048 the fastest dual 1.7Ghz Xeon of the time.  Renderfarm support even in
3049 the simplest form brings HDTV times back in line with SD while making
3050 SD faster than realtime.
3051
3052    <p>While the renderfarm interface isn't spectacular, it's simple enough to
3053 use inside an editing suite with less than a dozen nodes without going
3054 through the same amount of hassle you would with a several hundred node
3055 farm.  Renderfarm is invoked transparently for all file-&gt;render
3056 operations when it is enabled in the preferences.
3057
3058    <p>Cinelerra divides the selected region of the timeline into a certain
3059 number of jobs which are then dispatched to the different nodes
3060 depending on the load balance.  The nodes process the jobs and write
3061 their output to individual files on the filesystem.  The output files
3062 are not concatenated.  It's important for all the nodes to have access
3063 to the same filesystem on the same mount point for assets.
3064
3065    <p>If a node can't access an input asset it'll display error messages to
3066 its console but probably not die.  If it can't access an output asset
3067 it'll cause the rendering to abort.
3068
3069    <p>It should be noted that in the render dialog, the <b>Create new file at
3070 each label</b> option causes a new renderfarm job to be created at each
3071 label instead of by the load balancer.  If this option is selected when
3072 no labels exist, only one job will be created.
3073
3074    <p>A Cinelerra renderfarm is organized into a master node and any number
3075 of slave nodes.  The master node is the computer which is running the
3076 GUI.  The slave nodes are anywhere else on the network and are run from
3077 the command line.  Run a slave node from the command line with
3078
3079    <p><b>cinelerra -d</b>
3080
3081    <p>That is the simplest configuration.  Type <b>cinelerra -h</b> to see more
3082 options.  The default port number may be overridden by passing a port
3083 number after the -d.
3084
3085    <p>Most of the time you'll want to bring in the rendered output and fine
3086 tune the timing on the timeline.  Also some file formats like MPEG
3087 can't be direct copied.  Because of this, the jobs are left in
3088 individual files.
3089
3090    <p>You can load these by creating a new track and specifying
3091 <b>concatenate to existing tracks</b> in the load dialog.  Files which
3092 support direct copy can be concatenated into a single file by rendering
3093 to the same file format with renderfarm disabled.  Also to get direct
3094 copy, the track dimensions, output dimensions, and asset dimensions
3095 must be equal.
3096
3097    <p>MPEG files or files which don't support direct copy have to be
3098 concatenated with a command line utility.  MPEG files can be
3099 concatenated with <b>cat</b>.
3100
3101    <p>Configuration of the renderfarm is described in the configuration
3102 chapter See <a href="#RENDERFARM">RENDERFARM</a>.  The slave nodes traditionally read and
3103 write data to a common filesystem over a network, thus they don't need
3104 hard drives.
3105
3106    <p>Ideally all the nodes on the renderfarm have similar CPU performance.
3107 Cinelerra load balances on a first come first serve basis.  If the last
3108 segment is dispatched to the slowest node, all the fastest nodes may
3109 end up waiting for the slowest node to finish while they themselves
3110 could have rendered it faster.
3111
3112 <div class="node">
3113 <a name="COMMAND-LINE-RENDERING"></a>
3114 <p><hr>
3115 Previous:&nbsp;<a rel="previous" accesskey="p" href="#THE-RENDER-FARM">THE RENDER FARM</a>,
3116 Up:&nbsp;<a rel="up" accesskey="u" href="#RENDERING-FILES">RENDERING FILES</a>
3117
3118 </div>
3119
3120 <h4 class="subsection">7.5.4 COMMAND LINE RENDERING</h4>
3121
3122 <p>The command line rendering facility consists of a way to load the
3123 current set of batch rendering jobs and process them without a GUI.
3124 This is useful if you're planning on crashing X repeatedly or want to
3125 do rendering on the other side of a low bandwidth network.  You might
3126 have access to a supercomputer in India but still be stuck in America,
3127 exhiled you might say.  A command line interface is ideal for this.
3128
3129    <p>To perform rendering from the command line, first run Cinelerra in
3130 graphical mode.  Go to <b>file-&gt;batch render</b>.  Create the batches you
3131 intend to render in the batch window and close the window.  This saves
3132 the batches in a file.  Set up the desired renderfarm attributes in
3133 <b>settings-&gt;preferences</b> and exit Cinelerra.  These settings are used
3134 the next time command line rendering is used.
3135
3136    <p>On the command line run
3137
3138    <p><b>cinelerra -r</b>
3139
3140    <p>to processes the current batch jobs without a GUI.  Setting up all the
3141 parameters for this operation is hard.  That's why the command line
3142 aborts if any output files already exist.
3143
3144    <p>Other parameters exist for specifying alternative files for the
3145 preferences and the batches.  Attempting to use anything but the
3146 defaults is very involved so it hasn't been tested.
3147
3148 <div class="node">
3149 <a name="NAVIGATING-THE-PROJECT"></a>
3150 <p><hr>
3151 Next:&nbsp;<a rel="next" accesskey="n" href="#EDITING">EDITING</a>,
3152 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LOADING-AND-SAVING-FILES">LOADING AND SAVING FILES</a>,
3153 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
3154
3155 </div>
3156
3157 <h2 class="chapter">8 NAVIGATING THE PROJECT</h2>
3158
3159 <p>The thing you want to do most of the time is get to a certain time and
3160 place in the media.  Internally the media is organized into tracks.
3161 Each track extends across time.  Navigation involves both getting to a
3162 track and getting to a certain time in the track.
3163
3164 <ul class="menu">
3165 <li><a accesskey="1" href="#NAVIGATING-THE-PROGRAM-WINDOW">NAVIGATING THE PROGRAM WINDOW</a>
3166 <li><a accesskey="2" href="#NAVIGATING-THE-VIEWER-AND-COMPOSITOR">NAVIGATING THE VIEWER AND COMPOSITOR</a>
3167 <li><a accesskey="3" href="#NAVIGATING-THE-RESOURCES">NAVIGATING THE RESOURCES</a>
3168 <li><a accesskey="4" href="#USING-THE-TRANSPORT-CONTROLS">USING THE TRANSPORT CONTROLS</a>
3169 <li><a accesskey="5" href="#USING-BACKGROUND-RENDERING">USING BACKGROUND RENDERING</a>
3170 </ul>
3171
3172 <div class="node">
3173 <a name="NAVIGATING-THE-PROGRAM-WINDOW"></a>
3174 <p><hr>
3175 Next:&nbsp;<a rel="next" accesskey="n" href="#NAVIGATING-THE-VIEWER-AND-COMPOSITOR">NAVIGATING THE VIEWER AND COMPOSITOR</a>,
3176 Up:&nbsp;<a rel="up" accesskey="u" href="#NAVIGATING-THE-PROJECT">NAVIGATING THE PROJECT</a>
3177
3178 </div>
3179
3180 <h3 class="section">8.1 NAVIGATING THE PROGRAM WINDOW</h3>
3181
3182 <p>The program window contains many features for navigation and displays
3183 the timeline as it is structured in memory: tracks stacked vertically
3184 and extending across time horizontall.  The horizontal scroll bar
3185 allows you to scan across time.  The vertical scroll bar allows you to
3186 scan across tracks.
3187
3188    <p>Below the timeline you'll find the zoom panel.  The zoom panel contains
3189 values for <b>sample zoom</b>, <b>amplitude</b>, <b>track zoom</b>, and
3190 <b>curve zoom</b>.  These values in addition to the scrollbars are the
3191 main tools for positioning the timeline.
3192
3193    <pre class="sp">
3194
3195 </pre>
3196
3197 <img src="zoompanel.png" alt="zoompanel.png">
3198
3199    <p>Changing the <b>sample zoom</b> causes the amount of time visible to
3200 change.  <b>If your mouse has a wheel and it works in X11 go over
3201 the tumblers and use the wheel to zoom in and out.</b>
3202
3203    <p>The <b>amplitude</b> only affects audio.  It determines how big the
3204 waveform is if the waveform is drawn.
3205
3206    <p>The <b>track zoom</b> affects all tracks.  It determines the height of
3207 each track.  If you change the track zoom the amplitude zoom
3208 compensates so  audio waveforms look proportional.
3209
3210    <p>The <b>curve zoom</b> affects the curves in all the tracks.  It
3211 determines the amplitude and offset of the curves.  The tumbler affects
3212 curve amplitude but the only way to change curve offset is to use the
3213 <b>fit curves</b> button.  <img src="fit_curves.png" alt="fit_curves.png">
3214
3215    <p>In addition to the graphical tools, you'll probably more often use the
3216 keyboard to navigate.  Use <b>PAGE UP</b> and <b>PAGE DOWN</b> to
3217 scroll up and down the tracks.
3218
3219    <p>Use the <b>LEFT</b> and <b>RIGHT</b> arrows to move across time in
3220 small increments.  You'll often need to scroll beyond the end of the
3221 timeline but scrollbars won't let you do it.  Instead use the
3222 <b>RIGHT</b> arrow to scroll past the end of timeline.
3223
3224    <p>Use the <b>HOME</b> and <b>END</b> keys to instantly go to the
3225 beginning or end of the timeline.  In <b>I-beam</b> mode, hold down
3226 shift while pressing <b>HOME</b> or <b>END</b> to select the region of
3227 the timeline between the insertion point and the key pressed.
3228
3229    <p>Use the <b>UP</b> and <b>DOWN</b> arrows to change the sample zoom by a
3230 power of 2.
3231
3232    <p><b>CTRL-UP</b> and <b>CTRL-DOWN</b> cause the amplitude zoom to change.
3233
3234    <p><b>CTRL-PGUP</b> and <b>CTRL-PGDOWN</b> cause the track zoom to change.
3235
3236    <p><b>ALT-UP</b> and <b>ALT-DOWN</b> cause the curve amplitude to change.
3237
3238 <ul class="menu">
3239 <li><a accesskey="1" href="#THE-INSERTION-POINT">THE INSERTION POINT</a>
3240 <li><a accesskey="2" href="#THE-IN_002fOUT-POINTS">THE IN/OUT POINTS</a>
3241 <li><a accesskey="3" href="#USING-LABELS-IN-THE-PROGRAM-WINDOW">USING LABELS IN THE PROGRAM WINDOW</a>
3242 </ul>
3243
3244 <div class="node">
3245 <a name="THE-INSERTION-POINT"></a>
3246 <p><hr>
3247 Next:&nbsp;<a rel="next" accesskey="n" href="#THE-IN_002fOUT-POINTS">THE IN/OUT POINTS</a>,
3248 Up:&nbsp;<a rel="up" accesskey="u" href="#NAVIGATING-THE-PROGRAM-WINDOW">NAVIGATING THE PROGRAM WINDOW</a>
3249
3250 </div>
3251
3252 <h4 class="subsection">8.1.1 THE INSERTION POINT</h4>
3253
3254 <p>By default you'll see a flashing insertion point in the program window
3255 the first time you boot it up.  This is where new media is pasted onto
3256 the timeline.  It's also the starting point of all playback
3257 operations.  When rendering, it defines the region of the timeline to
3258 be rendered.
3259
3260    <p>The insertion point is normally moved by clicking inside the timebar.
3261 Any region of the timebar not obscured by labels and in/out points is a
3262 hotspot for repositioning the insertion point.
3263
3264    <pre class="sp">
3265
3266 </pre>
3267 <img src="main_timebar.png" alt="main_timebar.png">
3268 <b>The main timebar</b>
3269
3270    <p>The insertion point also can be moved by clicking in the timeline
3271 itself, but not always.  The insertion point has two modes of
3272 operation:
3273
3274      <ul>
3275 <li>drag and drop mode
3276
3277      <li>cut and paste mode
3278
3279    </ul>
3280
3281    <p>The mode of operation is determined by selecting the arrow or the
3282 i-beam in the buttonbar.
3283
3284    <pre class="sp">
3285
3286 </pre>
3287 <img src="editing_mode.png" alt="editing_mode.png">
3288 <b>The editing mode buttons</b>
3289
3290    <p>If the arrow is highlighted it enables <b>drag and drop</b> mode.  In
3291 drag and drop mode, clicking in the timeline doesn't reposition the
3292 insertion point.  Instead it selects an entire edit.  Dragging in the
3293 timeline repositions the edit, snapping it to other edit boundaries.
3294 This is normally useful for reordering audio playlists and moving
3295 effects around.
3296
3297    <p>If the i-beam is highlighted it enables <b>cut and paste mode</b>.  In
3298 cut and paste mode clicking in the timeline repositions the insertion
3299 point.  Dragging in the timeline highlights a region.  The highlighted
3300 region becomes the playback range during the next playback operation,
3301 the rendered range during the next render operation, and the region
3302 affected by cut and paste operations.
3303
3304    <p><b>Shift-clicking</b> in the timeline extends the highlighted region.
3305
3306    <p><b>Double-clicking</b> in the timeline selects the entire edit the
3307 cursor is over.
3308
3309    <p>It should be noted that when moving the insertion point and selecting
3310 regions, the positions are either aligned to frames or aligned to
3311 samples.  When editing video you'll want to align to frames.  When
3312 editing audio you'll want to align to samples.  This is set in
3313 <b>settings-&gt;align cursor on frames</b>.
3314
3315    <p>If the highlighted region is the region affected by cut and paste
3316 operations, how do I cut and paste in <b>drag and drop</b> mode?  In
3317 this case you need to set <b>in/out points</b> to define an affected region.
3318
3319 <div class="node">
3320 <a name="THE-IN%2fOUT-POINTS"></a>
3321 <a name="THE-IN_002fOUT-POINTS"></a>
3322 <p><hr>
3323 Next:&nbsp;<a rel="next" accesskey="n" href="#USING-LABELS-IN-THE-PROGRAM-WINDOW">USING LABELS IN THE PROGRAM WINDOW</a>,
3324 Previous:&nbsp;<a rel="previous" accesskey="p" href="#THE-INSERTION-POINT">THE INSERTION POINT</a>,
3325 Up:&nbsp;<a rel="up" accesskey="u" href="#NAVIGATING-THE-PROGRAM-WINDOW">NAVIGATING THE PROGRAM WINDOW</a>
3326
3327 </div>
3328
3329 <h4 class="subsection">8.1.2 THE IN/OUT POINTS</h4>
3330
3331 <p>In both editing modes you can set in/out points.  The in/out points
3332 define the affected region.  In drag and drop mode they are the only
3333 way to define an affected region.  In both cut and paste mode and drag
3334 and drop mode the highlighted area overrides the in/out points.  If a
3335 highlighted area and in/out points are set, the highlighted area is
3336 affected by editing operations and the in/out points are ignored.  If
3337 no region is highlighted, the in/out points are used.
3338
3339    <p>Normally, in/out points do not affect the playback region.  Only if you
3340 hold down CTRL while issuing a playback command do the in/out points
3341 determine the playback region.
3342
3343    <p>To set in/out points go to the timebar and position the insertion point
3344 somewhere.  Hit the <img src="in_point_button.png" alt="in_point_button.png"> <b>in point button</b>.  Go
3345 to a position after the in point and hit the <img src="out_point_button.png" alt="out_point_button.png">
3346 <b>out point button</b>.
3347
3348    <pre class="sp">
3349
3350 </pre>
3351 <img src="inout_points.png" alt="inout_points.png"> <b>Timebar with in/out points set</b>.
3352
3353    <p>Select either the in point or the out point and the insertion point
3354 jumps to that location.  After selecting an in point, if you hit the
3355 <b>in point button</b> the in point will be deleted.  After selecting
3356 an out point, if you hit the <b>out point button</b> the out point will
3357 be deleted.
3358
3359    <p>If you select a region somewhere else while in/out points already
3360 exist, the existing points will be repositioned when you hit the in/out
3361 buttons.
3362
3363    <p><b>Shift-clicking</b> on an in/out point extends the highlighted region
3364 to that point.
3365
3366    <p>Instead of using the button bar you can use the <b>[</b> and <b>]</b>
3367 keys to toggle in/out points.
3368
3369    <p>The insertion point and the in/out points allow you to define an
3370 affected region but they don't let you jump to exact points on the
3371 timeline very easily.  For this purpose there are labels.
3372
3373 <div class="node">
3374 <a name="USING-LABELS-IN-THE-PROGRAM-WINDOW"></a>
3375 <p><hr>
3376 Previous:&nbsp;<a rel="previous" accesskey="p" href="#THE-IN_002fOUT-POINTS">THE IN/OUT POINTS</a>,
3377 Up:&nbsp;<a rel="up" accesskey="u" href="#NAVIGATING-THE-PROGRAM-WINDOW">NAVIGATING THE PROGRAM WINDOW</a>
3378
3379 </div>
3380
3381 <h4 class="subsection">8.1.3 USING LABELS IN THE PROGRAM WINDOW</h4>
3382
3383 <p>Labels are an easy way to set exact locations on the timeline you want
3384 to jump to.  When you position the insertion point somewhere and hit
3385 the <img src="label_button.png" alt="label_button.png"> <b>label button</b> a new label appears on the
3386 timeline.
3387
3388    <pre class="sp">
3389
3390 </pre>
3391 <img src="timebar_label.png" alt="timebar_label.png"> <b>Timebar with a label on it</b>
3392
3393    <p>No matter what the zoom settings are, clicking on the label positions
3394 the insertion point exactly where you set it.  Hitting the label button
3395 again when a label is selected deletes it.
3396
3397    <p><b>Shift-clicking</b> on a label extends the highlighted region.
3398
3399    <p><b>Double-clicking</b> between two labels highlights the region between
3400 the labels.
3401
3402    <p>Hitting the <b>l</b> key has the same effect as the label button.
3403
3404    <p>If you hit the label button when a region is highlighted, two labels
3405 are toggled at each end of the highlighted region.  If one end already
3406 has a label, then the existing label is deleted and a label is created
3407 at the opposite end.
3408
3409    <p>Labels can reposition the insertion point when they are selected but
3410 they can also be traversed with the <img src="label_traversal.png" alt="label_traversal.png"> <b>label
3411 traversal</b> buttons.  When a label is out of view, the label traversal
3412 buttons reposition the timeline so the label is visible.  There are
3413 keyboard shortcuts for label traversal, too.
3414
3415    <p><b>CTRL-LEFT</b> repositions the insertion point on the previous label.
3416
3417    <p><b>CTRL-RIGHT</b> repositions the insertion point on the next label.
3418
3419    <p>With label traversal you can quickly seek back and forth on the
3420 timeline but you can also select regions.
3421
3422    <p><b>SHIFT-CTRL-LEFT</b> extends the highlighted region to the previous
3423 label.
3424
3425    <p><b>SHIFT-CTRL-RIGHT</b> extends the highlighted region to the next label.
3426
3427    <p>Manually hitting the label button or <b>l</b> key over and over again
3428 to delete a series of labels can get tedious.  For deleting a set of
3429 labels, first highlight a region and second use the <b>Edit-&gt;Clear
3430 labels</b> function.  If in/out points exist, the labels between the
3431 in/out points are cleared and the highlighted region ignored.
3432
3433 <div class="node">
3434 <a name="NAVIGATING-THE-VIEWER-AND-COMPOSITOR"></a>
3435 <p><hr>
3436 Next:&nbsp;<a rel="next" accesskey="n" href="#NAVIGATING-THE-RESOURCES">NAVIGATING THE RESOURCES</a>,
3437 Previous:&nbsp;<a rel="previous" accesskey="p" href="#NAVIGATING-THE-PROGRAM-WINDOW">NAVIGATING THE PROGRAM WINDOW</a>,
3438 Up:&nbsp;<a rel="up" accesskey="u" href="#NAVIGATING-THE-PROJECT">NAVIGATING THE PROJECT</a>
3439
3440 </div>
3441
3442 <h3 class="section">8.2 NAVIGATING THE VIEWER AND COMPOSITOR</h3>
3443
3444 <p>The navigation features of the Viewer and Compositor behave very
3445 similarly.  Each has a timebar and slider below the video output.  The
3446 timebar and slider are critical for navigation.
3447
3448    <pre class="sp">
3449
3450 </pre>
3451
3452 <img src="timebarslider.png" alt="timebarslider.png">
3453
3454    <p>The timebar represents the entire time covered by the program.  When
3455 you define labels and in/out points it defines those, too.  Finally the
3456 timebar defines a region known as the <b>preview region</b>.
3457
3458    <p>The <b>preview region</b> is the region of the timeline which the
3459 slider effects.  The slider only covers the time covered by the preview
3460 region.  By using a preview region inside the entire program and using
3461 the slider inside the preview region you can quickly and precisely seek
3462 in the compositor and viewer.
3463
3464    <p>When you replace the current project with a file the preview region
3465 automatically resizes to cover the entire file.  When you append data
3466 or change the size of the current project, the preview region stays the
3467 same size and shrinks.  Therefore, you need to resize the preview
3468 region.
3469
3470    <p>Load a file and then slide around it using the compositor slider.  The
3471 insertion point in the main window follows the compositor.  Move the
3472 pointer over the compositor's timebar until it turns into a left resize
3473 pointer.  The click and drag right.  The preview region should have
3474 changed and the slider resized proportionally.
3475
3476    <p>Go to the right of the timebar until a right resize pointer appears.
3477 Drag left so the preview region shrinks.
3478
3479    <p>Go to the center of the preview region in the timebar and drag it
3480 around to convince yourself if can be moved.
3481
3482    <pre class="sp">
3483
3484 </pre>
3485
3486 <img src="previewregion.png" alt="previewregion.png">
3487
3488    <p><b>Preview region in compositor</b>
3489
3490    <p>If you go to the slider and slide it around with the preview region
3491 shrunk, you'll see the slider only affects the preview region.  The
3492 timebar and slider in the viewer window work exactly the same.
3493
3494    <p>Labels and in/out points are fully supported in the viewer and
3495 compositor.  The only difference between the viewer and compositor is
3496 the compositor reflects the state of the program while the viewer
3497 reflects the state of a clip but not the program.
3498
3499    <p>When you hit the <b>label button</b> in the compositor, the label
3500 appears both in the compositor timebar and the program timebar.
3501
3502    <p>When you select a label or in/out point in the compositor, the program
3503 window jumps to that position.
3504
3505    <pre class="sp">
3506
3507 </pre>
3508 <img src="viewer_labels.png" alt="viewer_labels.png"> <b>Labels and in/out points in the viewer</b>.
3509
3510    <p>In the viewer and compositor, labels and in/out points are displayed in
3511 the timebar.  Instead of displaying just a region of the program, the
3512 timebar displays the entire program here.
3513
3514    <p>Like the Program window, the Compositor has a zoom capability.  First,
3515 the pulldown menu on the bottom of the compositor window has a number
3516 of zoom options.  When set to <b>Auto</b> the video is zoomed to match
3517 the compositor window size as closely as possible.  When set to any
3518 other percentage, the video is zoomed a power of 2 and scrollbars can
3519 be used to scroll around the output.  When the video is zoomed bigger
3520 than the window size, not only do scrollbars scan around it but
3521 <b>middle mouse button</b> dragging in the video output scans around
3522 it.  This is exactly when The Gimp does.
3523
3524    <p>Furthermore, the zoom <img src="magnify.png" alt="magnify.png"> toggle causes the Compositor
3525 window to enter zoom mode.  In zoom mode, clicking in the video output
3526 zooms in while <b>ctrl-clicking</b> in the video output zooms out.  If
3527 you have a wheel mouse, rotating the wheel zooms in or out too.
3528
3529    <p>Zooming in or out with the zoom tool does not change the rendered
3530 output, mind you.  It's merely for scrutinizing video or fitting it in
3531 the desktop.
3532
3533 <div class="node">
3534 <a name="NAVIGATING-THE-RESOURCES"></a>
3535 <p><hr>
3536 Next:&nbsp;<a rel="next" accesskey="n" href="#USING-THE-TRANSPORT-CONTROLS">USING THE TRANSPORT CONTROLS</a>,
3537 Previous:&nbsp;<a rel="previous" accesskey="p" href="#NAVIGATING-THE-VIEWER-AND-COMPOSITOR">NAVIGATING THE VIEWER AND COMPOSITOR</a>,
3538 Up:&nbsp;<a rel="up" accesskey="u" href="#NAVIGATING-THE-PROJECT">NAVIGATING THE PROJECT</a>
3539
3540 </div>
3541
3542 <h3 class="section">8.3 NAVIGATING THE RESOURCES</h3>
3543
3544 <p>The resource window is divided into two areas.  One area lists folders
3545 and another area lists folder contents.  Going into the folder list and
3546 clicking on a folder updates the contents area with the contents of
3547 that folder.
3548
3549    <p>The folder and contents can be displayed as icons or text.
3550
3551    <p><b>Right clicking</b> in the folder or contents area brings up a menu
3552 containing formatting options.  Select <b>Display text</b> to display a
3553 text listing.  Select <b>Sort items</b> to sort the contents of the
3554 folder alphabetically.
3555
3556 <div class="node">
3557 <a name="USING-THE-TRANSPORT-CONTROLS"></a>
3558 <p><hr>
3559 Next:&nbsp;<a rel="next" accesskey="n" href="#USING-BACKGROUND-RENDERING">USING BACKGROUND RENDERING</a>,
3560 Previous:&nbsp;<a rel="previous" accesskey="p" href="#NAVIGATING-THE-RESOURCES">NAVIGATING THE RESOURCES</a>,
3561 Up:&nbsp;<a rel="up" accesskey="u" href="#NAVIGATING-THE-PROJECT">NAVIGATING THE PROJECT</a>
3562
3563 </div>
3564
3565 <h3 class="section">8.4 USING THE TRANSPORT CONTROLS</h3>
3566
3567 <p>Transport controls are just as useful in navigation as they are in
3568 playing back footage, hence they are described here in the navigation
3569 section.  Each of the Viewer, Compositor, and Program windows has a
3570 transport panel.
3571
3572    <pre class="sp">
3573
3574 </pre>
3575 <img src="transport_panel.png" alt="transport_panel.png"> <b>The transport panel</b>.
3576
3577    <p>The transport panel is controlled by the keyboard as well as the
3578 graphical interface.  For each of the operations it performs, the
3579 starting position is the position of the insertion point in the Program
3580 window and the slider in the Compositor window.  The ending position is
3581 either the end or start of the timeline or the end or start of the
3582 selected region if there is one.
3583
3584    <p>The orientation of the end or start depends on the direction of
3585 playback.  If it's forward the end position is the end of the selected
3586 region.  If it's backward the end position is the start of the selected
3587 region.
3588
3589    <p>The insertion point moves to track playback.  When playback stops, the
3590 insertion point stays where playback stopped.  Thus, by playing back
3591 you change the position of the insertion point.
3592
3593    <p>The keyboard interface is usually the fastest and has more speeds.  The
3594 transport keys are arranged in a sideways <b>T</b> on the number pad.
3595
3596      <ul>
3597 <li><b>+</b> Fast reverse
3598 <li><b>6</b> Normal reverse
3599 <li><b>5</b> Slow reverse
3600 <li><b>4</b> Frame reverse
3601 <li><b>1</b> Frame forward
3602 <li><b>2</b> Slow forward
3603 <li><b>3</b> Normal forward
3604 <li><b>Enter</b> Fast forward
3605 <li><b>0</b> Stop
3606 <li><b>Spacebar</b> Normal forward
3607 </ul>
3608
3609    <p>Hitting any key on the keyboard twice pauses it.
3610
3611    <p>When using frame advance functions the behavior may seem odd.  If you
3612 frame advance forward and then frame advance backward, the displayed
3613 frame doesn't change.  This is because the playback position isn't the
3614 frame but the time between two frames.  The rendered frame is the area
3615 that the playback position crosses.  When you increment the time
3616 between two frames by one and decrement it by one, you cross the same
3617 frame both times and so the same frame is displayed.
3618
3619    <p>The transport behavior changes if you hold down CTRL when issuing any
3620 of the transport commands.  This causes the starting point to be the in
3621 point if playing forward and the out point if playing backward.  If
3622 playing forward, the out point becomes the ending point and if playing
3623 backward, the in point becomes the ending point.  If no in/out points
3624 are specified, the behavior falls back to using the insertion point and
3625 track boundaries as the starting and ending points.
3626
3627 <div class="node">
3628 <a name="USING-BACKGROUND-RENDERING"></a>
3629 <p><hr>
3630 Previous:&nbsp;<a rel="previous" accesskey="p" href="#USING-THE-TRANSPORT-CONTROLS">USING THE TRANSPORT CONTROLS</a>,
3631 Up:&nbsp;<a rel="up" accesskey="u" href="#NAVIGATING-THE-PROJECT">NAVIGATING THE PROJECT</a>
3632
3633 </div>
3634
3635 <h3 class="section">8.5 USING BACKGROUND RENDERING</h3>
3636
3637 <p>Background rendering allows impossibly slow effects to play back in
3638 realtime shortly after the effect is pasted in the timeline.  It
3639 continuously renders temporary output.  When renderfarm is enabled,
3640 background rendering uses the renderfarm continuously.  This way, any
3641 size video can be seen in realtime merely by creating a fast enough
3642 network with enough nodes.
3643
3644    <p>Background rendering is enabled in settings-&gt;preferences-&gt;performance.
3645 It has one interactive function: <b>settings-&gt;set background render</b>.  This
3646 sets the point where background rendering begins to where the in point
3647 is.  If any video exists, a red bar appears in the time bar showing
3648 what has been background rendered.
3649
3650    <p>It's often useful to insert an effect or a transition and then select
3651 settings-&gt;set background render right before the effect to preview it
3652 in full framerates.
3653
3654 <div class="node">
3655 <a name="EDITING"></a>
3656 <p><hr>
3657 Next:&nbsp;<a rel="next" accesskey="n" href="#USING-EFFECTS">USING EFFECTS</a>,
3658 Previous:&nbsp;<a rel="previous" accesskey="p" href="#NAVIGATING-THE-PROJECT">NAVIGATING THE PROJECT</a>,
3659 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
3660
3661 </div>
3662
3663 <h2 class="chapter">9 EDITING</h2>
3664
3665 <p>Editing comprises both the time domain and the track domain.  Since the
3666 timeline consists of a stack of tracks, you need to worry about how to
3667 sort and create tracks in addition to what time certain media appears
3668 on a track.
3669
3670    <p>In the time domain, Cinelerra offers many ways to approach the editing
3671 process.  The three main methods are two screen editing, drag and drop
3672 editing, and cut and paste editing.
3673
3674    <p>There are several concepts Cinelerra uses when editing which apply to
3675 all the methods.  The <b>timeline</b> is where all editing decisions are
3676 represented.  This is a stack of tracks in the center of the main
3677 window.  It can be scrolled up, down, left and right with the
3678 scrollbars on the right and bottom of it.  It can also be scrolled up
3679 and down with a mouse wheel.
3680
3681    <p>The <b>active region</b> is the range of time which is affected by editing
3682 commands on the timeline.  The active region is determined first by the
3683 presence of in/out points in the timeline.  If those don't exist the
3684 highlighted region is used.  If no highlighted region exists the
3685 insertion point is used as the start of the active region.  Some
3686 commands treat all the space to the right of the insertion point as
3687 active, like <b>Render</b>, while others treat the active length as 0 if no
3688 end point for the active region is defined.
3689
3690    <p>Finally, editing decisions never affect source material.  This is
3691 <b>non destructive editing</b> and it became popular with audio because it
3692 was much faster than if you had to copy all the media affected by an
3693 edit.  Editing only affects pointers to source material, so if you want
3694 to have a media file at the end of your editing session which
3695 represents the editing decisions, you need to <b>render</b> it.
3696 See <a href="#RENDERING-FILES">RENDERING FILES</a>.
3697
3698    <p>Every track on the timeline has a set of attributes on
3699 the left, the most important of which is the <b>arm track</b>
3700 attribute.
3701
3702 <ul class="menu">
3703 <li><a accesskey="1" href="#THE-PATCHBAY">THE PATCHBAY</a>:            Enabling different features on different tracks
3704 <li><a accesskey="2" href="#NUDGING-TRACKS">NUDGING TRACKS</a>:          Move entire tracks horizontally
3705 <li><a accesskey="3" href="#PANNING-TRACKS">PANNING TRACKS</a>:          Changing the audio output channels
3706 <li><a accesskey="4" href="#AUTOMATIC-TRACK-PANNING">AUTOMATIC TRACK PANNING</a>:   Panning tracks to common speaker arrangements
3707 <li><a accesskey="5" href="#STANDARD-AUDIO-MAPPINGS">STANDARD AUDIO MAPPINGS</a>:   Making audio panning that works on other players.
3708 <li><a accesskey="6" href="#MANIPULATING-TRACKS">MANIPULATING TRACKS</a>:     Moving whole tracks around
3709 <li><a accesskey="7" href="#TWO-SCREEN-EDITING">TWO SCREEN EDITING</a>:      Using two video windows to edit
3710 <li><a accesskey="8" href="#DRAG-AND-DROP-EDITING">DRAG AND DROP EDITING</a>:   Dragging objects to edit
3711 <li><a accesskey="9" href="#CUT-AND-PASTE-EDITING">CUT AND PASTE EDITING</a>:   Editing media like text
3712 <li><a href="#TRIMMING">TRIMMING</a>:                Changing in and out points
3713 </ul>
3714
3715 <div class="node">
3716 <a name="THE-PATCHBAY"></a>
3717 <p><hr>
3718 Next:&nbsp;<a rel="next" accesskey="n" href="#NUDGING-TRACKS">NUDGING TRACKS</a>,
3719 Up:&nbsp;<a rel="up" accesskey="u" href="#EDITING">EDITING</a>
3720
3721 </div>
3722
3723 <h3 class="section">9.1 THE PATCHBAY</h3>
3724
3725 <p>On the left of the timeline is a region affectionately known as the
3726 patchbay.  The patchbay enables features specific to each track.  All
3727 tracks have a text area for naming the track.
3728
3729    <p>All tracks have an <b>expander</b> <img src="expandpatch_checked.png" alt="expandpatch_checked.png"> for viewing
3730 more options and for viewing the effects on the track.  Click on the
3731 expander to expand or collapse the track.  If it's pointing sideways,
3732 the track is collapsed.  If it's pointing down, the track is expanded.
3733 The effects appear below the media for the track if they exist.
3734
3735    <p>All tracks have the following row of toggles for several features.
3736
3737    <pre class="sp">
3738
3739 </pre>
3740 <img src="track_attributes.png" alt="track_attributes.png">
3741 <b>Track attributes</b>
3742
3743    <p>If the toggle is colored, it is enabled.  If the toggle is the
3744 background color of most of the windows, it is disabled.  Click on the
3745 toggle to enable or disable the feature.  Several mouse operations
3746 speed up the configuration of several tracks at a time.
3747
3748    <p>Click on an attribute and drag across adjacent tracks to copy the same
3749 attribute to those tracks.
3750
3751    <p>Hold down <b>shift</b> while clicking a track's attribute to enable the
3752 attribute in the current track and toggle the attribute in all the
3753 other tracks.
3754
3755    <p>Hold down <b>shift</b> while clicking an attribute.  Click until all the
3756 tracks except the selected one are disabled.  Then drag the cursor over
3757 the adjacent track to enable the attribute in the adjacent track.
3758
3759    <p>The other attributes affect the output of the track.
3760
3761      <ul>
3762 <li>
3763 <b>Play track</b> determines whether the track is rendered or not.  If
3764 it's off, the track is not rendered.  However, if the track is chained
3765 to any other tracks, the other tracks perform all the effects in the
3766 chained track, regardless of play status.
3767      <pre class="sp">
3768
3769      </pre>
3770
3771 <li>
3772 <b>Arm track</b> determines whether the track is armed or not.   Only the
3773 <b>armed tracks</b> are affected by editing operations.  Make sure you
3774 have enough armed destination tracks when you paste or splice material
3775 or some tracks in the material will get left out.
3776
3777      <p>In addition to restricting editing operations, the armed tracks in
3778 combination with the active region determine where material is inserted
3779 when loading files.  If the files are loaded with one of the insertion
3780 strategies which doesn't delete the existing project, the armed tracks
3781 will be used as destination tracks.
3782
3783      <p>Press <b>Tab</b> while the cursor is anywhere over a track to toggle the
3784 track arming status.
3785
3786      <p>Press <b>Shift-Tab</b> while the cursor is over a track to toggle the
3787 arming status of every other track.
3788
3789      <li>
3790 <b>Gang fader</b> causes the fader to track the movement of whatever other
3791 fader you're adjusting.  A fader is only ganged if the <b>arm track</b> is
3792 also on.  This is normally used to adjust audio levels on all the
3793 tracks simultaneously.  Gang also causes <b>Nudge</b> parameters to
3794 synchronise across all the ganged tracks.
3795
3796      <pre class="sp">
3797
3798      </pre>
3799
3800 <li>
3801 <b>Draw media</b> determines if picons or waveforms are drawn on the
3802 track.  By default, some file formats load with this off while other
3803 file formats load with it on.  This depends on whether the file format
3804 takes a long time to draw on the timeline.  Merely set it to on if you
3805 want to see picons for any file format.
3806      <pre class="sp">
3807
3808      </pre>
3809
3810 <li>
3811 <b>Mute track</b> causes the output to be thrown away once the track is
3812 completely rendered.  This happens whether or not <b>play track</b> is
3813 on.  If the track is part of an effect chain, the output of the effect
3814 chain track is overlayed on the final output even though it's routed
3815 back to another track.  Mute track is used to keep the effect chain
3816 track from overlapping the output of the source track.
3817      <pre class="sp">
3818
3819      </pre>
3820
3821 <li>
3822 <b>Fader</b> All tracks have a fader, but the units of each fader depend
3823 on whether it's audio or video.  Click and drag the fader to fade the
3824 track in and out.  If it is ganged to other tracks of the same media
3825 type, with the <b>arm</b> option enabled, the other faders should follow.
3826
3827      <p>Hold down <b>shift</b> and drag a fader to center it on 0.
3828
3829    </ul>
3830
3831 <div class="node">
3832 <a name="NUDGING-TRACKS"></a>
3833 <p><hr>
3834 Next:&nbsp;<a rel="next" accesskey="n" href="#PANNING-TRACKS">PANNING TRACKS</a>,
3835 Previous:&nbsp;<a rel="previous" accesskey="p" href="#THE-PATCHBAY">THE PATCHBAY</a>,
3836 Up:&nbsp;<a rel="up" accesskey="u" href="#EDITING">EDITING</a>
3837
3838 </div>
3839
3840 <h3 class="section">9.2 NUDGING TRACKS</h3>
3841
3842 <p>Each track has a nudge textbox in its patchbay.  You may have to expand
3843 the track to see it.  These are views of the patchbays when expanded.
3844
3845    <div class="block-image"><img src="apatches.png" alt="apatches.png"></div>
3846
3847    <p>Pan and nudge for an audio track.
3848
3849    <div class="block-image"><img src="vpatches.png" alt="vpatches.png"></div>
3850
3851    <p>Overlay mode and nudge for a video track.
3852
3853    <p>The nudge is the amount the track is shifted left or right during
3854 playback.  The track is not displayed shifted on the timeline, but it
3855 is shifted when it's played back.  This is useful for synchronizing
3856 audio with video, creating fake stereo, or compensating for an effect
3857 which shifts time, all without tampering with any edits.
3858
3859    <p>Merely enter in the amount of time to shift by to instantly shift the
3860 track.  Negative numbers make the track play later.  Positive numbers
3861 make the track play sooner.  The nudge units are either <b>seconds</b> or
3862 the native units for the track.  Select the units by <b>right clicking</b>
3863 on the nudge textbox and using the context sensitive menu.
3864
3865    <p>Nudge settings are ganged with the <b>Gang faders</b> toggle and the
3866 <b>Arm track</b> toggle.
3867
3868    <p>Use the mouse wheel over the nudge textbox to increment and decriment
3869 it.
3870
3871 <div class="node">
3872 <a name="PANNING-TRACKS"></a>
3873 <p><hr>
3874 Next:&nbsp;<a rel="next" accesskey="n" href="#AUTOMATIC-TRACK-PANNING">AUTOMATIC TRACK PANNING</a>,
3875 Previous:&nbsp;<a rel="previous" accesskey="p" href="#NUDGING-TRACKS">NUDGING TRACKS</a>,
3876 Up:&nbsp;<a rel="up" accesskey="u" href="#EDITING">EDITING</a>
3877
3878 </div>
3879
3880 <h3 class="section">9.3 PANNING TRACKS</h3>
3881
3882 <p>Audio tracks have a panning box in their patchbay.  It may have to be
3883 expanded to see it.  The panning box is shown here.
3884
3885    <div class="block-image"><img src="apatches.png" alt="apatches.png"></div>
3886
3887    <p>Pan and nudge for an audio track.
3888
3889    <p>Position the pointer in the panning box and click/drag to reposition
3890 the audio output among the speaker arrangement.  The loudness of each
3891 speaker is printed during the dragging operation.  The panning box uses
3892 a special algorithm to try to allow audio to be focused through one
3893 speaker or branched between the nearest speakers when more than 2
3894 speakers are used.
3895
3896 <div class="node">
3897 <a name="AUTOMATIC-TRACK-PANNING"></a>
3898 <p><hr>
3899 Next:&nbsp;<a rel="next" accesskey="n" href="#STANDARD-AUDIO-MAPPINGS">STANDARD AUDIO MAPPINGS</a>,
3900 Previous:&nbsp;<a rel="previous" accesskey="p" href="#PANNING-TRACKS">PANNING TRACKS</a>,
3901 Up:&nbsp;<a rel="up" accesskey="u" href="#EDITING">EDITING</a>
3902
3903 </div>
3904
3905 <h3 class="section">9.4 AUTOMATIC TRACK PANNING</h3>
3906
3907 <p>Several convenience functions are provided for automatically setting
3908 the panning to several common standards.  They are listed in the
3909 <b>Audio</b> menu.  These functions only affect audio tracks with
3910 <b>recording</b> enabled.
3911
3912    <p><b>Audio-&gt;Map 1:1</b> - This maps every track to its own channel and wraps
3913 around when all the channels are allocated.  It's most useful for
3914 making 2 tracks with 2 channels map to stereo and for making 6 tracks
3915 with 6 channels map to a 6 channel soundcard.
3916
3917    <p><b>Audio-&gt;Map 5.1:2</b> - This maps 6 tracks to 2 channels.  The project
3918 should have 2 channels when using this function.  Go to
3919 <b>Settings-&gt;format</b> to set the output channels to 2.  This is most
3920 useful for downmixing 5.1 audio to stereo.
3921
3922 <div class="node">
3923 <a name="STANDARD-AUDIO-MAPPINGS"></a>
3924 <p><hr>
3925 Next:&nbsp;<a rel="next" accesskey="n" href="#MANIPULATING-TRACKS">MANIPULATING TRACKS</a>,
3926 Previous:&nbsp;<a rel="previous" accesskey="p" href="#AUTOMATIC-TRACK-PANNING">AUTOMATIC TRACK PANNING</a>,
3927 Up:&nbsp;<a rel="up" accesskey="u" href="#EDITING">EDITING</a>
3928
3929 </div>
3930
3931 <h3 class="section">9.5 STANDARD AUDIO MAPPINGS</h3>
3932
3933 <p>Although Cinelerra lets you map any audio track to any speaker, there
3934 are standard mappings you should use to ensure the media can be played
3935 back elsewhere.  Also, most audio encoders require the audio tracks to
3936 be mapped to standard speaker numbers or they won't work.
3937
3938    <p>In the <b>channel position</b> widget See <a href="#SETTING-PROJECT-ATTRIBUTES">SETTING PROJECT ATTRIBUTES</a>,
3939 the channels are numbered to correspond to the output tracks they are
3940 rendered to.  For stereo, the source of channel 1 needs to be the left
3941 track and the source of channel 2 needs to be the right track.
3942
3943    <p>For 5.1 surround sound, the sources of the 6 channels need to be in the
3944 order of center, front left, front right, back left, back right, low
3945 frequency effects.  If the right tracks aren't mapped to the right
3946 speakers, most audio encoders won't encode the right information if
3947 they encode anything at all.  The low frequency effects track
3948 specifically can't store high frequencies in most cases.
3949
3950 <div class="node">
3951 <a name="MANIPULATING-TRACKS"></a>
3952 <p><hr>
3953 Next:&nbsp;<a rel="next" accesskey="n" href="#TWO-SCREEN-EDITING">TWO SCREEN EDITING</a>,
3954 Previous:&nbsp;<a rel="previous" accesskey="p" href="#STANDARD-AUDIO-MAPPINGS">STANDARD AUDIO MAPPINGS</a>,
3955 Up:&nbsp;<a rel="up" accesskey="u" href="#EDITING">EDITING</a>
3956
3957 </div>
3958
3959 <h3 class="section">9.6 MANIPULATING TRACKS</h3>
3960
3961 <p>Tracks in Cinelerra either contain audio or video.  There is no special
3962 designation for tracks other than the type of media they contain.  When
3963 you create a new project, it contains a certain mumber of default
3964 tracks.  You can still add or delete tracks from a number of menus.
3965 The <b>Tracks</b> menu contains a number of options for dealing with
3966 multiple tracks simultaneously.  Each track itself has a popup menu
3967 which affects one track.
3968
3969    <p>Bring up the popup menu by moving over a track and right clicking.  The
3970 popup menu affects the track whether it's armed or not.
3971
3972    <p><b>Move up</b> and <b>move down</b> moves the one track up or down in
3973 the stack.  <b>Delete track</b> deletes the track.
3974
3975    <p>Operations in the <b>Tracks</b> menu affect only tracks which are
3976 armed.
3977
3978    <p><b>Move tracks up</b> and <b>Move tracks down</b> shift all the armed
3979 tracks up or down the stack.
3980
3981    <p><b>Delete tracks</b> deletes the armed tracks.
3982
3983    <p><b>Delete last track</b> deletes the last track, whether it's armed or
3984 not.  Holding down the <b>d</b> key quickly deletes all the tracks.
3985
3986    <p><b>Concatenate tracks</b> is more complicated.  It takes every
3987 <b>playable</b> track and concatenates it to the end of the first
3988 <b>armed tracks</b>.  If there are two armed tracks followed by two
3989 playable tracks, the concatenate operation puts the two playable tracks
3990 after the two armed tracks.  If there are three playable tracks
3991 instead, two tracks are put after the armed tracks and a third track is
3992 put on the end of the first armed track.  The destination track wraps
3993 around until all the playable tracks are concatenated.
3994
3995    <p>Finally, you'll want to create new tracks.  The <b>Audio</b> and
3996 <b>Video</b> menus each contain an option to add a track of their
3997 specific type.  In the case of audio, the new track is put on the
3998 bottom of the timeline and the output channel of the audio track is
3999 incremented by one.  In the case of video, the new track is put on the
4000 top of the timeline.  This way, video has a natural compositing order.
4001 New video tracks are overlayed on top of old tracks.
4002
4003 <div class="node">
4004 <a name="TWO-SCREEN-EDITING"></a>
4005 <p><hr>
4006 Next:&nbsp;<a rel="next" accesskey="n" href="#DRAG-AND-DROP-EDITING">DRAG AND DROP EDITING</a>,
4007 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MANIPULATING-TRACKS">MANIPULATING TRACKS</a>,
4008 Up:&nbsp;<a rel="up" accesskey="u" href="#EDITING">EDITING</a>
4009
4010 </div>
4011
4012 <h3 class="section">9.7 TWO SCREEN EDITING</h3>
4013
4014 <p>This is the fastest way to construct a program out of movie files.  The
4015 idea consists of viewing a movie file in one window and viewing the
4016 program in another window.  Sections of the movie file are defined in
4017 one window and transferred to the end of the program in the other
4018 window.
4019
4020    <p>The way to begin a two screen editing session is to load some
4021 resources.  In <b>file-&gt;load</b> load some movies with the insertion
4022 mode <b>create new resources</b>.  You want the timeline to stay
4023 unchanged while new resources are brought in.  Go to the Resource
4024 Window and select the <b>media</b> folder.  The newly loaded resources
4025 should appear.  Drag a resource from the media side of the window over
4026 the Viewer window.
4027
4028    <p>There should be enough armed tracks on the timeline to put the sections
4029 of source material that you want.  If there aren't, create new tracks
4030 or arm more tracks.
4031
4032    <p>In the viewer window seek to the starting point of a clip you want to
4033 use.  Use either the <b>slider</b> or the <b>transport controls</b>.
4034 Use the <b>preview region</b> to narrow down the search.  Set the
4035 starting point with the <img src="in_point_button.png" alt="in_point_button.png"> <b>in point button</b>.
4036
4037    <p>Seek to the ending point of the clip you want to use.  Set the ending
4038 point with the <img src="out_point_button.png" alt="out_point_button.png"> <b>out point button</b>.  The
4039 two points should now appear on the timebar and define a clip.
4040
4041    <p>There are several things you can do with the clip now.
4042
4043      <ul>
4044 <li>
4045 Splice <img src="splice_button.png" alt="splice_button.png"> inserts the clip in the timeline, pushing
4046 everything back.  If an <b>in point</b> or <b>out point</b> exists on
4047 the timeline it's inserted there, otherwise it's inserted after the
4048 insertion point.  After that, the insertion point moves to the end of
4049 the clip.  If there is no in/out point, the insertion point will be
4050 used as the next splice location.  This way you can continuously build
4051 up the program by splicing.
4052
4053      <li>
4054 Overwrite <img src="overwrite_button.png" alt="overwrite_button.png"> overwrites the region of the
4055 timeline with the clip.  If an <b>in point</b> or <b>out point</b>
4056 exists on the timeline it's overwritten there, otherwise it's
4057 overwritten after the insertion point.  If a region is highlighted or
4058 both in and out points exist the difference between the active region
4059 and the clip length is deleted.
4060
4061      <li>
4062 Create a clip <img src="toclip_button.png" alt="toclip_button.png"> generates a new clip for the
4063 resource window containing the affected region but doesn't change the
4064 timeline.  Every clip has a title and a description.  These are
4065 optional.
4066
4067      <li>
4068 Copy behaves the same as in cut and paste editing.
4069
4070    </ul>
4071
4072    <p>Two screen editing can be done purely by keybard shortcuts.  When you
4073 move the pointer over any button a tooltip should appear, showing what
4074 key is bound to that button.  In the Viewer window, the number pad keys
4075 control the transport and the <b>[ ] v</b> keys perform in/out points
4076 and splicing.
4077
4078 <div class="node">
4079 <a name="DRAG-AND-DROP-EDITING"></a>
4080 <p><hr>
4081 Next:&nbsp;<a rel="next" accesskey="n" href="#CUT-AND-PASTE-EDITING">CUT AND PASTE EDITING</a>,
4082 Previous:&nbsp;<a rel="previous" accesskey="p" href="#TWO-SCREEN-EDITING">TWO SCREEN EDITING</a>,
4083 Up:&nbsp;<a rel="up" accesskey="u" href="#EDITING">EDITING</a>
4084
4085 </div>
4086
4087 <h3 class="section">9.8 DRAG AND DROP EDITING</h3>
4088
4089 <p>The answer is yes, you can you create a bunch of clips and drag them on
4090 the timeline.  You can also drag edits around the timeline.
4091
4092    <p>Load some files using <b>file-&gt;load</b>.  Set the insertion mode to
4093 <b>Create new resources</b>.  This loads the files into the Resource
4094 Window.  Create some audio and video tracks on the timeline using the
4095 video and audio menus.
4096
4097    <p>Open the <b>Media</b> folder in the resource window.  Drag a media file
4098 from the resource window to the timeline.  If the media has video, drag
4099 it onto a video track.  If the media is pure audio, drag it onto an
4100 audio track.
4101
4102    <p>Cinelerra fills out the audio and video tracks below the dragging
4103 cursor with data from the file.  This affects what tracks you should
4104 create initially and which track to drag the media onto.  If the media
4105 has one video track and two audio tracks, you'll need one video track
4106 and two audio tracks on the timeline and the media should be dragged
4107 over the first video track.  If the media has audio only you'll need
4108 one audio track on the timeline for every audio track in the media and
4109 the media should be dragged over the first audio track.
4110
4111    <p>When dragging, the media snaps to the start of track if the track is
4112 empty.  If there are edits on the track, the media snaps to the nearest
4113 edit boundary.
4114
4115    <p>You can also drag multiple files from the resource window.  Either draw
4116 a box around the files, use SHIFT, or use CTRL when selecting files.
4117 When you drop the files in the timeline, they are concatenated.  The
4118 behavior of SHIFT and CTRL changes depending on if the resources are in
4119 text or icons.
4120
4121    <p>To display the resources as text or icons, right click inside the media
4122 list.  Select either <b>display icons</b> or <b>display text</b> to
4123 change the list format.
4124
4125    <p>When displaying text in the resource window <b>SHIFT-clicking</b> on
4126 media files extends the number of highlighted selections.
4127 <b>CTRL-clicking</b> on media files in text mode selects additional
4128 files one at a time.
4129
4130    <p>When displaying icons in the resource window <b>SHIFT-clicking</b> or
4131 <b>CTRL-clicking</b> selects media files one at a time.
4132
4133    <p>In addition to dragging media files, if you create clips and open the
4134 <b>clip</b> folder you can drag clips on the timeline.
4135
4136    <p>In the timeline there is further dragging functionality.  To enable the
4137 dragging functionality of the timeline, select the arrow toggle
4138 <img src="arrow.png" alt="arrow.png">.  Move over an edit and drag it.  If more than one
4139 track is armed, Cinelerra will drag any edits which start on the same
4140 position as the edit the cursur is currently over.  During a dragging
4141 operation the edit snaps to the nearest boundary.
4142
4143    <p>Dragging edits around the timeline allows you to sort music playlists,
4144 sort movie scenes, and give better NAB demos but not much else.
4145
4146 <div class="node">
4147 <a name="CUT-AND-PASTE-EDITING"></a>
4148 <p><hr>
4149 Next:&nbsp;<a rel="next" accesskey="n" href="#TRIMMING">TRIMMING</a>,
4150 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DRAG-AND-DROP-EDITING">DRAG AND DROP EDITING</a>,
4151 Up:&nbsp;<a rel="up" accesskey="u" href="#EDITING">EDITING</a>
4152
4153 </div>
4154
4155 <h3 class="section">9.9 CUT AND PASTE EDITING</h3>
4156
4157 <p>This is the traditional method of editing in audio editors.  In the
4158 case of Cinelerra, you either need to start a second copy of Cinelerra
4159 and copy from one copy to the other, copy from different tracks in the
4160 same copy, or load a media file into the Viewer and copy from there.
4161
4162    <p>Load some files onto the timeline.  To perform cut and paste editing
4163 select the <img src="ibeam.png" alt="ibeam.png"> i-beam toggle.  Select a region of the
4164 timeline and select the <img src="cut.png" alt="cut.png"> cut button to cut it.  Move the
4165 insertion point to another point in the timeline and select the
4166 <img src="paste.png" alt="paste.png"> paste button.  Assuming no in/out points are defined on
4167 the timeline this performs a cut and paste operation.
4168
4169    <p>If in/out points are defined, the insertion point and highlighted
4170 region are overridden by the in/out points for clipboard operations.
4171 Thus, with in/out points you can perform cut and paste in drag and drop
4172 mode as well as cut and paste mode.
4173
4174    <p>When editing audio, it is customary to cut from one part of a waveform
4175 into the same part of another waveform.  The start and stop points of
4176 the cut are identical in each waveform and might be offset slightly,
4177 while the wave data is different.  It would be very hard to highlight
4178 one waveform to cut it and highlight the second waveform to paste it
4179 without changing the relative start and stop positions.
4180
4181    <p>One option for simplifying this is to open a second copy of Cinelerra,
4182 cutting and pasting to transport media between the two copies.  This
4183 way two highlighed regions can exist simultanously.
4184
4185    <p>Another option is to set in/out points for the source region of the
4186 source waveform and set labels for the destination region of the
4187 destination waveform.  Perform a cut, clear the in/out points, select
4188 the region between the labels, and perform a paste.
4189
4190    <p>A final operation in cut and paste editing is the <b>edit-&gt;clear</b>
4191 operation.  If a region is highlighted or in/out points exist, the
4192 affected region is cleared by <b>edit-&gt;clear</b>.  But if the insertion
4193 point is over an edit boundary and the edits on each side of the edit
4194 boundary are the same resource, the edits are combined into one edit
4195 comprised by the resource.  The start of this one edit is the start of
4196 the first edit and the end of this one edit is the end of the second
4197 edit.  This either results in the edit expanding or shrinking.
4198
4199 <div class="node">
4200 <a name="TRIMMING"></a>
4201 <p><hr>
4202 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CUT-AND-PASTE-EDITING">CUT AND PASTE EDITING</a>,
4203 Up:&nbsp;<a rel="up" accesskey="u" href="#EDITING">EDITING</a>
4204
4205 </div>
4206
4207 <h3 class="section">9.10 TRIMMING</h3>
4208
4209 <p>With some edits on the timeline it's possible to do trimming.  By
4210 trimming you shrink or grow the edit boundaries by dragging them.  In
4211 either drag and drop mode or cut and paste mode, move the cursor over
4212 an edit boundary until it changes shape.  The cursor will either be an
4213 expand left or an expand right.  If the cursor is an expand left, the
4214 dragging operation affects the beginning of the edit.  If the cursor is
4215 an expand right, the dragging operation affects the end of the edit.
4216
4217    <p>When you click on an edit boundary to start dragging, the mouse button
4218 number determines which dragging behavior is going to be followed.  3
4219 possible behaviors are bound to mouse buttons in the interface
4220 preferences. See <a href="#INTERFACE">INTERFACE</a>.
4221
4222    <p>The effect of each drag operation not only depends on the behavior
4223 button but whether the beginning or end of the edit is being dragged.
4224 When you release the mouse button, the trimming operation is performed.
4225
4226    <p>In a <b>Drag all following edits</b> operation, the beginning of the
4227 edit either cuts data from the edit if you move it forward or pastes
4228 new data from before the edit if you move it backward.  The end of the
4229 edit pastes data into the edit if you move it forward or cuts data from
4230 the end of the edit if you move it backward.  All the edits thereafter
4231 shift.  Finally, if you drag the end of the edit past the start of the
4232 edit, the edit is deleted.
4233
4234    <p>In a <b>Drag only one edit</b> operation, the behavior is the same when
4235 you drag the beginning or end of an edit.  The only difference is none
4236 of the other edits in the track shift.  Instead, anything adjacent to
4237 the current edit expands or shrinks to fill gaps left by the drag
4238 operation.
4239
4240    <p>In a <b>Drag source only</b> operation, nothing is cut or pasted.  If
4241 you move the beginning or end of the edit forward, the source reference
4242 in the edit shifts forward.  If you move the beginning or end of the
4243 edit backward, the source reference shifts backward.  Where the edit
4244 appears in the timeline remains the same but the source shifts.
4245
4246    <p>For all file formats besides still images, the extent of the trimming
4247 operation is clamped to the source file length.  Attempting to drag the
4248 start of the edit beyond the start of the source clamps it to the
4249 source start.
4250
4251    <p>In all trimming operations, all edits which start on the same position
4252 as the cursor when the drag operation begins are affected.  Unarm
4253 tracks to prevent edits from getting affected.
4254
4255 <div class="node">
4256 <a name="USING-EFFECTS"></a>
4257 <p><hr>
4258 Next:&nbsp;<a rel="next" accesskey="n" href="#SETTING-PROJECT-ATTRIBUTES">SETTING PROJECT ATTRIBUTES</a>,
4259 Previous:&nbsp;<a rel="previous" accesskey="p" href="#EDITING">EDITING</a>,
4260 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
4261
4262 </div>
4263
4264 <h2 class="chapter">10 USING EFFECTS</h2>
4265
4266 <p>It would be sufficient to perform all changes to the timeline using
4267 editing operations, but this isn't very extensible.  Certain timeline
4268 changes should produce a different effect in the output without
4269 involving a unique procedure to apply each change.  This is why we have
4270 effects.
4271
4272    <p>Effects fall into three categories, and each effect in a category is
4273 applied using the same procedure.
4274
4275 <ul class="menu">
4276 <li><a accesskey="1" href="#REALTIME-EFFECTS">REALTIME EFFECTS</a>
4277 <li><a accesskey="2" href="#RENDERED-EFFECTS">RENDERED EFFECTS</a>
4278 <li><a accesskey="3" href="#TRANSITIONS">TRANSITIONS</a>
4279 <li><a accesskey="4" href="#LADSPA-EFFECTS">LADSPA EFFECTS</a>
4280 <li><a accesskey="5" href="#EFFECT-PRESETS">EFFECT PRESETS</a>
4281 </ul>
4282
4283 <div class="node">
4284 <a name="REALTIME-EFFECTS"></a>
4285 <p><hr>
4286 Next:&nbsp;<a rel="next" accesskey="n" href="#RENDERED-EFFECTS">RENDERED EFFECTS</a>,
4287 Up:&nbsp;<a rel="up" accesskey="u" href="#USING-EFFECTS">USING EFFECTS</a>
4288
4289 </div>
4290
4291 <h3 class="section">10.1 REALTIME EFFECTS</h3>
4292
4293 <p>These are layered under the track they apply to.  They process the
4294 track when the track is played back, with no permanent storage of the
4295 output except when the project is rendered.
4296
4297    <p><b>APPLYING REALTIME EFFECTS</b>
4298
4299    <p>All the realtime effects are listed in the resource window, divided
4300 into two groups: audio effects and video effects.  Audio effects should
4301 be dragged from the resource window onto audio tracks.  Video effects
4302 should be dragged onto video tracks.
4303
4304    <p>If there is data on the destination track, the effect is applied to the
4305 entire track.  If there is no data on the track the effect is deleted.
4306 Finally, if a region of the track is selected the effect is pasted into
4307 the region, regardless of whether there is data.
4308
4309    <p>Some of the effects don't process data but synthesize data.  In the
4310 case of a synthesis effect, you'll want to select a region of the
4311 track so the dragging operation pastes it without deleting it.
4312
4313    <p>When dragging more than one effect onto a track, you'll see the effects
4314 layering from top to bottom, on the bottom of the track.   When the
4315 track is played back, effects are processed from top to bottom.  The
4316 output of the top effect becomes the input of the bottom effect and so
4317 on and so forth.
4318
4319    <p>In addition to dragging from the resource window, there are 2 other
4320 methods of applying them:
4321
4322      <ul>
4323 <li><b>APPLYING FROM THE TRACK POPUP MENU:</b>
4324
4325      <p>Right click on a track and select <b>Attach effect</b> from the popup.  The attach effect
4326 dialog gives you more control than pure dragging and dropping.  For one
4327 thing, the attach effect dialog lets you attach two more types of
4328 effects: shared effects and shared tracks.  Select a plugin from the
4329 <b>Plugins</b> column and hit <b>Attach</b> under the plugins column to attach
4330 it.  The effect is the same as if the effect was dragged from the
4331 resource window.
4332
4333      <li><b>APPLYING FROM THE AUDIO AND VIDEO MENUS:</b>
4334
4335      <p>Select <b>Audio-&gt;Attach effect...</b> or <b>Video-&gt;Attach effect</b> to attach
4336 a realtime effect to all the recordable tracks simultaneously.  The
4337 advantage with this is most of the time you want to attach the same
4338 effect to all the audio tracks and the other two methods require
4339 repeating the same work for every track.
4340
4341      <p>The menu interface has an option called  <b>Attach single standalone and
4342 share others</b>.  Enable this to make the first track get a standalone
4343 effect and to have the other tracks share the standalone effect.  Most
4344 of the time, you want this to be on.
4345
4346    </ul>
4347
4348    <p>When an effect exists under a track, it most often needs to be
4349 configured.  Go to the effect and right click on it to bring up the
4350 effect popup.  In the effect popup is a <b>show</b> option.  The show
4351 option causes the GUI for the effect to appear under the cursor.  Most
4352 effects have GUI's but some don't.  If the effect doesn't have a GUI,
4353 nothing pops up when the <b>show</b> option is selected.  When you
4354 tweek parameters in the effect GUI, the parameters normally effect the
4355 entire duration of the effect.
4356
4357 <ul class="menu">
4358 <li><a accesskey="1" href="#REALTIME-EFFECT-TYPES">REALTIME EFFECT TYPES</a>
4359 <li><a accesskey="2" href="#EDITING-REALTIME-EFFECTS">EDITING REALTIME EFFECTS</a>
4360 </ul>
4361
4362 <div class="node">
4363 <a name="REALTIME-EFFECT-TYPES"></a>
4364 <p><hr>
4365 Next:&nbsp;<a rel="next" accesskey="n" href="#EDITING-REALTIME-EFFECTS">EDITING REALTIME EFFECTS</a>,
4366 Up:&nbsp;<a rel="up" accesskey="u" href="#REALTIME-EFFECTS">REALTIME EFFECTS</a>
4367
4368 </div>
4369
4370 <h4 class="subsection">10.1.1 REALTIME EFFECT TYPES</h4>
4371
4372 <p>The two other effect types supported by the Attach Effect dialog are
4373 recycled effects.  In order to use a recycled effect, three requiremenets
4374 must be met:
4375
4376      <ul>
4377 <li>There must be other effects in the timeline.
4378
4379      <li>
4380 The other effects must be of the same type as the track you're
4381 attaching an effect to.  If the track is an audio track, the effects
4382 must be audio effects.  If the track is a video track, the effects must
4383 be video effects.
4384
4385      <li>
4386 The insertion point or selected region must start inside the other effects.
4387
4388    </ul>
4389
4390    <p>In the case of a shared effect, these conditions must be true.  In the
4391 case of a shared track, there merely must be another track on the
4392 timeline of the same type as the track you're applying an effect to.
4393 If you right clicked on a video track to attach an effect, there won't
4394 be anything in the <b>shared tracks</b> column if no other video track
4395 exists.  If you right clicked on an audio track there won't be anything
4396 in the shared track column if no other audio track exists.
4397
4398    <p>If shared effects or shared tracks are available, they appear in the
4399 <b>shared effects</b> and <b>shared tracks</b> columns.  The
4400 <b>attach</b> button under each column causes anything highlighted in
4401 the column to be attached under the current track.
4402
4403    <p>Shared effects and shared tracks allow very unique things to be done.
4404 In the case of a shared effect, the shared effect is treated like a
4405 copy of the original effect except in the shared effect the GUI can't
4406 be brought up.  All configuration of the shared effect is determined by
4407 the GUI of the original effect and only the GUI of the original effect
4408 can be brought up.
4409
4410    <p>When a shared effect is played back, it's processed just like a normal
4411 effect except the configuration is copied from the original effect.
4412 Some effects detect when they are being shared, like the reverb effects
4413 and the compressor.  These effects determine what tracks are sharing
4414 them and either mix the two tracks together or use one track to stage
4415 some value.  The reverb mixes tracks together to simulate ambience.
4416 The compressor uses one of the sharing tracks as the trigger.
4417
4418    <p>When an original track has a <b>shared track</b> as one of its effects,
4419 the shared track itself is used as a realtime effect.  This is more
4420 commonly known as <b>bouncing tracks</b> but Cinelerra achieves the
4421 same operation by attaching shared tracks.  The fade and any effects in
4422 the shared track are applied to the original track.  Once the shared
4423 track has processed the data, the original track performs any effects
4424 which come below the shared track and then composites it on the output.
4425
4426    <p>In addition, once the shared track has processed the output of the
4427 original track like a realtime effect, the shared track mixes itself
4428 into the output with it's settings for pan, mode, and projector.  Thus,
4429 two tracks are mixing the same data on the output.  Most of the time
4430 you don't want the shared track to mix the same data as the original
4431 track on the output.  You want it to stop right before the mixing stage
4432 and give the data back to the original track.  Do this by enabling the
4433 <img src="mutepatch_up.png" alt="mutepatch_up.png"> mute toggle next to each track for whom you don't
4434 want to mix on the output.
4435
4436    <p>Suppose you were making video and you did want the shared track to
4437 composite the original track's data on the output a second time.  In
4438 the case of video, the video from the shared track would always appear
4439 under the video from the original track, regardless of whether it was
4440 on top of the original track.  This is because shared tracks are
4441 composited in order of their attachment.  Since it's part of the original
4442 track it has to be composited before the original track is composited.
4443
4444 <div class="node">
4445 <a name="EDITING-REALTIME-EFFECTS"></a>
4446 <p><hr>
4447 Previous:&nbsp;<a rel="previous" accesskey="p" href="#REALTIME-EFFECT-TYPES">REALTIME EFFECT TYPES</a>,
4448 Up:&nbsp;<a rel="up" accesskey="u" href="#REALTIME-EFFECTS">REALTIME EFFECTS</a>
4449
4450 </div>
4451
4452 <h4 class="subsection">10.1.2 EDITING REALTIME EFFECTS</h4>
4453
4454 <p>Many operations exist for manipulating effects once they are in the
4455 timeline.  Because mixing effects and media is such complex business,
4456 the methods used in editing effects aren't as concise as cutting and
4457 pasting.  Some of the editing happens by dragging in/out points, some
4458 of the editing happens through popup menus, and some of it happens by
4459 dragging effects.
4460
4461    <p>Normally when you edit tracks, the effects follow the editing
4462 decisions.  If you cut from a track, the effect shrinks.  If you drag
4463 edit in/out points, the effect changes length.  This behavior can be
4464 disabled by selecting <b>Settings-&gt;edit effects</b> in the project
4465 window.  This decouples effects from editing operations, but what if
4466 you just want to edit the effects?
4467
4468    <p>Move the timeline cursor over the effect borders until it changes to a
4469 resize left or resize right icon.  In this state, if you drag the end
4470 of the effect, it performs an edit just like dragging the end of a
4471 track does.
4472
4473    <p>The three editing behaviors of track trimming apply to effect trimming
4474 and they are bound to the mouse buttons that you set in <b>interface
4475 preferences</b>. See <a href="#INTERFACE">INTERFACE</a>.  When you perform a trim edit on an
4476 effect, the effect boundary is moved by dragging on it.  Unlike track
4477 editing, the effect has no source length.  You can extend the end of an
4478 effect as much as desired without being limited.
4479
4480    <p>Also unlike track editing, the starting position of the drag operation
4481 doesn't bind the edit decision to media.  The media the effect is bound
4482 to doesn't follow effect edits.  Other effects; however, do follow
4483 editing decisions made on an effect.  If you drag the end of an effect
4484 which is lined up to effects on other tracks, the effects on the other
4485 tracks will be edited while the media stays the same.
4486
4487    <p>What happens if you trim the end of an effect in, leaving a lot of
4488 unaffected time near the end of the track?  When you drag an effect in
4489 from the Resource Window you can insert the effect in the portion of
4490 the row unoccupied by the trimming operation.  Realtime effects are
4491 organized into rows under the track.  Each row can have multiple
4492 effects.
4493
4494    <p>In some cases you'll want a trimming operation to change only one row
4495 of effects.  This can be achieved by first positioning the insertion
4496 point on the start or end of the effect.  Then press <b>shift</b> while
4497 beginning the trimming operation.  This causes the operation to change
4498 only one row of effects.
4499
4500    <p>In addition to trimming, you can move effects up or down.  Every track
4501 can have a stack of effects under it.  By moving an effect up or down
4502 you change the order in which effects are processed in the stack.  Go
4503 to an effect and right click to bring up the effect menu.  The
4504 <b>Move up</b> and <b>Move down</b> options move the effect up or down.
4505
4506    <p>When you're moving effects up or down, be aware that if they're shared
4507 as <b>shared effects</b>, any references will be pointing to a
4508 different effect after the move operation.
4509
4510    <p>Finally, there's dragging of effects.  Dragging effects works just like
4511 dragging edits.  You must select the <img src="arrow.png" alt="arrow.png"> arrow to enter drag and
4512 drop mode before dragging effects.  The effects snap to media
4513 boundaries, effect boundaries, and tracks.  Be aware if you drag a
4514 reference to a shared effect, the reference will usually point to the
4515 wrong effect afterwards.
4516
4517    <p>Right click on an effect to bring up a menu for the effect.  Select
4518 <b>attach...</b> to change the effect or change the reference if it is
4519 a shared effect.
4520
4521 <div class="node">
4522 <a name="RENDERED-EFFECTS"></a>
4523 <p><hr>
4524 Next:&nbsp;<a rel="next" accesskey="n" href="#TRANSITIONS">TRANSITIONS</a>,
4525 Previous:&nbsp;<a rel="previous" accesskey="p" href="#REALTIME-EFFECTS">REALTIME EFFECTS</a>,
4526 Up:&nbsp;<a rel="up" accesskey="u" href="#USING-EFFECTS">USING EFFECTS</a>
4527
4528 </div>
4529
4530 <h3 class="section">10.2 RENDERED EFFECTS</h3>
4531
4532 <p>Another type of effect is performed on a section of the track and the
4533 result stored somewhere before it is played back.  The result is
4534 usually pasted into the track to replace the original data.
4535
4536    <p>In 15 years, the only effect we actually ever rendered with this feature
4537 was <b>normalize</b>.  We've never rendered an effect which could be
4538 applied on the timeline, even though this feature supports rendering
4539 realtime effects.
4540
4541    <p>This feature was implemented back when computers were too slow to play
4542 back anything in realtime.  Decent sounding reverb took a long time &amp;
4543 was considered major number crunching.
4544
4545    <p>The rendered effects are not listed in the resource window but instead
4546 are accessed through the <b>Audio-&gt;Render effect</b> and
4547 <b>Video-&gt;Render effect</b> menu options.  Each of these menu options
4548 brings up a dialog for the rendered effect.  Rendered effects apply to
4549 only one type of track, either audio or video.  If no tracks of the
4550 type exist, an error pops up.
4551
4552    <p>A region of the timeline to apply the effect to must be defined before
4553 selecting <b>Render effect...</b>.  If no in/out points and no
4554 highlighted region exists, the entire region after the insertion point
4555 is treated as the affected region.  Otherwise, the region between the
4556 in/out points or the highlighted region is the affected region.
4557
4558    <p>Secondly, the tracks to apply the rendered affect to need to be
4559 <b>armed</b>.  All other tracks are ignored.
4560
4561    <p>Finally, the rendered affect processes certain track attributes when it
4562 reads its input data but not others.  Transitions in the affected track
4563 are applied.  Nudge is not and effects are not.  This allows the new
4564 data to be pasted into the existing position without changing the nudge
4565 value.
4566
4567    <p>In the render effect dialog is a list of all the realtime and all the
4568 rendered effects.  The difference here is that the realtime effects are
4569 rendered to disk and not applied under the track.  Highlight an effect
4570 in the list to designate it as the one being performed.
4571
4572    <p>Define a file to render the effect to in the <b>Select a file to
4573 render to</b> box.  The <img src="magnify.png" alt="magnify.png"> magnifying glass allows file
4574 selection from a list.
4575
4576    <p>Select a file format which can handle the track type.  The
4577 <img src="wrench.png" alt="wrench.png"> wrench allows configuration specific to the file format.
4578
4579    <p>There is also an option for creating a new file at each label.  If you
4580 have a CD rip on the timeline which you want to divide into different
4581 files, the labels would become dividing points between the files if
4582 this option were selected.  When the timeline is divided by labels, the
4583 effect is re-initialized at every label.  Normalize operations take the
4584 peak in the current file and not in the entire timeline.
4585
4586    <p>Finally there is an insertion strategy just like in the render dialog.
4587 It should be noted that even though the effect applies only to audio or
4588 video, the insertion strategy applies to all tracks just like a
4589 clipboard operation.
4590
4591    <p>When you click <b>OK</b> in the effect dialog, it calls the GUI of the
4592 effect.  If the effect is also a realtime effect, a second GUI appears
4593 to prompt for acceptance or rejection of the current settings.  After
4594 accepting the settings, the effect is processed.
4595
4596 <div class="node">
4597 <a name="TRANSITIONS"></a>
4598 <p><hr>
4599 Next:&nbsp;<a rel="next" accesskey="n" href="#LADSPA-EFFECTS">LADSPA EFFECTS</a>,
4600 Previous:&nbsp;<a rel="previous" accesskey="p" href="#RENDERED-EFFECTS">RENDERED EFFECTS</a>,
4601 Up:&nbsp;<a rel="up" accesskey="u" href="#USING-EFFECTS">USING EFFECTS</a>
4602
4603 </div>
4604
4605 <h3 class="section">10.3 TRANSITIONS</h3>
4606
4607 <p>When one edit ends and another edit begins, the default behaviour is to
4608 have the first edit's output immediately become the output of the
4609 second edit when played back.  Transitions are a way for the first
4610 edit's output to become the second edit's output with different
4611 variations.
4612
4613    <p>Cinelerra supports audio and video transitions, all of which are listed
4614 in the resource window.  Transitions may only apply to the matching
4615 track type.  Transitions under <b>audio transitions</b> can only apply
4616 to audio tracks.  Transitions under <b>video transitions</b> can only
4617 apply to video tracks.
4618
4619    <p>Load a video file and cut a section from the center so the edit point
4620 is visible on the timeline.  Go the resource window and click on the
4621 <b>Video transitions</b> folder.  Drag a transition from the transition
4622 list onto the second video edit on the timeline.  A box highlights over
4623 where the transition will appear.  Releasing it over the second edit
4624 applies the transition between the first and second edit.
4625
4626    <p>You can now scrub over the transition with the transport controls and
4627 watch the output in the <b>Compositor window</b>.  Scrubbing with the
4628 insertion point doesn't normally show transitions because the
4629 transition durations are usually too short.  The exact point in time
4630 when the transition takes effect isn't straightforward.  It starts when
4631 the second edit begins and lasts a certain amount of time into the
4632 second edit.  Therefore, the first asset needs to have enough data
4633 after the edit point to fill the transition into the second edit.
4634
4635    <p>Once the transition is in place, it can be edited similarly to an
4636 effect.  Move the pointer over the transition and right click to bring
4637 up the transition menu.  The <b>show</b> option brings up specific
4638 parameters for the transition in question if there are any.  The
4639 <b>length</b> option adjusts the length of the transition in seconds.
4640 Once these two parameters are set, they are applied to future
4641 transitions until they are changed again.  Finally, the <b>detach</b>
4642 option removes the transition from the timeline.
4643
4644    <p>Dragging and dropping transitions from the Resource window to the
4645 Program window can be really slow and tiring.  Fortunately, once you
4646 drag a transition from the Resource window, the <b>U</b> and <b>u</b>
4647 keys will paste the same transition.  The <b>U</b> key pastes the last
4648 video transition and the <b>u</b> key pastes the last audio transition
4649 on all the recordable tracks.  If the insertion point or in point is
4650 over an edit, the beginning of the edit is covered by the transition.
4651
4652    <p>It should be noted that when playing transitions from the timeline to a
4653 hardware accelerated video device, the hardware acceleration will
4654 usually be turned off momentarily during the transition and on after
4655 the transition in order to render the transition.  Using an
4656 unaccelerated video device for the entire timeline normally removes the
4657 disturbance.
4658
4659 <div class="node">
4660 <a name="LADSPA-EFFECTS"></a>
4661 <p><hr>
4662 Next:&nbsp;<a rel="next" accesskey="n" href="#EFFECT-PRESETS">EFFECT PRESETS</a>,
4663 Previous:&nbsp;<a rel="previous" accesskey="p" href="#TRANSITIONS">TRANSITIONS</a>,
4664 Up:&nbsp;<a rel="up" accesskey="u" href="#USING-EFFECTS">USING EFFECTS</a>
4665
4666 </div>
4667
4668 <h3 class="section">10.4 LADSPA EFFECTS</h3>
4669
4670 <p>LADSPA effects are supported in realtime and rendered mode for audio.
4671 The LADSPA plugins you get from the internet vary in quality.  Most
4672 can't be tweeked in realtime very easily and work better when
4673 rendered.  Some crash and some can only be applied to one track due to
4674 a lack of reentrancy.  Although Cinelerra implements the LADSPA
4675 interface as accurately as possible, multiple tracks of realtime,
4676 simultaneous processing go beyond the majority of LADSPA users.  LADSPA
4677 effects appear in the audio folder as the hammer and screwdriver, to
4678 signify that they are Plugins for Linux Audio Developers.
4679
4680    <p>LADSPA Effects are enabled merely by setting the <b>LADSPA_PATH</b>
4681 environment variable to the location of your LADSPA plugins or putting
4682 them in the <b>/usr/lib/cinelerra</b> directory.
4683
4684 <div class="node">
4685 <a name="EFFECT-PRESETS"></a>
4686 <p><hr>
4687 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LADSPA-EFFECTS">LADSPA EFFECTS</a>,
4688 Up:&nbsp;<a rel="up" accesskey="u" href="#USING-EFFECTS">USING EFFECTS</a>
4689
4690 </div>
4691
4692 <h3 class="section">10.5 EFFECT PRESETS</h3>
4693
4694 <p>Save and recall all the settings for an effect by using the <b>presets</b>
4695 window.  Bring up the effect context menu by right clicking on the
4696 effect on the timeline.  Go to <b>Presets...</b> to bring up the window.
4697 Save all the settings to a preset by entering a title in <b>Preset
4698 title</b> and clicking <b>save</b>.  Recall the settings in a preset by
4699 highlighting it and clicking <b>Apply</b>.  Delete a preset by highlighting
4700 it and clicking <b>Delete</b>.
4701
4702 <div class="node">
4703 <a name="SETTING-PROJECT-ATTRIBUTES"></a>
4704 <p><hr>
4705 Next:&nbsp;<a rel="next" accesskey="n" href="#COMPOSITING">COMPOSITING</a>,
4706 Previous:&nbsp;<a rel="previous" accesskey="p" href="#USING-EFFECTS">USING EFFECTS</a>,
4707 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
4708
4709 </div>
4710
4711 <h2 class="chapter">11 SETTING PROJECT ATTRIBUTES</h2>
4712
4713 <p>When you play media files in Cinelerra, the media files have a certain
4714 number of tracks, a certain frame size, a certain sample size, and so
4715 on and so forth.  No matter what the media file has; however, it is
4716 still played back according to the project attributes.  If an audio
4717 file's samplerate is different than the project attributes, it is
4718 resampled.  If a video file's frame size is different than the project
4719 attributes, it is composited on a black frame, either cropped or
4720 bordered with black.
4721
4722    <p>The project attributes are adjusted in <b>Settings-&gt;Set Format</b> and in
4723 to a more limited extent in <b>File-&gt;New</b>.  When you adjust project
4724 settings in <b>file-&gt;new</b> a new timeline is created with no data.
4725 Every timeline created from this point uses the same settings.  When
4726 you adjust settings in <b>settings-&gt;format</b>, the timeline is not
4727 recreated with no data but every timeline created from this point uses
4728 the same settings.
4729
4730    <p>In addition to the traditional settings for sample rate, frame rate,
4731 frame size, Cinelerra uses some unusual settings like <b>channel
4732 positions, color model, and aspect ratio.</b>
4733
4734 <ul class="menu">
4735 <li><a accesskey="1" href="#AUDIO-CHANNEL-POSITIONS">AUDIO CHANNEL POSITIONS</a>
4736 <li><a accesskey="2" href="#COLOR-MODEL">COLOR MODEL</a>
4737 <li><a accesskey="3" href="#ASPECT-RATIO">ASPECT RATIO</a>
4738 </ul>
4739
4740 <div class="node">
4741 <a name="AUDIO-CHANNEL-POSITIONS"></a>
4742 <p><hr>
4743 Next:&nbsp;<a rel="next" accesskey="n" href="#COLOR-MODEL">COLOR MODEL</a>,
4744 Up:&nbsp;<a rel="up" accesskey="u" href="#SETTING-PROJECT-ATTRIBUTES">SETTING PROJECT ATTRIBUTES</a>
4745
4746 </div>
4747
4748 <h3 class="section">11.1 AUDIO CHANNEL POSITIONS</h3>
4749
4750 <p>The currently enabled audio channels and their positions in the user
4751 interface boxes are displayed in the channel position widget.
4752
4753    <pre class="sp">
4754
4755
4756 </pre>
4757 <img src="channelpositions.png" alt="channelpositions.png">
4758    <pre class="sp">
4759
4760
4761 </pre>
4762
4763    <p>The channels are numbered.  When rendered, the output from channel 1 is
4764 rendered to the first output track in the file or the first soundcard
4765 channel of the soundcard.  Later channels are rendered to their
4766 successively numbered output tracks.
4767
4768    <p>The audio channel locations correspond to where in the panning widgets
4769 each of the audio outputs is.  The closer the panning position is to
4770 one of the audio outputs, the more signal that speaker gets.  Click on
4771 a speaker icon and drag to change the audio channel location.
4772
4773    <p>The speakers can be in any orientation.  A different speaker
4774 arrangement is stored for every number of audio channels since normally
4775 you don't want the same speaker arrangement for different numbers of
4776 channels.
4777
4778    <p>Channel positions is the only setting which doesn't affect the output
4779 necessarily.  Click on a speaker icon and drag to change the position
4780 of a channel.  It is merely a convenience so when more than 2 channels
4781 are used, the pan controls on the timeline can distinguish between
4782 them.  It has nothing to do with the actual arrangement of speakers.
4783
4784    <p>But different channels can be positioned very close together to make
4785 them have the same output.
4786
4787 <div class="node">
4788 <a name="COLOR-MODEL"></a>
4789 <p><hr>
4790 Next:&nbsp;<a rel="next" accesskey="n" href="#ASPECT-RATIO">ASPECT RATIO</a>,
4791 Previous:&nbsp;<a rel="previous" accesskey="p" href="#AUDIO-CHANNEL-POSITIONS">AUDIO CHANNEL POSITIONS</a>,
4792 Up:&nbsp;<a rel="up" accesskey="u" href="#SETTING-PROJECT-ATTRIBUTES">SETTING PROJECT ATTRIBUTES</a>
4793
4794 </div>
4795
4796 <h3 class="section">11.2 COLOR MODEL</h3>
4797
4798 <p>Color model is very important for video playback because video has the
4799 disadvantage of being very slow.  Although it isn't noticable, audio
4800 intermediates contain much more information than the audio on disk and
4801 the audio which is played.  Audio always uses the highest bandwidth
4802 intermediate because it's fast.
4803
4804    <p>Video intermediates must use the least amount of data for the required
4805 quality because it's slow, but video intermediates still use a higher
4806 bandwidth color model than video which is stored and video which is
4807 played.  This allows more processing to be done with less destruction
4808 of the original data.
4809
4810    <p>The video is stored on disk in one colormodel, normally compressed
4811 using a YUV derivative.  When played back, Cinelerra decompresses it
4812 from the file format directly into the format of the output device.  If
4813 effects are processed, the decompression is into an intermediate
4814 colormodel first and the intermediate colormodel is then converted to
4815 the format of the output device.  The selection of intermediate
4816 colormodel determines how accurate and fast the effects are.
4817
4818    <p>Cinelerra colormodels are described using a certain packing order of
4819 components and a certain number of bits for each component.  The
4820 packing order is printed on the left and the bit allocation is printed
4821 on the right.
4822
4823      <ul>
4824 <li>
4825 <b>RGB-888</b>
4826
4827      <p>This allocates 8 bits for the R, G, and B channels and no alpha. This
4828 is normally used for uncompressed media with low dynamic range.
4829
4830      <li>
4831 <b>RGBA-8888</b>
4832
4833      <p>This allocates an alpha channel to the 8 bit RGB colormodel.  It's used
4834 for overlaying multiple tracks.
4835
4836      <li>
4837 <b>YUV-888</b>
4838
4839      <p>This allocates 8 bits for Y, U, and V.  This is used for low dynamic
4840 range operations in which the media is compressed in the YUV color
4841 space.  Most compressed media is in YUV and this allows it to be
4842 processed fast with the least color degradation.
4843
4844      <li>
4845 <b>YUVA-8888</b>
4846
4847      <p>This allocates an alpha channel to the 8 bit YUV colormodel for
4848 transparency.
4849
4850      <li>
4851 <b>RGB-Float</b>
4852
4853      <p>This allocates a 32 bit float for the R, G, and B channels and no
4854 alpha.  This is used for high dynamic range processing with no
4855 transparency.
4856
4857      <li>
4858 <b>RGBA-Float</b> This adds a 32 bit float for alpha to RGB-Float.  This
4859 is used for high dynamic range processing with transparency.
4860
4861    </ul>
4862
4863    <p>In order to do effects which involve alpha channels, a colormodel with
4864 an alpha channel must be selected.  These are RGBA8888, YUVA8888, and
4865 RGBA Float.  The 4 channel colormodels are notoriously slower than 3
4866 channel colormodels, with the slowest being RGBA Float.  Some effects,
4867 like fade, work around the need for alpha channels while other effects,
4868 like chromakey, require an alpha channel to do anything, so it's a good
4869 idea to try the effect without alpha channels to see if it works before
4870 settling on an alpha channel and slowing it down.
4871
4872    <p>The YUV colormodels are usually faster than RGB colormodels when using
4873 compressed footage.  They also destroy fewer colors than RGB
4874 colormodels.  If footage stored as JPEG or MPEG is processed many times
4875 in RGB, the colors will fade while they won't if processed in YUV.
4876
4877    <p>Years of working with high dynamic range footage have shown floating
4878 point RGB to be the best format for high dynamic range.  While 16 bit
4879 integers were used in the past, these were too lossy and slow for the
4880 amount of improvement.
4881
4882    <p>RGB float doesn't destroy information when used with YUV source
4883 footage.  It also supports brightness above 100%.  Be aware that some
4884 effects, like Histogram, still clip above 100% when in floating point.
4885
4886 <div class="node">
4887 <a name="ASPECT-RATIO"></a>
4888 <p><hr>
4889 Previous:&nbsp;<a rel="previous" accesskey="p" href="#COLOR-MODEL">COLOR MODEL</a>,
4890 Up:&nbsp;<a rel="up" accesskey="u" href="#SETTING-PROJECT-ATTRIBUTES">SETTING PROJECT ATTRIBUTES</a>
4891
4892 </div>
4893
4894 <h3 class="section">11.3 ASPECT RATIO</h3>
4895
4896 <p>Aspect ratio determines the shape of the video output when using the
4897 X11 video output.  The numbers in each direction can be any floating
4898 point number.  When drawn on the screen, video pixels are stretched to
4899 match the aspect ratio.
4900
4901    <p>Some file formats, like MPEG video, write the project aspect ratio to
4902 the file.
4903
4904 <div class="node">
4905 <a name="COMPOSITING"></a>
4906 <p><hr>
4907 Next:&nbsp;<a rel="next" accesskey="n" href="#KEYFRAMES">KEYFRAMES</a>,
4908 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SETTING-PROJECT-ATTRIBUTES">SETTING PROJECT ATTRIBUTES</a>,
4909 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
4910
4911 </div>
4912
4913 <h2 class="chapter">12 COMPOSITING</h2>
4914
4915 <p>A large amount of Cinelerra's binary size is directed towards
4916 compositing.  When you remove the letterboxing from a widescreen show,
4917 you're compositing.  Changing the resolution of a show, making a split
4918 screen, and fading in and out among other things are all compositing
4919 operations in Cinelerra.  Cinelerra detects when it's in a compositing
4920 operation and plays back through the compositing engine only then.
4921 Otherwise, it uses the fastest decoder available in the hardware.
4922
4923    <p>Compositing operations are done on the timeline and in the Compositor
4924 window.  Shortcuts exist in the Resource window for changing some
4925 compositing attributes.  Once some video files are on the timeline, the
4926 compositor window is a good place to try compositing.
4927
4928 <ul class="menu">
4929 <li><a accesskey="1" href="#THE-CAMERA-AND-PROJECTOR">THE CAMERA AND PROJECTOR</a>
4930 <li><a accesskey="2" href="#MASKS">MASKS</a>
4931 <li><a accesskey="3" href="#CROPPING">CROPPING</a>
4932 <li><a accesskey="4" href="#SAFE-REGIONS">SAFE REGIONS</a>
4933 <li><a accesskey="5" href="#OVERLAY-MODES">OVERLAY MODES</a>
4934 <li><a accesskey="6" href="#TRACK-AND-OUTPUT-SIZES">TRACK AND OUTPUT SIZES</a>
4935 </ul>
4936
4937 <div class="node">
4938 <a name="THE-CAMERA-AND-PROJECTOR"></a>
4939 <p><hr>
4940 Next:&nbsp;<a rel="next" accesskey="n" href="#MASKS">MASKS</a>,
4941 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITING">COMPOSITING</a>
4942
4943 </div>
4944
4945 <h3 class="section">12.1 THE CAMERA AND PROJECTOR</h3>
4946
4947 <p>In the compositor window, the most important functions are the
4948 <img src="camera.png" alt="camera.png"> camera button and the <img src="projector.png" alt="projector.png"> projector
4949 button.  These control operation of the camera and projector.  Inside
4950 Cinelerra's compositing pipeline, the camera determines where in the
4951 source video the temporary is copied from.  The projector determines
4952 where in the output the temporary is copied to.  The temporary is a
4953 frame of video in Cinelerra's memory where all graphics processing is
4954 done.  Each track has a different temporary which is defined by the
4955 track size.  By resizing the tracks you can create splitscreens, pans,
4956 and zooms.
4957
4958    <pre class="sp">
4959
4960
4961 </pre>
4962 <img src="compositing_pipeline.png" alt="compositing_pipeline.png">
4963    <pre class="sp">
4964
4965
4966 </pre>
4967 <b>Visual representation of the compositing pipeline</b>.
4968
4969    <p>When editing the camera and projector in the compositing window, the
4970 first track with <b>record</b> enabled is the track affected.  Even if
4971 the track is completely transparent, it's still the affected track.  If
4972 multiple video tracks exist, the easiest way to select one track for
4973 editing is to <b>shift-click</b> on the record icon of the track.  This
4974 solos the track.
4975
4976    <p>When the <b>projector</b> button is enabled in the compositor window,
4977 you're in projector editing mode.  A guide box appears in the video
4978 window.  Dragging anywhere in the video window causes the guide box to
4979 move, hopefully along with the video.  <b>shift-dragging</b> anywhere
4980 in the video window causes the guide box to shrink and grow along with
4981 the video.  Once you've positioned the video with the projector, you're
4982 ready to master the camera.
4983
4984    <p>Select the <img src="camera.png" alt="camera.png"> camera button to enable camera editing mode.
4985 In this mode, the guide box shows where the camera position is in
4986 relation to past and future camera positions but not where it is in
4987 relation to the source video.  Dragging the camera box in the
4988 compositor window doesn't move the box but instead moves the location
4989 of the video inside the box.
4990
4991    <p>For example, when you drag the camera left, the video moves right.
4992 When you drag the camera up, the video moves down.  When you shift-drag
4993 the camera, the effect is the same as if you zoomed in or out of the
4994 source.  The intention of the camera is to produce still photo panning,
4995 while the intention of the projector is to composite several sources in
4996 the same scene.
4997
4998    <p>In the compositing window, there is a popup menu of options for the
4999 camera and projector.  Right click over the video portion of the
5000 compositing window to bring up the menu.
5001
5002      <ul>
5003 <li>Reset Camera causes the camera to return to the center position.
5004
5005      <li>Reset Projector causes the projector to return to the center.
5006
5007    </ul>
5008
5009    <p>The camera and projector have shortcut operations neither in the popup
5010 menu or represented in video overlays.  These are accessed in the
5011 <b>Tool window</b>.  Most operations in the Compositor window have a
5012 tool window which is enabled by activating the <img src="toolwindow.png" alt="toolwindow.png">
5013 question mark.
5014
5015    <p>In the case of the camera and projector, the tool window shows x, y,
5016 and z coordinates.  By either tumbling or entering text directly, the
5017 camera and projector can be precisely positioned.  9 justification
5018 types are also defined for easy access.  A popular justification
5019 operation is upper left projection after image reduction.  This is used
5020 when reducing the size of video with aspect ratio adjustment.
5021
5022    <p>The translation effect allows simultaneous aspect ratio conversion and
5023 reduction but is easier to use if the reduced video is put in the upper
5024 left of the temporary instead of in the center.  The track size is set
5025 to the original size of the video and the camera is centered.  The
5026 output size is set to the reduced size of the video.  Without any
5027 effects, this produces just the cropped center portion of the video in
5028 the output.
5029
5030    <p>The translation effect is dropped onto the video track.  The input
5031 dimensions of the translation effect are set to the original size and
5032 the output dimensions are set to the reduced size.  To put the reduced
5033 video in the center section that the projector shows would require
5034 offsetting <b>out x and out y</b> by a complicated calculation.
5035 Instead, we leave <b>out x and out y</b> at 0 and use the projector's
5036 tool window.
5037
5038    <p>Merely by selecting <img src="left_justify.png" alt="left_justify.png"> left justify and
5039 <img src="top_justify.png" alt="top_justify.png"> top justify, the projector displays the reduced
5040 image from the top left corner of the temporary in the center of the
5041 output.
5042
5043 <div class="node">
5044 <a name="MASKS"></a>
5045 <p><hr>
5046 Next:&nbsp;<a rel="next" accesskey="n" href="#CROPPING">CROPPING</a>,
5047 Previous:&nbsp;<a rel="previous" accesskey="p" href="#THE-CAMERA-AND-PROJECTOR">THE CAMERA AND PROJECTOR</a>,
5048 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITING">COMPOSITING</a>
5049
5050 </div>
5051
5052 <h3 class="section">12.2 MASKS</h3>
5053
5054 <p>Masks select a region of the video for either displaying or hiding.
5055 Masks are also used in conjunction with another effect to isolate the
5056 effect to a certain region of the frame.  A copy of one video track may
5057 be delayed slightly and unmasked in locations where the one copy has
5058 interference but the other copy doesn't.  Color correction may be
5059 needed in one section of a frame but not another.  A mask can be
5060 applied to just a section of the color corrected track while the
5061 vanilla track shows through.  Removal of boom microphones, airplanes,
5062 and housewives are other mask uses.
5063
5064    <p>The order of the compositing pipeline affects what can be done with
5065 masks.  Mainly, masks are performed on the temporary after effects and
5066 before the projector.  This means multiple tracks can be bounced to a
5067 masked track and projected with the same mask.
5068
5069    <p>Our compositing pipeline graph now has a masking stage.  There are 8
5070 possible masks per track.  Each mask is defined separately, although
5071 they each perform the same operation, whether it's addition or
5072 subtraction.
5073
5074    <pre class="sp">
5075
5076
5077 </pre>
5078 <img src="compositing_pipeline2.png" alt="compositing_pipeline2.png">
5079    <pre class="sp">
5080
5081
5082 </pre>
5083 <b>Compositing pipeline with masks</b>
5084
5085    <p>To define a mask, go into the Compositor window and enable the
5086 <img src="mask.png" alt="mask.png"> <b>mask</b> toggle.  Now go over the video and
5087 click-drag.  Click-drag again in another part of the image to create
5088 each new point of the mask.  While it isn't the conventional bezier
5089 curve behavior, this masking interface performs in realtime what the
5090 effect of the mask is going to be.  Creating each point of the mask
5091 expands a rubber band curve.
5092
5093    <p>Once points are defined, they can be moved by <b>ctrl-dragging</b> in
5094 the vicinity of the corner.  This; however, doesn't smooth out the
5095 curve.  The in-out points of the bezier curve are accessed by
5096 <b>shift-dragging</b> in the vicinity of the corner.  Then
5097 <b>shift-dragging</b> near the in or out point causes the point to
5098 move.
5099
5100    <p>Finally, once you have a mask, the mask can be translated in one piece
5101 by <b>alt-dragging</b> the mask.  Mask editing in Cinelerra is
5102 identical to how The Gimp edits masks except in this case the effect of
5103 the mask is always on.
5104
5105    <p>The masks have many more parameters which couldn't be represented with
5106 video overlays.  These are represented in the tool window for masks.
5107 Selecting the <img src="toolwindow.png" alt="toolwindow.png"> question mark when the <img src="mask.png" alt="mask.png">
5108 mask toggle is highlighted brings up the mask options.
5109
5110    <p>The <b>mode</b> of the mask determines if the mask removes data or
5111 makes data visible.  If the mode is subtractive, the mask causes video
5112 to disappear.  If the mode is additive, the mask causes video to appear
5113 and everything outside the mask to disappear.
5114
5115    <p>The <b>value</b> of the mask determines how extreme the addition or
5116 subtraction is.  In the subtractive mode, higher values subtract more
5117 alpha.  In the additive mode, higher values make the region in the mask
5118 brighter while the region outside the mask is always hidden.
5119
5120    <p>The mask number determines which one of the 8 possible masks we're
5121 editing.  Each track has 8 possible masks.  When you click-drag in the
5122 compositor window, you're only editing one of the masks.  Change the
5123 value of <b>mask number</b> to cause another mask to be edited.  The
5124 previous mask is still active but only the curve overlay for the
5125 currently selected mask is visible.
5126
5127    <p>When multiple masks are used, their effects are ORed together.  Every
5128 mask in a single track uses the same value and mode.
5129
5130    <p>The edges of a mask are hard by default but this rarely is desired.
5131 The <b>feather</b> parameter determines how many pixels to feather the
5132 mask.  This creates softer edges but takes longer to render.
5133
5134    <p>Finally, there are parameters which affect one point on the current
5135 mask instead of the whole mask.  These are <b>Delete, x, y</b>.  The
5136 active point is defined as the last point dragged in the compositor
5137 window.  Any point can be activated merely by <b>ctrl-clicking</b> near
5138 it without moving the pointer.  Once a point is activated,
5139 <b>Delete</b> deletes it and <b>x, y</b> allow repositioning by numeric
5140 entry.
5141
5142 <div class="node">
5143 <a name="CROPPING"></a>
5144 <p><hr>
5145 Next:&nbsp;<a rel="next" accesskey="n" href="#SAFE-REGIONS">SAFE REGIONS</a>,
5146 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MASKS">MASKS</a>,
5147 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITING">COMPOSITING</a>
5148
5149 </div>
5150
5151 <h3 class="section">12.3 CROPPING</h3>
5152
5153 <p>Cropping changes the value of the output dimensions and the projector
5154 to reduce the visible picture area.  Enable the <img src="crop.png" alt="crop.png"> crop
5155 toggle and the <img src="toolwindow.png" alt="toolwindow.png"> tool window in the <b>compositing
5156 window</b> to perform cropping.
5157
5158    <p>This draws a rectangle over the video.  Click-drag anywhere in the
5159 video to start a new rectangle.  Click-drag over any corner of the
5160 rectangle to reposition the corner.
5161
5162    <p>Alt-click in the cropping rectangle to translate the rectangle to any
5163 position without resizing it.
5164
5165    <p>The tool window allows text entry of the coordinates and executes the
5166 cropping operation.  When the rectangle is positioned, hit the <b>do
5167 it</b> button in the tool window to execute the cropping operation.
5168
5169 <div class="node">
5170 <a name="SAFE-REGIONS"></a>
5171 <p><hr>
5172 Next:&nbsp;<a rel="next" accesskey="n" href="#OVERLAY-MODES">OVERLAY MODES</a>,
5173 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CROPPING">CROPPING</a>,
5174 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITING">COMPOSITING</a>
5175
5176 </div>
5177
5178 <h3 class="section">12.4 SAFE REGIONS</h3>
5179
5180 <p>On consumer displays the borders of the image are cut off and within
5181 the cutoff point is a region which isn't always square like it is in
5182 the compositor window.  The borders are intended for scratch room and
5183 vertical blanking data.  You can show where these borders are by
5184 enabling the <img src="titlesafe.png" alt="titlesafe.png"> safe regions toggle.  Keep titles inside
5185 the inner rectangle and keep action inside the outer rectangle.
5186
5187 <div class="node">
5188 <a name="OVERLAY-MODES"></a>
5189 <p><hr>
5190 Next:&nbsp;<a rel="next" accesskey="n" href="#TRACK-AND-OUTPUT-SIZES">TRACK AND OUTPUT SIZES</a>,
5191 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SAFE-REGIONS">SAFE REGIONS</a>,
5192 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITING">COMPOSITING</a>
5193
5194 </div>
5195
5196 <h3 class="section">12.5 OVERLAY MODES</h3>
5197
5198 <p>Every video track has an overlay mode, accessible by expanding the
5199 track.  The overlay mode is a pulldown menu on the left under the
5200 fader.  When collapsed, it displays an icon representing the current
5201 overlay mode.
5202
5203    <p>Select the <img src="expandpatch_checked.png" alt="expandpatch_checked.png"> expand track toggle to view all
5204 the options for a video track if you can't see the overlay mode.  The
5205 overlay mode of video tracks is <b>normal</b> by default.  Select other
5206 modes by clicking the overlay button and selecting an item from the
5207 popup menu.
5208
5209    <p>Overlay modes are processed inside the projector stage of compositing.
5210 The different modes are summarized below.
5211
5212      <ul>
5213 <li>
5214 <b>Normal</b> uses a traditional Porter-Diff equation to blend tracks with
5215 alpha.  When no alpha exists in the project color model, the new track
5216 always replaces the output.
5217
5218      <li>
5219 <b>Addition</b>  In this mode, whatever is in the output is added to the
5220 current track.  The result is blended based on the current track's
5221 alpha onto the output.
5222
5223      <li>
5224 <b>Subtraction</b> In this mode, the current track is subtracted from the
5225 output and the result is alpha blended onto the output.
5226
5227      <li>
5228 <b>Multiply</b> is the most useful operation.  The current track is multiplied
5229 by the output and the result blended onto the output.  Usually a black
5230 and white image with no alpha channel or a white title on a black image
5231 is used as the current track.  With the multiply operation, only the
5232 output portions under the white area show.
5233
5234      <li>
5235 <b>Divide</b> divides the current track by the output and the result is
5236 blended into the output.  It usually results in overloaded levels.
5237
5238      <li>
5239 <b>Replace</b> does no blending and overwrites the output with the current
5240 track.
5241
5242    </ul>
5243
5244 <div class="node">
5245 <a name="TRACK-AND-OUTPUT-SIZES"></a>
5246 <p><hr>
5247 Previous:&nbsp;<a rel="previous" accesskey="p" href="#OVERLAY-MODES">OVERLAY MODES</a>,
5248 Up:&nbsp;<a rel="up" accesskey="u" href="#COMPOSITING">COMPOSITING</a>
5249
5250 </div>
5251
5252 <h3 class="section">12.6 TRACK AND OUTPUT SIZES</h3>
5253
5254 <p>The size of the temporary and the size of the output in our compositing
5255 pipeline are independant and variable.  This fits into everything
5256 covered so far.  The camera's viewport is the temporary size.  Effects
5257 are processed in the temporary and are affected by the temporary size.
5258 Projectors are rendered to the output and are affected by the output
5259 size.  If the temporary is smaller than the output, the temporary is
5260 bordered by blank regions in the output.  If the temporary is bigger
5261 than the output, the temporary is cropped.
5262
5263    <p>The temporary size is defined as the track size.  Each track has a
5264 different size.  Right click on a track to bring up the track's menu.
5265 Select <b>Resize Track</b> to resize the track to any arbitrary size.
5266 Alternatively you can select <b>Match output size</b> to make the track
5267 the same size as the output.
5268
5269    <p>The output size is set in either <b>New</b> when creating a new project
5270 or <b>Settings-&gt;Format</b>.  In the Resource window there is another
5271 way to change the output size.  Right click on a video asset and select
5272 <b>Match project size</b> to conform the output to the asset.  When new
5273 tracks are created, the track size always conforms to the output size
5274 specified by these methods.
5275
5276 <div class="node">
5277 <a name="KEYFRAMES"></a>
5278 <p><hr>
5279 Next:&nbsp;<a rel="next" accesskey="n" href="#CAPTURING-MEDIA">CAPTURING MEDIA</a>,
5280 Previous:&nbsp;<a rel="previous" accesskey="p" href="#COMPOSITING">COMPOSITING</a>,
5281 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
5282
5283 </div>
5284
5285 <h2 class="chapter">13 KEYFRAMES</h2>
5286
5287 <p>When you change the fade, camera, projector, or other parameters for a
5288 track, they stay by default the same for the entire durection of the
5289 timeline.   Setting static parameters isn't very useful sometimes.
5290 Normally you need to move the camera around over time or change mask
5291 positions.  Masks need to follow objects.  We create dymanic changes by
5292 defining keyframes.  A keyframe is a certain point in time when the
5293 settings for one operation change.  In Cinelerra, there are keyframes
5294 for almost every compositing parameter and effect parameter.
5295
5296    <p>Whenever you adjust any parameter, the value is stored in a keyframe.
5297 If the value is stored in a keyframe, why doesn't it always change?
5298 The keyframe it is stored in by default is known as the <b>default
5299 keyframe</b>.  The default keyframe applies to the entire duration if no
5300 other keyframes are present.  The default keyframe is not drawn
5301 anywhere because it always exists.  The only way change occurs over
5302 time is if non-default keyframes are created.
5303
5304    <p>Display keyframes for any parameter by using the <b>view</b> menu.  A
5305 faster way to toggle multiple keyframe types is to bring up
5306 <b>window-&gt;overlays</b>.  This window allows toggling of every parameter
5307 in the view menu.  When keyframes are selected, they are drawn on the
5308 timeline over the tracks they apply to.
5309
5310    <p>Keyframes come in many forms: curves, toggles, modes, and so on.
5311 How to handle the different types of keyframes is described here.
5312
5313 <ul class="menu">
5314 <li><a accesskey="1" href="#CURVE-KEYFRAMES">CURVE KEYFRAMES</a>:   Using rubber band curves
5315 <li><a accesskey="2" href="#CHANGING-BEZIER-_0026-LINEAR-MODE">CHANGING BEZIER &amp; LINEAR MODE</a>:   Change curves from linear to curved
5316 <li><a accesskey="3" href="#SNAPPING-TO-NEIGHBOR-KEYFRAMES">SNAPPING TO NEIGHBOR KEYFRAMES</a>
5317 <li><a accesskey="4" href="#NAVIGATING-CURVE-KEYFRAMES">NAVIGATING CURVE KEYFRAMES</a>
5318 <li><a accesskey="5" href="#TOGGLE-KEYFRAMES">TOGGLE KEYFRAMES</a>
5319 <li><a accesskey="6" href="#AUTOMATIC-KEYFRAMES">AUTOMATIC KEYFRAMES</a>
5320 <li><a accesskey="7" href="#COMPOSITOR-KEYFRAMES">COMPOSITOR KEYFRAMES</a>
5321 <li><a accesskey="8" href="#EDITING-KEYFRAMES">EDITING KEYFRAMES</a>:    Moving keyframes around
5322 <li><a accesskey="9" href="#KEYFRAME-SPANNING">KEYFRAME SPANNING</a>:    How to change 1 parameter in many keyframes simultaneously
5323 </ul>
5324
5325 <div class="node">
5326 <a name="CURVE-KEYFRAMES"></a>
5327 <p><hr>
5328 Next:&nbsp;<a rel="next" accesskey="n" href="#CHANGING-BEZIER-_0026-LINEAR-MODE">CHANGING BEZIER &amp; LINEAR MODE</a>,
5329 Up:&nbsp;<a rel="up" accesskey="u" href="#KEYFRAMES">KEYFRAMES</a>
5330
5331 </div>
5332
5333 <h3 class="section">13.1 CURVE KEYFRAMES</h3>
5334
5335 <p>Many parameters are stored in rubber band curves.  Go to <b>view-&gt;fade</b> or
5336 <b>view-&gt;...zoom</b> to show curves on the timeline for those parameters.
5337 In either arrow editing mode or i-beam editing mode, move the cursor
5338 over the curves in the timeline until it changes shape.  Then merely by
5339 clicking and dragging on the curve you can create a keyframe at the
5340 position.
5341
5342    <p>After the keyframe is created, click drag on it again to reposition
5343 it.  When you click-drag a second keyframe on the curve, it creates a
5344 smooth ramp.
5345
5346 <div class="node">
5347 <a name="CHANGING-BEZIER-%26-LINEAR-MODE"></a>
5348 <a name="CHANGING-BEZIER-_0026-LINEAR-MODE"></a>
5349 <p><hr>
5350 Next:&nbsp;<a rel="next" accesskey="n" href="#SNAPPING-TO-NEIGHBOR-KEYFRAMES">SNAPPING TO NEIGHBOR KEYFRAMES</a>,
5351 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CURVE-KEYFRAMES">CURVE KEYFRAMES</a>,
5352 Up:&nbsp;<a rel="up" accesskey="u" href="#KEYFRAMES">KEYFRAMES</a>
5353
5354 </div>
5355
5356 <h3 class="section">13.2 CHANGING BEZIER &amp; LINEAR MODE</h3>
5357
5358 <p>The curve keyframes have bezier and linear modes.  In linear mode, the
5359 keyframe looks like a square and the lines emanating from it are
5360 straight.  In bezier mode, the keyframe is rounded and has 2 control
5361 lines in addition to the rubber band curve lines.
5362
5363    <p>These are keyframes in linear mode.
5364
5365    <div class="block-image"><img src="linear.png" alt="linear.png"></div>
5366
5367    <p>These are keyframes in bezier mode.
5368
5369    <div class="block-image"><img src="bezier.png" alt="bezier.png"></div>
5370
5371    <p>Change the mode of an existing keyframe by right clicking on it to bring
5372 up the context menu and selecting <b>make linear</b> or <b>make bezier</b>.
5373
5374    <p>Change the mode of several keyframes by highlighting the entire region of the
5375 timeline and selecting <b>Keyframes-&gt;change to linear</b> or
5376 <b>Keyframes-&gt;change to bezier</b>.
5377
5378    <p>When keyframes are created, they can be linear or bezier by default.
5379 Change the default mode by checking or unchecking <b>Keyframes-&gt;create
5380 bezier</b>.
5381
5382    <p>For bezier keyframes, <b>ctrl-dragging</b> on the control lines of a
5383 keyframe changes the value of either the input control or the output
5384 control.  Without <b>ctrl</b> the cursor only affects the central
5385 keyframe.  This affects the sharpness of the curve.  The input and
5386 output controls can only be moved vertically.
5387
5388    <p>If the control lines aren't visible, <b>ctrl-drag</b> on the left or right
5389 of the keyframe.
5390
5391 <div class="node">
5392 <a name="SNAPPING-TO-NEIGHBOR-KEYFRAMES"></a>
5393 <p><hr>
5394 Next:&nbsp;<a rel="next" accesskey="n" href="#NAVIGATING-CURVE-KEYFRAMES">NAVIGATING CURVE KEYFRAMES</a>,
5395 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CHANGING-BEZIER-_0026-LINEAR-MODE">CHANGING BEZIER &amp; LINEAR MODE</a>,
5396 Up:&nbsp;<a rel="up" accesskey="u" href="#KEYFRAMES">KEYFRAMES</a>
5397
5398 </div>
5399
5400 <h3 class="section">13.3 SNAPPING TO NEIGHBOR KEYFRAMES</h3>
5401
5402 <p><b>shift-drag</b> on a curve keyframe to make the keyframe snap to the
5403 value of either the next or previous keyframe, depending on which
5404 exists.  This lets you set a constant curve value without having to copy
5405 the next or previous keyframe.
5406
5407 <div class="node">
5408 <a name="NAVIGATING-CURVE-KEYFRAMES"></a>
5409 <p><hr>
5410 Next:&nbsp;<a rel="next" accesskey="n" href="#TOGGLE-KEYFRAMES">TOGGLE KEYFRAMES</a>,
5411 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SNAPPING-TO-NEIGHBOR-KEYFRAMES">SNAPPING TO NEIGHBOR KEYFRAMES</a>,
5412 Up:&nbsp;<a rel="up" accesskey="u" href="#KEYFRAMES">KEYFRAMES</a>
5413
5414 </div>
5415
5416 <h3 class="section">13.4 NAVIGATING CURVE KEYFRAMES</h3>
5417
5418 <p>There isn't much room on the timeline for a wide range of curve
5419 values.  You need to zoom the curves in and out vertically to have any
5420 variability.  This is done by 2 tools: the automation fit button
5421 <img src="fitautos.png" alt="fitautos.png"> and automation zoom menu <img src="autozoom.png" alt="autozoom.png">.
5422
5423    <p>The automation fit button scales and offsets the vertical range so the
5424 selected curve area appears in the timeline.  If a region of the
5425 timeline is highlighted by the cursor, only that region is scaled.
5426 In/out points don't affect the zoomed region.  <b>Alt-f</b> also performs
5427 automation fitting.
5428
5429    <p>The automation zoom menu manually changes the vertical scaling of the
5430 curves in multiples of 2.  Click on its tumbler to change the zoom.
5431 <b>Alt-Up and Alt-Dn</b> change the automation zoom from the keyboard.
5432
5433 <div class="node">
5434 <a name="TOGGLE-KEYFRAMES"></a>
5435 <p><hr>
5436 Next:&nbsp;<a rel="next" accesskey="n" href="#AUTOMATIC-KEYFRAMES">AUTOMATIC KEYFRAMES</a>,
5437 Previous:&nbsp;<a rel="previous" accesskey="p" href="#NAVIGATING-CURVE-KEYFRAMES">NAVIGATING CURVE KEYFRAMES</a>,
5438 Up:&nbsp;<a rel="up" accesskey="u" href="#KEYFRAMES">KEYFRAMES</a>
5439
5440 </div>
5441
5442 <h3 class="section">13.5 TOGGLE KEYFRAMES</h3>
5443
5444 <p>Mute is the only toggle keyframe.  Mute keyframes determine where the
5445 track is processed but not rendered to the output.  Click-drag on these
5446 curves to create a keyframe.  Unlike curves, the toggle keyframe has
5447 only two values: on or off.  Ctrl and shift do nothing on toggle
5448 keyframes.
5449
5450 <div class="node">
5451 <a name="AUTOMATIC-KEYFRAMES"></a>
5452 <p><hr>
5453 Next:&nbsp;<a rel="next" accesskey="n" href="#COMPOSITOR-KEYFRAMES">COMPOSITOR KEYFRAMES</a>,
5454 Previous:&nbsp;<a rel="previous" accesskey="p" href="#TOGGLE-KEYFRAMES">TOGGLE KEYFRAMES</a>,
5455 Up:&nbsp;<a rel="up" accesskey="u" href="#KEYFRAMES">KEYFRAMES</a>
5456
5457 </div>
5458
5459 <h3 class="section">13.6 AUTOMATIC KEYFRAMES</h3>
5460
5461 <p>You may have noticed when a few fade curves are set up, moving the
5462 insertion point around the curves causes the faders to reflect the
5463 curve value under the insertion point.  This isn't just to look cool.
5464 The faders themselves can set keyframes in automatic keyframe mode.
5465 Automatic keyframe mode is usually more useful than dragging curves.
5466
5467    <p>Enable automatic keyframe mode by enabling the automatic keyframe
5468 toggle <img src="autokeyframe.png" alt="autokeyframe.png">.  In automatic keyframe mode, every time
5469 you tweek a keyframeable parameter it creates a keyframe on the
5470 timeline.  Since automatic keyframes affect many parameters, it's best
5471 enabled just before you need a keyframe and disabled immediately
5472 thereafter.
5473
5474    <p>It's useful to go into the <b>View</b> menu and make the desired
5475 parameter visible before performing a change.  The location where the
5476 automatic keyframe is generated is under the insertion point.  If the
5477 timeline is playing back during a tweek, several automatic keyframes
5478 will be generated as you change the parameter.
5479
5480    <p>When automatic keyframe mode is disabled, a similarly strange thing
5481 happens.  Adjusting a parameter adjusts the keyframe immediately
5482 preceeding the insertion point.  If two fade keyframes exist and the
5483 insertion point is between them, changing the fader changes the first
5484 keyframe.
5485
5486    <p>There are many parameters which can only be keyframed in automatic
5487 keyframe mode.  These are parameters for which curves would take up too
5488 much space on the track or which can't be represented easily by a
5489 curve.
5490
5491    <p>Effects are only keyframable in automatic mode because of the number of
5492 parameters in each individual effect.
5493
5494    <p>Camera and projector translation can only be keyframed in automatic
5495 keyframe mode while camera and projector zoom can be keyframed with
5496 curves.  It is here that we conclude the discussion of compositing,
5497 since compositing is highly dependant on the ability to change over
5498 time.
5499
5500 <div class="node">
5501 <a name="COMPOSITOR-KEYFRAMES"></a>
5502 <p><hr>
5503 Next:&nbsp;<a rel="next" accesskey="n" href="#EDITING-KEYFRAMES">EDITING KEYFRAMES</a>,
5504 Previous:&nbsp;<a rel="previous" accesskey="p" href="#AUTOMATIC-KEYFRAMES">AUTOMATIC KEYFRAMES</a>,
5505 Up:&nbsp;<a rel="up" accesskey="u" href="#KEYFRAMES">KEYFRAMES</a>
5506
5507 </div>
5508
5509 <h3 class="section">13.7 COMPOSITOR KEYFRAMES</h3>
5510
5511 <p>Camera and projector translation is represented by two parameters: x
5512 and y.  Therefore it is cumbersome to adjust with curves.  Cinelerra
5513 solves this problem by relying on automatic keyframes.  With a video
5514 track loaded, move the insertion point to the beginning of the track
5515 and enable automatic keyframe mode.
5516
5517    <p>Move the projector slightly in the compositor window to create a
5518 keyframe.  Then go forward several seconds.  Move the projector a long
5519 distance to create another keyframe and emphasize motion.  This creates
5520 a second projector box in the compositor, with a line joining the two
5521 boxes.  The joining line is the motion path.  If you create more
5522 keyframes, more boxes are created.  Once all the desired keyframes are
5523 created, disable automatic keyframe mode.
5524
5525    <p>Now when scrubbing around with the compositor window's slider, the
5526 video projection moves over time.  At any point between two keyframes,
5527 the motion path is read for all time before the insertion point and
5528 green for all time after the insertion point.  It's debatable if this
5529 is a very useful feature but it makes you feel good to know what
5530 keyframe is going to be affected by the next projector tweek.
5531
5532    <p>Click-drag when automatic keyframes are off to adjust the preceeding
5533 keyframe.  If you're halfway between two keyframes, the first projector
5534 box is adjusted while the second one stays the same.  Furthermore, the
5535 video doesn't appear to move in step with the first keyframe.  This is
5536 because, halfway between two keyframes the projector translation is
5537 interpolated.  In order to set the second keyframe you'll need to scrub
5538 after the second keyframe.
5539
5540    <p>By default the motion path is a straight line, but it can be curved
5541 with control points.  <b>Ctrl-drag</b> to set either the in or out
5542 control point of the preceeding keyframe.  Once again, we depart from
5543 The Gimp because <b>shift</b> is already used for zoom.  After the in
5544 or out control points are extrapolated from the keyframe,
5545 <b>Ctrl-dragging</b> anywhere in the video adjusts the nearest control
5546 point.  A control point can be out of view entirely yet still
5547 controllable.
5548
5549    <p>When editing the camera translation, the behavior of the camera boxes
5550 is slightly different.  Camera automation is normally used for still
5551 photo panning.  The current camera box doesn't move during a drag, but
5552 if multiple keyframes are set, every camera box except the current
5553 keyframe appears to move.  This is because the camera display shows
5554 every other camera position relative to the current one.
5555
5556    <p>The situation becomes more intuitive if you bend the motion path
5557 between two keyframes and scrub between the two keyframes.  The
5558 division between red and green, the current position between the
5559 keyframes, is always centered while the camera boxes move.
5560
5561 <div class="node">
5562 <a name="EDITING-KEYFRAMES"></a>
5563 <p><hr>
5564 Next:&nbsp;<a rel="next" accesskey="n" href="#KEYFRAME-SPANNING">KEYFRAME SPANNING</a>,
5565 Previous:&nbsp;<a rel="previous" accesskey="p" href="#COMPOSITOR-KEYFRAMES">COMPOSITOR KEYFRAMES</a>,
5566 Up:&nbsp;<a rel="up" accesskey="u" href="#KEYFRAMES">KEYFRAMES</a>
5567
5568 </div>
5569
5570 <h3 class="section">13.8 EDITING KEYFRAMES</h3>
5571
5572 <p>Keyframes can be shifted around and moved between tracks on the
5573 timeline using similar cut and paste operations to editing media.  Only
5574 the keyframes selected in the <b>view</b> menu are affected by keyframe
5575 editing operations, however.
5576
5577    <p>The most popular keyframe editing operation is replication of some
5578 curve from one track to the other, to make a stereo pair.  The first
5579 step is to solo the source track's record <img src="recordpatch.png" alt="recordpatch.png"> patch
5580 by <b>shift-clicking</b> on it.  Then either set in/out points or
5581 highlight the desired region of keyframes.  Go to <b>keyframes-&gt;copy
5582 keyframes</b> to copy them to the clipboard.  Solo the destination track's
5583 record <img src="recordpatch.png" alt="recordpatch.png"> patch by <b>shift-clicking</b> on it and
5584 go to <b>keyframes-&gt;paste keyframes</b> to paste the clipboard.
5585
5586    <p>The media editing commands are mapped to the keyframe editing commands
5587 by using the <b>shift</b> key instead of just the keyboard shortcut.
5588
5589    <p>This leads to the most complicated part of keyframe editing, the
5590 default keyframe.  Remember that when no keyframes are set at all,
5591 there is still a default keyframe which stores a global parameter for
5592 the entire duration.  The default keyframe isn't drawn because it
5593 always exists.  What if the default keyframe is a good value which you
5594 want to transpose between other non-default keyframes?  The
5595 <b>keyframes-&gt;copy default keyframe</b> and <b>keyframes-&gt;paste
5596 default keyframe</b> allow conversion of the default keyframe to a
5597 non-default keyframe.
5598
5599    <p><b>Keyframes-&gt;copy default keyframe</b> copies the default keyframe to
5600 the clipboard, no matter what region of the timeline is selected.  The
5601 <b>keyframes-&gt;paste keyframes</b> function may then be used to paste
5602 the clipboard as a non-default keyframe.
5603
5604    <p>If you've copied a non-default keyframe, it can be stored as the
5605 default keyframe by calling <b>keyframes-&gt;paste default keyframe</b>.
5606 After using paste default keyframe to convert a non-default keyframe
5607 into a default keyframe, you won't see the value of the default
5608 keyframe reflected until all the non-default keyframes are removed.
5609
5610    <p>Finally, there is a convenient way to delete keyframes besides
5611 selecting a region and calling <b>keyframes-&gt;clear keyframes</b>.
5612 Merely click-drag a keyframe before its preceeding keyframe or after
5613 its following keyframe on the track.
5614
5615 <div class="node">
5616 <a name="KEYFRAME-SPANNING"></a>
5617 <p><hr>
5618 Previous:&nbsp;<a rel="previous" accesskey="p" href="#EDITING-KEYFRAMES">EDITING KEYFRAMES</a>,
5619 Up:&nbsp;<a rel="up" accesskey="u" href="#KEYFRAMES">KEYFRAMES</a>
5620
5621 </div>
5622
5623 <h3 class="section">13.9 KEYFRAME SPANNING</h3>
5624
5625 <p>To change a single parameter in multiple keyframes without changing the
5626 other parameters, highlight a region on the timeline and adjust the
5627 parameter.  Instead of a new keyframe being created, the existing
5628 keyframes are modified and only the changed parameter is modified.
5629
5630    <p>It doesn't matter if <img src="autokeyframe.png" alt="autokeyframe.png"> auto keyframe is enabled.  It
5631 only works when the keyframe stores multiple parameters.  Only mask and
5632 effect keyframes do this.  Other types of keyframes are generated as usual.
5633
5634 <div class="node">
5635 <a name="CAPTURING-MEDIA"></a>
5636 <p><hr>
5637 Next:&nbsp;<a rel="next" accesskey="n" href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>,
5638 Previous:&nbsp;<a rel="previous" accesskey="p" href="#KEYFRAMES">KEYFRAMES</a>,
5639 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
5640
5641 </div>
5642
5643 <h2 class="chapter">14 CAPTURING MEDIA</h2>
5644
5645 <p>Ideally, all media would be stored on hard drives, CD-ROM, flash, or
5646 DVD and loading it into Cinelerra would be a matter of loading a file.
5647 In reality, very few sources of media can be accessed like a filesystem
5648 but instead rely on tape transport mechanisms and dumb I/O mechanisms
5649 to transfer the data to computers.  These media types are imported into
5650 Cinelerra through the Record dialog.
5651
5652    <p>The first step in recording is to configure the input device.  In
5653 <b>Settings-&gt;preferences</b> are a number of recording parameters
5654 described in configuration See <a href="#RECORDING">RECORDING</a>.  These parameters apply to
5655 recording no matter what the project settings are, because the
5656 recording parameters are usually the maximum capability of the
5657 recording hardware while project settings come and go.
5658
5659    <p>Go to <b>File-&gt;record</b> to record a dumb I/O source.  This prompts
5660 for an output format much like rendering does.  Once that's done, the
5661 record window and the record monitor pop up.
5662
5663    <p>The record window has discrete sections.  While many parameters change
5664 depending on if the file has audio or video, the discrete sections are
5665 always the same.
5666
5667      <ul>
5668 <li>
5669 The output format area describes the format of the output file and the
5670 current position within it.
5671
5672      <li>
5673 The edit batch area lets you change parameters in the current batch.
5674
5675      <li>
5676 The transport controls start and stop recording different ways.
5677
5678      <li>
5679 The batch list displays all the defined batches.
5680
5681      <li>
5682 The confirmation area lets you determine how the output files are
5683 imported into the timeline and quit.
5684
5685    </ul>
5686
5687    <div class="block-image"><img src="recording.png" alt="recording.png"></div>
5688    <pre class="sp">
5689
5690
5691 </pre>
5692 <b>Recording window areas</b>
5693
5694    <p>Recording in Cinelerra is organized around batches.  A batch
5695 essentially defines a distinct output file for the recording.  For now
5696 you can ignore the batch concept entirely and record merely by hitting
5697 the record button <img src="record.png" alt="record.png">.
5698
5699    <p>The record button opens the current output file if it isn't opened and
5700 writes captured data to it.  Use the stop button to stop the
5701 recording.  Recording can be resumed with the record button without
5702 erasing the file at this point.  In the case of a video file, there is
5703 a single frame record button <img src="singleframe.png" alt="singleframe.png"> which records a single
5704 frame.
5705
5706    <p>When enough media is recorded, choose an insertion method from the
5707 <b>Insertion Strategy</b> menu and hit <b>close</b>.
5708
5709 <ul class="menu">
5710 <li><a accesskey="1" href="#BATCHES">BATCHES</a>
5711 <li><a accesskey="2" href="#EDITING-TUNER-INFORMATION">EDITING TUNER INFORMATION</a>
5712 </ul>
5713
5714 <div class="node">
5715 <a name="BATCHES"></a>
5716 <p><hr>
5717 Next:&nbsp;<a rel="next" accesskey="n" href="#EDITING-TUNER-INFORMATION">EDITING TUNER INFORMATION</a>,
5718 Up:&nbsp;<a rel="up" accesskey="u" href="#CAPTURING-MEDIA">CAPTURING MEDIA</a>
5719
5720 </div>
5721
5722 <h3 class="section">14.1 BATCHES</h3>
5723
5724 <p>Now we come to the concept of batches.  Batches try to make the dumb
5725 I/O look more like a filesystem.  Batches are traditionally used to
5726 divide tape into different programs and save the different programs as
5727 different files instead of recording straight through an entire tape.
5728 Because of the high cost of developing frame-accurate deck control
5729 mechanisms, the only use of batches now is recording different programs
5730 during different times of day.  This is still useful for recording TV
5731 shows or time lapse movies as anyone who can't afford proper appliances
5732 knows.
5733
5734    <p>The record window supports a list of batches and two recording modes:
5735 interactive and batch recording.  Interactive recording happens when
5736 the record button is pressed.  Interactive recording starts immediately
5737 and uses the current batch to determine everything except start time.
5738 By default, the current batch is configured to behave like tape.
5739
5740    <p>Batch recording happens when the <b>start</b> button is pressed.  In
5741 batch recording, the <b>start time</b> is the time the batch starts
5742 recording.
5743
5744    <p>First, you'll want to create some batches.  Each batch has certain
5745 parameters and methods of adjustment.
5746
5747      <ul>
5748 <li>
5749 <b>On</b> determines whether the batch is included in batch recording
5750 operations.  Click the list row under <b>On</b> to enable or disable
5751 batches.
5752
5753      <li>
5754 <b>Path</b> is the file the batch is going to be recorded to.  The
5755 filename specified in the record dialog is the name of the first batch,
5756 to simplify interactive recording, but the filename may be changed in
5757 the record window for any batch in the <b>edit batch</b> area.
5758
5759      <li>
5760 <b>News</b> shows whether the file exists or not.  This is a very
5761 important attribute since there is no confirmation dialog if the file
5762 exists.  The first time you hit record, the file is opened.  If the
5763 file exists at this point it's erased.  News says <b>File exists</b> if
5764 it exists and <b>OK</b> if it doesn't.  Every time you resume recording
5765 in the same batch, the news should say <b>Open</b>, indicating the file
5766 is already opened and won't be erased in the next record button press.
5767
5768      <p>If you change out of the current batch after recording, the file is
5769 closed.  Next time you change into the batch, the file will be erased.
5770
5771      <li>
5772 <b>Start time</b> is the 24 hour time of day the batch will start
5773 recording if in batch mode.  The start time may become a time of tape
5774 and reel number if deck control is implemented but for now it's a time
5775 of day.
5776
5777      <li>
5778 <b>Duration</b> is the length of the batch.  It only has meaning if the
5779 <b>Mode</b> of the batch is <b>Timed</b>.  Once the recording length
5780 reaches <b>duration</b> the recording stops, whether in interactive or
5781 batch mode.
5782
5783      <li>
5784 <b>Source</b> has meaning only when the capturing hardware has multiple
5785 sources.  Usually the source is a tuner channel or input.  When the
5786 current batch finishes and the next batch begins recording, the source
5787 is changed to what the next batch is set to.  This way multiple TV
5788 stations can be recorded at different times.
5789
5790    </ul>
5791
5792    <p>The record window has a notion of the <b>current batch</b>.  The
5793 current batch is not the same as the batch which is highlighted in the
5794 batch list.  The current batch text is colored red in the batch list.
5795 The highlighted batch is merely displayed in the edit batch section for
5796 editing.
5797
5798    <p>By coloring the current batch red, any batch can be edited by
5799 highlighting it, without changing the batch to be recorded.
5800
5801    <p>All recording operations take place in the current batch.   If there
5802 are multiple batches, highlight the desired batch and hit
5803 <b>activate</b> to make it the current batch.  If the <b>start</b>
5804 button is pressed, the current batch flashes to indicate it's waiting
5805 for the start time in batch mode.  If the <b>record</b> button is
5806 pressed, the current batch is recorded immediately in interactive mode.
5807
5808    <p>In batch and interactive recording modes, when the current batch
5809 finishes recording the next batch is activated and performed.  All
5810 future recording is done in batch mode.  When the first batch finishes,
5811 the next batch flashes until its start time is reached.
5812
5813    <p>Interrupt either the batch or the interactive operation by hitting the
5814 stop button.
5815
5816    <p>Finally there is the <img src="rewind.png" alt="rewind.png"> rewind button.  In either
5817 interactive or batch recording, the rewind button causes the current
5818 batch to close its file.  The next recording operation in the current
5819 batch deletes the file.
5820
5821 <div class="node">
5822 <a name="EDITING-TUNER-INFORMATION"></a>
5823 <p><hr>
5824 Previous:&nbsp;<a rel="previous" accesskey="p" href="#BATCHES">BATCHES</a>,
5825 Up:&nbsp;<a rel="up" accesskey="u" href="#CAPTURING-MEDIA">CAPTURING MEDIA</a>
5826
5827 </div>
5828
5829 <h3 class="section">14.2 EDITING TUNER INFORMATION</h3>
5830
5831 <p>Sometimes in the recording process and the configuration process,
5832 you'll need to define and select tuner channels to either record or
5833 play back to.  In the case of the Video4Linux and Buz recording
5834 drivers, tuner channels define the source.  When the Buz driver is also
5835 used for playback, tuner channels define the destination.
5836
5837    <p>Defining tuner channels is accomplished by pushing the <img src="channel.png" alt="channel.png">
5838 channel button.  This brings up the channel editing window.  In this
5839 window you add, edit, and sort channels.  Also, for certain video
5840 drivers, you can adjust the picture quality.
5841
5842    <p>The <b>add</b> operation brings up a channel editing box.  The title of
5843 the channel appears in the channel list.  The source of the channel is
5844 the entry in the physical tuner's frequency table corresponding to the
5845 title.
5846
5847    <p>Fine tuning in the channel edit dialog adjusts the physical frequency
5848 slightly if the driver supports it.  The norm and frequency table
5849 together define which frequency table is selected for defining
5850 sources.  If the device supports multiple inputs, the input menu
5851 selects these.
5852
5853    <p>To sort channels, highlight the channel in the list and push <b>move
5854 up</b> or <b>move down</b> to move it.
5855
5856    <p>Once channels are defined, the <b>source</b> item in the record window
5857 can be used to select channels for recording.  The same channel
5858 selecting ability also exists in the record monitor window.  Be aware
5859 channel selections in the record monitor window and the record window
5860 are stored in the current batch.
5861
5862    <p>For some drivers an option to <b>swap fields</b> may be visible.  These
5863 drivers don't get the field order right every time without human
5864 intervention.  Toggle this to get the odd and even lines to record in
5865 the right order.
5866
5867 <div class="node">
5868 <a name="IMPROVING-PERFORMANCE"></a>
5869 <p><hr>
5870 Next:&nbsp;<a rel="next" accesskey="n" href="#TROUBLESHOOTING">TROUBLESHOOTING</a>,
5871 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CAPTURING-MEDIA">CAPTURING MEDIA</a>,
5872 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
5873
5874 </div>
5875
5876 <h2 class="chapter">15 IMPROVING PERFORMANCE</h2>
5877
5878 <p>Let's get one thing perfectly clear.  Linux is not a very good
5879 desktop.  It's a server.  Most of what you'll find on modern Linux
5880 distributions are faceless, network-only programs strategicly designed
5881 to counteract one Microsoft server feature or another and not to
5882 perform very well at user interaction.  There are a number of
5883 parameters on Linux, which ordinary people can adjust to make it behave
5884 more like a thoroughbred in desktop usage.
5885
5886 <ul class="menu">
5887 <li><a accesskey="1" href="#DISABLING-SWAP-SPACE">DISABLING SWAP SPACE</a>
5888 <li><a accesskey="2" href="#ENLARGING-SOUND-BUFFERS">ENLARGING SOUND BUFFERS</a>
5889 <li><a accesskey="3" href="#FREEING-MORE-SHARED-MEMORY">FREEING MORE SHARED MEMORY</a>
5890 <li><a accesskey="4" href="#SPEEDING-UP-THE-HARD-DRIVE">SPEEDING UP THE HARD DRIVE</a>
5891 <li><a accesskey="5" href="#DISABLING-CRON">DISABLING CRON</a>
5892 <li><a accesskey="6" href="#REDUCING-USB-MOUSE-SENSITIVITY">REDUCING USB MOUSE SENSITIVITY</a>
5893 <li><a accesskey="7" href="#ASSORTED-X-TWEEKS">ASSORTED X TWEEKS</a>
5894 <li><a accesskey="8" href="#SPEEDING-UP-THE-FILE-SYSTEM">SPEEDING UP THE FILE SYSTEM</a>
5895 <li><a accesskey="9" href="#IMPROVING-ZORAN-VIDEO">IMPROVING ZORAN VIDEO</a>
5896 </ul>
5897
5898 <div class="node">
5899 <a name="DISABLING-SWAP-SPACE"></a>
5900 <p><hr>
5901 Next:&nbsp;<a rel="next" accesskey="n" href="#ENLARGING-SOUND-BUFFERS">ENLARGING SOUND BUFFERS</a>,
5902 Up:&nbsp;<a rel="up" accesskey="u" href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>
5903
5904 </div>
5905
5906 <h3 class="section">15.1 DISABLING SWAP SPACE</h3>
5907
5908 <p>On systems with lots of memory, Cinelerra sometimes runs better without
5909 a swap space.  If you have 4 GB of RAM, you're probably better off
5910 without a swap space.  If you have 512MB of RAM, you should keep the
5911 swap.  If you want to do recording, you should probably disable swap
5912 space in any case.  There's a reason for this.  Linux only allows half
5913 the available memory to be used.  Beyond that, it starts searching for
5914 free pages to swap, in order to cache more disk access.  In a 4 GB
5915 system, you start waiting for page swaps after using only 2 GB.
5916
5917    <p>The question then is how to make Linux run without a swap space.
5918 Theoretically it should be a matter of running
5919
5920 <pre class="example">     swapoff -a
5921 </pre>
5922    <p>Unfortunately, without a swap space the <b>kswapd</b> tasklet normally
5923 spins at 100%.  To eliminate this problem, edit <b>linux/mm/vmscan.c</b>.
5924 In this file, put a line saying <b>return 0;</b> before it says
5925
5926 <pre class="example">           /*
5927          * Kswapd main loop.
5928          */
5929 </pre>
5930    <p>Then recompile the kernel.
5931
5932 <div class="node">
5933 <a name="ENLARGING-SOUND-BUFFERS"></a>
5934 <p><hr>
5935 Next:&nbsp;<a rel="next" accesskey="n" href="#FREEING-MORE-SHARED-MEMORY">FREEING MORE SHARED MEMORY</a>,
5936 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DISABLING-SWAP-SPACE">DISABLING SWAP SPACE</a>,
5937 Up:&nbsp;<a rel="up" accesskey="u" href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>
5938
5939 </div>
5940
5941 <h3 class="section">15.2 ENLARGING SOUND BUFFERS</h3>
5942
5943 <p>In order to improve realtime performance, the audio buffers for all the
5944 Linux sound drivers were limited from 128k to 64k.  For recording audio
5945 and video simultaneously and for most audio recording this causes
5946 dropouts.  Application of low latency and preemtible kernel patches
5947 make it possible to record more audio recordings but it doesn't improve
5948 recording video with audio.  This is where you need to hack the kernel.
5949
5950    <p>To see if your sound buffers are suitable, run the included
5951 <b>soundtest</b> program with nothing playing or recording.  This
5952 allocates the largest possible buffers and displays them.  If the
5953 <b>TOTAL BYTES AVAILABLE</b> is under 131072, you need to see about
5954 getting the buffers enlarged in the driver.  While many drivers differ,
5955 we have a hack for at least one driver.
5956
5957    <p>This only applies to the OSS version of the Soundblaster Live driver.
5958 Since every sound card and every sound driver derivative has a
5959 different implementation you'll need to do some searching for other
5960 sound cards.  Edit <b>linux/drivers/sound/emu10k1/audio.c</b>
5961
5962    <p>Where is says
5963
5964 <pre class="example">     if (bufsize &gt;= 0x10000)
5965 </pre>
5966    <p>change it to say
5967
5968 <pre class="example">     if (bufsize &gt; 0x40000)
5969 </pre>
5970    <p>Where is says
5971
5972 <pre class="example">                   for (i = 0; i &lt; 8; i++)
5973                         for (j = 0; j &lt; 4; j++)
5974 </pre>
5975    <p>change it to say
5976
5977 <pre class="example">                   for (i = 0; i &lt; 16; i++)
5978                         for (j = 0; j &lt; 4; j++)
5979 </pre>
5980    <p>In <b>linux/drivers/sound/emu10k1/hwaccess.h</b>
5981
5982    <p>Change
5983
5984    <p><b>#define MAXBUFSIZE     65536</b>
5985
5986    <p>to
5987
5988    <p><b>#define MAXBUFSIZE     262144</b>
5989
5990    <p>Finally, in <b>linux/drivers/sound/emu10k1/cardwi.h</b>
5991
5992    <p><b>#define WAVEIN_MAXBUFSIZE         65536</b>
5993
5994    <p>to
5995
5996    <p><b>#define WAVEIN_MAXBUFSIZE         262144</b>
5997
5998    <p>Then recompile the kernel modules.
5999
6000 <div class="node">
6001 <a name="FREEING-MORE-SHARED-MEMORY"></a>
6002 <p><hr>
6003 Next:&nbsp;<a rel="next" accesskey="n" href="#SPEEDING-UP-THE-HARD-DRIVE">SPEEDING UP THE HARD DRIVE</a>,
6004 Previous:&nbsp;<a rel="previous" accesskey="p" href="#ENLARGING-SOUND-BUFFERS">ENLARGING SOUND BUFFERS</a>,
6005 Up:&nbsp;<a rel="up" accesskey="u" href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>
6006
6007 </div>
6008
6009 <h3 class="section">15.3 FREEING MORE SHARED MEMORY</h3>
6010
6011 <p>The Linux kernel only allows 32MB of shared memory to be allocated by
6012 default.  This needs to be increased to do anything useful.  Run the
6013 following command:
6014
6015    <p><b>echo "0x7fffffff" &gt; /proc/sys/kernel/shmmax</b>
6016
6017 <div class="node">
6018 <a name="SPEEDING-UP-THE-HARD-DRIVE"></a>
6019 <p><hr>
6020 Next:&nbsp;<a rel="next" accesskey="n" href="#DISABLING-CRON">DISABLING CRON</a>,
6021 Previous:&nbsp;<a rel="previous" accesskey="p" href="#FREEING-MORE-SHARED-MEMORY">FREEING MORE SHARED MEMORY</a>,
6022 Up:&nbsp;<a rel="up" accesskey="u" href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>
6023
6024 </div>
6025
6026 <h3 class="section">15.4 SPEEDING UP THE HARD DRIVE</h3>
6027
6028 <p>This is a very popular command sequence among Linux gurus, which is not
6029 done by default on Linux distributions.
6030
6031    <p><b>hdparm -c3 -d1 -u1 -k1 /dev/hda</b>
6032
6033    <p><b>-c3</b> puts the hard drive into 32 bit I/O with sync.  This normally
6034 doesn't work due to inept kernel support for most IDE controllers.  If
6035 you get lost interrupt or SeekComplete errors, quickly use <b>-c0</b>
6036 instead of <b>-c3</b> in your command.
6037
6038    <p><b>-d1</b> enables DMA of course.  This frees up the CPU partially during
6039 data transfers.
6040
6041    <p><b>-u1</b> allows multiple interrupts to be handled during hard drive
6042 transactions.  This frees up even more CPU time.
6043
6044    <p><b>-k1</b> prevents Linux from resetting your settings in case of a
6045 glitch.
6046
6047 <div class="node">
6048 <a name="DISABLING-CRON"></a>
6049 <p><hr>
6050 Next:&nbsp;<a rel="next" accesskey="n" href="#REDUCING-USB-MOUSE-SENSITIVITY">REDUCING USB MOUSE SENSITIVITY</a>,
6051 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SPEEDING-UP-THE-HARD-DRIVE">SPEEDING UP THE HARD DRIVE</a>,
6052 Up:&nbsp;<a rel="up" accesskey="u" href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>
6053
6054 </div>
6055
6056 <h3 class="section">15.5 DISABLING CRON</h3>
6057
6058 <p>Linux runs some daily operations like compressing man pages.  These may
6059 be acceptable background tasks while compiling or word processing but
6060 not while playing video.  Disable these operations by editing
6061 <b>/etc/rc.d/init.d/anacron</b>.
6062
6063    <p>Put <b>exit</b> before the first line not beginning in <b>#</b>.
6064
6065    <p>In <b>/etc/rc.d/init.d/crond</b> put <b>exit</b> before the first line not
6066 beginning in <b>#</b>.  Then make like Win 2000 and reboot.
6067
6068    <p>You can't use the <b>at</b> command anymore, but who uses that command
6069 anyways?
6070
6071 <div class="node">
6072 <a name="REDUCING-USB-MOUSE-SENSITIVITY"></a>
6073 <p><hr>
6074 Next:&nbsp;<a rel="next" accesskey="n" href="#ASSORTED-X-TWEEKS">ASSORTED X TWEEKS</a>,
6075 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DISABLING-CRON">DISABLING CRON</a>,
6076 Up:&nbsp;<a rel="up" accesskey="u" href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>
6077
6078 </div>
6079
6080 <h3 class="section">15.6 REDUCING USB MOUSE SENSITIVITY</h3>
6081
6082 <p>Gamers like high resolution mice, but this can be painful for precisely
6083 positioning the mouse on a timeline or video screen.  XFree86 once
6084 allowed you to reduce PS/2 mouse sensitivity using commands like
6085 <b>xset m 1 1</b> but you're out of luck with USB mice or KVM's.
6086
6087    <p>We have a way to reduce USB mouse sensitivity but it requires editing
6088 the kernel source code.  Even though USB mice have been supported for
6089 years, the kernel source code for USB mice is constantly being
6090 rewritten.  These instructions were relevant for 2.6.12.3.  Edit
6091 <b>/usr/src/linux/drivers/input/mousedev.c</b>.
6092
6093    <p>After the line saying
6094
6095 <pre class="example">     struct mousedev_hw_data {
6096 </pre>
6097    <p>put
6098
6099 <pre class="example">     #define DOWNSAMPLE_N 100
6100      #define DOWNSAMPLE_D 350
6101      int x_accum, y_accum;
6102 </pre>
6103    <p>Next, the section which says something like:
6104
6105 <pre class="example">     switch (code) {
6106         case REL_X:     mousedev-&gt;packet.dx += value; break;
6107         case REL_Y:     mousedev-&gt;packet.dy -= value; break;
6108         case REL_WHEEL: mousedev-&gt;packet.dz -= value; break;
6109      }
6110 </pre>
6111    <p>must be replaced by
6112
6113 <pre class="example">
6114         switch (code) {
6115                         case REL_X:
6116                                 mousedev-&gt;packet.x_accum += value * DOWNSAMPLE_N;
6117                                 mousedev-&gt;packet.dx += (int)mousedev-&gt;packet.x_accum / (int)DOWNSAMPLE_D;
6118                                 mousedev-&gt;packet.x_accum -= ((int)mousedev-&gt;packet.x_accum / (int)DOWNSAMPLE_D) * (int)DOWNSAMPLE_D;
6119                                 break;
6120                         case REL_Y:
6121                                 mousedev-&gt;packet.y_accum += value * DOWNSAMPLE_N;
6122                                 mousedev-&gt;packet.dy -= (int)mousedev-&gt;packet.y_accum / (int)DOWNSAMPLE_D;
6123                                 mousedev-&gt;packet.y_accum -= ((int)mousedev-&gt;packet.y_accum / (int)DOWNSAMPLE_D) * (int)DOWNSAMPLE_D;
6124                                 break;
6125                         case REL_WHEEL: mousedev-&gt;packet.dz -= value; break;
6126         }
6127
6128
6129
6130 </pre>
6131    <p>Change the value of <b>DOWNSAMPLE_N</b> to change the mouse sensitivity.
6132
6133 <div class="node">
6134 <a name="ASSORTED-X-TWEEKS"></a>
6135 <p><hr>
6136 Next:&nbsp;<a rel="next" accesskey="n" href="#SPEEDING-UP-THE-FILE-SYSTEM">SPEEDING UP THE FILE SYSTEM</a>,
6137 Previous:&nbsp;<a rel="previous" accesskey="p" href="#REDUCING-USB-MOUSE-SENSITIVITY">REDUCING USB MOUSE SENSITIVITY</a>,
6138 Up:&nbsp;<a rel="up" accesskey="u" href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>
6139
6140 </div>
6141
6142 <h3 class="section">15.7 ASSORTED X TWEEKS</h3>
6143
6144 <p>XFree86 by default can't display Cinelerra's advanced pixmap rendering
6145 very fast.  The X server stalls during list box drawing.  Fix this by
6146 adding a line to your XF86Config* files.
6147
6148    <p>In the <b>Section "Device"</b> area, add a line saying:
6149
6150    <p><b>Option "XaaNoOffscreenPixmaps"</b>
6151
6152    <p>and restart the X server.
6153
6154    <p>Screen blanking is really annoying, unless you're fabulously rich and
6155 can afford to leave your monitor on 24 hours a day without power saving
6156 mode.  In <b>/etc/X11/xinit/xinitrc</b> put
6157
6158 <pre class="example">     xset s off
6159      xset s noblank
6160 </pre>
6161    <p>before the first <b>if</b> statement.
6162
6163    <p>How about those windows keys which no Linux distribution even thinks to
6164 use.  You can make the window keys provide ALT functionality by editing
6165 <b>/etc/X11/Xmodmap</b>.  Append the following to it.
6166
6167 <pre class="example">     keycode 115 = Hyper_L
6168      keycode 116 = Hyper_R
6169      add mod4 = Hyper_L
6170      add mod5 = Hyper_R
6171 </pre>
6172    <p>The actual changes to a window manager to make it recognize window keys
6173 for ALT are complex.  In <b>FVWM</b> at least, you can edit
6174 <b>/etc/X11/fvwm/system.fvwm2rc</b> and put
6175
6176 <pre class="example">     Mouse 0 T A move-and-raise-or-raiselower
6177      #Mouse 0 W M move
6178      Mouse 0 W 4 move
6179      Mouse 0 W 5 move
6180      Mouse 0 F A resize-or-raiselower
6181      Mouse 0 S A resize-or-raiselower
6182 </pre>
6183    <p>in place of the default section for moving and resizing.  Your best
6184 performance is going to be on FVWM.  Other window managers seem to slow
6185 down video with extra event trapping and aren't as efficient in layout.
6186
6187 <div class="node">
6188 <a name="SPEEDING-UP-THE-FILE-SYSTEM"></a>
6189 <p><hr>
6190 Next:&nbsp;<a rel="next" accesskey="n" href="#IMPROVING-ZORAN-VIDEO">IMPROVING ZORAN VIDEO</a>,
6191 Previous:&nbsp;<a rel="previous" accesskey="p" href="#ASSORTED-X-TWEEKS">ASSORTED X TWEEKS</a>,
6192 Up:&nbsp;<a rel="up" accesskey="u" href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>
6193
6194 </div>
6195
6196 <h3 class="section">15.8 SPEEDING UP THE FILE SYSTEM</h3>
6197
6198 <p>You'll often store video on an expensive, gigantic disk array separate
6199 from your boot disk.  You'll thus have to manually install an EXT
6200 filesystem on this disk array, using the <b>mke2fs</b> command.  By far
6201 the fastest file system is
6202
6203 <pre class="example">
6204      mke2fs -i 65536 -b 4096 my_device
6205      tune2fs -r0 -c10000 my_device
6206
6207 </pre>
6208    <p>This has no journaling, reserves as few blocks as possible for
6209 filenames, and accesses the largest amount of data per block possible.
6210 A slightly slower file system, which is easier to recover after power
6211 failures is
6212
6213 <pre class="example">
6214      mke2fs -j -i 65536 -b 4096 my_device
6215      tune2fs -r0 -c10000 my_device
6216
6217 </pre>
6218    <p>This adds a journal which slows down the writes but makes us immune to
6219 power failures.
6220
6221 <div class="node">
6222 <a name="IMPROVING-ZORAN-VIDEO"></a>
6223 <p><hr>
6224 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SPEEDING-UP-THE-FILE-SYSTEM">SPEEDING UP THE FILE SYSTEM</a>,
6225 Up:&nbsp;<a rel="up" accesskey="u" href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>
6226
6227 </div>
6228
6229 <h3 class="section">15.9 IMPROVING ZORAN VIDEO</h3>
6230
6231 <p>Video recorded from the ZORAN inputs is normally unaligned or not
6232 completely encoded on the right.  This can be slightly compensated by
6233 adjusting parameters in the driver sourcecode.
6234
6235    <p>In <b>/usr/src/linux/drivers/media/video/zr36067.c</b> the structures
6236 defined near line 623 affect alignment.  At least for NTSC, the 2.4.20
6237 version of the driver could be improved by changing
6238
6239 <pre class="example">     static struct tvnorm f60ccir601 = { 858, 720, 57, 788, 525, 480, 16 };
6240 </pre>
6241    <p>to
6242
6243 <pre class="example">     static struct tvnorm f60ccir601 = { 858, 720, 57, 788, 525, 480, 17 };
6244 </pre>
6245    <p>In <b>/usr/src/linux/drivers/media/video/bt819.c</b> more structures near
6246 line 76 affect alignment and encoding.
6247
6248    <p>For NTSC
6249
6250 <pre class="example">     {858 - 24, 2, 523, 1, 0x00f8, 0x0000},
6251 </pre>
6252    <p>could be changed to
6253 <pre class="example">     {868 - 24, 2, 523, 1, 0x00f8, 0x0000},
6254 </pre>
6255    <p>Adjusting these parameters may or may not move your picture closer to
6256 the center.  More of the time, they'll cause the driver to lock up
6257 before capturing the first frame.
6258
6259 <h4 class="subsection">15.9.1 NEW IN 2.6.5</h4>
6260
6261 <p>In the 2.6 kernels, the video subsystem was rewritten again from
6262 scratch.  To adjust the Zoran parameters go to
6263 <b>drivers/media/video/zoran_card.c</b> and look for a group of lines like
6264
6265 <pre class="example">     static struct tvnorm f50sqpixel = { 944, 768, 83, 880, 625, 576, 16 };
6266      static struct tvnorm f60sqpixel = { 780, 640, 51, 716, 525, 480, 12 };
6267      static struct tvnorm f50ccir601 = { 864, 720, 75, 804, 625, 576, 18 };
6268      static struct tvnorm f60ccir601 = { 858, 720, 57, 788, 525, 480, 16 };
6269
6270      static struct tvnorm f50ccir601_lml33 = { 864, 720, 75+34, 804, 625, 576, 18 };
6271      static struct tvnorm f60ccir601_lml33 = { 858, 720, 57+34, 788, 525, 480, 16 };
6272
6273      /* The DC10 (57/16/50) uses VActive as HSync, so HStart must be 0 */
6274      static struct tvnorm f50sqpixel_dc10 = { 944, 768, 0, 880, 625, 576, 0 };
6275      static struct tvnorm f60sqpixel_dc10 = { 780, 640, 0, 716, 525, 480, 12 };
6276
6277      /* FIXME: I cannot swap U and V in saa7114, so i do one
6278       * pixel left shift in zoran (75 -&gt; 74)
6279       * (Maxim Yevtyushkin &lt;max@linuxmedialabs.com&gt;) */
6280      static struct tvnorm f50ccir601_lm33r10 = { 864, 720, 74+54, 804, 625, 576, 18 };
6281      static struct tvnorm f60ccir601_lm33r10 = { 858, 720, 56+54, 788, 525, 480, 16 };
6282 </pre>
6283    <p>These seem to control the image position.  At least for the LML33 the
6284 following definition for <b>f60ccir601_lml33</b> does the trick.
6285
6286 <pre class="example">     static struct tvnorm f60ccir601_lml33 = { 858, 720, 67+34, 788, 525, 480, 13 };
6287 </pre>
6288    <div class="node">
6289 <a name="TROUBLESHOOTING"></a>
6290 <p><hr>
6291 Next:&nbsp;<a rel="next" accesskey="n" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>,
6292 Previous:&nbsp;<a rel="previous" accesskey="p" href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>,
6293 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
6294
6295 </div>
6296
6297 <h2 class="chapter">16 TROUBLESHOOTING</h2>
6298
6299 <ul class="menu">
6300 <li><a accesskey="1" href="#BUZ-DRIVER-CRASHES">BUZ DRIVER CRASHES</a>
6301 <li><a accesskey="2" href="#DRAGGING-IN-AND-OUT-POINTS-DOESN_0027T-WORK">DRAGGING IN AND OUT POINTS DOESN'T WORK</a>
6302 <li><a accesskey="3" href="#LOCKING-UP-WHEN-LOADING-FILES">LOCKING UP WHEN LOADING FILES</a>
6303 <li><a accesskey="4" href="#SYNCHRONIZATION-LOST-WHILE-RECORDING">SYNCHRONIZATION LOST WHILE RECORDING</a>
6304 <li><a accesskey="5" href="#APPLYING-LINEARIZE-FOLLOWED-BY-BLUR-DOESN_0027T-WORK">APPLYING LINEARIZE FOLLOWED BY BLUR DOESN'T WORK</a>
6305 </ul>
6306
6307 <div class="node">
6308 <a name="BUZ-DRIVER-CRASHES"></a>
6309 <p><hr>
6310 Next:&nbsp;<a rel="next" accesskey="n" href="#DRAGGING-IN-AND-OUT-POINTS-DOESN_0027T-WORK">DRAGGING IN AND OUT POINTS DOESN'T WORK</a>,
6311 Up:&nbsp;<a rel="up" accesskey="u" href="#TROUBLESHOOTING">TROUBLESHOOTING</a>
6312
6313 </div>
6314
6315 <h3 class="section">16.1 BUZ DRIVER CRASHES</h3>
6316
6317 <p>First, Zoran capture boards must be accessed using the <b>Buz</b> video
6318 driver in <b>Preferences-&gt;Recording</b> and <b>Preferences-&gt;Playback</b>.
6319 Some performance tweeks are available in another section.
6320 See <a href="#IMPROVING-PERFORMANCE">IMPROVING PERFORMANCE</a>.
6321
6322    <p>Once tweeked, the Buz driver seems to crash if the number of recording
6323 buffers is too high.  Make sure <b>Preferences-&gt;Recording-&gt;Frames to
6324 buffer in device</b> is below 10.
6325
6326 <div class="node">
6327 <a name="DRAGGING-IN-AND-OUT-POINTS-DOESN'T-WORK"></a>
6328 <a name="DRAGGING-IN-AND-OUT-POINTS-DOESN_0027T-WORK"></a>
6329 <p><hr>
6330 Next:&nbsp;<a rel="next" accesskey="n" href="#LOCKING-UP-WHEN-LOADING-FILES">LOCKING UP WHEN LOADING FILES</a>,
6331 Previous:&nbsp;<a rel="previous" accesskey="p" href="#BUZ-DRIVER-CRASHES">BUZ DRIVER CRASHES</a>,
6332 Up:&nbsp;<a rel="up" accesskey="u" href="#TROUBLESHOOTING">TROUBLESHOOTING</a>
6333
6334 </div>
6335
6336 <h3 class="section">16.2 DRAGGING IN AND OUT POINTS DOESN'T WORK</h3>
6337
6338 <p>Sometimes there will be two edits really close together.  The point
6339 selected for dragging may be next to the indended edit on an edit too
6340 small to see at the current zoom level.  Zoom in horizontally.
6341
6342 <div class="node">
6343 <a name="LOCKING-UP-WHEN-LOADING-FILES"></a>
6344 <p><hr>
6345 Next:&nbsp;<a rel="next" accesskey="n" href="#SYNCHRONIZATION-LOST-WHILE-RECORDING">SYNCHRONIZATION LOST WHILE RECORDING</a>,
6346 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DRAGGING-IN-AND-OUT-POINTS-DOESN_0027T-WORK">DRAGGING IN AND OUT POINTS DOESN'T WORK</a>,
6347 Up:&nbsp;<a rel="up" accesskey="u" href="#TROUBLESHOOTING">TROUBLESHOOTING</a>
6348
6349 </div>
6350
6351 <h3 class="section">16.3 LOCKING UP WHEN LOADING FILES</h3>
6352
6353 <p>The most common reason loading files locks up is because the codec
6354 isn't supported.  Another reason is because Cinelerra is building
6355 picons for the Resources window.  If you load a large number of images,
6356 it needs to decompress every single image to build a picon.  Go into
6357 settings-&gt;preferences-&gt;interface and disable <b>Use thumbnails in
6358 resource window</b> to skip this process.
6359
6360 <div class="node">
6361 <a name="SYNCHRONIZATION-LOST-WHILE-RECORDING"></a>
6362 <p><hr>
6363 Next:&nbsp;<a rel="next" accesskey="n" href="#APPLYING-LINEARIZE-FOLLOWED-BY-BLUR-DOESN_0027T-WORK">APPLYING LINEARIZE FOLLOWED BY BLUR DOESN'T WORK</a>,
6364 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LOCKING-UP-WHEN-LOADING-FILES">LOCKING UP WHEN LOADING FILES</a>,
6365 Up:&nbsp;<a rel="up" accesskey="u" href="#TROUBLESHOOTING">TROUBLESHOOTING</a>
6366
6367 </div>
6368
6369 <h3 class="section">16.4 SYNCHRONIZATION LOST WHILE RECORDING</h3>
6370
6371 <p>If the framerate of the recording is much lower than the framerate of
6372 the source, the video will accumulate in the recording buffers over
6373 time while the audio and video are well out of sync.  Decrease the
6374 <b>number of frames to buffer in the device</b> in
6375 <b>preferences-&gt;recording</b> so the excess frames are dropped instead of
6376 buffered.
6377
6378 <div class="node">
6379 <a name="APPLYING-LINEARIZE-FOLLOWED-BY-BLUR-DOESN'T-WORK"></a>
6380 <a name="APPLYING-LINEARIZE-FOLLOWED-BY-BLUR-DOESN_0027T-WORK"></a>
6381 <p><hr>
6382 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SYNCHRONIZATION-LOST-WHILE-RECORDING">SYNCHRONIZATION LOST WHILE RECORDING</a>,
6383 Up:&nbsp;<a rel="up" accesskey="u" href="#TROUBLESHOOTING">TROUBLESHOOTING</a>
6384
6385 </div>
6386
6387 <h3 class="section">16.5 APPLYING LINEARIZE FOLLOWED BY BLUR DOESN'T WORK</h3>
6388
6389 <p>The linearize effect uses the pow function while the blur effect uses a
6390 number of exp functions in the math library.  For some reason, using
6391 the pow function breaks later calls to the exp functions in the math
6392 library.  You need to apply linearize after blur to get it to work.
6393
6394 <div class="node">
6395 <a name="SECRETS-OF-CINELERRA"></a>
6396 <p><hr>
6397 Next:&nbsp;<a rel="next" accesskey="n" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>,
6398 Previous:&nbsp;<a rel="previous" accesskey="p" href="#TROUBLESHOOTING">TROUBLESHOOTING</a>,
6399 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
6400
6401 </div>
6402
6403 <h2 class="chapter">17 SECRETS OF CINELERRA</h2>
6404
6405 <p>In this section, you'll find ways to apply Cinelerra to common
6406 problems.  Other sections are arranged in order of the tools and what
6407 the tools are used for.  This section is arranged in order of the
6408 problems and what tools are used to solve the problems.
6409
6410 <ul class="menu">
6411 <li><a accesskey="1" href="#DOLBY-PRO-LOGIC-ENCODING">DOLBY PRO LOGIC ENCODING</a>
6412 <li><a accesskey="2" href="#ANALOG-TV-CLEANING">ANALOG TV CLEANING</a>
6413 <li><a accesskey="3" href="#DEFEATING-INTERLACING">DEFEATING INTERLACING</a>
6414 <li><a accesskey="4" href="#MAKING-VIDEO-LOOK-LIKE-FILM">MAKING VIDEO LOOK LIKE FILM</a>
6415 <li><a accesskey="5" href="#CLEARING-OUT-HAZE">CLEARING OUT HAZE</a>
6416 <li><a accesskey="6" href="#MAKING-A-DVD">MAKING A DVD</a>
6417 <li><a accesskey="7" href="#MAKING-A-RINGTONE">MAKING A RINGTONE</a>
6418 <li><a accesskey="8" href="#TIME-STRETCHING-AUDIO">TIME STRETCHING AUDIO</a>
6419 <li><a accesskey="9" href="#PITCH-SHIFTING-AUDIO">PITCH SHIFTING AUDIO</a>
6420 <li><a href="#TEXT-TO-MOVIE">TEXT TO MOVIE</a>
6421 </ul>
6422
6423 <div class="node">
6424 <a name="DOLBY-PRO-LOGIC-ENCODING"></a>
6425 <p><hr>
6426 Next:&nbsp;<a rel="next" accesskey="n" href="#ANALOG-TV-CLEANING">ANALOG TV CLEANING</a>,
6427 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>
6428
6429 </div>
6430
6431 <h3 class="section">17.1 DOLBY PRO LOGIC ENCODING</h3>
6432
6433 <p>Dolby pro logic is an easy way to output 6 channel audio from a 2
6434 channel soundcard with degraded but useful results.  Rudimentary Dolby
6435 pro logic encoding can be achieved with clever usage of the effects.
6436
6437    <p>Create 2 audio tracks with the same audio.  Apply <b>invert audio</b> to
6438 one track.  The signal comes out of the back speakers.
6439
6440    <p>Create a single audio track with monaural audio of a different source.
6441 Center it in the <b>pan</b> control.  The signal comes out of the center
6442 speaker.
6443
6444    <p>Create other tracks with different signals and pan them left or right
6445 to put signals in the front left or right speaker.
6446
6447    <p>Finally, if a copy of the signal in the back speakers is desired in any
6448 single front speaker, the signal in the back speakers must be delayed
6449 by at least 0.05 seconds and a single new track should be created.  Pan
6450 the new track to orient the signal in the front speakers.
6451
6452    <p>If the same signal is desired in all the speakers except the center
6453 speaker, delay the back speakers by 0.5 seconds and delay either the
6454 front left or front right by 0.2 seconds.
6455
6456    <p>If you want to hear something from the subwoofer, create a new track,
6457 select a range, drop a synthesizer effect, and set the frequency below
6458 60 Hz.  The subwoofer merely plays anything below around 60Hz.
6459
6460    <p>Other tricks you can perform to separate the speakers are parametric
6461 equalization to play only selected ranges of frequencies through
6462 different speakers and lowpass filtering to play signals through the
6463 subwoofer.
6464
6465 <div class="node">
6466 <a name="ANALOG-TV-CLEANING"></a>
6467 <p><hr>
6468 Next:&nbsp;<a rel="next" accesskey="n" href="#DEFEATING-INTERLACING">DEFEATING INTERLACING</a>,
6469 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DOLBY-PRO-LOGIC-ENCODING">DOLBY PRO LOGIC ENCODING</a>,
6470 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>
6471
6472 </div>
6473
6474 <h3 class="section">17.2 ANALOG TV CLEANING</h3>
6475
6476 <p>Unless you live in a rich nation like China or are a terrorist, you
6477 probably record analog TV more than you record digital TV.  The picture
6478 quality on analog TV is horrible but you can do things in Cinelerra to
6479 make it look more like it did in the studio.
6480
6481    <p>First, when capturing the video, capture it in the highest resolution
6482 possible.  For Europeans it's 720x576 and for Americans it's 720x480.
6483 Don't bother adjusting the brightness or contrast in the recording
6484 monitor, although maxing out the color is useful.  Capture it using
6485 MJPEG or uncompressed Component Video if possible.  If those are too
6486 demanding, then capture it using JPEG.  RGB should be a last resort.
6487
6488    <p>Now on the timeline use <b>Settings-&gt;Format</b> to set a YUV colorspace.
6489 Drop a <b>Downsample</b> effect on the footage.  Set it for
6490
6491 <pre class="example">     Horizontal:        2
6492      Horizontal offset: 0
6493      Vertical:          2
6494      Vertical offset:   0
6495
6496            red
6497        x   green
6498        x   blue
6499            alpha
6500 </pre>
6501    <p>Use the camera tool to shift the picture up or down a line to remove
6502 the most color interference from the image.  This is the difference
6503 we're looking for:
6504
6505    <pre class="sp">
6506
6507 </pre>
6508
6509 <img src="cleaning1.png" alt="cleaning1.png">
6510
6511    <p>If you have vertical blanking information or crawls which constantly
6512 change in each frame, block them out with the <b>Mask</b> tool.  This
6513 improves compression ratios.
6514
6515    <p>This is about all you can do without destroying more data than you
6516 would naturally lose in compression.  The more invasive cleaning
6517 techniques involve deinterlacing.
6518
6519 <div class="node">
6520 <a name="DEFEATING-INTERLACING"></a>
6521 <p><hr>
6522 Next:&nbsp;<a rel="next" accesskey="n" href="#MAKING-VIDEO-LOOK-LIKE-FILM">MAKING VIDEO LOOK LIKE FILM</a>,
6523 Previous:&nbsp;<a rel="previous" accesskey="p" href="#ANALOG-TV-CLEANING">ANALOG TV CLEANING</a>,
6524 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>
6525
6526 </div>
6527
6528 <h3 class="section">17.3 DEFEATING INTERLACING</h3>
6529
6530 <p>Interlacing is done on most video sources because it costs too much to
6531 build progressive scanning cameras and progressive scanning CRT's.
6532 Many a consumer has been dissapointed to spend 5 paychecks on a
6533 camcorder and discover what horrible jagged images it produces on a
6534 computer monitor.
6535
6536    <p>As for progressive scanning camcorders, forget it.  Cost factors are
6537 probably going to keep progressive scanning cameras from ever equalling
6538 the spatial resolution of interlaced cameras.  Interlacing is here to
6539 stay.  That's why they made deinterlacing effects in Cinelerra.
6540
6541    <p>We don't believe there has ever been a perfect deinterlacing effect.
6542 They're either irreversible or don't work.  Cinelerra cuts down the
6543 middle by providing deinterlacing tools that are irreversible sometimes
6544 and don't work sometimes but are neither one or the other.
6545
6546    <p><b>Line Doubling</b>
6547
6548    <p>This one is done by the <b>Deinterlace</b> effect when set to <b>Odd
6549 lines</b> or <b>Even lines</b>.  When applied to a track it reduces the
6550 vertical resolution by 1/2 and gives you progressive frames with
6551 stairstepping.  This is only useful when followed by a scale effect
6552 which reduces the image to half its size.
6553
6554    <p><b>Line averaging</b>
6555
6556    <p>The <b>Deinterlace</b> effect when set to <b>Average even lines</b> or
6557 <b>Average odd lines</b> does exactly what line doubling does except
6558 instead of making straight copies of the lines it makes averages of the
6559 lines.  This is actually useful for all scaling.
6560
6561    <p>There's an option for adaptive line averaging which selects which lines
6562 to line average and which lines to leave interlaced based on the
6563 difference between the lines.  It doesn't work.
6564
6565    <p><b>Inverse Telecine</b>
6566
6567    <p>This is the most effective deinterlacing tool when the footage is an
6568 NTSC TV broadcast of a film.  See <a href="#INVERSE-TELECINE">INVERSE TELECINE</a>.
6569
6570    <p><b>Time base correction</b>
6571
6572    <p>The first three tools either destroy footage irreversibly or don't work
6573 sometimes.  <b>Time base correction</b> is last because it's the perfect
6574 deinterlacing tool.  It leaves the footage intact.  It doesn't reduce
6575 resolution, perceptually at least.  It doesn't cause jittery timing.
6576
6577    <p>The <b>Frames to Fields</b> effect converts each frame to two frames, so
6578 it must be used on a timeline whose project frame rate is twice the
6579 footage's frame rate.  In the first frame it puts a line averaged copy
6580 of the even lines.  In the second frame it puts a line averaged copy of
6581 the odd lines.  When played back at full framerates it gives the
6582 illusion of progressive video with no loss of detail.
6583
6584    <p>Best of all, this effect can be reversed with the <b>Fields to frames</b>
6585 effect.  That one combines two frames of footage back into the one
6586 original interlaced frame of half the framerate.
6587
6588    <p>Be aware that frames to fields inputs frames at half the framerate as
6589 the project.  Effects before frames to fields process at the reduced
6590 framerate.
6591
6592    <p>Unfortunately, the output of <b>Frames to Fields</b> can't be compressed
6593 as efficiently as the original because it introduces vertical twitter
6594 and a super high framerate.
6595
6596    <p>Interlaced 29.97fps footage can be made to look like film by applying
6597 <b>Frames to Fields</b> and then reducing the project frame rate of the
6598 resulting 59.94fps footage to 23.97fps.  This produces no timing jitter
6599 and the occasional odd field gives the illusion of more detail than
6600 there would be if you just line averaged the original.
6601
6602    <p><b>HDTV exceptions</b>
6603
6604    <p>1920x1080 HDTV is encoded a special way.  If it's a broadcast of
6605 original HDTV film, an inverse telecine works fine.  If it's a
6606 rebroadcast of a 720x480 source, you need to use a time base and line
6607 doubling algorithm to deinterlace it, See <a href="#g_t1080-TO-480">1080 TO 480</a>.
6608
6609 <div class="node">
6610 <a name="MAKING-VIDEO-LOOK-LIKE-FILM"></a>
6611 <p><hr>
6612 Next:&nbsp;<a rel="next" accesskey="n" href="#CLEARING-OUT-HAZE">CLEARING OUT HAZE</a>,
6613 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DEFEATING-INTERLACING">DEFEATING INTERLACING</a>,
6614 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>
6615
6616 </div>
6617
6618 <h3 class="section">17.4 MAKING VIDEO LOOK LIKE FILM</h3>
6619
6620 <p>Video sweetening is constantly getting better.  Lately the best thing
6621 you can do for dirt cheap consumer camcorder video is to turn it into
6622 progressive 24fps output.  While you can't really do that, you can get
6623 pretty close for the money.  Mind you, this procedure can degrade high
6624 quality video just as easily as it improves low quality video.  It
6625 should only be used for low quality video.
6626
6627      <ul>
6628 <li>
6629 Step 1 - Set project framerate to twice the video framerate.
6630
6631      <li>
6632 Step 2 - Apply a <b>Sharpen</b> effect.  Set it to sharpness: 25, no
6633 interlacing, and horizontal only.
6634
6635      <li>
6636 Step 3 - Drop a <b>Frame to Fields</b> effect on the same track.  Set
6637 Average Empty Rows on and play through the video a few times to figure
6638 out which field is first.  If the wrong field is first, the motion is
6639 shaky.  Secondly, any editing in the doubled frame rate may now screw
6640 up the field order.  We're still figuring out the easiest way to
6641 support warnings for field glitches but for now you need to go back to
6642 the normal framerate to do editing or play test to make sure the fields
6643 are right.
6644
6645      <li>
6646 Step 4 - Render just the video to the highest quality file possible.
6647
6648      <li>
6649 Step 5 - Import the video back to a new track.  Set the project
6650 framerate to 24.  The new track should now display more filmish and
6651 sharper images than the original footage.
6652
6653    </ul>
6654
6655    <p>This entire procedure could be implemented in one nonrealtime effect,
6656 but the biggest problem with that is you'll most often want to keep the
6657 field based output and the 24fps output for posterity.  A nonrealtime
6658 effect would require all that processing just for the 24fps copy.
6659 Still debating that one.
6660
6661 <div class="node">
6662 <a name="CLEARING-OUT-HAZE"></a>
6663 <p><hr>
6664 Next:&nbsp;<a rel="next" accesskey="n" href="#MAKING-A-DVD">MAKING A DVD</a>,
6665 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MAKING-VIDEO-LOOK-LIKE-FILM">MAKING VIDEO LOOK LIKE FILM</a>,
6666 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>
6667
6668 </div>
6669
6670 <h3 class="section">17.5 CLEARING OUT HAZE</h3>
6671
6672 <p>Let's face it, if you're employed you live in Silicon Valley.  As such
6673 you probably photograph a lot of haze and never see blue sky ever.
6674 Even if you can afford to briefly go somewhere where there is blue sky,
6675 horizon shots usually can stand for more depth.  This is what the
6676 <b>gradient effect</b> is for.
6677
6678    <p>Drop the gradient effect on hazy tracks.  Set the following parameters:
6679
6680 <pre class="example">     Angle: 0
6681      Inner radius: 0
6682      Outer radius: 40
6683      Inner color: blue 100% alpha
6684      Outer color: blue 0% alpha
6685 </pre>
6686    <p>It's important to set the 0% alpha color to blue even though it's 0%
6687 alpha.  The color of the outer alpha is still interpolated with the
6688 inner color.  This is a generally applicable setting for the gradient.
6689 Some scenes may work better with orange or brown for an evening feel.
6690
6691 <div class="node">
6692 <a name="MAKING-A-DVD"></a>
6693 <p><hr>
6694 Next:&nbsp;<a rel="next" accesskey="n" href="#MAKING-A-RINGTONE">MAKING A RINGTONE</a>,
6695 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CLEARING-OUT-HAZE">CLEARING OUT HAZE</a>,
6696 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>
6697
6698 </div>
6699
6700 <h3 class="section">17.6 MAKING A DVD</h3>
6701
6702 <p><b>A single chapter DVD</b>
6703
6704    <p>Make a single chapter DVD by rendering video to an MPEG video file.
6705 The video should be 720x480, 29.97fps.  The aspect ratio should be 16x9
6706 or 4x3.
6707
6708    <p>Use the YUV 4:2:0 color model and DVD preset.  Set the bitrate to the
6709 desired bitrate.  It's not clear exactly what other parameters the MPEG
6710 encoder uses in the DVD preset but we've enabled the following:
6711
6712 <pre class="example">     Derivative: MPEG-2
6713      Fixed bitrate
6714      I frame distance: 15
6715      P frame distance: 0
6716      Sequence start codes in every GOP
6717 </pre>
6718    <p>Render the audio to an AC3 audio file.  Any bitrate can be used.
6719
6720    <p><b>Dvdrtools</b> must be downloaded to generate the actual DVD
6721 filesystem.  The actual usage of dvdrtools changes frequently but
6722 currently it involves the mkisofs and ifogen programs.  Mkisofs is
6723 built automatically in dvdrtools but ifogen may have to be built
6724 manually by entering the <b>video</b> directory and running <b>make
6725 ifogen</b>.  Mkisofs and ifogen must be put into /usr/bin manually.
6726
6727    <p>Also, the <b>mplex</b> program from <b>mjpegtools</b> must be installed.  The
6728 mjpegtools package is built in the hvirtual distribution and the mplex
6729 utility may be extracted from there.
6730
6731    <p>Given the files audio.ac3 and video.m2v, rendered by Cinelerra, the
6732 following commands pack them into a dvd readable by commercial
6733 appliances.
6734
6735 <pre class="example">     mplex -M -f 8 -o final.mpg audio.ac3 video.m2v
6736      mkdir -p dvd/VIDEO_TS
6737      ifogen final.mpg -o dvd
6738      ifogen -T -o dvd
6739      mkisofs -dvd-video -udf -o dvd.iso dvd/
6740 </pre>
6741    <p>Chapters may be set with the following.  The units are seconds.  Version
6742 0.3.1 ignores the 1st chapter, so it has to be specified as 0.
6743
6744 <pre class="example">     ifogen -o dvd --chapters=0,0021.788,0047.447,0077.043 final.mpg
6745 </pre>
6746    <p>Replace the chapter times.
6747
6748    <p>dvd.iso can be burned directly to a DVD with the following:
6749
6750 <pre class="example">     dvdrecord -ignsize -dao -v dev=/dev/hdc fs=67108864 dvd.iso
6751 </pre>
6752    <p>The argument to dev= is the IDE device of the DVD drive.  Burning DVD's
6753 through SCSI is currently not supported.
6754
6755 <div class="node">
6756 <a name="MAKING-A-RINGTONE"></a>
6757 <p><hr>
6758 Next:&nbsp;<a rel="next" accesskey="n" href="#TIME-STRETCHING-AUDIO">TIME STRETCHING AUDIO</a>,
6759 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MAKING-A-DVD">MAKING A DVD</a>,
6760 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>
6761
6762 </div>
6763
6764 <h3 class="section">17.7 MAKING A RINGTONE</h3>
6765
6766 <p>This is how we made ringtones for the low end Motorola V180's and it'll
6767 probably work with any new phone.  Go to <b>File-&gt;Load files...</b> and
6768 load a sound file with Insertion strategy: <b>Replace current
6769 project</b>.  Go to <b>Settings-&gt;Format</b> change <b>Channels</b> to 1 and
6770 <b>Samplerate</b> to 16000 or 22050.
6771
6772    <p>Either highlight a region of the timeline or set in/out points to use
6773 for the ringtone.  To improve sound quality on the cell phone, you need
6774 the maximum amplitude in as many parts of the sound as possible.  Right
6775 click on track Audio 1 and select <b>Attach effect..</b>.  Highlight the
6776 <b>Compressor</b> effect and hit <b>Attach</b> in the attachment popup.
6777
6778    <p>Make sure the insertion point or highlighted area is in the region with
6779 the Compressor effect. Right click on track Audio 2 and select
6780 <b>Attach effect..</b>.  Highlight <b>Audio 1: Compressor</b> and hit
6781 <b>Attach</b>.  Click the Audio1 Compressor's magnifying glass
6782 <img src="magnify.png" alt="magnify.png"> to bring up the compressor GUI.
6783
6784    <p>Set the following parameters:
6785
6786 <pre class="example">     Reaction secs: <b>-0.1</b>
6787      Decay secs: <b>0.1</b>
6788      Trigger Type: <b>Total</b>
6789      Trigger: <b>0</b>
6790      Smooth only: <b>No</b>
6791 </pre>
6792    <p>Click <b>Clear</b> to clear the graph.  Click anywhere in the
6793 grid area and drag a new point to 0 Output and -50 Input.  The graph
6794 should look like this.
6795
6796    <pre class="sp">
6797
6798 </pre>
6799 <img src="compress.png" alt="compress.png">
6800
6801    <p>Go to <b>File-&gt;Render</b>.  Specify the name of an mp3 file to output to.
6802 Set the file format to <b>MPEG Audio</b>.  Click the wrench <img src="wrench.png" alt="wrench.png">
6803 for Audio and set <b>Layer</b> to <b>III</b> and <b>Kbits per second</b> to
6804 <b>24</b> or <b>32</b>.  Check <b>Render audio tracks</b> and uncheck <b>Render
6805 video tracks</b>.  Hit OK to render the file.
6806
6807    <p>The resulting .mp3 file must be uploaded to a web server.  Then, the
6808 phone's web browser must download the .mp3 file directly from the URL.
6809 There also may be a size limit on the file.
6810
6811 <div class="node">
6812 <a name="TIME-STRETCHING-AUDIO"></a>
6813 <p><hr>
6814 Next:&nbsp;<a rel="next" accesskey="n" href="#PITCH-SHIFTING-AUDIO">PITCH SHIFTING AUDIO</a>,
6815 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MAKING-A-RINGTONE">MAKING A RINGTONE</a>,
6816 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>
6817
6818 </div>
6819
6820 <h3 class="section">17.8 TIME STRETCHING AUDIO</h3>
6821
6822 <p>It may appear that time stretching audio is a matter of selecting a
6823 region of the audio tracks, enabling recording for the desired tracks,
6824 going to <b>Audio-&gt;Render Effect</b>, and applying <b>Time Stretch</b>.  In
6825 actuality there are 3 audio effects for time stretching: <b>Time
6826 Stretch</b>, <b>Resample</b>, and <b>Asset info dialog</b>.
6827
6828    <p>Time Stretch applies a fast fourier transform to try to change the
6829 duration without changing the pitch, but this introduces windowing
6830 artifacts to the audio.  It's only useful for large changes in time
6831 because obvious changes in duration make windowing artifacts less
6832 obtrusive.
6833
6834    <p>For smaller changes in duration, in the range of 5%, <b>Resample</b>
6835 should be used.  This changes the pitch of the audio but small enough
6836 changes aren't noticable.  Resample doesn't introduce any windowing
6837 artifacts, so this is most useful for slight duration changes where the
6838 listener isn't supposed to know what's going on.
6839
6840    <p>Another way to change duration slightly is to go to the <b>Resources</b>
6841 window, highlight the <b>media</b> folder, right click on an audio file,
6842 click on <b>Info</b>.  Adjust the sample rate in the <b>Info</b> dialog to
6843 adjust the duration.  This method also requires left clicking on the
6844 right boundary of the audio tracks and dragging left or right to
6845 correspond to the length changes.
6846
6847 <div class="node">
6848 <a name="PITCH-SHIFTING-AUDIO"></a>
6849 <p><hr>
6850 Next:&nbsp;<a rel="next" accesskey="n" href="#TEXT-TO-MOVIE">TEXT TO MOVIE</a>,
6851 Previous:&nbsp;<a rel="previous" accesskey="p" href="#TIME-STRETCHING-AUDIO">TIME STRETCHING AUDIO</a>,
6852 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>
6853
6854 </div>
6855
6856 <h3 class="section">17.9 PITCH SHIFTING AUDIO</h3>
6857
6858 <p>Like the time stretching methods, there are three pitch shifting
6859 methods: <b>Pitch shift</b>, <b>Resample</b>, and <b>Asset info dialog</b>.
6860 Pitch shift is a realtime effect which can be dragged and dropped onto
6861 recordable audio tracks.  Pitch shift uses a fast fourier transform to
6862 try to change the pitch without changing the duration, but this
6863 introduces windowing artifacts.
6864
6865    <p>Because the windowing artifacts are less obtrusive in audio which is
6866 obvously pitch shifted, Pitch shift is mainly useful for extreme pitch
6867 changes.  For mild pitch changes, use <b>Resample</b> from the
6868 <b>Audio-&gt;Render Effect</b> interface.  Resample can change the pitch
6869 within 5% without a noticable change in duration.
6870
6871    <p>Another way to change pitch slightly is to go to the <b>Resources</b>
6872 window, highlight the <b>media</b> folder, right click on an audio file,
6873 click on <b>Info</b>.  Adjust the sample rate in the <b>Info</b> dialog to
6874 adjust the pitch.  This method also requires left clicking on the right
6875 boundary of the audio tracks and dragging left or right to correspond
6876 to the length changes.
6877
6878 <div class="node">
6879 <a name="TEXT-TO-MOVIE"></a>
6880 <p><hr>
6881 Previous:&nbsp;<a rel="previous" accesskey="p" href="#PITCH-SHIFTING-AUDIO">PITCH SHIFTING AUDIO</a>,
6882 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>
6883
6884 </div>
6885
6886 <h3 class="section">17.10 TEXT TO MOVIE</h3>
6887
6888 <p>Text to movie was added when another one of those startups whose name
6889 was an unmemorable combination of farting noises that the venture
6890 capitalist heard, started charging money for a ridulously simple program
6891 that converted scripts directly to movies.  It was such a simple
6892 program, we decided to add most of the functionality to Cinelerra.
6893
6894    <p>The easiest way to make a movie is to copy <b>tests/text2movie</b> and
6895 <b>tests/text2movie.xml</b> as a starting point.  Load the
6896 <b>text2movie.xml</b> file to see the movie.
6897
6898    <p>The <b>text2movie</b> file acts like a normal asset, except changes to it
6899 are immediately reflected on the timeline, without reloading.  Also, the
6900 length is infiinite.  Edit the <b>text2movie</b> file to change the
6901 script.  If the length of the movie increases, drag the right edit
6902 handle to extend the edit or use <b>edit-&gt;edit length</b>.
6903
6904    <p>1 audio channel is created for every character.  The frame rate, sample
6905 rate, and frame size are fixed.  Get it from the <b>asset window</b>.
6906 Right click on the asset and go to <b>Asset info...</b>  Camera angles are
6907 fixed.
6908
6909    <p>Since its only use was to show dialog between 2 people, that's the
6910 functionality we focused on.  The character model and voice is selected
6911 separately in the script, because that was how it was done with the fee
6912 service.  The models are defined in model files, in the Cinelerra
6913 executable directory.  Usually <b>/opt/cinelerra/models</b>.
6914
6915    <p>There is a search path for models, starting with the directory the
6916 script is in.  You can define new models for the script, without
6917 affecting the entire system.  The model files are the exact name that
6918 appears in the script.  They define the total size of the model and the
6919 images used in the model.
6920
6921    <p>The models are 2D png images, because all the animations are baked.  No
6922 custom movement is currently supported, that would require a 3D
6923 renderer.
6924
6925    <p>Some actions are implemented.  Character2 can cut off character1 if
6926 character1's dialog ends in <b>...</b>
6927
6928    <p>Inserting <b>[pause]</b> anywhere causes the character to pause.  Useful
6929 for adjusting the timing of dialog.
6930
6931    <p>Speech synthesis is pretty lousy.  Punctuation and spelling needs to be
6932 adjusted based on the sound.  The dialog is rendered on-demand, so there
6933 is a delay when each character starts to speak.  Split dialog into
6934 shorter blocks to reduce the delay.
6935
6936 <div class="node">
6937 <a name="SECRETS-OF-CINELERRA-EFFECTS"></a>
6938 <p><hr>
6939 Next:&nbsp;<a rel="next" accesskey="n" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>,
6940 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SECRETS-OF-CINELERRA">SECRETS OF CINELERRA</a>,
6941 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
6942
6943 </div>
6944
6945 <h2 class="chapter">18 SECRETS OF CINELERRA EFFECTS</h2>
6946
6947 <p>Most effects in Cinelerra can be figured out just by using them and
6948 tweeking.  Here are brief descriptions of effects which you might not
6949 utilize fully by mere experimentation.
6950
6951 <ul class="menu">
6952 <li><a accesskey="1" href="#g_t1080-TO-480">1080 TO 480</a>:        How to convert HDTV into SD
6953 <li><a accesskey="2" href="#CHROMA-KEY">CHROMA KEY</a>:         Create transparency based on color similarities.
6954 <li><a accesskey="3" href="#COMPRESSOR">COMPRESSOR</a>:         How to reduce the dynamic range of audio.
6955 <li><a accesskey="4" href="#DECIMATE">DECIMATE</a>:           How to reduce frame rates by eliminating similar frames.
6956 <li><a accesskey="5" href="#DEINTERLACE">DEINTERLACE</a>:        How to convert interlaced video to progressive video.
6957 <li><a accesskey="6" href="#DIFFERENCE-KEY">DIFFERENCE KEY</a>:     Create transparency based on color differences.
6958 <li><a accesskey="7" href="#FIELDS-TO-FRAMES">FIELDS TO FRAMES</a>:   How to recover interlaced video from bobbed video
6959 <li><a accesskey="8" href="#FREEZE-FRAME">FREEZE FRAME</a>:       How to stop action in the timeline.
6960 <li><a accesskey="9" href="#HISTOGRAM">HISTOGRAM</a>:          How to change the mapping of different brightness values.
6961 <li><a href="#INVERSE-TELECINE">INVERSE TELECINE</a>:   How to convert pulled down frames to progressive frames.
6962 <li><a href="#INTERPOLATE-VIDEO">INTERPOLATE VIDEO</a>:  How to create the illusion of higher framerates.
6963 <li><a href="#LENS">LENS</a>:               Correcting spherical aberration
6964 <li><a href="#LINEARIZE">LINEARIZE</a>:          Fix gamma in raw camera images
6965 <li><a href="#LIVE-AUDIO">LIVE AUDIO</a>:         Pass audio from the soundcard directly to the timeline.
6966 <li><a href="#LIVE-VIDEO">LIVE VIDEO</a>:         Pass video from the capture card directly to the timeline.
6967 <li><a href="#LOOP">LOOP</a>:               How to loop regions of the timeline.
6968 <li><a href="#MOTION">MOTION</a>:             Motion tracking with rotation.
6969 <li><a href="#MOTION-2-POINT">MOTION 2 POINT</a>:     Motion and rotation tracking from translation only.
6970 <li><a href="#REFRAMERT">REFRAMERT</a>:          Changing the number of frames in a sequence.
6971 <li><a href="#REFRAME">REFRAME</a>:            Changing the number of frames in a sequence with rendering.
6972 <li><a href="#RESAMPLE">RESAMPLE</a>:           Change the number of samples in a sequence with rendering.
6973 <li><a href="#REVERSE-VIDEO_002fAUDIO">REVERSE VIDEO/AUDIO</a>:  How to play regions in reverse.
6974 <li><a href="#SWAP-FRAMES">SWAP FRAMES</a>:        Fixing temporal field order
6975 <li><a href="#THRESHOLD">THRESHOLD</a>:          How to get monochrome out of a region of the image.
6976 <li><a href="#TIME-AVERAGE">TIME AVERAGE</a>:       How to stack images.
6977 <li><a href="#TITLER">TITLER</a>:             How to add text to a track from inside Cinelerra.
6978 <li><a href="#VIDEO-SCOPE">VIDEO SCOPE</a>:        How to view the dynamic range of intensity and hue.
6979 </ul>
6980
6981 <div class="node">
6982 <a name="g_t1080-TO-480"></a>
6983 <p><hr>
6984 Next:&nbsp;<a rel="next" accesskey="n" href="#CHROMA-KEY">CHROMA KEY</a>,
6985 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
6986
6987 </div>
6988
6989 <h3 class="section">18.1 1080 TO 480</h3>
6990
6991 <p>Most TV broadcasts are recieved with a 1920x1080 resolution but
6992 originate from a 720x480 source at the studio.  It's a waste of space
6993 to compress the entire 1920x1080 if the only resolvable details are
6994 720x480.  Unfortunately resizing 1920x1080 video to 720x480 isn't as
6995 simple as shrinking it.
6996
6997    <p>At the TV station the original 720x480 footage was first converted to
6998 fields of 720x240.  Each field was then scaled up to 1920x540.  The two
6999 1920x540 fields were finally combined with interlacing to form the
7000 1920x1080 image.  This technique allows a consumer TV to display the
7001 resampled image without extra circuitry to handle 720x480 interlacing
7002 in a 1920x1080 image.
7003
7004    <p>If you merely deinterlaced the 1920x1080 images, you would end up with
7005 resolution of 720x240.  The <b>1080 to 480</b> effect properly extracts
7006 two 1920x540 size fields from the image, resizes them separately, and
7007 combines them again to restore a 1920x480 interlaced image.  The
7008 <b>scale</b> effect must then be applied to reduce the horizontal size to
7009 960 or 720 depending on the original aspect ratio.
7010
7011    <p>The tracks to which <b>1080 to 480</b> is applied need to be at 1920x1080
7012 resolution.  The project settings in <b>settings-&gt;format</b> should be at
7013 least 720x480 resolution.
7014
7015    <p>The effect doesn't know if the first row in the 1920x1080 image belongs
7016 to the first row of the 720x480 original.  You have to specify what the
7017 first row is in the effect configuration.
7018
7019    <p>The output of this effect is a small image in the middle of the
7020 original 1920x1080 frame.  Use the projector to center the output image
7021 in the playback.
7022
7023    <p>Finally, once you have 720x480 interlaced video you can either apply
7024 <b>frames to fields</b> of <b>inverse telecine</b> to further recover original
7025 progressive frames.
7026
7027 <div class="node">
7028 <a name="CHROMA-KEY"></a>
7029 <p><hr>
7030 Next:&nbsp;<a rel="next" accesskey="n" href="#COMPRESSOR">COMPRESSOR</a>,
7031 Previous:&nbsp;<a rel="previous" accesskey="p" href="#g_t1080-TO-480">1080 TO 480</a>,
7032 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7033
7034 </div>
7035
7036 <h3 class="section">18.2 CHROMA KEY</h3>
7037
7038 <p>This effect erases pixels which match the selected color.  They are
7039 replaced with black if there is no alpha channel and transparency if
7040 there is an alpha channel.  The selection of color model is important
7041 to determine the behavior.
7042
7043    <p>Chroma key uses either the lightness or the hue to determine what is
7044 erased.  <b>Use value</b> singles out only the lightness to determine
7045 transparency.  Select a center color to erase using the <b>Color</b>
7046 button.  Alternatively a color can be picked directly from the output
7047 frame by first using the <b>color picker</b> in the compositor window and
7048 then selecting the <b>Use color picker</b> button.  This sets the chroma
7049 key color to the current color picker color.
7050
7051    <p>Be aware that the output of the chroma key is fed back to the
7052 compositor, so selecting a color again from the compositor will use the
7053 output of the chroma key effect.  The chroma key should be disabled
7054 when selecting colors with the color picker.
7055
7056    <p>If the lightness or hue is within a certain threshold it's erased.
7057 Increasing the threshold determines the range of colors to be erased.
7058 It's not a simple on/off switch, however.  As the color approaches the
7059 edge of the threshold, it gradually gets erased if the slope is high or
7060 is rapidly erased if the slope is low.  The slope as defined here is
7061 the number of extra values flanking the threshold required to go from
7062 opaque to transparent.
7063
7064    <p>Normally threshold is very low when using a high slope.  The two
7065 parameters tend to be exclusive because slope fills in extra threshold.
7066
7067    <p>The slope tries to soften the edges of the chroma key but it doesn't
7068 work well for compressed sources.  A popular softening technique is to
7069 use a maximum slope and chain a blur effect below the chroma key effect
7070 to blur just the alpha.
7071
7072 <div class="node">
7073 <a name="COMPRESSOR"></a>
7074 <p><hr>
7075 Next:&nbsp;<a rel="next" accesskey="n" href="#DECIMATE">DECIMATE</a>,
7076 Previous:&nbsp;<a rel="previous" accesskey="p" href="#CHROMA-KEY">CHROMA KEY</a>,
7077 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7078
7079 </div>
7080
7081 <h3 class="section">18.3 COMPRESSOR</h3>
7082
7083 <p>Contrary to computer science experience, the audio compressor does not
7084 reduce the amount of data required to store the audio.  The audio
7085 compressor reduces the dynamic range of the audio.  In Cinelerra the
7086 compressor actually performs the function of an expander and
7087 compressor.
7088
7089    <p>The compressor works by calculating the maximum sound level within a
7090 certain time period of the current position.  The maximum sound level
7091 is taken as the input sound level.  For every input sound level there
7092 is an output sound level specified by the user.  The gain at the
7093 current position is adjusted so the maximum sound level in the time
7094 range is the user specified value.
7095
7096    <p>The compressor has a graph which correlates every input sound level to
7097 an output level.  The horizontal direction is the input sound level in
7098 dB.  The vertical direction is the ouptut sound level in dB.  The user
7099 specifies output sound levels by creating points on the graph.  Click
7100 in the graph to create a point.  If 2 points exist, drag one point
7101 across another point to delete it.  The most recent point selected has
7102 its vales displayed in textboxes for more precise adjustment.
7103
7104    <p>To make the compressor reduce the dynamic range of the audio, make all
7105 the output values greater than the input values except 0 db.  To make
7106 the compressor expand the dynamic range of the audio, make all the
7107 output values except 0 db less than the input values.  The algorithm
7108 currently limits all sound levels above 0 db to 0 db so to get an
7109 overloaded effect put a gain effect before the compressor to reduce all
7110 the levels and follow it with another gain effect to amplify all the
7111 levels back over 0 db.
7112
7113    <p><b>Reaction secs:</b> This determines where in relation to the current
7114 position the maximum sound level is taken and how fast the gain is
7115 adjusted to reach that peak.  It's notated in seconds.  If it's
7116 negative the compressor reads ahead of the current position to get the
7117 future peak.  The gain is ramped to that peak over one reaction time.
7118 This allows it to hit the desired output level exactly when the input
7119 peak occurs at the current position.
7120
7121    <p>If the reaction time is positive the compressor scans only the current
7122 position for the gain and ramps gain over one reaction time to hit the
7123 desired output level.  It hits the output level exactly one reaction
7124 time after detecting the input peak.
7125
7126    <p><b>Decay secs:</b> If the peak is higher than the current level, the
7127 compressor ramps the gain up to the peak value.  Then if a future peak
7128 is less than the current peak it ramps the gain down.  The time taken
7129 to ramp the gain down can be greater than the time taken to ramp the
7130 gain up.  This ramping down time is the decay seconds.
7131
7132    <p><b>Trigger type:</b>  The compressor is a multichannel effect.  Several
7133 tracks can share one compressor.  How the signal from many tracks is
7134 interpreted is determined by the trigger type.
7135
7136    <p>The <b>Trigger</b> trigger type uses the value supplied in the <b>Trigger</b>
7137 textbox as the number of the track to use as input for the compressor.
7138 This allows a track which isn't even heard to determine the loudness of
7139 the other tracks.
7140
7141    <p>The <b>Maximum</b> trigger takes the loudest track and uses it as the
7142 input for the compressor.
7143
7144    <p>The <b>Total</b> trigger type adds the signals from all the tracks and
7145 uses the total as the input for the compressor.  This is the most
7146 natural sounding compression and is ideal when multiple tracks are
7147 averaged into single speakers.
7148
7149    <p><b>Trigger:</b> The compressor is a multichannel effect.  Several tracks
7150 can share one compressor.  Normally only one track is scanned for the
7151 input peak.  This track is specified by the <b>Trigger</b>.  By sharing
7152 several tracks and playing with the trigger value, you can make a sine
7153 wave on one track follow the amplitude of a drum on another track for
7154 example.
7155
7156    <p><b>Smooth only:</b> For visualizing what the compressor is doing to the
7157 soundlevel, this option causes it to replace the soundwave with just
7158 the current peak value.  It makes it very easy to see how <b>reaction
7159 secs</b> affects the detected peak values.
7160
7161 <div class="node">
7162 <a name="DECIMATE"></a>
7163 <p><hr>
7164 Next:&nbsp;<a rel="next" accesskey="n" href="#DEINTERLACE">DEINTERLACE</a>,
7165 Previous:&nbsp;<a rel="previous" accesskey="p" href="#COMPRESSOR">COMPRESSOR</a>,
7166 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7167
7168 </div>
7169
7170 <h3 class="section">18.4 DECIMATE</h3>
7171
7172 <p>This effect drops frames from a track which are most similar in order
7173 to reduce the frame rate.  This is usually applied to a DVD to convert
7174 the 29.97 fps video to the 23.97 fps film rate but this decimate effect
7175 can take any input rate and convert it to any lower output rate.
7176
7177    <p>The output rate of <b>decimate</b> is the project frame rate.  The input
7178 rate is set in the <b>decimate</b> user interface.  To convert 29.97fps
7179 progressive video to 23.97fps film, apply a decimate effect to the
7180 track.  Set the decimate input rate to 29.97 and the project rate to
7181 23.97.
7182
7183    <p>Be aware every effect layered before decimate processes video at the
7184 decimate input rate and every effect layered after decimate processes
7185 video at the project frame rate.  Computationally intensive effects
7186 should come below decimate.
7187
7188 <div class="node">
7189 <a name="DEINTERLACE"></a>
7190 <p><hr>
7191 Next:&nbsp;<a rel="next" accesskey="n" href="#DIFFERENCE-KEY">DIFFERENCE KEY</a>,
7192 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DECIMATE">DECIMATE</a>,
7193 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7194
7195 </div>
7196
7197 <h3 class="section">18.5 DEINTERLACE</h3>
7198
7199 <p>The deinterlace effect has evolved over the years to deinterlacing and
7200 a whole lot more.  In fact two of the deinterlacing methods, <b>Inverse
7201 Telecine</b> and <b>Frames to Fields</b>, are separate effects.  The
7202 deinterlace effect offers several variations of line replication to
7203 eliminate comb artifacts in interlaced video.  It also has some line
7204 swapping tools to fix improperly captured video or make the result of a
7205 reverse effect display fields in the right order.
7206
7207 <div class="node">
7208 <a name="DIFFERENCE-KEY"></a>
7209 <p><hr>
7210 Next:&nbsp;<a rel="next" accesskey="n" href="#FIELDS-TO-FRAMES">FIELDS TO FRAMES</a>,
7211 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DEINTERLACE">DEINTERLACE</a>,
7212 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7213
7214 </div>
7215
7216 <h3 class="section">18.6 DIFFERENCE KEY</h3>
7217
7218 <p>The differency key creates transparency in areas which are similar
7219 between 2 frames.  The Difference key effect must be applied to 2
7220 tracks.  One track contains the action in front of a constant
7221 background and another track contains the background with nothing in
7222 front of it.  Apply the difference key to the track with the action and
7223 apply a shared copy of it to the track with the background.  The track
7224 with the background should be muted and underneath the track with the
7225 action and the colormodel should have an alpha channel.
7226
7227    <p>Pixels which are different between the background and action track are
7228 treated as opaque.  Pixels which are similar are treated as
7229 transparent.  Change <b>threshold</b> in the differency key window to make
7230 more pixels which aren't the same color transparent. Change <b>slope</b>
7231 to change the rate at which the transparency tapers off as pixels get
7232 more different.
7233
7234    <p>The slope as defined here is the number of extra values flanking the
7235 threshold required to go from opaque to transparent.  A high slope is
7236 more useful with a low threshold because slope fills in extra
7237 threshold.
7238
7239    <p><b>Use value</b> causes the intensity of pixels to be compared instead of
7240 the color.
7241
7242    <p>Applying a blur to the top track with just the alpha channel blurred
7243 can soften the transparency border.
7244
7245 <div class="node">
7246 <a name="FIELDS-TO-FRAMES"></a>
7247 <p><hr>
7248 Next:&nbsp;<a rel="next" accesskey="n" href="#FREEZE-FRAME">FREEZE FRAME</a>,
7249 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DIFFERENCE-KEY">DIFFERENCE KEY</a>,
7250 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7251
7252 </div>
7253
7254 <h3 class="section">18.7 FIELDS TO FRAMES</h3>
7255
7256 <p>This effects reads frames at twice the project framerate, combining 2
7257 input frames into a single interlaced output frame.  Effects preceeding
7258 <b>fields to frames</b> process frames at twice the project frame rate.
7259 Each input frame is called a field.
7260
7261    <p><b>Fields to frames</b> needs to know what field corresponds to what lines
7262 in the output frame.  The easiest way to figure it out is to try both
7263 options in the window.  If the input fields are the result of a line
7264 doubling process like <b>frames to fields</b>, the wrong setting results
7265 in blurrier output.  If the input fields are the result of a standards
7266 conversion process like <b>1080 to 480</b>, the wrong setting won't make
7267 any difference.
7268
7269    <p>The debobber which converts 720x480 interlaced into 1920x1080
7270 interlaced or 1280x720 progressive seems to degrade the vertical
7271 resolution to the point that it can't be recovered.
7272
7273 <div class="node">
7274 <a name="FREEZE-FRAME"></a>
7275 <p><hr>
7276 Next:&nbsp;<a rel="next" accesskey="n" href="#HISTOGRAM">HISTOGRAM</a>,
7277 Previous:&nbsp;<a rel="previous" accesskey="p" href="#FIELDS-TO-FRAMES">FIELDS TO FRAMES</a>,
7278 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7279
7280 </div>
7281
7282 <h3 class="section">18.8 FREEZE FRAME</h3>
7283
7284 <p>In its simplest form, highlight a region of the track to freeze, drop
7285 the freeze frame effect on the highlighted region, and the lowest
7286 numbered frame in the affected area will play throughout the entire
7287 region.
7288
7289    <p>Freezeframe has an <b>enabled</b> option which can be keyframed.  Regions
7290 of a freeze frame effect which are enabled repeat the lowest numbered
7291 frame since the last keyframe.  This has unique possibilities.
7292
7293    <p>If a freeze frame effect has a keyframe in the middle of it set to
7294 <b>enabled</b>, the frame in the middle is repeated in the entire effect.
7295
7296    <p>If a freeze frame effect has several keyframes, each set to
7297 <b>enabled</b>, every time a keyframe is encountered the frame under it
7298 becomes the frozen one.
7299
7300    <p>If a freeze frame effect alternates between <b>enabled</b> and
7301 <b>disabled</b>, each time an <b>enabled</b> keyframe is encountered the
7302 frame under it is replicated until the next <b>disabled</b> keyframe.  The
7303 disabled regions play through.
7304
7305 <div class="node">
7306 <a name="HISTOGRAM"></a>
7307 <p><hr>
7308 Next:&nbsp;<a rel="next" accesskey="n" href="#INVERSE-TELECINE">INVERSE TELECINE</a>,
7309 Previous:&nbsp;<a rel="previous" accesskey="p" href="#FREEZE-FRAME">FREEZE FRAME</a>,
7310 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7311
7312 </div>
7313
7314 <h3 class="section">18.9 HISTOGRAM</h3>
7315
7316 <p>This shows the number of occurances of each color on a histogram plot.
7317
7318    <p>It is always performed in floating point RGB regardless of
7319 the project colorspace.  The histogram has two sets of transfer
7320 parameters: the input transfer and the output transfer.
7321
7322    <p>4 histograms are possible in the histogram viewer.  The red, green,
7323 blue histograms show the input histograms for red, green, blue and
7324 multiply them by an input transfer to get the output red, green, blue.
7325 Then the output red, green, blue is scaled by an output transfer.  The
7326 scaled red, green, blue is converted into a value and plotted on the
7327 value histogram.  The value histogram thus changes depending on the
7328 settings for red, green, blue.  The value transfers are applied
7329 uniformly to R, G, B after their color transfers are applied.
7330
7331    <p>Select which transfer to view by selecting one of the channels on the
7332 top of the histogram.
7333
7334    <p>The input transfer is defined by a graph overlaid on the histogram.
7335 The horizontal direction corresponds to every possible input color.
7336 The vertical direction corresponds to the output color for every input
7337 color.  Video entering the histogram is first plotted on the histogram
7338 plot, then it is translated so output values now equal the output
7339 values for each input value on the input graph.
7340
7341    <p>The input graph is edited by adding and removing any number of points.
7342 Click and drag anywhere in the input graph to create a point and move
7343 it.  Click on an existing point to make it active and move it.  The
7344 active point is always indicated by being filled in.  The active
7345 point's input and output color are given in text boxes on top of the
7346 window.  The input and output color of the point can be changed through
7347 these text boxes.
7348
7349    <p>Points can be deleted by first selecting a point and then dragging it
7350 to the other side of an adjacent point.  They can also be deleted by
7351 selecting them and hitting <b>delete</b>.
7352
7353    <p>After the input transfer, the image is processed by the output
7354 transfer.  The output transfer is simply a minimum and maximum to scale
7355 the input colors to.  Input values of 100% are scaled down to the
7356 output's maximum.  Input values of 0% are scaled up to the output
7357 minimum.
7358
7359    <p>Input values below 0 are always clamped to 0 and input values above
7360 100% are always clamped to 100%.  Click and drag on the output
7361 gradient's triangles to change it.  It also has textboxes to enter
7362 values into.
7363
7364    <p>Enable the <b>automatic</b> toggle to have the histogram calculate an
7365 automatic input transfer for the red, green, blue but not the value.
7366 It does this by scaling the middle 99% of the pixels to take 100% of
7367 the histogram width.  The number of pixels permitted to pass through is
7368 set by the <b>Threshold</b> textbox.  A threshold of 0.99 scales the input
7369 so 99% of the pixels pass through.  Smaller thresholds permit fewer
7370 pixels to pass through and make the output look more contrasty.
7371
7372    <p>Automatic input transfer is calculated for the R, G, and B channels but
7373 not the value.
7374
7375    <p><b>PLOT HISTOGRAM</b>
7376
7377    <p><b>SPLIT OUTPUT</b>
7378
7379 <div class="node">
7380 <a name="INVERSE-TELECINE"></a>
7381 <p><hr>
7382 Next:&nbsp;<a rel="next" accesskey="n" href="#INTERPOLATE-VIDEO">INTERPOLATE VIDEO</a>,
7383 Previous:&nbsp;<a rel="previous" accesskey="p" href="#HISTOGRAM">HISTOGRAM</a>,
7384 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7385
7386 </div>
7387
7388 <h3 class="section">18.10 INVERSE TELECINE</h3>
7389
7390 <p>This is the most effective deinterlacing tool when the footage is a
7391 video transfer of a film.  Here the film was converted from 24fps to
7392 60fps.  Then the 60fps was downsampled to 30fps by extracting odd and
7393 even lines and interlacing the lines.  The IVTC effect is primarily a
7394 way to convert interlaced video to progressive video.  It undoes three
7395 patterns of interlacing.
7396
7397 <pre class="example">       A AB BC CD D
7398        AB CD CD DE EF
7399        Automatic
7400 </pre>
7401    <p>The first two options are fixed patterns and affected by the <b>pattern
7402 offset</b> and <b>odd field first</b> parameters.  The last option creates
7403 several combinations of lines for each frame and picks the most
7404 progressive combination.  It's a brute force algorithm.
7405
7406    <p>This technique doesn't rely on a pattern like other techniques and is
7407 less destructive but the timing is going to be jittery because of the
7408 lack of a frame rate reduction.  In order to smooth out the timing, you
7409 need to follow inverse telecine with a decimate effect.
7410
7411 <div class="node">
7412 <a name="INTERPOLATE-VIDEO"></a>
7413 <p><hr>
7414 Next:&nbsp;<a rel="next" accesskey="n" href="#LENS">LENS</a>,
7415 Previous:&nbsp;<a rel="previous" accesskey="p" href="#INVERSE-TELECINE">INVERSE TELECINE</a>,
7416 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7417
7418 </div>
7419
7420 <h3 class="section">18.11 INTERPOLATE VIDEO</h3>
7421
7422 <p>The interpolate video effect tries to create the illusion of a higher
7423 frame rate from source footage of very low framerates by averaging
7424 frames over time.  It averages two input frames for each output frame.
7425 The input frames are at different times, resulting in a dissolve for
7426 all output frames between the input frames.  There are two ways of
7427 specifying the input frames.  You can specify an input frame rate which
7428 is lower than the project frame rate.  This causes input frames to be
7429 taken at even intervals,
7430
7431    <p>You can also specify keyframe locations as the positions of the input
7432 frames.  In this mode the output frame rate is used as the input frame
7433 rate and you just create keyframes wherever you want to specify an
7434 input frame.
7435
7436 <div class="node">
7437 <a name="LENS"></a>
7438 <p><hr>
7439 Next:&nbsp;<a rel="next" accesskey="n" href="#LINEARIZE">LINEARIZE</a>,
7440 Previous:&nbsp;<a rel="previous" accesskey="p" href="#INTERPOLATE-VIDEO">INTERPOLATE VIDEO</a>,
7441 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7442
7443 </div>
7444
7445 <h3 class="section">18.12 LENS</h3>
7446
7447 <p>The lens affect stretches or shrinks to convert lens distorted images to
7448 rectilinear images.  The most common use is converting fish eye lenses
7449 to rectilinear lenses.  It is also useful for star tracking.
7450
7451    <p><b>R, G, B, A Field of view:</b> These determine how much the image is
7452 stretched in each channel.
7453
7454    <p><b>Lock:</b> This causes changes to 1 channel to affect all the channels.
7455 This is normally the desired behavior.
7456
7457    <p><b>Aspect Ratio:</b> This changes the amount of stretching done in the X
7458 axis vs the Y axis.  To crop less data from stretched images, this
7459 allows more stretching to be done on 1 axis without creating black
7460 borders in the other axis.
7461
7462    <p><b>Radius:</b> This determines the size of the stretched region.  While
7463 adjusting the <b>field of view</b>, black borders may appear.  Adjust the
7464 <b>radius</b> to shrink or expand the output so black borders are out of
7465 frame.
7466
7467    <p><b>Center X, Y:</b> The center of the stretched region.  This is only
7468 useful if the image was previously translated by the software so the
7469 center of the lens is now off center.
7470
7471    <p><b>Draw center:</b> This is a visual aid when adjusting the <b>Center X, Y</b>
7472 but doesn't affect the results.
7473
7474    <p><b>Mode:</b> The type of stretching algorithm.
7475
7476      <ul>
7477 <li><b>Sphere shrink:</b> This is for making an image look like it's mapped to a sphere.
7478
7479      <li><b>Sphere expand:</b> This is for unmapping an image mapped to a sphere and
7480 flattening it.
7481
7482      <li><b>Rectilinear Stretch:</b> This is for flattening a fish eye lens.
7483
7484      <li><b>Rectilinear Shrink:</b> This is for making something flat look like it
7485 was taken by a fish eye lens.
7486
7487    </ul>
7488
7489 <div class="node">
7490 <a name="LINEARIZE"></a>
7491 <p><hr>
7492 Next:&nbsp;<a rel="next" accesskey="n" href="#LIVE-AUDIO">LIVE AUDIO</a>,
7493 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LENS">LENS</a>,
7494 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7495
7496 </div>
7497
7498 <h3 class="section">18.13 LINEARIZE</h3>
7499
7500 <p>Raw camera images store colors in a logarithmic scale.  The blacks in
7501 these images are nearly 0 and the whites are supposed to be infinity.
7502 The graphics card and most video codecs store colors in a linear scale
7503 but Cinelerra keeps raw camera images in their original logarithmic
7504 scale when it renders them.  This is necessary because the raw image
7505 parser can't always decode the proper gamma values for the images.  It
7506 also does its processing in 16 bit integers, which takes away a lot of
7507 information.
7508
7509    <p>The linearize effect converts the logarithmic colors to linear colors
7510 through a gamma value and a maximum value.  The gamma value determines
7511 how steep the output curve is and the maximum value is where 1.0 in the
7512 output corresponds to maximum brightness in the input.
7513
7514    <p>The linearize effect has 2 more parameters to simplify gamma
7515 correction.  The <b>automatic</b> option causes it to calculate <b>max</b>
7516 from the histogram of the image.  Use this when making a preview of a
7517 long list of images since it changes for every image.
7518
7519    <p>The <b>use color picker</b> option uses the value currently in the color
7520 picker to set the <b>max</b> value.  Note that every time you pick a color
7521 from the compositor window, you need to hit <b>use color picker</b> to
7522 apply the new value.
7523
7524 <div class="node">
7525 <a name="LIVE-AUDIO"></a>
7526 <p><hr>
7527 Next:&nbsp;<a rel="next" accesskey="n" href="#LIVE-VIDEO">LIVE VIDEO</a>,
7528 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LINEARIZE">LINEARIZE</a>,
7529 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7530
7531 </div>
7532
7533 <h3 class="section">18.14 LIVE AUDIO</h3>
7534
7535 <p>This effect reads audio directly from the soundcard input.  It replaces
7536 any audio on the track so it's normally applied to an empty track.
7537
7538    <p>To use Live Audio, highlight a horizontal region of an audio track or
7539 define in and out points.  Then drop the Live Audio effect into it.
7540 Create extra tracks and attach shared copies of the first Live Audio
7541 effect to the other tracks to have extra channels recorded.
7542
7543    <p>Live Audio uses the sound driver selected in
7544 <b>Settings-&gt;Preferences-&gt;Playback-&gt;Audio Out</b> for recording, but
7545 unlike recording it uses the <b>playback buffer size</b> as the recording
7546 buffer size and it uses the <b>project sample rate</b> as the sampling
7547 rate.
7548
7549    <p>These settings are critical since some sound drivers can't record in
7550 the same sized buffer they play back in.  Live audio has been most
7551 reliable when ALSA is the recording driver and the playback fragment
7552 size is 2048.
7553
7554    <p>Drop other effects after Live Audio to process soundcard input in
7555 realtime.
7556
7557    <p>Now the bad news.  With live audio there is no readahead so effects
7558 like compressor will either delay if they have readahead enabled or
7559 playback will underrun.
7560
7561    <p>Another problem is sometimes the recording clock on the soundcard is
7562 slightly slower than the playback clock.  The recording eventually
7563 falls behind and playback sounds choppy.
7564
7565    <p>Finally, live audio doesn't work in reverse.
7566
7567 <div class="node">
7568 <a name="LIVE-VIDEO"></a>
7569 <p><hr>
7570 Next:&nbsp;<a rel="next" accesskey="n" href="#LOOP">LOOP</a>,
7571 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LIVE-AUDIO">LIVE AUDIO</a>,
7572 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7573
7574 </div>
7575
7576 <h3 class="section">18.15 LIVE VIDEO</h3>
7577
7578 <p>This effect reads video directly from the capture card input.  It
7579 replaces any video on the track so it's normally applied to an empty
7580 track.  The configuration for the capture card is taken from the
7581 recording preferences.  Go to <b>Settings-&gt;Preferences-&gt;Recording</b> to
7582 set up the capture card.
7583
7584    <p>Go to the <b>Video In</b> section where it says <b>Record driver</b>.  It
7585 must be set to either <b>Video4Linux2</b> or <b>IEC 61883</b>.  Other video
7586 drivers haven't been tested with Live Video and probably won't work.
7587
7588    <p>For live video, the selection for <b>File Format</b> and <b>Video</b> needs
7589 to be set to a format the timeline can use.  The file format must be
7590 <b>Quicktime for Linux</b> and video recording must be enabled for it.
7591 Click on the wrench <img src="wrench.png" alt="wrench.png"> to set the video compression.
7592
7593    <p>The video compression depends on the recording driver.  For the
7594 <b>Video4Linux2</b> recording driver, the compression must be <b>Motion
7595 JPEG A</b>.  For the <b>IEC 61883</b> driver, the compression must be
7596 <b>DV</b>.  This gets the driver to generate output in a colormodel that
7597 the timeline can use.
7598
7599    <p>Some cards provide color and channel settings.  Live video takes the
7600 color settings from the values set in the <b>Video In</b> window.  Go to
7601 <b>File-&gt;Record</b> to bring up the recording interface and the Video In
7602 window.  Values set in the <b>Video in</b> window are used by <b>Live
7603 Video</b>.  Any channels the capture card supports need to be configured
7604 in the <b>Video in</b> interface since the same channels are used by the
7605 <b>Live Video</b> effect.
7606
7607    <p>With the video recording configured, highlight a horizontal region of a
7608 video track or define in and out points.  Then drop the Live Video
7609 effect into it.  Drop other effects after Live Video to process the
7610 live video in realtime.  For best results, you should use OpenGL and a
7611 video card which supports GL shading language.  Go to
7612 <b>Settings-&gt;Preferences-&gt;Playback-&gt;Video Out</b> to enable the OpenGL
7613 driver.
7614
7615    <p>Only one Live Video effect can exist at any time on the timeline.  It
7616 can't be shared by more than one track.
7617
7618 <div class="node">
7619 <a name="LOOP"></a>
7620 <p><hr>
7621 Next:&nbsp;<a rel="next" accesskey="n" href="#MOTION">MOTION</a>,
7622 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LIVE-VIDEO">LIVE VIDEO</a>,
7623 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7624
7625 </div>
7626
7627 <h3 class="section">18.16 LOOP</h3>
7628
7629 <p>Sections of audio or video can be looped by dropping a <b>loop</b> effect
7630 on them.  Contrary to the the <b>settings-&gt;loop playback</b> option, the
7631 loop effects can be rendered where the <b>settings-&gt;loop playback</b>
7632 option can not be.  The loop effects are also convenient for short
7633 regions.
7634
7635    <p>The loop effects have one option: the number of <b>frames</b> or
7636 <b>samples</b> to loop.  This specifies the length of the region to loop
7637 starting from either the beginning of the effect or the latest
7638 keyframe.  The region is replicated for the entire effect.
7639
7640    <p>Every time a keyframe is set in a loop effect, the keyframe becomes the
7641 beginning of the region to loop.  Setting several keyframes in
7642 succession causes several regions to loop.  Setting a single keyframe
7643 causes the region after the keyframe to be looped throughout the
7644 effect, no matter where the keyframe is.  The end of an effect can be
7645 looped from the beginning by setting the keyframe near the end.
7646
7647 <div class="node">
7648 <a name="MOTION"></a>
7649 <p><hr>
7650 Next:&nbsp;<a rel="next" accesskey="n" href="#MOTION-2-POINT">MOTION 2 POINT</a>,
7651 Previous:&nbsp;<a rel="previous" accesskey="p" href="#LOOP">LOOP</a>,
7652 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
7653
7654 </div>
7655
7656 <h3 class="section">18.17 MOTION</h3>
7657
7658 <p>The motion tracker is almost a complete application in itself.  The
7659 motion tracker tracks two types of motion: translation and rotation.
7660 It can track both simultaneously or one only.  It can do 1/4 pixel
7661 tracking or single pixel tracking.  It can stabilize motion or cause
7662 one track to follow the motion of another track.
7663
7664    <p>Although the motion tracker is applied as a realtime effect, it usually
7665 must be rendered to see useful results.  The effect takes a long time
7666 to precisely detect motion.
7667
7668    <p>The motion tracker works by using one region of the frame as the region
7669 to track.  It compares this region between 2 frames to calculate the
7670 motion.  This region can be defined anywhere on the screen.  Once the
7671 motion between 2 frames has been calculated, a number of things can be
7672 done with that motion vector.  It can be scaled by a user value and
7673 clamped to a maximum range.  It can be thrown away or accumulated with
7674 all the motion vectors leading up to the current position.
7675
7676    <p>To save time the motion result can be saved for later reuse, recalled
7677 from a previous calculation, or discarded.
7678
7679    <p>The motion tracker has a notion of 2 tracks, the master layer and the
7680 target layer.  The master layer is where the comparison between 2
7681 frames takes place.  The target layer is where motion is applied either
7682 to track or compensate for the motion in the master layer.
7683
7684    <p>The intricacies of motion tracking are enough to sustain entire
7685 companies and build careers around.  The motion tracker in Cinelerra
7686 isn't as sophisticated as some world class motion trackers but it's
7687 enough to sweeten some camcorder footage.
7688
7689    <p>Here is a brief description of the motion tracking parameters:
7690
7691      <ul>
7692 <li><b>Track translation:</b> Enables translation operations.
7693 The motion tracker tracks X and Y motion in the master layer and
7694 adjusts X and Y motion in the target layer.
7695
7696      <li>
7697 <b>Translation block size:</b> For the translation operations, a block is
7698 compared to a number of neighboring blocks to find the one with the
7699 least difference.  The size of the block to search for is given by this
7700 parameter.
7701
7702      <li>
7703 <b>Translation search radius:</b> The size of the area to scan for the
7704 translation block.
7705
7706      <li>
7707 <b>Translation search steps:</b> Ideally the search operation would
7708 compare the  translation block with every other pixel in the
7709 translation search radius.  To  speed this operation up, a subset of
7710 the total positions is searched.   Then the search area is narrowed and
7711 rescanned by the same number of search steps until the motion is known
7712 to 1/4 pixel accuracy.
7713
7714      <li>
7715 <b>Block X, Y:</b> These coordinates determine the center of the
7716 translation  block based on percentages of the width and height of the
7717 image.  The center of the block should be part of the image which is
7718 visible at all times.
7719
7720      <li>
7721 <b>Maximum absolute offset:</b> In <b>track previous frame</b> and <b>previous
7722 frame same block</b> modes, the motion detected between every frame is
7723 accumulated to form an absolute motion vector for the entire sequence.
7724 The amount of motion detected by the motion tracker is unlimited if this
7725 is 100.  If it's under 100 the amount of motion is limited to that
7726 percentage of the image size.  The value must be smaller for larger
7727 <b>translation block sizes</b> so there is enough area under the block to
7728 sense motion with.
7729
7730      <li>
7731 <b>Settling speed</b> In <b>track previous frame</b> and <b>previous frame
7732 same block</b> modes, the motion detected between every frame is
7733 accumulated to form an absolute motion vector for the entire sequence.
7734 To keep the absolute motion from exceeding limits, it can be
7735 automatically reset over time by the settling speed.  If the settling
7736 speed is 100 the absolute vector resets to 0 after every frame.  If the
7737 settling speed is less than 100 the absolute vector is reduced slightly
7738 before the next frame is added.
7739
7740      <li>
7741 <b>Track rotation:</b> Enables rotation operations.  The motion tracker
7742 tracks rotation in the master layer and adjusts rotation in the target
7743 layer.
7744
7745      <li>
7746 <b>Rotation block size:</b> For rotation operations a single block is
7747 compared to equally sized blocks, each rotated by a different amount.
7748 This is the size of the rotation block.
7749
7750      <li>
7751 <b>Rotation search radius:</b> This is the maximum angle of rotation from
7752 the starting frame the rotation scanner can detect.  The rotation scan
7753 is from this angle counterclockwise to this angle clockwise.  Thus the
7754 rotation search radius is half the total range scanned.
7755
7756      <li>
7757 <b>Rotation search steps:</b> Ideally every possible angle would be tested
7758 to get the rotation.  To speed up the rotation search, the rotation
7759 search radius is divided into a finite number of angles and only those
7760 angles compared to the starting frame.  Then the search radius is
7761 narrowed and an equal number of angles is compared in the smaller
7762 radius until the highest possible accuracy is achieved.
7763
7764      <p>Normally you need one search step for every degree scanned.  Since the
7765 rotation scanner scans the rotation search radius in two directions,
7766 you need two steps for every degree in the search radius to search the
7767 complete range.
7768
7769      <li>
7770 <b>Draw vectors:</b> When translation is enabled, 2 boxes are drawn on the
7771 frame.  One box represents the translation block.  Another box outside
7772 the translation block represents the extent of the translation search
7773 radius.  In the center of these boxes is an arrow showing the
7774 translation between the 2 master frames.
7775
7776      <p>When rotation is enabled a single box the size of the rotation block is
7777 drawn rotated by the amount of rotation detected.
7778
7779      <li>
7780 <b>Track single frame:</b> When this option is used the motion between a
7781 single starting frame and the frame currently under the insertion point
7782 is calculated.  The starting frame is specified in the <b>Frame number</b>
7783 blank.  The motion calculated this way is taken as the absolute motion
7784 vector.  The absolute motion vector for each frame replaces the
7785 absolute motion vector for the previous frame.  Settling speed has no
7786 effect on it since it doesn't contain any previous motion vectors.
7787 Playback can start anywhere on the timeline since there is no
7788 dependance on previous results.
7789
7790      <li>
7791 <b>Track previous frame:</b> Causes only the motion between the previous
7792 frame and the current frame to be calculated.  This is added to an
7793 absolute motion vector to get the new motion from the start of the
7794 sequence to the current position.  After every frame processed this
7795 way, the block position is shifted to always cover the same region of
7796 the image.  Playback must be started from the start of the motion
7797 effect in order to accumulate all the necessary motion vectors.
7798
7799      <li>
7800 <b>Previous frame same block:</b> This is useful for stabilizing jerky
7801 camcorder footage.  In this mode the motion between the previous frame
7802 and the current frame is calculated.  Instead of adjusting the block
7803 position to reflect the new location of the image, like Track Previous
7804 Frame does, the block position is unchanged between each frame.  Thus a
7805 new region is compared for each frame.
7806
7807      <li>
7808 <b>Master layer:</b> This determines the track which supplies the starting
7809 frame and ending frame for the motion calculation.  If it's <b>Bottom</b>
7810 the bottom track of all the tracks sharing this effect is the master
7811 layer.  The top track of all the tracks is the target layer.
7812
7813      <li>
7814 <b>Calculation:</b> This determines whether to calculate the motion at all
7815 and whether to save it to disk.  If it's <b>Don't Calculate</b> the motion
7816 calculation is skipped.  If it's <b>Recalculate</b> the motion calculation
7817 is performed every time each frame is rendered.  If it's <b>Save</b> the
7818 motion calculation is always performed but a copy is also saved.  If
7819 it's <b>Load</b>, the motion calculation is loaded from a previous save
7820 calculation.  If there is no previous save calculation on disk, a new
7821 motion calculation is performed.
7822
7823      <li>
7824 <b>Action:</b> Once the motion vector is known this determines whether to
7825 move the target layer opposing the motion vector or following the
7826 motion vector.  If it's <b>Do Nothing</b> the target layer is untouched.
7827 If it's <b>Track...</b> the target layer is moved by the same amount as
7828 the master layer.  This is useful for matching titles to objects in the
7829 frame.  If it's <b>Stabilize...</b> the target layer is moved opposite to
7830 the motion vector.  This is useful for stabilizing an object in the
7831 frame.  The motion operations can be accurate to single pixels or
7832 subpixels by changing the action setting.
7833
7834    </ul>
7835
7836 <ul class="menu">
7837 <li><a accesskey="1" href="#SECRETS-OF-MOTION-TRACKING">SECRETS OF MOTION TRACKING</a>
7838 <li><a accesskey="2" href="#g_t2-PASS-MOTION-TRACKING">2 PASS MOTION TRACKING</a>
7839 <li><a accesskey="3" href="#USING-BLUR-TO-IMPROVE-MOTION-TRACKING">USING BLUR TO IMPROVE MOTION TRACKING</a>
7840 <li><a accesskey="4" href="#USING-HISTOGRAM-TO-IMPROVE-MOTION-TRACKING">USING HISTOGRAM TO IMPROVE MOTION TRACKING</a>
7841 <li><a accesskey="5" href="#INTERPOLATING-MOTION-BETWEEN-FRAMES">INTERPOLATING MOTION BETWEEN FRAMES</a>
7842 <li><a accesskey="6" href="#FILLING-IN-THE-BLACK-AREAS">FILLING IN THE BLACK AREAS</a>
7843 </ul>
7844
7845 <div class="node">
7846 <a name="SECRETS-OF-MOTION-TRACKING"></a>
7847 <p><hr>
7848 Next:&nbsp;<a rel="next" accesskey="n" href="#g_t2-PASS-MOTION-TRACKING">2 PASS MOTION TRACKING</a>,
7849 Up:&nbsp;<a rel="up" accesskey="u" href="#MOTION">MOTION</a>
7850
7851 </div>
7852
7853 <h4 class="subsection">18.17.1 SECRETS OF MOTION TRACKING</h4>
7854
7855 <p>Since it is a very slow effect, there is a method to applying the
7856 motion tracker to get the most out of it.  First disable playback for
7857 the track to do motion tracking on.  Then drop the effect on a region
7858 of video with some motion to track.  Then rewind the insertion point to
7859 the start of the region.  Set <b>Action</b> -&gt; <b>Do Nothing</b>.  Set
7860 <b>Calculation</b> -&gt; <b>Don't calculate</b>.  Enable <b>Draw vectors</b>. Then
7861 enable playback of the track to see the motion tracking areas.
7862
7863    <p>Enable which of <b>translation motion</b> or <b>rotation motion</b> vectors
7864 you want to track.  By watching the compositor window and adjusting the
7865 <b>Block x,y</b> settings, center the block on the part of the image you
7866 want to track.  Then set search radius, block size, and block
7867 coordinates for translation and rotation.
7868
7869    <p>Once this is configured, set the calculation to <b>Save coords</b> and do
7870 test runs through the sequence to see if the motion tracker works and
7871 to save the motion vectors.  Once this is done, disable playback for
7872 the track, disable <b>Draw vectors</b>, set the motion action to perform
7873 on the target layer and change the calculation to <b>Load coords</b>.
7874 Finally enable playback for the track.
7875
7876    <p>When using a single starting frame to calculate the motion of a
7877 sequence, the starting frame should be a single frame with the least
7878 motion to any of the other frames.  This is rarely frame 0.  Usually
7879 it's a frame near the middle of the sequence.  This way the search
7880 radius need only reach halfway to the full extent of the motion in the
7881 sequence.
7882
7883    <p>If the motion tracker is used on a render farm, <b>Save coords</b> and
7884 <b>previous frame</b> mode won't work.  The results of the save coords
7885 operation are saved to the hard drives on the render nodes, not the
7886 master node.  Future rendering operations on these nodes will process
7887 different frames and read the wrong coordinates from the node
7888 filesystems.  The fact that render nodes only visualize a portion of
7889 the timeline also prevents <b>previous frame</b> from working since it
7890 depends on calculating an absolute motion vector starting on frame 0.
7891
7892 <div class="node">
7893 <a name="g_t2-PASS-MOTION-TRACKING"></a>
7894 <p><hr>
7895 Next:&nbsp;<a rel="next" accesskey="n" href="#USING-BLUR-TO-IMPROVE-MOTION-TRACKING">USING BLUR TO IMPROVE MOTION TRACKING</a>,
7896 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SECRETS-OF-MOTION-TRACKING">SECRETS OF MOTION TRACKING</a>,
7897 Up:&nbsp;<a rel="up" accesskey="u" href="#MOTION">MOTION</a>
7898
7899 </div>
7900
7901 <h4 class="subsection">18.17.2 2 PASS MOTION TRACKING</h4>
7902
7903 <p>The method described above is 2 pass motion tracking.  One pass is used
7904 just to calculate the motion vectors.  A second pass is used to apply
7905 the motion vectors to the footage.  This is faster than a single pass
7906 because errors in the motion vector calculation can be discovered
7907 quickly.
7908
7909    <p>This also allows the motion tracking to use a less demanding colormodel
7910 like RGB888 in the scanning step and a more demanding colormodel like
7911 RGB Float in the action step.  The scanning step takes much longer than
7912 action.
7913
7914    <p>This suffers the disadvantage of not being practical for extremely long
7915 sequences where some error is acceptable and the picture quality is
7916 lousy to begin with, like stabilizing camcorder footage.
7917
7918    <p>The slower method is to calculate the motion vectors and apply them
7919 simultaneously.  This method can use one track as the motion vector
7920 calculation track and another track as the target track for motion
7921 vector actions.  This is useful for long sequences where some error is
7922 acceptable.
7923
7924 <div class="node">
7925 <a name="USING-BLUR-TO-IMPROVE-MOTION-TRACKING"></a>
7926 <p><hr>
7927 Next:&nbsp;<a rel="next" accesskey="n" href="#USING-HISTOGRAM-TO-IMPROVE-MOTION-TRACKING">USING HISTOGRAM TO IMPROVE MOTION TRACKING</a>,
7928 Previous:&nbsp;<a rel="previous" accesskey="p" href="#g_t2-PASS-MOTION-TRACKING">2 PASS MOTION TRACKING</a>,
7929 Up:&nbsp;<a rel="up" accesskey="u" href="#MOTION">MOTION</a>
7930
7931 </div>
7932
7933 <h4 class="subsection">18.17.3 USING BLUR TO IMPROVE MOTION TRACKING</h4>
7934
7935 <p>With extremely noisy or interlaced footage, applying a blur effect
7936 before the motion tracking can improve accuracy.  Either save the
7937 motion vectors in a <b>tracking pass</b> and disable the blur for the
7938 <b>action pass</b> or apply the blur just to the <b>master layer</b>.
7939
7940 <div class="node">
7941 <a name="USING-HISTOGRAM-TO-IMPROVE-MOTION-TRACKING"></a>
7942 <p><hr>
7943 Next:&nbsp;<a rel="next" accesskey="n" href="#INTERPOLATING-MOTION-BETWEEN-FRAMES">INTERPOLATING MOTION BETWEEN FRAMES</a>,
7944 Previous:&nbsp;<a rel="previous" accesskey="p" href="#USING-BLUR-TO-IMPROVE-MOTION-TRACKING">USING BLUR TO IMPROVE MOTION TRACKING</a>,
7945 Up:&nbsp;<a rel="up" accesskey="u" href="#MOTION">MOTION</a>
7946
7947 </div>
7948
7949 <h4 class="subsection">18.17.4 USING HISTOGRAM TO IMPROVE MOTION TRACKING</h4>
7950
7951 <p>A histogram is almost always applied before motion tracking to clamp
7952 out noise in the darker pixels.  Either save the motion vectors in a
7953 <b>tracking pass</b> and disable the histogram for the <b>action pass</b> or
7954 apply the histogram just to the <b>master layer</b>.
7955
7956 <div class="node">
7957 <a name="INTERPOLATING-MOTION-BETWEEN-FRAMES"></a>
7958 <p><hr>
7959 Next:&nbsp;<a rel="next" accesskey="n" href="#FILLING-IN-THE-BLACK-AREAS">FILLING IN THE BLACK AREAS</a>,
7960 Previous:&nbsp;<a rel="previous" accesskey="p" href="#USING-HISTOGRAM-TO-IMPROVE-MOTION-TRACKING">USING HISTOGRAM TO IMPROVE MOTION TRACKING</a>,
7961 Up:&nbsp;<a rel="up" accesskey="u" href="#MOTION">MOTION</a>
7962
7963 </div>
7964
7965 <h4 class="subsection">18.17.5 INTERPOLATING MOTION BETWEEN FRAMES</h4>
7966
7967 <p>The motion tracker can simulate higher frame rates than the media frame
7968 rate by interpolating the motion.  Interpolation is enabled with the
7969 <b>maximum absolute offset</b> and <b>settling speed</b> options.
7970
7971    <p>First, go to <b>Settings-&gt;Format</b> in the main window and set the
7972 <b>video frame rate</b> to a number higher than the media frame rate.
7973
7974    <p>In the <b>Motion</b> window, select a tracking option which accumulates
7975 motion.  This is either <b>Track previous frame</b> or <b>Previous frame
7976 same block</b>.  These cause the <b>maximum absolute offset</b> and
7977 <b>settling speed</b> options to take effect.
7978
7979    <p><b>maximum absolute offset</b> must be set to the maximum motion to be
7980 accumulated as a percentage of the video size.  A value of 50 limits the
7981 motion to 50% of the video size.  50 works well.  The value must be
7982 smaller for larger <b>translation block sizes</b> so there is enough area
7983 under the block to sense motion with.
7984
7985    <p><b>settling speed</b> must be set to the rate at which the accumulated
7986 motion resets to 0 over time.  The reset happens whether or not any
7987 motion was detected, so when the project frame rate is higher than the
7988 media frame rate, the frames between media frames regress towards the
7989 center.  For interpolated motion, the <b>settling speed</b> value should be
7990 small, so the movement is smooth.  3 works well.
7991
7992 <div class="node">
7993 <a name="FILLING-IN-THE-BLACK-AREAS"></a>
7994 <p><hr>
7995 Previous:&nbsp;<a rel="previous" accesskey="p" href="#INTERPOLATING-MOTION-BETWEEN-FRAMES">INTERPOLATING MOTION BETWEEN FRAMES</a>,
7996 Up:&nbsp;<a rel="up" accesskey="u" href="#MOTION">MOTION</a>
7997
7998 </div>
7999
8000 <h4 class="subsection">18.17.6 FILLING IN THE BLACK AREAS</h4>
8001
8002 <p>Stabilization always creates black borders in the track resolution.  One
8003 solution is to shrink the project resolution so the borders are always
8004 cropped off the output.  Another solution is to apply a <b>Time Average</b>
8005 effect after stabilization.
8006
8007    <p>Configure <b>Time Average</b> the following way:
8008
8009      <ul>
8010 <li><b>Frame count:</b> 1
8011 <li><b>Accumulate sequence again:</b> No
8012 <li><b>Replace:</b> Yes
8013 <li><b>Threshold:</b> 1
8014 <li><b>Border:</b> 4
8015 </ul>
8016
8017    <p>This makes new frames replace only the pixels in the previous frames
8018 where there is new data.  The black areas in new frames don't replace
8019 previous data so the previous data shows through and fills them in.
8020
8021 <div class="node">
8022 <a name="MOTION-2-POINT"></a>
8023 <p><hr>
8024 Next:&nbsp;<a rel="next" accesskey="n" href="#REFRAMERT">REFRAMERT</a>,
8025 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MOTION">MOTION</a>,
8026 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
8027
8028 </div>
8029
8030 <h3 class="section">18.18 MOTION 2 POINT</h3>
8031
8032 <p>The 2 point motion tracker is the same as using 2 of the translation
8033 motion trackers to track 2 points.  It doesn't have a rotation tracker.
8034 Instead, it uses the angle between the 2 translation points to
8035 determine  rotation.  The 2 points can be enabled separately.
8036
8037    <p>If 1 point is enabled, only translation is tracked.
8038
8039    <p>If 2 points are enabled, translation is tracked by point 1 and rotation
8040 is tracked by point 2.  Stabilization is performed with point 1 as the center.
8041
8042    <p>The other parameters for the 2 point tracker are the same as the single
8043 point tracker.  In addition, the 2 point tracker supports <b>TRANSLATION
8044 SEARCH OFFSET</b>.
8045
8046    <p><b>TRANSLATION SEARCH OFFSET</b> forces the motion search to look in a
8047 region other than directly next to the translation block position.  The
8048 <b>translation search offset</b> is added to the new search result, giving
8049 contiguous motion results throughout any changes in translation search area.
8050
8051    <p>This is useful if the camera position changed in the middle of a
8052 sequence of images but the subject stayed the same.  Offset the
8053 translation search area when the camera position changes and the
8054 detected motion stays contiguous through the entire sequence.
8055
8056    <p>2 point tracking works best if the points don't change shape between
8057 frames.  It is more prone to rotation errors than single point motion
8058 tracking if the points change shape.  2 point tracking is mainly used
8059 for tracking stars.
8060
8061    <p>Use the smallest search blocks possible since larger blocks are harder
8062 to compare when they're rotated.
8063
8064 <div class="node">
8065 <a name="REFRAMERT"></a>
8066 <p><hr>
8067 Next:&nbsp;<a rel="next" accesskey="n" href="#REFRAME">REFRAME</a>,
8068 Previous:&nbsp;<a rel="previous" accesskey="p" href="#MOTION-2-POINT">MOTION 2 POINT</a>,
8069 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
8070
8071 </div>
8072
8073 <h3 class="section">18.19 REFRAMERT</h3>
8074
8075 <p>ReframeRT changes number of frames in a sequence of video directly from
8076 the timeline.  It has 2 modes, selected by the 2 toggles in the GUI.
8077
8078    <p><b>Stretch</b> mode multiplies the current frame number of its output by
8079 the scale factor to arrive at the frame to read from its input.  If its
8080 current output frame is #55 and the scale factor is 2, frame #110 is
8081 read from its input.  The stretch mode has the effect of changing the
8082 length of output video by the inverse of the scale factor.  If the
8083 scale factor is greater than 1, the output will end before the end of
8084 the sequence on the timeline.  If it's less than 1, the output will end
8085 after the end of the sequence on the timeline.  The ReframeRT effect
8086 must be lengthened to the necessary length to accomodate the scale
8087 factor.  Change the length of the effect by clicking on the endpoint of
8088 the effect and dragging.
8089
8090    <p>Although stretch mode changes the number of the frame read from its
8091 input, it doesn't change the frame rate of the input.  Effects before
8092 ReframeRT assume the same frame rate as ReframeRT.
8093
8094    <p><b>Downsample</b> mode doesn't change the length of the output sequence.
8095 It multiplies the frame rate of the output by the scale factor to
8096 arrive at a frame rate rate to read the input.  This has the effect of
8097 replicating the input frames so that they only change at the scaled
8098 frame rate when sent to the output.  It doesn't change the length of
8099 the sequence.  If the scale factor is 0.5 and the output frame rate is
8100 30 fps, only 15 frames will be shown per second and the input will be
8101 read at 15 fps.  Downsample is only useful for scalefactors below 1,
8102 hence the name downsample.
8103
8104    <p>Downsample mode changes the frame rate of the input as well as the
8105 number of the frame to read, so effects before ReframeRT see the frame
8106 rate * the scale factor as their frame rate.  If the scale factor is 2
8107 and the output frame rate is 30, the input frame rate will be 60 and
8108 the input frame number will by doubled.  This won't normally do
8109 anything but some input effects may behave differently at the higher
8110 frame rate.
8111
8112 <div class="node">
8113 <a name="REFRAME"></a>
8114 <p><hr>
8115 Next:&nbsp;<a rel="next" accesskey="n" href="#RESAMPLE">RESAMPLE</a>,
8116 Previous:&nbsp;<a rel="previous" accesskey="p" href="#REFRAMERT">REFRAMERT</a>,
8117 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
8118
8119 </div>
8120
8121 <h3 class="section">18.20 REFRAME</h3>
8122
8123 <p>This does exactly the same thing as <b>ReframeRT</b> in <b>Stretch</b> mode.
8124 It multiplies the output frame number by the scale factor to arrive at
8125 the input frame number and changes the length of the sequence.  Unlike
8126 ReframeRT, this must run from the <b>Video</b> menu and render its output.
8127
8128    <p>Be aware <b>Reframe</b> doesn't write the scaled frame rate as the frame
8129 rate of the rendered file.  It produces a file of scaled length and
8130 equal frame rate as the project.  The new length is 1/scale factor as
8131 big as the original sequence.
8132
8133 <div class="node">
8134 <a name="RESAMPLE"></a>
8135 <p><hr>
8136 Next:&nbsp;<a rel="next" accesskey="n" href="#REVERSE-VIDEO_002fAUDIO">REVERSE VIDEO/AUDIO</a>,
8137 Previous:&nbsp;<a rel="previous" accesskey="p" href="#REFRAME">REFRAME</a>,
8138 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
8139
8140 </div>
8141
8142 <h3 class="section">18.21 RESAMPLE</h3>
8143
8144 <p>This multiplies the number of each output sample by a scale factor to
8145 arrive at the number of the input sample.  The output file's sample
8146 rate is set to the project sample rate but its length is changed to
8147 reflect the scaled number of samples.  It also filters the resampled
8148 audio to remove aliasing.
8149
8150    <p>If the scale factor is 2, every 2 input samples will be reduced to 1
8151 output sample and the output file will have half as many samples as the
8152 input sequence.  If it's 0.5, every 0.5 input samples will be stretched
8153 to 1 output sample and the output file will have twice as many samples
8154 as the input sequence.
8155
8156 <div class="node">
8157 <a name="REVERSE-VIDEO%2fAUDIO"></a>
8158 <a name="REVERSE-VIDEO_002fAUDIO"></a>
8159 <p><hr>
8160 Next:&nbsp;<a rel="next" accesskey="n" href="#SWAP-FRAMES">SWAP FRAMES</a>,
8161 Previous:&nbsp;<a rel="previous" accesskey="p" href="#RESAMPLE">RESAMPLE</a>,
8162 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
8163
8164 </div>
8165
8166 <h3 class="section">18.22 REVERSE VIDEO/AUDIO</h3>
8167
8168 <p>Media can be reversed on the timeline in realtime.  This isn't to be
8169 confused with using the reverse playback on the transport.  The reverse
8170 effects reverse the region covered by the effect regardless of the
8171 transport direction.  Apply <b>reverse audio</b> to an audio track and
8172 play it backwards.  The sound plays forward.
8173
8174    <p>The region to be reversed is first determined by what part of the track
8175 the effect is under and second by the locations of keyframes in the
8176 effect.  The reverse effects have an <b>enabled</b> option which allows
8177 you to set keyframes.  This allows may possibilities.
8178
8179    <p>Every <b>enabled</b> keyframe is treated as the start of a new reversed
8180 region and the end of a previous reversed region.  Several <b>enabled</b>
8181 keyframes in succession yield several regions reversed independant of
8182 each other.  An <b>enabled</b> keyframe followed by a <b>disabled</b>
8183 keyframe yields one reversed region followed by a forward region.
8184
8185    <p>Finally, be aware when reversing audio that the waveform on the
8186 timeline doesn't reflect the actual reversed output.
8187
8188 <div class="node">
8189 <a name="SWAP-FRAMES"></a>
8190 <p><hr>
8191 Next:&nbsp;<a rel="next" accesskey="n" href="#THRESHOLD">THRESHOLD</a>,
8192 Previous:&nbsp;<a rel="previous" accesskey="p" href="#REVERSE-VIDEO_002fAUDIO">REVERSE VIDEO/AUDIO</a>,
8193 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
8194
8195 </div>
8196
8197 <h3 class="section">18.23 SWAP FRAMES</h3>
8198
8199 <p>This is normally used on interlaced video which has been converted to
8200 fields.  One set of lines becomes one frame and the other set of lines
8201 becomes the next frame.  Now the frame rate is double and is showing
8202 fields of the original video sequentially.  The fields may be out of
8203 order, which is what <b>SWAP FRAMES</b> can correct.
8204
8205 <div class="node">
8206 <a name="THRESHOLD"></a>
8207 <p><hr>
8208 Next:&nbsp;<a rel="next" accesskey="n" href="#TIME-AVERAGE">TIME AVERAGE</a>,
8209 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SWAP-FRAMES">SWAP FRAMES</a>,
8210 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
8211
8212 </div>
8213
8214 <h3 class="section">18.24 THRESHOLD</h3>
8215
8216 <p>Threshold converts the image to pure luminance.  Then luminance values
8217 below and above the threshold range are converted to black and
8218 luminance values inside the threshold range are converted to white.
8219 The threshold window shows a histogram of luminance values for the
8220 current frame.  Click dragging inside the histogram creates a range to
8221 convert to white.  Shift-clicking extends one border of this range.
8222 Values for the threshold range can also be specified in the text boxes.
8223
8224    <p>This effect is basically a primitive luminance key.  A second track
8225 above the track with the threshold effect can be multiplied, resulting
8226 in only the parts of the second track within the threshold being
8227 displayed.
8228
8229 <div class="node">
8230 <a name="TIME-AVERAGE"></a>
8231 <p><hr>
8232 Next:&nbsp;<a rel="next" accesskey="n" href="#TITLER">TITLER</a>,
8233 Previous:&nbsp;<a rel="previous" accesskey="p" href="#THRESHOLD">THRESHOLD</a>,
8234 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
8235
8236 </div>
8237
8238 <h3 class="section">18.25 TIME AVERAGE</h3>
8239
8240 <p>Time average is one effect which has many uses besides creating nifty
8241 trail patterns of moving objects.  It's main use is reducing noise in
8242 still images.  Merely point a video camera at a stationary subject for
8243 30 frames, capture the frames, and average them using TIME AVERAGE and
8244 you'll have a super high quality print.  In floating point colormodels, time
8245 average can increase the dynamic range of lousy cameras.
8246
8247    <p>Inside the time average effect is an accumulation buffer and a
8248 divisor.  A number of frames are accumulated in the accumulation buffer
8249 and divided by the divisor to get the average.
8250
8251    <p>Because the time average can consume enourmous amounts of memory, it is
8252 best applied by first disabling playback for the track, dropping the
8253 time average in it, configuring time average for the desired number of
8254 frames, and re-enabling playback for the track.
8255
8256    <p><b>Frames count:</b> This determines the number of frames to be accumulated
8257 in the accumulation buffer.  For extremely large integrations it's
8258 easier to edit the EDL in a text editor and put in the number of frames.
8259
8260    <p><b>Accumulate sequence again:</b> If an effect before the time average is
8261 adjusted the time average normally doesn't reread the accumulation
8262 buffer to get the change.  This forces it to reread the accumulation
8263 buffer when any other effects change.
8264
8265    <p><b>Average:</b> This causes the accumulation buffer to be divided before
8266 being output.  The result is the average of all the frames.
8267
8268    <p><b>Accumulate:</b> This outputs the accumulation buffer without dividing
8269 it.  The result is the sum of all the frames.
8270
8271    <p><b>Accumulate only:</b>
8272
8273    <p>In order to accumulate only the specified number of frames, the time
8274 average retains all the previous frames in memory and subtracts them out
8275 as it plays forward.  <b>Accumulate only:</b> causes the history buffer to
8276 not be used in <b>averaging</b> and <b>accumulating</b>.  Without the history
8277 buffer, frames are added endlessly without ever being subtracted.  It's
8278 the same as an infinitely long accumulation buffer.  The only difference
8279 is for <b>Average</b> mode, the output is still divided by the <b>Frame
8280 count</b>.  <b>Accumulate only</b> is used where the number of frames in the
8281 accumulation would be too big to fit in memory.
8282
8283    <p><b>Replace:</b> This causes the accumulation buffer to be replaced by only
8284 pixels which aren't transparent.  This allows black borders from motion
8285 tracking to be filled in.
8286
8287    <p><b>Threshold:</b> The value a pixel must be before it replaces the previous
8288 pixel.  If alpha channels are enabled, the alpha is the value compared.
8289 If there is no alpha channel, the brightness is the value compared.
8290
8291    <p><b>Border:</b> The number of pixels on the border of the image to never
8292 replace.  This hides errors in the replacement operation from the
8293 output, since errors occur at the transition between the replaced area
8294 and the ignored area.
8295
8296    <p><b>Greater:</b> Pixels are replaced if their value is greater than the
8297 previous pixel.  Use this to create star trails in stacks of many night
8298 sky photos or paint many copies of an object from its motion if it is
8299 lighter than the background.
8300
8301    <p><b>Less:</b> Pixels are replaced if their value is less than the previous
8302 pixel.  Use this to paint copies of an object from its motion if it is
8303 darker than the background.
8304
8305 <div class="node">
8306 <a name="TITLER"></a>
8307 <p><hr>
8308 Next:&nbsp;<a rel="next" accesskey="n" href="#VIDEO-SCOPE">VIDEO SCOPE</a>,
8309 Previous:&nbsp;<a rel="previous" accesskey="p" href="#TIME-AVERAGE">TIME AVERAGE</a>,
8310 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
8311
8312 </div>
8313
8314 <h3 class="section">18.26 TITLER</h3>
8315
8316 <p>While it is possible to add text to movies by importing still images
8317 from The Gimp and compositing them, the Titler allows you to add text
8318 from within Cinelerra.
8319
8320    <p>The titler has standard options for <b>font, size, and style</b>.  The
8321 best font is a generic, normal font like Arial in a large size.
8322
8323    <p>The titler also has options you'll only find in moving pictures.  The
8324 <b>Justify</b> operation justifies the text relative to the entire frame.
8325 Once justified, the <b>X and Y</b> offset is applied.  This allows text to
8326 be justified while at the same time letting you push it within the
8327 title safe region.
8328
8329    <p>The <b>motion type</b> scrolls the text in any of the four directions.
8330 When using this, the text may dissappear.  Move the insertion point
8331 along the timeline until the text is far enough along the animation to
8332 reappear.  The text scrolls on and scrolls off.
8333
8334    <p>Setting <b>loop</b> causes the text to scroll completely off and repeat.
8335 Without <b>loop</b> the text scrolls off and never reappears.
8336
8337    <p>The speed of the animation is determined by <b>speed</b>  Set it higher to
8338 speed up the animation.
8339
8340    <p><b>Drop shadow</b> draws a black copy of the text to the bottom right of
8341 the original text.  Useful when drawing text over changing video to
8342 keep the border always visible.
8343
8344    <p>In addition to the scrolling, <b>Fade in/Fade out</b> are a second type of
8345 animation.  If the fade seconds are 0, no fading is done.
8346
8347    <p><b>Outline</b> draws an outline on the characters if it's greater than 0.
8348 Set the outline size by changing the number.  Set the outline color with
8349 the <b>OUTLINE COLOR</b> button.  If no outline is visible, make sure the
8350 alpha in <b>OUTLINE COLOR</b> is nonzero.  To get pure outline characters,
8351 set <b>COLOR</b> alpha to 0.
8352
8353    <p><b>COLOR</b> picks the color to draw the text in.  Usually white is the
8354 only practical color.
8355
8356    <p><b>OUTLINE COLOR</b> picks the color to draw the text outline in.
8357
8358    <p><b>Stamp timecode</b> replaces the text with the current position on the
8359 timeline in seconds and frames.
8360
8361    <p><b>SECRETS OF THE TITLER</b>
8362
8363 <ul class="menu">
8364 <li><a accesskey="1" href="#ADDING-FONTS-TO-THE-TITLER">ADDING FONTS TO THE TITLER</a>:  How to add fonts to the titler
8365 <li><a accesskey="2" href="#THE-TITLE_002dSAFE-REGION">THE TITLE-SAFE REGION</a>:       How to keep text visible on output
8366 <li><a accesskey="3" href="#MAKING-TITLES-LOOK-GOOD">MAKING TITLES LOOK GOOD</a>:     How to make your titles look good.
8367 </ul>
8368
8369 <div class="node">
8370 <a name="ADDING-FONTS-TO-THE-TITLER"></a>
8371 <p><hr>
8372 Next:&nbsp;<a rel="next" accesskey="n" href="#THE-TITLE_002dSAFE-REGION">THE TITLE-SAFE REGION</a>,
8373 Up:&nbsp;<a rel="up" accesskey="u" href="#TITLER">TITLER</a>
8374
8375 </div>
8376
8377 <h4 class="subsection">18.26.1 ADDING FONTS TO THE TITLER</h4>
8378
8379 <p>The X Window system originally didn't have a suitable font renderer for
8380 video.  It also is restricted to the current bit depth.  It doesn't
8381 have a convenient way to know which fonts work with the suitable font
8382 renderer in the desired bit depth.  The easiest way we've found to
8383 support fonts in the titler is to have a directory for them at
8384 <b>/usr/lib/cinelerra/fonts</b>.
8385
8386    <p>The titler supports mainly <b>TTF</b>, true type fonts.  It supports
8387 others but TTF are the most reliable.  To add true type fonts, copy the
8388 <b>.TTF</b> files to the <b>/usr/lib/cinelerra/fonts</b> directory.  In that
8389 directory run <b>ttmkfdir &amp;&amp; mv fonts.scale fonts.dir</b> and restart
8390 Cinelerra.  The new fonts should appear.  The usage of ttmkfdir changes
8391 frequently so this technique might not work.
8392
8393 <div class="node">
8394 <a name="THE-TITLE-SAFE-REGION"></a>
8395 <a name="THE-TITLE_002dSAFE-REGION"></a>
8396 <p><hr>
8397 Next:&nbsp;<a rel="next" accesskey="n" href="#MAKING-TITLES-LOOK-GOOD">MAKING TITLES LOOK GOOD</a>,
8398 Previous:&nbsp;<a rel="previous" accesskey="p" href="#ADDING-FONTS-TO-THE-TITLER">ADDING FONTS TO THE TITLER</a>,
8399 Up:&nbsp;<a rel="up" accesskey="u" href="#TITLER">TITLER</a>
8400
8401 </div>
8402
8403 <h4 class="subsection">18.26.2 THE TITLE-SAFE REGION</h4>
8404
8405 <p>If the video is displayed on a consumer TV, the outer border is going
8406 to be cropped by 5% on each side.  Moreover, text which is too close to
8407 the edge looks sloppy.  Make sure when adding titles to have the
8408 <b>title-safe</b> <img src="titlesafe.png" alt="titlesafe.png"> tool active in the <b>compositor</b> window.
8409 The text shouldn't cross the inner rectangle.
8410
8411 <div class="node">
8412 <a name="MAKING-TITLES-LOOK-GOOD"></a>
8413 <p><hr>
8414 Previous:&nbsp;<a rel="previous" accesskey="p" href="#THE-TITLE_002dSAFE-REGION">THE TITLE-SAFE REGION</a>,
8415 Up:&nbsp;<a rel="up" accesskey="u" href="#TITLER">TITLER</a>
8416
8417 </div>
8418
8419 <h4 class="subsection">18.26.3 MAKING TITLES LOOK GOOD</h4>
8420
8421 <p>No-one else is going to tell you this, but to make good looking titles,
8422 ignore most of the features of the titler.  The best settings are:
8423
8424      <ul>
8425 <li>Font: <b>Arial</b>
8426 <li>Italic: <b>off</b>
8427 <li>Motion: <b>No motion</b>
8428 <li>Bold: <b>on or off</b>
8429 <li>Fade in: <b>0</b>
8430 <li>Fade out: <b>0</b>
8431 <li>Color: <b>white</b>
8432 <li>Outline color: <b>black</b>
8433 <li>Drop Shadow or outline: <b>use either to improve contrast but not both</b>
8434 </ul>
8435
8436    <p>Don't waste the audience's time with fading &amp; crawls.  Use crawls only
8437 if there's too much text to fit on the screen.  The title should be
8438 legible enough to take the least amount of time to read.  You're
8439 supposed to show the story, not write it.  If they wanted to read a
8440 story, they would be reading a book instead of watching video.
8441
8442 <div class="node">
8443 <a name="VIDEO-SCOPE"></a>
8444 <p><hr>
8445 Previous:&nbsp;<a rel="previous" accesskey="p" href="#TITLER">TITLER</a>,
8446 Up:&nbsp;<a rel="up" accesskey="u" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>
8447
8448 </div>
8449
8450 <h3 class="section">18.27 VIDEO SCOPE</h3>
8451
8452 <p>The video scope plots two views of the image.  One view plots the
8453 intensity of each pixel against horizontal position.  They call this
8454 the WAVEFORM.  Another view translates hue to angle and saturation to
8455 radius for each pixel.  They call this the VECTORSCOPE.
8456
8457    <p>The vectorscope is actually very useful for determining if an image is
8458 saturated.  When adjusting saturation, it's important to watch the
8459 vectorscope to make sure pixels don't extend past the 100 radius.
8460
8461    <p>The waveform allows you to make sure image data extends from complete
8462 black to complete white while adjusting the brightness/contrast.
8463
8464    <p>Some thought is being given to having a video scope for recording.
8465 Unfortunately, this would require a lot of variations of the video
8466 scope for all the different video drivers.
8467
8468 <div class="node">
8469 <a name="PLUGIN-AUTHORING"></a>
8470 <p><hr>
8471 Next:&nbsp;<a rel="next" accesskey="n" href="#KEYBOARD-SHORTCUTS">KEYBOARD SHORTCUTS</a>,
8472 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SECRETS-OF-CINELERRA-EFFECTS">SECRETS OF CINELERRA EFFECTS</a>,
8473 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
8474
8475 </div>
8476
8477 <h2 class="chapter">19 PLUGIN AUTHORING</h2>
8478
8479 <p>The plugin API in Cinelerra dates back to 1997, before the LADSPA and
8480 before VST became popular.  It's fundamentally the same as it was in
8481 1997, with minor modifications to handle keyframes and GUI feedback.
8482 The GUI is not abstracted from the programmer.  This allows the
8483 programmer to use whatever toolkit they want and allows more
8484 flexibility in appearance but it costs more.
8485
8486    <p>There are several types of plugins, each with a common method of
8487 implementation and specific changes for that particular type.  The
8488 easiest way to implement a plugin is to take the simplest existing one
8489 out of the group and rename the symbols.
8490
8491 <ul class="menu">
8492 <li><a accesskey="1" href="#INTRODUCING-THE-PULL-METHOD">INTRODUCING THE PULL METHOD</a>:  The current paradigm for plugin writing
8493 <li><a accesskey="2" href="#COMMON-PLUGIN-FUNCTIONS">COMMON PLUGIN FUNCTIONS</a>:  What all effects have to do.
8494 <li><a accesskey="3" href="#REALTIME-PLUGINS">REALTIME PLUGINS</a>:  What realtime effects have to do.
8495 <li><a accesskey="4" href="#NONREALTIME-PLUGINS">NONREALTIME PLUGINS</a>:  What rendered effects have to do.
8496 <li><a accesskey="5" href="#AUDIO-PLUGINS">AUDIO PLUGINS</a>:  What audio effects have to do.
8497 <li><a accesskey="6" href="#VIDEO-PLUGINS">VIDEO PLUGINS</a>:  What video effects have to do.
8498 <li><a accesskey="7" href="#TRANSITION-PLUGINS">TRANSITION PLUGINS</a>:  What transitions have to do.
8499 <li><a accesskey="8" href="#PLUGIN-GUI_0027S-WHICH-UPDATE-DURING-PLAYBACK">PLUGIN GUI'S WHICH UPDATE DURING PLAYBACK</a>:  How to use currently playing data to draw the GUI.
8500 <li><a accesskey="9" href="#USING-OPENGL">USING OPENGL</a>:  How to use hardware to speed up operations.
8501 <li><a href="#PLUGIN-QUERIES">PLUGIN QUERIES</a>:  How plugins get information about the data to be processed.
8502 </ul>
8503
8504 <div class="node">
8505 <a name="INTRODUCING-THE-PULL-METHOD"></a>
8506 <p><hr>
8507 Next:&nbsp;<a rel="next" accesskey="n" href="#COMMON-PLUGIN-FUNCTIONS">COMMON PLUGIN FUNCTIONS</a>,
8508 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>
8509
8510 </div>
8511
8512 <h3 class="section">19.1 INTRODUCING THE PULL METHOD</h3>
8513
8514 <p>Originally plugins were designed with the push method.  The push method
8515 is intuitive and simple.  A source pushes data to a plugin, the plugin
8516 does math operations on it, and the plugin pushes it to a destination.
8517 For 6 years this was the way all realtime plugins were driven
8518 internally but it didn't allow you to reduce the rate of playback in
8519 realtime.  While plugins can still be designed as if they're pushing
8520 data, this is not the way they're processed internally anymore.
8521
8522    <p>The latest evolution in Cinelerra's plugin design is the pull method.
8523 The rendering pipeline starts at the final output and the final steps
8524 in the rendering pipeline are reading the data from disk.  Every step
8525 in the rendering chain involves requesting data from the previous
8526 step.  When the rendering pipleline eventually requests data from a
8527 plugin chain, each plugin requests data from the plugin before it.
8528
8529    <p>This is less intuitive than the push method but is much more powerful.
8530 Realtime plugins written using the pull method can change the rate data
8531 is presented to the viewer and the direction of playback.  The pull
8532 method allows plugins to take in data at a higher rate than they send
8533 it out.
8534
8535    <p>To get the power of rate independance, the pull method requires plugins
8536 to know more about the data than they needed to under the push method.
8537 Plugins need to know what rate the project is at, what rate their
8538 output is supposed to be at and what rate their input is supposed to be
8539 at.  These different data rates have to be correlated for a plugin to
8540 configure itself properly.
8541
8542    <p>Keyframes for a plugin are stored relative to the project frame rate.
8543 Queries from a plugin for for the current playback position are given
8544 relative to the project frame rate.  If the plugin's output was
8545 requested to be at twice the project frame rate, the positions need to
8546 be converted to the project rate for keyframes to match up.  Two
8547 classes of data rates were created to handle this problem.
8548
8549    <p>Rate conversions are done in terms of the <b>project rate</b> and the
8550 <b>requested rate</b>.  The project rate is identical for all plugins.  It
8551 is determined by the <b>settings-&gt;format</b> window.  The requested rate
8552 is determined by the downstream plugin requesting data from the current
8553 plugin.  The requested rate is arbitrary.  Exactly how to use these
8554 rates is described below.
8555
8556 <div class="node">
8557 <a name="COMMON-PLUGIN-FUNCTIONS"></a>
8558 <p><hr>
8559 Next:&nbsp;<a rel="next" accesskey="n" href="#REALTIME-PLUGINS">REALTIME PLUGINS</a>,
8560 Previous:&nbsp;<a rel="previous" accesskey="p" href="#INTRODUCING-THE-PULL-METHOD">INTRODUCING THE PULL METHOD</a>,
8561 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>
8562
8563 </div>
8564
8565 <h3 class="section">19.2 COMMON PLUGIN FUNCTIONS</h3>
8566
8567 <p>All plugins inherit from a derivative of PluginClient.  This
8568 PluginClient derivative implements most of the required methods in
8569 PluginClient, but users must still define methods for PluginClient.
8570 The most commonly used methods are predefined in macros to reduce the
8571 typing yet still allow flexibility.
8572
8573    <p>The files they include depend on the plugin type.  Audio plugins
8574 include <b>pluginaclient.h</b> and video plugins include
8575 <b>pluginvclient.h</b>.  They inherit <b>PluginAClient</b> and
8576 <b>PluginVClient</b> respectively.
8577
8578    <p>Cinelerra instantiates all plugins at least twice when they are used in
8579 a movie.  Once instance is the GUI.  The other instance is the signal
8580 processor.  User input, through a complicated sequence, is propogated
8581 from the GUI instance to the signal processor instance.  If the signal
8582 processor wants to alter the GUI, it propogates data back to the GUI
8583 instance.  There are utility functions for doing all this.
8584
8585    <p>All plugins define at least three objects:
8586
8587      <ul>
8588 <li>
8589 <b>Processing object</b> - Contains pointers to all the other objects and
8590 performs the signal processing.  This object contains a number of
8591 queries to identify itself and is the object you register to register
8592 the plugin.
8593
8594      <li>
8595 <b>User interface object</b> - This is a subclass of
8596 <b>PluginClientWindow</b>.  It shows data on the screen and collects
8597 parameters from the user.
8598
8599      <p>The window has pointers to a number of widgets, a few initialization
8600 methods, and a back pointer to the plugin's processing object.  The GUI
8601 uses Cinelerra's toolkit.  The plugin abstraction layer handles creating
8602 a thread for the GUI.
8603
8604      <li>
8605 <b>Configuration object</b> - This stores the user parameters and always
8606 needs interpolation, copying, and comparison functions.  Macros for the
8607 plugin client automatically call configuration methods to interpolate
8608 keyframes.
8609
8610    </ul>
8611
8612 <ul class="menu">
8613 <li><a accesskey="1" href="#THE-PROCESSING-OBJECT">THE PROCESSING OBJECT</a>
8614 <li><a accesskey="2" href="#THE-CONFIGURATION-OBJECT">THE CONFIGURATION OBJECT</a>
8615 <li><a accesskey="3" href="#THE-USER-INTERFACE-OBJECT">THE USER INTERFACE OBJECT</a>
8616 </ul>
8617
8618 <div class="node">
8619 <a name="THE-PROCESSING-OBJECT"></a>
8620 <p><hr>
8621 Next:&nbsp;<a rel="next" accesskey="n" href="#THE-CONFIGURATION-OBJECT">THE CONFIGURATION OBJECT</a>,
8622 Up:&nbsp;<a rel="up" accesskey="u" href="#COMMON-PLUGIN-FUNCTIONS">COMMON PLUGIN FUNCTIONS</a>
8623
8624 </div>
8625
8626 <h4 class="subsection">19.2.1 THE PROCESSING OBJECT</h4>
8627
8628 <p>Load up a simple plugin like gain to see what this object looks like.
8629 The processing object should inherit from the intended PluginClient
8630 derivative.  Its constructor should take a PluginServer argument.
8631
8632 <pre class="example">     MyPlugin(PluginServer *server);
8633 </pre>
8634    <p>In the implementation, the plugin must contain a registration line with
8635 the name of the processing object like
8636
8637 <pre class="example">     REGISTER_PLUGIN(MyPlugin)
8638 </pre>
8639    <p>Another function which is useful but not mandatory is
8640
8641 <pre class="example">     int is_multichannel();
8642 </pre>
8643    <p>It should return 1 if one instance of the plugin handles multiple
8644 tracks simultaneously or 0 if one instance of the plugin only handles
8645 one track.  The default is 0 if it is omitted.
8646
8647    <p>Multichannel plugins in their processing function should refer to a
8648 function called <b>PluginClient::get_total_buffers()</b> to determine the
8649 number of channels.
8650
8651    <p>To simplify the implementation of realtime plugins, a macro for
8652 commonly used members has been created for the class header, taking the
8653 configuration object and user interface thread object as arguments.
8654 The macro definitions apply mainly to realtime plugins and are not
8655 useful in nonrealtime plugins.  Fortunately, nonrealtime plugins are
8656 simpler.
8657
8658 <pre class="example">     PLUGIN_CLASS_MEMBERS(config_name, thread_name)
8659 </pre>
8660    <p>The commonly used members in PLUGIN_CLASS_MEMBERS are described below.
8661
8662      <ul>
8663 <li>int load_configuration();
8664
8665      <p>Loads the configuration based on surrounding keyframes and current
8666 position.  The class definition for load_configuration should contain
8667
8668      <pre class="example">          LOAD_CONFIGURATION_MACRO(plugin_class, config_class)
8669 </pre>
8670      <p>to implement the default behavior for load_configuration.  This stores
8671 whatever the current configuration is inside the plugin's configuration
8672 object and returns 1 if the new configuration differs from the previous
8673 configuration.  The return value of load_configuration is used by
8674 another commonly used function, update_gui to determine if the GUI really needs to be updated.
8675
8676      <p>The plugin's configuration object is always called <b>config</b> inside
8677 PLUGIN_CLASS_MEMBERS.
8678
8679      <li>VFrame* new_picon();
8680
8681      <p>Creates a picon for display in the resource window.  Use
8682
8683      <pre class="example">          #include "picon_png.h"
8684           NEW_PICON_MACRO(plugin_class)
8685 </pre>
8686      <p>to implement new_picon.  In addition, the user should create a
8687 <b>picon_png.h</b> header file from a PNG image using <b>pngtoh</b>.
8688 <b>pngtoh</b> is compiled in the <b>guicast/ARCH</b> directory.
8689
8690      <p>The source PNG image should be called picon.png and can be any format
8691 supported by PNG.
8692
8693      <li>char* plugin_title();
8694
8695      <p>Returns a text string identifying the plugin in the resource window.
8696 The string has to be unique.
8697
8698      <li>void update_gui();
8699
8700      <p>Should first load the configuration, test for a return of 1, and then
8701 redraw the GUI with the new parameters.  All the plugins using GuiCast
8702 have a format like
8703
8704      <pre class="example">          void MyPlugin::update_gui()
8705           {
8706                 if(thread)
8707                 {
8708                         if(load_configuration())
8709                         {
8710                                 thread-&gt;window-&gt;lock_window();
8711           // update widgets here
8712                                 thread-&gt;window-&gt;unlock_window();
8713                         }
8714                 }
8715           }
8716 </pre>
8717      <p>to handle concurrency and conditions of no GUI.
8718
8719    </ul>
8720
8721    <p>Important functions the processing object must define are the
8722 functions which load and save configuration data from keyframes.  These
8723 functions are called by the macros so all you need to worry about is
8724 accessing the keyframe data.
8725
8726 <pre class="example">     void save_data(KeyFrame *keyframe);
8727      void read_data(KeyFrame *keyframe);
8728 </pre>
8729    <p>The read data functions are only used in realtime plugins.  The read
8730 data functions translate the plugin configuration between the KeyFrame
8731 argument and the configuration object for the plugin.  The keyframes
8732 are stored on the timeline and can change for every project.
8733
8734    <p>Use an object called <b>FileXML</b> to do the translation and some
8735 specific commands to get the data out of the KeyFrame argument.  See
8736 any existing plugin to see the usage of KeyFrame and FileXML.
8737
8738 <pre class="example">     int load_defaults();
8739      int save_defaults();
8740 </pre>
8741    <p>The load defaults functions are used in realtime and non-realtime
8742 plugins.  The load defaults functions translate the plugin
8743 configuration between a BC_Hash object and the plugin's
8744 configuration.  The BC_Hash object stores configurations in a discrete
8745 file on disk for each plugin but doesn't isolate different
8746 configurations for different projects.
8747
8748    <p>The function overriding <b>load_defaults</b> also needs to call <b>defaults
8749 = new BC_Hash(path);</b> with the configuration path.  See any existing
8750 plugin to see the usage of BC_Hash.   The function overriding
8751 <b>save_defaults</b> does not create <b>defaults</b>.
8752
8753    <p>Other standard members may be defined in the processing object,
8754 depending on the plugin type.
8755
8756 <div class="node">
8757 <a name="THE-CONFIGURATION-OBJECT"></a>
8758 <p><hr>
8759 Next:&nbsp;<a rel="next" accesskey="n" href="#THE-USER-INTERFACE-OBJECT">THE USER INTERFACE OBJECT</a>,
8760 Previous:&nbsp;<a rel="previous" accesskey="p" href="#THE-PROCESSING-OBJECT">THE PROCESSING OBJECT</a>,
8761 Up:&nbsp;<a rel="up" accesskey="u" href="#COMMON-PLUGIN-FUNCTIONS">COMMON PLUGIN FUNCTIONS</a>
8762
8763 </div>
8764
8765 <h4 class="subsection">19.2.2 THE CONFIGURATION OBJECT</h4>
8766
8767 <p>The configuration object is critical for GUI updates, signal
8768 processing, and default settings in realtime plugins.  Be aware it is
8769 not used in nonrealtime plugins.  The configuration object inherits
8770 from nothing and has no dependancies.  It's merely a class containing
8771 three functions and variables specific to the plugin's parameters.
8772
8773    <p>Usually the configuration object starts with the name of the plugin
8774 followed by Config.
8775
8776 <pre class="example">     class MyPluginConfig
8777      {
8778      public:
8779         MyPluginConfig();
8780 </pre>
8781    <p>Following the name of the configuration class, we put in three
8782 required functions and the configuration variables.
8783
8784 <pre class="example">           int equivalent(MyPluginConfig &amp;that);
8785         void copy_from(MyPluginConfig &amp;that);
8786         void interpolate(MyPluginConfig &amp;prev,
8787                 MyPluginConfig &amp;next,
8788                 int64_t prev_position,
8789                 int64_t next_position,
8790                 int64_t current_position);
8791
8792
8793
8794         float parameter1;
8795         float parameter2;
8796         int parameter3;
8797      };
8798
8799 </pre>
8800    <p>Now you must define the three functions.  <b>Equivalent</b> is called by
8801 LOAD_CONFIGURATION_MACRO to determine if the local configuration
8802 parameters are identical to the configuration parameters in the
8803 arguement.  If equivalent returns 0, the LOAD_CONFIGURATION_MACRO
8804 causes the GUI to redraw.  If equivalent returns 1, the
8805 LOAD_CONFIGURATION_MACRO doesn't redraw the GUI.
8806
8807    <p>Then there's <b>copy_from</b> which transfers the configuration values
8808 from the argument to the local variables.  This is once again used in
8809 LOAD_CONFIGURATION_MACRO to store configurations in temporaries.  Once
8810 LOAD_CONFIGURATION_MACRO has replicated the configuration, it loads a
8811 second configuration.  Then it interpolates the two configurations to
8812 get the current configuration.  The interpolation function performs the
8813 interpolation and stores the result in the local variables.
8814
8815    <p>Normally the interpolate function calculates a previous and next
8816 fraction, using the arguments.
8817
8818 <pre class="example">     void MyPluginConfig::interpolate(MyPluginConfig &amp;prev,
8819                 MyPluginConfig &amp;next,
8820                 int64_t prev_position,
8821                 int64_t next_position,
8822                 int64_t current_position)
8823      {
8824         double next_scale = (double)(current_position - prev_position) / (next_position - prev_position);
8825         double prev_scale = (double)(next_position - current_position) / (next_position - prev_position);
8826 </pre>
8827    <p>Then the fractions are applied to the previous and next configuration
8828 variables to yield the current values.
8829
8830 <pre class="example">
8831         this-&gt;parameter1 = (float)(prev.parameter1 * prev_scale + next.parameter1 * next_scale);
8832         this-&gt;parameter2 = (float)(prev.parameter2 * prev_scale + next.parameter2 * next_scale);
8833         this-&gt;parameter3 = (int)(prev.parameter3 * prev_scale + next.parameter3 * next_scale);
8834      }
8835
8836 </pre>
8837    <p>Alternatively you can copy the values from the previous configuration
8838 argument if no interpolation is desired.
8839
8840    <p>This usage of the configuration object is the same in audio and video
8841 plugins.  In video playback, the interpolation function is called for
8842 every frame, yielding smooth interpolation.  In audio playback, the
8843 interpolation function is called only once for every console fragment
8844 and once every time the insertion point moves.  This is good enough for
8845 updating the GUI while selecting regions on the timeline but it may not
8846 be accurate enough for really smooth rendering of the effect.
8847
8848    <p>For really smooth rendering of audio, you can still use
8849 load_configuration when updating the GUI.  For process_buffer; however,
8850 ignore load_configuration and write your own interpolation routine
8851 which loads all the keyframes in a console fragment and interpolates
8852 every sample.  This would be really slow and hard to debug, yielding
8853 improvement which may not be audible.  Then of course, every country
8854 has its own wierdos.
8855
8856    <p>An easier way to get smoother interpolation is to reduce the console
8857 fragment to 1 sample.  This would have to be rendered and played back
8858 with the console fragment back over 2048 of course.  The Linux sound
8859 drivers can't play fragments of 1 sample.
8860
8861 <div class="node">
8862 <a name="THE-USER-INTERFACE-OBJECT"></a>
8863 <p><hr>
8864 Previous:&nbsp;<a rel="previous" accesskey="p" href="#THE-CONFIGURATION-OBJECT">THE CONFIGURATION OBJECT</a>,
8865 Up:&nbsp;<a rel="up" accesskey="u" href="#COMMON-PLUGIN-FUNCTIONS">COMMON PLUGIN FUNCTIONS</a>
8866
8867 </div>
8868
8869 <h4 class="subsection">19.2.3 THE USER INTERFACE OBJECT</h4>
8870
8871 <p>The user interface object is derived from <b>PluginClientWindow</b>.  The
8872 user must call <b>NEW_WINDOW_MACRO</b> in the processing object to create
8873 the <b>PluginClientWindow</b>.  This system is used in realtime plugins but
8874 not in nonrealtime plugins.
8875
8876    <p>Nonrealtime plugins create and destroy their own GUI in their
8877 <b>get_parameters</b> function and there's no need for a
8878 <b>PluginClientWindow</b> subclass.
8879
8880    <p>Now the window class must be declared in the plugin header.  It's
8881 easiest to implement the window by copying an existing plugin and
8882 renaming the symbols.  The following is an outline of what happens.
8883 The plugin header must declare the window's constructor using the
8884 appropriate arguments.
8885
8886 <pre class="example">
8887      #include "guicast.h"
8888
8889      MyWindow::MyWindow(MyPlugin *plugin)
8890       : PluginClientWindow(plugin,
8891         440,
8892         500,
8893         440,
8894         500,
8895         0)
8896      {
8897
8898 </pre>
8899    <p>This becomes a window on the screen with the size given by the arguments
8900 to <b>PluginClientWindow</b>.
8901
8902    <p>It needs two methods
8903
8904 <pre class="example">           void create_objects();
8905 </pre>
8906    <p>and a back pointer to the plugin
8907
8908 <pre class="example">           MyPlugin *plugin;
8909 </pre>
8910    <p>The create_objects member puts widgets in the window according to
8911 GuiCast's syntax.  A pointer to each widget which you want to
8912 synchronize to a configuration parameter is stored in the window class.
8913 These are updated in the <b>update_gui</b> function you earlier defined for
8914 the plugin.  The widgets are usually derivatives of a GuiCast widget and
8915 they override functions in GuiCast to handle events.  Finally
8916 create_objects calls
8917
8918 <pre class="example">           show_window();
8919 </pre>
8920    <p>to make the window appear all at once.
8921
8922    <p>Every widget in the GUI needs to detect when its value changes.  In
8923 GuiCast the <b>handle_event</b> method is called whenever the value
8924 changes.  In <b>handle_event</b>, the widget then needs to call
8925 <b>plugin-&gt;send_configure_change()</b> to propogate the change to any
8926 copies of the plugin which are processing data.
8927
8928 <div class="node">
8929 <a name="REALTIME-PLUGINS"></a>
8930 <p><hr>
8931 Next:&nbsp;<a rel="next" accesskey="n" href="#NONREALTIME-PLUGINS">NONREALTIME PLUGINS</a>,
8932 Previous:&nbsp;<a rel="previous" accesskey="p" href="#COMMON-PLUGIN-FUNCTIONS">COMMON PLUGIN FUNCTIONS</a>,
8933 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>
8934
8935 </div>
8936
8937 <h3 class="section">19.3 REALTIME PLUGINS</h3>
8938
8939 <p>Realtime plugins should use PLUGIN_CLASS_MEMBERS to define the basic
8940 set of members in their headers.  All realtime plugins must define an
8941
8942 <pre class="example">     int is_realtime()
8943 </pre>
8944    <p>member returning 1.  This causes a number of methods to be called
8945 during live playback and the plugin to be usable on the timeline.
8946
8947    <p>Realtime plugins must override a member called
8948
8949 <pre class="example">     process_buffer
8950 </pre>
8951    <p>This function takes different arguments depending on if the plugin
8952 handles video or audio.  See an existing plugin to find out which usage
8953 applies.
8954
8955    <p>The main features of the process_buffer function are a buffer to store
8956 the output, the starting position of the output, and the requested
8957 output rate.  For audio, there's also a size argument for the number of
8958 samples.
8959
8960    <p>The starting position of the output buffer is the lowest numbered
8961 sample on the timeline if playback is forward and the highest numbered
8962 sample on the timeline if playback is reverse.  The direction of
8963 playback is determined by one of the plugin queries described below.
8964
8965    <p>The position and size arguments are all relative to the frame rate and
8966 sample rate passed to process_buffer.  This is the requested data rate
8967 and may not be the same as the project data rate.
8968
8969    <p>The process_realtime function should start by calling
8970 <b>load_configuration</b>.  The LOAD_CONFIGURATION_MACRO returns 1 if the
8971 configuration changed.
8972
8973    <p>After determining the plugin's configuration, input media has to be
8974 loaded for processing.  Call
8975
8976 <pre class="example">     read_frame(VFrame *buffer,
8977                 int channel,
8978                 int64_t start_position,
8979                 double frame_rate)
8980 </pre>
8981    <p>or
8982
8983 <pre class="example">     read_samples(double *buffer,
8984                 int channel,
8985                 int sample_rate,
8986                 int64_t start_position,
8987                 int64_t len)
8988 </pre>
8989    <p>to request input data from the object which comes before this plugin.
8990 The read function needs a buffer to store the input data in.  This can
8991 either be a temporary you create in the plugin or the output buffer
8992 supplied to process_buffer if you don't need a temporary.
8993
8994    <p>It also needs a set of position arguments to determine when you want to
8995 read the data from.  The start position, rate, and len passed to a read
8996 function need not be the same as the values recieved by the
8997 process_buffer function.  This way plugins can read data at a different
8998 rate than they output data.
8999
9000    <p>The channel argument is only meaningful if this is a multichannel
9001 plugin.  They need to read data for each track in the
9002 get_total_buffers() value and process all the tracks.  Single channel
9003 plugins should pass 0 for channel.
9004
9005    <p>Additional members are implemented to maintain configuration in
9006 realtime plugins.  Some of these are also needed in nonrealtime
9007 plugins.
9008
9009      <ul>
9010 <li>void read_data(KeyFrame *keyframe);
9011
9012      <p>Loads data from a keyframe into the plugin's configuration.  Inside the
9013 keyframe is an XML string.  It's most easily parsed by creating a
9014 <b>FileXML</b> object.  See an existing plugin to see how the read_data
9015 function is implemented.
9016
9017      <p>Read data loads data out of the XML object and stores values in the
9018 plugin's configuration object.  Since configuration objects vary from
9019 plugin to plugin, these functions can't be automated.
9020
9021      <li>void save_data(KeyFrame *keyframe);
9022
9023      <p>Saves data from the plugin's configuration to a keyframe.  Inside the
9024 keyframe you'll put an XML string which is normally created by a
9025 FileXML object.  See an existing plugin to see how the save_data
9026 function is implemented.
9027
9028      <p>Save data saves data from the plugin's configuration object into the
9029 XML object.
9030
9031      <li>int load_defaults();
9032
9033      <p>Another way the plugin gets parameters is from a defaults file.  The
9034 load and save defaults routines use a BC_Hash object to parse the
9035 defaults file.  The defaults object is created in <b>load_defaults</b> and
9036 destroyed in the plugin's destructor.  See an existing plugin to see
9037 how the BC_Hash object is used.
9038
9039      <li>int save_defaults();
9040
9041      <p>Saves the configuration in the defaults object.
9042
9043    </ul>
9044
9045 <div class="node">
9046 <a name="NONREALTIME-PLUGINS"></a>
9047 <p><hr>
9048 Next:&nbsp;<a rel="next" accesskey="n" href="#AUDIO-PLUGINS">AUDIO PLUGINS</a>,
9049 Previous:&nbsp;<a rel="previous" accesskey="p" href="#REALTIME-PLUGINS">REALTIME PLUGINS</a>,
9050 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>
9051
9052 </div>
9053
9054 <h3 class="section">19.4 NONREALTIME PLUGINS</h3>
9055
9056 <p>Some references for non-realtime plugins are <b>Normalize</b> for audio
9057 and <b>Reframe</b> for video.
9058
9059    <p>Like realtime plugins, <b>load_defaults</b> and <b>save_defaults</b> must be
9060 implemented.  In nonrealtime plugins, these are not just used for
9061 default parameters but to transfer values from the user interface to
9062 the signal processor.  There doesn't need to be a configuration class
9063 in nonrealtime plugins.
9064
9065    <p>Unlike realtime plugins, the LOAD_CONFIGURATION_MACRO can't be used in
9066 the plugin header.  Instead, the following methods must be defined.
9067
9068    <p>The nonrealtime plugin should contain a pointer to a defaults object.
9069
9070 <pre class="example">
9071      BC_Hash *defaults;
9072
9073 </pre>
9074    <p>It should also have a pointer to a MainProgressBar.
9075
9076 <pre class="example">
9077      MainProgressBar *progress;
9078 </pre>
9079    <p>The progress pointer allows nonrealtime plugins to display their
9080 progress in Cinelerra's main window.
9081
9082    <p>The constructor for a nonrealtime plugin can't use
9083 PLUGIN_CONSTRUCTOR_MACRO but must call <b>load_defaults</b> directly.
9084
9085    <p>The destructor, likewise, must call <b>save_defaults</b> and <b>delete
9086 defaults</b> directly instead of PLUGIN_DESTRUCTOR_MACRO.
9087
9088      <ul>
9089 <li>VFrame* new_picon();
9090
9091      <p>char* plugin_title();
9092
9093      <p>The usage of these is the same as realtime plugins.
9094
9095      <li>int is_realtime();
9096
9097      <p>This function must return 0 to indicate a nonrealtime plugin.
9098
9099      <li>
9100 int get_parameters();
9101
9102      <p>Here, the user should create a GUI, wait for the user to hit an OK
9103 button or a cancel button, and store the parameters in plugin
9104 variables.  This routine must return 0 for success and 1 for failure.
9105 This way the user can cancel the effect from the GUI.
9106
9107      <p>Unlike the realtime plugin, this GUI need not run asynchronously of the
9108 plugin.  It should block the get_parameters function until the user
9109 selects OK or Cancel.
9110
9111      <li>int load_defaults();
9112
9113      <p>This should set the <b>defaults</b> variable to a new <b>Defaults</b> object
9114 and load parameters from the defaults object into plugin variables.
9115
9116      <li>int save_defaults();
9117
9118      <p>This should save plugin variables to the defaults object.  It should not
9119 create the defaults object.
9120
9121      <li>int start_loop();
9122
9123      <p>If <b>get_parameters</b> returned 0 for success, this is called once to
9124 give the plugin a chance to initialize processing.  The plugin should
9125 instantiate the progress object with a line like
9126
9127      <pre class="example">
9128           progress = start_progress("MyPlugin progress...",
9129                 PluginClient::get_total_len());
9130
9131 </pre>
9132      <p>The usage of <b>start_progress</b> depends on whether the plugin is
9133 multichannel or single channel.  If it's multichannel you always call
9134 start_progress.  If it's single channel, you first need to know whether
9135 the progress bar has already started in another instance of the plugin.
9136
9137      <p>If <b>PluginClient::interactive</b> is 1, you need to start the progress
9138 bar.  If it's 0, the progress bar has already been started.
9139
9140      <p>The PluginClient defines <b>get_total_len()</b> and <b>get_source_start()</b>
9141 to describe the timeline range to be processed.  The units are either
9142 samples or frames and in the project rate.
9143
9144      <li>int process_loop
9145
9146      <p>This is called repeatedly until the timeline range is processed.  It
9147 has either a samples or frames buffer for output and a reference to
9148 write_length to store the number of samples processed.  If this is an
9149 audio plugin, the user needs to call <b>get_buffer_size()</b> to know how
9150 many samples the output buffer can hold.
9151
9152      <p>The plugin must use <b>read_samples</b> or <b>read_frame</b> to read the
9153 input.  These functions are a bit different for a non realtime plugin
9154 than they are for a realtime plugin.
9155
9156      <p>They take a buffer and a position relative to the start of the
9157 timeline, in the timeline's rate.  Then you must process it and put the
9158 output in the buffer argument to process_loop.  write_length should
9159 contain the number of samples generated if it's audio.
9160
9161      <p>Finally, process_loop must test <b>PluginClient::interactive</b> and
9162 update the progress bar if it's 1.
9163
9164      <pre class="example">          progress-&gt;update(total_written);
9165 </pre>
9166      <p>returns 1 or 0 if the progress bar was cancelled.  If it's 1,
9167 process_loop should return 1 to indicate a cancellation.  In addition
9168 to progress bar cancellation, <b>process_loop</b> should return 1 when the
9169 entire timeline range is processed.
9170
9171      <li>int stop_loop();
9172
9173      <p>This is called after process_loop processes its last buffer.
9174
9175      <p>If PluginClient::is_interactive is 1, this should call
9176 <b>stop_progress</b> in the progress bar pointer and delete the pointer.
9177 Then it should delete any objects it created for processing in
9178 <b>start_loop</b>.
9179
9180    </ul>
9181
9182 <div class="node">
9183 <a name="AUDIO-PLUGINS"></a>
9184 <p><hr>
9185 Next:&nbsp;<a rel="next" accesskey="n" href="#VIDEO-PLUGINS">VIDEO PLUGINS</a>,
9186 Previous:&nbsp;<a rel="previous" accesskey="p" href="#NONREALTIME-PLUGINS">NONREALTIME PLUGINS</a>,
9187 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>
9188
9189 </div>
9190
9191 <h3 class="section">19.5 AUDIO PLUGINS</h3>
9192
9193 <p>The simplest audio plugin is Gain.  The processing object should
9194 include <b>pluginaclient.h</b> and inherit from <b>PluginAClient</b>.  Realtime audio plugins need to
9195 define
9196
9197 <pre class="example">     int process_buffer(int64_t size,
9198                 double **buffer,
9199                 int64_t start_position,
9200                 int sample_rate);
9201 </pre>
9202    <p>if it's multichannel or
9203
9204 <pre class="example">     int process_buffer(int64_t size,
9205                 double *buffer,
9206                 int64_t start_position,
9207                 int sample_rate);
9208 </pre>
9209    <p>if it's single channel.  These should return 0 on success and 1 on
9210 failure.  In the future, the return value may abort failed rendering.
9211
9212    <p>The processing function needs to request input samples with
9213
9214 <pre class="example">     int read_samples(double *buffer,
9215                 int channel,
9216                 int sample_rate,
9217                 int64_t start_position,
9218                 int64_t len);
9219 </pre>
9220    <p>It always returns 0.  The user may specify any desired sample rate and
9221 start position.
9222
9223    <p>Nonrealtime audio plugins need to define
9224
9225 <pre class="example">     int process_loop(double *buffer, int64_t &amp;write_length);
9226 </pre>
9227    <p>for single channel or
9228
9229 <pre class="example">     int process_loop(double **buffers, int64_t &amp;write_length);
9230 </pre>
9231    <p>for multi channel.  Non realtime plugins use a different set of
9232 read_samples functions to request input data.  These are fixed to the
9233 project sample rate.
9234
9235 <div class="node">
9236 <a name="VIDEO-PLUGINS"></a>
9237 <p><hr>
9238 Next:&nbsp;<a rel="next" accesskey="n" href="#TRANSITION-PLUGINS">TRANSITION PLUGINS</a>,
9239 Previous:&nbsp;<a rel="previous" accesskey="p" href="#AUDIO-PLUGINS">AUDIO PLUGINS</a>,
9240 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>
9241
9242 </div>
9243
9244 <h3 class="section">19.6 VIDEO PLUGINS</h3>
9245
9246 <p>The simplest video plugin is Flip.  The processing object should
9247 include <b>pluginvclient.h</b> and inherit from <b>PluginVClient</b>.
9248 Realtime video plugins need to define
9249
9250 <pre class="example">     int process_buffer(VFrame **frame,
9251         int64_t start_position,
9252         double frame_rate);
9253 </pre>
9254    <p>if it's multichannel or
9255
9256 <pre class="example">     int process_buffer(VFrame *frame,
9257         int64_t start_position,
9258         double frame_rate);
9259 </pre>
9260    <p>if it's single channel.
9261
9262    <p>The nonrealtime video plugins need to define
9263
9264 <pre class="example">     int process_loop(VFrame *buffer);
9265 </pre>
9266    <p>for single channel or
9267
9268 <pre class="example">     int process_loop(VFrame **buffers);
9269 </pre>
9270    <p>for multi channel.  The amount of frames generated in a single
9271 process_loop is always assumed to be 1, hence the lack of a
9272 write_length argument.  Returning 0 causes the rendering to continue.
9273 Returning 1 causes the rendering to abort.
9274
9275    <p>A set of read_frame functions exist for requesting input frames in
9276 non-realtime video plugins.  These are fixed to the project frame rate.
9277
9278 <div class="node">
9279 <a name="TRANSITION-PLUGINS"></a>
9280 <p><hr>
9281 Next:&nbsp;<a rel="next" accesskey="n" href="#PLUGIN-GUI_0027S-WHICH-UPDATE-DURING-PLAYBACK">PLUGIN GUI'S WHICH UPDATE DURING PLAYBACK</a>,
9282 Previous:&nbsp;<a rel="previous" accesskey="p" href="#VIDEO-PLUGINS">VIDEO PLUGINS</a>,
9283 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>
9284
9285 </div>
9286
9287 <h3 class="section">19.7 TRANSITION PLUGINS</h3>
9288
9289 <p>The simplest video transition is <b>wipe</b> and the simplest audio
9290 transition is <b>crossfade</b>.  These use a subset of the default class
9291 members of realtime plugins, but so far no analogue to
9292 PLUGIN_CLASS_MEMBERS has been done for transitions.
9293
9294    <p>The processing object for audio transitions still inherits from
9295 PluginAClient and for video transitions it still inherits from
9296 PluginVClient.
9297
9298    <p>Transitions may or may not have a GUI.  If they have a GUI, they must
9299 also manage a thread like realtime plugins.  Do this with the same
9300 PLUGIN_THREAD_OBJECT and PLUGIN_THREAD_HEADER macros as realtime
9301 plugins.  Since there is only one keyframe in a transition, you don't
9302 need to worry about updating the GUI from the processing object like
9303 you do in a realtime plugin.
9304
9305    <p>If the transition has a GUI, you can use PLUGIN_CONSTRUCTOR_MACRO and
9306 PLUGIN_DESTRUCTOR_MACRO to initialize the processing object.  You'll
9307 also need a BC_Hash object and a Thread object for these macros.
9308
9309    <p>Since the GUI is optional, overwrite a function called <b>uses_gui()</b>
9310 to signifiy whether or not the transition has a GUI.  Return 1 if it
9311 does and 0 if it doesn't.
9312
9313    <p>Transitions need a <b>load_defaults</b> and <b>save_defaults</b> function so
9314 the first time they're dropped on the timeline they'll have useful
9315 settings.
9316
9317    <p>A <b>read_data</b> and <b>save_data</b> function takes over after insertion
9318 to access data specific to each instance of the transition.
9319
9320    <p>The most important difference between transitions and realtime plugins
9321 is the addition of an <b>is_transition</b> method to the processing
9322 object.  <b>is_transition</b> should return 1 to signify the plugin is a
9323 transition.
9324
9325    <p>Transitions process data in a <b>process_realtime</b> function.
9326
9327 <pre class="example">     int process_realtime(VFrame *input,
9328                 VFrame *output);
9329 </pre>
9330    <pre class="example">     int process_realtime(int64_t size,
9331                 double *input_ptr,
9332                 double *output_ptr);
9333 </pre>
9334    <p>The input argument to process_realtime is the data for the next edit.
9335 The output argument to process_realtime is the data for the previous
9336 edit.
9337
9338    <p>Routines exist for determining where you are relative to the
9339 transition's start and end.
9340
9341      <ul>
9342 <li><b>PluginClient::get_source_position()</b> - returns the current
9343 position since the start of the transition of the lowest sample in the
9344 buffers.
9345
9346      <li><b>PluginClient::get_total_len()</b> - returns the integer length of
9347 the transition.  The units are either samples or frames, in the data
9348 rate requested by the first plugin.
9349
9350    </ul>
9351
9352    <p>Users should divide the source position by total length to get the
9353 fraction of the transition the current <b>process_realtime</b> function is
9354 at.
9355
9356    <p>Transitions run in the data rate requested by the first plugin in the
9357 track.  This may be different than the project data rate.  Since
9358 process_realtime lacks a rate argument, use <b>get_framerate()</b> or
9359 <b>get_samplerate</b> to get the requested rate.
9360
9361 <div class="node">
9362 <a name="PLUGIN-GUI'S-WHICH-UPDATE-DURING-PLAYBACK"></a>
9363 <a name="PLUGIN-GUI_0027S-WHICH-UPDATE-DURING-PLAYBACK"></a>
9364 <p><hr>
9365 Next:&nbsp;<a rel="next" accesskey="n" href="#USING-OPENGL">USING OPENGL</a>,
9366 Previous:&nbsp;<a rel="previous" accesskey="p" href="#TRANSITION-PLUGINS">TRANSITION PLUGINS</a>,
9367 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>
9368
9369 </div>
9370
9371 <h3 class="section">19.8 PLUGIN GUI'S WHICH UPDATE DURING PLAYBACK</h3>
9372
9373 <p>Effects like <b>Histogram</b> and <b>VideoScope</b> need to update the GUI
9374 during playback to display information about the signal.  This is
9375 achieved with the <b>send_render_gui</b> and <b>render_gui</b> methods.
9376 Normally in process_buffer, when the processing object wants to update
9377 the GUI it should call <b>send_render_gui</b>.  This should only be called
9378 in process_buffer.  Send_render_gui goes through a search and
9379 eventually calls <b>render_gui</b> in the GUI instance of the plugin.
9380
9381    <p>Render_gui should have a sequence like
9382
9383 <pre class="example">     void MyPlugin::render_gui(void *data)
9384      {
9385         if(thread)
9386         {
9387                 thread-&gt;window-&gt;lock_window();
9388
9389      // update GUI here
9390
9391                 thread-&gt;window-&gt;unlock_window();
9392         }
9393      }
9394
9395 </pre>
9396    <p>Send_render_gui and render_gui use one argument, a void pointer to
9397 transfer information from the processing object to the GUI.  The user
9398 should typecast this pointer into something useful.
9399
9400 <div class="node">
9401 <a name="PLUGIN-QUERIES"></a>
9402 <p><hr>
9403 Previous:&nbsp;<a rel="previous" accesskey="p" href="#USING-OPENGL">USING OPENGL</a>,
9404 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>
9405
9406 </div>
9407
9408 <h3 class="section">19.9 PLUGIN QUERIES</h3>
9409
9410 <p>There are several useful queries in PluginClient which can be accessed
9411 from the processing object.  Some of them have different meaning in
9412 realtime and non-realtime mode.  They all give information about the
9413 operating system or the project which can be used to improve the
9414 quality of the processing.
9415
9416 <ul class="menu">
9417 <li><a accesskey="1" href="#SYSTEM-QUERIES">SYSTEM QUERIES</a>:  Utilities for determining the system resources.
9418 <li><a accesskey="2" href="#TIMING-QUERIES">TIMING QUERIES</a>:  Utilities for performing time-dependant processing.
9419 </ul>
9420
9421 <div class="node">
9422 <a name="SYSTEM-QUERIES"></a>
9423 <p><hr>
9424 Next:&nbsp;<a rel="next" accesskey="n" href="#TIMING-QUERIES">TIMING QUERIES</a>,
9425 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-QUERIES">PLUGIN QUERIES</a>
9426
9427 </div>
9428
9429 <h4 class="subsection">19.9.1 SYSTEM QUERIES</h4>
9430
9431      <ul>
9432 <li>
9433 <b>get_interpolation_type()</b> returns the type of interpolation the user
9434 wants for all scaling operations.  This is a macro from
9435 overlayframe.inc.  It can be applied to any call to the
9436 <b>OverlayFrame</b> object.
9437
9438      <li>
9439 <b>get_project_smp()</b> Gives the number of CPU's on the system minus 1.
9440 If it's a uniprocessor it's 0.  If it's a dual processor, it's 1.  This
9441 number should be used to gain parallelism.
9442
9443      <li>
9444 <b>get_total_buffers()</b> Gives the number of tracks a multichannel
9445 plugin needs to process.
9446
9447 </ul>
9448
9449 <div class="node">
9450 <a name="TIMING-QUERIES"></a>
9451 <p><hr>
9452 Previous:&nbsp;<a rel="previous" accesskey="p" href="#SYSTEM-QUERIES">SYSTEM QUERIES</a>,
9453 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-QUERIES">PLUGIN QUERIES</a>
9454
9455 </div>
9456
9457 <h4 class="subsection">19.9.2 TIMING QUERIES</h4>
9458
9459 <p>There are two rates for media a realtime plugin has to be aware of: the
9460 project rate and the requested rate.  Functions are provided for
9461 getting the project and requested rate.  In addition, doing time
9462 dependant effects requires using several functions which tell where you
9463 are in the effect.
9464
9465      <ul>
9466 <li>
9467 <b>get_project_framerate()</b> Gives the frames per second of the video as
9468 defined by the project settings.
9469
9470      <li>
9471 <b>get_project_samplerate()</b> Gives the samples per second of the audio as
9472 defined by the project settings.
9473
9474      <li>
9475 <b>get_framerate()</b> Gives the frames per second requested by the plugin
9476 after this one.  This is the requested frame rate and is the same as
9477 the frame_rate argument to process_buffer.
9478
9479      <li>
9480 <b>get_samplerate()</b> Gives the samples per second requested by the plugin
9481 after this one.  This is the requested sample rate and is the same as
9482 the sample_rate argument to process_buffer.
9483
9484      <li>
9485 <b>get_total_len()</b> Gives the number of samples or frames in the
9486 range covered by the effect, relative to the requested data rate.
9487
9488      <li>
9489 <b>get_source_start()</b> For realtime plugins it gives the lowest sample
9490 or frame in the effect range in the requested data rate.  For
9491 nonrealtime plugins it's the start of the range of the timeline to
9492 process.
9493
9494      <li>
9495 <b>get_source_position()</b> For realtime plugins it's the lowest numbered
9496 sample in the requested region to process if playing forward and the
9497 highest numbered sample in the region if playing backward.  For video
9498 it's the start of the frame if playing forward and the end of the frame
9499 if playing in reverse.  The position is relative to the start of the
9500 EDL and in the requested data rate.
9501
9502      <p>For transitions this is always the lowest numbered sample of the region
9503 to process relative to the start of the transition.
9504
9505      <li>
9506 <b>get_direction()</b> Gives the direction of the current playback
9507 operation.  This is a macro defined in transportque.inc.  This is
9508 useful for calling read functions since the read functions position
9509 themselves at the start or end of the region to read, depending on the
9510 playback operation.
9511
9512      <li>
9513 <b>local_to_edl()</b>
9514
9515      <li>
9516 <b>edl_to_local()</b>
9517
9518      <p>These convert between the requested data rate and the project data
9519 rate.  They are used to convert keyframe positions into numbers which
9520 can be interpolated at the requested data rate.  The conversion is
9521 automatically based on frame rate or sample rate depending on the type
9522 of plugin.
9523
9524      <li><b>get_prev_keyframe(int64_t position, int is_local)</b>
9525
9526      <li><b>get_next_keyframe(int64_t position, int is_local)</b>
9527
9528      <p>These give the nearest keyframe before or after the position given.
9529 The macro defined version of load_configuration automatically retrieves
9530 the right keyframes but you may want to do this on your own.
9531
9532      <p>The position argument can be either in the project rate or the
9533 requested rate.  Set is_local to 1 if it's in the requested rate and 0
9534 if it's in the project rate.
9535
9536      <p>In each keyframe, another position value tells the keyframe's position
9537 relative to the start of the timeline and in the project rate.
9538
9539      <p>The only way to get smooth interpolation between keyframes is to
9540 convert the positions in the keyframe objects to the requested rate.
9541 Do this by using edl_to_local on the keyframe positions.
9542
9543    </ul>
9544
9545 <div class="node">
9546 <a name="USING-OPENGL"></a>
9547 <p><hr>
9548 Next:&nbsp;<a rel="next" accesskey="n" href="#PLUGIN-QUERIES">PLUGIN QUERIES</a>,
9549 Previous:&nbsp;<a rel="previous" accesskey="p" href="#PLUGIN-GUI_0027S-WHICH-UPDATE-DURING-PLAYBACK">PLUGIN GUI'S WHICH UPDATE DURING PLAYBACK</a>,
9550 Up:&nbsp;<a rel="up" accesskey="u" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>
9551
9552 </div>
9553
9554 <h3 class="section">19.10 USING OPENGL</h3>
9555
9556 <p>Realtime video plugins support OpenGL.  Using OpenGL to do plugin
9557 routines can speed up playback greatly since it does most of the work
9558 in hardware.  Unfortunately, every OpenGL routine needs a software
9559 counterpart for rendering, doubling the amount of software to
9560 maintain.  Fortunately, having an OpenGL routine means the software
9561 version doesn't need to be as optimized as it did when software was the
9562 only way.
9563
9564    <p>As always, the best way to design a first OpenGL plugin is to copy an
9565 existing one and alter it.  The <b>Brightness</b> plugin is a simple
9566 OpenGL plugin to copy.  There are 3 main points in OpenGL rendering and
9567 1 point for optimizing OpenGL rendering.
9568
9569 <ul class="menu">
9570 <li><a accesskey="1" href="#GETTING-OPENGL-DATA">GETTING OPENGL DATA</a>:  Getting video data in a form usable by OpenGL
9571 <li><a accesskey="2" href="#DRAWING-USING-OPENGL">DRAWING USING OPENGL</a>:  The method of drawing video in OpenGL
9572 <li><a accesskey="3" href="#USING-SHADERS">USING SHADERS</a>:  Routines to simplify shader usage
9573 <li><a accesskey="4" href="#AGGREGATING-PLUGINS">AGGREGATING PLUGINS</a>:  Combining OpenGL routines from different plugins into one.
9574 </ul>
9575
9576 <div class="node">
9577 <a name="GETTING-OPENGL-DATA"></a>
9578 <p><hr>
9579 Next:&nbsp;<a rel="next" accesskey="n" href="#DRAWING-USING-OPENGL">DRAWING USING OPENGL</a>,
9580 Up:&nbsp;<a rel="up" accesskey="u" href="#USING-OPENGL">USING OPENGL</a>
9581
9582 </div>
9583
9584 <h4 class="subsection">19.10.1 GETTING OPENGL DATA</h4>
9585
9586 <p>The first problem is getting OpenGL-enabled plugins to interact with
9587 software-only plugins.  To solve this, all the information required to
9588 do OpenGL playback is stored in the VFrame object which is passed to
9589 <b>process_buffer</b>.  To support 3D, the VFrame contains a PBuffer and a
9590 texture, in addition to VFrame's original rows.
9591
9592    <p>In OpenGL mode, VFrame has 3 states corresponding to the location of
9593 its video data.  The opengl state is recovered by calling
9594 <b>get_opengl_state</b> and is set by calling <b>set_opengl_state</b>.  The
9595 states are:
9596
9597      <ul>
9598 <li>
9599 <b>VFrame::RAM</b> - This means the video data is stored in the
9600 traditional row pointers.  It must be loaded into a texture before
9601 being drawn using OpenGL routines.
9602
9603      <li><b>VFrame::TEXTURE</b> - The video data is stored in texture
9604 memory.  It's ready to be drawn using OpenGL routines.
9605
9606      <li><b>VFrame::SCREEN</b> - The video data is stored in a frame buffer
9607 in the graphics card.  For plugins, the frame buffer is always a
9608 PBuffer.  The image on the frame buffer can't be replicated again
9609 unless it is read back into the texture and the opengl state is reset
9610 to TEXTURE.  The frame buffer is limited to 8 bits per channel.  If an
9611 OpenGL effect is used in a floating point project, it only retains 8
9612 bits.
9613
9614    </ul>
9615
9616    <p>In the plugin's <b>process_buffer</b> routine, there is normally a call to
9617 <b>read_frame</b> to get data from the previous plugin in the chain.
9618 <b>read_frame</b> takes a new parameter called <b>use_opengl</b>.
9619
9620    <p>The plugin passes 1 to <b>use_opengl</b> if it intends to handle the data
9621 using OpenGL.  It passes 0 to <b>use_opengl</b> if it can only handle the
9622 data using software.  The value of <b>use_opengl</b> is passed up the
9623 chain to ensure a plugin which only does software only gets the data in
9624 the row pointers.  If <b>use_opengl</b> is 0, the opengl state in VFrame
9625 is RAM.
9626
9627    <p>The plugin must not only know if it is software-only but if its output
9628 must be software only.  Call <b>get_use_opengl</b> to determine if the
9629 output can be handled by OpenGL.  If <b>get_use_opengl</b> returns 0, the
9630 plugin must pass 0 for <b>use_opengl</b> in <b>read_frame</b> and do its
9631 processing in software.  If <b>get_use_opengl</b> is 1, the plugin can
9632 decide based on its implementation whether to use OpenGL.
9633
9634    <p>The main problem with OpenGL is that all the gl... calls need to be run
9635 from the same thread.  To work around this, the plugin interface has
9636 routines for running OpenGL in a common thread.
9637
9638    <p><b>run_opengl</b> transfers control to the common OpenGL thread.  This is
9639 normally called by the plugin in <b>process_buffer</b> after it calls
9640 <b>read_frame</b> and only if <b>get_use_opengl</b> is 1.
9641
9642    <p>Through a series of indirections, <b>run_opengl</b> eventually transfers
9643 control to a virtual function called <b>handle_opengl</b>.
9644 <b>handle_opengl</b> must be overridden with a function to perform all the
9645 OpenGL routines.  The contents of <b>handle_opengl</b> must be enclosed in
9646 <b>#ifdef HAVE_GL</b> ... <b>#endif</b> to allow it to be compiled on systems
9647 with no graphics support, like render nodes.  The return value of
9648 <b>handle_opengl</b> is passed back from <b>run_opengl</b>.
9649
9650    <p><b>read_frame</b> can't be called from inside <b>handle_opengl</b>.  This
9651 would create a recursive lockup because it would cause other objects to
9652 call <b>run_opengl</b>.
9653
9654    <p>Once inside <b>handle_opengl</b>, the plugin has full usage of all the
9655 OpenGL features.  VFrame provides some functions to automate common
9656 OpenGL sequences.
9657
9658    <p>The VFrame argument to <b>process_buffer</b> is always available through
9659 the <b>get_output(int layer)</b> function.  If the plugin is multichannel,
9660 the layer argument retrieves a specific layer of the output buffers.
9661 The PBuffer of the output buffer is where the OpenGL output must go if
9662 any processing is done.
9663
9664 <div class="node">
9665 <a name="DRAWING-USING-OPENGL"></a>
9666 <p><hr>
9667 Next:&nbsp;<a rel="next" accesskey="n" href="#USING-SHADERS">USING SHADERS</a>,
9668 Previous:&nbsp;<a rel="previous" accesskey="p" href="#GETTING-OPENGL-DATA">GETTING OPENGL DATA</a>,
9669 Up:&nbsp;<a rel="up" accesskey="u" href="#USING-OPENGL">USING OPENGL</a>
9670
9671 </div>
9672
9673 <h4 class="subsection">19.10.2 DRAWING USING OPENGL</h4>
9674
9675 <p>The sequence of commands to draw on the output PBuffer stars with
9676 getting the video in a memory area where it can be recalled for
9677 drawing:
9678
9679 <pre class="example">     get_output()-&gt;to_texture();
9680      get_output()-&gt;enable_opengl();
9681 </pre>
9682    <p><b>to_texture</b> transfers the OpenGL data from wherever it is to the
9683 output's texture memory and sets the output state to TEXTURE.
9684
9685    <p><b>enable_opengl</b> makes the OpenGL context relative to the output's
9686 PBuffer.
9687
9688    <p>The next step is to draw the texture with some processing on the
9689 PBuffer.  The normal sequence of commands to draw a texture is:
9690
9691 <pre class="example">     get_output()-&gt;init_screen();
9692      get_output()-&gt;bind_texture(0);
9693      get_output()-&gt;draw_texture();
9694 </pre>
9695    <p><b>VFrame::init_screen</b> sets the OpenGL frustum and parameters to known
9696 values.
9697
9698    <p><b>VFrame::bind_texture(int texture_unit)</b> binds the texture to the given
9699 texture unit and enables it.
9700
9701    <p><b>VFrame::draw_texture()</b> calls the vertex functions to draw the
9702 texture normalized to the size of the PBuffer.  Copy this if you want
9703 custom vertices.
9704
9705    <p>The last step in the handle_opengl routine, after the texture has been
9706 drawn on the PBuffer, is to set the output's opengl state to SCREEN
9707 with a call to <b>VFrame::set_opengl_state</b>.  The plugin should not
9708 read back the frame buffer into a texture or row pointers if it has no
9709 further processing.  Plugins should only leave the output in the
9710 texture or RAM if its location results from normal processing.  They
9711 should set the opengl state to RAM or TEXTURE if they do.
9712
9713    <p><b>Colormodels in OpenGL</b>
9714
9715    <p>The colormodel exposed to OpenGL routines is always floating point since
9716 that is what OpenGL uses, but it may be YUV or RGB depending on the
9717 project settings.  If it's YUV, the U &amp; V are offset by 0.5 just like in
9718 software.  Passing YUV colormodels to plugins was necessary for speed.
9719 The other option was to convert YUV to RGB in the first step that needed
9720 OpenGL.  Every effect and rendering step would have needed a YUV to RGB
9721 routine.  With the YUV retained, only the final compositing step needs a
9722 YUV to RGB routine.
9723
9724    <p>The OpenGL mode differentiates between alpha &amp; flat colormodels even
9725 though OpenGL always has an alpha channel.  For RGB colormodels, you
9726 must multiply the alpha component by the RGB &amp; set the alpha component
9727 to 1 whenever the colormodel has no alpha to ensure consistency with the
9728 software mode.
9729
9730 <pre class="example">     Rout = Rin * Ain
9731      Gout = Gin * Ain
9732      Bout = Bin * Ain
9733      Aout = 1
9734 </pre>
9735    <p>For YUV colormodels, you must multiply the alpha using the following
9736 formula.
9737
9738 <pre class="example">     Yout = Yin * Ain
9739      Uout = Uin * Ain + 0.5 * (1 - Ain)
9740      Vout = Vin * Ain + 0.5 * (1 - Ain)
9741      Aout = 1
9742 </pre>
9743    <div class="node">
9744 <a name="USING-SHADERS"></a>
9745 <p><hr>
9746 Next:&nbsp;<a rel="next" accesskey="n" href="#AGGREGATING-PLUGINS">AGGREGATING PLUGINS</a>,
9747 Previous:&nbsp;<a rel="previous" accesskey="p" href="#DRAWING-USING-OPENGL">DRAWING USING OPENGL</a>,
9748 Up:&nbsp;<a rel="up" accesskey="u" href="#USING-OPENGL">USING OPENGL</a>
9749
9750 </div>
9751
9752 <h4 class="subsection">19.10.3 USING SHADERS</h4>
9753
9754 <p>Very few effects can do anything useful with just a straight drawing of
9755 the texture on the PBuffer.  It's also not easy to figure out exactly
9756 what math is being used by the different OpenGL blending macros.
9757 Normally you'll use shaders.  The shader is a C program which runs on
9758 the graphics card.  Since the graphics card is optimized for graphics,
9759 it can be much faster than running it on the CPU.
9760
9761    <p>Shaders are written in OpenGL Shading Language.  The shader source code
9762 is contained in a string.  The normal sequence for using a shader comes
9763 after a call to <b>enable_opengl</b>.
9764
9765 <pre class="example">     char *shader_source = "...";
9766      unsigned char shader_id = VFrame::make_shader(0, shader_source, 0);
9767      glUseProgram(shader_id);
9768      // Set uniform variables using glUniform commands
9769 </pre>
9770    <p>The compilation and linking step for shaders is encapsulated by the
9771 VFrame::make_shader command.  It returns a shader_id which can be
9772 passed to OpenGL functions.  The first and last arguments must always
9773 by 0.  And arbitrary number of source strings may be put between the
9774 0's.  The source strings are concatenated by make_shader into one huge
9775 shader source.  If multiple main functions are in the sources, the main
9776 functions are renamed and run in order.
9777
9778    <p>There are a number of useful macros for shaders in playback3d.h.  All
9779 the shaders so far have been fragment shaders.  After the shader is
9780 initialized, draw the texture starting from <b>init_screen</b>.  The
9781 shader program must be disabled with another call to
9782 <b>glUseProgram(0)</b> and 0 as the argument.
9783
9784    <p>The shader_id and source code is stored in memory as long as Cinelerra
9785 runs.  Future calls to make_shader with the same source code run much
9786 faster.
9787
9788 <div class="node">
9789 <a name="AGGREGATING-PLUGINS"></a>
9790 <p><hr>
9791 Previous:&nbsp;<a rel="previous" accesskey="p" href="#USING-SHADERS">USING SHADERS</a>,
9792 Up:&nbsp;<a rel="up" accesskey="u" href="#USING-OPENGL">USING OPENGL</a>
9793
9794 </div>
9795
9796 <h4 class="subsection">19.10.4 AGGREGATING PLUGINS</h4>
9797
9798 <p>Further speed improvements may be obtained by combining OpenGL routines
9799 from two plugins into a single handle_opengl function.  This is done
9800 when <b>Frame to Fields</b> and <b>RGB to 601</b> are attached in order.
9801 Aggregations of more than two plugins are possible but very hard to get
9802 working.  Aggregation is useful for OpenGL because each plugin must
9803 copy the video from a texture to a PBuffer.  In software there was no
9804 copy operation.
9805
9806    <p>In aggregation, one plugin processes everything from the other plugins
9807 and the other plugins fall through.  The fall through plugins must copy
9808 their parameters to the output buffer so they can be detected by the
9809 processing plugin.
9810
9811    <p>The VFrame used as the output buffer contains a parameter table for
9812 parameter passing between plugins and it's accessed with
9813 <b>get_output()-&gt;get_params()</b>.  Parameters are set and retrieved in
9814 the table with calls to <b>update</b> and <b>get</b> just like with defaults.
9815
9816    <p>The fall through plugins must determine if the processor plugin is
9817 attached with calls to <b>next_effect_is</b> and <b>prev_effect_is</b>.
9818 These take the name of the processor plugin as a string argument and
9819 return 1 if the next or previous plugin is the processor plugin.  If
9820 either returns 1, the fall through plugin must still call <b>read_frame</b> to
9821 propogate the data but return after that.
9822
9823    <p>The processor plugin must call <b>next_effect_is</b> and
9824 <b>prev_effect_is</b> to determine if it's aggregated with a fall through
9825 plugin.  If it is, it must perform the operations of the fall through
9826 plugin in its OpenGL routine.  The parameters for the the fall through
9827 plugin should be available by <b>get_output()-&gt;get_params()</b> if the
9828 fall through plugin set them.
9829
9830 <div class="node">
9831 <a name="KEYBOARD-SHORTCUTS"></a>
9832 <p><hr>
9833 Previous:&nbsp;<a rel="previous" accesskey="p" href="#PLUGIN-AUTHORING">PLUGIN AUTHORING</a>,
9834 Up:&nbsp;<a rel="up" accesskey="u" href="#Top">Top</a>
9835
9836 </div>
9837
9838 <h2 class="chapter">20 KEYBOARD SHORTCUTS</h2>
9839
9840 <p>Alex Ferrer started summarizing most of the keyboard shortcuts.  Most
9841 of the keys work without any modifier like shift or ctrl.  Most windows
9842 can be closed with a <b>Ctrl-w</b>.  Most operations can be cancelled with
9843 <b>ESC</b> and accepted with <b>Enter</b>.
9844
9845 <h3 class="section">20.1 PROGRAM WINDOW</h3>
9846
9847 <h4 class="subsection">20.1.1 Editing Media</h4>
9848
9849 <pre class="example">     z         Undo
9850      Shift Z   Re-Do
9851      x         Cut
9852      c         Copy
9853      v         Paste
9854      Del       Clear
9855      Shift Spc Paste Silence
9856      m         Mute region
9857      a         Select all
9858      shift + click   When done over an edit causes the highlighted selection to extend to the cursor position.
9859                      When done over the boundary of an effect causes the trim operation to apply to one effect.
9860 </pre>
9861 <h4 class="subsection">20.1.2 Editing Labels &amp; In/Out Points</h4>
9862
9863 <pre class="example">     [             Toggle In point
9864      ]             Toggle Out point
9865      l             Toggle label at current position
9866      Ctrl &lt;-       Go to Previous Label
9867      Ctrl -&gt;       Go to Next Label
9868 </pre>
9869 <h4 class="subsection">20.1.3 Navigation</h4>
9870
9871 <pre class="example">     Right arrow      Move right*
9872      Left arrow       Move left*
9873      Up arrow         Zoom out*
9874      Down arrow       Zoom in*
9875      Ctrl Up          Expand waveform amplitude
9876      Ctrl Dn          Shrink waveform amplitude
9877      Alt Up           Expand curve amplitude
9878      Alt Dn           Shrink curve amplitude
9879      f                Fit time displayed to selection
9880      Alt f            Fit curve amplitude to highlighted section of curves
9881      Alt Left         Move left one edit
9882      Alt Right        Move right one edit
9883      Page Up          Move up*
9884      Page Dn          Move down*
9885      Ctrl Page Up     Expand track height
9886      Ctrl Page Dn     Shrink track height
9887      Home             Go to beginning of timeline*
9888      End              Go to end of timeline*
9889
9890 </pre>
9891    <p>* You may have to click on the timeline to deactivate any text boxes or
9892 tumblers before these work.
9893
9894 <h4 class="subsection">20.1.4 File operations</h4>
9895
9896 <pre class="example">     n         New project
9897      o         Load Files
9898      s         Save Project
9899      r         Record
9900      Shift R   Render
9901      q         Quit
9902      Shift P   Preferences
9903      Shift B   Batch Render
9904      Shift F   Set Format
9905 </pre>
9906 <h4 class="subsection">20.1.5 Key Frame Editing</h4>
9907
9908 <pre class="example">
9909      Shift X    Cut keyframes
9910      Shift C    Copy keyframes
9911      Shift V    Paste keyframes
9912      Shift Del  Clear keyframes
9913      Alt c      Copy default keyframe
9914      Alt v      Paste default keyframe
9915
9916 </pre>
9917 <h4 class="subsection">20.1.6 Track Manipulation</h4>
9918
9919 <pre class="example">
9920      t          Add Audio Track
9921      u          Insert default Audio Transition
9922      Shift T    Add Video Track
9923      Shift U    Insert Default Video Transition
9924      d          Delete last Track
9925      Shift L    Loop playback
9926      Tab        Toggle single track arming status
9927      Shift-Tab  Toggle every other track's arming status
9928
9929 </pre>
9930 <h4 class="subsection">20.1.7 What's drawn on the timeline</h4>
9931
9932 <pre class="example">
9933      1         Show titles
9934      2         Show transitions
9935      3         Fade keyframes
9936      4         Mute keyframes
9937      5         Mode keyframes
9938      6         Pan keyframes
9939      7         Camera keyframes
9940      8         Projector keyframes
9941      9         Plugin keyframes
9942      0         Mask keyframes
9943      -         Camera Zoom
9944      =         Projector Zoom
9945
9946 </pre>
9947 <h3 class="section">20.2 VIEWER &amp; COMPOSITOR WINDOWS</h3>
9948
9949 <pre class="example">
9950      x         Cut
9951      c         Copy
9952      v         Paste
9953      v         Splice
9954      b         Overwrite
9955      [         Toggle In point
9956      ]         Toggle Out point
9957      l         Toggle label at current position
9958      Ctrl &lt;-   Go to Previous Label
9959      Ctrl -&gt;   Go to Next Label
9960      Home      Go to beginning
9961      End       Go to end
9962      z         Undo
9963      Shift Z   Re-Do
9964      +         Zoom in
9965      -         Zoom out
9966
9967 </pre>
9968 <h3 class="section">20.3 PLAYBACK TRANSPORT</h3>
9969
9970 <p>Transport controls work in any window which has a playback transport.  They are
9971 accessed through the number pad with num lock disabled.
9972
9973 <pre class="example">     4 Frame back         5 Reverse Slow     6 Reverse      + Reverse Fast
9974      1 Frame Forward      2 Forward Slow     3 Play     Enter Fast Forward
9975      0 Stop
9976
9977 </pre>
9978    <p>[ Space bar ] is normal Play, Hitting any key twice is Pause.
9979
9980    <p>Hitting any transport control with CTRL down causes only the region
9981 between the in/out points to be played, if in/out points are defined.
9982
9983 <h3 class="section">20.4 RECORD WINDOW</h3>
9984
9985 <pre class="example">
9986      Space              Start and pause recording of the current batch
9987      l                  Toggle label at current position.
9988
9989 </pre>
9990 </body></html>
9991