path: root/manual/xml/working_with_regions.xml

<?xml version="1.0" standalone="no"?>

<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

]>

<section id="sn-working-with-regions">
  <title>Working with Regions</title>
  <para>
    Regions are the basic elements of editing and composing in Ardour. Each
    region represents a single, contiguous section of one or more audio
    files. Regions are defined by a fixed set of attributes:
  </para>

  <itemizedlist>
    <listitem>
      <para>
        the source audio file(s) they represent
      </para>
    </listitem>

    <listitem>
      <para>
        a starting point in the audio file(s)
      </para>
    </listitem>

    <listitem>
      <para>
        a length
      </para>
    </listitem>
  </itemizedlist>

  <para>
    When placed into a
    <glossterm linkend="gt-playlist">playlist</glossterm>, they gain
    additional attributes:
  </para>

  <itemizedlist>
    <listitem>
      <para>
        a position along the timeline
      </para>
    </listitem>

    <listitem>
      <para>
        a layer
      </para>
    </listitem>
  </itemizedlist>

  <para>
    There are <emphasis>other attributes</emphasis> as well, but they do not
    define the region. Things you should know about regions:
  </para>

  <variablelist>
    <title></title>
    <varlistentry>
      <term>Regions are Cheap</term>
      <listitem>
        <para>
          By themselves, regions do not consume hardly any of your
          computer's resources. Each region requires a small amount of
          memory, and represents a rather small amount of CPU work if placed
          into an active track. So, don't worry about creating regions
          whenever you need to.
        </para>
      </listitem>
    </varlistentry>

    <varlistentry>
      <term>Regions are not audio files</term>
      <listitem>
        <para>
          Although a region can represent an entire audio file, they are
          never equivalent to an audio file. Most regions represent just
          parts of an audio file(s) on disk, and removing a region from a
          track has nothing to do with removing the audio file(s) from the
          disk ((the <emphasis>Destroy</emphasis> operation, one of Ardour's
          few destructive operations, can affect this)). Changing the length
          of a region has no effect on the audio file(s) on disk. Splitting
          and copying regions does not alter the audio file in anyway, nor
          does it create new audio files ((the <emphasis>Export</emphasis> ,
          <emphasis>Bounce</emphasis> and <emphasis>Reverse</emphasis>
          operations do create new audio files)).
        </para>
      </listitem>
    </varlistentry>
  </variablelist>

  <section id="region-naming">
    <title>Region Naming</title>
    <para>
      Regions are initially named using either:
    </para>

    <itemizedlist>
      <listitem>
        <para>
          the name of the playlist for which they were recorded
        </para>
      </listitem>

      <listitem>
        <para>
          the name of the embedded/imported audio file they represent
        </para>
      </listitem>
    </itemizedlist>

    <section id="whole-file-region-names">
      <title>Whole File Region Names</title>
      <para>
        These are not audio files, but regions that represent the full
        extent of an audio file. Every time a new recording is done, or a
        new file is embedded/imported, a new region is created that
        represents the entire audio file(s) This region will have the name
        of the playlist/original file, followed by a "-" and then a number.
      </para>

      <para>
        For recorded regions, the number will increase each time a new
        recording is made. So, for example, if there is a playlist called
        "Didgeridoo", the first recorded whole file region for that playlist
        will be called "Digderidoo-1". The next one will be "Digeridoo-2"
        and so on.
      </para>

      <para>
        For imported/embedded files, the region name will be based on the
        file name, but with any final suffix (e.g. ".wav" or ".aiff")
        removed.
      </para>

      <para>
        Normally, whole file regions are not inserted into tracks/playlists,
        but regions derived from them are. The whole-file versions live in
        the editor region list where they act as an organizing mechanism for
        regions that are derived from them.
      </para>
    </section>

    <section id="normal-region-names">
      <title>Normal Region Names</title>
      <para>
        When a region is inserted into a track/playlist, its initial name
        will end in a version number, such as ".1" or ".103". For a recorded
        region, if the whole file region was "Hang drum-1", then the region
        in the track will appear with the name "Hang drum-1.1". For an
        imported/embedded region, if the whole file region was
        "Bach:Invention3", then the region in the track will appear with the
        name "Bach:Invention3.1".
      </para>
    </section>

    <section id="copied-region-names">
      <title>Copied Region Names</title>
      <para>
        If the region is a copy of another region, it will begin life with
        the same name as the original. When an operation is carried out that
        modifies one of the copies, that particular copy will be renamed by
        incrementing the version number.
      </para>
    </section>

    <section id="renaming-regions">
      <title>Renaming Regions</title>
      <para>
        You can rename a region at any time. Use the <emphasis>region
        context menu</emphasis> to popup the rename dialog. The new name
        does not need to have a version number in it (in fact, it probably
        should not). The region will retain its name until it is modified
        after being copied.
      </para>
    </section>
  </section>

  <section id="selecting-regions">
    <title>Selecting Regions</title>
    <para>
      In general, operations on regions apply to whichever regions are
      currently <emphasis>selected</emphasis> .
    </para>

    <para>
      To select a single region, click on it using
      <mousebutton>Button1</mousebutton>.
    </para>

    <para>
      To add an unselected region to the currently selected regions, click
      on it using
      <keycombo><keycap>Shift</keycap><mousebutton>Button1</mousebutton></keycombo>.
    </para>

    <para>
      To remove a selected region from the currently selected regions, click
      on it using
      <keycombo><keycap>Shift</keycap><mousebutton>Button1</mousebutton></keycombo>.
    </para>
  </section>

  <section id="removing-regions">
    <title>Removing Regions</title>
    <para>
      Select the region(s) to be removed. Then press the "Delete" key or use
      the standard key binding for "Cut" (
      <keycombo><keycap>Ctrl</keycap><keycap>X</keycap></keycombo> by
      default).
    </para>

    <para>
      Note that "removing" a region is a non-destructive operation. It has
      no effect on the audio file(s) stored on disk. If you really want to
      destructively remove the region, use the context menu for the region
      which has a "Destroy" item. This is not guaranteed to remove the audio
      file from your disk storage, but it generally will.
    </para>
  </section>

  <section id="moving-regions">
    <title>Moving Regions</title>
    <para>
      To move a region, make sure you are in <emphasis>object</emphasis>
      mouse mode. Move the mouse pointer into the waveform display part of
      the region, press <mousebutton>Button1</mousebutton> and drag. The
      region will follow the mouse pointer as you move it around. By
      default, the region can move freely along the timeline - see
      <xref linkend="sn-snap-settings"/> for information on how to force the
      region to align to certain kinds of points along the timeline.
    </para>

    <para>
      To move a region from one track to another, simply start a move as
      described above, but move the mouse pointer into the desired track.
      The region will follow the mouse pointer. Note that if you have other
      kinds of "tracks" visible, the region will remain where it is as the
      mouse pointer moves across them, and will then jump to the new track.
      This serves as a visual reminder that you cannot drag an audio region
      into an automation track or a bus, for example.
    </para>

    <section id="moving-more-than-one-region">
      <title>Moving more than one region</title>
      <para>
        To move multiple regions, select them before moving. Then click+drag
        on one of the selected regions. All the regions will move, keeping
        their positions relative to each other.
      </para>
    </section>

    <section id="region-fixed-time-motion">
      <title>Fixed-time motion</title>
      <para>
        Sometimes, you want to move a region to another track, but keeping
        its position along the timeline exactly the same. To do this, use
        <mousebutton>Button2</mousebutton> rather than
        <mousebutton>Button1</mousebutton>.
      </para>
    </section>
  </section>

  <section id="copying-regions">
    <title>Copying Regions</title>
    <para>
      To copy a region, make sure you are in <emphasis>object</emphasis>
      mouse mode. Move the mouse pointer into the waveform press the
      <keycap>Ctrl</keycap> key, keep it down while pressing
      <mousebutton>Button1</mousebutton> and drag. A new region is created
      and will follow the mouse pointer as it moves. See
      <xref linkend="moving-regions"/> for more details on moving the copied
      region around.
    </para>

    <section id="copying-more-than-one-region">
      <title>Copying more than one region</title>
      <para>
        To copy multiple regions, select them before copying. Then
        click+drag on one of the selected regions. All the regions will be
        copied and as they move, the will keep their positions relative to
        each other.
      </para>
    </section>

    <section id="region-fixed-time-copying">
      <title>Fixed-time copying</title>
      <para>
        If you want to copy region(s) to other track(s) but keep the copies
        at the exact position on the timeline as the originals, simply use
        <keycombo><keycap>Ctrl</keycap><mousebutton>Button2</mousebutton></keycombo>
        instead of
        <keycombo><keycap>Ctrl</keycap><mousebutton>Button1</mousebutton></keycombo>.
      </para>
    </section>
  </section>

  <section id="trimming-regions">
    <title>Trimming Regions</title>
    <para></para>
  </section>

  <section id="auditioning-regions">
    <title>Auditioning Regions</title>
    <para></para>
  </section>

  <section id="region-gain-envelopes">
    <title>Region Gain Envelopes</title>
    <para></para>
  </section>

  <section id="region-context-menu">
