manual/xml/working_with_regions.xml

   1 <?xml version="1.0" standalone="no"?>
   2
   3 <!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
   4
   5 ]>
   6
   7 <section id="sn-working-with-regions">
   8   <title>Working with Regions</title>
   9   <para>
  10     Regions are the basic elements of editing and composing in Ardour. Each
  11     region represents a single, contiguous section of one or more audio
  12     files. Regions are defined by a fixed set of attributes:
  13   </para>
  14
  15   <itemizedlist>
  16     <listitem>
  17       <para>
  18         the source audio file(s) they represent
  19       </para>
  20     </listitem>
  21
  22     <listitem>
  23       <para>
  24         a starting point in the audio file(s)
  25       </para>
  26     </listitem>
  27
  28     <listitem>
  29       <para>
  30         a length
  31       </para>
  32     </listitem>
  33   </itemizedlist>
  34
  35   <para>
  36     When placed into a
  37     <glossterm linkend="gt-playlist">playlist</glossterm>, they gain
  38     additional attributes:
  39   </para>
  40
  41   <itemizedlist>
  42     <listitem>
  43       <para>
  44         a position along the timeline
  45       </para>
  46     </listitem>
  47
  48     <listitem>
  49       <para>
  50         a layer
  51       </para>
  52     </listitem>
  53   </itemizedlist>
  54
  55   <para>
  56     There are <emphasis>other attributes</emphasis> as well, but they do not
  57     define the region. Things you should know about regions:
  58   </para>
  59
  60   <variablelist>
  61     <title></title>
  62     <varlistentry>
  63       <term>Regions are Cheap</term>
  64       <listitem>
  65         <para>
  66           By themselves, regions do not consume hardly any of your
  67           computer's resources. Each region requires a small amount of
  68           memory, and represents a rather small amount of CPU work if placed
  69           into an active track. So, don't worry about creating regions
  70           whenever you need to.
  71         </para>
  72       </listitem>
  73     </varlistentry>
  74
  75     <varlistentry>
  76       <term>Regions are not audio files</term>
  77       <listitem>
  78         <para>
  79           Although a region can represent an entire audio file, they are
  80           never equivalent to an audio file. Most regions represent just
  81           parts of an audio file(s) on disk, and removing a region from a
  82           track has nothing to do with removing the audio file(s) from the
  83           disk ((the <emphasis>Destroy</emphasis> operation, one of Ardour's
  84           few destructive operations, can affect this)). Changing the length
  85           of a region has no effect on the audio file(s) on disk. Splitting
  86           and copying regions does not alter the audio file in anyway, nor
  87           does it create new audio files ((the <emphasis>Export</emphasis> ,
  88           <emphasis>Bounce</emphasis> and <emphasis>Reverse</emphasis>
  89           operations do create new audio files)).
  90         </para>
  91       </listitem>
  92     </varlistentry>
  93   </variablelist>
  94
  95   <section id="region-naming">
  96     <title>Region Naming</title>
  97     <para>
  98       Regions are initially named using either:
  99     </para>
 100
 101     <itemizedlist>
 102       <listitem>
 103         <para>
 104           the name of the playlist for which they were recorded
 105         </para>
 106       </listitem>
 107
 108       <listitem>
 109         <para>
 110           the name of the embedded/imported audio file they represent
 111         </para>
 112       </listitem>
 113     </itemizedlist>
 114
 115     <section id="whole-file-region-names">
 116       <title>Whole File Region Names</title>
 117       <para>
 118         These are not audio files, but regions that represent the full
 119         extent of an audio file. Every time a new recording is done, or a
 120         new file is embedded/imported, a new region is created that
 121         represents the entire audio file(s) This region will have the name
 122         of the playlist/original file, followed by a "-" and then a number.
 123       </para>
 124
 125       <para>
 126         For recorded regions, the number will increase each time a new
 127         recording is made. So, for example, if there is a playlist called
 128         "Didgeridoo", the first recorded whole file region for that playlist
 129         will be called "Digderidoo-1". The next one will be "Digeridoo-2"
 130         and so on.
 131       </para>
 132
 133       <para>
 134         For imported/embedded files, the region name will be based on the
 135         file name, but with any final suffix (e.g. ".wav" or ".aiff")
 136         removed.
 137       </para>
 138
 139       <para>
 140         Normally, whole file regions are not inserted into tracks/playlists,
 141         but regions derived from them are. The whole-file versions live in
 142         the editor region list where they act as an organizing mechanism for
 143         regions that are derived from them.
 144       </para>
 145     </section>
 146
 147     <section id="normal-region-names">
 148       <title>Normal Region Names</title>
 149       <para>
 150         When a region is inserted into a track/playlist, its initial name
 151         will end in a version number, such as ".1" or ".103". For a recorded
 152         region, if the whole file region was "Hang drum-1", then the region
 153         in the track will appear with the name "Hang drum-1.1". For an
 154         imported/embedded region, if the whole file region was
 155         "Bach:Invention3", then the region in the track will appear with the
 156         name "Bach:Invention3.1".
 157       </para>
 158     </section>
 159
 160     <section id="copied-region-names">
 161       <title>Copied Region Names</title>
 162       <para>
 163         If the region is a copy of another region, it will begin life with
 164         the same name as the original. When an operation is carried out that
 165         modifies one of the copies, that particular copy will be renamed by
 166         incrementing the version number.
 167       </para>
 168     </section>
 169
 170     <section id="renaming-regions">
 171       <title>Renaming Regions</title>
 172       <para>
 173         You can rename a region at any time. Use the <emphasis>region
 174         context menu</emphasis> to popup the rename dialog. The new name
 175         does not need to have a version number in it (in fact, it probably
 176         should not). The region will retain its name until it is modified
 177         after being copied.
 178       </para>
 179     </section>
 180   </section>
 181
 182   <section id="selecting-regions">
 183     <title>Selecting Regions</title>
 184     <para>
 185       In general, operations on regions apply to whichever regions are
 186       currently <emphasis>selected</emphasis> .
 187     </para>
 188
 189     <para>
 190       To select a single region, click on it using
 191       <mousebutton>Button1</mousebutton>.
 192     </para>
 193
 194     <para>
 195       To add an unselected region to the currently selected regions, click
 196       on it using
 197       <keycombo><keycap>Shift</keycap><mousebutton>Button1</mousebutton></keycombo>.
 198     </para>
 199
 200     <para>
 201       To remove a selected region from the currently selected regions, click
 202       on it using
 203       <keycombo><keycap>Shift</keycap><mousebutton>Button1</mousebutton></keycombo>.
 204     </para>
 205   </section>
 206
 207   <section id="removing-regions">
 208     <title>Removing Regions</title>
 209     <para>
 210       Select the region(s) to be removed. Then press the "Delete" key or use
 211       the standard key binding for "Cut" (
 212       <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo> by
 213       default).
 214     </para>
 215
 216     <para>
 217       Note that "removing" a region is a non-destructive operation. It has
 218       no effect on the audio file(s) stored on disk. If you really want to
 219       destructively remove the region, use the context menu for the region
 220       which has a "Destroy" item. This is not guaranteed to remove the audio
 221       file from your disk storage, but it generally will.
 222     </para>
 223   </section>
 224
 225   <section id="moving-regions">
 226     <title>Moving Regions</title>
 227     <para>
 228       To move a region, make sure you are in <emphasis>object</emphasis>
 229       mouse mode. Move the mouse pointer into the waveform display part of
 230       the region, press <mousebutton>Button1</mousebutton> and drag. The
 231       region will follow the mouse pointer as you move it around. By
 232       default, the region can move freely along the timeline - see
 233       <xref linkend="sn-snap-settings"/> for information on how to force the
 234       region to align to certain kinds of points along the timeline.
 235     </para>
 236
 237     <para>
 238       To move a region from one track to another, simply start a move as
 239       described above, but move the mouse pointer into the desired track.
 240       The region will follow the mouse pointer. Note that if you have other
 241       kinds of "tracks" visible, the region will remain where it is as the
 242       mouse pointer moves across them, and will then jump to the new track.
 243       This serves as a visual reminder that you cannot drag an audio region
 244       into an automation track or a bus, for example.
 245     </para>
 246
 247     <section id="moving-more-than-one-region">
 248       <title>Moving more than one region</title>
 249       <para>
 250         To move multiple regions, select them before moving. Then click+drag
 251         on one of the selected regions. All the regions will move, keeping
 252         their positions relative to each other.
 253       </para>
 254     </section>
 255
 256     <section id="region-fixed-time-motion">
 257       <title>Fixed-time motion</title>
 258       <para>
 259         Sometimes, you want to move a region to another track, but keeping
 260         its position along the timeline exactly the same. To do this, use
 261         <mousebutton>Button2</mousebutton> rather than
 262         <mousebutton>Button1</mousebutton>.
 263       </para>
 264     </section>
 265   </section>
 266
 267   <section id="copying-regions">
 268     <title>Copying Regions</title>
 269     <para>
 270       To copy a region, make sure you are in <emphasis>object</emphasis>
 271       mouse mode. Move the mouse pointer into the waveform press the
 272       <keycap>Ctrl</keycap> key, keep it down while pressing
 273       <mousebutton>Button1</mousebutton> and drag. A new region is created
 274       and will follow the mouse pointer as it moves. See
 275       <xref linkend="moving-regions"/> for more details on moving the copied
 276       region around.
 277     </para>
 278
 279     <section id="copying-more-than-one-region">
 280       <title>Copying more than one region</title>
 281       <para>
 282         To copy multiple regions, select them before copying. Then
 283         click+drag on one of the selected regions. All the regions will be
 284         copied and as they move, the will keep their positions relative to
 285         each other.
 286       </para>
 287     </section>
 288
 289     <section id="region-fixed-time-copying">
 290       <title>Fixed-time copying</title>
 291       <para>
 292         If you want to copy region(s) to other track(s) but keep the copies
 293         at the exact position on the timeline as the originals, simply use
 294         <keycombo><keycap>Ctrl</keycap><mousebutton>Button2</mousebutton></keycombo>
 295         instead of
 296         <keycombo><keycap>Ctrl</keycap><mousebutton>Button1</mousebutton></keycombo>.
 297       </para>
 298     </section>
 299   </section>
 300
 301   <section id="trimming-regions">
 302     <title>Trimming Regions</title>
 303     <para></para>
 304   </section>
 305
 306   <section id="auditioning-regions">
 307     <title>Auditioning Regions</title>
 308     <para></para>
 309   </section>
 310
 311   <section id="region-gain-envelopes">
 312     <title>Region Gain Envelopes</title>
 313     <para></para>
 314   </section>
 315
 316   <section id="region-context-menu">
 317 <!-- needs work -->
 318     <title>Region Context Menu</title>
 319     <para>
 320       If you context-click on a region, a popup menu will appear. At or near
 321       the top of that menu is a list of all regions that exist in the
 322       clicked-upon track under the mouse pointer. Each region entry (shown
 323       by name) points to a submenu that contains region-specific operations:
 324     </para>
 325
 326     <variablelist>
 327       <title></title>
 328       <varlistentry>
 329         <term><guilabel>Popup region editor</guilabel></term>
 330         <listitem>
 331           <para>
 332             creates and displays the editor for this region, allowing even
 333             more specific control over the region than this menu
 334           </para>
 335         </listitem>
 336       </varlistentry>
 337
 338       <varlistentry>
 339         <term><guilabel>Raise to top layer</guilabel></term>
 340         <listitem>
 341           <para>
 342             moves the region to the top layer of this track (works only in
 343             "Most recently added/moved/trimmed regions are higher"
 344             <emphasis>layer mode</emphasis>
 345           </para>
 346         </listitem>
 347       </varlistentry>
 348
 349       <varlistentry>
 350         <term><guilabel>Lower to bottom layer</guilabel></term>
 351         <listitem>
 352           <para>
 353             moves the region to the bottom layer of this track (works only
 354             in "Most recently added/moved/trimmed regions are higher"
 355             <emphasis>layer mode</emphasis>
 356           </para>
 357         </listitem>
 358       </varlistentry>
 359
 360       <varlistentry>
 361         <term><guilabel>Define sync point</guilabel></term>
 362         <listitem>
 363           <para>
 364             if the edit cursor is within this region, defines the region
 365             sync point at the edit cursor location.
 366           </para>
 367         </listitem>
 368       </varlistentry>
 369
 370       <varlistentry>
 371         <term><guilabel>Remove sync point</guilabel></term>
 372         <listitem>
 373           <para></para>
 374         </listitem>
 375       </varlistentry>
 376
 377       <varlistentry>
 378         <term><guilabel>Audition</guilabel></term>
 379         <listitem>
 380           <para>
 381             plays this region via the
 382             <glossterm linkend="gt-auditioner">auditioner</glossterm>
 383           </para>
 384         </listitem>
 385       </varlistentry>
 386
 387       <varlistentry>
 388         <term><guilabel>Export</guilabel></term>
 389         <listitem>
 390           <para>
 391             exports this region to a new audio file, via the export dialog
 392             (thus allowing resampling, dithering, format specification etc.)
 393           </para>
 394         </listitem>
 395       </varlistentry>
 396
 397       <varlistentry>
 398         <term><guilabel>Bounce</guilabel></term>
 399         <listitem>
 400           <para>
 401             re-records this region (with any plugins/inserts applied) to a
 402             new audio file, and replaces the region with one referring to
 403             the new file.
 404           </para>
 405         </listitem>
 406       </varlistentry>
 407
 408       <varlistentry>
 409         <term><guilabel>Lock</guilabel></term>
 410         <listitem>
 411           <para>
 412             prevents the region from being moved, trimmed, or modified in
 413             almost any way.
 414           </para>
 415         </listitem>
 416       </varlistentry>
 417
 418       <varlistentry>
 419         <term><guilabel>Unlock</guilabel></term>
 420         <listitem>
 421           <para>
 422             removes the lock on region modification
 423           </para>
 424         </listitem>
 425       </varlistentry>
 426
 427       <varlistentry>
 428         <term><guilabel>Mute</guilabel></term>
 429         <listitem>
 430           <para>
 431             makes the region silent during playback
 432           </para>
 433         </listitem>
 434       </varlistentry>
 435
 436       <varlistentry>
 437         <term><guilabel>Unmute</guilabel></term>
 438         <listitem>
 439           <para></para>
 440         </listitem>
 441       </varlistentry>
 442
 443       <varlistentry>
 444         <term><guilabel>Toggle envelope visibility</guilabel></term>
 445         <listitem>
 446           <para>
 447             shows/hides the region gain envelope
 448           </para>
 449         </listitem>
 450       </varlistentry>
 451
 452       <varlistentry>
 453         <term><guilabel>Toggle envelope active</guilabel></term>
 454         <listitem>
 455           <para>
 456             turns the region gain envelope on/off (the line is gray when the
 457             envelope is off, green when it is on)
 458           </para>
 459         </listitem>
 460       </varlistentry>
 461
 462       <varlistentry>
 463         <term><guilabel>Original position</guilabel></term>
 464         <listitem>
 465           <para>
 466             if the region was recorded (and Broadcast WAVE was the native
 467             file format) moves the region to its original capture position
 468           </para>
 469         </listitem>
 470       </varlistentry>
 471
 472       <varlistentry>
 473         <term><guilabel>Normalize</guilabel></term>
 474         <listitem>
 475           <para>
 476             alters the gain processing of the region so that the loudest
 477             sample is at 0dBFS
 478           </para>
 479         </listitem>
 480       </varlistentry>
 481
 482       <varlistentry>
 483         <term><guilabel>DeNormalize</guilabel></term>
 484         <listitem>
 485           <para>
 486             undoes the effect of a normalize
 487           </para>
 488         </listitem>
 489       </varlistentry>
 490
 491       <varlistentry>
 492         <term><guilabel>Reverse</guilabel></term>
 493         <listitem>
 494           <para>
 495             writes the region to a new audio file with the contents
 496             reversed, and replaces the region with one referring to the new
 497             file
 498           </para>
 499         </listitem>
 500       </varlistentry>
 501
 502       <varlistentry>
 503         <term><guilabel>Nudge</guilabel></term>
 504         <listitem>
 505           <para>
 506             moves the region in various ways
 507           </para>
 508         </listitem>
 509       </varlistentry>
 510
 511       <varlistentry>
 512         <term><guilabel>Nudge fwd</guilabel></term>
 513         <listitem>
 514           <para>
 515             moves the region forward by the amount shown in the nudge clock
 516           </para>
 517         </listitem>
 518       </varlistentry>
 519
 520       <varlistentry>
 521         <term><guilabel>Nudge bwd</guilabel></term>
 522         <listitem>
 523           <para>
 524             moves the region backward by the amount shown in the nudge clock
 525           </para>
 526         </listitem>
 527       </varlistentry>
 528
 529       <varlistentry>
 530         <term><guilabel>Nudge fwd by capture offset</guilabel></term>
 531         <listitem>
 532           <para>
 533             moves the region forward by the same offset that it might have
 534             been (incorrectly) adjusted by when captured
 535           </para>
 536         </listitem>
 537       </varlistentry>
 538
 539       <varlistentry>
 540         <term><guilabel>Nudge bwd by capture offset</guilabel></term>
 541         <listitem>
 542           <para>
 543             moves the region backwards by the same offset that it might have
 544             been (incorrectly) adjusted by when captured
 545           </para>
 546         </listitem>
 547       </varlistentry>
 548
 549       <varlistentry>
 550         <term><guilabel>Trim</guilabel></term>
 551         <listitem>
 552           <para></para>
 553         </listitem>
 554       </varlistentry>
 555
 556       <varlistentry>
 557         <term><guilabel>Start to edit cursor</guilabel></term>
 558         <listitem>
 559           <para>
 560             adjusts the start of the region to the current position of the
 561             edit cursor (if possible)
 562           </para>
 563         </listitem>
 564       </varlistentry>
 565
 566       <varlistentry>
 567         <term><guilabel>Edit cursor to end</guilabel></term>
 568         <listitem>
 569           <para>
 570             adjusts the end of the region to the current position of the
 571             edit cursor (if possible)
 572           </para>
 573         </listitem>
 574       </varlistentry>
 575
 576       <varlistentry>
 577         <term><guilabel>Split</guilabel></term>
 578         <listitem>
 579           <para>
 580             if the edit cursor is within the region, splits the region at
 581             the editor cursor location
 582           </para>
 583         </listitem>
 584       </varlistentry>
 585
 586       <varlistentry>
 587         <term><guilabel>Make mono regions</guilabel></term>
 588         <listitem>
 589           <para>
 590             if the region is a multi-channel one, creates new regions
 591             corresponding to each channel. The new regions are added to the
 592             editor's region list, not the track.
 593           </para>
 594         </listitem>
 595       </varlistentry>
 596
 597       <varlistentry>
 598         <term><guilabel>Duplicate</guilabel></term>
 599         <listitem>
 600           <para>
 601             pops up a dialog allowing the region to be copied 1 or more
 602             times. Each copy is placed directly after the original or
 603             previous copy.
 604           </para>
 605         </listitem>
 606       </varlistentry>
 607
 608       <varlistentry>
 609         <term><guilabel>Fill Track</guilabel></term>
 610         <listitem>
 611           <para>
 612             copies the region as many times as necessary to fill the track
 613             to the current session end mark. Each copy is placed directly
 614             after the original or previous copy.
 615           </para>
 616         </listitem>
 617       </varlistentry>
 618
 619       <varlistentry>
 620         <term><guilabel>Remove</guilabel></term>
 621         <listitem>
 622           <para>
 623             remove the region from the track (non-destructive)
 624           </para>
 625         </listitem>
 626       </varlistentry>
 627
 628       <varlistentry>
 629         <term><guilabel>Destroy</guilabel></term>
 630         <listitem>
 631           <para>
 632             remove the region from the track and the editor region list, and
 633             if no other regions are referencing it, remove the audio file
 634             that the region is derived from. (
 635             <emphasis>DESTRUCTIVE</emphasis> )
 636           </para>
 637         </listitem>
 638       </varlistentry>
 639     </variablelist>
 640   </section>
 641 <!--
 642         <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
 643                 href="Some_Subsection.xml" />
 644         -->
 645 </section>