add audio to proxy, and minor bug fixes
[goodguy/history.git] / cinelerra-5.1 / doc / cinelerra.texi
1 \input texinfo   @c -*-texinfo-*-
2
3
4
5 @setfilename cinelerra.info
6 @settitle SECRETS OF CINELERRA
7
8
9 @node TOP
10 @top
11
12 @center 
13
14 Version 4.1
15
16 by Adam Williams
17
18 Copyright @copyright{} 2011
19
20
21
22 @chapter SHORT CONTENTS
23
24 @menu
25 * ABOUT CINELERRA::          Cinelerra in brief.
26 * INSTALLATION::             Making Cinelerra work on your system.
27 * CONFIGURATION::            Adjusting the behavior of Cinelerra.
28 * CREATING A NEW PROJECT::   Creating a new project
29 * THE MAIN WINDOWS::         The most often used user interfaces.
30 * LOADING AND SAVING FILES:: Moving media between disk and Cinelerra.
31 * NAVIGATING THE PROJECT::   Moving around the media.
32 * EDITING::                  Moving the media in time.
33 * USING EFFECTS::            Altering the media.
34 * SETTING PROJECT ATTRIBUTES:: Changing the way the media is displayed.
35 * COMPOSITING::              Overlaying different sources of video.
36 * KEYFRAMES::                Making effects change over time.
37 * CAPTURING MEDIA::          Moving media from the real world to disk.
38 * IMPROVING PERFORMANCE::    Making Cinelerra run better on Linux.
39 * TROUBLESHOOTING::          Problems with Cinelerra.
40 * SECRETS OF CINELERRA::     Unusual applications of Cinelerra to common problems.
41 * SECRETS OF CINELERRA EFFECTS::      Secrets of the more complicated effects.
42 * PLUGIN AUTHORING::         How to write new effects.
43 * KEYBOARD SHORTCUTS::       How to accelerate most commands with the keyboard.
44 @end menu
45
46
47
48 @contents
49
50
51
52
53
54
55
56 @node ABOUT CINELERRA
57 @chapter ABOUT CINELERRA
58
59 @b{BROADCAST 1.0}
60
61 In 1996 our first editor came out: Broadcast 1.0.  It was just a window
62 with a waveform in it, it could cut and paste stereo audio waveforms on
63 a UNIX box, except unlike other audio editors it could handle files up
64 to 2 gigabytes with only 64 megs of RAM.  That was a feature normally
65 only accessible to the highest end professional audio houses.
66
67
68 @b{BROADCAST 2.0}
69
70 In 1997 Broadcast 1.0 was replaced by Broadcast 2.0.  This time the
71 window had a menubar, patchbay, console, and transport control. 
72 Broadcast 2.0 still only handled audio but this time it handled
73 unlimited tracks, and it could perform effects on audio and save the
74 resulting waveform to disk.  More notably a few effects could be
75 performed as the audio was playing back, in realtime.  A user could mix
76 unlimited numbers of tracks, adjust fade, pan, and EQ, and hear the
77 result instantly.   Amazingly this real time tweeking is still
78 unavailable on most audio programs.
79
80 @b{BROADCAST 2000}
81
82 But Broadcast 2.0 still didn't handle video and it wasn't very graceful
83 at audio either.  In 1999 video broke into the story with Broadcast
84 2000.  This iteration of the Broadcast series could do wonders with
85 audio and offered a pretty good video feature set.  It could edit video
86 files up to 64 terabytes.  It could do everything Broadcast 2.1 did
87 with audio except now all effects for video and audio could be chained
88 and performed on the fly, with instant feedback as a user tweeked
89 parameters during playback.  Broadcast 2000 made it very easy to do a
90 lot of processing and editing on video and audio that would otherwise
91 involve many hours setting up command line sequences and writing to
92 disk. For a time it seemed as if the original dream of immersive movie
93 making for everyone regardless of income level had arrived.
94
95 @b{CINELERRA}
96
97
98 Later on Broadcast 2000 began to come short.  Its audio and video was
99 graceful if you knew how to use it efficiently, but quality issues and
100 new user interface techniques were emerging.  Broadcast 2000 kept the
101 audio interface from its ancestors, which didn't apply well to video. 
102 Users likewise were maturing.  No longer would it be sufficient to just
103 edit video on a UNIX box.  Most users expected on UNIX the same thing
104 they got in Win or Mac. In mid 2000 designs for a Broadcast 2000
105 replacement were drafted.  The Broadcast name was officially retired
106 from the series and the software would now be called Cinelerra. 
107 Cinelerra would allow users to configure certain effects in much less
108 time than required with Broadcast 2000.  It would begin to emulate some
109 of the features found in Win and Mac software while not attempting to
110 become a clone.  It's interface would be designed for video from the
111 ground up, while supplementing that with the Broadcast audio
112 interface.  As always, quality improvements would happen.
113
114 @b{LINUX DERIVATIVES}
115
116 Linux became more and more fragmented after corporations adopted it. 
117 Threading once worked the same on all derivatives.  Today there are more
118 threading models than days of the week.  We try to focus on 1 of the
119 most popular Linux derivatives at any moment.  The threading model is
120 ported to that Linux derivative shortly before a release, but Linux
121 derivatives quickly evolve to new threading models and everything
122 breaks.
123
124 Also, there is no consistent behaviour for sound and video drivers.  The
125 situation with video capture has improved in that modern video sources
126 can all be mounted like disk drives.  The audio capture drivers have
127 been a bit more reliable.
128
129
130
131
132
133
134 @menu
135 * ABOUT THIS MANUAL::
136 @end menu
137
138 @node ABOUT THIS MANUAL
139 @section ABOUT THIS MANUAL
140
141 This is the original manual for Cinelerra.  This manual has been copied
142 and translated into many languages on many websites in varying degrees
143 of completeness.
144
145 Organizing information in the easiest manner for users to find out what
146 they need to know is sort of like cataloging the internet.  They've
147 been trying to get it right for 30 years and will probably keep trying
148 until the end of time.
149
150 There a lot of fragments of documentation scattered throughout the
151 internet about Cinelerra.  This document attempts to combine all the
152 pieces of information in one piece.
153
154 Like the operating system and compiler for a piece of software, the
155 document writing format is the most important thing in choosing our
156 document format.  We wanted a format which would be readable regardless
157 of corporate whims and fads.  A piece of software which compiles on GCC
158 and Linux will be usable as long as there are C compilers.  Documents
159 written in Texinfo will be readable as long as there's a C compiler.
160
161 After many years of searching for the perfect documentation format
162 we've arrived at TexInfo.  This format can be converted to HTML,
163 printed, automatically indexed, but most importantly is not bound to
164 any commercial word processor.
165
166 There are no screenshots in this manual.  Screenshots become obsolete
167 quickly and as a result confuse the users.  What looks one way in a
168 screenshot will always look different in the real program because the
169 real program and the manual are always evolving, never perfectly
170 synchronized.  It is true that manuals should have screenshots, but our
171 objective in omitting screenshots is to keep the software costs minimal
172 so you don't have to pay for it.  That includes additional labor to
173 synchronize the manual with the software.
174
175 In addition to telling you the basic editing features of Cinelerra this
176 manual covers tricks that won't be described anywhere else.  We're
177 going to try to come up with certain things you can do with Cinelerra
178 that you wouldn't think of on your own.
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196 @node INSTALLATION
197 @chapter INSTALLATION
198
199
200 The Cinelerra package contains Cinelerra and most of the libraries
201 needed to run it.  We try to include all the dependancies because of
202 the difficulty in tracking down the right versions.  Also included are
203 some utilities for handling files.  The following are the general
204 contents of all Cinelerra packages.
205
206 @itemize
207
208 @item
209
210 @b{Foreign language translations} - These go into /usr/share/locale.
211
212 @item
213
214 @b{Cinelerra executable} - This goes into /usr/bin
215
216 @item
217
218 @b{Cinelerra plugins} - These go into /usr/lib/cinelerra in 32 bit
219 systems and /usr/lib64/cinelerra in 64 bit systems.
220
221 @item
222
223 @b{soundtest} - Utility for determining sound card buffer size.
224
225 @item
226
227 @b{mplexlo} - Multiplexing of MPEG elementary streams without standards
228 conformance but more efficiently.
229
230 @item
231
232 @b{mpeg3cat} - Utility for reading an MPEG file from a certain standard
233 and outputting it to stdout.
234
235 @item
236
237 @b{mpeg3toc, mpeg3cat, mpeg3dump} - Utilities/ for indexing and reading MPEG files.
238
239 @item
240
241 @b{mpeg3peek} - Utility for displaying the byte offset of a frame in an
242 MPEG file.
243
244 @end itemize
245
246
247
248 @menu
249 * INSTALLING AN RPM::
250 * COMPILING FROM SCRATCH::
251 * RUNNING CINELERRA::
252 @end menu
253
254
255
256
257
258
259
260
261 @node INSTALLING AN RPM
262 @section INSTALLING AN RPM
263
264 Cinelerra is easiest installed by downloading an RPM and running
265
266 @example
267 rpm -U --force --nodeps hvirtual*.rpm
268 @end example
269
270 on a Fedora 4 system.
271
272 On systems which don't support RPM look for a utility called
273 @b{rpm2cpio}.  Download a Cinelerra RPM and from the /
274 directory run
275
276 @example
277 rpm2cpio hvirtual*.rpm | cpio -i --make-directories
278 @end example
279
280 This doesn't always work because there are many forks of the C library,
281 each incompatible with the others.  This is the biggest reason to
282 compile from scratch.
283
284
285
286
287
288
289
290 @node COMPILING FROM SCRATCH
291 @section COMPILING FROM SCRATCH
292
293 It should be noted that the compiler used in building Cinelerra
294 binaries is the free GNU compiler and very conservative optimization
295 flags.  Alternative optimization flags and compilers produce varying
296 results.  Compiling the source is hard and there's no warranty if the
297 source code fails to compile, but the method for compiling starts by
298 downloading the source code and decompressing.
299
300 The compilation is verified on a vanilla Fedora 4 installation,
301 workstation mode.  Fedora doesn't install a lot of dependancies like
302 @b{nasm} and @b{yasm}.  Yes, 3 assemblers are now required to assemble
303 x86 code.  Compiling the source is hard and there's no warranty if the
304 source code fails to compile, but the method for compiling starts by
305 downloading the source code and decompressing.
306
307 @example
308 tar jxf cinelerra*.tar.bz2
309 @end example
310
311
312 The compilation is verified on a Fedora 4 installation.  Fedora 4
313 doesn't install a lot of the reqiured compilers.  Mainly @b{nasm} and
314 @b{yasm}, 2 of the 3 assemblers.  These have to be installed manually
315 for compilation to succeed.
316
317 Enter the hvirtual directory
318
319 @example
320 cd cinelerra
321 @end example
322
323 Then run
324
325 @example
326 ./configure
327 @end example
328
329 This checks the build environment for the right tools and should give
330 you an error if a tool is missing.  Once that succeeds run
331
332 @example
333 make
334 @end example
335
336 The make procedure should run through all the directories and put
337 binaries in the @b{i686} or @b{x86_64} directories.  When NFS was
338 a lot faster, we compiled Alpha and i686 binaries in the same
339 filesystem with the objects in different subdirectories, so all the
340 binaries are still put in subdirectories.
341
342 A lot of libraries are included to get the version numbers right.  Some
343 of the libraries don't compile on SMP systems.  One solution is to
344 disable SMP when rebooting and reenable it when compilation is
345 finished.  Another solution is to rerun make over and over until it
346 gets through the offending libraries.
347
348
349 Once finished, make sure you are root and run
350
351 @example
352 make install
353 @end example
354
355 to install the binaries.  If installation fails it means something
356 failed to compile or you weren't root.  Run @b{make} again and watch
357 for errors.
358
359 Sometimes you'll want to run @b{make clean} if you're programming
360 something or the system libraries change.  In this case, you'll
361 probably need to run @b{configure} again because some libraries delete
362 their configuration files in @b{make clean}.
363
364 @node RUNNING CINELERRA
365 @section RUNNING CINELERRA
366
367
368 The simplest way to run Cinelerra is by running
369
370
371 @example
372 /usr/bin/cinelerra
373 @end example
374
375 This command hides a much more capable command line interface.  Run
376 @b{cinelerra -h} to get a listing of command line options.  The use of
377 these options is described in several sections.
378
379 For rendering from the command line @xref{RENDERING FILES}.
380
381
382
383
384
385
386
387
388
389
390
391
392 @node CONFIGURATION
393 @chapter CONFIGURATION
394
395
396 Because of the variety of uses, Cinelerra cannot be run optimally
397 without some intimate configuration for your specific needs. Very few
398 parameters are adjustible at compile time.  Runtime configuration is
399 the only option for most configuration because of the multitude of
400 parameters.
401
402 Here we discuss not only the configuration options but which of the
403 different API's in Linux are supported.
404
405 Go to @b{settings->preferences} and to see the options.
406
407
408 @menu
409 * ENVIRONMENT VARIABLES::  These environment variables are recognized by Cinelerra
410 * AUDIO DRIVERS::          Information about the audio drivers
411 * VIDEO DRIVERS::          Information about the video drivers
412 * PLAYBACK::               Configuring parameters related to playback.
413 * RECORDING::              Configuring parameters related to recording.
414 * PERFORMANCE::            Configuring parameters related to how fast things go.
415 * INTERFACE::              Configuring the user interface.
416 * ABOUT::                  Viewing information about the program.
417 @end menu
418
419
420 @node ENVIRONMENT VARIABLES
421 @section ENVIRONMENT VARIABLES
422
423 In UNIX derivatives, environment variables are global variables in the
424 shell which all applications can read.  They are set with a command
425 like @b{set VARIABLE=value}.  All the environment variables can be
426 viewed with a command like @b{env}.  Cinelerra recognizes the following
427 environment variables:
428
429 @itemize
430
431 @item @b{LADSPA_PATH} - If you want to use LADSPA plugins, this must be
432 defined: a colon separated list of directories to search for LADSPA
433 plugins.  These are not native Cinelerra plugins.  @xref{LADSPA
434 EFFECTS}.
435
436
437 @end itemize
438
439
440
441
442
443
444 @node AUDIO DRIVERS
445 @section AUDIO DRIVERS
446
447 The audio drivers are used for both recording and playback to get data
448 to and from the hardware.  Since the same drivers are used for both
449 recording and playback, their functionality is described here in a
450 separate section.
451
452
453
454
455 @menu
456 * COMMON SOUND DRIVER ATTRIBUTES:: Attributes used for more than one sound driver.
457 * OSS:: Notes about the OSS driver
458 * OSS Envy24:: Notes about the OSS driver for the Envy24 chip
459 * ALSA:: Notes about the ALSA driver
460 * ESOUND:: Notes about the ESound driver
461 * RAW 1394:: Notes about the Raw1394 driver
462 * DV 1394:: Notes about the DV1394 driver
463 * IEC 61883:: Notes about the IEC 61883 driver
464 @end menu
465
466 @node COMMON SOUND DRIVER ATTRIBUTES
467 @subsection COMMON SOUND DRIVER ATTRIBUTES
468
469 @itemize
470
471 @item
472 DEVICE PATH
473
474 Usually a file in the @b{/dev/} directory which controls the
475 device.
476
477 @item
478
479 BITS
480
481 The number of bits of precision Cinelerra should set the device for. 
482 This sometimes has a figuritive meaning.  Some sound drivers need to be
483 set to 32 bits to perform 24 bit playback and won't play anything when
484 set to 24 bits.  Some sound drivers need to be set to 24 bits for 24
485 bit playback.
486
487 @end itemize
488
489
490
491 @node OSS
492 @subsection OSS
493
494 This was the first Linux sound driver.  It had an open source
495 implementation and a commercial implementation with more sound cards
496 supported.  It was the standard sound driver up to linux 2.4.  It still
497 is the only sound driver which an i386 binary can use when running on
498 an x86_64 system.
499
500 @node OSS Envy24
501 @subsection OSS Envy24
502
503 The commercial version of OSS had a variant for 24 bit 96 Khz
504 soundcards.  This variant required significant changes to the way the
505 sound drivers were used, which is what the OSS Envy24 variant is for.
506
507
508 @node ALSA
509 @subsection ALSA
510
511 ALSA is the most common sound driver in Linux 2.6.  It supports the
512 most sound cards now.  It takes advantage of low latency features in
513 Linux 2.6 to get better performance than OSS had in 2.4 but roughly the
514 same performance that OSS had in 2.0.  Unfortunately ALSA is constantly
515 changing.  A program which works with it one day may not the next day. 
516 New wrappers are being developed on top of ALSA at such a pace, we plan
517 to support them at regular intervals, not at every new release of a new
518 wrapper.
519
520 ALSA is no longer portable between i386 and x86_64.  If an i386 binary
521 tries to play back on an x86_64 kernel it'll crash.  For this scenario,
522 use OSS.
523
524 @node ESOUND
525 @subsection ESOUND
526
527 ESOUND was a sound server that sat on top of OSS.  It was written for a
528 window manager called Enlightenment.  It supported a limited number of
529 bits and had high latency compared to modern times but multiplexed
530 multiple audio sources.  It's unknown whether it still works.
531
532 @node RAW 1394
533 @subsection RAW 1394
534
535 The first interface between linux software and firewire camcorders. 
536 This was the least reliable way to play audio to a camcorder.  It
537 consisted of a library on top of the kernel commands.
538
539 @node DV 1394
540 @subsection DV 1394
541
542 The second rewrite of DV camcorder support in Linux.  This was the most
543 reliable way to play audio to a camcorder.  This consisted of direct
544 kernel commands.
545
546 @node IEC 61883
547 @subsection IEC 61883
548
549 The third rewrite of DV camcorder support in Linux.  This is a library
550 on top of RAW 1394 which is a library on top of the kernel commands. 
551 It's less reliable than DV 1394 but more reliable than RAW 1394.  The
552 next rewrite ought to fix that.
553
554
555
556
557
558
559
560
561 @node VIDEO DRIVERS
562 @section VIDEO DRIVERS
563
564 The audio drivers are used for both recording and playback to get data
565 to and from the hardware.  Since the same drivers are used for both
566 recording and playback, their functionality is described here in a
567 separate section.
568
569
570 @menu
571 * COMMON VIDEO DRIVER ATTRIBUTES:: Parameters used by more than one driver.
572 * X11::
573 * X11-XV::
574 * X11-OPENGL::
575 * BUZ::
576 * RAW 1394 VIDEO PLAYBACK::
577 * DV 1394 VIDEO PLAYBACK::
578 * IEC 61883 VIDEO PLAYBACK::
579 @end menu
580
581 @node COMMON VIDEO DRIVER ATTRIBUTES
582 @subsection COMMON VIDEO DRIVER ATTRIBUTES
583
584
585 @itemize
586
587 @item
588
589 DISPLAY
590
591 The is intended for dual monitor
592 displays.  Depending on the value of Display, the Compositor window
593 will appear on a different monitor from the rest of the windows.
594
595 @item
596
597 DEVICE PATH
598
599 Usually a file in the @b{/dev/} directory
600 which controls the device.
601
602 @item
603
604 SWAP FIELDS
605
606 Make the even lines odd and the odd lines even
607 when sending to the device.  On an NTSC or 1080i monitor the fields may
608 need to be swapped to prevent jittery motion.
609
610 @item
611
612 OUTPUT CHANNEL
613
614 Devices with multiple outputs may need a
615 specific connector to send video on.
616
617 @item
618
619 PORT
620
621 The IEEE1394 standard specifies something known as the
622 @b{port}.  This is probably the firewire card number in the system
623 to use.
624
625 @item
626
627 CHANNEL
628
629 The IEEE1394 standard specifies something known as the
630 @b{channel}.  For DV cameras it's always @b{63}.
631
632 @end itemize
633
634 @node X11
635 @subsection X11
636
637 This was the first method of video playback on any UNIX system, valid
638 all the way until 1999.  It just writes the RGB triplet for each pixel
639 directly to the window.  It's the slowest playback method.  It's still
640 useful as a fallback when graphics hardware can't handle very large
641 frames.
642
643 @node X11-XV
644 @subsection X11-XV
645
646 This was the second big method of video playback in UNIX starting in
647 1999.  It converts YUV to RGB in hardware with scaling.  It's the
648 preferred playback method but can't handle large frame sizes.  The
649 maximum video size for XV is usually 1920x1080.
650
651
652 @node X11-OPENGL
653 @subsection X11-OPENGL
654
655 The most powerful video playback method is OpenGL.  With this driver,
656 most effects are done in hardware.  OpenGL allows video sizes up to the
657 maximum texture size, which is usually larger than what XV supports,
658 depending on the graphics driver.
659
660 OpenGL doesn't affect rendering.  It just accelerates playback.  OpenGL
661 relies on PBuffers and shaders to do video rendering.  The graphics
662 driver must support OpenGL 2 and Cinelerra needs to be explicitely
663 compiled with OpenGL 2 support.  This requires compiling it on a system
664 with the OpenGL 2 headers.
665
666 PBuffers are known to be fickle.  If the graphics card doesn't have
667 enough memory or doesn't have the right visuals, PBuffers won't work. 
668 Try seeking several frames or restarting Cinelerra if OpenGL doesn't
669 work.
670
671 Because of OpenGL limitations, X11-OpenGL processes everything in 8 bit
672 colormodels, although the difference between YUV and RGB is retained.
673
674 The @b{scaling equation} in Preferences is ignored by OpenGL.  OpenGL
675 always uses linear scaling.
676
677 Project and track sizes need to be multiples of 4 for OpenGL to work.  
678
679 To get the most acceleration, OpenGL-enabled effects must be placed
680 after software-only effects.  All rendering before the last
681 software-only effect is done in software.  The core Cinelerra
682 operations like camera and projector are of course OpenGL.
683
684
685
686 @node BUZ
687 @subsection BUZ
688
689 This is a method for playing motion JPEG-A files directly to a
690 composite analog signal.  It uses a popular hack of the Video4Linux 1
691 driver from 2000 to decompress JPEG in hardware.  Sadly, even though
692 analog output is largely obsolete, newer drivers have replaced BUZ.
693
694 @node RAW 1394 VIDEO PLAYBACK
695 @subsection RAW 1394 VIDEO PLAYBACK
696
697 The first interface between linux software and firewire camcorders. 
698 This was the least reliable way to play video to a camcorder.  It
699 consisted of a library on top of the kernel commands.
700
701
702 @node DV 1394 VIDEO PLAYBACK
703 @subsection DV 1394 VIDEO PLAYBACK
704
705 The second rewrite of DV camcorder support in Linux.  This was the most
706 reliable way to play video to a camcorder.  This consisted of direct
707 kernel commands.
708
709 @node IEC 61883 VIDEO PLAYBACK
710 @subsection IEC 61883 VIDEO PLAYBACK
711
712
713 The third rewrite of DV camcorder support in Linux.  This is a library
714 on top of RAW 1394 which is a library on top of the kernel commands. 
715 It's less reliable than DV 1394 but more reliable than RAW 1394.  The
716 next rewrite ought to fix that.
717
718
719
720
721
722
723
724 @node PLAYBACK
725 @section PLAYBACK
726
727
728
729 @menu
730 * AUDIO OUT::
731 * VIDEO OUT::
732 @end menu
733
734
735
736 @node AUDIO OUT
737 @subsection AUDIO OUT
738
739 These determine what happens when you play sound from the timeline.
740
741 @itemize 
742
743 @item
744 SAMPLES TO SEND TO CONSOLE:
745
746 For playing audio, small fragments of sound are read from disk and
747 processed in a virtual console sequentially.  A larger value here
748 causes more latency when you change mixing parameters but gives more
749 reliable playback.
750
751 Some sound drivers don't allow changing of the console fragment so
752 latency is unchanged no matter what this value is.
753
754 A good way of ensuring high quality playback was to read bigger
755 fragments from the disk and break them into smaller fragments for the
756 soundcard.  That changed when the virtual console moved from the push
757 model to the pull model.  Since different stages of the rendering
758 pipeline can change the rate of the incoming data, it would now be real
759 hard to disconnect size of the console fragments from the size of the
760 fragments read from disk.
761
762 @item
763
764 AUDIO OFFSET:
765
766 The ability to tell the exact playback position on Linux sound drivers
767 is pretty bad if it's provided at all.  Since this information is
768 required for proper video synchronization, it has to be accurate.  The
769 @b{AUDIO OFFSET} allows users to adjust the position returned by the
770 sound driver to reflect reality.  The audio offset doesn't affect the
771 audio playback or rendering at all.  It merely changes the
772 synchronization of video playback.
773
774 The easiest way to set the audio offset is to create a timeline with 1
775 video track and one audio track.  Expand the audio track and center the
776 audio pan.  The frame rate should be something over 24fps and the
777 sampling rate should be over 32000.  The frame size should be small
778 enough for your computer to render it at the full framerate.  Highlight
779 a region of the timeline starting at 10 seconds and ending at 20
780 seconds.  Drop a @b{gradient} effect on the video track and configure
781 it to be clearly visible.  Drop a @b{synthesizer} effect on the audio
782 and configure it to be clearly audible.
783
784 Play the timeline from 0 and watch to see if the gradient effect starts
785 exactly when the audio starts.  If it doesn't, expand the audio track
786 and adjust the nudge.  If the audio starts ahead of the video, decrease
787 the nudge value.  If the audio starts after the video, increase the
788 nudge value.  Once the tracks play back synchronized, copy the nudge
789 value to the @b{AUDIO OFFSET} value in preferences.
790
791 @b{Note:} if you change sound drivers or you change the value of @b{USE
792 SOFTWARE FOR POSITIONING INFORMATION}, you'll need to change the audio
793 offset because different sound drivers are unequally inaccurate.
794
795 @item
796
797 VIEW FOLLOWS PLAYBACK
798
799 Causes the timeline window to scroll when the playback cursor moves. 
800 This can bog down the X Server or cause the timeline window to lock up
801 for long periods of time while drawing the assetse.
802
803 @item
804 USE SOFTWARE FOR POSITIONING INFORMATION
805
806 Most soundcards and sound drivers don't give reliable information on
807 the number of samples the card has played. When playing video you need
808 this information for synchronization. This option causes the sound
809 driver to be ignored and a software timer to be used for
810 synchronization.
811
812 @item
813 AUDIO PLAYBACK IN REALTIME:
814
815 Back in the days when 150Mhz was the maximum, this allowed
816 uninterrupted playback on heavy loads.  It forces the audio playback to
817 the highest priority in the kernel.  Today it's most useful for
818 achieving very low latency between console tweeks and soundcard
819 output.  You must be root to get realtime priority.
820
821 @item
822 AUDIO DRIVER
823
824 There are many sound drivers for Linux.  This allows selecting one
825 sound driver and setting parameters specific to it.  The sound drivers
826 and their parameters are described in the sound driver section. 
827 @xref{AUDIO DRIVERS}.
828
829 @end itemize
830
831
832
833
834 @node VIDEO OUT
835 @subsection VIDEO OUT
836
837 These determine how video gets from the timeline to your eyes.
838
839 @itemize
840
841
842 @item PLAY EVERY FRAME
843
844 Causes every frame of video to be displayed even if it means falling
845 behind the audio.  This should always be on unless you use mostly
846 uncompressed codecs.  Most compressed codecs don't support frame
847 dropping anymore.
848
849
850
851 @item
852
853 FRAMERATE ACHIEVED
854
855 The number of frames per second being displayed during playback.  This
856 is only updated during playback.
857
858 @item DECODE FRAMES ASYNCHRONOUSLY
859
860 If you have lots of memory and more than one CPU, this option can
861 improve playback performance by decoding video on one CPU as fast as
862 possible while dedicating other CPU to displaying video only.  It
863 assumes all playback operations are forward and no frames are dropped. 
864 Operations involving reverse playback or frame dropping are negatively
865 impacted.
866
867 Since this option requires enourmous amounts of memory, it may crash if
868 the input frames are very large.
869
870
871 @item
872
873 SCALING EQUATION
874
875 When video playback involves any kind of scaling or translation, this
876 algorithm is used.  This doesn't affect 1:1 playback.
877
878 @itemize
879
880 @item
881 NEAREST NEIGHBOR ENLARGE AND REDUCE
882
883 lowest but fastest
884 quality.  Produces jagged edges and uneven motion.
885
886
887 @item
888
889 BICUBIC ENLARGE AND BILINEAR REDUCE
890
891 highest but slowest
892 quality.  For enlarging a bicubic interpolation is used, which blurs
893 slightly but doesn't reveal stair steps.  For reduction a bilinear
894 interpolation is used, which produces very sharp images and reduces
895 noise.  The bilinear reduced images can be sharpened with a sharpen
896 effect with less noise than a normal sized image.
897
898 @item
899
900 BILINEAR ENLARGE AND BILINEAR REDUCE
901
902 when slight enlargement
903 is needed a bilinear enlargement looks better than a bicubic
904 enlargement.
905
906 @end itemize
907
908
909 @item
910
911 PRELOAD BUFFER FOR QUICKTIME
912
913 The Quicktime/AVI decoder can handle DVD sources better when this is
914 around 10000000.  This reduces the amount of seeking required. 
915 Unfortunately when reading high bitrate sources from a hard drive, this
916 tends to slow it down.  For normal use this should be 0.
917
918
919 @item 
920
921 DVD SUBTITLE TO DISPLAY
922
923 DVD IFO files usually contain subtitle tracks.  These must be decoded
924 with by the MPEG decoder.  Select @b{Enable subtitles} to enable
925 subtitle decoding.  There are usually multiple subtitle tracks starting
926 from 0.  The subtitle track to be decoded for all MPEG streams goes in
927 the DVD subtitlee to display text box.  Go to the asset corresponding
928 to the MPEG file in the Resources window and right click.  Click on
929 Info.  The number of subtitle tracks is given at the bottom.
930
931
932 @item 
933
934 INTERPOLATE CR2 IMAGES
935
936 Enables interpolation of CR2 images.  This is required since the raw
937 image in a CR2 file is a bayer pattern.  The interpolation uses dcraw's
938 built-in interpolation and is very slow.  This operation can be
939 disabled and the @b{Interpolate Pixels} effect used instead for fast
940 previewing.
941
942
943 @item 
944
945 WHITE BALANCE CR2 IMAGES
946
947 This enables white balancing for CR2 images if interpolation is also
948 enabled.  It uses the camera's matrix which is contained in the CR2
949 file.  White balancing is not performed if interpolation is not
950 performed because white balancing needs a blending of all 3 primary
951 colors. 
952
953 Disabling white balancing is useful for operations involving dark frame
954 subtraction.  The dark frame and the long exposure need to have the
955 same color matrix.
956
957 If you disable @b{Interpolate CR2 Images} and use the @b{Interpolate
958 Pixels} effect, be aware the @b{Interpolate Pixels} effect always does
959 both interpolation and white balancing using the camera's matrix,
960 regardless of the settings in Preferences.  Dark frame subtraction
961 needs to be performed before @b{Interpolate Pixels}.
962
963 @item
964
965
966
967
968 VIDEO DRIVER
969
970 Normally video on the timeline goes to the compositor window during
971 continuous playback and when the insertion point is repositioned. 
972 Instead of sending video to the Compositor window the video driver can
973 be set to send video to another output device during continuous
974 playback.  This doesn't affect where video goes when the insertion
975 point is repositioned, however.
976
977 The video drivers and their parameters are described in the video
978 driver section.  @xref{VIDEO DRIVERS}.
979
980
981 @end itemize
982
983
984
985
986 @node RECORDING
987 @section RECORDING
988
989 @menu
990 * FILE FORMAT::
991 * AUDIO IN::
992 * VIDEO IN::
993 @end menu
994
995
996
997 The parameters here affect what happens when you go to
998 @b{File->Record...}.  The intention was to make @b{File->Record...} go
999 as fast as possible into the record monitoring window, without a
1000 lengthy dialog to configure the file format.  Instead the file format
1001 for recording is set here and it is applied to all recordings.  Also
1002 set here is the hardware for recording, since the hardware determines
1003 the supported file format in most cases.
1004
1005
1006 @node FILE FORMAT
1007 @subsection FILE FORMAT
1008
1009 This determines the output file format for recordings.  It depends
1010 heavily on the type of driver used.  The interface is the same as the
1011 rendering interface.  The @b{Record audio tracks} toggle must be
1012 enabled to record audio.  The @b{Record video tracks} toggle must be
1013 enabled to record video.  The wrench button left of each toggle opens a
1014 configuration dialog to set the codec corresponding to audio and
1015 video.  The audio and video is wrapped in a wrapper defined by the
1016 @b{File Format} menu.  Different wrappers may record audio only, video
1017 only, or both.
1018
1019 Some video drivers can only record to a certain wrapper.  DV, for
1020 example, can only record to Quicktime with DV as the video compression.
1021 If the video driver is changed, the file format may be updated to give
1022 the supported output.  If you change the file format to an unsupported
1023 format, it may not work with the video driver.
1024
1025
1026
1027 @node AUDIO IN
1028 @subsection AUDIO IN
1029
1030 These determine what happens when you record audio.
1031
1032 @itemize
1033 @item
1034
1035 RECORD DRIVER
1036
1037 This is used for recording audio in the Record window.  It may be
1038 shared with the Record Driver for video if the audio and video are
1039 wrapped in the same stream.  It takes variable parameters depending on
1040 the driver.  The parameters have the same meaning as they do for
1041 playback.
1042
1043 @itemize
1044 @item
1045
1046 DEVICE PATH
1047
1048 Usually a file in the @b{/dev/} directory which controls the
1049 device.
1050
1051 @item
1052
1053 BITS
1054
1055 The number of bits of precision Cinelerra should set the device for. 
1056 This sometimes has a figuritive meaning.  Some sound drivers need to be
1057 set to 32 bits to perform 24 bit recording and won't record anything
1058 when set to 24 bits.  Some sound drivers need to be set to 24 bits for
1059 24 bit recording.
1060
1061
1062
1063 @end itemize
1064
1065 @item
1066
1067 SAMPLES TO WRITE AT A TIME
1068
1069 Audio is first read in small fragments from the device.  Many small
1070 fragments are combined into a large fragment before writing to disk. 
1071 The disk writing process is done in a different thread.  The value here
1072 determines how large the combination of fragments is for each disk
1073 write.
1074
1075 @item
1076
1077 SAMPLE RATE FOR RECORDING
1078
1079 Regardless of what the project settings are.  This is the sample rate
1080 used for recording.  This should be the highest the audio device
1081 supports.
1082
1083 @end itemize
1084
1085 @node VIDEO IN
1086 @subsection VIDEO IN
1087
1088 These determine what happens when you record video.
1089
1090 @itemize
1091 @item
1092
1093 RECORD DRIVER
1094
1095 This is used for recording video in the Record window.  It may be
1096 shared with the Record Driver for audio if the audio and video are
1097 wrapped in the same stream.  It takes variable parameters depending on
1098 the driver.  The parameters have the same meaning as they do for
1099 playback.
1100
1101 @item
1102
1103 FRAMES TO RECORD TO DISK AT A TIME
1104
1105 Frames are recorded in a pipeline.  First frames are buffered in the
1106 device.  Then they're read into a larger buffer for writing to disk. 
1107 The disk writing is done in a different thread as the device reading. 
1108 For certain codecs the disk writing uses multiple processors.  This
1109 value determines how many frames are written to disk at a time.
1110
1111 @item
1112
1113 FRAMES TO BUFFER IN DEVICE
1114
1115 The number of frames to store in the device before reading.  This
1116 determines how much latency there can be in the system before frames
1117 are dropped.
1118
1119 @item
1120 USE SOFTWARE FOR POSITIONING INFORMATION
1121
1122 Video uses audio for
1123
1124
1125 synchronization but most soundcards don't give accurate position
1126 information.  This calculates an estimation of audio position in
1127 software instead of the hardware for synchronization.
1128
1129 @item
1130
1131 SYNC DRIVES AUTOMATICALLY
1132
1133 For high bitrate recording the drives may be fast enough to store the
1134 data but Linux may wait several minutes and stall as it writes several
1135 minutes of data at a time.  This forces Linux to flush its buffers
1136 every second instead of every few minutes and produce slightly better
1137 realtime behavior.
1138
1139 @item
1140
1141 SIZE OF CAPTURED FRAME
1142
1143 This is the size of the frames recorded.  It is independant of the
1144 project frame size because most video devices only record a fixed frame
1145 size.  If the frame size given here isn't supported by the device it
1146 might crash Cinelerra.
1147
1148 @item
1149 FRAME RATE FOR RECORDING
1150
1151 The frame rate recorded is different from the project settings.  This
1152 sets the recorded frame rate.
1153
1154 @end itemize
1155
1156
1157
1158
1159
1160
1161
1162
1163 @node PERFORMANCE
1164 @section PERFORMANCE
1165
1166
1167 You'll spend most of your time configuring this section.  The main
1168 focus of performance is rendering parameters not available in the
1169 rendering dialog.  
1170
1171
1172
1173
1174
1175 @itemize 
1176
1177 @item
1178 CACHE ITEMS
1179
1180
1181
1182 To speed up rendering, several assets are kept open simultaneously.
1183 This determines how many are kept open.  A number too large may exhaust
1184 your memory pretty fast and result in a crash.  A number too small may
1185 result in slow playback as assets need to be reopened more frequently.
1186
1187
1188 @item
1189
1190 SECONDS TO PREROLL RENDERS
1191
1192 Some effects need a certain amount of time to settle in.  This sets a
1193 number of seconds to render without writing to disk before the selected
1194 region is rendered.  When using the renderfarm you'll sometimes need to
1195 preroll to get seemless transitions between the jobs.  Every job in a
1196 renderfarm is prerolled by this value.  This does not affect background
1197 rendering, however.  Background rendering uses a different preroll
1198 value.
1199
1200 @item
1201
1202 FORCE SINGLE PROCESSOR USE
1203
1204 Cinelerra tries to use all processors on the system by default but
1205 sometimes you'll only want to use one processor, like in a renderfarm
1206 client.  This forces only one processer to be used.  The operating
1207 system, however, usually uses the second processor anyway for disk
1208 access so this option is really a 1.25 processor mode.  The value of
1209 this parameter is used in renderfarm clients.
1210
1211 @end itemize
1212
1213
1214 @menu
1215 * BACKGROUND RENDERING::
1216 * RENDERFARM::
1217 @end menu
1218
1219
1220 @node BACKGROUND RENDERING
1221 @subsection BACKGROUND RENDERING
1222
1223 Background rendering was originally concieved to allow HDTV effects to
1224 be displayed in realtime.  Background rendering causes temporary output
1225 to constantly be rendered while the timeline is being modified.  The
1226 temporary output is played during playack whenever possible.  It's very
1227 useful for transitions and previewing effects which are too slow to
1228 display in a reasonable amount of time.  If renderfarm is enabled, the
1229 renderfarm is used for background rendering, giving you the potential
1230 for realtime effects if enough network bandwidth and CPU nodes exist.
1231
1232 @itemize
1233
1234
1235
1236
1237
1238 @item
1239 FRAMES PER BACKGROUND RENDERING JOB
1240
1241 This only works if renderfarm is being used, otherwise background
1242 rendering creates a single job for the entire timeline.  The number of
1243 frames specified here is scaled to the relative CPU speed of rendering
1244 nodes and used in a single renderfarm job.  The optimum number is 10 -
1245 30 since network bandwidth is used to initialize each job.
1246
1247
1248
1249 @item
1250 FRAMES TO PREROLL BACKGROUND
1251
1252 This is the number of frames to render ahead of each background
1253 rendering job.  Background rendering is degraded when preroll is used
1254 since the jobs are small.  When using background rendering, this number
1255 is ideally 0.  Some effects may require 3 frames of preroll.
1256
1257
1258
1259
1260
1261 @item
1262 OUTPUT FOR BACKGROUND RENDERING
1263
1264 Background rendering generates a sequence of image files in a certain
1265 directory.  This parameter determines the filename prefix of the image
1266 files.  It should be on a fast disk, accessible to every node in the
1267 renderfarm by the same path.  Since hundreds of thousands of image
1268 files are usually created, @b{ls} commands won't work in the
1269 background rendering directory.  The @image{magnify} browse button for
1270 this option normally won't work either, but the @image{wrench}
1271 configuration button for this option works.
1272
1273 @item
1274 FILE FORMAT
1275
1276 The file format for background rendering has to be a sequence of
1277 images. The format of the image sequence determines the quality and
1278 speed of playback.  JPEG is good most of the time.
1279
1280
1281 @end itemize
1282
1283 @node RENDERFARM
1284 @subsection RENDERFARM
1285
1286 To use the renderfarm set these options.  Ignore them for a standalone
1287 system
1288
1289 @itemize
1290
1291 @item
1292
1293 USE RENDER FARM FOR RENDERING
1294
1295 When selected, all the
1296 @b{file->render} operations use the renderfarm.
1297
1298 @item
1299
1300 NODES
1301
1302 Displays all the nodes on the renderfarm and which ones are active. 
1303
1304 Nodes are added by entering the host name of the node, verifying the
1305 value of @b{port} and hitting @b{add node}.
1306
1307 Computer freaks may be better off editing the
1308 @b{~/.bcast/.Cinelerra_rc} file than this if they have hundreds of
1309 nodes.  Remember that .Cinelerra_rc is overwritten whenever a copy of
1310 Cinelerra exits.
1311
1312 Select the @b{ON} column to activate and deactivate nodes once they
1313 are created.
1314
1315 Nodes may be edited by highlighting a row and hitting @b{apply changes}.
1316
1317 @item
1318
1319 HOSTNAME
1320
1321 Edit the hostname of an existing node or enter the hostname of a new
1322 node here.
1323
1324 @item
1325
1326 PORT
1327
1328 Edit the port of an existing node or enter the port of a new node here.
1329
1330 @item
1331
1332 REPLACE NODE
1333
1334 When editing an existing node, hit this to commit the changes to
1335 @b{HOSTNAME} and @b{PORT}.  The changes won't be committed if you
1336 don't hit this button.
1337
1338 @item
1339
1340 ADD NODE
1341
1342 Create a new node with the @b{HOSTNAME} and @b{PORT} settings.
1343
1344 @item
1345
1346 DELETE NODE
1347
1348 Deletes whatever node is highlighted in the @b{NODES} list.
1349
1350 @item
1351
1352 SORT NODES
1353
1354 Sorts the @b{NODES} list based on the hostname.
1355
1356 @item
1357
1358 RESET RATES
1359
1360 This sets the framerate for all the nodes to 0.  Frame rates are used
1361 to scale job sizes based on CPU speed of the node.  Frame rates are
1362 only calculated when renderfarm is enabled.
1363
1364
1365
1366
1367
1368
1369 @item
1370
1371 TOTAL JOBS TO CREATE
1372
1373 Determines the number of jobs to dispatch to the renderfarm.  The more
1374 jobs you create, the more finely balanced the renderfarm becomes.
1375
1376 Determine the total jobs to create by multiplying the number of nodes
1377 including the master node by some number.  Multiply them by 1 to have
1378 one job dispatched for every node.  Multiply them by 3 to have 3 jobs
1379 dispatched for every node.  If you have 10 slave nodes and one master
1380 node, specify 33 to have a well balanced renderfarm.
1381
1382 @end itemize
1383
1384
1385
1386
1387
1388 @node INTERFACE
1389 @section INTERFACE
1390
1391 These parameters affect purely how the user interface works.
1392
1393 @itemize
1394
1395 @item
1396
1397 INDEX FILES GO HERE
1398
1399 Back in the days when 4 MB/sec was unearthly speed for a hard drive,
1400 index files were introduced to speed up drawing the audio tracks.  This
1401 option determines where index files are placed on the hard drive.
1402
1403
1404 @item
1405
1406 SIZE OF INDEX FILE
1407
1408 Determines the size of an index file. Larger index sizes allow smaller
1409 files to be drawn faster while slowing down the drawing of large files.
1410 Smaller index sizes allow large files to be drawn faster while slowing
1411 down small files.
1412
1413 @item
1414
1415 NUMBER OF INDEX FILES TO KEEP
1416
1417 To keep the index directory from becoming unruly, old index files are
1418 deleted. This determines the maximum number of index files to keep in
1419 the directory.
1420
1421 @item
1422
1423 DELETE ALL INDEXES
1424
1425 When you change the index size or you want to clean out excessive index
1426 files, this deletes all the index files.
1427
1428 @item
1429 USE HOURS:MINUTES:SECONDS.XXX
1430
1431 Various representations of time are given.  Select the most convenient
1432 one.  The time representation can also be changed by @b{CTRL}
1433 clicking on the time ruler.
1434
1435 @item
1436 USE THUMBNAILS
1437
1438 The Resource Window displays thumbnails of assets by default.  This can
1439 take a long time to set up.  This option disables the thumbnails.
1440
1441 @item
1442 CLICKING IN/OUT POINTS DOES WHAT
1443
1444 Cinelerra not only allows you to perform editing by dragging in/out
1445 points but also defines three seperate operations which occur when you
1446 drag an in/out point. For each mouse button you select the behavior in
1447 this window. The usage of each editing mode is described in editing.
1448
1449 @item
1450 MIN DB FOR METER
1451
1452 Some sound sources have a lower noise threshold than others. 
1453 Everything below the noise threshold is meaningless.  This option sets
1454 the meters to clip below a certain level.  Consumer soundcards usually
1455 bottom out at -65.  Professional soundcards bottom out at -90.
1456 @xref{SOUND LEVEL METERS}.
1457
1458 @item
1459 MAX DB FOR METER
1460
1461 This sets the maximum sound level represented by the sound meters.  No
1462 matter what this value is, no soundcard can play sound over 0 db.  This
1463 value is presented merely to show how far over the limit a sound wave
1464 is.
1465 @xref{SOUND LEVEL METERS}.
1466
1467 @item
1468 THEME
1469
1470 Cinelerra supports variable themes.  Select one here and restart
1471 Cinelerra to see it.
1472
1473 @end itemize
1474
1475
1476
1477 @node ABOUT
1478 @section ABOUT
1479
1480 This section gives you information about the copyright, the time of the
1481 current build, the lack of a warranty, and the versions of some of the
1482 libraries.  Be sure to agree to the terms of the lack of the warranty.
1483
1484
1485
1486
1487
1488
1489
1490 @node CREATING A NEW PROJECT
1491 @chapter CREATING A NEW PROJECT
1492
1493 There are 2 ways to create a new project: going to @b{File->New} or
1494 loading new files @xref{LOADING FILES}.  Once a new project is
1495 created, all the parameters can be changed later without creating a new
1496 project.  
1497
1498
1499 @menu
1500 * USING THE NEW PROJECT DIALOG::
1501 * CHANGING PARAMETERS AFTER LOADING::
1502 @end menu
1503
1504
1505
1506 @node USING THE NEW PROJECT DIALOG
1507 @section USING THE NEW PROJECT DIALOG
1508
1509 One way is to go to @b{File->New}.  This dialog contains the parameters
1510 for the new project.  The sections of the @b{New} dialog are described
1511 here:
1512
1513 @itemize
1514
1515 @item
1516
1517 @b{Presets} - Select an option from this menu to have all the project
1518 settings set to one of the known standards.
1519
1520 @item
1521 @b{Audio -> Tracks} - Sets the number of audio tracks the new project
1522 should have.  Tracks can be added or deleted later, but options are
1523 provided here for convenience.
1524
1525 @item
1526 @b{Audio -> Channels} - Sets the number of audio channels the new
1527 project should have.  The number of audio channels doesn't have to be
1528 the same as the number of tracks.
1529
1530 @item
1531 @b{Audio -> Samplerate} - Sets the samplerate of the audio.  The
1532 project samplerate doesn't have to be the same as the media sample rate
1533 that you load.  Media is resampled to match the project sample rate.
1534
1535 @item
1536 @b{Video -> Tracks} - Sets the number of video tracks the new project
1537 should have.  Tracks can be added or deleted later, but options are
1538 provided here for convenience.
1539
1540 @item
1541 @b{Video -> Framerate} - Sets the framerate of the video.  The project
1542 framerate doesn't have to be the same as the media frame rate that you
1543 load.  Media is reframed to match the project framerate.
1544
1545 @item
1546 @b{Video -> Canvas size} - Sets the size of the video output.  Each
1547 track also has its own frame size.  Initially the @b{New} dialog
1548 creates video tracks whose sizes all match the video output, but the
1549 video track sizes can be changed later without changing the video
1550 output.
1551
1552 @item
1553 @b{Video -> Aspect ratio} - Sets the aspect ratio.  The aspect ratio is
1554 applied to the video output.  The aspect ratio can be different than
1555 the number of horizontal pixels / the number of vertical pixels. 
1556 Setting a different aspect ratio than the number of pixels results in
1557 nonsquare pixels.
1558
1559 @item
1560 @b{Video -> Auto aspect ratio} - If this is checked, the @b{New} dialog
1561 always recalculates the @b{Aspect ratio} setting when the @b{Canvas
1562 size} is changed.  This ensures pixels are always square.
1563
1564 @item 
1565 @b{Video -> Color model} - This sets the color model video intermediates
1566 in the project will be stored in.  Color models are described in a 
1567 separate section @xref{COLOR MODEL}.
1568
1569 @end itemize
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583 @node CHANGING PARAMETERS AFTER LOADING
1584 @section CHANGING PARAMETERS AFTER LOADING
1585
1586 After a project is created, you have to use the set format dialog to
1587 change parameters without deleting the project.  Go to @b{Settings->Set
1588 format}.  
1589
1590 Most of the options are identical to the @b{File->New}
1591 options except the lack of a number of tracks to create and the
1592 addition of audio channel locations.
1593
1594 This section is discussed in @xref{SETTING PROJECT ATTRIBUTES}.
1595
1596
1597
1598
1599
1600
1601 @node THE MAIN WINDOWS
1602 @chapter THE MAIN WINDOWS
1603
1604 When Cinelerra first starts, you'll get four main windows.  Hitting
1605 @b{CTRL-w} in any window closes it.
1606
1607
1608 @menu
1609 * VIEWER::
1610 * COMPOSITOR::
1611 * PROGRAM::
1612 * RESOURCES::
1613 * SOUND LEVEL METERS::
1614 * OTHER WINDOWS::
1615 @end menu
1616
1617 @node VIEWER
1618 @section VIEWER
1619
1620
1621 In here you'll scrub around source media and clips, selecting regions
1622 to paste into the project.  Operations done in the viewer affect a
1623 temporary EDL or a clip but not the timeline.
1624
1625 @node COMPOSITOR
1626 @section COMPOSITOR
1627
1628
1629 This window displays the output of the timeline.  It's the interface
1630 for most compositing operations or operations that affect the
1631 appearance of the timeline output.  Operations done in the Compositor
1632 affect the timeline but don't affect clips.
1633
1634 The video output has several navigation functions.  The video output
1635 size is either locked to the window size or unlocked with scrollbars
1636 for navigation.  The video output can be zoomed in and out and panned. 
1637 Navigating the video output this way doesn't affect the rendered
1638 output, it just changes the point of view in the compositor window.
1639
1640 If it is unlocked from the window size, middle clicking and dragging
1641 anywhere in the video pans the point of view.
1642
1643 Hitting the + and - keys zooms in and out of the video output.
1644
1645 Underneath the video output are copies of many of the functions
1646 available in the main window.  In addition there is a
1647 @image{cwindow_zoom} zoom menu and a @image{cwindow_light} tally light.
1648
1649 The zoom menu jumps to all the possible zoom settings and, through the
1650 @b{Auto} option, locks the video to the window size.  The zoom menu
1651 does not affect the window size.
1652
1653 The tally light turns red when rendering is happening.  This is useful
1654 for knowing if the output is current.
1655
1656 Right clicking anywhere in the video output brings up a menu with all
1657 the zoom levels and some other options.  In this particular case the
1658 zoom levels resize the entire window and not just the video.  
1659
1660 The @b{reset camera} and @b{reset projector} options center the camera
1661 and projector @xref{COMPOSITING}.
1662
1663 The @b{Hide controls} option hides everything except the video.
1664
1665 On the left of the video output is a toolbar specific to the compositor
1666 window.  Here are the functions in the toolbar:
1667
1668 @menu
1669 * PROTECT VIDEO::
1670 * MAGNIFYING GLASS::
1671 * MASKS TOOL::
1672 * CAMERA::
1673 * PROJECTOR::
1674 * CROP TOOL::
1675 * EYEDROPPER::
1676 * TOOL INFO::
1677 * SAFE REGIONS TOOL::
1678 @end menu
1679
1680 @node PROTECT VIDEO
1681 @subsection PROTECT VIDEO
1682
1683 @image{protect}
1684
1685 This disables changes to the compositor output from clicks in it.  It
1686 is an extra layer on top of the track arming toggle to prevent
1687 unwanted changes.
1688
1689 @node MAGNIFYING GLASS
1690 @subsection MAGNIFYING GLASS
1691
1692 @image{magnify}
1693
1694 This zooms in and out of the compositor output without resizing the
1695 window.  If the video output is currently locked to the size of the
1696 window, clicking in it with the magnifying glass unlocks it and
1697 creates scrollbars for navigation.
1698
1699 Left clicking in the video zooms in.
1700
1701 Ctrl clicking in the video zooms out.
1702
1703 Rotating the wheel on a wheel mouse zooms in and out.
1704
1705
1706 @node MASKS TOOL
1707 @subsection MASKS TOOL
1708
1709 @image{mask}
1710
1711 This brings up the mask editing tool @xref{MASKS}.  Enable the
1712 @image{toolwindow} tool window to see options for this tool.
1713
1714 @node CAMERA
1715 @subsection CAMERA
1716
1717
1718 @image{camera}
1719
1720 This brings up the camera editing tool @xref{THE CAMERA AND
1721 PROJECTOR}.  Enable the @image{toolwindow} tool window to see options
1722 for this tool.
1723
1724 @node PROJECTOR
1725 @subsection PROJECTOR
1726
1727 @image{projector}
1728
1729 This brings up the projector editing tool @xref{THE CAMERA AND
1730 PROJECTOR}.  Enable the @image{toolwindow} tool window to see options
1731 for this tool.
1732
1733 @node CROP TOOL
1734 @subsection CROP TOOL
1735
1736 @image{crop}
1737
1738 This brings up the cropping tool @xref{CROPPING}.  The
1739 @image{toolwindow} tool window must be enabled to use this tool.
1740
1741 @node EYEDROPPER
1742 @subsection EYEDROPPER
1743
1744 @image{eyedrop}
1745
1746 This brings up the eyedropper.  The eyedropper detects whatever color
1747 is under it and stores it in a temporary area.  Enabling the
1748 @image{toolwindow} tool info shows the currently selected color.  Click
1749 anywhere in the video output to select the color at that point.
1750
1751 The eyedropper not only lets you see areas which are clipped, but its
1752 value can be applied to many effects.  Different effects handle the
1753 eyedropper differently.
1754
1755
1756 @node TOOL INFO
1757 @subsection TOOL INFO
1758
1759 @image{toolwindow}
1760
1761 This brings up a window containing options for the currently selected
1762 tool.
1763
1764
1765 @node SAFE REGIONS TOOL
1766 @subsection SAFE REGIONS TOOL
1767
1768 @image{titlesafe}
1769
1770 This draws the safe regions in the video output.  This doesn't affect
1771 the rendered output @xref{SAFE REGIONS}.
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783 @node PROGRAM
1784 @section PROGRAM
1785
1786
1787 This contains the timeline and the entry point for all menu driven
1788 operations.  The timeline consists of a vertical stack of tracks with
1789 horizontal representation of time.  This defines the output of
1790 rendering operations and what is saved when you save files.  Left of
1791 the timeline is the patchbay which contains options affecting each
1792 track.
1793
1794 Under the @b{Window} menu you'll find options affecting the main
1795 windows.  @b{default positions} repositions all the windows to a 4
1796 screen editing configuration.  On dual headed displays, the
1797 @b{default positions} operation fills only one monitor with windows.
1798
1799
1800 @node RESOURCES
1801 @section RESOURCES
1802
1803
1804 Effects, transitions, clips, and assets are accessed here.  Most of the
1805 resources are inserted into the project by dragging them out of the
1806 resource window.  Management of resource allocation is also performed
1807 here.
1808
1809 @node SOUND LEVEL METERS
1810 @section SOUND LEVEL METERS
1811
1812 An additional window, the @b{levels window} can be brought up from
1813 the @b{Window} menu.  The @b{levels} window displays the output
1814 audio levels after all mixing is done.
1815
1816 Sound level meters appear in many locations.  They can be toggled in
1817 the viewer and compositor windows with the @image{show_meters} level
1818 toggle. They appear in the patchbay when a track is expanded (@xref{THE
1819 PATCHBAY}.)  They appear in the recording monitor when audio is being
1820 recorded.  
1821
1822 The sound levels in the @b{levels window, compositor, and viewer}
1823 correspond to the final output levels before they are clipped to the
1824 soundcard range.  In the @b{record monitor} they are the input values
1825 from the sound card.  In the @b{patchbay} they are the sound levels for
1826 each track after all effects are processed and before downmixing for
1827 the output.
1828
1829 Most of the time, audio levels have numerical markings in DB but in the
1830 patchbay there isn't enough room.
1831
1832 The sound level is color coded as an extra means of determining the
1833 sound level.  Even without numerical markings, the sound level color
1834 can distinguish between several ranges and overload.  Look at the color
1835 codings in a meter with numerical markings to see what colors
1836 correspond to what sound level.  Then for meters in the patchbay in
1837 expanded audio tracks, use the color codings to see if it's overloading.
1838
1839 Be aware that sound levels in Cinelerra can go above 0DB.  This allows
1840 not only seeing if a track is overloading but how much information is
1841 being lost by the overloading.  Overloading by less than 3DB is usually
1842 acceptable.  While overloading is treated as positive numbers in
1843 Cinelerra, it is clipped to 0 when sent to a sound card or file.
1844
1845 The visible range of the sound level meters is configurable in
1846 @b{settings->preferences->interface} (@xref{INTERFACE}.)
1847
1848 @node OTHER WINDOWS
1849 @section OTHER WINDOWS
1850
1851 The @b{Overlays window} can be brought up from the @b{Window}
1852 menu.  This is a quick way to toggle what is drawn in the timeline. 
1853 Every option in the @b{View} menu is available here.
1854
1855
1856
1857
1858
1859
1860
1861 @node LOADING AND SAVING FILES
1862 @chapter LOADING AND SAVING FILES
1863
1864
1865 @menu
1866 * SUPPORTED FILE FORMATS::     What formats Cinelerra can import and export
1867 * LOADING FILES::              Loading all types of files
1868 * LOADING THE BACKUP::         Recovering the session from before a crash
1869 * SAVING FILES::               Saving edit decision lists
1870 * RENDERING FILES::            Saving media files
1871 @end menu
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882 @node SUPPORTED FILE FORMATS
1883 @section SUPPORTED FILE FORMATS
1884
1885 Here are most of the supported file formats and notes regarding their
1886 compression.  You may be able to load other formats not described here.
1887
1888 The format of the file affects what Cinelerra does with it.  Edit
1889 decision lists replace the project settings.  Formats which contain
1890 media but no edit decisions just add data to the tracks.  If your
1891 project sample rate is 48khz and you load a sound file with 96khz,
1892 you'll still be playing it at 48khz.   If you load an EDL file at 96khz
1893 and the current project sample rate is 48khz, you'll change it to
1894 96khz.
1895
1896 Some file formats are very slow to display on the timeline.  These
1897 usually have video which is highly compressed.  Drawing highly
1898 compressed video picons can be very slow.  Disable picon drawing for
1899 these files with the @b{draw media} toggle to speed up operations.
1900
1901
1902 @sp 1
1903 @image{track_attributes}
1904 @b{Track attributes}
1905
1906 Supported file formats are currently:
1907
1908 @itemize
1909 @item
1910 WAV
1911 @item
1912 FLAC
1913 @item
1914 PCM
1915 @item
1916 AIFF
1917 @item
1918 AC3 audio
1919 @end itemize
1920
1921 @menu
1922 * QUICKTIME::
1923 * MPEG-4 AUDIO::
1924 * IMAGE SEQUENCES::
1925 * STILL IMAGES::
1926 * AVI::
1927 * MPEG FILES CONTAINING VIDEO::
1928 * DVD MOVIES::
1929 * MPEG 1 AUDIO::
1930 * OGG THEORA/VORBIS::
1931 * EDIT DECISION LIST::
1932 @end menu
1933
1934
1935 @node QUICKTIME
1936 @subsection QUICKTIME
1937 Quicktime is not the standard for UNIX but we use it because it's well
1938 documented.  All of the Quicktime movies on the internet are
1939 compressed.  Cinelerra doesn't support most compressed Quicktime movies
1940 but does support some.  If it crashes when loading a Quicktime movie,
1941 that means the format probably wasn't supported.
1942
1943 @b{NOTES ON QUICKTIME ENCODING}
1944
1945 Here are some notes regarding making Quicktime movies in Cinelerra:
1946
1947 Quicktime is a wrapper for 2 codecs, a video codec and an audio codec. 
1948 The video and audio codecs are picked separately.  The preferred
1949 encoding for Quicktime output is MPEG-4 Video and MPEG-4 Audio.  This
1950 format plays in the commercial players for Windows and has good
1951 compression quality.  For better compression, use H-264 Video. 
1952 Unfortunately H-264 decoding is so slow it can't play very large frame
1953 sizes.
1954
1955 Cinelerra supports 2 nonstandard codecs: Dual MPEG-4 video and dual
1956 H.264 video.  These won't play in anything but Cinelerra and XMovie. 
1957 They are designed for movies where the frames have been divided into 2
1958 fields, each field displayed sequentially.  The dual codecs interleave
1959 2 video streams to improve efficiency without requiring major changes
1960 to the player.
1961
1962 @node MPEG-4 AUDIO
1963 @subsection MPEG-4 AUDIO
1964
1965 This is the same as Quicktime with MPEG-4 Audio as the audio codec.
1966
1967 @node IMAGE SEQUENCES
1968 @subsection IMAGE SEQUENCES
1969
1970
1971 Rendering an image sequence is not the same as rendering a single
1972 image.  When rendering an image sequence Cinelerra generates a table of
1973 contents file for the image sequence and makes a different image file
1974 for every timeline position.  The table of contents can be loaded
1975 instead of the individual images to get better performance.  To learn
1976 more about the different image formats supported in an image sequence,
1977 read about still images.
1978
1979
1980 @node STILL IMAGES
1981 @subsection STILL IMAGES
1982
1983
1984 Rendering a single image causes the image file to be overwritten for
1985 every timeline position.  No table of contents is created.  When
1986 loaded, the image takes up one frame in length and doesn't change the
1987 project attributes.
1988
1989 Several still image formats not normally found in other programs are
1990 described here.
1991
1992 @menu
1993 * OPEN EXR IMAGES::
1994 * RAW DIGITAL CAMERA IMAGES::
1995 @end menu
1996
1997 @node OPEN EXR IMAGES
1998 @subsubsection OPEN EXR IMAGES
1999
2000 You may not know about Open EXR.  This format stores floating point RGB
2001 images.  It also supports a small amount of compression.  Projects
2002 which render to EXR should be in a floating point color model to take
2003 advantage of it @xref{SETTING PROJECT ATTRIBUTES}.  Several compression
2004 options are available for EXR.
2005
2006 @itemize
2007
2008 @item
2009
2010 @b{PIZ} Lossless wavelet compression.  This is the best compression.
2011
2012 @item
2013 @b{ZIP} Lossless gzip algorithm.
2014
2015 @item
2016 @b{RLE} Lossless run length encoding.  This is the fastest and worst
2017 compression.
2018
2019 @item
2020 @b{PXR24} Lossy compression where the floating point numbers are
2021 converted to 24 bits and compressed with gzip.
2022
2023 @end itemize
2024
2025 Select @b{Use Alpha} if the project colormodel has an alpha channel and
2026 you want to retain it in the file.  Otherwise the primary colors are
2027 multiplied by the alpha channel.
2028
2029 @node RAW DIGITAL CAMERA IMAGES
2030 @subsubsection RAW DIGITAL CAMERA IMAGES
2031
2032 RAW digital camera images are a special kind of image file which
2033 Cinelerra only imports.  These must be processed in a floating point
2034 color space once they are on the timeline.  Raw images from Canon
2035 cameras are the only ones tested.  They need to have the @b{Linearize}
2036 effect applied to correct gamma.  Because raw images take a long time
2037 to interpolate, they are usually viewed first in a proxy file and then
2038 touched up.
2039
2040 First apply the Linearize effect to a track of raw images and set it to
2041 @b{automatic} with @b{0.6} gamma.  Then render the timeline to a
2042 Quicktime JPEG file.  Append the Quicktime JPEG file in a new track and
2043 disable playback of the old track.  Now the gamma corrected copy of
2044 each raw image can be previewed relatively fast in the same timeline
2045 position as the original image.
2046
2047
2048
2049 @node AVI
2050 @subsection AVI
2051
2052 AVI with assorted audio and video codecs.  Because AVI is so
2053 fragmented, your luck will vary.
2054
2055
2056 @node MPEG FILES CONTAINING VIDEO
2057 @subsection MPEG FILES CONTAINING VIDEO
2058
2059
2060 MPEG files containing video can be loaded directly into Cinelerra.  If
2061 the file is supported, a table of contents is built.  If the file is
2062 unsupported, it usually crashes or shows very short tracks. 
2063 Unfortunately, this method of loading MPEG files isn't good enough if
2064 you intend to use the files in a renderfarm.  
2065
2066 To use MPEG files in a renderfarm you need to run @b{mpeg3toc} to
2067 generate a table of contents for the file, then load the table of
2068 contents.  Mpeg3toc needs the absolute path of the MPEG file.  If you
2069 don't use an absolute path, it assumes the MPEG file is in the same
2070 directory that Cinelerra is run from.
2071
2072 MPEG streams are structured into multiple tracks.  Each track can be
2073 video or audio.  Each audio track can have 1-6 channels.  Cinelerra
2074 converts each channel of audio into a track.
2075
2076 @b{NOTES ON MPEG VIDEO ENCODING}
2077
2078 MPEG video encoding is done separately from MPEG audio encoding.  In
2079 MPEG video there are 2 colormodels.  The YUV 4:2:0 colormodel is
2080 encoded by a highly optimized version of mpeg2enc with presets for
2081 standard consumer electronics.  In the process of optimizing mpeg2enc,
2082 they got rid of YUV 4:2:2 encoding.  The YUV 4:2:2 colormodel is
2083 encoded by a less optimized version of mpeg2enc.
2084
2085 YUV 4:2:2 encoding was kept around because the NTSC version of DV video
2086 loses too much quality when transferred to YUV 4:2:0.  This DV video
2087 must be transferred to YUV 4:2:2.
2088
2089 When encoding YUV 4:2:0, the bitrate parameter changes meaning
2090 depending on whether the bitrate or quantization is fixed.  If the
2091 bitrate is fixed, it's the target bitrate.  If the quantization is
2092 fixed, it's the maximum bitrate allowed.  This is a quirk of the
2093 mpeg2enc version.
2094
2095 @node DVD MOVIES
2096 @subsection DVD MOVIES
2097
2098
2099 DVD's are spit into a number of programs, each identified by a unique
2100 @b{IFO} file.  If you want to load a DVD, find the corresponding
2101 @b{IFO} file for the program of interest.  Load the IFO file directly
2102 and a table of contents will be built.  Alternatively for renderfarm
2103 usage, a table of contents can be created separately.
2104
2105 Run
2106
2107 @example
2108 mpeg3toc -v /cdrom/video_ts/vts_01_0.ifo dvd.toc
2109 @end example
2110
2111 or something similar.  Then load @b{dvd.toc}.
2112
2113
2114
2115 @node MPEG 1 AUDIO
2116 @subsection MPEG 1 AUDIO
2117
2118 These are .mp2 and .mp3 files.  If fixed bitrate, they can be loaded
2119 directly with no table of contents.  Variable bitrate streams need to
2120 have a table of contents created with @b{mpeg3toc}.
2121
2122 @node OGG THEORA/VORBIS
2123 @subsection OGG THEORA/VORBIS
2124
2125
2126 The OGG format is an antiquated but supposedly unpatented way of
2127 compressing audio and video.  The quality isn't as good as H.264 or
2128 MPEG-4 Audio.  In reality, anyone with enough money and desire can find
2129 a patent violation so the justification for OGG is questionable.
2130
2131 @node EDIT DECISION LIST
2132 @subsection EDIT DECISION LIST
2133
2134
2135 Edit decision lists are generated by Cinelerra for storing projects. 
2136 They end in .xml.  They change project attributes when loaded.
2137
2138 Because edit decision lists consist of text, they can be edited in a
2139 text editor.
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158 @node LOADING FILES
2159 @section LOADING FILES
2160
2161 All data that you work with in Cinelerra is acquired either by
2162 @b{recording from a device} or by @b{loading from disk}.  This
2163 section describes loading.
2164
2165 The loading and playing of files is just as you would expect. Just go
2166 to @b{file->Load}, select a file for loading, and hit @b{ok}. Hit
2167 the forward play button and it should start playing, regardless of
2168 whether a progress bar has popped up.
2169
2170 Another way to load files is to pass the filenames as arguments on the
2171 command line.  This creates new tracks for every file and starts the
2172 program with all the arguments loaded.
2173
2174 If the file is a still image, the project's attributes are not changed
2175 and the first frame of the track becomes the image.  If the file has
2176 audio, Cinelerra may build an index file for it to speed up drawing. 
2177 You can edit and play the file while the index file is being built.
2178
2179 @menu
2180 * INSERTION STRATEGY::
2181 * LOADING MULTIPLE FILES::
2182 @end menu
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194 @node INSERTION STRATEGY
2195 @subsection INSERTION STRATEGY
2196
2197 Usually three things happen when you load a file.  First the existing
2198 project is cleared from the screen, second the project's attributes are
2199 changed to match the file's, and finally the new file's tracks are
2200 created in the timeline.
2201
2202 But Cinelerra lets you change what happens when you load a file.
2203
2204 In the file selection box there is a range of options for @b{Insertion
2205 strategy}.  Each of these options loads the file a different way.
2206
2207 @image{insertion_strategy}
2208
2209 @itemize
2210
2211
2212 @item
2213 @b{Replace current project}
2214 @image{loadmode_new}
2215
2216 All tracks in the current project are deleted and new tracks are
2217 created to match the source.  Project attributes are only changed when
2218 loading XML.  If multiple files are selected it adds new tracks for
2219 every file.
2220
2221 @item
2222 @b{Replace current project and concatenate tracks}
2223 @image{loadmode_newcat}
2224
2225 Same as replace current project except if multiple files are selected
2226 it concatenates the tracks of every file after the first.
2227
2228 @item
2229 @b{Append in new tracks}
2230 @image{loadmode_newtracks}
2231
2232 The current project is not deleted and new tracks are created for the
2233 source.
2234
2235 @item
2236 @b{Concatenate to existing tracks}
2237 @image{loadmode_cat}
2238
2239 The current project is not deleted and new files are concatenated to
2240 the existing tracks.
2241
2242 @item
2243 @b{Paste at insertion point}
2244 @image{loadmode_paste}
2245
2246 The file is pasted in like a normal paste operation.
2247
2248 @item
2249 @b{Create new resources only}
2250 @image{loadmode_resource}
2251
2252 The timeline is unchanged and new resources are created in the Resource
2253 Window.
2254
2255 @item
2256 @b{Nested EDL}
2257 @image{loadmode_nested}
2258
2259 If the file is an EDL, the output of the EDL is pasted in like a media
2260 file.  Nested EDLs have 1 video track & a number of audio tracks
2261 corresponding to the number of output channels.  They allow larger
2262 sequences composed of many smaller sequences, transitions to be applied
2263 to the output of another EDL, & global processing on the output of an
2264 EDL without having to manipulate each track.
2265
2266
2267
2268 @end itemize
2269
2270
2271 The insertion strategy is a recurring option in many of Cinelerra's
2272 functions.  In each place the options do the same thing.  With these
2273 options you can almost do all your editing by loading files.
2274
2275 If you load files by passing command line arguments to Cinelerra, the
2276 files are loaded with @b{Replace current project} rules.
2277
2278
2279
2280
2281
2282 @node LOADING MULTIPLE FILES
2283 @subsection LOADING MULTIPLE FILES
2284
2285 In the file selection box go to the list of files.  Select a file.  Go
2286 to another file and select it while holding down @b{CTRL}.  This
2287 selects one additional file.  Go to another file and select it while
2288 holding down @b{SHIFT}.  This selects every intervening file.  This
2289 behavior is available in most every list box.
2290
2291 Select a bunch of mp3 files and @b{Replace current project and
2292 concatenate tracks} in the insertion strategy to create a song
2293 playlist.
2294
2295
2296
2297
2298 @node LOADING THE BACKUP
2299 @section LOADING THE BACKUP
2300
2301 There is one special XML file on disk at all times.  After every
2302 editing operation Cinelerra saves the current project to a backup in
2303 @b{$HOME/.bcast/backup.xml}.  In the event of a crash go to
2304 @b{file->load backup} to load the backup.  It is important after a
2305 crash to reboot Cinelerra without performing any editing operations. 
2306 Loading the backup should be the first operation or you'll overwrite
2307 the backup.
2308
2309
2310 @node SAVING FILES
2311 @section SAVING FILES
2312
2313 When Cinelerra saves a file it saves an edit decision list of the
2314 current project but doesn't save any media.  Go to @b{File->save
2315 as...}.  Select a file to overwrite or enter a new file.  Cinelerra
2316 automatically concatenates @b{.xml} to the filename if no
2317 @b{.xml} extension is given.
2318
2319 The saved file contains all the project settings and locations of every
2320 edit but instead of media it contains pointers to the original media
2321 files on disk.
2322
2323 For each media file the XML file stores either an absolute path or just
2324 the relative path.  If the media is in the same directory as the XML
2325 file a relative path is saved.  If it's in a different directory an
2326 absolute path is saved.
2327
2328 In order to move XML files around without breaking the media linkages
2329 you either need to keep the media in the same directory as XML file
2330 forever or save the XML file in a different directory than the media
2331 and not move the media ever again.
2332
2333 If you want to create an audio playlist and burn it on CD-ROM, save the
2334 XML file in the same directory as the audio files and burn the entire
2335 directory.  This keeps the media paths relative.
2336
2337 XML files are useful for saving the current state before going to sleep
2338 and saving audio playlists but they're limited in that they're specific
2339 to Cinelerra.  You can't play XML files in a dedicated movie player. 
2340 Realtime effects in an XML file have to be resynthesized every time you
2341 play it back.  The XML file also requires you to maintain copies of all
2342 the source assets on hard drives, which can take up space and cost a
2343 lot of electricity to spin.  For a more persistent storage of the
2344 output there's rendering.
2345
2346
2347
2348
2349
2350
2351 @node RENDERING FILES
2352 @section RENDERING FILES
2353
2354 Rendering takes a section of the timeline, performs all the editing,
2355 effects and compositing, and stores it in a pure movie file.  You can
2356 then delete all the source assets, play the rendered file in a movie
2357 player, or bring it back into Cinelerra for more editing.  It's very
2358 difficult to retouch any editing decisions in the pure movie file,
2359 however, so keep the original assets and XML file around several days
2360 after you render it.
2361
2362 All rendering operations are based on a region of the timeline to be
2363 rendered.  You need to define this region on the timeline.  The
2364 navigation section describes methods of defining regions. 
2365 @xref{NAVIGATING THE PROJECT}.  The rendering functions define the
2366 region based on a set of rules.  When a region is highlighted or in/out
2367 points are set, the affected region is rendered.  When no region is
2368 highlighted, everything after the insertion point is rendered.  Merely
2369 by positioning the insertion point at the beginning of a track and
2370 unsetting all in/out points, the entire track is rendered.
2371
2372
2373
2374 @menu
2375 * SINGLE FILE RENDERING::      Rendering a single file
2376 * BATCH RENDERING::            Rendering several files unattended
2377 * THE RENDER FARM::            Rendering using many computers
2378 * COMMAND LINE RENDERING::     Rendering from the command line without a GUI
2379 @end menu
2380
2381
2382
2383 @node SINGLE FILE RENDERING
2384 @subsection SINGLE FILE RENDERING
2385
2386 The fastest way to get media to disk is to use the single file
2387 rendering function.
2388
2389 Go to @b{File->render} to bring up the render dialog.  Select the
2390 magnifying glass @image{magnify} to bring up a file selection dialog.  This determines
2391 the filename to write the rendered file to and the encoding parameters.
2392
2393 In the render dialog select a format from the @b{File Format} menu. 
2394 The format of the file determines whether you can render audio or video
2395 or both.  Select the @b{Render audio tracks} toggle to generate
2396 audio tracks and @b{Render video tracks} to generate video tracks.
2397
2398
2399 Select the wrench @image{wrench} next to each toggle to set compression
2400 parameters.  If the file format can't store audio or video the
2401 compression parameters will be blank.  If @b{Render audio tracks} or
2402 @b{Render video tracks} is selected and the file format doesn't
2403 support it, trying to render will pop up an error.
2404
2405 The @b{Create new file at each label} option causes a new file to be
2406 created when every label in the timeline is encountered.  This is
2407 useful for dividing long audio recordings into individual tracks.  When
2408 using the renderfarm, @b{Create new file at each label} causes one
2409 renderfarm job to be created at every label instead of using the
2410 internal load balancing algorithm to space jobs.
2411
2412 When @b{Create new file at each label} is selected, a new filename
2413 is created for every output file.  If the filename given in the render
2414 dialog has a 2 digit number in it, the 2 digit number is overwritten
2415 with a different incremental number for every output file.  If no 2
2416 digit number is given, Cinelerra automatically concatenates a number to
2417 the end of the given filename for every output file.
2418
2419 In the filename @b{/hmov/track01.wav} the @b{01} would be
2420 overwritten for every output file.  The filename
2421 @b{/hmov/track.wav}; however, would become @b{/hmov/track.wav001}
2422 and so on and so forth.  Filename regeneration is only used when either
2423 renderfarm mode is active or creating new files for every label is
2424 active.
2425
2426 Finally the render dialog lets you select an insertion mode.  The
2427 insertion modes are the same as with loading files.  In this case if
2428 you select @b{insert nothing} the file will be written out to disk
2429 without changing the current project.  For other insertion strategies
2430 be sure to prepare the timeline to have the output inserted at the
2431 right position before the rendering operation is finished. 
2432 @xref{EDITING}.  Editing describes how to cause output to be inserted
2433 at the right position.
2434
2435 It should be noted that even if you only have audio or only have video
2436 rendered, a @b{paste} insertion strategy will behave like a normal
2437 paste operation, erasing any selected region of the timeline and
2438 pasting just the data that was rendered.  If you render only audio and
2439 have some video tracks armed, the video tracks will get truncated while
2440 the audio output is pasted into the audio tracks.
2441
2442
2443
2444 @node BATCH RENDERING
2445 @subsection BATCH RENDERING
2446
2447
2448
2449 If you want to render many projects to media files without having to
2450 repeatedly attend to the @b{Render} dialog, @b{batch rendering} is the
2451 function to use.  In this function, you specify many EDL files to
2452 render and the unique output files for each.  Then Cinelerra loads each
2453 EDL file and renders it automatically, without any user intervention. 
2454 Each EDL file and its output to be rendered is called a @b{batch}. 
2455 This allows a huge amount of media to be processed and greatly
2456 increases the value of an expensive computer.
2457
2458 The first thing to do when preparing to do batch rendering is define
2459 projects to be rendered.  The batch renderer requires a separate EDL
2460 file for every batch to be rendered.  Set up a project and define the
2461 region to be rendered either by highlighting it, setting in/out points
2462 around it, or positioning the insertion point before it.  Then save the
2463 project as an EDL.  Define as many projects as needed this way.  The
2464 batch renderer takes the active region from the EDL file for rendering.
2465
2466 With all the EDL files prepared with active regions, go to
2467 @b{File->batch render}.  This brings up the batch rendering dialog. 
2468 The interface for batch rendering is a bit more complex than for single
2469 file rendering.
2470
2471
2472 A list of batches must be defined before starting a batch rendering
2473 operation.  The table of batches appears on the bottom of the batch
2474 render dialog and is called @b{batches to render}.  Above this are
2475 the configuration parameters for a single batch.
2476
2477 Set the @b{output path}, @b{file format}, @b{Audio}, @b{Video}, and
2478 @b{Create new file at each label} parameters as if it was a single
2479 file.  These parameters apply to only one batch.  In addition to the
2480 standard rendering parameters, you must select the source EDL to use in
2481 the batch.  Do this by setting the @b{EDL path}.
2482
2483 If the @b{batches to render} list is empty or nothing is highlighted,
2484 click @b{New} to create a new batch.  The new batch will contain all
2485 the parameters you just set.
2486
2487 Repeatedly press the @b{New} button to create more batches with the
2488 same parameters.  Highlight any batch and edit the configuration on the
2489 top of the batch render window.  The highlighted batch is always
2490 synchronized to the information displayed.
2491
2492 Click and drag batches to change the order in which they're rendered. 
2493 Hit @b{delete} to permanently remove the highlighted batch.
2494
2495 In the list box is a column which enables or disables the batch.  This
2496 way batches can be skipped without being deleted.  Click on the
2497 @b{Enabled} column in the list box to enable or disable a batch.  If it
2498 is checked, the batch is rendered.  If it is blank, the batch is
2499 skipped.
2500
2501 The other columns in the batch list are informative.
2502
2503 @itemize
2504
2505 @item
2506 @b{Output} The output path of the batch.
2507 @item
2508 @b{EDL} The source EDL of the batch.
2509 @item
2510 @b{Elapsed} The amount of time taken to render the batch if it is finished.
2511
2512 @end itemize
2513
2514 To start rendering from the first enabled batch, hit @b{Start}.
2515
2516 Once rendering, the main window shows the progress of the batch.  Once
2517 the batch finishes, the elapsed column in the batch list is updated and
2518 the next batch is rendered until all the enabled batches are finished.
2519 The currently rendering batch is always highlighted red.
2520
2521
2522 To stop rendering before the batches are finished without closing the
2523 batch render dialog, hit @b{Stop}.
2524
2525 To stop rendering before the batches are finished and close the batch
2526 render dialog, hit @b{Cancel}.
2527
2528 To exit the batch render dialog whether or not anything is being
2529 rendered, hit @b{Cancel}.
2530
2531
2532
2533
2534
2535
2536
2537 @node THE RENDER FARM
2538 @subsection THE RENDER FARM
2539
2540 When bicubic interpolation and HDTV was first done on Cinelerra, the
2541 time needed to produce the simplest output became unbearable even on
2542 the fastest dual 1.7Ghz Xeon of the time.  Renderfarm support even in
2543 the simplest form brings HDTV times back in line with SD while making
2544 SD faster than realtime.
2545
2546 While the renderfarm interface isn't spectacular, it's simple enough to
2547 use inside an editing suite with less than a dozen nodes without going
2548 through the same amount of hassle you would with a several hundred node
2549 farm.  Renderfarm is invoked transparently for all file->render
2550 operations when it is enabled in the preferences.
2551
2552 Cinelerra divides the selected region of the timeline into a certain
2553 number of jobs which are then dispatched to the different nodes
2554 depending on the load balance.  The nodes process the jobs and write
2555 their output to individual files on the filesystem.  The output files
2556 are not concatenated.  It's important for all the nodes to have access
2557 to the same filesystem on the same mount point for assets.
2558
2559 If a node can't access an input asset it'll display error messages to
2560 its console but probably not die.  If it can't access an output asset
2561 it'll cause the rendering to abort.
2562
2563 It should be noted that in the render dialog, the @b{Create new file at
2564 each label} option causes a new renderfarm job to be created at each
2565 label instead of by the load balancer.  If this option is selected when
2566 no labels exist, only one job will be created.
2567
2568 A Cinelerra renderfarm is organized into a master node and any number
2569 of slave nodes.  The master node is the computer which is running the
2570 GUI.  The slave nodes are anywhere else on the network and are run from
2571 the command line.  Run a slave node from the command line with 
2572
2573 @b{cinelerra -d}
2574
2575 That is the simplest configuration.  Type @b{cinelerra -h} to see more
2576 options.  The default port number may be overridden by passing a port
2577 number after the -d.
2578
2579
2580 Most of the time you'll want to bring in the rendered output and fine
2581 tune the timing on the timeline.  Also some file formats like MPEG
2582 can't be direct copied.  Because of this, the jobs are left in
2583 individual files.
2584
2585 You can load these by creating a new track and specifying
2586 @b{concatenate to existing tracks} in the load dialog.  Files which
2587 support direct copy can be concatenated into a single file by rendering
2588 to the same file format with renderfarm disabled.  Also to get direct
2589 copy, the track dimensions, output dimensions, and asset dimensions
2590 must be equal.
2591
2592 MPEG files or files which don't support direct copy have to be
2593 concatenated with a command line utility.  MPEG files can be
2594 concatenated with @b{cat}.
2595
2596 Configuration of the renderfarm is described in the configuration
2597 chapter @xref{RENDERFARM}.  The slave nodes traditionally read and
2598 write data to a common filesystem over a network, thus they don't need
2599 hard drives.
2600
2601 Ideally all the nodes on the renderfarm have similar CPU performance. 
2602 Cinelerra load balances on a first come first serve basis.  If the last
2603 segment is dispatched to the slowest node, all the fastest nodes may
2604 end up waiting for the slowest node to finish while they themselves
2605 could have rendered it faster.
2606
2607
2608
2609
2610
2611 @node COMMAND LINE RENDERING
2612 @subsection COMMAND LINE RENDERING
2613
2614 The command line rendering facility consists of a way to load the
2615 current set of batch rendering jobs and process them without a GUI. 
2616 This is useful if you're planning on crashing X repeatedly or want to
2617 do rendering on the other side of a low bandwidth network.  You might
2618 have access to a supercomputer in India but still be stuck in America,
2619 exhiled you might say.  A command line interface is ideal for this.
2620
2621 To perform rendering from the command line, first run Cinelerra in
2622 graphical mode.  Go to @b{file->batch render}.  Create the batches you
2623 intend to render in the batch window and close the window.  This saves
2624 the batches in a file.  Set up the desired renderfarm attributes in
2625 @b{settings->preferences} and exit Cinelerra.  These settings are used
2626 the next time command line rendering is used.
2627
2628 On the command line run 
2629
2630 @b{cinelerra -r}
2631
2632 to processes the current batch jobs without a GUI.  Setting up all the
2633 parameters for this operation is hard.  That's why the command line
2634 aborts if any output files already exist.
2635
2636 Other parameters exist for specifying alternative files for the
2637 preferences and the batches.  Attempting to use anything but the
2638 defaults is very involved so it hasn't been tested.
2639
2640
2641
2642
2643
2644 @node NAVIGATING THE PROJECT
2645 @chapter NAVIGATING THE PROJECT
2646
2647 The thing you want to do most of the time is get to a certain time and
2648 place in the media.  Internally the media is organized into tracks. 
2649 Each track extends across time.  Navigation involves both getting to a
2650 track and getting to a certain time in the track.
2651
2652
2653
2654 @menu
2655 * NAVIGATING THE PROGRAM WINDOW::
2656 * NAVIGATING THE VIEWER AND COMPOSITOR::
2657 * NAVIGATING THE RESOURCES::
2658 * USING THE TRANSPORT CONTROLS::
2659 * USING BACKGROUND RENDERING::
2660 @end menu
2661
2662
2663
2664 @node NAVIGATING THE PROGRAM WINDOW
2665 @section NAVIGATING THE PROGRAM WINDOW
2666
2667 The program window contains many features for navigation and displays
2668 the timeline as it is structured in memory: tracks stacked vertically
2669 and extending across time horizontall.  The horizontal scroll bar
2670 allows you to scan across time.  The vertical scroll bar allows you to
2671 scan across tracks.
2672
2673 Below the timeline you'll find the zoom panel.  The zoom panel contains
2674 values for @b{sample zoom}, @b{amplitude}, @b{track zoom}, and
2675 @b{curve zoom}.  These values in addition to the scrollbars are the
2676 main tools for positioning the timeline.
2677
2678
2679
2680
2681
2682
2683
2684
2685 @sp 1
2686
2687 @image{zoompanel}
2688
2689
2690 Changing the @b{sample zoom} causes the amount of time visible to
2691 change.  @b{If your mouse has a wheel and it works in X11 go over
2692 the tumblers and use the wheel to zoom in and out.}
2693
2694 The @b{amplitude} only affects audio.  It determines how big the
2695 waveform is if the waveform is drawn.
2696
2697 The @b{track zoom} affects all tracks.  It determines the height of
2698 each track.  If you change the track zoom the amplitude zoom
2699 compensates so  audio waveforms look proportional.
2700
2701 The @b{curve zoom} affects the curves in all the tracks.  It
2702 determines the amplitude and offset of the curves.  The tumbler affects
2703 curve amplitude but the only way to change curve offset is to use the
2704 @b{fit curves} button.  @image{fit_curves,,,,}
2705
2706
2707 In addition to the graphical tools, you'll probably more often use the
2708 keyboard to navigate.  Use @b{PAGE UP} and @b{PAGE DOWN} to
2709 scroll up and down the tracks.
2710
2711 Use the @b{LEFT} and @b{RIGHT} arrows to move across time in
2712 small increments.  You'll often need to scroll beyond the end of the
2713 timeline but scrollbars won't let you do it.  Instead use the
2714 @b{RIGHT} arrow to scroll past the end of timeline.
2715
2716 Use the @b{HOME} and @b{END} keys to instantly go to the
2717 beginning or end of the timeline.  In @b{I-beam} mode, hold down
2718 shift while pressing @b{HOME} or @b{END} to select the region of
2719 the timeline between the insertion point and the key pressed.
2720
2721 Use the @b{UP} and @b{DOWN} arrows to change the sample zoom by a
2722 power of 2.
2723
2724 @b{CTRL-UP} and @b{CTRL-DOWN} cause the amplitude zoom to change.
2725
2726 @b{CTRL-PGUP} and @b{CTRL-PGDOWN} cause the track zoom to change.
2727
2728 @b{ALT-UP} and @b{ALT-DOWN} cause the curve amplitude to change.
2729
2730
2731
2732 @menu
2733 * THE INSERTION POINT::
2734 * THE IN/OUT POINTS::
2735 * USING LABELS IN THE PROGRAM WINDOW::
2736 @end menu
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750 @node THE INSERTION POINT
2751 @subsection THE INSERTION POINT
2752
2753 By default you'll see a flashing insertion point in the program window
2754 the first time you boot it up.  This is where new media is pasted onto
2755 the timeline.  It's also the starting point of all playback
2756 operations.  When rendering, it defines the region of the timeline to
2757 be rendered.
2758
2759 The insertion point is normally moved by clicking inside the timebar. 
2760 Any region of the timebar not obscured by labels and in/out points is a
2761 hotspot for repositioning the insertion point.
2762
2763 @sp 1
2764 @image{main_timebar,,,,}
2765 @b{The main timebar}
2766
2767 The insertion point also can be moved by clicking in the timeline
2768 itself, but not always.  The insertion point has two modes of
2769 operation: 
2770
2771 @itemize
2772 @item
2773 drag and drop mode 
2774
2775 @item
2776 cut and paste mode
2777
2778 @end itemize
2779
2780 The mode of operation is determined by selecting the arrow or the
2781 i-beam in the buttonbar.
2782
2783 @sp 1
2784 @image{editing_mode,,,,}
2785 @b{The editing mode buttons}
2786
2787 If the arrow is highlighted it enables @b{drag and drop} mode.  In
2788 drag and drop mode, clicking in the timeline doesn't reposition the
2789 insertion point.  Instead it selects an entire edit.  Dragging in the
2790 timeline repositions the edit, snapping it to other edit boundaries. 
2791 This is normally useful for reordering audio playlists and moving
2792 effects around.
2793
2794 If the i-beam is highlighted it enables @b{cut and paste mode}.  In
2795 cut and paste mode clicking in the timeline repositions the insertion
2796 point.  Dragging in the timeline highlights a region.  The highlighted
2797 region becomes the playback range during the next playback operation,
2798 the rendered range during the next render operation, and the region
2799 affected by cut and paste operations.
2800
2801 @b{Shift-clicking} in the timeline extends the highlighted region.
2802
2803 @b{Double-clicking} in the timeline selects the entire edit the
2804 cursor is over.
2805
2806 It should be noted that when moving the insertion point and selecting
2807 regions, the positions are either aligned to frames or aligned to
2808 samples.  When editing video you'll want to align to frames.  When
2809 editing audio you'll want to align to samples.  This is set in
2810 @b{settings->align cursor on frames}.
2811
2812 If the highlighted region is the region affected by cut and paste
2813 operations, how do I cut and paste in @b{drag and drop} mode?  In
2814 this case you need to set @b{in/out points} to define an affected region.
2815
2816
2817
2818
2819
2820 @node THE IN/OUT POINTS
2821 @subsection THE IN/OUT POINTS
2822
2823 In both editing modes you can set in/out points.  The in/out points
2824 define the affected region.  In drag and drop mode they are the only
2825 way to define an affected region.  In both cut and paste mode and drag
2826 and drop mode the highlighted area overrides the in/out points.  If a
2827 highlighted area and in/out points are set, the highlighted area is
2828 affected by editing operations and the in/out points are ignored.  If
2829 no region is highlighted, the in/out points are used.
2830
2831 Normally, in/out points do not affect the playback region.  Only if you
2832 hold down CTRL while issuing a playback command do the in/out points
2833 determine the playback region.
2834
2835 To set in/out points go to the timebar and position the insertion point
2836 somewhere.  Hit the @image{in_point_button} @b{in point button}.  Go
2837 to a position after the in point and hit the @image{out_point_button}
2838 @b{out point button}.
2839
2840 @sp 1
2841 @image{inout_points} @b{Timebar with in/out points set}.
2842
2843 Select either the in point or the out point and the insertion point
2844 jumps to that location.  After selecting an in point, if you hit the
2845 @b{in point button} the in point will be deleted.  After selecting
2846 an out point, if you hit the @b{out point button} the out point will
2847 be deleted.
2848
2849 If you select a region somewhere else while in/out points already
2850 exist, the existing points will be repositioned when you hit the in/out
2851 buttons.
2852
2853 @b{Shift-clicking} on an in/out point extends the highlighted region
2854 to that point.
2855
2856 Instead of using the button bar you can use the @b{[} and @b{]}
2857 keys to toggle in/out points.
2858
2859 The insertion point and the in/out points allow you to define an
2860 affected region but they don't let you jump to exact points on the
2861 timeline very easily.  For this purpose there are labels.
2862
2863
2864
2865
2866
2867 @node USING LABELS IN THE PROGRAM WINDOW
2868 @subsection USING LABELS IN THE PROGRAM WINDOW
2869
2870 Labels are an easy way to set exact locations on the timeline you want
2871 to jump to.  When you position the insertion point somewhere and hit
2872 the @image{label_button} @b{label button} a new label appears on the
2873 timeline.  
2874
2875 @sp 1
2876 @image{timebar_label} @b{Timebar with a label on it}
2877
2878 No matter what the zoom settings are, clicking on the label positions
2879 the insertion point exactly where you set it.  Hitting the label button
2880 again when a label is selected deletes it.
2881
2882 @b{Shift-clicking} on a label extends the highlighted region.
2883
2884 @b{Double-clicking} between two labels highlights the region between
2885 the labels.
2886
2887 Hitting the @b{l} key has the same effect as the label button.
2888
2889 If you hit the label button when a region is highlighted, two labels
2890 are toggled at each end of the highlighted region.  If one end already
2891 has a label, then the existing label is deleted and a label is created
2892 at the opposite end.
2893
2894 Labels can reposition the insertion point when they are selected but
2895 they can also be traversed with the @image{label_traversal} @b{label
2896 traversal} buttons.  When a label is out of view, the label traversal
2897 buttons reposition the timeline so the label is visible.  There are
2898 keyboard shortcuts for label traversal, too.
2899
2900 @b{CTRL-LEFT} repositions the insertion point on the previous label.
2901
2902 @b{CTRL-RIGHT} repositions the insertion point on the next label.
2903
2904 With label traversal you can quickly seek back and forth on the
2905 timeline but you can also select regions.
2906
2907 @b{SHIFT-CTRL-LEFT} extends the highlighted region to the previous
2908 label.
2909
2910 @b{SHIFT-CTRL-RIGHT} extends the highlighted region to the next label.
2911
2912 Manually hitting the label button or @b{l} key over and over again
2913 to delete a series of labels can get tedious.  For deleting a set of
2914 labels, first highlight a region and second use the @b{Edit->Clear
2915 labels} function.  If in/out points exist, the labels between the
2916 in/out points are cleared and the highlighted region ignored.
2917
2918
2919
2920
2921
2922
2923
2924
2925 @node NAVIGATING THE VIEWER AND COMPOSITOR
2926 @section NAVIGATING THE VIEWER AND COMPOSITOR
2927
2928 The navigation features of the Viewer and Compositor behave very
2929 similarly.  Each has a timebar and slider below the video output.  The
2930 timebar and slider are critical for navigation.
2931
2932 @sp 1
2933
2934 @image{timebarslider,,,,}
2935
2936 The timebar represents the entire time covered by the program.  When
2937 you define labels and in/out points it defines those, too.  Finally the
2938 timebar defines a region known as the @b{preview region}.
2939
2940 The @b{preview region} is the region of the timeline which the
2941 slider effects.  The slider only covers the time covered by the preview
2942 region.  By using a preview region inside the entire program and using
2943 the slider inside the preview region you can quickly and precisely seek
2944 in the compositor and viewer.
2945
2946 When you replace the current project with a file the preview region
2947 automatically resizes to cover the entire file.  When you append data
2948 or change the size of the current project, the preview region stays the
2949 same size and shrinks.  Therefore, you need to resize the preview
2950 region.
2951
2952 Load a file and then slide around it using the compositor slider.  The
2953 insertion point in the main window follows the compositor.  Move the
2954 pointer over the compositor's timebar until it turns into a left resize
2955 pointer.  The click and drag right.  The preview region should have
2956 changed and the slider resized proportionally.
2957
2958 Go to the right of the timebar until a right resize pointer appears. 
2959 Drag left so the preview region shrinks.
2960
2961 Go to the center of the preview region in the timebar and drag it
2962 around to convince yourself if can be moved.
2963
2964
2965 @sp 1
2966
2967 @image{previewregion,,,,}
2968
2969 @b{Preview region in compositor}
2970
2971 If you go to the slider and slide it around with the preview region
2972 shrunk, you'll see the slider only affects the preview region.  The
2973 timebar and slider in the viewer window work exactly the same.
2974
2975 Labels and in/out points are fully supported in the viewer and
2976 compositor.  The only difference between the viewer and compositor is
2977 the compositor reflects the state of the program while the viewer
2978 reflects the state of a clip but not the program.
2979
2980 When you hit the @b{label button} in the compositor, the label
2981 appears both in the compositor timebar and the program timebar.
2982
2983 When you select a label or in/out point in the compositor, the program
2984 window jumps to that position.
2985
2986 @sp 1
2987 @image{viewer_labels} @b{Labels and in/out points in the viewer}.
2988
2989 In the viewer and compositor, labels and in/out points are displayed in
2990 the timebar.  Instead of displaying just a region of the program, the
2991 timebar displays the entire program here.
2992
2993
2994
2995 Like the Program window, the Compositor has a zoom capability.  First,
2996 the pulldown menu on the bottom of the compositor window has a number
2997 of zoom options.  When set to @b{Auto} the video is zoomed to match
2998 the compositor window size as closely as possible.  When set to any
2999 other percentage, the video is zoomed a power of 2 and scrollbars can
3000 be used to scroll around the output.  When the video is zoomed bigger
3001 than the window size, not only do scrollbars scan around it but
3002 @b{middle mouse button} dragging in the video output scans around
3003 it.  This is exactly when The Gimp does.
3004
3005 Furthermore, the zoom @image{magnify} toggle causes the Compositor
3006 window to enter zoom mode.  In zoom mode, clicking in the video output
3007 zooms in while @b{ctrl-clicking} in the video output zooms out.  If
3008 you have a wheel mouse, rotating the wheel zooms in or out too.
3009
3010 Zooming in or out with the zoom tool does not change the rendered
3011 output, mind you.  It's merely for scrutinizing video or fitting it in
3012 the desktop.
3013
3014
3015
3016
3017
3018
3019 @node NAVIGATING THE RESOURCES
3020 @section NAVIGATING THE RESOURCES
3021
3022 The resource window is divided into two areas.  One area lists folders
3023 and another area lists folder contents.  Going into the folder list and
3024 clicking on a folder updates the contents area with the contents of
3025 that folder.
3026
3027 The folder and contents can be displayed as icons or text.
3028
3029 @b{Right clicking} in the folder or contents area brings up a menu
3030 containing formatting options.  Select @b{Display text} to display a
3031 text listing.  Select @b{Sort items} to sort the contents of the
3032 folder alphabetically.
3033
3034
3035
3036
3037
3038
3039
3040
3041 @node USING THE TRANSPORT CONTROLS
3042 @section USING THE TRANSPORT CONTROLS
3043
3044 Transport controls are just as useful in navigation as they are in
3045 playing back footage, hence they are described here in the navigation
3046 section.  Each of the Viewer, Compositor, and Program windows has a
3047 transport panel.
3048
3049 @sp 1
3050 @image{transport_panel} @b{The transport panel}.
3051
3052 The transport panel is controlled by the keyboard as well as the
3053 graphical interface.  For each of the operations it performs, the
3054 starting position is the position of the insertion point in the Program
3055 window and the slider in the Compositor window.  The ending position is
3056 either the end or start of the timeline or the end or start of the
3057 selected region if there is one.
3058
3059 The orientation of the end or start depends on the direction of
3060 playback.  If it's forward the end position is the end of the selected
3061 region.  If it's backward the end position is the start of the selected
3062 region.
3063
3064 The insertion point moves to track playback.  When playback stops, the
3065 insertion point stays where playback stopped.  Thus, by playing back
3066 you change the position of the insertion point.
3067
3068 The keyboard interface is usually the fastest and has more speeds.  The
3069 transport keys are arranged in a sideways @b{T} on the number pad.
3070
3071 @itemize
3072
3073 @item
3074 @b{+} Fast reverse
3075 @item
3076 @b{6} Normal reverse
3077 @item
3078 @b{5} Slow reverse
3079 @item
3080 @b{4} Frame reverse
3081 @item
3082 @b{1} Frame forward
3083 @item
3084 @b{2} Slow forward
3085 @item
3086 @b{3} Normal forward
3087 @item
3088 @b{Enter} Fast forward
3089 @item
3090 @b{0} Stop
3091 @item
3092 @b{Spacebar} Normal forward
3093 @end itemize
3094
3095 Hitting any key on the keyboard twice pauses it.
3096
3097 When using frame advance functions the behavior may seem odd.  If you
3098 frame advance forward and then frame advance backward, the displayed
3099 frame doesn't change.  This is because the playback position isn't the
3100 frame but the time between two frames.  The rendered frame is the area
3101 that the playback position crosses.  When you increment the time
3102 between two frames by one and decrement it by one, you cross the same
3103 frame both times and so the same frame is displayed.
3104
3105 The transport behavior changes if you hold down CTRL when issuing any
3106 of the transport commands.  This causes the starting point to be the in
3107 point if playing forward and the out point if playing backward.  If
3108 playing forward, the out point becomes the ending point and if playing
3109 backward, the in point becomes the ending point.  If no in/out points
3110 are specified, the behavior falls back to using the insertion point and
3111 track boundaries as the starting and ending points.
3112
3113
3114
3115 @node USING BACKGROUND RENDERING
3116 @section USING BACKGROUND RENDERING
3117
3118
3119
3120 Background rendering allows impossibly slow effects to play back in
3121 realtime shortly after the effect is pasted in the timeline.  It
3122 continuously renders temporary output.  When renderfarm is enabled,
3123 background rendering uses the renderfarm continuously.  This way, any
3124 size video can be seen in realtime merely by creating a fast enough
3125 network with enough nodes.
3126
3127 Background rendering is enabled in settings->preferences->performance. 
3128 It has one interactive function: @b{settings->set background render}.  This
3129 sets the point where background rendering begins to where the in point
3130 is.  If any video exists, a red bar appears in the time bar showing
3131 what has been background rendered.
3132
3133 It's often useful to insert an effect or a transition and then select
3134 settings->set background render right before the effect to preview it
3135 in full framerates.
3136
3137
3138
3139 @node EDITING
3140 @chapter EDITING
3141
3142
3143 Editing comprises both the time domain and the track domain.  Since the
3144 timeline consists of a stack of tracks, you need to worry about how to
3145 sort and create tracks in addition to what time certain media appears
3146 on a track.
3147
3148 In the time domain, Cinelerra offers many ways to approach the editing
3149 process.  The three main methods are two screen editing, drag and drop
3150 editing, and cut and paste editing.
3151
3152 There are several concepts Cinelerra uses when editing which apply to
3153 all the methods.  The @b{timeline} is where all editing decisions are
3154 represented.  This is a stack of tracks in the center of the main
3155 window.  It can be scrolled up, down, left and right with the
3156 scrollbars on the right and bottom of it.  It can also be scrolled up
3157 and down with a mouse wheel.
3158
3159 The @b{active region} is the range of time which is affected by editing
3160 commands on the timeline.  The active region is determined first by the
3161 presence of in/out points in the timeline.  If those don't exist the
3162 highlighted region is used.  If no highlighted region exists the
3163 insertion point is used as the start of the active region.  Some
3164 commands treat all the space to the right of the insertion point as
3165 active, like @b{Render}, while others treat the active length as 0 if no
3166 end point for the active region is defined.
3167
3168 Finally, editing decisions never affect source material.  This is
3169 @b{non destructive editing} and it became popular with audio because it
3170 was much faster than if you had to copy all the media affected by an
3171 edit.  Editing only affects pointers to source material, so if you want
3172 to have a media file at the end of your editing session which
3173 represents the editing decisions, you need to @b{render} it.
3174 @xref{RENDERING FILES}.
3175
3176 Every track on the timeline has a set of attributes on
3177 the left, the most important of which is the @b{arm track}
3178 attribute.
3179
3180
3181
3182 @menu
3183 * THE PATCHBAY::           Enabling different features on different tracks
3184 * NUDGING TRACKS::         Move entire tracks horizontally
3185 * PANNING TRACKS::         Changing the audio output channels
3186 * AUTOMATIC TRACK PANNING::  Panning tracks to common speaker arrangements
3187 * STANDARD AUDIO MAPPINGS::  Making audio panning that works on other players.
3188 * MANIPULATING TRACKS::    Moving whole tracks around
3189 * TWO SCREEN EDITING::     Using two video windows to edit
3190 * DRAG AND DROP EDITING::  Dragging objects to edit
3191 * CUT AND PASTE EDITING::  Editing media like text
3192 * TRIMMING::               Changing in and out points
3193 @end menu
3194
3195
3196 @node THE PATCHBAY
3197 @section THE PATCHBAY
3198
3199
3200 On the left of the timeline is a region affectionately known as the
3201 patchbay.  The patchbay enables features specific to each track.  All
3202 tracks have a text area for naming the track.
3203
3204 All tracks have an @b{expander} @image{expandpatch_checked} for viewing
3205 more options and for viewing the effects on the track.  Click on the
3206 expander to expand or collapse the track.  If it's pointing sideways,
3207 the track is collapsed.  If it's pointing down, the track is expanded. 
3208 The effects appear below the media for the track if they exist.
3209
3210 All tracks have the following row of toggles for several features.
3211
3212 @sp 1
3213 @image{track_attributes}
3214 @b{Track attributes}
3215
3216
3217 If the toggle is colored, it is enabled.  If the toggle is the
3218 background color of most of the windows, it is disabled.  Click on the
3219 toggle to enable or disable the feature.  Several mouse operations
3220 speed up the configuration of several tracks at a time.
3221
3222 Click on an attribute and drag across adjacent tracks to copy the same
3223 attribute to those tracks.
3224
3225 Hold down @b{shift} while clicking a track's attribute to enable the
3226 attribute in the current track and toggle the attribute in all the
3227 other tracks.
3228
3229 Hold down @b{shift} while clicking an attribute.  Click until all the
3230 tracks except the selected one are disabled.  Then drag the cursor over
3231 the adjacent track to enable the attribute in the adjacent track.
3232
3233
3234 The other attributes affect the output of the track.
3235
3236 @itemize
3237
3238 @item
3239
3240 @b{Play track} determines whether the track is rendered or not.  If
3241 it's off, the track is not rendered.  However, if the track is chained
3242 to any other tracks, the other tracks perform all the effects in the
3243 chained track, regardless of play status.
3244 @sp 1
3245
3246 @item
3247
3248 @b{Arm track} determines whether the track is armed or not.   Only the
3249 @b{armed tracks} are affected by editing operations.  Make sure you
3250 have enough armed destination tracks when you paste or splice material
3251 or some tracks in the material will get left out.
3252
3253 In addition to restricting editing operations, the armed tracks in
3254 combination with the active region determine where material is inserted
3255 when loading files.  If the files are loaded with one of the insertion
3256 strategies which doesn't delete the existing project, the armed tracks
3257 will be used as destination tracks.
3258
3259 Press @b{Tab} while the cursor is anywhere over a track to toggle the
3260 track arming status.
3261
3262 Press @b{Shift-Tab} while the cursor is over a track to toggle the
3263 arming status of every other track.
3264
3265 @item
3266
3267 @b{Gang fader} causes the fader to track the movement of whatever other
3268 fader you're adjusting.  A fader is only ganged if the @b{arm track} is
3269 also on.  This is normally used to adjust audio levels on all the
3270 tracks simultaneously.  Gang also causes @b{Nudge} parameters to
3271 synchronise across all the ganged tracks.
3272
3273
3274 @sp 1
3275
3276 @item
3277
3278 @b{Draw media} determines if picons or waveforms are drawn on the
3279 track.  By default, some file formats load with this off while other
3280 file formats load with it on.  This depends on whether the file format
3281 takes a long time to draw on the timeline.  Merely set it to on if you
3282 want to see picons for any file format.
3283 @sp 1
3284
3285 @item
3286
3287 @b{Mute track} causes the output to be thrown away once the track is
3288 completely rendered.  This happens whether or not @b{play track} is
3289 on.  If the track is part of an effect chain, the output of the effect
3290 chain track is overlayed on the final output even though it's routed
3291 back to another track.  Mute track is used to keep the effect chain
3292 track from overlapping the output of the source track.
3293 @sp 1
3294
3295 @item
3296
3297 @b{Fader} All tracks have a fader, but the units of each fader depend
3298 on whether it's audio or video.  Click and drag the fader to fade the
3299 track in and out.  If it is ganged to other tracks of the same media
3300 type, with the @b{arm} option enabled, the other faders should follow.
3301
3302 Hold down @b{shift} and drag a fader to center it on 0.
3303
3304 @end itemize
3305
3306
3307
3308 @node NUDGING TRACKS
3309 @section NUDGING TRACKS
3310
3311 Each track has a nudge textbox in its patchbay.  You may have to expand
3312 the track to see it.  These are views of the patchbays when expanded.
3313
3314 @image{apatches}
3315
3316 Pan and nudge for an audio track.
3317
3318 @image{vpatches}
3319
3320 Overlay mode and nudge for a video track.
3321
3322
3323 The nudge is the amount the track is shifted left or right during
3324 playback.  The track is not displayed shifted on the timeline, but it
3325 is shifted when it's played back.  This is useful for synchronizing
3326 audio with video, creating fake stereo, or compensating for an effect
3327 which shifts time, all without tampering with any edits.
3328
3329 Merely enter in the amount of time to shift by to instantly shift the
3330 track.  Negative numbers make the track play later.  Positive numbers
3331 make the track play sooner.  The nudge units are either @b{seconds} or
3332 the native units for the track.  Select the units by @b{right clicking}
3333 on the nudge textbox and using the context sensitive menu.
3334
3335 Nudge settings are ganged with the @b{Gang faders} toggle and the
3336 @b{Arm track} toggle.
3337
3338 Use the mouse wheel over the nudge textbox to increment and decriment
3339 it.
3340
3341
3342
3343
3344
3345 @node PANNING TRACKS
3346 @section PANNING TRACKS
3347
3348 Audio tracks have a panning box in their patchbay.  It may have to be
3349 expanded to see it.  The panning box is shown here.
3350
3351 @image{apatches}
3352
3353 Pan and nudge for an audio track.
3354
3355 Position the pointer in the panning box and click/drag to reposition
3356 the audio output among the speaker arrangement.  The loudness of each
3357 speaker is printed during the dragging operation.  The panning box uses
3358 a special algorithm to try to allow audio to be focused through one
3359 speaker or branched between the nearest speakers when more than 2
3360 speakers are used.
3361
3362
3363
3364 @node AUTOMATIC TRACK PANNING
3365 @section AUTOMATIC TRACK PANNING
3366
3367
3368 Several convenience functions are provided for automatically setting
3369 the panning to several common standards.  They are listed in the
3370 @b{Audio} menu.  These functions only affect audio tracks with
3371 @b{recording} enabled.
3372
3373 @b{Audio->Map 1:1} - This maps every track to its own channel and wraps
3374 around when all the channels are allocated.  It's most useful for
3375 making 2 tracks with 2 channels map to stereo and for making 6 tracks
3376 with 6 channels map to a 6 channel soundcard.
3377
3378 @b{Audio->Map 5.1:2} - This maps 6 tracks to 2 channels.  The project
3379 should have 2 channels when using this function.  Go to
3380 @b{Settings->format} to set the output channels to 2.  This is most
3381 useful for downmixing 5.1 audio to stereo.
3382
3383
3384
3385
3386
3387 @node STANDARD AUDIO MAPPINGS
3388 @section STANDARD AUDIO MAPPINGS
3389
3390 Although Cinelerra lets you map any audio track to any speaker, there
3391 are standard mappings you should use to ensure the media can be played
3392 back elsewhere.  Also, most audio encoders require the audio tracks to
3393 be mapped to standard speaker numbers or they won't work.
3394
3395 In the @b{channel position} widget @xref{SETTING PROJECT ATTRIBUTES},
3396 the channels are numbered to correspond to the output tracks they are
3397 rendered to.  For stereo, the source of channel 1 needs to be the left
3398 track and the source of channel 2 needs to be the right track.
3399
3400 For 5.1 surround sound, the sources of the 6 channels need to be in the
3401 order of center, front left, front right, back left, back right, low
3402 frequency effects.  If the right tracks aren't mapped to the right
3403 speakers, most audio encoders won't encode the right information if
3404 they encode anything at all.  The low frequency effects track
3405 specifically can't store high frequencies in most cases.
3406
3407
3408
3409
3410
3411 @node MANIPULATING TRACKS
3412 @section MANIPULATING TRACKS
3413
3414 Tracks in Cinelerra either contain audio or video.  There is no special
3415 designation for tracks other than the type of media they contain.  When
3416 you create a new project, it contains a certain mumber of default
3417 tracks.  You can still add or delete tracks from a number of menus. 
3418 The @b{Tracks} menu contains a number of options for dealing with
3419 multiple tracks simultaneously.  Each track itself has a popup menu
3420 which affects one track.
3421
3422 Bring up the popup menu by moving over a track and right clicking.  The
3423 popup menu affects the track whether it's armed or not.
3424
3425 @b{Move up} and @b{move down} moves the one track up or down in
3426 the stack.  @b{Delete track} deletes the track.
3427
3428 Operations in the @b{Tracks} menu affect only tracks which are
3429 armed.
3430
3431 @b{Move tracks up} and @b{Move tracks down} shift all the armed
3432 tracks up or down the stack.
3433
3434 @b{Delete tracks} deletes the armed tracks.
3435
3436 @b{Delete last track} deletes the last track, whether it's armed or
3437 not.  Holding down the @b{d} key quickly deletes all the tracks.
3438
3439 @b{Concatenate tracks} is more complicated.  It takes every
3440 @b{playable} track and concatenates it to the end of the first
3441 @b{armed tracks}.  If there are two armed tracks followed by two
3442 playable tracks, the concatenate operation puts the two playable tracks
3443 after the two armed tracks.  If there are three playable tracks
3444 instead, two tracks are put after the armed tracks and a third track is
3445 put on the end of the first armed track.  The destination track wraps
3446 around until all the playable tracks are concatenated.
3447
3448 Finally, you'll want to create new tracks.  The @b{Audio} and
3449 @b{Video} menus each contain an option to add a track of their
3450 specific type.  In the case of audio, the new track is put on the
3451 bottom of the timeline and the output channel of the audio track is
3452 incremented by one.  In the case of video, the new track is put on the
3453 top of the timeline.  This way, video has a natural compositing order. 
3454 New video tracks are overlayed on top of old tracks.
3455
3456
3457
3458
3459
3460
3461
3462
3463
3464 @node TWO SCREEN EDITING
3465 @section TWO SCREEN EDITING
3466
3467 This is the fastest way to construct a program out of movie files.  The
3468 idea consists of viewing a movie file in one window and viewing the
3469 program in another window.  Sections of the movie file are defined in
3470 one window and transferred to the end of the program in the other
3471 window.
3472
3473 The way to begin a two screen editing session is to load some
3474 resources.  In @b{file->load} load some movies with the insertion
3475 mode @b{create new resources}.  You want the timeline to stay
3476 unchanged while new resources are brought in.  Go to the Resource
3477 Window and select the @b{media} folder.  The newly loaded resources
3478 should appear.  Drag a resource from the media side of the window over
3479 the Viewer window.
3480
3481 There should be enough armed tracks on the timeline to put the sections
3482 of source material that you want.  If there aren't, create new tracks
3483 or arm more tracks.
3484
3485 In the viewer window seek to the starting point of a clip you want to
3486 use.  Use either the @b{slider} or the @b{transport controls}. 
3487 Use the @b{preview region} to narrow down the search.  Set the
3488 starting point with the @image{in_point_button} @b{in point button}.
3489
3490 Seek to the ending point of the clip you want to use.  Set the ending
3491 point with the @image{out_point_button} @b{out point button}.  The
3492 two points should now appear on the timebar and define a clip.
3493
3494 There are several things you can do with the clip now.
3495
3496 @itemize
3497
3498 @item
3499
3500 Splice @image{splice_button} inserts the clip in the timeline, pushing
3501 everything back.  If an @b{in point} or @b{out point} exists on
3502 the timeline it's inserted there, otherwise it's inserted after the
3503 insertion point.  After that, the insertion point moves to the end of
3504 the clip.  If there is no in/out point, the insertion point will be
3505 used as the next splice location.  This way you can continuously build
3506 up the program by splicing.
3507
3508 @item
3509
3510 Overwrite @image{overwrite_button} overwrites the region of the
3511 timeline with the clip.  If an @b{in point} or @b{out point}
3512 exists on the timeline it's overwritten there, otherwise it's
3513 overwritten after the insertion point.  If a region is highlighted or
3514 both in and out points exist the difference between the active region
3515 and the clip length is deleted.
3516
3517
3518
3519 @item
3520
3521 Create a clip @image{toclip_button} generates a new clip for the
3522 resource window containing the affected region but doesn't change the
3523 timeline.  Every clip has a title and a description.  These are
3524 optional.
3525
3526 @item
3527
3528 Copy behaves the same as in cut and paste editing.
3529
3530 @end itemize
3531
3532 Two screen editing can be done purely by keybard shortcuts.  When you
3533 move the pointer over any button a tooltip should appear, showing what
3534 key is bound to that button.  In the Viewer window, the number pad keys
3535 control the transport and the @b{[ ] v} keys perform in/out points
3536 and splicing.
3537
3538
3539
3540
3541
3542
3543
3544
3545
3546
3547
3548 @node DRAG AND DROP EDITING
3549 @section DRAG AND DROP EDITING
3550
3551 The answer is yes, you can you create a bunch of clips and drag them on
3552 the timeline.  You can also drag edits around the timeline.
3553
3554 Load some files using @b{file->load}.  Set the insertion mode to
3555 @b{Create new resources}.  This loads the files into the Resource
3556 Window.  Create some audio and video tracks on the timeline using the
3557 video and audio menus.
3558
3559 Open the @b{Media} folder in the resource window.  Drag a media file
3560 from the resource window to the timeline.  If the media has video, drag
3561 it onto a video track.  If the media is pure audio, drag it onto an
3562 audio track.
3563
3564 Cinelerra fills out the audio and video tracks below the dragging
3565 cursor with data from the file.  This affects what tracks you should
3566 create initially and which track to drag the media onto.  If the media
3567 has one video track and two audio tracks, you'll need one video track
3568 and two audio tracks on the timeline and the media should be dragged
3569 over the first video track.  If the media has audio only you'll need
3570 one audio track on the timeline for every audio track in the media and
3571 the media should be dragged over the first audio track.
3572
3573 When dragging, the media snaps to the start of track if the track is
3574 empty.  If there are edits on the track, the media snaps to the nearest
3575 edit boundary.
3576
3577 You can also drag multiple files from the resource window.  Either draw
3578 a box around the files, use SHIFT, or use CTRL when selecting files. 
3579 When you drop the files in the timeline, they are concatenated.  The
3580 behavior of SHIFT and CTRL changes depending on if the resources are in
3581 text or icons.
3582
3583 To display the resources as text or icons, right click inside the media
3584 list.  Select either @b{display icons} or @b{display text} to
3585 change the list format.
3586
3587 When displaying text in the resource window @b{SHIFT-clicking} on
3588 media files extends the number of highlighted selections. 
3589 @b{CTRL-clicking} on media files in text mode selects additional
3590 files one at a time.
3591
3592 When displaying icons in the resource window @b{SHIFT-clicking} or
3593 @b{CTRL-clicking} selects media files one at a time.
3594
3595 In addition to dragging media files, if you create clips and open the
3596 @b{clip} folder you can drag clips on the timeline.
3597
3598 In the timeline there is further dragging functionality.  To enable the
3599 dragging functionality of the timeline, select the arrow toggle
3600 @image{arrow}.  Move over an edit and drag it.  If more than one
3601 track is armed, Cinelerra will drag any edits which start on the same
3602 position as the edit the cursur is currently over.  During a dragging
3603 operation the edit snaps to the nearest boundary.
3604
3605 Dragging edits around the timeline allows you to sort music playlists,
3606 sort movie scenes, and give better NAB demos but not much else.
3607
3608
3609
3610
3611
3612
3613
3614
3615
3616
3617
3618 @node CUT AND PASTE EDITING
3619 @section CUT AND PASTE EDITING
3620
3621 This is the traditional method of editing in audio editors.  In the
3622 case of Cinelerra, you either need to start a second copy of Cinelerra
3623 and copy from one copy to the other, copy from different tracks in the
3624 same copy, or load a media file into the Viewer and copy from there.
3625
3626 Load some files onto the timeline.  To perform cut and paste editing
3627 select the @image{ibeam} i-beam toggle.  Select a region of the
3628 timeline and select the @image{cut} cut button to cut it.  Move the
3629 insertion point to another point in the timeline and select the
3630 @image{paste} paste button.  Assuming no in/out points are defined on
3631 the timeline this performs a cut and paste operation.
3632
3633 If in/out points are defined, the insertion point and highlighted
3634 region are overridden by the in/out points for clipboard operations. 
3635 Thus, with in/out points you can perform cut and paste in drag and drop
3636 mode as well as cut and paste mode.
3637
3638 When editing audio, it is customary to cut from one part of a waveform
3639 into the same part of another waveform.  The start and stop points of
3640 the cut are identical in each waveform and might be offset slightly,
3641 while the wave data is different.  It would be very hard to highlight
3642 one waveform to cut it and highlight the second waveform to paste it
3643 without changing the relative start and stop positions.
3644
3645 One option for simplifying this is to open a second copy of Cinelerra,
3646 cutting and pasting to transport media between the two copies.  This
3647 way two highlighed regions can exist simultanously.
3648
3649 Another option is to set in/out points for the source region of the
3650 source waveform and set labels for the destination region of the
3651 destination waveform.  Perform a cut, clear the in/out points, select
3652 the region between the labels, and perform a paste.
3653
3654
3655
3656 A final operation in cut and paste editing is the @b{edit->clear}
3657 operation.  If a region is highlighted or in/out points exist, the
3658 affected region is cleared by @b{edit->clear}.  But if the insertion
3659 point is over an edit boundary and the edits on each side of the edit
3660 boundary are the same resource, the edits are combined into one edit
3661 comprised by the resource.  The start of this one edit is the start of
3662 the first edit and the end of this one edit is the end of the second
3663 edit.  This either results in the edit expanding or shrinking.
3664
3665
3666
3667
3668
3669 @node TRIMMING
3670 @section TRIMMING
3671
3672 With some edits on the timeline it's possible to do trimming.  By
3673 trimming you shrink or grow the edit boundaries by dragging them.  In
3674 either drag and drop mode or cut and paste mode, move the cursor over
3675 an edit boundary until it changes shape.  The cursor will either be an
3676 expand left or an expand right.  If the cursor is an expand left, the
3677 dragging operation affects the beginning of the edit.  If the cursor is
3678 an expand right, the dragging operation affects the end of the edit.
3679
3680 When you click on an edit boundary to start dragging, the mouse button
3681 number determines which dragging behavior is going to be followed.  3
3682 possible behaviors are bound to mouse buttons in the interface
3683 preferences. @xref{INTERFACE}.
3684
3685 The effect of each drag operation not only depends on the behavior
3686 button but whether the beginning or end of the edit is being dragged.
3687 When you release the mouse button, the trimming operation is performed.
3688
3689 In a @b{Drag all following edits} operation, the beginning of the
3690 edit either cuts data from the edit if you move it forward or pastes
3691 new data from before the edit if you move it backward.  The end of the
3692 edit pastes data into the edit if you move it forward or cuts data from
3693 the end of the edit if you move it backward.  All the edits thereafter
3694 shift.  Finally, if you drag the end of the edit past the start of the
3695 edit, the edit is deleted.
3696
3697 In a @b{Drag only one edit} operation, the behavior is the same when
3698 you drag the beginning or end of an edit.  The only difference is none
3699 of the other edits in the track shift.  Instead, anything adjacent to
3700 the current edit expands or shrinks to fill gaps left by the drag
3701 operation.
3702
3703 In a @b{Drag source only} operation, nothing is cut or pasted.  If
3704 you move the beginning or end of the edit forward, the source reference
3705 in the edit shifts forward.  If you move the beginning or end of the
3706 edit backward, the source reference shifts backward.  Where the edit
3707 appears in the timeline remains the same but the source shifts.
3708
3709 For all file formats besides still images, the extent of the trimming
3710 operation is clamped to the source file length.  Attempting to drag the
3711 start of the edit beyond the start of the source clamps it to the
3712 source start.
3713
3714 In all trimming operations, all edits which start on the same position
3715 as the cursor when the drag operation begins are affected.  Unarm
3716 tracks to prevent edits from getting affected.
3717
3718
3719
3720
3721
3722
3723
3724
3725 @node USING EFFECTS
3726 @chapter USING EFFECTS
3727
3728 It would be sufficient to perform all changes to the timeline using
3729 editing operations, but this isn't very extensible.  Certain timeline
3730 changes should produce a different effect in the output without
3731 involving a unique procedure to apply each change.  This is why we have
3732 effects.
3733
3734 Effects fall into three categories, and each effect in a category is
3735 applied using the same procedure.
3736
3737
3738 @menu
3739 * REALTIME EFFECTS::
3740 * RENDERED EFFECTS::
3741 * TRANSITIONS::
3742 * LADSPA EFFECTS::
3743 * EFFECT PRESETS::
3744 @end menu
3745
3746
3747
3748 @node REALTIME EFFECTS
3749 @section REALTIME EFFECTS
3750
3751 These are layered under the track they apply to.  They process the
3752 track when the track is played back, with no permanent storage of the
3753 output except when the project is rendered.
3754
3755 @b{APPLYING REALTIME EFFECTS}
3756
3757 All the realtime effects are listed in the resource window, divided
3758 into two groups: audio effects and video effects.  Audio effects should
3759 be dragged from the resource window onto audio tracks.  Video effects
3760 should be dragged onto video tracks.
3761
3762 If there is data on the destination track, the effect is applied to the
3763 entire track.  If there is no data on the track the effect is deleted. 
3764 Finally, if a region of the track is selected the effect is pasted into
3765 the region, regardless of whether there is data.
3766
3767 Some of the effects don't process data but synthesize data.  In the
3768 case of a synthesis effect, you'll want to select a region of the
3769 track so the dragging operation pastes it without deleting it.
3770
3771 When dragging more than one effect onto a track, you'll see the effects
3772 layering from top to bottom, on the bottom of the track.   When the
3773 track is played back, effects are processed from top to bottom.  The
3774 output of the top effect becomes the input of the bottom effect and so
3775 on and so forth.
3776
3777 In addition to dragging from the resource window, there are 2 other
3778 methods of applying them:
3779
3780 @itemize
3781 @item
3782 @b{APPLYING FROM THE TRACK POPUP MENU:}
3783
3784 Right click on a track and select @b{Attach effect} from the popup.  The attach effect
3785 dialog gives you more control than pure dragging and dropping.  For one
3786 thing, the attach effect dialog lets you attach two more types of
3787 effects: shared effects and shared tracks.  Select a plugin from the
3788 @b{Plugins} column and hit @b{Attach} under the plugins column to attach
3789 it.  The effect is the same as if the effect was dragged from the
3790 resource window.
3791
3792 @item
3793 @b{APPLYING FROM THE AUDIO AND VIDEO MENUS:}
3794
3795 Select @b{Audio->Attach effect...} or @b{Video->Attach effect} to attach
3796 a realtime effect to all the recordable tracks simultaneously.  The
3797 advantage with this is most of the time you want to attach the same
3798 effect to all the audio tracks and the other two methods require
3799 repeating the same work for every track.
3800
3801 The menu interface has an option called  @b{Attach single standalone and
3802 share others}.  Enable this to make the first track get a standalone
3803 effect and to have the other tracks share the standalone effect.  Most
3804 of the time, you want this to be on.
3805
3806 @end itemize
3807
3808
3809 When an effect exists under a track, it most often needs to be
3810 configured.  Go to the effect and right click on it to bring up the
3811 effect popup.  In the effect popup is a @b{show} option.  The show
3812 option causes the GUI for the effect to appear under the cursor.  Most
3813 effects have GUI's but some don't.  If the effect doesn't have a GUI,
3814 nothing pops up when the @b{show} option is selected.  When you
3815 tweek parameters in the effect GUI, the parameters normally effect the
3816 entire duration of the effect.
3817
3818
3819 @menu
3820 * REALTIME EFFECT TYPES::
3821 * EDITING REALTIME EFFECTS::
3822 @end menu
3823
3824
3825
3826 @node REALTIME EFFECT TYPES
3827 @subsection REALTIME EFFECT TYPES
3828
3829 The two other effect types supported by the Attach Effect dialog are
3830 recycled effects.  In order to use a recycled effect, three requiremenets
3831 must be met:
3832
3833 @itemize
3834
3835 @item
3836 There must be other effects in the timeline.
3837
3838 @item
3839
3840 The other effects must be of the same type as the track you're
3841 attaching an effect to.  If the track is an audio track, the effects
3842 must be audio effects.  If the track is a video track, the effects must
3843 be video effects.
3844
3845 @item
3846
3847 The insertion point or selected region must start inside the other effects.
3848
3849 @end itemize
3850
3851 In the case of a shared effect, these conditions must be true.  In the
3852 case of a shared track, there merely must be another track on the
3853 timeline of the same type as the track you're applying an effect to. 
3854 If you right clicked on a video track to attach an effect, there won't
3855 be anything in the @b{shared tracks} column if no other video track
3856 exists.  If you right clicked on an audio track there won't be anything
3857 in the shared track column if no other audio track exists.
3858
3859 If shared effects or shared tracks are available, they appear in the
3860 @b{shared effects} and @b{shared tracks} columns.  The
3861 @b{attach} button under each column causes anything highlighted in
3862 the column to be attached under the current track.
3863
3864 Shared effects and shared tracks allow very unique things to be done. 
3865 In the case of a shared effect, the shared effect is treated like a
3866 copy of the original effect except in the shared effect the GUI can't
3867 be brought up.  All configuration of the shared effect is determined by
3868 the GUI of the original effect and only the GUI of the original effect
3869 can be brought up.
3870
3871 When a shared effect is played back, it's processed just like a normal
3872 effect except the configuration is copied from the original effect. 
3873 Some effects detect when they are being shared, like the reverb effects
3874 and the compressor.  These effects determine what tracks are sharing
3875 them and either mix the two tracks together or use one track to stage
3876 some value.  The reverb mixes tracks together to simulate ambience. 
3877 The compressor uses one of the sharing tracks as the trigger.
3878
3879 When an original track has a @b{shared track} as one of its effects,
3880 the shared track itself is used as a realtime effect.  This is more
3881 commonly known as @b{bouncing tracks} but Cinelerra achieves the
3882 same operation by attaching shared tracks.  The fade and any effects in
3883 the shared track are applied to the original track.  Once the shared
3884 track has processed the data, the original track performs any effects
3885 which come below the shared track and then composites it on the output.
3886
3887 In addition, once the shared track has processed the output of the
3888 original track like a realtime effect, the shared track mixes itself
3889 into the output with it's settings for pan, mode, and projector.  Thus,
3890 two tracks are mixing the same data on the output.  Most of the time
3891 you don't want the shared track to mix the same data as the original
3892 track on the output.  You want it to stop right before the mixing stage
3893 and give the data back to the original track.  Do this by enabling the
3894 @image{mutepatch_up} mute toggle next to each track for whom you don't
3895 want to mix on the output.
3896
3897 Suppose you were making video and you did want the shared track to
3898 composite the original track's data on the output a second time.  In
3899 the case of video, the video from the shared track would always appear
3900 under the video from the original track, regardless of whether it was
3901 on top of the original track.  This is because shared tracks are
3902 composited in order of their attachment.  Since it's part of the original
3903 track it has to be composited before the original track is composited.
3904
3905
3906
3907
3908
3909
3910
3911 @node EDITING REALTIME EFFECTS
3912 @subsection EDITING REALTIME EFFECTS
3913
3914 Many operations exist for manipulating effects once they are in the
3915 timeline.  Because mixing effects and media is such complex business,
3916 the methods used in editing effects aren't as concise as cutting and
3917 pasting.  Some of the editing happens by dragging in/out points, some
3918 of the editing happens through popup menus, and some of it happens by
3919 dragging effects.
3920
3921 Normally when you edit tracks, the effects follow the editing
3922 decisions.  If you cut from a track, the effect shrinks.  If you drag
3923 edit in/out points, the effect changes length.  This behavior can be
3924 disabled by selecting @b{Settings->edit effects} in the project
3925 window.  This decouples effects from editing operations, but what if
3926 you just want to edit the effects?
3927
3928 Move the timeline cursor over the effect borders until it changes to a
3929 resize left or resize right icon.  In this state, if you drag the end
3930 of the effect, it performs an edit just like dragging the end of a
3931 track does.  
3932
3933 The three editing behaviors of track trimming apply to effect trimming
3934 and they are bound to the mouse buttons that you set in @b{interface
3935 preferences}. @xref{INTERFACE}.  When you perform a trim edit on an
3936 effect, the effect boundary is moved by dragging on it.  Unlike track
3937 editing, the effect has no source length.  You can extend the end of an
3938 effect as much as desired without being limited.
3939
3940 Also unlike track editing, the starting position of the drag operation
3941 doesn't bind the edit decision to media.  The media the effect is bound
3942 to doesn't follow effect edits.  Other effects; however, do follow
3943 editing decisions made on an effect.  If you drag the end of an effect
3944 which is lined up to effects on other tracks, the effects on the other
3945 tracks will be edited while the media stays the same.
3946
3947 What happens if you trim the end of an effect in, leaving a lot of
3948 unaffected time near the end of the track?  When you drag an effect in
3949 from the Resource Window you can insert the effect in the portion of
3950 the row unoccupied by the trimming operation.  Realtime effects are
3951 organized into rows under the track.  Each row can have multiple
3952 effects.
3953
3954 In some cases you'll want a trimming operation to change only one row
3955 of effects.  This can be achieved by first positioning the insertion
3956 point on the start or end of the effect.  Then press @b{shift} while
3957 beginning the trimming operation.  This causes the operation to change
3958 only one row of effects.
3959
3960 In addition to trimming, you can move effects up or down.  Every track
3961 can have a stack of effects under it.  By moving an effect up or down
3962 you change the order in which effects are processed in the stack.  Go
3963 to an effect and right click to bring up the effect menu.  The
3964 @b{Move up} and @b{Move down} options move the effect up or down.
3965
3966 When you're moving effects up or down, be aware that if they're shared
3967 as @b{shared effects}, any references will be pointing to a
3968 different effect after the move operation.
3969
3970 Finally, there's dragging of effects.  Dragging effects works just like
3971 dragging edits.  You must select the @image{arrow} arrow to enter drag and
3972 drop mode before dragging effects.  The effects snap to media
3973 boundaries, effect boundaries, and tracks.  Be aware if you drag a
3974 reference to a shared effect, the reference will usually point to the
3975 wrong effect afterwards.
3976
3977 Right click on an effect to bring up a menu for the effect.  Select
3978 @b{attach...} to change the effect or change the reference if it is
3979 a shared effect.
3980
3981
3982
3983
3984
3985
3986
3987
3988 @node RENDERED EFFECTS
3989 @section RENDERED EFFECTS
3990
3991
3992 Another type of effect is performed on a section of the track and the
3993 result stored somewhere before it is played back.  The result is
3994 usually pasted into the track to replace the original data.
3995
3996 In 15 years, the only effect we actually ever rendered with this feature
3997 was @b{normalize}.  We've never rendered an effect which could be
3998 applied on the timeline, even though this feature supports rendering
3999 realtime effects.
4000
4001 This feature was implemented back when computers were too slow to play
4002 back anything in realtime.  Decent sounding reverb took a long time &
4003 was considered major number crunching.
4004
4005 The rendered effects are not listed in the resource window but instead
4006 are accessed through the @b{Audio->Render effect} and
4007 @b{Video->Render effect} menu options.  Each of these menu options
4008 brings up a dialog for the rendered effect.  Rendered effects apply to
4009 only one type of track, either audio or video.  If no tracks of the
4010 type exist, an error pops up.
4011
4012 A region of the timeline to apply the effect to must be defined before
4013 selecting @b{Render effect...}.  If no in/out points and no
4014 highlighted region exists, the entire region after the insertion point
4015 is treated as the affected region.  Otherwise, the region between the
4016 in/out points or the highlighted region is the affected region.
4017
4018 Secondly, the tracks to apply the rendered affect to need to be
4019 @b{armed}.  All other tracks are ignored.
4020
4021 Finally, the rendered affect processes certain track attributes when it
4022 reads its input data but not others.  Transitions in the affected track
4023 are applied.  Nudge is not and effects are not.  This allows the new
4024 data to be pasted into the existing position without changing the nudge
4025 value.
4026
4027 In the render effect dialog is a list of all the realtime and all the
4028 rendered effects.  The difference here is that the realtime effects are
4029 rendered to disk and not applied under the track.  Highlight an effect
4030 in the list to designate it as the one being performed.
4031
4032 Define a file to render the effect to in the @b{Select a file to
4033 render to} box.  The @image{magnify} magnifying glass allows file
4034 selection from a list.
4035
4036 Select a file format which can handle the track type.  The
4037 @image{wrench} wrench allows configuration specific to the file format.
4038
4039 There is also an option for creating a new file at each label.  If you
4040 have a CD rip on the timeline which you want to divide into different
4041 files, the labels would become dividing points between the files if
4042 this option were selected.  When the timeline is divided by labels, the
4043 effect is re-initialized at every label.  Normalize operations take the
4044 peak in the current file and not in the entire timeline.
4045
4046 Finally there is an insertion strategy just like in the render dialog. 
4047 It should be noted that even though the effect applies only to audio or
4048 video, the insertion strategy applies to all tracks just like a
4049 clipboard operation.
4050
4051 When you click @b{OK} in the effect dialog, it calls the GUI of the
4052 effect.  If the effect is also a realtime effect, a second GUI appears
4053 to prompt for acceptance or rejection of the current settings.  After
4054 accepting the settings, the effect is processed.
4055
4056
4057
4058
4059
4060
4061
4062
4063
4064
4065
4066
4067
4068
4069 @node TRANSITIONS
4070 @section TRANSITIONS
4071
4072 When one edit ends and another edit begins, the default behaviour is to
4073 have the first edit's output immediately become the output of the
4074 second edit when played back.  Transitions are a way for the first
4075 edit's output to become the second edit's output with different
4076 variations.
4077
4078 Cinelerra supports audio and video transitions, all of which are listed
4079 in the resource window.  Transitions may only apply to the matching
4080 track type.  Transitions under @b{audio transitions} can only apply
4081 to audio tracks.  Transitions under @b{video transitions} can only
4082 apply to video tracks.
4083
4084 Load a video file and cut a section from the center so the edit point
4085 is visible on the timeline.  Go the resource window and click on the
4086 @b{Video transitions} folder.  Drag a transition from the transition
4087 list onto the second video edit on the timeline.  A box highlights over
4088 where the transition will appear.  Releasing it over the second edit
4089 applies the transition between the first and second edit.
4090
4091 You can now scrub over the transition with the transport controls and
4092 watch the output in the @b{Compositor window}.  Scrubbing with the
4093 insertion point doesn't normally show transitions because the
4094 transition durations are usually too short.  The exact point in time
4095 when the transition takes effect isn't straightforward.  It starts when
4096 the second edit begins and lasts a certain amount of time into the
4097 second edit.  Therefore, the first asset needs to have enough data
4098 after the edit point to fill the transition into the second edit.
4099
4100 Once the transition is in place, it can be edited similarly to an
4101 effect.  Move the pointer over the transition and right click to bring
4102 up the transition menu.  The @b{show} option brings up specific
4103 parameters for the transition in question if there are any.  The
4104 @b{length} option adjusts the length of the transition in seconds. 
4105 Once these two parameters are set, they are applied to future
4106 transitions until they are changed again.  Finally, the @b{detach}
4107 option removes the transition from the timeline.
4108
4109 Dragging and dropping transitions from the Resource window to the
4110 Program window can be really slow and tiring.  Fortunately, once you
4111 drag a transition from the Resource window, the @b{U} and @b{u}
4112 keys will paste the same transition.  The @b{U} key pastes the last
4113 video transition and the @b{u} key pastes the last audio transition
4114 on all the recordable tracks.  If the insertion point or in point is
4115 over an edit, the beginning of the edit is covered by the transition.  
4116
4117 It should be noted that when playing transitions from the timeline to a
4118 hardware accelerated video device, the hardware acceleration will
4119 usually be turned off momentarily during the transition and on after
4120 the transition in order to render the transition.  Using an
4121 unaccelerated video device for the entire timeline normally removes the
4122 disturbance.
4123
4124
4125
4126
4127
4128 @node LADSPA EFFECTS
4129 @section LADSPA EFFECTS
4130
4131
4132 LADSPA effects are supported in realtime and rendered mode for audio. 
4133 The LADSPA plugins you get from the internet vary in quality.  Most
4134 can't be tweeked in realtime very easily and work better when
4135 rendered.  Some crash and some can only be applied to one track due to
4136 a lack of reentrancy.  Although Cinelerra implements the LADSPA
4137 interface as accurately as possible, multiple tracks of realtime,
4138 simultaneous processing go beyond the majority of LADSPA users.  LADSPA
4139 effects appear in the audio folder as the hammer and screwdriver, to
4140 signify that they are Plugins for Linux Audio Developers.
4141
4142 LADSPA Effects are enabled merely by setting the @b{LADSPA_PATH}
4143 environment variable to the location of your LADSPA plugins or putting
4144 them in the @b{/usr/lib/cinelerra} directory.
4145
4146
4147
4148
4149
4150 @node EFFECT PRESETS
4151 @section EFFECT PRESETS
4152
4153 Save and recall all the settings for an effect by using the @b{presets}
4154 window.  Bring up the effect context menu by right clicking on the
4155 effect on the timeline.  Go to @b{Presets...} to bring up the window. 
4156 Save all the settings to a preset by entering a title in @b{Preset
4157 title} and clicking @b{save}.  Recall the settings in a preset by
4158 highlighting it and clicking @b{Apply}.  Delete a preset by highlighting
4159 it and clicking @b{Delete}.
4160
4161
4162
4163
4164
4165
4166
4167 @node SETTING PROJECT ATTRIBUTES
4168 @chapter SETTING PROJECT ATTRIBUTES
4169
4170 When you play media files in Cinelerra, the media files have a certain
4171 number of tracks, a certain frame size, a certain sample size, and so
4172 on and so forth.  No matter what the media file has; however, it is
4173 still played back according to the project attributes.  If an audio
4174 file's samplerate is different than the project attributes, it is
4175 resampled.  If a video file's frame size is different than the project
4176 attributes, it is composited on a black frame, either cropped or
4177 bordered with black.
4178
4179 The project attributes are adjusted in @b{Settings->Set Format} and in
4180 to a more limited extent in @b{File->New}.  When you adjust project
4181 settings in @b{file->new} a new timeline is created with no data. 
4182 Every timeline created from this point uses the same settings.  When
4183 you adjust settings in @b{settings->format}, the timeline is not
4184 recreated with no data but every timeline created from this point uses
4185 the same settings.
4186
4187 In addition to the traditional settings for sample rate, frame rate,
4188 frame size, Cinelerra uses some unusual settings like @b{channel
4189 positions, color model, and aspect ratio.}
4190
4191
4192
4193 @menu
4194 * AUDIO CHANNEL POSITIONS::
4195 * COLOR MODEL::
4196 * ASPECT RATIO::
4197 @end menu
4198
4199
4200
4201
4202
4203 @node AUDIO CHANNEL POSITIONS
4204 @section AUDIO CHANNEL POSITIONS
4205
4206 The currently enabled audio channels and their positions in the user
4207 interface boxes are displayed in the channel position widget.
4208
4209 @sp 2
4210 @image{channelpositions}
4211 @sp 2
4212
4213
4214 The channels are numbered.  When rendered, the output from channel 1 is
4215 rendered to the first output track in the file or the first soundcard
4216 channel of the soundcard.  Later channels are rendered to their
4217 successively numbered output tracks.
4218
4219 The audio channel locations correspond to where in the panning widgets
4220 each of the audio outputs is.  The closer the panning position is to
4221 one of the audio outputs, the more signal that speaker gets.  Click on
4222 a speaker icon and drag to change the audio channel location.
4223
4224 The speakers can be in any orientation.  A different speaker
4225 arrangement is stored for every number of audio channels since normally
4226 you don't want the same speaker arrangement for different numbers of
4227 channels.
4228
4229 Channel positions is the only setting which doesn't affect the output
4230 necessarily.  Click on a speaker icon and drag to change the position
4231 of a channel.  It is merely a convenience so when more than 2 channels
4232 are used, the pan controls on the timeline can distinguish between
4233 them.  It has nothing to do with the actual arrangement of speakers.
4234
4235
4236 But different channels can be positioned very close together to make
4237 them have the same output.
4238
4239
4240
4241
4242 @node COLOR MODEL
4243 @section COLOR MODEL
4244
4245 Color model is very important for video playback because video has the
4246 disadvantage of being very slow.  Although it isn't noticable, audio
4247 intermediates contain much more information than the audio on disk and
4248 the audio which is played.  Audio always uses the highest bandwidth
4249 intermediate because it's fast.
4250
4251 Video intermediates must use the least amount of data for the required
4252 quality because it's slow, but video intermediates still use a higher
4253 bandwidth color model than video which is stored and video which is
4254 played.  This allows more processing to be done with less destruction
4255 of the original data.   
4256
4257 The video is stored on disk in one colormodel, normally compressed
4258 using a YUV derivative.  When played back, Cinelerra decompresses it
4259 from the file format directly into the format of the output device.  If
4260 effects are processed, the decompression is into an intermediate
4261 colormodel first and the intermediate colormodel is then converted to
4262 the format of the output device.  The selection of intermediate
4263 colormodel determines how accurate and fast the effects are.
4264
4265 Cinelerra colormodels are described using a certain packing order of
4266 components and a certain number of bits for each component.  The
4267 packing order is printed on the left and the bit allocation is printed
4268 on the right.
4269
4270 @itemize
4271 @item
4272
4273 @b{RGB-888} 
4274
4275 This allocates 8 bits for the R, G, and B channels and no alpha. This
4276 is normally used for uncompressed media with low dynamic range.
4277
4278 @item
4279
4280 @b{RGBA-8888} 
4281
4282 This allocates an alpha channel to the 8 bit RGB colormodel.  It's used
4283 for overlaying multiple tracks.
4284
4285 @item
4286
4287 @b{YUV-888} 
4288
4289 This allocates 8 bits for Y, U, and V.  This is used for low dynamic
4290 range operations in which the media is compressed in the YUV color
4291 space.  Most compressed media is in YUV and this allows it to be
4292 processed fast with the least color degradation. 
4293
4294 @item
4295
4296 @b{YUVA-8888} 
4297
4298 This allocates an alpha channel to the 8 bit YUV colormodel for
4299 transparency.
4300
4301 @item
4302
4303 @b{RGB-Float} 
4304
4305 This allocates a 32 bit float for the R, G, and B channels and no
4306 alpha.  This is used for high dynamic range processing with no
4307 transparency.
4308
4309 @item
4310
4311 @b{RGBA-Float} This adds a 32 bit float for alpha to RGB-Float.  This
4312 is used for high dynamic range processing with transparency.
4313
4314 @end itemize
4315
4316
4317
4318 In order to do effects which involve alpha channels, a colormodel with
4319 an alpha channel must be selected.  These are RGBA8888, YUVA8888, and
4320 RGBA Float.  The 4 channel colormodels are notoriously slower than 3
4321 channel colormodels, with the slowest being RGBA Float.  Some effects,
4322 like fade, work around the need for alpha channels while other effects,
4323 like chromakey, require an alpha channel to do anything, so it's a good
4324 idea to try the effect without alpha channels to see if it works before
4325 settling on an alpha channel and slowing it down.
4326
4327 The YUV colormodels are usually faster than RGB colormodels when using
4328 compressed footage.  They also destroy fewer colors than RGB
4329 colormodels.  If footage stored as JPEG or MPEG is processed many times
4330 in RGB, the colors will fade while they won't if processed in YUV.
4331
4332 Years of working with high dynamic range footage have shown floating
4333 point RGB to be the best format for high dynamic range.  While 16 bit
4334 integers were used in the past, these were too lossy and slow for the
4335 amount of improvement.
4336
4337 RGB float doesn't destroy information when used with YUV source
4338 footage.  It also supports brightness above 100%.  Be aware that some
4339 effects, like Histogram, still clip above 100% when in floating point.
4340
4341 @node ASPECT RATIO
4342 @section ASPECT RATIO
4343
4344 Aspect ratio determines the shape of the video output when using the
4345 X11 video output.  The numbers in each direction can be any floating
4346 point number.  When drawn on the screen, video pixels are stretched to
4347 match the aspect ratio.
4348
4349 Some file formats, like MPEG video, write the project aspect ratio to
4350 the file.
4351
4352
4353
4354
4355
4356
4357
4358
4359
4360
4361 @node COMPOSITING
4362 @chapter COMPOSITING
4363
4364
4365 A large amount of Cinelerra's binary size is directed towards
4366 compositing.  When you remove the letterboxing from a widescreen show,
4367 you're compositing.  Changing the resolution of a show, making a split
4368 screen, and fading in and out among other things are all compositing
4369 operations in Cinelerra.  Cinelerra detects when it's in a compositing
4370 operation and plays back through the compositing engine only then. 
4371 Otherwise, it uses the fastest decoder available in the hardware.
4372
4373 Compositing operations are done on the timeline and in the Compositor
4374 window.  Shortcuts exist in the Resource window for changing some
4375 compositing attributes.  Once some video files are on the timeline, the
4376 compositor window is a good place to try compositing.
4377
4378
4379
4380 @menu
4381 * THE CAMERA AND PROJECTOR::
4382 * MASKS::
4383 * CROPPING::
4384 * SAFE REGIONS::
4385 * OVERLAY MODES::
4386 * TRACK AND OUTPUT SIZES::
4387 @end menu
4388
4389
4390
4391 @node THE CAMERA AND PROJECTOR
4392 @section THE CAMERA AND PROJECTOR
4393
4394 In the compositor window, the most important functions are the
4395 @image{camera} camera button and the @image{projector} projector
4396 button.  These control operation of the camera and projector.  Inside
4397 Cinelerra's compositing pipeline, the camera determines where in the
4398 source video the temporary is copied from.  The projector determines
4399 where in the output the temporary is copied to.  The temporary is a
4400 frame of video in Cinelerra's memory where all graphics processing is
4401 done.  Each track has a different temporary which is defined by the
4402 track size.  By resizing the tracks you can create splitscreens, pans,
4403 and zooms.
4404
4405 @sp 2
4406 @image{compositing_pipeline}
4407 @sp 2
4408 @b{Visual representation of the compositing pipeline}.
4409
4410 When editing the camera and projector in the compositing window, the
4411 first track with @b{record} enabled is the track affected.  Even if
4412 the track is completely transparent, it's still the affected track.  If
4413 multiple video tracks exist, the easiest way to select one track for
4414 editing is to @b{shift-click} on the record icon of the track.  This
4415 solos the track.
4416
4417 When the @b{projector} button is enabled in the compositor window,
4418 you're in projector editing mode.  A guide box appears in the video
4419 window.  Dragging anywhere in the video window causes the guide box to
4420 move, hopefully along with the video.  @b{shift-dragging} anywhere
4421 in the video window causes the guide box to shrink and grow along with
4422 the video.  Once you've positioned the video with the projector, you're
4423 ready to master the camera.
4424
4425 Select the @image{camera} camera button to enable camera editing mode. 
4426 In this mode, the guide box shows where the camera position is in
4427 relation to past and future camera positions but not where it is in
4428 relation to the source video.  Dragging the camera box in the
4429 compositor window doesn't move the box but instead moves the location
4430 of the video inside the box.
4431
4432 For example, when you drag the camera left, the video moves right. 
4433 When you drag the camera up, the video moves down.  When you shift-drag
4434 the camera, the effect is the same as if you zoomed in or out of the
4435 source.  The intention of the camera is to produce still photo panning,
4436 while the intention of the projector is to composite several sources in
4437 the same scene.
4438
4439 In the compositing window, there is a popup menu of options for the
4440 camera and projector.  Right click over the video portion of the
4441 compositing window to bring up the menu.
4442
4443 @itemize
4444
4445 @item Reset Camera causes the camera to return to the center position.
4446
4447 @item Reset Projector causes the projector to return to the center.
4448
4449 @end itemize
4450
4451
4452 The camera and projector have shortcut operations neither in the popup
4453 menu or represented in video overlays.  These are accessed in the
4454 @b{Tool window}.  Most operations in the Compositor window have a
4455 tool window which is enabled by activating the @image{toolwindow}
4456 question mark.
4457
4458 In the case of the camera and projector, the tool window shows x, y,
4459 and z coordinates.  By either tumbling or entering text directly, the
4460 camera and projector can be precisely positioned.  9 justification
4461 types are also defined for easy access.  A popular justification
4462 operation is upper left projection after image reduction.  This is used
4463 when reducing the size of video with aspect ratio adjustment.
4464
4465 The translation effect allows simultaneous aspect ratio conversion and
4466 reduction but is easier to use if the reduced video is put in the upper
4467 left of the temporary instead of in the center.  The track size is set
4468 to the original size of the video and the camera is centered.  The
4469 output size is set to the reduced size of the video.  Without any
4470 effects, this produces just the cropped center portion of the video in
4471 the output.
4472
4473 The translation effect is dropped onto the video track.  The input
4474 dimensions of the translation effect are set to the original size and
4475 the output dimensions are set to the reduced size.  To put the reduced
4476 video in the center section that the projector shows would require
4477 offsetting @b{out x and out y} by a complicated calculation. 
4478 Instead, we leave @b{out x and out y} at 0 and use the projector's
4479 tool window.
4480
4481 Merely by selecting @image{left_justify} left justify and
4482 @image{top_justify} top justify, the projector displays the reduced
4483 image from the top left corner of the temporary in the center of the
4484 output.
4485
4486
4487
4488
4489
4490
4491 @node MASKS
4492 @section MASKS
4493
4494 Masks select a region of the video for either displaying or hiding. 
4495 Masks are also used in conjunction with another effect to isolate the
4496 effect to a certain region of the frame.  A copy of one video track may
4497 be delayed slightly and unmasked in locations where the one copy has
4498 interference but the other copy doesn't.  Color correction may be
4499 needed in one section of a frame but not another.  A mask can be
4500 applied to just a section of the color corrected track while the
4501 vanilla track shows through.  Removal of boom microphones, airplanes,
4502 and housewives are other mask uses.
4503
4504 The order of the compositing pipeline affects what can be done with
4505 masks.  Mainly, masks are performed on the temporary after effects and
4506 before the projector.  This means multiple tracks can be bounced to a
4507 masked track and projected with the same mask.
4508
4509 Our compositing pipeline graph now has a masking stage.  There are 8
4510 possible masks per track.  Each mask is defined separately, although
4511 they each perform the same operation, whether it's addition or
4512 subtraction.
4513
4514 @sp 2
4515 @image{compositing_pipeline2}
4516 @sp 2
4517 @b{Compositing pipeline with masks}
4518
4519 To define a mask, go into the Compositor window and enable the
4520 @image{mask} @b{mask} toggle.  Now go over the video and
4521 click-drag.  Click-drag again in another part of the image to create
4522 each new point of the mask.  While it isn't the conventional bezier
4523 curve behavior, this masking interface performs in realtime what the
4524 effect of the mask is going to be.  Creating each point of the mask
4525 expands a rubber band curve.  
4526
4527 Once points are defined, they can be moved by @b{ctrl-dragging} in
4528 the vicinity of the corner.  This; however, doesn't smooth out the
4529 curve.  The in-out points of the bezier curve are accessed by
4530 @b{shift-dragging} in the vicinity of the corner.  Then
4531 @b{shift-dragging} near the in or out point causes the point to
4532 move.
4533
4534 Finally, once you have a mask, the mask can be translated in one piece
4535 by @b{alt-dragging} the mask.  Mask editing in Cinelerra is
4536 identical to how The Gimp edits masks except in this case the effect of
4537 the mask is always on.
4538
4539 The masks have many more parameters which couldn't be represented with
4540 video overlays.  These are represented in the tool window for masks. 
4541 Selecting the @image{toolwindow} question mark when the @image{mask}
4542 mask toggle is highlighted brings up the mask options.
4543
4544 The @b{mode} of the mask determines if the mask removes data or
4545 makes data visible.  If the mode is subtractive, the mask causes video
4546 to disappear.  If the mode is additive, the mask causes video to appear
4547 and everything outside the mask to disappear.
4548
4549 The @b{value} of the mask determines how extreme the addition or
4550 subtraction is.  In the subtractive mode, higher values subtract more
4551 alpha.  In the additive mode, higher values make the region in the mask
4552 brighter while the region outside the mask is always hidden.
4553
4554 The mask number determines which one of the 8 possible masks we're
4555 editing.  Each track has 8 possible masks.  When you click-drag in the
4556 compositor window, you're only editing one of the masks.  Change the
4557 value of @b{mask number} to cause another mask to be edited.  The
4558 previous mask is still active but only the curve overlay for the
4559 currently selected mask is visible.
4560
4561 When multiple masks are used, their effects are ORed together.  Every
4562 mask in a single track uses the same value and mode.
4563
4564 The edges of a mask are hard by default but this rarely is desired. 
4565 The @b{feather} parameter determines how many pixels to feather the
4566 mask.  This creates softer edges but takes longer to render.
4567
4568 Finally, there are parameters which affect one point on the current
4569 mask instead of the whole mask.  These are @b{Delete, x, y}.  The
4570 active point is defined as the last point dragged in the compositor
4571 window.  Any point can be activated merely by @b{ctrl-clicking} near
4572 it without moving the pointer.  Once a point is activated,
4573 @b{Delete} deletes it and @b{x, y} allow repositioning by numeric
4574 entry.
4575
4576
4577
4578
4579 @node CROPPING
4580 @section CROPPING
4581
4582
4583
4584 Cropping changes the value of the output dimensions and the projector
4585 to reduce the visible picture area.  Enable the @image{crop} crop
4586 toggle and the @image{toolwindow} tool window in the @b{compositing
4587 window} to perform cropping.
4588
4589 This draws a rectangle over the video.  Click-drag anywhere in the
4590 video to start a new rectangle.  Click-drag over any corner of the
4591 rectangle to reposition the corner.
4592
4593 Alt-click in the cropping rectangle to translate the rectangle to any
4594 position without resizing it.
4595
4596 The tool window allows text entry of the coordinates and executes the
4597 cropping operation.  When the rectangle is positioned, hit the @b{do
4598 it} button in the tool window to execute the cropping operation.
4599
4600
4601
4602
4603
4604
4605 @node SAFE REGIONS
4606 @section SAFE REGIONS
4607
4608 On consumer displays the borders of the image are cut off and within
4609 the cutoff point is a region which isn't always square like it is in
4610 the compositor window.  The borders are intended for scratch room and
4611 vertical blanking data.  You can show where these borders are by
4612 enabling the @image{titlesafe} safe regions toggle.  Keep titles inside
4613 the inner rectangle and keep action inside the outer rectangle.
4614
4615
4616
4617
4618
4619
4620
4621
4622 @node OVERLAY MODES
4623 @section OVERLAY MODES
4624
4625 Every video track has an overlay mode, accessible by expanding the
4626 track.  The overlay mode is a pulldown menu on the left under the
4627 fader.  When collapsed, it displays an icon representing the current
4628 overlay mode.
4629
4630 Select the @image{expandpatch_checked} expand track toggle to view all
4631 the options for a video track if you can't see the overlay mode.  The
4632 overlay mode of video tracks is @b{normal} by default.  Select other
4633 modes by clicking the overlay button and selecting an item from the
4634 popup menu.
4635
4636 Overlay modes are processed inside the projector stage of compositing. 
4637 The different modes are summarized below.
4638
4639 @itemize
4640
4641 @item
4642
4643 @b{Normal} uses a traditional Porter-Diff equation to blend tracks with
4644 alpha.  When no alpha exists in the project color model, the new track
4645 always replaces the output.
4646
4647 @item
4648
4649 @b{Addition}  In this mode, whatever is in the output is added to the
4650 current track.  The result is blended based on the current track's
4651 alpha onto the output.
4652
4653 @item
4654
4655 @b{Subtraction} In this mode, the current track is subtracted from the
4656 output and the result is alpha blended onto the output.
4657
4658 @item 
4659
4660 @b{Multiply} is the most useful operation.  The current track is multiplied
4661 by the output and the result blended onto the output.  Usually a black
4662 and white image with no alpha channel or a white title on a black image
4663 is used as the current track.  With the multiply operation, only the
4664 output portions under the white area show.
4665
4666 @item
4667
4668 @b{Divide} divides the current track by the output and the result is
4669 blended into the output.  It usually results in overloaded levels.
4670
4671 @item
4672
4673 @b{Replace} does no blending and overwrites the output with the current
4674 track.
4675
4676 @end itemize
4677
4678
4679
4680
4681
4682 @node TRACK AND OUTPUT SIZES
4683 @section TRACK AND OUTPUT SIZES
4684
4685 The size of the temporary and the size of the output in our compositing
4686 pipeline are independant and variable.  This fits into everything
4687 covered so far.  The camera's viewport is the temporary size.  Effects
4688 are processed in the temporary and are affected by the temporary size. 
4689 Projectors are rendered to the output and are affected by the output
4690 size.  If the temporary is smaller than the output, the temporary is
4691 bordered by blank regions in the output.  If the temporary is bigger
4692 than the output, the temporary is cropped.
4693
4694 The temporary size is defined as the track size.  Each track has a
4695 different size.  Right click on a track to bring up the track's menu. 
4696 Select @b{Resize Track} to resize the track to any arbitrary size. 
4697 Alternatively you can select @b{Match output size} to make the track
4698 the same size as the output.
4699
4700 The output size is set in either @b{New} when creating a new project
4701 or @b{Settings->Format}.  In the Resource window there is another
4702 way to change the output size.  Right click on a video asset and select
4703 @b{Match project size} to conform the output to the asset.  When new
4704 tracks are created, the track size always conforms to the output size
4705 specified by these methods.
4706
4707
4708
4709
4710
4711
4712 @node KEYFRAMES
4713 @chapter KEYFRAMES
4714
4715
4716 When you change the fade, camera, projector, or other parameters for a
4717 track, they stay by default the same for the entire durection of the
4718 timeline.   Setting static parameters isn't very useful sometimes. 
4719 Normally you need to move the camera around over time or change mask
4720 positions.  Masks need to follow objects.  We create dymanic changes by
4721 defining keyframes.  A keyframe is a certain point in time when the
4722 settings for one operation change.  In Cinelerra, there are keyframes
4723 for almost every compositing parameter and effect parameter.
4724
4725 Whenever you adjust any parameter, the value is stored in a keyframe. 
4726 If the value is stored in a keyframe, why doesn't it always change? 
4727 The keyframe it is stored in by default is known as the @b{default
4728 keyframe}.  The default keyframe applies to the entire duration if no
4729 other keyframes are present.  The default keyframe is not drawn
4730 anywhere because it always exists.  The only way change occurs over
4731 time is if non-default keyframes are created.
4732
4733 Display keyframes for any parameter by using the @b{view} menu.  A
4734 faster way to toggle multiple keyframe types is to bring up
4735 @b{window->overlays}.  This window allows toggling of every parameter
4736 in the view menu.  When keyframes are selected, they are drawn on the
4737 timeline over the tracks they apply to.
4738
4739 Keyframes come in many forms: curves, toggles, modes, and so on. 
4740 How to handle the different types of keyframes is described here.
4741
4742 @menu
4743 * CURVE KEYFRAMES::  Using rubber band curves
4744 * CHANGING BEZIER & LINEAR MODE::  Change curves from linear to curved
4745 * SNAPPING TO NEIGHBOR KEYFRAMES::  
4746 * NAVIGATING CURVE KEYFRAMES::
4747 * TOGGLE KEYFRAMES::
4748 * AUTOMATIC KEYFRAMES::
4749 * COMPOSITOR KEYFRAMES::  
4750 * EDITING KEYFRAMES::   Moving keyframes around
4751 * KEYFRAME SPANNING::   How to change 1 parameter in many keyframes simultaneously
4752 @end menu
4753
4754
4755
4756 @node CURVE KEYFRAMES
4757 @section CURVE KEYFRAMES
4758
4759 Many parameters are stored in rubber band curves.  Go to @b{view->fade} or
4760 @b{view->...zoom} to show curves on the timeline for those parameters. 
4761 In either arrow editing mode or i-beam editing mode, move the cursor
4762 over the curves in the timeline until it changes shape.  Then merely by
4763 clicking and dragging on the curve you can create a keyframe at the
4764 position.
4765
4766 After the keyframe is created, click drag on it again to reposition
4767 it.  When you click-drag a second keyframe on the curve, it creates a
4768 smooth ramp.
4769
4770 @node CHANGING BEZIER & LINEAR MODE
4771 @section CHANGING BEZIER & LINEAR MODE
4772
4773 The curve keyframes have bezier and linear modes.  In linear mode, the
4774 keyframe looks like a square and the lines emanating from it are
4775 straight.  In bezier mode, the keyframe is rounded and has 2 control
4776 lines in addition to the rubber band curve lines.
4777
4778 These are keyframes in linear mode.
4779
4780 @image{linear}
4781
4782 These are keyframes in bezier mode.
4783
4784 @image{bezier}
4785
4786 Change the mode of an existing keyframe by right clicking on it to bring
4787 up the context menu and selecting @b{make linear} or @b{make bezier}.
4788
4789
4790 Change the mode of several keyframes by highlighting the entire region of the
4791 timeline and selecting @b{Keyframes->change to linear} or
4792 @b{Keyframes->change to bezier}.
4793
4794 When keyframes are created, they can be linear or bezier by default. 
4795 Change the default mode by checking or unchecking @b{Keyframes->create
4796 bezier}.
4797
4798
4799 For bezier keyframes, @b{ctrl-dragging} on the control lines of a
4800 keyframe changes the value of either the input control or the output
4801 control.  Without @b{ctrl} the cursor only affects the central
4802 keyframe.  This affects the sharpness of the curve.  The input and
4803 output controls can only be moved vertically.
4804
4805 If the control lines aren't visible, @b{ctrl-drag} on the left or right
4806 of the keyframe.
4807
4808 @node SNAPPING TO NEIGHBOR KEYFRAMES
4809 @section SNAPPING TO NEIGHBOR KEYFRAMES
4810
4811 @b{shift-drag} on a curve keyframe to make the keyframe snap to the
4812 value of either the next or previous keyframe, depending on which
4813 exists.  This lets you set a constant curve value without having to copy
4814 the next or previous keyframe.
4815
4816
4817
4818 @node NAVIGATING CURVE KEYFRAMES
4819 @section NAVIGATING CURVE KEYFRAMES
4820
4821 There isn't much room on the timeline for a wide range of curve
4822 values.  You need to zoom the curves in and out vertically to have any
4823 variability.  This is done by 2 tools: the automation fit button
4824 @image{fitautos} and automation zoom menu @image{autozoom}.
4825
4826 The automation fit button scales and offsets the vertical range so the
4827 selected curve area appears in the timeline.  If a region of the
4828 timeline is highlighted by the cursor, only that region is scaled. 
4829 In/out points don't affect the zoomed region.  @b{Alt-f} also performs
4830 automation fitting.
4831
4832 The automation zoom menu manually changes the vertical scaling of the
4833 curves in multiples of 2.  Click on its tumbler to change the zoom. 
4834 @b{Alt-Up and Alt-Dn} change the automation zoom from the keyboard.
4835
4836
4837 @node TOGGLE KEYFRAMES
4838 @section TOGGLE KEYFRAMES
4839
4840 Mute is the only toggle keyframe.  Mute keyframes determine where the
4841 track is processed but not rendered to the output.  Click-drag on these
4842 curves to create a keyframe.  Unlike curves, the toggle keyframe has
4843 only two values: on or off.  Ctrl and shift do nothing on toggle
4844 keyframes.
4845
4846
4847
4848
4849
4850
4851 @node AUTOMATIC KEYFRAMES
4852 @section AUTOMATIC KEYFRAMES
4853
4854 You may have noticed when a few fade curves are set up, moving the
4855 insertion point around the curves causes the faders to reflect the
4856 curve value under the insertion point.  This isn't just to look cool. 
4857 The faders themselves can set keyframes in automatic keyframe mode. 
4858 Automatic keyframe mode is usually more useful than dragging curves.
4859
4860 Enable automatic keyframe mode by enabling the automatic keyframe
4861 toggle @image{autokeyframe}.  In automatic keyframe mode, every time
4862 you tweek a keyframeable parameter it creates a keyframe on the
4863 timeline.  Since automatic keyframes affect many parameters, it's best
4864 enabled just before you need a keyframe and disabled immediately
4865 thereafter.
4866
4867 It's useful to go into the @b{View} menu and make the desired
4868 parameter visible before performing a change.  The location where the
4869 automatic keyframe is generated is under the insertion point.  If the
4870 timeline is playing back during a tweek, several automatic keyframes
4871 will be generated as you change the parameter.
4872
4873 When automatic keyframe mode is disabled, a similarly strange thing
4874 happens.  Adjusting a parameter adjusts the keyframe immediately
4875 preceeding the insertion point.  If two fade keyframes exist and the
4876 insertion point is between them, changing the fader changes the first
4877 keyframe.
4878
4879 There are many parameters which can only be keyframed in automatic
4880 keyframe mode.  These are parameters for which curves would take up too
4881 much space on the track or which can't be represented easily by a
4882 curve.
4883
4884 Effects are only keyframable in automatic mode because of the number of
4885 parameters in each individual effect.  
4886
4887 Camera and projector translation can only be keyframed in automatic
4888 keyframe mode while camera and projector zoom can be keyframed with
4889 curves.  It is here that we conclude the discussion of compositing,
4890 since compositing is highly dependant on the ability to change over
4891 time.
4892
4893
4894
4895 @node COMPOSITOR KEYFRAMES
4896 @section COMPOSITOR KEYFRAMES
4897
4898 Camera and projector translation is represented by two parameters: x
4899 and y.  Therefore it is cumbersome to adjust with curves.  Cinelerra
4900 solves this problem by relying on automatic keyframes.  With a video
4901 track loaded, move the insertion point to the beginning of the track
4902 and enable automatic keyframe mode.
4903
4904 Move the projector slightly in the compositor window to create a
4905 keyframe.  Then go forward several seconds.  Move the projector a long
4906 distance to create another keyframe and emphasize motion.  This creates
4907 a second projector box in the compositor, with a line joining the two
4908 boxes.  The joining line is the motion path.  If you create more
4909 keyframes, more boxes are created.  Once all the desired keyframes are
4910 created, disable automatic keyframe mode.
4911
4912 Now when scrubbing around with the compositor window's slider, the
4913 video projection moves over time.  At any point between two keyframes,
4914 the motion path is read for all time before the insertion point and
4915 green for all time after the insertion point.  It's debatable if this
4916 is a very useful feature but it makes you feel good to know what
4917 keyframe is going to be affected by the next projector tweek.
4918
4919 Click-drag when automatic keyframes are off to adjust the preceeding
4920 keyframe.  If you're halfway between two keyframes, the first projector
4921 box is adjusted while the second one stays the same.  Furthermore, the
4922 video doesn't appear to move in step with the first keyframe.  This is
4923 because, halfway between two keyframes the projector translation is
4924 interpolated.  In order to set the second keyframe you'll need to scrub
4925 after the second keyframe.
4926
4927 By default the motion path is a straight line, but it can be curved
4928 with control points.  @b{Ctrl-drag} to set either the in or out
4929 control point of the preceeding keyframe.  Once again, we depart from
4930 The Gimp because @b{shift} is already used for zoom.  After the in
4931 or out control points are extrapolated from the keyframe,
4932 @b{Ctrl-dragging} anywhere in the video adjusts the nearest control
4933 point.  A control point can be out of view entirely yet still
4934 controllable.
4935
4936 When editing the camera translation, the behavior of the camera boxes
4937 is slightly different.  Camera automation is normally used for still
4938 photo panning.  The current camera box doesn't move during a drag, but
4939 if multiple keyframes are set, every camera box except the current
4940 keyframe appears to move.  This is because the camera display shows
4941 every other camera position relative to the current one.
4942
4943 The situation becomes more intuitive if you bend the motion path
4944 between two keyframes and scrub between the two keyframes.  The
4945 division between red and green, the current position between the
4946 keyframes, is always centered while the camera boxes move.
4947
4948
4949
4950
4951
4952
4953 @node EDITING KEYFRAMES
4954 @section EDITING KEYFRAMES
4955
4956 Keyframes can be shifted around and moved between tracks on the
4957 timeline using similar cut and paste operations to editing media.  Only
4958 the keyframes selected in the @b{view} menu are affected by keyframe
4959 editing operations, however.
4960
4961 The most popular keyframe editing operation is replication of some
4962 curve from one track to the other, to make a stereo pair.  The first
4963 step is to solo the source track's record @image{recordpatch} patch
4964 by @b{shift-clicking} on it.  Then either set in/out points or
4965 highlight the desired region of keyframes.  Go to @b{keyframes->copy
4966 keyframes} to copy them to the clipboard.  Solo the destination track's
4967 record @image{recordpatch} patch by @b{shift-clicking} on it and
4968 go to @b{keyframes->paste keyframes} to paste the clipboard.
4969
4970 The media editing commands are mapped to the keyframe editing commands
4971 by using the @b{shift} key instead of just the keyboard shortcut.  
4972
4973 This leads to the most complicated part of keyframe editing, the
4974 default keyframe.  Remember that when no keyframes are set at all,
4975 there is still a default keyframe which stores a global parameter for
4976 the entire duration.  The default keyframe isn't drawn because it
4977 always exists.  What if the default keyframe is a good value which you
4978 want to transpose between other non-default keyframes?  The
4979 @b{keyframes->copy default keyframe} and @b{keyframes->paste
4980 default keyframe} allow conversion of the default keyframe to a
4981 non-default keyframe.
4982
4983 @b{Keyframes->copy default keyframe} copies the default keyframe to
4984 the clipboard, no matter what region of the timeline is selected.  The
4985 @b{keyframes->paste keyframes} function may then be used to paste
4986 the clipboard as a non-default keyframe.
4987
4988 If you've copied a non-default keyframe, it can be stored as the
4989 default keyframe by calling @b{keyframes->paste default keyframe}. 
4990 After using paste default keyframe to convert a non-default keyframe
4991 into a default keyframe, you won't see the value of the default
4992 keyframe reflected until all the non-default keyframes are removed.
4993
4994 Finally, there is a convenient way to delete keyframes besides
4995 selecting a region and calling @b{keyframes->clear keyframes}. 
4996 Merely click-drag a keyframe before its preceeding keyframe or after
4997 its following keyframe on the track.
4998
4999
5000
5001 @node KEYFRAME SPANNING
5002 @section KEYFRAME SPANNING
5003
5004
5005
5006 To change a single parameter in multiple keyframes without changing the
5007 other parameters, highlight a region on the timeline and adjust the
5008 parameter.  Instead of a new keyframe being created, the existing
5009 keyframes are modified and only the changed parameter is modified.
5010
5011 It doesn't matter if @image{autokeyframe} auto keyframe is enabled.  It
5012 only works when the keyframe stores multiple parameters.  Only mask and
5013 effect keyframes do this.  Other types of keyframes are generated as usual.
5014
5015
5016
5017
5018
5019
5020
5021
5022
5023
5024
5025 @node CAPTURING MEDIA
5026 @chapter CAPTURING MEDIA
5027
5028 Ideally, all media would be stored on hard drives, CD-ROM, flash, or
5029 DVD and loading it into Cinelerra would be a matter of loading a file. 
5030 In reality, very few sources of media can be accessed like a filesystem
5031 but instead rely on tape transport mechanisms and dumb I/O mechanisms
5032 to transfer the data to computers.  These media types are imported into
5033 Cinelerra through the Record dialog.
5034
5035 The first step in recording is to configure the input device.  In
5036 @b{Settings->preferences} are a number of recording parameters
5037 described in configuration @xref{RECORDING}.  These parameters apply to
5038 recording no matter what the project settings are, because the
5039 recording parameters are usually the maximum capability of the
5040 recording hardware while project settings come and go.
5041
5042 Go to @b{File->record} to record a dumb I/O source.  This prompts
5043 for an output format much like rendering does.  Once that's done, the
5044 record window and the record monitor pop up.
5045
5046 The record window has discrete sections.  While many parameters change
5047 depending on if the file has audio or video, the discrete sections are
5048 always the same.
5049
5050 @itemize
5051
5052 @item
5053
5054 The output format area describes the format of the output file and the
5055 current position within it.
5056
5057
5058 @item
5059
5060 The edit batch area lets you change parameters in the current batch.
5061
5062 @item
5063
5064 The transport controls start and stop recording different ways.
5065
5066 @item
5067
5068 The batch list displays all the defined batches.
5069
5070 @item
5071
5072 The confirmation area lets you determine how the output files are
5073 imported into the timeline and quit.
5074
5075 @end itemize
5076
5077 @image{recording}
5078 @sp 2
5079 @b{Recording window areas}
5080
5081
5082 Recording in Cinelerra is organized around batches.  A batch
5083 essentially defines a distinct output file for the recording.  For now
5084 you can ignore the batch concept entirely and record merely by hitting
5085 the record button @image{record}.
5086
5087 The record button opens the current output file if it isn't opened and
5088 writes captured data to it.  Use the stop button to stop the
5089 recording.  Recording can be resumed with the record button without
5090 erasing the file at this point.  In the case of a video file, there is
5091 a single frame record button @image{singleframe} which records a single
5092 frame.
5093
5094 When enough media is recorded, choose an insertion method from the
5095 @b{Insertion Strategy} menu and hit @b{close}.
5096
5097
5098
5099
5100 @menu
5101 * BATCHES::
5102 * EDITING TUNER INFORMATION::
5103 @end menu
5104
5105
5106
5107
5108 @node BATCHES
5109 @section BATCHES
5110
5111 Now we come to the concept of batches.  Batches try to make the dumb
5112 I/O look more like a filesystem.  Batches are traditionally used to
5113 divide tape into different programs and save the different programs as
5114 different files instead of recording straight through an entire tape. 
5115 Because of the high cost of developing frame-accurate deck control
5116 mechanisms, the only use of batches now is recording different programs
5117 during different times of day.  This is still useful for recording TV
5118 shows or time lapse movies as anyone who can't afford proper appliances
5119 knows.
5120
5121 The record window supports a list of batches and two recording modes:
5122 interactive and batch recording.  Interactive recording happens when
5123 the record button is pressed.  Interactive recording starts immediately
5124 and uses the current batch to determine everything except start time. 
5125 By default, the current batch is configured to behave like tape.
5126
5127 Batch recording happens when the @b{start} button is pressed.  In
5128 batch recording, the @b{start time} is the time the batch starts
5129 recording.
5130
5131 First, you'll want to create some batches.  Each batch has certain
5132 parameters and methods of adjustment.  
5133
5134
5135
5136
5137 @itemize
5138
5139 @item 
5140
5141 @b{On} determines whether the batch is included in batch recording
5142 operations.  Click the list row under @b{On} to enable or disable
5143 batches.
5144
5145
5146 @item 
5147
5148 @b{Path} is the file the batch is going to be recorded to.  The
5149 filename specified in the record dialog is the name of the first batch,
5150 to simplify interactive recording, but the filename may be changed in
5151 the record window for any batch in the @b{edit batch} area.
5152
5153
5154 @item
5155
5156 @b{News} shows whether the file exists or not.  This is a very
5157 important attribute since there is no confirmation dialog if the file
5158 exists.  The first time you hit record, the file is opened.  If the
5159 file exists at this point it's erased.  News says @b{File exists} if
5160 it exists and @b{OK} if it doesn't.  Every time you resume recording
5161 in the same batch, the news should say @b{Open}, indicating the file
5162 is already opened and won't be erased in the next record button press.
5163
5164 If you change out of the current batch after recording, the file is
5165 closed.  Next time you change into the batch, the file will be erased.
5166
5167 @item
5168
5169 @b{Start time} is the 24 hour time of day the batch will start
5170 recording if in batch mode.  The start time may become a time of tape
5171 and reel number if deck control is implemented but for now it's a time
5172 of day.
5173
5174 @item
5175
5176 @b{Duration} is the length of the batch.  It only has meaning if the
5177 @b{Mode} of the batch is @b{Timed}.  Once the recording length
5178 reaches @b{duration} the recording stops, whether in interactive or
5179 batch mode.
5180
5181 @item
5182
5183 @b{Source} has meaning only when the capturing hardware has multiple
5184 sources.  Usually the source is a tuner channel or input.  When the
5185 current batch finishes and the next batch begins recording, the source
5186 is changed to what the next batch is set to.  This way multiple TV
5187 stations can be recorded at different times.
5188
5189
5190 @end itemize
5191
5192 The record window has a notion of the @b{current batch}.  The
5193 current batch is not the same as the batch which is highlighted in the
5194 batch list.  The current batch text is colored red in the batch list. 
5195 The highlighted batch is merely displayed in the edit batch section for
5196 editing.
5197
5198 By coloring the current batch red, any batch can be edited by
5199 highlighting it, without changing the batch to be recorded.
5200
5201 All recording operations take place in the current batch.   If there
5202 are multiple batches, highlight the desired batch and hit
5203 @b{activate} to make it the current batch.  If the @b{start}
5204 button is pressed, the current batch flashes to indicate it's waiting
5205 for the start time in batch mode.  If the @b{record} button is
5206 pressed, the current batch is recorded immediately in interactive mode.
5207
5208 In batch and interactive recording modes, when the current batch
5209 finishes recording the next batch is activated and performed.  All
5210 future recording is done in batch mode.  When the first batch finishes,
5211 the next batch flashes until its start time is reached.
5212
5213 Interrupt either the batch or the interactive operation by hitting the
5214 stop button.
5215
5216 Finally there is the @image{rewind} rewind button.  In either
5217 interactive or batch recording, the rewind button causes the current
5218 batch to close its file.  The next recording operation in the current
5219 batch deletes the file.
5220
5221
5222
5223
5224
5225
5226 @node EDITING TUNER INFORMATION
5227 @section EDITING TUNER INFORMATION
5228
5229
5230 Sometimes in the recording process and the configuration process,
5231 you'll need to define and select tuner channels to either record or
5232 play back to.  In the case of the Video4Linux and Buz recording
5233 drivers, tuner channels define the source.  When the Buz driver is also
5234 used for playback, tuner channels define the destination.  
5235
5236 Defining tuner channels is accomplished by pushing the @image{channel}
5237 channel button.  This brings up the channel editing window.  In this
5238 window you add, edit, and sort channels.  Also, for certain video
5239 drivers, you can adjust the picture quality.
5240
5241 The @b{add} operation brings up a channel editing box.  The title of
5242 the channel appears in the channel list.  The source of the channel is
5243 the entry in the physical tuner's frequency table corresponding to the
5244 title.  
5245
5246 Fine tuning in the channel edit dialog adjusts the physical frequency
5247 slightly if the driver supports it.  The norm and frequency table
5248 together define which frequency table is selected for defining
5249 sources.  If the device supports multiple inputs, the input menu
5250 selects these.
5251
5252 To sort channels, highlight the channel in the list and push @b{move
5253 up} or @b{move down} to move it.
5254
5255 Once channels are defined, the @b{source} item in the record window
5256 can be used to select channels for recording.  The same channel
5257 selecting ability also exists in the record monitor window.  Be aware
5258 channel selections in the record monitor window and the record window
5259 are stored in the current batch.
5260
5261 For some drivers an option to @b{swap fields} may be visible.  These
5262 drivers don't get the field order right every time without human
5263 intervention.  Toggle this to get the odd and even lines to record in
5264 the right order.
5265
5266
5267
5268
5269 @node IMPROVING PERFORMANCE
5270 @chapter IMPROVING PERFORMANCE
5271
5272
5273 Let's get one thing perfectly clear.  Linux is not a very good
5274 desktop.  It's a server.  Most of what you'll find on modern Linux
5275 distributions are faceless, network-only programs strategicly designed
5276 to counteract one Microsoft server feature or another and not to
5277 perform very well at user interaction.  There are a number of
5278 parameters on Linux, which ordinary people can adjust to make it behave
5279 more like a thoroughbred in desktop usage.
5280
5281
5282 @menu
5283 * DISABLING SWAP SPACE::
5284 * ENLARGING SOUND BUFFERS::
5285 * FREEING MORE SHARED MEMORY::
5286 * SPEEDING UP THE HARD DRIVE::
5287 * DISABLING CRON::
5288 * REDUCING USB MOUSE SENSITIVITY::
5289 * ASSORTED X TWEEKS::
5290 * SPEEDING UP THE FILE SYSTEM::
5291 * IMPROVING ZORAN VIDEO::
5292 @end menu
5293
5294 @node DISABLING SWAP SPACE
5295 @section DISABLING SWAP SPACE
5296
5297 On systems with lots of memory, Cinelerra sometimes runs better without
5298 a swap space.  If you have 4 GB of RAM, you're probably better off
5299 without a swap space.  If you have 512MB of RAM, you should keep the
5300 swap.  If you want to do recording, you should probably disable swap
5301 space in any case.  There's a reason for this.  Linux only allows half
5302 the available memory to be used.  Beyond that, it starts searching for
5303 free pages to swap, in order to cache more disk access.  In a 4 GB
5304 system, you start waiting for page swaps after using only 2 GB.  
5305
5306 The question then is how to make Linux run without a swap space. 
5307 Theoretically it should be a matter of running
5308
5309 @example
5310 swapoff -a
5311 @end example
5312
5313 Unfortunately, without a swap space the @b{kswapd} tasklet normally
5314 spins at 100%.  To eliminate this problem, edit @b{linux/mm/vmscan.c}.
5315 In this file, put a line saying @b{return 0;} before it says 
5316
5317 @example
5318         /*
5319          * Kswapd main loop.
5320          */
5321 @end example
5322
5323 Then recompile the kernel.
5324
5325
5326
5327
5328 @node ENLARGING SOUND BUFFERS
5329 @section ENLARGING SOUND BUFFERS
5330
5331 In order to improve realtime performance, the audio buffers for all the
5332 Linux sound drivers were limited from 128k to 64k.  For recording audio
5333 and video simultaneously and for most audio recording this causes
5334 dropouts.  Application of low latency and preemtible kernel patches
5335 make it possible to record more audio recordings but it doesn't improve
5336 recording video with audio.  This is where you need to hack the kernel.
5337
5338 To see if your sound buffers are suitable, run the included
5339 @b{soundtest} program with nothing playing or recording.  This
5340 allocates the largest possible buffers and displays them.  If the
5341 @b{TOTAL BYTES AVAILABLE} is under 131072, you need to see about
5342 getting the buffers enlarged in the driver.  While many drivers differ,
5343 we have a hack for at least one driver.
5344
5345 This only applies to the OSS version of the Soundblaster Live driver. 
5346 Since every sound card and every sound driver derivative has a
5347 different implementation you'll need to do some searching for other
5348 sound cards.  Edit @b{linux/drivers/sound/emu10k1/audio.c}
5349
5350 Where is says
5351
5352 @example
5353 if (bufsize >= 0x10000)
5354 @end example
5355
5356 change it to say
5357
5358 @example
5359 if (bufsize > 0x40000)
5360 @end example
5361
5362
5363
5364 Where is says
5365
5366 @example
5367                 for (i = 0; i < 8; i++)
5368                         for (j = 0; j < 4; j++)
5369 @end example
5370
5371 change it to say
5372
5373 @example
5374                 for (i = 0; i < 16; i++)
5375                         for (j = 0; j < 4; j++)
5376 @end example
5377
5378
5379
5380 In @b{linux/drivers/sound/emu10k1/hwaccess.h}
5381
5382 Change
5383
5384 @b{#define MAXBUFSIZE   65536} 
5385
5386 to 
5387
5388 @b{#define MAXBUFSIZE   262144} 
5389
5390 Finally, in @b{linux/drivers/sound/emu10k1/cardwi.h}
5391
5392 @b{#define WAVEIN_MAXBUFSIZE         65536}
5393
5394 to
5395
5396 @b{#define WAVEIN_MAXBUFSIZE         262144}
5397
5398 Then recompile the kernel modules.
5399
5400
5401
5402
5403
5404
5405 @node FREEING MORE SHARED MEMORY
5406 @section FREEING MORE SHARED MEMORY
5407
5408 The Linux kernel only allows 32MB of shared memory to be allocated by
5409 default.  This needs to be increased to do anything useful.  Run the
5410 following command:
5411
5412 @b{echo "0x7fffffff" > /proc/sys/kernel/shmmax}
5413
5414
5415
5416
5417
5418 @node SPEEDING UP THE HARD DRIVE
5419 @section SPEEDING UP THE HARD DRIVE
5420
5421 This is a very popular command sequence among Linux gurus, which is not
5422 done by default on Linux distributions.
5423
5424 @b{hdparm -c3 -d1 -u1 -k1 /dev/hda}
5425
5426 @b{-c3} puts the hard drive into 32 bit I/O with sync.  This normally
5427 doesn't work due to inept kernel support for most IDE controllers.  If
5428 you get lost interrupt or SeekComplete errors, quickly use @b{-c0}
5429 instead of @b{-c3} in your command.
5430
5431 @b{-d1} enables DMA of course.  This frees up the CPU partially during
5432 data transfers.
5433
5434 @b{-u1} allows multiple interrupts to be handled during hard drive
5435 transactions.  This frees up even more CPU time.
5436
5437 @b{-k1} prevents Linux from resetting your settings in case of a
5438 glitch.
5439
5440
5441
5442
5443
5444 @node DISABLING CRON
5445 @section DISABLING CRON
5446
5447 Linux runs some daily operations like compressing man pages.  These may
5448 be acceptable background tasks while compiling or word processing but
5449 not while playing video.  Disable these operations by editing
5450 @b{/etc/rc.d/init.d/anacron}.
5451
5452 Put @b{exit} before the first line not beginning in @b{#}.
5453
5454 In @b{/etc/rc.d/init.d/crond} put @b{exit} before the first line not
5455 beginning in @b{#}.  Then make like Win 2000 and reboot.
5456
5457 You can't use the @b{at} command anymore, but who uses that command
5458 anyways?
5459
5460
5461
5462
5463
5464
5465
5466
5467
5468 @node REDUCING USB MOUSE SENSITIVITY
5469 @section REDUCING USB MOUSE SENSITIVITY
5470
5471 Gamers like high resolution mice, but this can be painful for precisely
5472 positioning the mouse on a timeline or video screen.  XFree86 once
5473 allowed you to reduce PS/2 mouse sensitivity using commands like
5474 @b{xset m 1 1} but you're out of luck with USB mice or KVM's.
5475
5476 We have a way to reduce USB mouse sensitivity but it requires editing
5477 the kernel source code.  Even though USB mice have been supported for
5478 years, the kernel source code for USB mice is constantly being
5479 rewritten.  These instructions were relevant for 2.6.12.3.  Edit
5480 @b{/usr/src/linux/drivers/input/mousedev.c}.  
5481
5482 After the line saying 
5483
5484 @example
5485 struct mousedev_hw_data @{
5486 @end example
5487
5488
5489 put
5490
5491 @example
5492 #define DOWNSAMPLE_N 100
5493 #define DOWNSAMPLE_D 350
5494 int x_accum, y_accum;
5495 @end example
5496
5497 Next, the section which says something like:
5498
5499 @example
5500 switch (code) @{
5501         case REL_X:     mousedev->packet.dx += value; break;
5502         case REL_Y:     mousedev->packet.dy -= value; break;
5503         case REL_WHEEL: mousedev->packet.dz -= value; break;
5504 @}
5505 @end example
5506
5507 must be replaced by
5508
5509 @example
5510
5511         switch (code) @{
5512                 case REL_X:
5513                         mousedev->packet.x_accum += value * DOWNSAMPLE_N;
5514                         mousedev->packet.dx += (int)mousedev->packet.x_accum / (int)DOWNSAMPLE_D;
5515                         mousedev->packet.x_accum -= ((int)mousedev->packet.x_accum / (int)DOWNSAMPLE_D) * (int)DOWNSAMPLE_D;
5516                         break;
5517                 case REL_Y:
5518                         mousedev->packet.y_accum += value * DOWNSAMPLE_N;
5519                         mousedev->packet.dy -= (int)mousedev->packet.y_accum / (int)DOWNSAMPLE_D;
5520                         mousedev->packet.y_accum -= ((int)mousedev->packet.y_accum / (int)DOWNSAMPLE_D) * (int)DOWNSAMPLE_D;
5521                         break;
5522                 case REL_WHEEL: mousedev->packet.dz -= value; break;
5523         @}
5524
5525
5526
5527 @end example
5528
5529 Change the value of @b{DOWNSAMPLE_N} to change the mouse sensitivity.
5530
5531
5532
5533
5534
5535
5536
5537
5538 @node ASSORTED X TWEEKS
5539 @section ASSORTED X TWEEKS
5540
5541
5542 XFree86 by default can't display Cinelerra's advanced pixmap rendering
5543 very fast.  The X server stalls during list box drawing.  Fix this by
5544 adding a line to your XF86Config* files.
5545
5546 In the @b{Section "Device"} area, add a line saying:
5547
5548 @b{Option "XaaNoOffscreenPixmaps"}
5549
5550 and restart the X server.
5551
5552
5553
5554 Screen blanking is really annoying, unless you're fabulously rich and
5555 can afford to leave your monitor on 24 hours a day without power saving
5556 mode.  In @b{/etc/X11/xinit/xinitrc} put 
5557
5558 @example
5559 xset s off
5560 xset s noblank
5561 @end example
5562
5563 before the first @b{if} statement.
5564
5565 How about those windows keys which no Linux distribution even thinks to
5566 use.  You can make the window keys provide ALT functionality by editing
5567 @b{/etc/X11/Xmodmap}.  Append the following to it.
5568
5569 @example
5570 keycode 115 = Hyper_L
5571 keycode 116 = Hyper_R
5572 add mod4 = Hyper_L
5573 add mod5 = Hyper_R
5574 @end example
5575
5576 The actual changes to a window manager to make it recognize window keys
5577 for ALT are complex.  In @b{FVWM} at least, you can edit
5578 @b{/etc/X11/fvwm/system.fvwm2rc} and put
5579
5580 @example
5581 Mouse 0 T A move-and-raise-or-raiselower
5582 #Mouse 0 W M move
5583 Mouse 0 W 4 move
5584 Mouse 0 W 5 move
5585 Mouse 0 F A resize-or-raiselower
5586 Mouse 0 S A resize-or-raiselower
5587 @end example
5588
5589 in place of the default section for moving and resizing.  Your best
5590 performance is going to be on FVWM.  Other window managers seem to slow
5591 down video with extra event trapping and aren't as efficient in layout.
5592
5593
5594
5595
5596
5597
5598
5599
5600
5601
5602
5603 @node SPEEDING UP THE FILE SYSTEM
5604 @section SPEEDING UP THE FILE SYSTEM
5605
5606 You'll often store video on an expensive, gigantic disk array separate
5607 from your boot disk.  You'll thus have to manually install an EXT
5608 filesystem on this disk array, using the @b{mke2fs} command.  By far
5609 the fastest file system is 
5610
5611 @example
5612
5613 mke2fs -i 65536 -b 4096 my_device
5614 tune2fs -r0 -c10000 my_device
5615
5616 @end example
5617
5618 This has no journaling, reserves as few blocks as possible for
5619 filenames, and accesses the largest amount of data per block possible.
5620 A slightly slower file system, which is easier to recover after power
5621 failures is
5622
5623 @example
5624
5625 mke2fs -j -i 65536 -b 4096 my_device
5626 tune2fs -r0 -c10000 my_device
5627
5628 @end example
5629
5630 This adds a journal which slows down the writes but makes us immune to
5631 power failures.
5632
5633
5634
5635
5636
5637
5638
5639 @node IMPROVING ZORAN VIDEO
5640 @section IMPROVING ZORAN VIDEO
5641
5642 Video recorded from the ZORAN inputs is normally unaligned or not
5643 completely encoded on the right.  This can be slightly compensated by
5644 adjusting parameters in the driver sourcecode.
5645
5646 In @b{/usr/src/linux/drivers/media/video/zr36067.c} the structures
5647 defined near line 623 affect alignment.  At least for NTSC, the 2.4.20
5648 version of the driver could be improved by changing 
5649
5650 @example
5651 static struct tvnorm f60ccir601 = @{ 858, 720, 57, 788, 525, 480, 16 @};
5652 @end example
5653
5654 to
5655
5656 @example
5657 static struct tvnorm f60ccir601 = @{ 858, 720, 57, 788, 525, 480, 17 @};
5658 @end example
5659
5660
5661 In @b{/usr/src/linux/drivers/media/video/bt819.c} more structures near
5662 line 76 affect alignment and encoding.
5663
5664 For NTSC 
5665
5666 @example
5667 @{858 - 24, 2, 523, 1, 0x00f8, 0x0000@},
5668 @end example
5669
5670 could be changed to 
5671 @example
5672 @{868 - 24, 2, 523, 1, 0x00f8, 0x0000@},
5673 @end example
5674
5675 Adjusting these parameters may or may not move your picture closer to
5676 the center.  More of the time, they'll cause the driver to lock up
5677 before capturing the first frame.
5678
5679
5680 @subsection NEW IN 2.6.5
5681
5682 In the 2.6 kernels, the video subsystem was rewritten again from
5683 scratch.  To adjust the Zoran parameters go to
5684 @b{drivers/media/video/zoran_card.c} and look for a group of lines like
5685
5686 @example
5687 static struct tvnorm f50sqpixel = @{ 944, 768, 83, 880, 625, 576, 16 @};
5688 static struct tvnorm f60sqpixel = @{ 780, 640, 51, 716, 525, 480, 12 @};
5689 static struct tvnorm f50ccir601 = @{ 864, 720, 75, 804, 625, 576, 18 @};
5690 static struct tvnorm f60ccir601 = @{ 858, 720, 57, 788, 525, 480, 16 @};
5691
5692 static struct tvnorm f50ccir601_lml33 = @{ 864, 720, 75+34, 804, 625, 576, 18 @};
5693 static struct tvnorm f60ccir601_lml33 = @{ 858, 720, 57+34, 788, 525, 480, 16 @};
5694
5695 /* The DC10 (57/16/50) uses VActive as HSync, so HStart must be 0 */
5696 static struct tvnorm f50sqpixel_dc10 = @{ 944, 768, 0, 880, 625, 576, 0 @};
5697 static struct tvnorm f60sqpixel_dc10 = @{ 780, 640, 0, 716, 525, 480, 12 @};
5698
5699 /* FIXME: I cannot swap U and V in saa7114, so i do one
5700  * pixel left shift in zoran (75 -> 74)
5701  * (Maxim Yevtyushkin <max@@linuxmedialabs.com>) */
5702 static struct tvnorm f50ccir601_lm33r10 = @{ 864, 720, 74+54, 804, 625, 576, 18 @};
5703 static struct tvnorm f60ccir601_lm33r10 = @{ 858, 720, 56+54, 788, 525, 480, 16 @};
5704 @end example
5705
5706 These seem to control the image position.  At least for the LML33 the
5707 following definition for @b{f60ccir601_lml33} does the trick.
5708
5709 @example
5710 static struct tvnorm f60ccir601_lml33 = @{ 858, 720, 67+34, 788, 525, 480, 13 @};
5711 @end example
5712
5713
5714
5715
5716
5717
5718 @node TROUBLESHOOTING
5719 @chapter TROUBLESHOOTING
5720
5721
5722 @menu
5723 * BUZ DRIVER CRASHES::
5724 * DRAGGING IN AND OUT POINTS DOESN'T WORK::
5725 * LOCKING UP WHEN LOADING FILES::
5726 * SYNCHRONIZATION LOST WHILE RECORDING::
5727 * APPLYING LINEARIZE FOLLOWED BY BLUR DOESN'T WORK::
5728 @end menu
5729
5730 @node BUZ DRIVER CRASHES
5731 @section BUZ DRIVER CRASHES
5732
5733 First, Zoran capture boards must be accessed using the @b{Buz} video
5734 driver in @b{Preferences->Recording} and @b{Preferences->Playback}. 
5735 Some performance tweeks are available in another section. 
5736 @xref{IMPROVING PERFORMANCE}.
5737
5738 Once tweeked, the Buz driver seems to crash if the number of recording
5739 buffers is too high.  Make sure @b{Preferences->Recording->Frames to
5740 buffer in device} is below 10.
5741
5742
5743 @node DRAGGING IN AND OUT POINTS DOESN'T WORK
5744 @section DRAGGING IN AND OUT POINTS DOESN'T WORK
5745
5746
5747 Sometimes there will be two edits really close together.  The point
5748 selected for dragging may be next to the indended edit on an edit too
5749 small to see at the current zoom level.  Zoom in horizontally.
5750
5751
5752
5753 @node LOCKING UP WHEN LOADING FILES
5754 @section LOCKING UP WHEN LOADING FILES
5755
5756
5757 The most common reason loading files locks up is because the codec
5758 isn't supported.  Another reason is because Cinelerra is building
5759 picons for the Resources window.  If you load a large number of images,
5760 it needs to decompress every single image to build a picon.  Go into
5761 settings->preferences->interface and disable @b{Use thumbnails in
5762 resource window} to skip this process.
5763
5764
5765
5766
5767
5768 @node SYNCHRONIZATION LOST WHILE RECORDING
5769 @section SYNCHRONIZATION LOST WHILE RECORDING
5770
5771 If the framerate of the recording is much lower than the framerate of
5772 the source, the video will accumulate in the recording buffers over
5773 time while the audio and video are well out of sync.  Decrease the
5774 @b{number of frames to buffer in the device} in
5775 @b{preferences->recording} so the excess frames are dropped instead of
5776 buffered.
5777
5778 @node APPLYING LINEARIZE FOLLOWED BY BLUR DOESN'T WORK
5779 @section APPLYING LINEARIZE FOLLOWED BY BLUR DOESN'T WORK
5780
5781 The linearize effect uses the pow function while the blur effect uses a
5782 number of exp functions in the math library.  For some reason, using
5783 the pow function breaks later calls to the exp functions in the math
5784 library.  You need to apply linearize after blur to get it to work.
5785
5786
5787
5788
5789
5790
5791
5792
5793
5794
5795 @node SECRETS OF CINELERRA
5796 @chapter SECRETS OF CINELERRA
5797
5798 In this section, you'll find ways to apply Cinelerra to common
5799 problems.  Other sections are arranged in order of the tools and what
5800 the tools are used for.  This section is arranged in order of the
5801 problems and what tools are used to solve the problems.
5802
5803 @menu
5804 * DOLBY PRO LOGIC ENCODING::
5805 * ANALOG TV CLEANING::
5806 * DEFEATING INTERLACING::
5807 * MAKING VIDEO LOOK LIKE FILM::
5808 * CLEARING OUT HAZE::
5809 * MAKING A DVD::
5810 * MAKING A RINGTONE::
5811 * TIME STRETCHING AUDIO::
5812 * PITCH SHIFTING AUDIO::
5813 * TEXT TO MOVIE::
5814 @end menu
5815
5816
5817 @node DOLBY PRO LOGIC ENCODING
5818 @section DOLBY PRO LOGIC ENCODING
5819
5820 Dolby pro logic is an easy way to output 6 channel audio from a 2
5821 channel soundcard with degraded but useful results.  Rudimentary Dolby
5822 pro logic encoding can be achieved with clever usage of the effects.
5823
5824 Create 2 audio tracks with the same audio.  Apply @b{invert audio} to
5825 one track.  The signal comes out of the back speakers.
5826
5827 Create a single audio track with monaural audio of a different source. 
5828 Center it in the @b{pan} control.  The signal comes out of the center
5829 speaker.
5830
5831 Create other tracks with different signals and pan them left or right
5832 to put signals in the front left or right speaker.
5833
5834 Finally, if a copy of the signal in the back speakers is desired in any
5835 single front speaker, the signal in the back speakers must be delayed
5836 by at least 0.05 seconds and a single new track should be created.  Pan
5837 the new track to orient the signal in the front speakers.
5838
5839 If the same signal is desired in all the speakers except the center
5840 speaker, delay the back speakers by 0.5 seconds and delay either the
5841 front left or front right by 0.2 seconds.
5842
5843 If you want to hear something from the subwoofer, create a new track,
5844 select a range, drop a synthesizer effect, and set the frequency below
5845 60 Hz.  The subwoofer merely plays anything below around 60Hz.
5846
5847 Other tricks you can perform to separate the speakers are parametric
5848 equalization to play only selected ranges of frequencies through
5849 different speakers and lowpass filtering to play signals through the
5850 subwoofer.
5851
5852
5853
5854
5855 @node ANALOG TV CLEANING
5856 @section ANALOG TV CLEANING
5857
5858
5859 Unless you live in a rich nation like China or are a terrorist, you
5860 probably record analog TV more than you record digital TV.  The picture
5861 quality on analog TV is horrible but you can do things in Cinelerra to
5862 make it look more like it did in the studio.
5863
5864 First, when capturing the video, capture it in the highest resolution
5865 possible.  For Europeans it's 720x576 and for Americans it's 720x480. 
5866 Don't bother adjusting the brightness or contrast in the recording
5867 monitor, although maxing out the color is useful.  Capture it using
5868 MJPEG or uncompressed Component Video if possible.  If those are too
5869 demanding, then capture it using JPEG.  RGB should be a last resort.
5870
5871 Now on the timeline use @b{Settings->Format} to set a YUV colorspace. 
5872 Drop a @b{Downsample} effect on the footage.  Set it for 
5873
5874 @example
5875 Horizontal:        2
5876 Horizontal offset: 0
5877 Vertical:          2
5878 Vertical offset:   0
5879
5880       red
5881   x   green
5882   x   blue
5883       alpha
5884 @end example
5885
5886 Use the camera tool to shift the picture up or down a line to remove
5887 the most color interference from the image.  This is the difference
5888 we're looking for:
5889
5890 @sp 1
5891
5892 @image{cleaning1}
5893
5894 If you have vertical blanking information or crawls which constantly
5895 change in each frame, block them out with the @b{Mask} tool.  This
5896 improves compression ratios.
5897
5898 This is about all you can do without destroying more data than you
5899 would naturally lose in compression.  The more invasive cleaning
5900 techniques involve deinterlacing.
5901
5902
5903
5904
5905
5906 @node DEFEATING INTERLACING
5907 @section DEFEATING INTERLACING
5908
5909
5910 Interlacing is done on most video sources because it costs too much to
5911 build progressive scanning cameras and progressive scanning CRT's. 
5912 Many a consumer has been dissapointed to spend 5 paychecks on a
5913 camcorder and discover what horrible jagged images it produces on a
5914 computer monitor.
5915
5916 As for progressive scanning camcorders, forget it.  Cost factors are
5917 probably going to keep progressive scanning cameras from ever equalling
5918 the spatial resolution of interlaced cameras.  Interlacing is here to
5919 stay.  That's why they made deinterlacing effects in Cinelerra.
5920
5921 We don't believe there has ever been a perfect deinterlacing effect. 
5922 They're either irreversible or don't work.  Cinelerra cuts down the
5923 middle by providing deinterlacing tools that are irreversible sometimes
5924 and don't work sometimes but are neither one or the other.
5925
5926 @b{Line Doubling}
5927
5928 This one is done by the @b{Deinterlace} effect when set to @b{Odd
5929 lines} or @b{Even lines}.  When applied to a track it reduces the
5930 vertical resolution by 1/2 and gives you progressive frames with
5931 stairstepping.  This is only useful when followed by a scale effect
5932 which reduces the image to half its size.
5933
5934 @b{Line averaging}
5935
5936 The @b{Deinterlace} effect when set to @b{Average even lines} or
5937 @b{Average odd lines} does exactly what line doubling does except
5938 instead of making straight copies of the lines it makes averages of the
5939 lines.  This is actually useful for all scaling.
5940
5941 There's an option for adaptive line averaging which selects which lines
5942 to line average and which lines to leave interlaced based on the
5943 difference between the lines.  It doesn't work.
5944
5945 @b{Inverse Telecine}
5946
5947 This is the most effective deinterlacing tool when the footage is an
5948 NTSC TV broadcast of a film.  @xref{INVERSE TELECINE}.
5949
5950
5951 @b{Time base correction}
5952
5953 The first three tools either destroy footage irreversibly or don't work
5954 sometimes.  @b{Time base correction} is last because it's the perfect
5955 deinterlacing tool.  It leaves the footage intact.  It doesn't reduce
5956 resolution, perceptually at least.  It doesn't cause jittery timing.
5957
5958 The @b{Frames to Fields} effect converts each frame to two frames, so
5959 it must be used on a timeline whose project frame rate is twice the
5960 footage's frame rate.  In the first frame it puts a line averaged copy
5961 of the even lines.  In the second frame it puts a line averaged copy of
5962 the odd lines.  When played back at full framerates it gives the
5963 illusion of progressive video with no loss of detail.
5964
5965 Best of all, this effect can be reversed with the @b{Fields to frames}
5966 effect.  That one combines two frames of footage back into the one
5967 original interlaced frame of half the framerate.
5968
5969 Be aware that frames to fields inputs frames at half the framerate as
5970 the project.  Effects before frames to fields process at the reduced
5971 framerate.
5972
5973 Unfortunately, the output of @b{Frames to Fields} can't be compressed
5974 as efficiently as the original because it introduces vertical twitter
5975 and a super high framerate.
5976
5977 Interlaced 29.97fps footage can be made to look like film by applying
5978 @b{Frames to Fields} and then reducing the project frame rate of the
5979 resulting 59.94fps footage to 23.97fps.  This produces no timing jitter
5980 and the occasional odd field gives the illusion of more detail than
5981 there would be if you just line averaged the original.
5982
5983
5984 @b{HDTV exceptions}
5985
5986 1920x1080 HDTV is encoded a special way.  If it's a broadcast of
5987 original HDTV film, an inverse telecine works fine.  If it's a
5988 rebroadcast of a 720x480 source, you need to use a time base and line
5989 doubling algorithm to deinterlace it, @xref{1080 TO 480}.
5990
5991
5992
5993
5994 @node MAKING VIDEO LOOK LIKE FILM
5995 @section MAKING VIDEO LOOK LIKE FILM
5996
5997
5998
5999
6000 Video sweetening is constantly getting better.  Lately the best thing
6001 you can do for dirt cheap consumer camcorder video is to turn it into
6002 progressive 24fps output.  While you can't really do that, you can get
6003 pretty close for the money.  Mind you, this procedure can degrade high
6004 quality video just as easily as it improves low quality video.  It
6005 should only be used for low quality video.
6006
6007 @itemize
6008
6009 @item
6010
6011 Step 1 - Set project framerate to twice the video framerate.
6012
6013 @item
6014
6015 Step 2 - Apply a @b{Sharpen} effect.  Set it to sharpness: 25, no
6016 interlacing, and horizontal only.
6017
6018 @item
6019
6020 Step 3 - Drop a @b{Frame to Fields} effect on the same track.  Set
6021 Average Empty Rows on and play through the video a few times to figure
6022 out which field is first.  If the wrong field is first, the motion is
6023 shaky.  Secondly, any editing in the doubled frame rate may now screw
6024 up the field order.  We're still figuring out the easiest way to
6025 support warnings for field glitches but for now you need to go back to
6026 the normal framerate to do editing or play test to make sure the fields
6027 are right.
6028
6029
6030 @item
6031
6032 Step 4 - Render just the video to the highest quality file possible.
6033
6034 @item
6035
6036 Step 5 - Import the video back to a new track.  Set the project
6037 framerate to 24.  The new track should now display more filmish and
6038 sharper images than the original footage.
6039
6040 @end itemize
6041
6042 This entire procedure could be implemented in one nonrealtime effect,
6043 but the biggest problem with that is you'll most often want to keep the
6044 field based output and the 24fps output for posterity.  A nonrealtime
6045 effect would require all that processing just for the 24fps copy. 
6046 Still debating that one.
6047
6048
6049
6050
6051
6052
6053
6054
6055
6056 @node CLEARING OUT HAZE
6057 @section CLEARING OUT HAZE
6058
6059 Let's face it, if you're employed you live in Silicon Valley.  As such
6060 you probably photograph a lot of haze and never see blue sky ever. 
6061 Even if you can afford to briefly go somewhere where there is blue sky,
6062 horizon shots usually can stand for more depth.  This is what the
6063 @b{gradient effect} is for.
6064
6065 Drop the gradient effect on hazy tracks.  Set the following parameters:
6066
6067 @example
6068 Angle: 0
6069 Inner radius: 0
6070 Outer radius: 40
6071 Inner color: blue 100% alpha
6072 Outer color: blue 0% alpha
6073 @end example
6074
6075 It's important to set the 0% alpha color to blue even though it's 0%
6076 alpha.  The color of the outer alpha is still interpolated with the
6077 inner color.  This is a generally applicable setting for the gradient. 
6078 Some scenes may work better with orange or brown for an evening feel.
6079
6080
6081
6082
6083
6084
6085
6086 @node MAKING A DVD
6087 @section MAKING A DVD
6088
6089 @b{A single chapter DVD}
6090
6091 Make a single chapter DVD by rendering video to an MPEG video file. 
6092 The video should be 720x480, 29.97fps.  The aspect ratio should be 16x9
6093 or 4x3.
6094
6095 Use the YUV 4:2:0 color model and DVD preset.  Set the bitrate to the
6096 desired bitrate.  It's not clear exactly what other parameters the MPEG
6097 encoder uses in the DVD preset but we've enabled the following:
6098
6099 @example
6100 Derivative: MPEG-2
6101 Fixed bitrate
6102 I frame distance: 15
6103 P frame distance: 0
6104 Sequence start codes in every GOP
6105 @end example
6106
6107 Render the audio to an AC3 audio file.  Any bitrate can be used.
6108
6109 @b{Dvdrtools} must be downloaded to generate the actual DVD
6110 filesystem.  The actual usage of dvdrtools changes frequently but
6111 currently it involves the mkisofs and ifogen programs.  Mkisofs is
6112 built automatically in dvdrtools but ifogen may have to be built
6113 manually by entering the @b{video} directory and running @b{make
6114 ifogen}.  Mkisofs and ifogen must be put into /usr/bin manually.
6115
6116 Also, the @b{mplex} program from @b{mjpegtools} must be installed.  The
6117 mjpegtools package is built in the hvirtual distribution and the mplex
6118 utility may be extracted from there.
6119
6120 Given the files audio.ac3 and video.m2v, rendered by Cinelerra, the
6121 following commands pack them into a dvd readable by commercial
6122 appliances.
6123
6124 @example
6125 mplex -M -f 8 -o final.mpg audio.ac3 video.m2v
6126 mkdir -p dvd/VIDEO_TS
6127 ifogen final.mpg -o dvd
6128 ifogen -T -o dvd
6129 mkisofs -dvd-video -udf -o dvd.iso dvd/
6130 @end example
6131
6132 Chapters may be set with the following.  The units are seconds.  Version
6133 0.3.1 ignores the 1st chapter, so it has to be specified as 0.
6134
6135 @example
6136 ifogen -o dvd --chapters=0,0021.788,0047.447,0077.043 final.mpg
6137 @end example
6138
6139 Replace the chapter times.
6140
6141 dvd.iso can be burned directly to a DVD with the following:
6142
6143 @example
6144 dvdrecord -ignsize -dao -v dev=/dev/hdc fs=67108864 dvd.iso
6145 @end example
6146
6147 The argument to dev= is the IDE device of the DVD drive.  Burning DVD's
6148 through SCSI is currently not supported.
6149
6150
6151
6152
6153
6154
6155
6156
6157 @node MAKING A RINGTONE
6158 @section MAKING A RINGTONE
6159
6160 This is how we made ringtones for the low end Motorola V180's and it'll
6161 probably work with any new phone.  Go to @b{File->Load files...} and
6162 load a sound file with Insertion strategy: @b{Replace current
6163 project}.  Go to @b{Settings->Format} change @b{Channels} to 1 and
6164 @b{Samplerate} to 16000 or 22050.
6165
6166 Either highlight a region of the timeline or set in/out points to use
6167 for the ringtone.  To improve sound quality on the cell phone, you need
6168 the maximum amplitude in as many parts of the sound as possible.  Right
6169 click on track Audio 1 and select @b{Attach effect..}.  Highlight the
6170 @b{Compressor} effect and hit @b{Attach} in the attachment popup.
6171
6172 Make sure the insertion point or highlighted area is in the region with
6173 the Compressor effect. Right click on track Audio 2 and select
6174 @b{Attach effect..}.  Highlight @b{Audio 1: Compressor} and hit
6175 @b{Attach}.  Click the Audio1 Compressor's magnifying glass
6176 @image{magnify} to bring up the compressor GUI.
6177
6178 Set the following parameters:
6179
6180 @example
6181 Reaction secs: @b{-0.1}
6182 Decay secs: @b{0.1}
6183 Trigger Type: @b{Total}
6184 Trigger: @b{0}
6185 Smooth only: @b{No}
6186 @end example
6187
6188
6189 Click @b{Clear} to clear the graph.  Click anywhere in the
6190 grid area and drag a new point to 0 Output and -50 Input.  The graph
6191 should look like this.
6192
6193 @sp 1
6194 @image{compress}
6195
6196 Go to @b{File->Render}.  Specify the name of an mp3 file to output to. 
6197 Set the file format to @b{MPEG Audio}.  Click the wrench @image{wrench}
6198 for Audio and set @b{Layer} to @b{III} and @b{Kbits per second} to
6199 @b{24} or @b{32}.  Check @b{Render audio tracks} and uncheck @b{Render
6200 video tracks}.  Hit OK to render the file.
6201
6202 The resulting .mp3 file must be uploaded to a web server.  Then, the
6203 phone's web browser must download the .mp3 file directly from the URL.
6204 There also may be a size limit on the file.
6205
6206
6207
6208
6209
6210
6211
6212 @node TIME STRETCHING AUDIO
6213 @section TIME STRETCHING AUDIO
6214
6215 It may appear that time stretching audio is a matter of selecting a
6216 region of the audio tracks, enabling recording for the desired tracks,
6217 going to @b{Audio->Render Effect}, and applying @b{Time Stretch}.  In
6218 actuality there are 3 audio effects for time stretching: @b{Time
6219 Stretch}, @b{Resample}, and @b{Asset info dialog}.
6220
6221 Time Stretch applies a fast fourier transform to try to change the
6222 duration without changing the pitch, but this introduces windowing
6223 artifacts to the audio.  It's only useful for large changes in time
6224 because obvious changes in duration make windowing artifacts less
6225 obtrusive.
6226
6227 For smaller changes in duration, in the range of 5%, @b{Resample}
6228 should be used.  This changes the pitch of the audio but small enough
6229 changes aren't noticable.  Resample doesn't introduce any windowing
6230 artifacts, so this is most useful for slight duration changes where the
6231 listener isn't supposed to know what's going on.
6232
6233 Another way to change duration slightly is to go to the @b{Resources}
6234 window, highlight the @b{media} folder, right click on an audio file,
6235 click on @b{Info}.  Adjust the sample rate in the @b{Info} dialog to
6236 adjust the duration.  This method also requires left clicking on the
6237 right boundary of the audio tracks and dragging left or right to
6238 correspond to the length changes.
6239
6240
6241 @node PITCH SHIFTING AUDIO
6242 @section PITCH SHIFTING AUDIO
6243
6244 Like the time stretching methods, there are three pitch shifting
6245 methods: @b{Pitch shift}, @b{Resample}, and @b{Asset info dialog}. 
6246 Pitch shift is a realtime effect which can be dragged and dropped onto
6247 recordable audio tracks.  Pitch shift uses a fast fourier transform to
6248 try to change the pitch without changing the duration, but this
6249 introduces windowing artifacts.
6250
6251 Because the windowing artifacts are less obtrusive in audio which is
6252 obvously pitch shifted, Pitch shift is mainly useful for extreme pitch
6253 changes.  For mild pitch changes, use @b{Resample} from the
6254 @b{Audio->Render Effect} interface.  Resample can change the pitch
6255 within 5% without a noticable change in duration.
6256
6257 Another way to change pitch slightly is to go to the @b{Resources}
6258 window, highlight the @b{media} folder, right click on an audio file,
6259 click on @b{Info}.  Adjust the sample rate in the @b{Info} dialog to
6260 adjust the pitch.  This method also requires left clicking on the right
6261 boundary of the audio tracks and dragging left or right to correspond
6262 to the length changes.
6263
6264
6265 @node TEXT TO MOVIE
6266 @section TEXT TO MOVIE
6267
6268
6269
6270 Text to movie was added when another one of those startups whose name
6271 was an unmemorable combination of farting noises that the venture
6272 capitalist heard, started charging money for a ridulously simple program
6273 that converted scripts directly to movies.  It was such a simple
6274 program, we decided to add most of the functionality to Cinelerra.
6275
6276 The easiest way to make a movie is to copy @b{tests/text2movie} and
6277 @b{tests/text2movie.xml} as a starting point.  Load the
6278 @b{text2movie.xml} file to see the movie.
6279
6280 The @b{text2movie} file acts like a normal asset, except changes to it
6281 are immediately reflected on the timeline, without reloading.  Also, the
6282 length is infiinite.  Edit the @b{text2movie} file to change the
6283 script.  If the length of the movie increases, drag the right edit
6284 handle to extend the edit or use @b{edit->edit length}.
6285
6286 1 audio channel is created for every character.  The frame rate, sample
6287 rate, and frame size are fixed.  Get it from the @b{asset window}. 
6288 Right click on the asset and go to @b{Asset info...}  Camera angles are
6289 fixed.
6290
6291 Since its only use was to show dialog between 2 people, that's the
6292 functionality we focused on.  The character model and voice is selected
6293 separately in the script, because that was how it was done with the fee
6294 service.  The models are defined in model files, in the Cinelerra
6295 executable directory.  Usually @b{/opt/cinelerra/models}.
6296
6297 There is a search path for models, starting with the directory the
6298 script is in.  You can define new models for the script, without
6299 affecting the entire system.  The model files are the exact name that
6300 appears in the script.  They define the total size of the model and the
6301 images used in the model.
6302
6303 The models are 2D png images, because all the animations are baked.  No
6304 custom movement is currently supported, that would require a 3D
6305 renderer.  
6306
6307 Some actions are implemented.  Character2 can cut off character1 if
6308 character1's dialog ends in @b{...}
6309
6310 Inserting @b{[pause]} anywhere causes the character to pause.  Useful
6311 for adjusting the timing of dialog.
6312
6313 Speech synthesis is pretty lousy.  Punctuation and spelling needs to be
6314 adjusted based on the sound.  The dialog is rendered on-demand, so there
6315 is a delay when each character starts to speak.  Split dialog into
6316 shorter blocks to reduce the delay.
6317
6318
6319
6320
6321
6322
6323 @node SECRETS OF CINELERRA EFFECTS
6324 @chapter SECRETS OF CINELERRA EFFECTS
6325
6326 Most effects in Cinelerra can be figured out just by using them and
6327 tweeking.  Here are brief descriptions of effects which you might not
6328 utilize fully by mere experimentation.
6329
6330
6331 @menu
6332 * 1080 TO 480::       How to convert HDTV into SD
6333 * CHROMA KEY::        Create transparency based on color similarities.
6334 * COMPRESSOR::        How to reduce the dynamic range of audio.
6335 * DECIMATE::          How to reduce frame rates by eliminating similar frames.
6336 * DEINTERLACE::       How to convert interlaced video to progressive video.
6337 * DIFFERENCE KEY::    Create transparency based on color differences.
6338 * FIELDS TO FRAMES::  How to recover interlaced video from bobbed video
6339 * FREEZE FRAME::      How to stop action in the timeline.
6340 * HISTOGRAM::         How to change the mapping of different brightness values.
6341 * INVERSE TELECINE::  How to convert pulled down frames to progressive frames.
6342 * INTERPOLATE VIDEO:: How to create the illusion of higher framerates.
6343 * LENS::              Correcting spherical aberration
6344 * LINEARIZE::         Fix gamma in raw camera images
6345 * LIVE AUDIO::        Pass audio from the soundcard directly to the timeline.
6346 * LIVE VIDEO::        Pass video from the capture card directly to the timeline.
6347 * LOOP::              How to loop regions of the timeline.
6348 * MOTION::            Motion tracking with rotation.
6349 * MOTION 2 POINT::    Motion and rotation tracking from translation only.
6350 * REFRAMERT::         Changing the number of frames in a sequence.
6351 * REFRAME::           Changing the number of frames in a sequence with rendering.
6352 * RESAMPLE::          Change the number of samples in a sequence with rendering.
6353 * REVERSE VIDEO/AUDIO:: How to play regions in reverse.
6354 * SWAP FRAMES::       Fixing temporal field order
6355 * THRESHOLD::         How to get monochrome out of a region of the image.
6356 * TIME AVERAGE::      How to stack images.
6357 * TITLER::            How to add text to a track from inside Cinelerra.
6358 * VIDEO SCOPE::       How to view the dynamic range of intensity and hue.
6359 @end menu
6360
6361
6362
6363
6364 @node 1080 TO 480
6365 @section 1080 TO 480
6366
6367
6368 Most TV broadcasts are recieved with a 1920x1080 resolution but
6369 originate from a 720x480 source at the studio.  It's a waste of space
6370 to compress the entire 1920x1080 if the only resolvable details are
6371 720x480.  Unfortunately resizing 1920x1080 video to 720x480 isn't as
6372 simple as shrinking it.
6373
6374 At the TV station the original 720x480 footage was first converted to
6375 fields of 720x240.  Each field was then scaled up to 1920x540.  The two
6376 1920x540 fields were finally combined with interlacing to form the
6377 1920x1080 image.  This technique allows a consumer TV to display the
6378 resampled image without extra circuitry to handle 720x480 interlacing
6379 in a 1920x1080 image.
6380
6381 If you merely deinterlaced the 1920x1080 images, you would end up with
6382 resolution of 720x240.  The @b{1080 to 480} effect properly extracts
6383 two 1920x540 size fields from the image, resizes them separately, and
6384 combines them again to restore a 1920x480 interlaced image.  The
6385 @b{scale} effect must then be applied to reduce the horizontal size to
6386 960 or 720 depending on the original aspect ratio.
6387
6388 The tracks to which @b{1080 to 480} is applied need to be at 1920x1080
6389 resolution.  The project settings in @b{settings->format} should be at
6390 least 720x480 resolution.
6391
6392 The effect doesn't know if the first row in the 1920x1080 image belongs
6393 to the first row of the 720x480 original.  You have to specify what the
6394 first row is in the effect configuration.
6395
6396 The output of this effect is a small image in the middle of the
6397 original 1920x1080 frame.  Use the projector to center the output image
6398 in the playback.
6399
6400 Finally, once you have 720x480 interlaced video you can either apply
6401 @b{frames to fields} of @b{inverse telecine} to further recover original
6402 progressive frames.
6403
6404
6405
6406
6407
6408
6409
6410 @node CHROMA KEY
6411 @section CHROMA KEY
6412
6413
6414 This effect erases pixels which match the selected color.  They are
6415 replaced with black if there is no alpha channel and transparency if
6416 there is an alpha channel.  The selection of color model is important
6417 to determine the behavior.
6418
6419 Chroma key uses either the lightness or the hue to determine what is
6420 erased.  @b{Use value} singles out only the lightness to determine
6421 transparency.  Select a center color to erase using the @b{Color}
6422 button.  Alternatively a color can be picked directly from the output
6423 frame by first using the @b{color picker} in the compositor window and
6424 then selecting the @b{Use color picker} button.  This sets the chroma
6425 key color to the current color picker color.
6426
6427 Be aware that the output of the chroma key is fed back to the
6428 compositor, so selecting a color again from the compositor will use the
6429 output of the chroma key effect.  The chroma key should be disabled
6430 when selecting colors with the color picker.
6431
6432
6433 If the lightness or hue is within a certain threshold it's erased. 
6434 Increasing the threshold determines the range of colors to be erased. 
6435 It's not a simple on/off switch, however.  As the color approaches the
6436 edge of the threshold, it gradually gets erased if the slope is high or
6437 is rapidly erased if the slope is low.  The slope as defined here is
6438 the number of extra values flanking the threshold required to go from
6439 opaque to transparent.
6440
6441 Normally threshold is very low when using a high slope.  The two
6442 parameters tend to be exclusive because slope fills in extra threshold.
6443
6444 The slope tries to soften the edges of the chroma key but it doesn't
6445 work well for compressed sources.  A popular softening technique is to
6446 use a maximum slope and chain a blur effect below the chroma key effect
6447 to blur just the alpha.
6448
6449
6450
6451
6452
6453
6454
6455
6456
6457 @node COMPRESSOR
6458 @section COMPRESSOR
6459
6460 Contrary to computer science experience, the audio compressor does not
6461 reduce the amount of data required to store the audio.  The audio
6462 compressor reduces the dynamic range of the audio.  In Cinelerra the
6463 compressor actually performs the function of an expander and
6464 compressor.
6465
6466 The compressor works by calculating the maximum sound level within a
6467 certain time period of the current position.  The maximum sound level
6468 is taken as the input sound level.  For every input sound level there
6469 is an output sound level specified by the user.  The gain at the
6470 current position is adjusted so the maximum sound level in the time
6471 range is the user specified value.
6472
6473 The compressor has a graph which correlates every input sound level to
6474 an output level.  The horizontal direction is the input sound level in
6475 dB.  The vertical direction is the ouptut sound level in dB.  The user
6476 specifies output sound levels by creating points on the graph.  Click
6477 in the graph to create a point.  If 2 points exist, drag one point
6478 across another point to delete it.  The most recent point selected has
6479 its vales displayed in textboxes for more precise adjustment.
6480
6481 To make the compressor reduce the dynamic range of the audio, make all
6482 the output values greater than the input values except 0 db.  To make
6483 the compressor expand the dynamic range of the audio, make all the
6484 output values except 0 db less than the input values.  The algorithm
6485 currently limits all sound levels above 0 db to 0 db so to get an
6486 overloaded effect put a gain effect before the compressor to reduce all
6487 the levels and follow it with another gain effect to amplify all the
6488 levels back over 0 db.
6489
6490 @b{Reaction secs:} This determines where in relation to the current
6491 position the maximum sound level is taken and how fast the gain is
6492 adjusted to reach that peak.  It's notated in seconds.  If it's
6493 negative the compressor reads ahead of the current position to get the
6494 future peak.  The gain is ramped to that peak over one reaction time. 
6495 This allows it to hit the desired output level exactly when the input
6496 peak occurs at the current position.
6497
6498 If the reaction time is positive the compressor scans only the current
6499 position for the gain and ramps gain over one reaction time to hit the
6500 desired output level.  It hits the output level exactly one reaction
6501 time after detecting the input peak.
6502
6503 @b{Decay secs:} If the peak is higher than the current level, the
6504 compressor ramps the gain up to the peak value.  Then if a future peak
6505 is less than the current peak it ramps the gain down.  The time taken
6506 to ramp the gain down can be greater than the time taken to ramp the
6507 gain up.  This ramping down time is the decay seconds.
6508
6509 @b{Trigger type:}  The compressor is a multichannel effect.  Several
6510 tracks can share one compressor.  How the signal from many tracks is
6511 interpreted is determined by the trigger type.
6512
6513 The @b{Trigger} trigger type uses the value supplied in the @b{Trigger}
6514 textbox as the number of the track to use as input for the compressor. 
6515 This allows a track which isn't even heard to determine the loudness of
6516 the other tracks.
6517
6518 The @b{Maximum} trigger takes the loudest track and uses it as the
6519 input for the compressor.
6520
6521 The @b{Total} trigger type adds the signals from all the tracks and
6522 uses the total as the input for the compressor.  This is the most
6523 natural sounding compression and is ideal when multiple tracks are
6524 averaged into single speakers.
6525
6526
6527
6528 @b{Trigger:} The compressor is a multichannel effect.  Several tracks
6529 can share one compressor.  Normally only one track is scanned for the
6530 input peak.  This track is specified by the @b{Trigger}.  By sharing
6531 several tracks and playing with the trigger value, you can make a sine
6532 wave on one track follow the amplitude of a drum on another track for
6533 example.
6534
6535 @b{Smooth only:} For visualizing what the compressor is doing to the
6536 soundlevel, this option causes it to replace the soundwave with just
6537 the current peak value.  It makes it very easy to see how @b{reaction
6538 secs} affects the detected peak values.
6539
6540
6541
6542
6543
6544
6545
6546 @node DECIMATE
6547 @section DECIMATE
6548
6549 This effect drops frames from a track which are most similar in order
6550 to reduce the frame rate.  This is usually applied to a DVD to convert
6551 the 29.97 fps video to the 23.97 fps film rate but this decimate effect
6552 can take any input rate and convert it to any lower output rate.
6553
6554 The output rate of @b{decimate} is the project frame rate.  The input
6555 rate is set in the @b{decimate} user interface.  To convert 29.97fps
6556 progressive video to 23.97fps film, apply a decimate effect to the
6557 track.  Set the decimate input rate to 29.97 and the project rate to
6558 23.97.
6559
6560 Be aware every effect layered before decimate processes video at the
6561 decimate input rate and every effect layered after decimate processes
6562 video at the project frame rate.  Computationally intensive effects
6563 should come below decimate.
6564
6565
6566
6567
6568
6569
6570
6571
6572 @node DEINTERLACE
6573 @section DEINTERLACE
6574
6575 The deinterlace effect has evolved over the years to deinterlacing and
6576 a whole lot more.  In fact two of the deinterlacing methods, @b{Inverse
6577 Telecine} and @b{Frames to Fields}, are separate effects.  The
6578 deinterlace effect offers several variations of line replication to
6579 eliminate comb artifacts in interlaced video.  It also has some line
6580 swapping tools to fix improperly captured video or make the result of a
6581 reverse effect display fields in the right order.
6582
6583
6584
6585
6586
6587
6588
6589
6590 @node DIFFERENCE KEY
6591 @section DIFFERENCE KEY
6592
6593 The differency key creates transparency in areas which are similar
6594 between 2 frames.  The Difference key effect must be applied to 2
6595 tracks.  One track contains the action in front of a constant
6596 background and another track contains the background with nothing in
6597 front of it.  Apply the difference key to the track with the action and
6598 apply a shared copy of it to the track with the background.  The track
6599 with the background should be muted and underneath the track with the
6600 action and the colormodel should have an alpha channel.
6601
6602 Pixels which are different between the background and action track are
6603 treated as opaque.  Pixels which are similar are treated as
6604 transparent.  Change @b{threshold} in the differency key window to make
6605 more pixels which aren't the same color transparent. Change @b{slope}
6606 to change the rate at which the transparency tapers off as pixels get
6607 more different.
6608
6609 The slope as defined here is the number of extra values flanking the
6610 threshold required to go from opaque to transparent.  A high slope is
6611 more useful with a low threshold because slope fills in extra
6612 threshold.
6613
6614 @b{Use value} causes the intensity of pixels to be compared instead of
6615 the color.
6616
6617 Applying a blur to the top track with just the alpha channel blurred
6618 can soften the transparency border.
6619
6620
6621
6622
6623
6624 @node FIELDS TO FRAMES
6625 @section FIELDS TO FRAMES
6626
6627 This effects reads frames at twice the project framerate, combining 2
6628 input frames into a single interlaced output frame.  Effects preceeding
6629 @b{fields to frames} process frames at twice the project frame rate. 
6630 Each input frame is called a field.
6631
6632 @b{Fields to frames} needs to know what field corresponds to what lines
6633 in the output frame.  The easiest way to figure it out is to try both
6634 options in the window.  If the input fields are the result of a line
6635 doubling process like @b{frames to fields}, the wrong setting results
6636 in blurrier output.  If the input fields are the result of a standards
6637 conversion process like @b{1080 to 480}, the wrong setting won't make
6638 any difference.
6639
6640 The debobber which converts 720x480 interlaced into 1920x1080
6641 interlaced or 1280x720 progressive seems to degrade the vertical
6642 resolution to the point that it can't be recovered.
6643
6644
6645
6646
6647
6648
6649
6650 @node FREEZE FRAME
6651 @section FREEZE FRAME
6652
6653 In its simplest form, highlight a region of the track to freeze, drop
6654 the freeze frame effect on the highlighted region, and the lowest
6655 numbered frame in the affected area will play throughout the entire
6656 region.  
6657
6658 Freezeframe has an @b{enabled} option which can be keyframed.  Regions
6659 of a freeze frame effect which are enabled repeat the lowest numbered
6660 frame since the last keyframe.  This has unique possibilities.
6661
6662 If a freeze frame effect has a keyframe in the middle of it set to
6663 @b{enabled}, the frame in the middle is repeated in the entire effect.
6664
6665 If a freeze frame effect has several keyframes, each set to
6666 @b{enabled}, every time a keyframe is encountered the frame under it
6667 becomes the frozen one.
6668
6669 If a freeze frame effect alternates between @b{enabled} and
6670 @b{disabled}, each time an @b{enabled} keyframe is encountered the
6671 frame under it is replicated until the next @b{disabled} keyframe.  The
6672 disabled regions play through.
6673
6674
6675
6676
6677
6678
6679 @node HISTOGRAM
6680 @section HISTOGRAM
6681
6682
6683 This shows the number of occurances of each color on a histogram plot.
6684
6685 It is always performed in floating point RGB regardless of
6686 the project colorspace.  The histogram has two sets of transfer
6687 parameters: the input transfer and the output transfer.
6688
6689 4 histograms are possible in the histogram viewer.  The red, green,
6690 blue histograms show the input histograms for red, green, blue and
6691 multiply them by an input transfer to get the output red, green, blue. 
6692 Then the output red, green, blue is scaled by an output transfer.  The
6693 scaled red, green, blue is converted into a value and plotted on the
6694 value histogram.  The value histogram thus changes depending on the
6695 settings for red, green, blue.  The value transfers are applied
6696 uniformly to R, G, B after their color transfers are applied.
6697
6698 Select which transfer to view by selecting one of the channels on the
6699 top of the histogram.
6700
6701
6702 The input transfer is defined by a graph overlaid on the histogram. 
6703 The horizontal direction corresponds to every possible input color. 
6704 The vertical direction corresponds to the output color for every input
6705 color.  Video entering the histogram is first plotted on the histogram
6706 plot, then it is translated so output values now equal the output
6707 values for each input value on the input graph.
6708
6709 The input graph is edited by adding and removing any number of points. 
6710 Click and drag anywhere in the input graph to create a point and move
6711 it.  Click on an existing point to make it active and move it.  The
6712 active point is always indicated by being filled in.  The active
6713 point's input and output color are given in text boxes on top of the
6714 window.  The input and output color of the point can be changed through
6715 these text boxes.
6716
6717 Points can be deleted by first selecting a point and then dragging it
6718 to the other side of an adjacent point.  They can also be deleted by
6719 selecting them and hitting @b{delete}.
6720
6721
6722 After the input transfer, the image is processed by the output
6723 transfer.  The output transfer is simply a minimum and maximum to scale
6724 the input colors to.  Input values of 100% are scaled down to the
6725 output's maximum.  Input values of 0% are scaled up to the output
6726 minimum.
6727
6728
6729 Input values below 0 are always clamped to 0 and input values above
6730 100% are always clamped to 100%.  Click and drag on the output
6731 gradient's triangles to change it.  It also has textboxes to enter
6732 values into.
6733
6734 Enable the @b{automatic} toggle to have the histogram calculate an
6735 automatic input transfer for the red, green, blue but not the value. 
6736 It does this by scaling the middle 99% of the pixels to take 100% of
6737 the histogram width.  The number of pixels permitted to pass through is
6738 set by the @b{Threshold} textbox.  A threshold of 0.99 scales the input
6739 so 99% of the pixels pass through.  Smaller thresholds permit fewer
6740 pixels to pass through and make the output look more contrasty.
6741
6742 Automatic input transfer is calculated for the R, G, and B channels but
6743 not the value.
6744
6745
6746 @b{PLOT HISTOGRAM}
6747
6748 @b{SPLIT OUTPUT}
6749
6750
6751
6752
6753
6754
6755
6756
6757 @node INVERSE TELECINE
6758 @section INVERSE TELECINE
6759
6760 This is the most effective deinterlacing tool when the footage is a
6761 video transfer of a film.  Here the film was converted from 24fps to
6762 60fps.  Then the 60fps was downsampled to 30fps by extracting odd and
6763 even lines and interlacing the lines.  The IVTC effect is primarily a
6764 way to convert interlaced video to progressive video.  It undoes three
6765 patterns of interlacing.
6766
6767 @example
6768   A AB BC CD D
6769   AB CD CD DE EF
6770   Automatic
6771 @end example
6772
6773 The first two options are fixed patterns and affected by the @b{pattern
6774 offset} and @b{odd field first} parameters.  The last option creates
6775 several combinations of lines for each frame and picks the most
6776 progressive combination.  It's a brute force algorithm.
6777
6778 This technique doesn't rely on a pattern like other techniques and is
6779 less destructive but the timing is going to be jittery because of the
6780 lack of a frame rate reduction.  In order to smooth out the timing, you
6781 need to follow inverse telecine with a decimate effect.
6782
6783
6784
6785
6786
6787 @node INTERPOLATE VIDEO
6788 @section INTERPOLATE VIDEO
6789
6790
6791 The interpolate video effect tries to create the illusion of a higher
6792 frame rate from source footage of very low framerates by averaging
6793 frames over time.  It averages two input frames for each output frame. 
6794 The input frames are at different times, resulting in a dissolve for
6795 all output frames between the input frames.  There are two ways of
6796 specifying the input frames.  You can specify an input frame rate which
6797 is lower than the project frame rate.  This causes input frames to be
6798 taken at even intervals,
6799
6800 You can also specify keyframe locations as the positions of the input
6801 frames.  In this mode the output frame rate is used as the input frame
6802 rate and you just create keyframes wherever you want to specify an
6803 input frame.
6804
6805
6806 @node LENS
6807 @section LENS
6808
6809 The lens affect stretches or shrinks to convert lens distorted images to
6810 rectilinear images.  The most common use is converting fish eye lenses
6811 to rectilinear lenses.  It is also useful for star tracking.
6812
6813 @b{R, G, B, A Field of view:} These determine how much the image is
6814 stretched in each channel.
6815
6816 @b{Lock:} This causes changes to 1 channel to affect all the channels. 
6817 This is normally the desired behavior.
6818
6819 @b{Aspect Ratio:} This changes the amount of stretching done in the X
6820 axis vs the Y axis.  To crop less data from stretched images, this
6821 allows more stretching to be done on 1 axis without creating black
6822 borders in the other axis.
6823
6824 @b{Radius:} This determines the size of the stretched region.  While
6825 adjusting the @b{field of view}, black borders may appear.  Adjust the
6826 @b{radius} to shrink or expand the output so black borders are out of
6827 frame.
6828
6829 @b{Center X, Y:} The center of the stretched region.  This is only
6830 useful if the image was previously translated by the software so the
6831 center of the lens is now off center.
6832
6833 @b{Draw center:} This is a visual aid when adjusting the @b{Center X, Y}
6834 but doesn't affect the results.
6835
6836 @b{Mode:} The type of stretching algorithm.
6837
6838 @itemize
6839 @item
6840 @b{Sphere shrink:} This is for making an image look like it's mapped to a sphere.
6841
6842 @item
6843 @b{Sphere expand:} This is for unmapping an image mapped to a sphere and
6844 flattening it.
6845
6846 @item
6847 @b{Rectilinear Stretch:} This is for flattening a fish eye lens.
6848
6849 @item
6850 @b{Rectilinear Shrink:} This is for making something flat look like it
6851 was taken by a fish eye lens.
6852
6853
6854 @end itemize
6855
6856
6857
6858
6859
6860
6861
6862
6863
6864
6865
6866 @node LINEARIZE
6867 @section LINEARIZE
6868
6869
6870 Raw camera images store colors in a logarithmic scale.  The blacks in
6871 these images are nearly 0 and the whites are supposed to be infinity. 
6872 The graphics card and most video codecs store colors in a linear scale
6873 but Cinelerra keeps raw camera images in their original logarithmic
6874 scale when it renders them.  This is necessary because the raw image
6875 parser can't always decode the proper gamma values for the images.  It
6876 also does its processing in 16 bit integers, which takes away a lot of
6877 information.
6878
6879 The linearize effect converts the logarithmic colors to linear colors
6880 through a gamma value and a maximum value.  The gamma value determines
6881 how steep the output curve is and the maximum value is where 1.0 in the
6882 output corresponds to maximum brightness in the input.
6883
6884 The linearize effect has 2 more parameters to simplify gamma
6885 correction.  The @b{automatic} option causes it to calculate @b{max}
6886 from the histogram of the image.  Use this when making a preview of a
6887 long list of images since it changes for every image.
6888
6889 The @b{use color picker} option uses the value currently in the color
6890 picker to set the @b{max} value.  Note that every time you pick a color
6891 from the compositor window, you need to hit @b{use color picker} to
6892 apply the new value.
6893
6894
6895
6896
6897
6898
6899
6900
6901 @node LIVE AUDIO
6902 @section LIVE AUDIO
6903
6904 This effect reads audio directly from the soundcard input.  It replaces
6905 any audio on the track so it's normally applied to an empty track. 
6906
6907
6908 To use Live Audio, highlight a horizontal region of an audio track or
6909 define in and out points.  Then drop the Live Audio effect into it. 
6910 Create extra tracks and attach shared copies of the first Live Audio
6911 effect to the other tracks to have extra channels recorded.
6912
6913 Live Audio uses the sound driver selected in
6914 @b{Settings->Preferences->Playback->Audio Out} for recording, but
6915 unlike recording it uses the @b{playback buffer size} as the recording
6916 buffer size and it uses the @b{project sample rate} as the sampling
6917 rate.
6918
6919 These settings are critical since some sound drivers can't record in
6920 the same sized buffer they play back in.  Live audio has been most
6921 reliable when ALSA is the recording driver and the playback fragment
6922 size is 2048.
6923
6924 Drop other effects after Live Audio to process soundcard input in
6925 realtime.  
6926
6927 Now the bad news.  With live audio there is no readahead so effects
6928 like compressor will either delay if they have readahead enabled or
6929 playback will underrun.  
6930
6931 Another problem is sometimes the recording clock on the soundcard is
6932 slightly slower than the playback clock.  The recording eventually
6933 falls behind and playback sounds choppy.
6934
6935 Finally, live audio doesn't work in reverse.
6936
6937
6938
6939
6940
6941 @node LIVE VIDEO
6942 @section LIVE VIDEO
6943
6944 This effect reads video directly from the capture card input.  It
6945 replaces any video on the track so it's normally applied to an empty
6946 track.  The configuration for the capture card is taken from the
6947 recording preferences.  Go to @b{Settings->Preferences->Recording} to
6948 set up the capture card.
6949
6950 Go to the @b{Video In} section where it says @b{Record driver}.  It
6951 must be set to either @b{Video4Linux2} or @b{IEC 61883}.  Other video
6952 drivers haven't been tested with Live Video and probably won't work.
6953
6954 For live video, the selection for @b{File Format} and @b{Video} needs
6955 to be set to a format the timeline can use.  The file format must be
6956 @b{Quicktime for Linux} and video recording must be enabled for it. 
6957 Click on the wrench @image{wrench} to set the video compression.
6958
6959 The video compression depends on the recording driver.  For the
6960 @b{Video4Linux2} recording driver, the compression must be @b{Motion
6961 JPEG A}.  For the @b{IEC 61883} driver, the compression must be
6962 @b{DV}.  This gets the driver to generate output in a colormodel that
6963 the timeline can use.
6964
6965 Some cards provide color and channel settings.  Live video takes the
6966 color settings from the values set in the @b{Video In} window.  Go to
6967 @b{File->Record} to bring up the recording interface and the Video In
6968 window.  Values set in the @b{Video in} window are used by @b{Live
6969 Video}.  Any channels the capture card supports need to be configured
6970 in the @b{Video in} interface since the same channels are used by the
6971 @b{Live Video} effect.
6972
6973 With the video recording configured, highlight a horizontal region of a
6974 video track or define in and out points.  Then drop the Live Video
6975 effect into it.  Drop other effects after Live Video to process the
6976 live video in realtime.  For best results, you should use OpenGL and a
6977 video card which supports GL shading language.  Go to
6978 @b{Settings->Preferences->Playback->Video Out} to enable the OpenGL
6979 driver.
6980
6981 Only one Live Video effect can exist at any time on the timeline.  It
6982 can't be shared by more than one track.
6983
6984
6985
6986
6987
6988
6989
6990
6991 @node LOOP
6992 @section LOOP
6993
6994 Sections of audio or video can be looped by dropping a @b{loop} effect
6995 on them.  Contrary to the the @b{settings->loop playback} option, the
6996 loop effects can be rendered where the @b{settings->loop playback}
6997 option can not be.  The loop effects are also convenient for short
6998 regions.
6999
7000 The loop effects have one option: the number of @b{frames} or
7001 @b{samples} to loop.  This specifies the length of the region to loop
7002 starting from either the beginning of the effect or the latest
7003 keyframe.  The region is replicated for the entire effect.
7004
7005 Every time a keyframe is set in a loop effect, the keyframe becomes the
7006 beginning of the region to loop.  Setting several keyframes in
7007 succession causes several regions to loop.  Setting a single keyframe
7008 causes the region after the keyframe to be looped throughout the
7009 effect, no matter where the keyframe is.  The end of an effect can be
7010 looped from the beginning by setting the keyframe near the end.
7011
7012
7013
7014
7015
7016
7017
7018
7019
7020
7021 @node MOTION
7022 @section MOTION
7023
7024 The motion tracker is almost a complete application in itself.  The
7025 motion tracker tracks two types of motion: translation and rotation. 
7026 It can track both simultaneously or one only.  It can do 1/4 pixel
7027 tracking or single pixel tracking.  It can stabilize motion or cause
7028 one track to follow the motion of another track.
7029
7030 Although the motion tracker is applied as a realtime effect, it usually
7031 must be rendered to see useful results.  The effect takes a long time
7032 to precisely detect motion.
7033
7034 The motion tracker works by using one region of the frame as the region
7035 to track.  It compares this region between 2 frames to calculate the
7036 motion.  This region can be defined anywhere on the screen.  Once the
7037 motion between 2 frames has been calculated, a number of things can be
7038 done with that motion vector.  It can be scaled by a user value and
7039 clamped to a maximum range.  It can be thrown away or accumulated with
7040 all the motion vectors leading up to the current position.
7041
7042 To save time the motion result can be saved for later reuse, recalled
7043 from a previous calculation, or discarded.
7044
7045 The motion tracker has a notion of 2 tracks, the master layer and the
7046 target layer.  The master layer is where the comparison between 2
7047 frames takes place.  The target layer is where motion is applied either
7048 to track or compensate for the motion in the master layer.
7049
7050 The intricacies of motion tracking are enough to sustain entire
7051 companies and build careers around.  The motion tracker in Cinelerra
7052 isn't as sophisticated as some world class motion trackers but it's
7053 enough to sweeten some camcorder footage.
7054
7055 Here is a brief description of the motion tracking parameters:
7056
7057 @itemize
7058 @item
7059 @b{Track translation:} Enables translation operations.  
7060 The motion tracker tracks X and Y motion in the master layer and 
7061 adjusts X and Y motion in the target layer.
7062
7063 @item
7064
7065 @b{Translation block size:} For the translation operations, a block is
7066 compared to a number of neighboring blocks to find the one with the
7067 least difference.  The size of the block to search for is given by this
7068 parameter.
7069
7070 @item
7071
7072 @b{Translation search radius:} The size of the area to scan for the
7073 translation block.
7074
7075 @item
7076
7077 @b{Translation search steps:} Ideally the search operation would
7078 compare the  translation block with every other pixel in the
7079 translation search radius.  To  speed this operation up, a subset of
7080 the total positions is searched.   Then the search area is narrowed and
7081 rescanned by the same number of search steps until the motion is known
7082 to 1/4 pixel accuracy.
7083
7084 @item
7085
7086 @b{Block X, Y:} These coordinates determine the center of the
7087 translation  block based on percentages of the width and height of the
7088 image.  The center of the block should be part of the image which is
7089 visible at all times.
7090
7091 @item 
7092
7093 @b{Maximum absolute offset:} In @b{track previous frame} and @b{previous
7094 frame same block} modes, the motion detected between every frame is
7095 accumulated to form an absolute motion vector for the entire sequence. 
7096 The amount of motion detected by the motion tracker is unlimited if this
7097 is 100.  If it's under 100 the amount of motion is limited to that
7098 percentage of the image size.  The value must be smaller for larger
7099 @b{translation block sizes} so there is enough area under the block to
7100 sense motion with.
7101
7102 @item
7103
7104 @b{Settling speed} In @b{track previous frame} and @b{previous frame
7105 same block} modes, the motion detected between every frame is
7106 accumulated to form an absolute motion vector for the entire sequence. 
7107 To keep the absolute motion from exceeding limits, it can be
7108 automatically reset over time by the settling speed.  If the settling
7109 speed is 100 the absolute vector resets to 0 after every frame.  If the
7110 settling speed is less than 100 the absolute vector is reduced slightly
7111 before the next frame is added.
7112
7113 @item
7114
7115 @b{Track rotation:} Enables rotation operations.  The motion tracker
7116 tracks rotation in the master layer and adjusts rotation in the target
7117 layer.
7118
7119 @item
7120
7121 @b{Rotation block size:} For rotation operations a single block is
7122 compared to equally sized blocks, each rotated by a different amount. 
7123 This is the size of the rotation block.
7124
7125 @item
7126
7127 @b{Rotation search radius:} This is the maximum angle of rotation from
7128 the starting frame the rotation scanner can detect.  The rotation scan
7129 is from this angle counterclockwise to this angle clockwise.  Thus the
7130 rotation search radius is half the total range scanned.
7131
7132 @item
7133
7134 @b{Rotation search steps:} Ideally every possible angle would be tested
7135 to get the rotation.  To speed up the rotation search, the rotation
7136 search radius is divided into a finite number of angles and only those
7137 angles compared to the starting frame.  Then the search radius is
7138 narrowed and an equal number of angles is compared in the smaller
7139 radius until the highest possible accuracy is achieved.
7140
7141 Normally you need one search step for every degree scanned.  Since the
7142 rotation scanner scans the rotation search radius in two directions,
7143 you need two steps for every degree in the search radius to search the
7144 complete range.
7145
7146 @item
7147
7148 @b{Draw vectors:} When translation is enabled, 2 boxes are drawn on the
7149 frame.  One box represents the translation block.  Another box outside
7150 the translation block represents the extent of the translation search
7151 radius.  In the center of these boxes is an arrow showing the
7152 translation between the 2 master frames.
7153
7154 When rotation is enabled a single box the size of the rotation block is
7155 drawn rotated by the amount of rotation detected.
7156
7157 @item
7158
7159 @b{Track single frame:} When this option is used the motion between a
7160 single starting frame and the frame currently under the insertion point
7161 is calculated.  The starting frame is specified in the @b{Frame number}
7162 blank.  The motion calculated this way is taken as the absolute motion
7163 vector.  The absolute motion vector for each frame replaces the
7164 absolute motion vector for the previous frame.  Settling speed has no
7165 effect on it since it doesn't contain any previous motion vectors. 
7166 Playback can start anywhere on the timeline since there is no
7167 dependance on previous results.
7168
7169 @item
7170
7171 @b{Track previous frame:} Causes only the motion between the previous
7172 frame and the current frame to be calculated.  This is added to an
7173 absolute motion vector to get the new motion from the start of the
7174 sequence to the current position.  After every frame processed this
7175 way, the block position is shifted to always cover the same region of
7176 the image.  Playback must be started from the start of the motion
7177 effect in order to accumulate all the necessary motion vectors.
7178
7179 @item
7180
7181 @b{Previous frame same block:} This is useful for stabilizing jerky
7182 camcorder footage.  In this mode the motion between the previous frame
7183 and the current frame is calculated.  Instead of adjusting the block
7184 position to reflect the new location of the image, like Track Previous
7185 Frame does, the block position is unchanged between each frame.  Thus a
7186 new region is compared for each frame.
7187
7188 @item
7189
7190 @b{Master layer:} This determines the track which supplies the starting
7191 frame and ending frame for the motion calculation.  If it's @b{Bottom}
7192 the bottom track of all the tracks sharing this effect is the master
7193 layer.  The top track of all the tracks is the target layer.
7194
7195 @item
7196
7197 @b{Calculation:} This determines whether to calculate the motion at all
7198 and whether to save it to disk.  If it's @b{Don't Calculate} the motion
7199 calculation is skipped.  If it's @b{Recalculate} the motion calculation
7200 is performed every time each frame is rendered.  If it's @b{Save} the
7201 motion calculation is always performed but a copy is also saved.  If
7202 it's @b{Load}, the motion calculation is loaded from a previous save
7203 calculation.  If there is no previous save calculation on disk, a new
7204 motion calculation is performed.
7205
7206 @item
7207
7208 @b{Action:} Once the motion vector is known this determines whether to
7209 move the target layer opposing the motion vector or following the
7210 motion vector.  If it's @b{Do Nothing} the target layer is untouched. 
7211 If it's @b{Track...} the target layer is moved by the same amount as
7212 the master layer.  This is useful for matching titles to objects in the
7213 frame.  If it's @b{Stabilize...} the target layer is moved opposite to
7214 the motion vector.  This is useful for stabilizing an object in the
7215 frame.  The motion operations can be accurate to single pixels or
7216 subpixels by changing the action setting.
7217
7218
7219
7220
7221
7222 @end itemize
7223
7224
7225
7226 @menu
7227 * SECRETS OF MOTION TRACKING::
7228 * 2 PASS MOTION TRACKING::
7229 * USING BLUR TO IMPROVE MOTION TRACKING::
7230 * USING HISTOGRAM TO IMPROVE MOTION TRACKING::
7231 * INTERPOLATING MOTION BETWEEN FRAMES::
7232 * FILLING IN THE BLACK AREAS::
7233 @end menu
7234
7235
7236 @node SECRETS OF MOTION TRACKING
7237 @subsection SECRETS OF MOTION TRACKING
7238
7239 Since it is a very slow effect, there is a method to applying the
7240 motion tracker to get the most out of it.  First disable playback for
7241 the track to do motion tracking on.  Then drop the effect on a region
7242 of video with some motion to track.  Then rewind the insertion point to
7243 the start of the region.  Set @b{Action} -> @b{Do Nothing}.  Set
7244 @b{Calculation} -> @b{Don't calculate}.  Enable @b{Draw vectors}. Then
7245 enable playback of the track to see the motion tracking areas.
7246
7247 Enable which of @b{translation motion} or @b{rotation motion} vectors
7248 you want to track.  By watching the compositor window and adjusting the
7249 @b{Block x,y} settings, center the block on the part of the image you
7250 want to track.  Then set search radius, block size, and block
7251 coordinates for translation and rotation.
7252
7253 Once this is configured, set the calculation to @b{Save coords} and do
7254 test runs through the sequence to see if the motion tracker works and
7255 to save the motion vectors.  Once this is done, disable playback for
7256 the track, disable @b{Draw vectors}, set the motion action to perform
7257 on the target layer and change the calculation to @b{Load coords}. 
7258 Finally enable playback for the track.
7259
7260 When using a single starting frame to calculate the motion of a
7261 sequence, the starting frame should be a single frame with the least
7262 motion to any of the other frames.  This is rarely frame 0.  Usually
7263 it's a frame near the middle of the sequence.  This way the search
7264 radius need only reach halfway to the full extent of the motion in the
7265 sequence.
7266
7267 If the motion tracker is used on a render farm, @b{Save coords} and
7268 @b{previous frame} mode won't work.  The results of the save coords
7269 operation are saved to the hard drives on the render nodes, not the
7270 master node.  Future rendering operations on these nodes will process
7271 different frames and read the wrong coordinates from the node
7272 filesystems.  The fact that render nodes only visualize a portion of
7273 the timeline also prevents @b{previous frame} from working since it
7274 depends on calculating an absolute motion vector starting on frame 0.
7275
7276 @node 2 PASS MOTION TRACKING
7277 @subsection 2 PASS MOTION TRACKING
7278
7279 The method described above is 2 pass motion tracking.  One pass is used
7280 just to calculate the motion vectors.  A second pass is used to apply
7281 the motion vectors to the footage.  This is faster than a single pass
7282 because errors in the motion vector calculation can be discovered
7283 quickly.
7284
7285 This also allows the motion tracking to use a less demanding colormodel
7286 like RGB888 in the scanning step and a more demanding colormodel like
7287 RGB Float in the action step.  The scanning step takes much longer than
7288 action.
7289
7290 This suffers the disadvantage of not being practical for extremely long
7291 sequences where some error is acceptable and the picture quality is
7292 lousy to begin with, like stabilizing camcorder footage.
7293
7294 The slower method is to calculate the motion vectors and apply them
7295 simultaneously.  This method can use one track as the motion vector
7296 calculation track and another track as the target track for motion
7297 vector actions.  This is useful for long sequences where some error is
7298 acceptable.
7299
7300
7301 @node USING BLUR TO IMPROVE MOTION TRACKING
7302 @subsection USING BLUR TO IMPROVE MOTION TRACKING
7303
7304 With extremely noisy or interlaced footage, applying a blur effect
7305 before the motion tracking can improve accuracy.  Either save the
7306 motion vectors in a @b{tracking pass} and disable the blur for the
7307 @b{action pass} or apply the blur just to the @b{master layer}.
7308
7309
7310 @node USING HISTOGRAM TO IMPROVE MOTION TRACKING
7311 @subsection USING HISTOGRAM TO IMPROVE MOTION TRACKING
7312
7313 A histogram is almost always applied before motion tracking to clamp
7314 out noise in the darker pixels.  Either save the motion vectors in a
7315 @b{tracking pass} and disable the histogram for the @b{action pass} or
7316 apply the histogram just to the @b{master layer}.
7317
7318
7319
7320
7321 @node INTERPOLATING MOTION BETWEEN FRAMES
7322 @subsection INTERPOLATING MOTION BETWEEN FRAMES
7323
7324 The motion tracker can simulate higher frame rates than the media frame
7325 rate by interpolating the motion.  Interpolation is enabled with the
7326 @b{maximum absolute offset} and @b{settling speed} options.
7327
7328 First, go to @b{Settings->Format} in the main window and set the
7329 @b{video frame rate} to a number higher than the media frame rate.
7330
7331 In the @b{Motion} window, select a tracking option which accumulates
7332 motion.  This is either @b{Track previous frame} or @b{Previous frame
7333 same block}.  These cause the @b{maximum absolute offset} and
7334 @b{settling speed} options to take effect.
7335
7336 @b{maximum absolute offset} must be set to the maximum motion to be
7337 accumulated as a percentage of the video size.  A value of 50 limits the
7338 motion to 50% of the video size.  50 works well.  The value must be
7339 smaller for larger @b{translation block sizes} so there is enough area
7340 under the block to sense motion with.
7341
7342 @b{settling speed} must be set to the rate at which the accumulated
7343 motion resets to 0 over time.  The reset happens whether or not any
7344 motion was detected, so when the project frame rate is higher than the
7345 media frame rate, the frames between media frames regress towards the
7346 center.  For interpolated motion, the @b{settling speed} value should be
7347 small, so the movement is smooth.  3 works well.
7348
7349
7350
7351
7352
7353
7354
7355
7356
7357 @node FILLING IN THE BLACK AREAS
7358 @subsection FILLING IN THE BLACK AREAS
7359
7360 Stabilization always creates black borders in the track resolution.  One
7361 solution is to shrink the project resolution so the borders are always
7362 cropped off the output.  Another solution is to apply a @b{Time Average}
7363 effect after stabilization.
7364
7365 Configure @b{Time Average} the following way:
7366
7367 @itemize
7368 @item
7369 @b{Frame count:} 1
7370 @item
7371 @b{Accumulate sequence again:} No
7372 @item
7373 @b{Replace:} Yes
7374 @item
7375 @b{Threshold:} 1
7376 @item
7377 @b{Border:} 4
7378 @end itemize
7379
7380 This makes new frames replace only the pixels in the previous frames
7381 where there is new data.  The black areas in new frames don't replace
7382 previous data so the previous data shows through and fills them in.
7383
7384
7385
7386
7387
7388
7389
7390
7391
7392
7393
7394
7395 @node MOTION 2 POINT
7396 @section MOTION 2 POINT
7397
7398
7399 The 2 point motion tracker is the same as using 2 of the translation
7400 motion trackers to track 2 points.  It doesn't have a rotation tracker. 
7401 Instead, it uses the angle between the 2 translation points to
7402 determine  rotation.  The 2 points can be enabled separately.
7403
7404 If 1 point is enabled, only translation is tracked.  
7405
7406 If 2 points are enabled, translation is tracked by point 1 and rotation
7407 is tracked by point 2.  Stabilization is performed with point 1 as the center.
7408
7409 The other parameters for the 2 point tracker are the same as the single
7410 point tracker.  In addition, the 2 point tracker supports @b{TRANSLATION
7411 SEARCH OFFSET}.
7412
7413 @b{TRANSLATION SEARCH OFFSET} forces the motion search to look in a
7414 region other than directly next to the translation block position.  The
7415 @b{translation search offset} is added to the new search result, giving
7416 contiguous motion results throughout any changes in translation search area.
7417
7418 This is useful if the camera position changed in the middle of a
7419 sequence of images but the subject stayed the same.  Offset the
7420 translation search area when the camera position changes and the
7421 detected motion stays contiguous through the entire sequence.
7422
7423 2 point tracking works best if the points don't change shape between
7424 frames.  It is more prone to rotation errors than single point motion
7425 tracking if the points change shape.  2 point tracking is mainly used
7426 for tracking stars.
7427
7428 Use the smallest search blocks possible since larger blocks are harder
7429 to compare when they're rotated.
7430
7431
7432
7433
7434
7435 @node REFRAMERT
7436 @section REFRAMERT
7437
7438
7439 ReframeRT changes number of frames in a sequence of video directly from
7440 the timeline.  It has 2 modes, selected by the 2 toggles in the GUI.
7441
7442 @b{Stretch} mode multiplies the current frame number of its output by
7443 the scale factor to arrive at the frame to read from its input.  If its
7444 current output frame is #55 and the scale factor is 2, frame #110 is
7445 read from its input.  The stretch mode has the effect of changing the
7446 length of output video by the inverse of the scale factor.  If the
7447 scale factor is greater than 1, the output will end before the end of
7448 the sequence on the timeline.  If it's less than 1, the output will end
7449 after the end of the sequence on the timeline.  The ReframeRT effect
7450 must be lengthened to the necessary length to accomodate the scale
7451 factor.  Change the length of the effect by clicking on the endpoint of
7452 the effect and dragging.
7453
7454 Although stretch mode changes the number of the frame read from its
7455 input, it doesn't change the frame rate of the input.  Effects before
7456 ReframeRT assume the same frame rate as ReframeRT.
7457
7458 @b{Downsample} mode doesn't change the length of the output sequence. 
7459 It multiplies the frame rate of the output by the scale factor to
7460 arrive at a frame rate rate to read the input.  This has the effect of
7461 replicating the input frames so that they only change at the scaled
7462 frame rate when sent to the output.  It doesn't change the length of
7463 the sequence.  If the scale factor is 0.5 and the output frame rate is
7464 30 fps, only 15 frames will be shown per second and the input will be
7465 read at 15 fps.  Downsample is only useful for scalefactors below 1,
7466 hence the name downsample.
7467
7468 Downsample mode changes the frame rate of the input as well as the
7469 number of the frame to read, so effects before ReframeRT see the frame
7470 rate * the scale factor as their frame rate.  If the scale factor is 2
7471 and the output frame rate is 30, the input frame rate will be 60 and
7472 the input frame number will by doubled.  This won't normally do
7473 anything but some input effects may behave differently at the higher
7474 frame rate.
7475
7476
7477
7478
7479 @node REFRAME
7480 @section REFRAME
7481
7482 This does exactly the same thing as @b{ReframeRT} in @b{Stretch} mode. 
7483 It multiplies the output frame number by the scale factor to arrive at
7484 the input frame number and changes the length of the sequence.  Unlike
7485 ReframeRT, this must run from the @b{Video} menu and render its output.
7486
7487 Be aware @b{Reframe} doesn't write the scaled frame rate as the frame
7488 rate of the rendered file.  It produces a file of scaled length and
7489 equal frame rate as the project.  The new length is 1/scale factor as
7490 big as the original sequence.
7491
7492
7493
7494
7495
7496
7497
7498
7499 @node RESAMPLE
7500 @section RESAMPLE
7501
7502 This multiplies the number of each output sample by a scale factor to
7503 arrive at the number of the input sample.  The output file's sample
7504 rate is set to the project sample rate but its length is changed to
7505 reflect the scaled number of samples.  It also filters the resampled
7506 audio to remove aliasing.
7507
7508 If the scale factor is 2, every 2 input samples will be reduced to 1
7509 output sample and the output file will have half as many samples as the
7510 input sequence.  If it's 0.5, every 0.5 input samples will be stretched
7511 to 1 output sample and the output file will have twice as many samples
7512 as the input sequence.
7513
7514
7515
7516
7517
7518
7519
7520
7521
7522
7523 @node REVERSE VIDEO/AUDIO
7524 @section REVERSE VIDEO/AUDIO
7525
7526 Media can be reversed on the timeline in realtime.  This isn't to be
7527 confused with using the reverse playback on the transport.  The reverse
7528 effects reverse the region covered by the effect regardless of the
7529 transport direction.  Apply @b{reverse audio} to an audio track and
7530 play it backwards.  The sound plays forward.
7531
7532 The region to be reversed is first determined by what part of the track
7533 the effect is under and second by the locations of keyframes in the
7534 effect.  The reverse effects have an @b{enabled} option which allows
7535 you to set keyframes.  This allows may possibilities.
7536
7537 Every @b{enabled} keyframe is treated as the start of a new reversed
7538 region and the end of a previous reversed region.  Several @b{enabled}
7539 keyframes in succession yield several regions reversed independant of
7540 each other.  An @b{enabled} keyframe followed by a @b{disabled}
7541 keyframe yields one reversed region followed by a forward region.
7542
7543 Finally, be aware when reversing audio that the waveform on the
7544 timeline doesn't reflect the actual reversed output.
7545
7546
7547
7548
7549 @node SWAP FRAMES
7550 @section SWAP FRAMES
7551
7552 This is normally used on interlaced video which has been converted to
7553 fields.  One set of lines becomes one frame and the other set of lines
7554 becomes the next frame.  Now the frame rate is double and is showing
7555 fields of the original video sequentially.  The fields may be out of
7556 order, which is what @b{SWAP FRAMES} can correct.
7557
7558
7559
7560
7561
7562
7563
7564
7565
7566
7567
7568
7569 @node THRESHOLD
7570 @section THRESHOLD
7571
7572 Threshold converts the image to pure luminance.  Then luminance values
7573 below and above the threshold range are converted to black and
7574 luminance values inside the threshold range are converted to white. 
7575 The threshold window shows a histogram of luminance values for the
7576 current frame.  Click dragging inside the histogram creates a range to
7577 convert to white.  Shift-clicking extends one border of this range. 
7578 Values for the threshold range can also be specified in the text boxes.
7579
7580 This effect is basically a primitive luminance key.  A second track
7581 above the track with the threshold effect can be multiplied, resulting
7582 in only the parts of the second track within the threshold being
7583 displayed.
7584
7585
7586
7587
7588
7589
7590
7591 @node TIME AVERAGE
7592 @section TIME AVERAGE
7593
7594 Time average is one effect which has many uses besides creating nifty
7595 trail patterns of moving objects.  It's main use is reducing noise in
7596 still images.  Merely point a video camera at a stationary subject for
7597 30 frames, capture the frames, and average them using TIME AVERAGE and
7598 you'll have a super high quality print.  In floating point colormodels, time
7599 average can increase the dynamic range of lousy cameras.
7600
7601 Inside the time average effect is an accumulation buffer and a
7602 divisor.  A number of frames are accumulated in the accumulation buffer
7603 and divided by the divisor to get the average.
7604
7605 Because the time average can consume enourmous amounts of memory, it is
7606 best applied by first disabling playback for the track, dropping the
7607 time average in it, configuring time average for the desired number of
7608 frames, and re-enabling playback for the track.
7609
7610 @b{Frames count:} This determines the number of frames to be accumulated
7611 in the accumulation buffer.  For extremely large integrations it's
7612 easier to edit the EDL in a text editor and put in the number of frames.
7613
7614 @b{Accumulate sequence again:} If an effect before the time average is
7615 adjusted the time average normally doesn't reread the accumulation
7616 buffer to get the change.  This forces it to reread the accumulation
7617 buffer when any other effects change.
7618
7619
7620 @b{Average:} This causes the accumulation buffer to be divided before
7621 being output.  The result is the average of all the frames.
7622
7623 @b{Accumulate:} This outputs the accumulation buffer without dividing
7624 it.  The result is the sum of all the frames.
7625
7626 @b{Accumulate only:}
7627
7628 In order to accumulate only the specified number of frames, the time
7629 average retains all the previous frames in memory and subtracts them out
7630 as it plays forward.  @b{Accumulate only:} causes the history buffer to
7631 not be used in @b{averaging} and @b{accumulating}.  Without the history
7632 buffer, frames are added endlessly without ever being subtracted.  It's
7633 the same as an infinitely long accumulation buffer.  The only difference
7634 is for @b{Average} mode, the output is still divided by the @b{Frame
7635 count}.  @b{Accumulate only} is used where the number of frames in the
7636 accumulation would be too big to fit in memory.
7637
7638 @b{Replace:} This causes the accumulation buffer to be replaced by only
7639 pixels which aren't transparent.  This allows black borders from motion
7640 tracking to be filled in.
7641
7642 @b{Threshold:} The value a pixel must be before it replaces the previous
7643 pixel.  If alpha channels are enabled, the alpha is the value compared. 
7644 If there is no alpha channel, the brightness is the value compared.
7645
7646 @b{Border:} The number of pixels on the border of the image to never
7647 replace.  This hides errors in the replacement operation from the
7648 output, since errors occur at the transition between the replaced area
7649 and the ignored area.
7650
7651 @b{Greater:} Pixels are replaced if their value is greater than the
7652 previous pixel.  Use this to create star trails in stacks of many night
7653 sky photos or paint many copies of an object from its motion if it is
7654 lighter than the background.
7655
7656 @b{Less:} Pixels are replaced if their value is less than the previous
7657 pixel.  Use this to paint copies of an object from its motion if it is
7658 darker than the background.
7659
7660
7661
7662
7663
7664
7665
7666 @node TITLER
7667 @section TITLER
7668
7669 While it is possible to add text to movies by importing still images
7670 from The Gimp and compositing them, the Titler allows you to add text
7671 from within Cinelerra.  
7672
7673 The titler has standard options for @b{font, size, and style}.  The
7674 best font is a generic, normal font like Arial in a large size.
7675
7676 The titler also has options you'll only find in moving pictures.  The
7677 @b{Justify} operation justifies the text relative to the entire frame. 
7678 Once justified, the @b{X and Y} offset is applied.  This allows text to
7679 be justified while at the same time letting you push it within the
7680 title safe region.
7681
7682 The @b{motion type} scrolls the text in any of the four directions. 
7683 When using this, the text may dissappear.  Move the insertion point
7684 along the timeline until the text is far enough along the animation to
7685 reappear.  The text scrolls on and scrolls off.
7686
7687 Setting @b{loop} causes the text to scroll completely off and repeat. 
7688 Without @b{loop} the text scrolls off and never reappears.
7689
7690 The speed of the animation is determined by @b{speed}  Set it higher to
7691 speed up the animation.
7692
7693 @b{Drop shadow} draws a black copy of the text to the bottom right of
7694 the original text.  Useful when drawing text over changing video to
7695 keep the border always visible.
7696
7697 In addition to the scrolling, @b{Fade in/Fade out} are a second type of
7698 animation.  If the fade seconds are 0, no fading is done.
7699
7700 @b{Outline} draws an outline on the characters if it's greater than 0. 
7701 Set the outline size by changing the number.  Set the outline color with
7702 the @b{OUTLINE COLOR} button.  If no outline is visible, make sure the
7703 alpha in @b{OUTLINE COLOR} is nonzero.  To get pure outline characters,
7704 set @b{COLOR} alpha to 0.
7705
7706 @b{COLOR} picks the color to draw the text in.  Usually white is the
7707 only practical color.
7708
7709 @b{OUTLINE COLOR} picks the color to draw the text outline in.
7710
7711 @b{Stamp timecode} replaces the text with the current position on the
7712 timeline in seconds and frames.
7713
7714 @b{SECRETS OF THE TITLER}
7715 @menu
7716 * ADDING FONTS TO THE TITLER:: How to add fonts to the titler
7717 * THE TITLE-SAFE REGION::      How to keep text visible on output
7718 * MAKING TITLES LOOK GOOD::    How to make your titles look good.
7719 @end menu
7720
7721 @node ADDING FONTS TO THE TITLER
7722 @subsection ADDING FONTS TO THE TITLER
7723
7724 The X Window system originally didn't have a suitable font renderer for
7725 video.  It also is restricted to the current bit depth.  It doesn't
7726 have a convenient way to know which fonts work with the suitable font
7727 renderer in the desired bit depth.  The easiest way we've found to
7728 support fonts in the titler is to have a directory for them at
7729 @b{/usr/lib/cinelerra/fonts}.
7730
7731 The titler supports mainly @b{TTF}, true type fonts.  It supports
7732 others but TTF are the most reliable.  To add true type fonts, copy the
7733 @b{.TTF} files to the @b{/usr/lib/cinelerra/fonts} directory.  In that
7734 directory run @b{ttmkfdir && mv fonts.scale fonts.dir} and restart
7735 Cinelerra.  The new fonts should appear.  The usage of ttmkfdir changes
7736 frequently so this technique might not work.
7737
7738
7739 @node THE TITLE-SAFE REGION
7740 @subsection THE TITLE-SAFE REGION
7741
7742 If the video is displayed on a consumer TV, the outer border is going
7743 to be cropped by 5% on each side.  Moreover, text which is too close to
7744 the edge looks sloppy.  Make sure when adding titles to have the
7745 @b{title-safe} @image{titlesafe} tool active in the @b{compositor} window.
7746 The text shouldn't cross the inner rectangle.
7747
7748
7749 @node MAKING TITLES LOOK GOOD
7750 @subsection MAKING TITLES LOOK GOOD
7751
7752 No-one else is going to tell you this, but to make good looking titles,
7753 ignore most of the features of the titler.  The best settings are:
7754
7755 @itemize
7756 @item
7757 Font: @b{Arial}
7758 @item
7759 Italic: @b{off}
7760 @item
7761 Motion: @b{No motion}
7762 @item
7763 Bold: @b{on or off}
7764 @item
7765 Fade in: @b{0}
7766 @item
7767 Fade out: @b{0}
7768 @item
7769 Color: @b{white}
7770 @item
7771 Outline color: @b{black}
7772 @item
7773 Drop Shadow or outline: @b{use either to improve contrast but not both}
7774 @end itemize
7775
7776
7777 Don't waste the audience's time with fading & crawls.  Use crawls only
7778 if there's too much text to fit on the screen.  The title should be
7779 legible enough to take the least amount of time to read.  You're
7780 supposed to show the story, not write it.  If they wanted to read a
7781 story, they would be reading a book instead of watching video.
7782
7783
7784
7785
7786
7787
7788
7789
7790
7791
7792
7793
7794
7795
7796 @node VIDEO SCOPE
7797 @section VIDEO SCOPE
7798
7799 The video scope plots two views of the image.  One view plots the
7800 intensity of each pixel against horizontal position.  They call this
7801 the WAVEFORM.  Another view translates hue to angle and saturation to
7802 radius for each pixel.  They call this the VECTORSCOPE.
7803
7804 The vectorscope is actually very useful for determining if an image is
7805 saturated.  When adjusting saturation, it's important to watch the
7806 vectorscope to make sure pixels don't extend past the 100 radius.
7807
7808 The waveform allows you to make sure image data extends from complete
7809 black to complete white while adjusting the brightness/contrast.
7810
7811 Some thought is being given to having a video scope for recording. 
7812 Unfortunately, this would require a lot of variations of the video
7813 scope for all the different video drivers.
7814
7815
7816
7817
7818
7819 @node PLUGIN AUTHORING
7820 @chapter PLUGIN AUTHORING
7821
7822 The plugin API in Cinelerra dates back to 1997, before the LADSPA and
7823 before VST became popular.  It's fundamentally the same as it was in
7824 1997, with minor modifications to handle keyframes and GUI feedback. 
7825 The GUI is not abstracted from the programmer.  This allows the
7826 programmer to use whatever toolkit they want and allows more
7827 flexibility in appearance but it costs more.
7828
7829 There are several types of plugins, each with a common method of
7830 implementation and specific changes for that particular type.  The
7831 easiest way to implement a plugin is to take the simplest existing one
7832 out of the group and rename the symbols.  
7833
7834
7835
7836 @menu
7837 * INTRODUCING THE PULL METHOD:: The current paradigm for plugin writing
7838 * COMMON PLUGIN FUNCTIONS:: What all effects have to do.
7839 * REALTIME PLUGINS:: What realtime effects have to do.
7840 * NONREALTIME PLUGINS:: What rendered effects have to do.
7841 * AUDIO PLUGINS:: What audio effects have to do.
7842 * VIDEO PLUGINS:: What video effects have to do.
7843 * TRANSITION PLUGINS:: What transitions have to do.
7844 * PLUGIN GUI'S WHICH UPDATE DURING PLAYBACK:: How to use currently playing data to draw the GUI.
7845 * USING OPENGL:: How to use hardware to speed up operations.
7846 * PLUGIN QUERIES:: How plugins get information about the data to be processed.
7847 @end menu
7848
7849
7850
7851
7852 @node INTRODUCING THE PULL METHOD
7853 @section INTRODUCING THE PULL METHOD
7854
7855 Originally plugins were designed with the push method.  The push method
7856 is intuitive and simple.  A source pushes data to a plugin, the plugin
7857 does math operations on it, and the plugin pushes it to a destination. 
7858 For 6 years this was the way all realtime plugins were driven
7859 internally but it didn't allow you to reduce the rate of playback in
7860 realtime.  While plugins can still be designed as if they're pushing
7861 data, this is not the way they're processed internally anymore.
7862
7863 The latest evolution in Cinelerra's plugin design is the pull method. 
7864 The rendering pipeline starts at the final output and the final steps
7865 in the rendering pipeline are reading the data from disk.  Every step
7866 in the rendering chain involves requesting data from the previous
7867 step.  When the rendering pipleline eventually requests data from a
7868 plugin chain, each plugin requests data from the plugin before it.
7869
7870 This is less intuitive than the push method but is much more powerful. 
7871 Realtime plugins written using the pull method can change the rate data
7872 is presented to the viewer and the direction of playback.  The pull
7873 method allows plugins to take in data at a higher rate than they send
7874 it out.
7875
7876 To get the power of rate independance, the pull method requires plugins
7877 to know more about the data than they needed to under the push method. 
7878 Plugins need to know what rate the project is at, what rate their
7879 output is supposed to be at and what rate their input is supposed to be
7880 at.  These different data rates have to be correlated for a plugin to
7881 configure itself properly.
7882
7883 Keyframes for a plugin are stored relative to the project frame rate. 
7884 Queries from a plugin for for the current playback position are given
7885 relative to the project frame rate.  If the plugin's output was
7886 requested to be at twice the project frame rate, the positions need to
7887 be converted to the project rate for keyframes to match up.  Two
7888 classes of data rates were created to handle this problem.
7889
7890 Rate conversions are done in terms of the @b{project rate} and the
7891 @b{requested rate}.  The project rate is identical for all plugins.  It
7892 is determined by the @b{settings->format} window.  The requested rate
7893 is determined by the downstream plugin requesting data from the current
7894 plugin.  The requested rate is arbitrary.  Exactly how to use these
7895 rates is described below.
7896
7897
7898
7899 @node COMMON PLUGIN FUNCTIONS
7900 @section COMMON PLUGIN FUNCTIONS
7901
7902 All plugins inherit from a derivative of PluginClient.  This
7903 PluginClient derivative implements most of the required methods in
7904 PluginClient, but users must still define methods for PluginClient. 
7905 The most commonly used methods are predefined in macros to reduce the
7906 typing yet still allow flexibility.
7907
7908 The files they include depend on the plugin type.  Audio plugins
7909 include @b{pluginaclient.h} and video plugins include
7910 @b{pluginvclient.h}.  They inherit @b{PluginAClient} and
7911 @b{PluginVClient} respectively.
7912
7913 Cinelerra instantiates all plugins at least twice when they are used in
7914 a movie.  Once instance is the GUI.  The other instance is the signal
7915 processor.  User input, through a complicated sequence, is propogated
7916 from the GUI instance to the signal processor instance.  If the signal
7917 processor wants to alter the GUI, it propogates data back to the GUI
7918 instance.  There are utility functions for doing all this.
7919
7920 All plugins define at least three objects:
7921
7922 @itemize
7923
7924 @item
7925
7926 @b{Processing object} - Contains pointers to all the other objects and
7927 performs the signal processing.  This object contains a number of
7928 queries to identify itself and is the object you register to register
7929 the plugin.
7930
7931
7932 @item
7933
7934 @b{User interface object} - This is a subclass of
7935 @b{PluginClientWindow}.  It shows data on the screen and collects
7936 parameters from the user.
7937
7938 The window has pointers to a number of widgets, a few initialization
7939 methods, and a back pointer to the plugin's processing object.  The GUI
7940 uses Cinelerra's toolkit.  The plugin abstraction layer handles creating
7941 a thread for the GUI.
7942
7943
7944
7945 @item
7946
7947 @b{Configuration object} - This stores the user parameters and always
7948 needs interpolation, copying, and comparison functions.  Macros for the
7949 plugin client automatically call configuration methods to interpolate
7950 keyframes.
7951
7952 @end itemize
7953
7954 @menu
7955 * THE PROCESSING OBJECT::
7956 * THE CONFIGURATION OBJECT::
7957 * THE USER INTERFACE OBJECT::
7958 @end menu
7959
7960
7961
7962 @node THE PROCESSING OBJECT
7963 @subsection THE PROCESSING OBJECT
7964
7965 Load up a simple plugin like gain to see what this object looks like.
7966 The processing object should inherit from the intended PluginClient
7967 derivative.  Its constructor should take a PluginServer argument.
7968
7969 @example
7970 MyPlugin(PluginServer *server);
7971 @end example
7972
7973 In the implementation, the plugin must contain a registration line with
7974 the name of the processing object like
7975
7976 @example
7977 REGISTER_PLUGIN(MyPlugin)
7978 @end example
7979
7980
7981
7982
7983 Another function which is useful but not mandatory is
7984
7985 @example
7986 int is_multichannel();
7987 @end example
7988
7989 It should return 1 if one instance of the plugin handles multiple
7990 tracks simultaneously or 0 if one instance of the plugin only handles
7991 one track.  The default is 0 if it is omitted.
7992
7993 Multichannel plugins in their processing function should refer to a
7994 function called @b{PluginClient::get_total_buffers()} to determine the
7995 number of channels.
7996
7997
7998
7999
8000 To simplify the implementation of realtime plugins, a macro for
8001 commonly used members has been created for the class header, taking the
8002 configuration object and user interface thread object as arguments. 
8003 The macro definitions apply mainly to realtime plugins and are not
8004 useful in nonrealtime plugins.  Fortunately, nonrealtime plugins are
8005 simpler.
8006
8007 @example
8008 PLUGIN_CLASS_MEMBERS(config_name, thread_name)
8009 @end example
8010
8011 The commonly used members in PLUGIN_CLASS_MEMBERS are described below.
8012
8013 @itemize
8014
8015 @item
8016 int load_configuration();
8017
8018 Loads the configuration based on surrounding keyframes and current
8019 position.  The class definition for load_configuration should contain 
8020
8021 @example
8022 LOAD_CONFIGURATION_MACRO(plugin_class, config_class)
8023 @end example
8024
8025 to implement the default behavior for load_configuration.  This stores
8026 whatever the current configuration is inside the plugin's configuration
8027 object and returns 1 if the new configuration differs from the previous
8028 configuration.  The return value of load_configuration is used by
8029 another commonly used function, update_gui to determine if the GUI really needs to be updated.
8030
8031 The plugin's configuration object is always called @b{config} inside
8032 PLUGIN_CLASS_MEMBERS.
8033
8034 @item
8035 VFrame* new_picon();
8036
8037 Creates a picon for display in the resource window.  Use
8038
8039 @example
8040 #include "picon_png.h"
8041 NEW_PICON_MACRO(plugin_class)
8042 @end example
8043
8044 to implement new_picon.  In addition, the user should create a
8045 @b{picon_png.h} header file from a PNG image using @b{pngtoh}. 
8046 @b{pngtoh} is compiled in the @b{guicast/ARCH} directory.
8047
8048 The source PNG image should be called picon.png and can be any format
8049 supported by PNG.
8050
8051 @item
8052 char* plugin_title();
8053
8054 Returns a text string identifying the plugin in the resource window. 
8055 The string has to be unique.
8056
8057
8058 @item
8059 void update_gui(); 
8060
8061 Should first load the configuration, test for a return of 1, and then
8062 redraw the GUI with the new parameters.  All the plugins using GuiCast
8063 have a format like
8064
8065 @example
8066 void MyPlugin::update_gui()
8067 @{
8068         if(thread)
8069         @{
8070                 if(load_configuration())
8071                 @{
8072                         thread->window->lock_window();
8073 // update widgets here
8074                         thread->window->unlock_window();
8075                 @}
8076         @}
8077 @}
8078 @end example
8079
8080 to handle concurrency and conditions of no GUI.
8081
8082
8083
8084
8085 @end itemize
8086
8087
8088 Important functions the processing object must define are the
8089 functions which load and save configuration data from keyframes.  These
8090 functions are called by the macros so all you need to worry about is
8091 accessing the keyframe data.
8092
8093 @example
8094 void save_data(KeyFrame *keyframe);
8095 void read_data(KeyFrame *keyframe);
8096 @end example
8097
8098 The read data functions are only used in realtime plugins.  The read
8099 data functions translate the plugin configuration between the KeyFrame
8100 argument and the configuration object for the plugin.  The keyframes
8101 are stored on the timeline and can change for every project.
8102
8103 Use an object called @b{FileXML} to do the translation and some
8104 specific commands to get the data out of the KeyFrame argument.  See
8105 any existing plugin to see the usage of KeyFrame and FileXML.
8106
8107
8108 @example
8109 int load_defaults();
8110 int save_defaults();
8111 @end example
8112
8113 The load defaults functions are used in realtime and non-realtime
8114 plugins.  The load defaults functions translate the plugin
8115 configuration between a BC_Hash object and the plugin's
8116 configuration.  The BC_Hash object stores configurations in a discrete
8117 file on disk for each plugin but doesn't isolate different
8118 configurations for different projects.
8119
8120 The function overriding @b{load_defaults} also needs to call @b{defaults
8121 = new BC_Hash(path);} with the configuration path.  See any existing
8122 plugin to see the usage of BC_Hash.   The function overriding
8123 @b{save_defaults} does not create @b{defaults}.
8124
8125 Other standard members may be defined in the processing object,
8126 depending on the plugin type.
8127
8128
8129
8130
8131 @node THE CONFIGURATION OBJECT
8132 @subsection THE CONFIGURATION OBJECT
8133
8134 The configuration object is critical for GUI updates, signal
8135 processing, and default settings in realtime plugins.  Be aware it is
8136 not used in nonrealtime plugins.  The configuration object inherits
8137 from nothing and has no dependancies.  It's merely a class containing
8138 three functions and variables specific to the plugin's parameters.
8139
8140 Usually the configuration object starts with the name of the plugin
8141 followed by Config.
8142
8143 @example
8144 class MyPluginConfig
8145 @{
8146 public:
8147         MyPluginConfig();
8148 @end example
8149
8150
8151 Following the name of the configuration class, we put in three
8152 required functions and the configuration variables.
8153
8154 @example
8155         int equivalent(MyPluginConfig &that);
8156         void copy_from(MyPluginConfig &that);
8157         void interpolate(MyPluginConfig &prev, 
8158                 MyPluginConfig &next, 
8159                 int64_t prev_position, 
8160                 int64_t next_position, 
8161                 int64_t current_position);
8162
8163
8164
8165         float parameter1;
8166         float parameter2;
8167         int parameter3;
8168 @};
8169
8170 @end example
8171
8172
8173 Now you must define the three functions.  @b{Equivalent} is called by
8174 LOAD_CONFIGURATION_MACRO to determine if the local configuration
8175 parameters are identical to the configuration parameters in the
8176 arguement.  If equivalent returns 0, the LOAD_CONFIGURATION_MACRO 
8177 causes the GUI to redraw.  If equivalent returns 1, the
8178 LOAD_CONFIGURATION_MACRO doesn't redraw the GUI.
8179
8180 Then there's @b{copy_from} which transfers the configuration values
8181 from the argument to the local variables.  This is once again used in
8182 LOAD_CONFIGURATION_MACRO to store configurations in temporaries.  Once 
8183 LOAD_CONFIGURATION_MACRO has replicated the configuration, it loads a
8184 second configuration.  Then it interpolates the two configurations to
8185 get the current configuration.  The interpolation function performs the
8186 interpolation and stores the result in the local variables.
8187
8188 Normally the interpolate function calculates a previous and next
8189 fraction, using the arguments.
8190
8191 @example
8192 void MyPluginConfig::interpolate(MyPluginConfig &prev, 
8193                 MyPluginConfig &next, 
8194                 int64_t prev_position, 
8195                 int64_t next_position, 
8196                 int64_t current_position)
8197 @{
8198         double next_scale = (double)(current_position - prev_position) / (next_position - prev_position);
8199         double prev_scale = (double)(next_position - current_position) / (next_position - prev_position);
8200 @end example
8201
8202 Then the fractions are applied to the previous and next configuration
8203 variables to yield the current values.
8204
8205 @example
8206
8207         this->parameter1 = (float)(prev.parameter1 * prev_scale + next.parameter1 * next_scale);
8208         this->parameter2 = (float)(prev.parameter2 * prev_scale + next.parameter2 * next_scale);
8209         this->parameter3 = (int)(prev.parameter3 * prev_scale + next.parameter3 * next_scale);
8210 @}
8211
8212 @end example
8213
8214 Alternatively you can copy the values from the previous configuration
8215 argument if no interpolation is desired.
8216
8217 This usage of the configuration object is the same in audio and video
8218 plugins.  In video playback, the interpolation function is called for
8219 every frame, yielding smooth interpolation.  In audio playback, the
8220 interpolation function is called only once for every console fragment
8221 and once every time the insertion point moves.  This is good enough for
8222 updating the GUI while selecting regions on the timeline but it may not
8223 be accurate enough for really smooth rendering of the effect.
8224
8225 For really smooth rendering of audio, you can still use
8226 load_configuration when updating the GUI.  For process_buffer; however,
8227 ignore load_configuration and write your own interpolation routine
8228 which loads all the keyframes in a console fragment and interpolates
8229 every sample.  This would be really slow and hard to debug, yielding
8230 improvement which may not be audible.  Then of course, every country
8231 has its own wierdos.
8232
8233 An easier way to get smoother interpolation is to reduce the console
8234 fragment to 1 sample.  This would have to be rendered and played back
8235 with the console fragment back over 2048 of course.  The Linux sound
8236 drivers can't play fragments of 1 sample.
8237
8238
8239
8240
8241
8242
8243
8244
8245 @node THE USER INTERFACE OBJECT
8246 @subsection THE USER INTERFACE OBJECT
8247
8248
8249 The user interface object is derived from @b{PluginClientWindow}.  The
8250 user must call @b{NEW_WINDOW_MACRO} in the processing object to create
8251 the @b{PluginClientWindow}.  This system is used in realtime plugins but
8252 not in nonrealtime plugins.
8253
8254 Nonrealtime plugins create and destroy their own GUI in their
8255 @b{get_parameters} function and there's no need for a
8256 @b{PluginClientWindow} subclass.
8257
8258 Now the window class must be declared in the plugin header.  It's
8259 easiest to implement the window by copying an existing plugin and
8260 renaming the symbols.  The following is an outline of what happens. 
8261 The plugin header must declare the window's constructor using the
8262 appropriate arguments.
8263
8264 @example
8265
8266 #include "guicast.h"
8267
8268 MyWindow::MyWindow(MyPlugin *plugin)
8269  : PluginClientWindow(plugin, 
8270         440, 
8271         500, 
8272         440, 
8273         500, 
8274         0)
8275 @{
8276
8277 @end example
8278
8279 This becomes a window on the screen with the size given by the arguments
8280 to @b{PluginClientWindow}.
8281
8282 It needs two methods
8283
8284 @example
8285         void create_objects();
8286 @end example
8287
8288 and a back pointer to the plugin
8289
8290 @example
8291         MyPlugin *plugin;
8292 @end example
8293
8294
8295 The create_objects member puts widgets in the window according to
8296 GuiCast's syntax.  A pointer to each widget which you want to
8297 synchronize to a configuration parameter is stored in the window class. 
8298 These are updated in the @b{update_gui} function you earlier defined for
8299 the plugin.  The widgets are usually derivatives of a GuiCast widget and
8300 they override functions in GuiCast to handle events.  Finally
8301 create_objects calls 
8302
8303 @example
8304         show_window();
8305 @end example
8306
8307 to make the window appear all at once.
8308
8309 Every widget in the GUI needs to detect when its value changes.  In
8310 GuiCast the @b{handle_event} method is called whenever the value
8311 changes.  In @b{handle_event}, the widget then needs to call
8312 @b{plugin->send_configure_change()} to propogate the change to any
8313 copies of the plugin which are processing data.
8314
8315
8316
8317
8318
8319
8320
8321
8322
8323 @node REALTIME PLUGINS
8324 @section REALTIME PLUGINS
8325
8326 Realtime plugins should use PLUGIN_CLASS_MEMBERS to define the basic
8327 set of members in their headers.  All realtime plugins must define an
8328
8329 @example
8330 int is_realtime()
8331 @end example
8332
8333 member returning 1.  This causes a number of methods to be called
8334 during live playback and the plugin to be usable on the timeline.
8335
8336 Realtime plugins must override a member called
8337
8338 @example
8339 process_buffer 
8340 @end example
8341
8342 This function takes different arguments depending on if the plugin
8343 handles video or audio.  See an existing plugin to find out which usage
8344 applies.
8345
8346 The main features of the process_buffer function are a buffer to store
8347 the output, the starting position of the output, and the requested
8348 output rate.  For audio, there's also a size argument for the number of
8349 samples.
8350
8351 The starting position of the output buffer is the lowest numbered
8352 sample on the timeline if playback is forward and the highest numbered
8353 sample on the timeline if playback is reverse.  The direction of
8354 playback is determined by one of the plugin queries described below.
8355
8356 The position and size arguments are all relative to the frame rate and
8357 sample rate passed to process_buffer.  This is the requested data rate
8358 and may not be the same as the project data rate.
8359
8360 The process_realtime function should start by calling
8361 @b{load_configuration}.  The LOAD_CONFIGURATION_MACRO returns 1 if the
8362 configuration changed.
8363
8364 After determining the plugin's configuration, input media has to be
8365 loaded for processing.  Call
8366
8367 @example
8368 read_frame(VFrame *buffer, 
8369                 int channel, 
8370                 int64_t start_position,
8371                 double frame_rate)
8372 @end example
8373
8374 or
8375
8376 @example
8377 read_samples(double *buffer,
8378                 int channel,
8379                 int sample_rate,
8380                 int64_t start_position,
8381                 int64_t len)
8382 @end example
8383
8384 to request input data from the object which comes before this plugin. 
8385 The read function needs a buffer to store the input data in.  This can
8386 either be a temporary you create in the plugin or the output buffer
8387 supplied to process_buffer if you don't need a temporary.
8388
8389 It also needs a set of position arguments to determine when you want to
8390 read the data from.  The start position, rate, and len passed to a read
8391 function need not be the same as the values recieved by the
8392 process_buffer function.  This way plugins can read data at a different
8393 rate than they output data.
8394
8395 The channel argument is only meaningful if this is a multichannel
8396 plugin.  They need to read data for each track in the
8397 get_total_buffers() value and process all the tracks.  Single channel
8398 plugins should pass 0 for channel.
8399
8400
8401 Additional members are implemented to maintain configuration in
8402 realtime plugins.  Some of these are also needed in nonrealtime
8403 plugins.
8404
8405 @itemize
8406 @item
8407 void read_data(KeyFrame *keyframe);
8408
8409 Loads data from a keyframe into the plugin's configuration.  Inside the
8410 keyframe is an XML string.  It's most easily parsed by creating a
8411 @b{FileXML} object.  See an existing plugin to see how the read_data
8412 function is implemented.
8413
8414 Read data loads data out of the XML object and stores values in the
8415 plugin's configuration object.  Since configuration objects vary from
8416 plugin to plugin, these functions can't be automated.
8417
8418 @item
8419 void save_data(KeyFrame *keyframe);
8420
8421 Saves data from the plugin's configuration to a keyframe.  Inside the
8422 keyframe you'll put an XML string which is normally created by a
8423 FileXML object.  See an existing plugin to see how the save_data
8424 function is implemented.
8425
8426 Save data saves data from the plugin's configuration object into the
8427 XML object.
8428
8429 @item
8430 int load_defaults();
8431
8432 Another way the plugin gets parameters is from a defaults file.  The
8433 load and save defaults routines use a BC_Hash object to parse the
8434 defaults file.  The defaults object is created in @b{load_defaults} and
8435 destroyed in the plugin's destructor.  See an existing plugin to see
8436 how the BC_Hash object is used.
8437
8438 @item
8439 int save_defaults();
8440
8441 Saves the configuration in the defaults object.
8442
8443 @end itemize
8444
8445
8446
8447
8448
8449
8450 @node NONREALTIME PLUGINS
8451 @section NONREALTIME PLUGINS
8452
8453 Some references for non-realtime plugins are @b{Normalize} for audio
8454 and @b{Reframe} for video.
8455
8456 Like realtime plugins, @b{load_defaults} and @b{save_defaults} must be
8457 implemented.  In nonrealtime plugins, these are not just used for
8458 default parameters but to transfer values from the user interface to
8459 the signal processor.  There doesn't need to be a configuration class
8460 in nonrealtime plugins.
8461
8462 Unlike realtime plugins, the LOAD_CONFIGURATION_MACRO can't be used in
8463 the plugin header.  Instead, the following methods must be defined.
8464
8465 The nonrealtime plugin should contain a pointer to a defaults object.
8466
8467 @example
8468
8469 BC_Hash *defaults;
8470
8471 @end example
8472
8473 It should also have a pointer to a MainProgressBar.
8474
8475 @example
8476
8477 MainProgressBar *progress;
8478 @end example
8479
8480 The progress pointer allows nonrealtime plugins to display their
8481 progress in Cinelerra's main window.
8482
8483 The constructor for a nonrealtime plugin can't use
8484 PLUGIN_CONSTRUCTOR_MACRO but must call @b{load_defaults} directly.
8485
8486 The destructor, likewise, must call @b{save_defaults} and @b{delete
8487 defaults} directly instead of PLUGIN_DESTRUCTOR_MACRO.
8488
8489 @itemize
8490
8491 @item
8492 VFrame* new_picon();
8493
8494 char* plugin_title();
8495
8496 The usage of these is the same as realtime plugins.
8497
8498 @item
8499 int is_realtime();
8500
8501 This function must return 0 to indicate a nonrealtime plugin.
8502
8503 @item
8504
8505 int get_parameters();
8506
8507 Here, the user should create a GUI, wait for the user to hit an OK
8508 button or a cancel button, and store the parameters in plugin
8509 variables.  This routine must return 0 for success and 1 for failure. 
8510 This way the user can cancel the effect from the GUI.
8511
8512 Unlike the realtime plugin, this GUI need not run asynchronously of the
8513 plugin.  It should block the get_parameters function until the user
8514 selects OK or Cancel.
8515
8516 @item
8517 int load_defaults();
8518
8519 This should set the @b{defaults} variable to a new @b{Defaults} object
8520 and load parameters from the defaults object into plugin variables.
8521
8522 @item
8523 int save_defaults();
8524
8525 This should save plugin variables to the defaults object.  It should not
8526 create the defaults object.
8527
8528
8529 @item
8530 int start_loop();
8531
8532 If @b{get_parameters} returned 0 for success, this is called once to
8533 give the plugin a chance to initialize processing.  The plugin should
8534 instantiate the progress object with a line like
8535
8536 @example
8537
8538 progress = start_progress("MyPlugin progress...", 
8539         PluginClient::get_total_len());
8540
8541 @end example
8542
8543 The usage of @b{start_progress} depends on whether the plugin is
8544 multichannel or single channel.  If it's multichannel you always call
8545 start_progress.  If it's single channel, you first need to know whether
8546 the progress bar has already started in another instance of the plugin.
8547
8548 If @b{PluginClient::interactive} is 1, you need to start the progress
8549 bar.  If it's 0, the progress bar has already been started.
8550
8551 The PluginClient defines @b{get_total_len()} and @b{get_source_start()}
8552 to describe the timeline range to be processed.  The units are either
8553 samples or frames and in the project rate.
8554
8555 @item
8556 int process_loop
8557
8558 This is called repeatedly until the timeline range is processed.  It
8559 has either a samples or frames buffer for output and a reference to
8560 write_length to store the number of samples processed.  If this is an
8561 audio plugin, the user needs to call @b{get_buffer_size()} to know how
8562 many samples the output buffer can hold.
8563
8564 The plugin must use @b{read_samples} or @b{read_frame} to read the
8565 input.  These functions are a bit different for a non realtime plugin
8566 than they are for a realtime plugin.
8567
8568 They take a buffer and a position relative to the start of the
8569 timeline, in the timeline's rate.  Then you must process it and put the
8570 output in the buffer argument to process_loop.  write_length should
8571 contain the number of samples generated if it's audio.
8572
8573 Finally, process_loop must test @b{PluginClient::interactive} and
8574 update the progress bar if it's 1.
8575
8576 @example
8577 progress->update(total_written);
8578 @end example
8579
8580 returns 1 or 0 if the progress bar was cancelled.  If it's 1,
8581 process_loop should return 1 to indicate a cancellation.  In addition
8582 to progress bar cancellation, @b{process_loop} should return 1 when the
8583 entire timeline range is processed.
8584
8585 @item
8586 int stop_loop();
8587
8588 This is called after process_loop processes its last buffer.  
8589
8590 If PluginClient::is_interactive is 1, this should call
8591 @b{stop_progress} in the progress bar pointer and delete the pointer. 
8592 Then it should delete any objects it created for processing in
8593 @b{start_loop}.
8594
8595
8596 @end itemize
8597
8598
8599
8600 @node AUDIO PLUGINS
8601 @section AUDIO PLUGINS
8602
8603 The simplest audio plugin is Gain.  The processing object should
8604 include @b{pluginaclient.h} and inherit from @b{PluginAClient}.  Realtime audio plugins need to
8605 define 
8606
8607 @example
8608 int process_buffer(int64_t size, 
8609                 double **buffer,
8610                 int64_t start_position,
8611                 int sample_rate);
8612 @end example
8613
8614 if it's multichannel or 
8615
8616 @example
8617 int process_buffer(int64_t size, 
8618                 double *buffer,
8619                 int64_t start_position,
8620                 int sample_rate);
8621 @end example
8622
8623 if it's single channel.  These should return 0 on success and 1 on
8624 failure.  In the future, the return value may abort failed rendering.
8625
8626 The processing function needs to request input samples with 
8627
8628 @example
8629 int read_samples(double *buffer,
8630                 int channel,
8631                 int sample_rate,
8632                 int64_t start_position,
8633                 int64_t len);
8634 @end example
8635
8636 It always returns 0.  The user may specify any desired sample rate and
8637 start position.
8638
8639 Nonrealtime audio plugins need to define
8640
8641 @example
8642 int process_loop(double *buffer, int64_t &write_length);
8643 @end example
8644
8645 for single channel or
8646
8647 @example
8648 int process_loop(double **buffers, int64_t &write_length);
8649 @end example
8650
8651 for multi channel.  Non realtime plugins use a different set of
8652 read_samples functions to request input data.  These are fixed to the
8653 project sample rate.
8654
8655
8656
8657 @node VIDEO PLUGINS
8658 @section VIDEO PLUGINS
8659
8660
8661
8662
8663 The simplest video plugin is Flip.  The processing object should
8664 include @b{pluginvclient.h} and inherit from @b{PluginVClient}. 
8665 Realtime video plugins need to define 
8666
8667 @example
8668 int process_buffer(VFrame **frame,
8669         int64_t start_position,
8670         double frame_rate);
8671 @end example
8672
8673 if it's multichannel or 
8674
8675 @example
8676 int process_buffer(VFrame *frame,
8677         int64_t start_position,
8678         double frame_rate);
8679 @end example
8680
8681 if it's single channel.  
8682
8683 The nonrealtime video plugins need to define
8684
8685 @example
8686 int process_loop(VFrame *buffer);
8687 @end example
8688
8689 for single channel or
8690
8691 @example
8692 int process_loop(VFrame **buffers);
8693 @end example
8694
8695 for multi channel.  The amount of frames generated in a single
8696 process_loop is always assumed to be 1, hence the lack of a
8697 write_length argument.  Returning 0 causes the rendering to continue. 
8698 Returning 1 causes the rendering to abort.
8699
8700 A set of read_frame functions exist for requesting input frames in
8701 non-realtime video plugins.  These are fixed to the project frame rate.
8702
8703
8704 @node TRANSITION PLUGINS
8705 @section TRANSITION PLUGINS
8706
8707
8708
8709
8710 The simplest video transition is @b{wipe} and the simplest audio
8711 transition is @b{crossfade}.  These use a subset of the default class
8712 members of realtime plugins, but so far no analogue to
8713 PLUGIN_CLASS_MEMBERS has been done for transitions.
8714
8715 The processing object for audio transitions still inherits from
8716 PluginAClient and for video transitions it still inherits from
8717 PluginVClient.
8718
8719 Transitions may or may not have a GUI.  If they have a GUI, they must
8720 also manage a thread like realtime plugins.  Do this with the same
8721 PLUGIN_THREAD_OBJECT and PLUGIN_THREAD_HEADER macros as realtime
8722 plugins.  Since there is only one keyframe in a transition, you don't
8723 need to worry about updating the GUI from the processing object like
8724 you do in a realtime plugin.
8725
8726 If the transition has a GUI, you can use PLUGIN_CONSTRUCTOR_MACRO and 
8727 PLUGIN_DESTRUCTOR_MACRO to initialize the processing object.  You'll
8728 also need a BC_Hash object and a Thread object for these macros.
8729
8730 Since the GUI is optional, overwrite a function called @b{uses_gui()}
8731 to signifiy whether or not the transition has a GUI.  Return 1 if it
8732 does and 0 if it doesn't.
8733
8734 Transitions need a @b{load_defaults} and @b{save_defaults} function so
8735 the first time they're dropped on the timeline they'll have useful
8736 settings.
8737
8738 A @b{read_data} and @b{save_data} function takes over after insertion
8739 to access data specific to each instance of the transition.
8740
8741 The most important difference between transitions and realtime plugins
8742 is the addition of an @b{is_transition} method to the processing
8743 object.  @b{is_transition} should return 1 to signify the plugin is a
8744 transition.
8745
8746 Transitions process data in a @b{process_realtime} function.
8747
8748 @example
8749 int process_realtime(VFrame *input, 
8750                 VFrame *output);
8751 @end example
8752
8753 @example
8754 int process_realtime(int64_t size, 
8755                 double *input_ptr, 
8756                 double *output_ptr);
8757 @end example
8758
8759 The input argument to process_realtime is the data for the next edit. 
8760 The output argument to process_realtime is the data for the previous
8761 edit.
8762
8763 Routines exist for determining where you are relative to the
8764 transition's start and end.
8765
8766 @itemize
8767
8768 @item @b{PluginClient::get_source_position()} - returns the current
8769 position since the start of the transition of the lowest sample in the
8770 buffers.
8771
8772 @item @b{PluginClient::get_total_len()} - returns the integer length of
8773 the transition.  The units are either samples or frames, in the data
8774 rate requested by the first plugin.
8775
8776 @end itemize
8777
8778 Users should divide the source position by total length to get the
8779 fraction of the transition the current @b{process_realtime} function is
8780 at.
8781
8782 Transitions run in the data rate requested by the first plugin in the
8783 track.  This may be different than the project data rate.  Since
8784 process_realtime lacks a rate argument, use @b{get_framerate()} or
8785 @b{get_samplerate} to get the requested rate.
8786
8787
8788
8789
8790
8791 @node PLUGIN GUI'S WHICH UPDATE DURING PLAYBACK
8792 @section PLUGIN GUI'S WHICH UPDATE DURING PLAYBACK
8793
8794 Effects like @b{Histogram} and @b{VideoScope} need to update the GUI
8795 during playback to display information about the signal.  This is
8796 achieved with the @b{send_render_gui} and @b{render_gui} methods. 
8797 Normally in process_buffer, when the processing object wants to update
8798 the GUI it should call @b{send_render_gui}.  This should only be called
8799 in process_buffer.  Send_render_gui goes through a search and
8800 eventually calls @b{render_gui} in the GUI instance of the plugin.
8801
8802 Render_gui should have a sequence like
8803
8804 @example
8805 void MyPlugin::render_gui(void *data)
8806 @{
8807         if(thread)
8808         @{
8809                 thread->window->lock_window();
8810
8811 // update GUI here
8812
8813                 thread->window->unlock_window();
8814         @}
8815 @}
8816
8817 @end example
8818
8819
8820 Send_render_gui and render_gui use one argument, a void pointer to
8821 transfer information from the processing object to the GUI.  The user
8822 should typecast this pointer into something useful.
8823
8824
8825
8826
8827
8828
8829
8830
8831
8832
8833
8834 @node PLUGIN QUERIES
8835 @section PLUGIN QUERIES
8836
8837
8838 There are several useful queries in PluginClient which can be accessed
8839 from the processing object.  Some of them have different meaning in
8840 realtime and non-realtime mode.  They all give information about the
8841 operating system or the project which can be used to improve the
8842 quality of the processing.
8843
8844 @menu
8845 * SYSTEM QUERIES:: Utilities for determining the system resources.
8846 * TIMING QUERIES:: Utilities for performing time-dependant processing.
8847 @end menu
8848
8849
8850
8851
8852
8853 @node SYSTEM QUERIES
8854 @subsection SYSTEM QUERIES
8855
8856
8857 @itemize
8858
8859 @item 
8860
8861 @b{get_interpolation_type()} returns the type of interpolation the user
8862 wants for all scaling operations.  This is a macro from
8863 overlayframe.inc.  It can be applied to any call to the
8864 @b{OverlayFrame} object.
8865
8866 @item
8867
8868 @b{get_project_smp()} Gives the number of CPU's on the system minus 1. 
8869 If it's a uniprocessor it's 0.  If it's a dual processor, it's 1.  This
8870 number should be used to gain parallelism.
8871
8872 @item
8873
8874 @b{get_total_buffers()} Gives the number of tracks a multichannel
8875 plugin needs to process.
8876
8877
8878 @end itemize
8879
8880
8881
8882
8883
8884
8885 @node TIMING QUERIES
8886 @subsection TIMING QUERIES
8887
8888
8889 There are two rates for media a realtime plugin has to be aware of: the
8890 project rate and the requested rate.  Functions are provided for
8891 getting the project and requested rate.  In addition, doing time
8892 dependant effects requires using several functions which tell where you
8893 are in the effect.
8894
8895 @itemize
8896 @item
8897
8898 @b{get_project_framerate()} Gives the frames per second of the video as
8899 defined by the project settings.
8900
8901
8902 @item
8903
8904 @b{get_project_samplerate()} Gives the samples per second of the audio as
8905 defined by the project settings.
8906
8907 @item
8908
8909 @b{get_framerate()} Gives the frames per second requested by the plugin
8910 after this one.  This is the requested frame rate and is the same as
8911 the frame_rate argument to process_buffer.
8912
8913 @item
8914
8915 @b{get_samplerate()} Gives the samples per second requested by the plugin
8916 after this one.  This is the requested sample rate and is the same as
8917 the sample_rate argument to process_buffer.
8918
8919 @item
8920
8921 @b{get_total_len()} Gives the number of samples or frames in the
8922 range covered by the effect, relative to the requested data rate.
8923
8924 @item
8925
8926 @b{get_source_start()} For realtime plugins it gives the lowest sample
8927 or frame in the effect range in the requested data rate.  For
8928 nonrealtime plugins it's the start of the range of the timeline to
8929 process.
8930
8931 @item
8932
8933 @b{get_source_position()} For realtime plugins it's the lowest numbered
8934 sample in the requested region to process if playing forward and the
8935 highest numbered sample in the region if playing backward.  For video
8936 it's the start of the frame if playing forward and the end of the frame
8937 if playing in reverse.  The position is relative to the start of the
8938 EDL and in the requested data rate.
8939
8940 For transitions this is always the lowest numbered sample of the region
8941 to process relative to the start of the transition.
8942
8943 @item
8944
8945 @b{get_direction()} Gives the direction of the current playback
8946 operation.  This is a macro defined in transportque.inc.  This is
8947 useful for calling read functions since the read functions position
8948 themselves at the start or end of the region to read, depending on the
8949 playback operation.
8950
8951 @item
8952
8953 @b{local_to_edl()}
8954
8955 @item
8956
8957 @b{edl_to_local()}
8958
8959 These convert between the requested data rate and the project data
8960 rate.  They are used to convert keyframe positions into numbers which
8961 can be interpolated at the requested data rate.  The conversion is
8962 automatically based on frame rate or sample rate depending on the type
8963 of plugin.
8964
8965 @item
8966 @b{get_prev_keyframe(int64_t position, int is_local)}
8967
8968 @item
8969 @b{get_next_keyframe(int64_t position, int is_local)}  
8970
8971 These give the nearest keyframe before or after the position given. 
8972 The macro defined version of load_configuration automatically retrieves
8973 the right keyframes but you may want to do this on your own.
8974
8975 The position argument can be either in the project rate or the
8976 requested rate.  Set is_local to 1 if it's in the requested rate and 0
8977 if it's in the project rate.
8978
8979 In each keyframe, another position value tells the keyframe's position
8980 relative to the start of the timeline and in the project rate.
8981
8982 The only way to get smooth interpolation between keyframes is to
8983 convert the positions in the keyframe objects to the requested rate. 
8984 Do this by using edl_to_local on the keyframe positions.
8985
8986 @end itemize
8987
8988
8989
8990
8991
8992 @node USING OPENGL
8993 @section USING OPENGL
8994
8995
8996
8997 Realtime video plugins support OpenGL.  Using OpenGL to do plugin
8998 routines can speed up playback greatly since it does most of the work
8999 in hardware.  Unfortunately, every OpenGL routine needs a software
9000 counterpart for rendering, doubling the amount of software to
9001 maintain.  Fortunately, having an OpenGL routine means the software
9002 version doesn't need to be as optimized as it did when software was the
9003 only way.
9004
9005 As always, the best way to design a first OpenGL plugin is to copy an
9006 existing one and alter it.  The @b{Brightness} plugin is a simple
9007 OpenGL plugin to copy.  There are 3 main points in OpenGL rendering and
9008 1 point for optimizing OpenGL rendering.
9009
9010 @menu
9011 * GETTING OPENGL DATA:: Getting video data in a form usable by OpenGL
9012 * DRAWING USING OPENGL:: The method of drawing video in OpenGL
9013 * USING SHADERS:: Routines to simplify shader usage
9014 * AGGREGATING PLUGINS:: Combining OpenGL routines from different plugins into one.
9015 @end menu
9016
9017
9018
9019 @node GETTING OPENGL DATA
9020 @subsection GETTING OPENGL DATA
9021
9022 The first problem is getting OpenGL-enabled plugins to interact with
9023 software-only plugins.  To solve this, all the information required to
9024 do OpenGL playback is stored in the VFrame object which is passed to
9025 @b{process_buffer}.  To support 3D, the VFrame contains a PBuffer and a
9026 texture, in addition to VFrame's original rows.
9027
9028 In OpenGL mode, VFrame has 3 states corresponding to the location of
9029 its video data.  The opengl state is recovered by calling
9030 @b{get_opengl_state} and is set by calling @b{set_opengl_state}.  The
9031 states are:
9032
9033 @itemize
9034
9035 @item
9036
9037 @b{VFrame::RAM} - This means the video data is stored in the
9038 traditional row pointers.  It must be loaded into a texture before
9039 being drawn using OpenGL routines.
9040
9041 @item @b{VFrame::TEXTURE} - The video data is stored in texture
9042 memory.  It's ready to be drawn using OpenGL routines.
9043
9044 @item @b{VFrame::SCREEN} - The video data is stored in a frame buffer
9045 in the graphics card.  For plugins, the frame buffer is always a
9046 PBuffer.  The image on the frame buffer can't be replicated again
9047 unless it is read back into the texture and the opengl state is reset
9048 to TEXTURE.  The frame buffer is limited to 8 bits per channel.  If an
9049 OpenGL effect is used in a floating point project, it only retains 8
9050 bits.
9051
9052 @end itemize
9053
9054 In the plugin's @b{process_buffer} routine, there is normally a call to
9055 @b{read_frame} to get data from the previous plugin in the chain. 
9056 @b{read_frame} takes a new parameter called @b{use_opengl}.  
9057
9058 The plugin passes 1 to @b{use_opengl} if it intends to handle the data
9059 using OpenGL.  It passes 0 to @b{use_opengl} if it can only handle the
9060 data using software.  The value of @b{use_opengl} is passed up the
9061 chain to ensure a plugin which only does software only gets the data in
9062 the row pointers.  If @b{use_opengl} is 0, the opengl state in VFrame
9063 is RAM.
9064
9065 The plugin must not only know if it is software-only but if its output
9066 must be software only.  Call @b{get_use_opengl} to determine if the
9067 output can be handled by OpenGL.  If @b{get_use_opengl} returns 0, the
9068 plugin must pass 0 for @b{use_opengl} in @b{read_frame} and do its
9069 processing in software.  If @b{get_use_opengl} is 1, the plugin can
9070 decide based on its implementation whether to use OpenGL.
9071
9072
9073 The main problem with OpenGL is that all the gl... calls need to be run
9074 from the same thread.  To work around this, the plugin interface has
9075 routines for running OpenGL in a common thread.  
9076
9077
9078 @b{run_opengl} transfers control to the common OpenGL thread.  This is
9079 normally called by the plugin in @b{process_buffer} after it calls
9080 @b{read_frame} and only if @b{get_use_opengl} is 1.
9081
9082 Through a series of indirections, @b{run_opengl} eventually transfers
9083 control to a virtual function called @b{handle_opengl}. 
9084 @b{handle_opengl} must be overridden with a function to perform all the
9085 OpenGL routines.  The contents of @b{handle_opengl} must be enclosed in
9086 @b{#ifdef HAVE_GL} ... @b{#endif} to allow it to be compiled on systems
9087 with no graphics support, like render nodes.  The return value of
9088 @b{handle_opengl} is passed back from @b{run_opengl}.
9089
9090 @b{read_frame} can't be called from inside @b{handle_opengl}.  This
9091 would create a recursive lockup because it would cause other objects to
9092 call @b{run_opengl}.
9093
9094 Once inside @b{handle_opengl}, the plugin has full usage of all the
9095 OpenGL features.  VFrame provides some functions to automate common
9096 OpenGL sequences.
9097
9098 The VFrame argument to @b{process_buffer} is always available through
9099 the @b{get_output(int layer)} function.  If the plugin is multichannel,
9100 the layer argument retrieves a specific layer of the output buffers. 
9101 The PBuffer of the output buffer is where the OpenGL output must go if
9102 any processing is done.
9103
9104
9105
9106 @node DRAWING USING OPENGL
9107 @subsection DRAWING USING OPENGL
9108
9109
9110 The sequence of commands to draw on the output PBuffer stars with
9111 getting the video in a memory area where it can be recalled for
9112 drawing:
9113
9114 @example
9115 get_output()->to_texture();
9116 get_output()->enable_opengl();
9117 @end example
9118
9119 @b{to_texture} transfers the OpenGL data from wherever it is to the
9120 output's texture memory and sets the output state to TEXTURE.
9121
9122 @b{enable_opengl} makes the OpenGL context relative to the output's
9123 PBuffer.
9124
9125 The next step is to draw the texture with some processing on the
9126 PBuffer.  The normal sequence of commands to draw a texture is:
9127
9128 @example
9129 get_output()->init_screen();
9130 get_output()->bind_texture(0);
9131 get_output()->draw_texture();
9132 @end example
9133
9134 @b{VFrame::init_screen} sets the OpenGL frustum and parameters to known
9135 values.
9136
9137 @b{VFrame::bind_texture(int texture_unit)} binds the texture to the given
9138 texture unit and enables it.
9139
9140 @b{VFrame::draw_texture()} calls the vertex functions to draw the
9141 texture normalized to the size of the PBuffer.  Copy this if you want
9142 custom vertices.
9143
9144 The last step in the handle_opengl routine, after the texture has been
9145 drawn on the PBuffer, is to set the output's opengl state to SCREEN
9146 with a call to @b{VFrame::set_opengl_state}.  The plugin should not
9147 read back the frame buffer into a texture or row pointers if it has no
9148 further processing.  Plugins should only leave the output in the
9149 texture or RAM if its location results from normal processing.  They
9150 should set the opengl state to RAM or TEXTURE if they do.
9151
9152 @b{Colormodels in OpenGL}
9153
9154 The colormodel exposed to OpenGL routines is always floating point since
9155 that is what OpenGL uses, but it may be YUV or RGB depending on the
9156 project settings.  If it's YUV, the U & V are offset by 0.5 just like in
9157 software.  Passing YUV colormodels to plugins was necessary for speed. 
9158 The other option was to convert YUV to RGB in the first step that needed
9159 OpenGL.  Every effect and rendering step would have needed a YUV to RGB
9160 routine.  With the YUV retained, only the final compositing step needs a
9161 YUV to RGB routine.
9162
9163 The OpenGL mode differentiates between alpha & flat colormodels even
9164 though OpenGL always has an alpha channel.  For RGB colormodels, you
9165 must multiply the alpha component by the RGB & set the alpha component
9166 to 1 whenever the colormodel has no alpha to ensure consistency with the
9167 software mode.
9168
9169 @example
9170 Rout = Rin * Ain
9171 Gout = Gin * Ain
9172 Bout = Bin * Ain
9173 Aout = 1
9174 @end example
9175
9176
9177 For YUV colormodels, you must multiply the alpha using the following
9178 formula.
9179
9180 @example
9181 Yout = Yin * Ain
9182 Uout = Uin * Ain + 0.5 * (1 - Ain)
9183 Vout = Vin * Ain + 0.5 * (1 - Ain)
9184 Aout = 1
9185 @end example
9186
9187
9188
9189
9190
9191
9192 @node USING SHADERS
9193 @subsection USING SHADERS
9194
9195 Very few effects can do anything useful with just a straight drawing of
9196 the texture on the PBuffer.  It's also not easy to figure out exactly
9197 what math is being used by the different OpenGL blending macros. 
9198 Normally you'll use shaders.  The shader is a C program which runs on
9199 the graphics card.  Since the graphics card is optimized for graphics,
9200 it can be much faster than running it on the CPU.
9201
9202 Shaders are written in OpenGL Shading Language.  The shader source code
9203 is contained in a string.  The normal sequence for using a shader comes
9204 after a call to @b{enable_opengl}.
9205
9206 @example
9207 char *shader_source = "...";
9208 unsigned char shader_id = VFrame::make_shader(0, shader_source, 0);
9209 glUseProgram(shader_id);
9210 // Set uniform variables using glUniform commands
9211 @end example
9212
9213 The compilation and linking step for shaders is encapsulated by the
9214 VFrame::make_shader command.  It returns a shader_id which can be
9215 passed to OpenGL functions.  The first and last arguments must always
9216 by 0.  And arbitrary number of source strings may be put between the
9217 0's.  The source strings are concatenated by make_shader into one huge
9218 shader source.  If multiple main functions are in the sources, the main
9219 functions are renamed and run in order.
9220
9221 There are a number of useful macros for shaders in playback3d.h.  All
9222 the shaders so far have been fragment shaders.  After the shader is
9223 initialized, draw the texture starting from @b{init_screen}.  The
9224 shader program must be disabled with another call to
9225 @b{glUseProgram(0)} and 0 as the argument.
9226
9227 The shader_id and source code is stored in memory as long as Cinelerra
9228 runs.  Future calls to make_shader with the same source code run much
9229 faster.
9230
9231
9232
9233
9234 @node AGGREGATING PLUGINS
9235 @subsection AGGREGATING PLUGINS
9236
9237 Further speed improvements may be obtained by combining OpenGL routines
9238 from two plugins into a single handle_opengl function.  This is done
9239 when @b{Frame to Fields} and @b{RGB to 601} are attached in order. 
9240 Aggregations of more than two plugins are possible but very hard to get
9241 working.  Aggregation is useful for OpenGL because each plugin must
9242 copy the video from a texture to a PBuffer.  In software there was no
9243 copy operation.
9244
9245 In aggregation, one plugin processes everything from the other plugins
9246 and the other plugins fall through.  The fall through plugins must copy
9247 their parameters to the output buffer so they can be detected by the
9248 processing plugin.
9249
9250 The VFrame used as the output buffer contains a parameter table for
9251 parameter passing between plugins and it's accessed with
9252 @b{get_output()->get_params()}.  Parameters are set and retrieved in
9253 the table with calls to @b{update} and @b{get} just like with defaults.
9254
9255 The fall through plugins must determine if the processor plugin is
9256 attached with calls to @b{next_effect_is} and @b{prev_effect_is}. 
9257 These take the name of the processor plugin as a string argument and
9258 return 1 if the next or previous plugin is the processor plugin.  If
9259 either returns 1, the fall through plugin must still call @b{read_frame} to
9260 propogate the data but return after that.
9261
9262 The processor plugin must call @b{next_effect_is} and
9263 @b{prev_effect_is} to determine if it's aggregated with a fall through
9264 plugin.  If it is, it must perform the operations of the fall through
9265 plugin in its OpenGL routine.  The parameters for the the fall through
9266 plugin should be available by @b{get_output()->get_params()} if the
9267 fall through plugin set them.
9268
9269
9270
9271
9272
9273
9274
9275
9276 @node KEYBOARD SHORTCUTS
9277 @chapter KEYBOARD SHORTCUTS
9278
9279 Alex Ferrer started summarizing most of the keyboard shortcuts.  Most
9280 of the keys work without any modifier like shift or ctrl.  Most windows
9281 can be closed with a @b{Ctrl-w}.  Most operations can be cancelled with
9282 @b{ESC} and accepted with @b{Enter}.
9283
9284 @section PROGRAM WINDOW
9285
9286
9287 @subsection Editing Media
9288
9289 @example
9290 z         Undo
9291 Shift Z   Re-Do
9292 x         Cut
9293 c         Copy
9294 v         Paste
9295 Del       Clear
9296 Shift Spc Paste Silence
9297 m         Mute region
9298 a         Select all
9299 shift + click   When done over an edit causes the highlighted selection to extend to the cursor position.
9300                 When done over the boundary of an effect causes the trim operation to apply to one effect.
9301 @end example
9302
9303 @subsection Editing Labels & In/Out Points
9304
9305 @example
9306 [             Toggle In point 
9307 ]             Toggle Out point 
9308 l             Toggle label at current position
9309 Ctrl <-       Go to Previous Label
9310 Ctrl ->       Go to Next Label
9311 @end example
9312
9313
9314 @subsection Navigation
9315
9316 @example
9317 Right arrow      Move right*
9318 Left arrow       Move left*
9319 Up arrow         Zoom out*
9320 Down arrow       Zoom in*
9321 Ctrl Up          Expand waveform amplitude
9322 Ctrl Dn          Shrink waveform amplitude
9323 Alt Up           Expand curve amplitude
9324 Alt Dn           Shrink curve amplitude
9325 f                Fit time displayed to selection
9326 Alt f            Fit curve amplitude to highlighted section of curves
9327 Alt Left         Move left one edit
9328 Alt Right        Move right one edit
9329 Page Up          Move up*
9330 Page Dn          Move down*
9331 Ctrl Page Up     Expand track height
9332 Ctrl Page Dn     Shrink track height
9333 Home             Go to beginning of timeline*
9334 End              Go to end of timeline*
9335
9336 @end example
9337
9338 * You may have to click on the timeline to deactivate any text boxes or
9339 tumblers before these work.
9340
9341
9342
9343
9344 @subsection File operations
9345
9346 @example
9347 n         New project
9348 o         Load Files
9349 s         Save Project
9350 r         Record
9351 Shift R   Render
9352 q         Quit
9353 Shift P   Preferences
9354 Shift B   Batch Render
9355 Shift F   Set Format
9356 @end example
9357
9358 @subsection Key Frame Editing
9359
9360 @example
9361
9362 Shift X    Cut keyframes
9363 Shift C    Copy keyframes
9364 Shift V    Paste keyframes
9365 Shift Del  Clear keyframes
9366 Alt c      Copy default keyframe
9367 Alt v      Paste default keyframe
9368
9369 @end example
9370
9371
9372 @subsection Track Manipulation
9373
9374 @example
9375
9376 t          Add Audio Track
9377 u          Insert default Audio Transition
9378 Shift T    Add Video Track
9379 Shift U    Insert Default Video Transition
9380 d          Delete last Track
9381 Shift L    Loop playback
9382 Tab        Toggle single track arming status
9383 Shift-Tab  Toggle every other track's arming status
9384
9385 @end example
9386
9387 @subsection What's drawn on the timeline
9388
9389 @example
9390
9391 1         Show titles
9392 2         Show transitions
9393 3         Fade keyframes
9394 4         Mute keyframes
9395 5         Mode keyframes
9396 6         Pan keyframes
9397 7         Camera keyframes
9398 8         Projector keyframes
9399 9         Plugin keyframes
9400 0         Mask keyframes
9401 -         Camera Zoom
9402 =         Projector Zoom
9403
9404 @end example
9405
9406
9407 @section VIEWER & COMPOSITOR WINDOWS
9408
9409 @example
9410
9411 x         Cut
9412 c         Copy
9413 v         Paste
9414 v         Splice
9415 b         Overwrite
9416 [         Toggle In point 
9417 ]         Toggle Out point 
9418 l         Toggle label at current position
9419 Ctrl <-   Go to Previous Label
9420 Ctrl ->   Go to Next Label
9421 Home      Go to beginning
9422 End       Go to end
9423 z         Undo
9424 Shift Z   Re-Do
9425 +         Zoom in
9426 -         Zoom out
9427
9428 @end example
9429
9430
9431
9432 @section PLAYBACK TRANSPORT
9433
9434 Transport controls work in any window which has a playback transport.  They are
9435 accessed through the number pad with num lock disabled.
9436
9437 @example
9438 4 Frame back         5 Reverse Slow     6 Reverse      + Reverse Fast
9439 1 Frame Forward      2 Forward Slow     3 Play     Enter Fast Forward
9440 0 Stop
9441
9442 @end example
9443
9444 [ Space bar ] is normal Play, Hitting any key twice is Pause.
9445
9446
9447 Hitting any transport control with CTRL down causes only the region
9448 between the in/out points to be played, if in/out points are defined.
9449
9450 @section RECORD WINDOW
9451
9452 @example
9453
9454 Space              Start and pause recording of the current batch
9455 l                  Toggle label at current position.
9456
9457 @end example
9458
9459 @bye
9460