<!-- needs work -->
    <title>Region Context Menu</title>
    <para>
      If you context-click on a region, a popup menu will appear. At or near
      the top of that menu is a list of all regions that exist in the
      clicked-upon track under the mouse pointer. Each region entry (shown
      by name) points to a submenu that contains region-specific operations:
    </para>

    <variablelist>
      <title></title>
      <varlistentry>
        <term><guilabel>Popup region editor</guilabel></term>
        <listitem>
          <para>
            creates and displays the editor for this region, allowing even
            more specific control over the region than this menu
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Raise to top layer</guilabel></term>
        <listitem>
          <para>
            moves the region to the top layer of this track (works only in
            "Most recently added/moved/trimmed regions are higher"
            <emphasis>layer mode</emphasis>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Lower to bottom layer</guilabel></term>
        <listitem>
          <para>
            moves the region to the bottom layer of this track (works only
            in "Most recently added/moved/trimmed regions are higher"
            <emphasis>layer mode</emphasis>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Define sync point</guilabel></term>
        <listitem>
          <para>
            if the edit cursor is within this region, defines the region
            sync point at the edit cursor location.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Remove sync point</guilabel></term>
        <listitem>
          <para></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Audition</guilabel></term>
        <listitem>
          <para>
            plays this region via the
            <glossterm linkend="gt-auditioner">auditioner</glossterm>
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Export</guilabel></term>
        <listitem>
          <para>
            exports this region to a new audio file, via the export dialog
            (thus allowing resampling, dithering, format specification etc.)
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Bounce</guilabel></term>
        <listitem>
          <para>
            re-records this region (with any plugins/inserts applied) to a
            new audio file, and replaces the region with one referring to
            the new file.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Lock</guilabel></term>
        <listitem>
          <para>
            prevents the region from being moved, trimmed, or modified in
            almost any way.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Unlock</guilabel></term>
        <listitem>
          <para>
            removes the lock on region modification
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Mute</guilabel></term>
        <listitem>
          <para>
            makes the region silent during playback
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Unmute</guilabel></term>
        <listitem>
          <para></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Toggle envelope visibility</guilabel></term>
        <listitem>
          <para>
            shows/hides the region gain envelope
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Toggle envelope active</guilabel></term>
        <listitem>
          <para>
            turns the region gain envelope on/off (the line is gray when the
            envelope is off, green when it is on)
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Original position</guilabel></term>
        <listitem>
          <para>
            if the region was recorded (and Broadcast WAVE was the native
            file format) moves the region to its original capture position
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Normalize</guilabel></term>
        <listitem>
          <para>
            alters the gain processing of the region so that the loudest
            sample is at 0dBFS
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>DeNormalize</guilabel></term>
        <listitem>
          <para>
            undoes the effect of a normalize
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Reverse</guilabel></term>
        <listitem>
          <para>
            writes the region to a new audio file with the contents
            reversed, and replaces the region with one referring to the new
            file
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Nudge</guilabel></term>
        <listitem>
          <para>
            moves the region in various ways
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Nudge fwd</guilabel></term>
        <listitem>
          <para>
            moves the region forward by the amount shown in the nudge clock
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Nudge bwd</guilabel></term>
        <listitem>
          <para>
            moves the region backward by the amount shown in the nudge clock
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Nudge fwd by capture offset</guilabel></term>
        <listitem>
          <para>
            moves the region forward by the same offset that it might have
            been (incorrectly) adjusted by when captured
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Nudge bwd by capture offset</guilabel></term>
        <listitem>
          <para>
            moves the region backwards by the same offset that it might have
            been (incorrectly) adjusted by when captured
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Trim</guilabel></term>
        <listitem>
          <para></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Start to edit cursor</guilabel></term>
        <listitem>
          <para>
            adjusts the start of the region to the current position of the
            edit cursor (if possible)
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Edit cursor to end</guilabel></term>
        <listitem>
          <para>
            adjusts the end of the region to the current position of the
            edit cursor (if possible)
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Split</guilabel></term>
        <listitem>
          <para>
            if the edit cursor is within the region, splits the region at
            the editor cursor location
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Make mono regions</guilabel></term>
        <listitem>
          <para>
            if the region is a multi-channel one, creates new regions
            corresponding to each channel. The new regions are added to the
            editor's region list, not the track.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Duplicate</guilabel></term>
        <listitem>
          <para>
            pops up a dialog allowing the region to be copied 1 or more
            times. Each copy is placed directly after the original or
            previous copy.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Fill Track</guilabel></term>
        <listitem>
          <para>
            copies the region as many times as necessary to fill the track
            to the current session end mark. Each copy is placed directly
            after the original or previous copy.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Remove</guilabel></term>
        <listitem>
          <para>
            remove the region from the track (non-destructive)
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guilabel>Destroy</guilabel></term>
        <listitem>
          <para>
            remove the region from the track and the editor region list, and
            if no other regions are referencing it, remove the audio file
            that the region is derived from. (
            <emphasis>DESTRUCTIVE</emphasis> )
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>
<!--
	<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
		href="Some_Subsection.xml" />
	-->
</section>