Copy local state in AudioRegionView copy constructor. Fixes #4047.

[ardour2.git] / manual / xml / mixer_strips.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" [

]>

<!-- XXX lots to do on this page -->

<section id="sn-mixer-strips">
  <title>Mixer Strips</title>
  <para>
    Each track and bus is represented in the mixer window by a
    <emphasis>mixer strip</emphasis> that contains various controls related
    to signal flow. There are two places in Ardour in which you can see
    mixer strips. The mixer window is the obvious one (and the one we deal
    with here), but you can also view a single mixer strip in the editor
    window by clicking the <guibutton>editor mixer</guibutton> button.
  </para>
  <mediaobject>
    <imageobject>
      <imagedata fileref="images/mixer_strip_diagram.png"/>
    </imageobject>
  </mediaobject>
  <para>
    this image needs replacing with labels and better resolution The mixer
    strip for a bus is essentially identical to the one for an audio track,
    but it is missing certain controls that make no sense - you cannot
    record into a bus, so there is no record enable button, for example.
  </para>

  <para>
    The mixer strips are designed to visually model signal flow. The input
    button selects the input of the track that this mixer strip monitors.
    The outputs of the track (the 'tape recorder') are 'hard-wired' to the
    inputs of the mixer strip. Think of the input to the strip starting at
    the polarity switch, flowing down through the prefader
    inserts/plugins/sends section, through the gain fader, past the
    postfader inserts/plugins/sends section, the panner, and out through the
    output selector. In the case of a bus, there is no 'tape machine'
    inserted between the input selector and the actual input of the strip,
    but the signal flow is identical otherwise.
  </para>

  <section id="mixer-strip-narrow-strip-button">
    <title>Narrow Mixer Strip Button</title>
    <para>
      the button on the top left of the mixer strip is labelled with two
      arrows separated by a line. Left clicking this button will reduce the
      horizontal size of the mixer strip. Clicking it again will restore the
      previous size. The first click also has the effect of shortening the
      names of controls. Plugin lists become very small in this mode,
      however more faders are accessible without scrolling. Your needs may
      vary, hence the existence of this button.
    </para>
  </section>

  <section id="mixer-strip-hide-button">
    <title>Hide Button</title>
    <para>
      The button opposite the <emphasis>Narrow Mixer Strip Button</emphasis>
      hides the mixer strip from view. this button has no effect on signal
      flow or muting. When a mixer strip is hidden, it's entry in the strips
      list is darkened. To restore the mixer strip to the visible state,
      click it's entry in the strip list with the left mouse button.
    </para>
  </section>

  <section id="mixer-strip-track-name">
    <title>Track Name</title>
    <para>
      The track name displays the current name of the track as displayed in
      the editor window. right-clicking on the name brings up a drop-down
      menu that allows you to rename, activate, deactivate and remove the
      track. Selecting <guimenuitem>Rename</guimenuitem> opens a new window
      displaying the name of the track. to change it, type your change and
      press ok. to leave it unaltered, press cancel. Selecting
      <guimenuitem>remove</guimenuitem> opens a new window asking for
      confirmation of your track removal request. removing a track removes
      that track from the project. If the playlist used by the removed track
      is not used by any other track, it will also be removed.
    </para>
  </section>

  <section id="mixer-strip-group-button">
    <title>Group Button</title>
    <para>
      The group button displays the name of the currently selected mix
      group. if no group is selected, it will read no group. when clicked, a
      drop-down menu appears which lists the current mixer groups, along
      with the option no group. if a group is selected, any fader movement
      on one of the group member faders will be translated to the other
      members of the group.
    </para>
  </section>

  <section id="mixer-strip-input-selector">
    <title>Input Selector</title>
    <para>
      The input selector allows you to assign hardware or software inputs to
      the track that this mixer strip monitors. clicking on the input box
      makes a drop-down menu appear which lists ready-made combinations of
      jack ports, along with the options disconnect and edit. You can either
      select a preset hardware input combination from the drop-down list, or
      select <guimenuitem>edit</guimenuitem> to open the input selector
      window which allows finer control, such as changing the number of
      inputs to the track or using software devices as inputs. For more
      information on this window, see <xref linkend="sn-other-windows"/>.
      <guibutton>Disconnect</guibutton> removes all input assignments while
      leaving the number of ports untouched.
    </para>
  </section>
  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 
          href="invert_polarity.xml" />
  <section id="mixer-strip-solo-button">
    <title>Solo Button</title>
    <para>
      The solo button puts the mixer strip in solo mode. the solo indicator
      in the editor window will flash if any mixer strip is set to solo, and
      only those tracks that are set in solo will be routed through the
      system.
    </para>
  </section>

  <section id="mixer-strip-mute-button">
    <title>Mute Button</title>
    <para>
      The mute button mutes the output of the mixer strip.
    </para>
  </section>

  <section id="mixer-strip-record-enable-button">
    <title>Record Enable Button</title>
    <para>
      The record enable button arms the track for recording. pressing this
      will change the way you monitor and meter the selected input signal
      depending on the state of the monitoring settings in the options
      editor, as well as the auto input setting in the editor.
    </para>
  </section>

  <section id="mixer-strip-automation-mode-buttons">
    <title>Automation Mode Buttons</title>
    <para>
      The automation mode buttons allow you to select a fader or pan
      automation mode from a drop-down list. see
      <xref linkend="sn-automation"/> for more information about automation
      modes.
    </para>
  </section>

  <section id="mixer-strip-redirect-boxes">
    <title>Redirect Boxes</title>
    <para>
      These dark areas above and below the fader allow you to place inserts,
      sends and plugins into the signal path before and after the fader
      respectively. you may also easily reorder them whilst playing.
      collectively, the objects that belong in these boxes are called
      redirects. If there are redirects present in the channel, they can be
      reordered by dragging them vertically. because plugins and inserts can
      have different numbers of inputs to outputs, sometimes you may reach a
      situation where the inputs and outputs cannot be all connected
      sensibly. in this case, your reordering change will be disallowed by
      the program.
    </para>

    <para>
      Right clicking within the dark area will bring up a drop-down menu
      which allows you to manipulate the redirects in various ways.
    </para>

    <variablelist>
      <title>Redirect Boxes</title>
      <varlistentry>
        <term><guimenuitem>new plugin</guimenuitem></term>
        <listitem>
          <para>
            selecting new plugin will open a dialog which lists the plugins
            available on your system. selecting a plugin which is compatible
            with the number of streams in the channel at that point will
            result in the plugin being placed in the redirect box in an
            inactive state. this is indicated by the brackets around the
            plugin name. double-clicking the plugin name will bring up a
            window that allows you to control the parameters of the plugin
            statically (including bypass) or using automation. all plugins
            that report their latency are time-compensated automatically in
            ardour.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guimenuitem>new insert</guimenuitem></term>
        <listitem>
          <para>
            places at least two new jack ports at that point in the mixer
            strip (one input, one output). these ports will then be
            available to any jack client (including Ardour itself), allowing
            another program (or channels within another program) to be
            inserted across the channel. hardware ports may also, of course,
            be used, allowing the insertion of outboard equipment. the
            insert will then appear in the redirect box in brackets
            indicating that it is inactive. to activate or deactivate an
            insert, right-click on it and select activate. double-clicking
            on the insert will bring up a dialog which allows to to assign
            its inputs and outputs to other jack ports.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guimenuitem>new send</guimenuitem></term>
        <listitem>
          <para>
            selecting new send will first bring up a dialog box that enables
            you to select the number of outputs the send has, along with the
            destination of each output. closing this dialog will reveal the
            name of the send in brackets, indicating that it is inactive. to
            activate the send, right click on it and select Activate.
            double-clicking on the send brings up the previous dialog, which
            will now include a fader which is provided for level control.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guimenuitem>clear</guimenuitem></term>
        <listitem>
          <para>
            selecting clear in the menu removes all redirects from the mixer
            strip (pre and post fader). you can remove an individual
            redirect by holding the shift key and right clicking it.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guimenuitem>cut</guimenuitem>, <guimenuitem>copy</guimenuitem>, <guimenuitem>paste</guimenuitem></term>
        <listitem>
          <para>
            these items allow you to cut, copy and paste plugins, including
            their current settings, between Redirect Boxes.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guimenuitem>rename</guimenuitem></term>
        <listitem>
          <para>
            selecting rename will bring up a dialog displaying the name of
            the selected redirect. change the name by typing into the text
            area and pressing ok.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guimenuitem>select all/deselect all</guimenuitem></term>
        <listitem>
          <para>
            these two options select or deselect all plugins in the channel.
            this could be used, for instance, in preparation to copy all
            plugins from a channel to another one, along with the current
            settings.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guimenuitem>activate/deactivate</guimenuitem></term>
        <listitem>
          <para>
            selecting either of these will activate or deactivate the
            currently selected redirect(s) respectively. deactivate is the
            equivalent of <guimenuitem>bypass</guimenuitem>.
          </para>

          <note>
            <para>
              note that you can bypass a plugin from it's parameter window
              as well as from here.
            </para>
          </note>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guimenuitem>activate all/deactivate all</guimenuitem></term>
        <listitem>
          <para>
            selecting either of these will activate or deactivate all
            redirect(s) in the mixer strip respectively. deactivate is the
            equivalent of <guimenuitem>bypass</guimenuitem> if you're a
            plugin.
          </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><guimenuitem>edit</guimenuitem></term>
        <listitem>
          <para>
            selecting edit brings up the controls relevent to the selected
            redirect. this is the equivalent to holding control and
            right-clicking on a redirect. note that the right click method
            will not bring up the controls of the selected redirect, only
            the one beneath the mouse pointer.
          </para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section id="mixer-strip-pre-post-input-button">
    <title>Pre/Post/Input Button</title>
    <para>
      This button cycles between three metering modes, which determine which
      signal is fed to the meters. the modes are pre-fader (the signal at
      the input to the fader), post-fader and input (the level at the track
      input). left clicking cycles through the three modes one step at a
      time, while middle-clicking alternates between the current setting and
      the setting two steps ahead. this allows one-click direct a/b
      comparison between all available monitoring points.
    </para>
  </section>

  <section id="mixer-strip-gain-display">
    <title>Gain Display</title>
    <para>
      this control displays the current gain of the fader to the nearest
      0.1dB. left clicking on the value will lower the gain by an amount
      dependent upon the fader position the graduations become smaller as
      the fader nears 0dB gain. right clicking increases the gain by the
      same amount. middle clicking resets the gain to 0dB.
    </para>
  </section>

  <section id="mixer-strip-unit-selector">
    <title>Unit Selector</title>
    <para>
      Right clicking on the meter bars allows you to select the range of
      signal levels displayed by the meters. the selected range will be
      displayed as a column of numbers next to the meter. /*XXX this feature
      is currently not working*/ Gain Level Display
    </para>
  </section>

  <section id="mixer-strip-peak-meter">
    <title>Peak Meter</title>
    <para>
      This control displays the highest peak since the last peak meter
      reset. Resetting the peak meter is achieved by left-clicking the
      displayed number. The peak meter monitors the signal selected by the
      <emphasis>Pre/Post/Input Button</emphasis> .. the same signal as the
      meters. It should be noted here that 0dBfs corresponds a value equal
      to the maximum input or output level of your audio hardware,
      independent of it's bit depth.
    </para>
  </section>

  <section id="mixer-strip-gain-fader">
    <title>Gain Fader</title>
    <para>
      The fader changes the signal level within the mixer strip before the
      post-fader plugins, which are before the output ports. 6dB of gain is
      allowed. there are several shortcuts available for the fader. Using
      the scroll wheel of your mouse while hovering above the fader will
      coarsely change its position. Holding the control key whilst mouse
      wheeling will give you finer control. Holding the shift key and
      clicking the fader will reset it to unity gain. Holding control and
      pressing the middle mouse button whilst over the fader will allow you
      to bind a midi control to it, provided you have an available midi
      device set in the options menu.
    </para>
  </section>

  <section id="mixer-strip-meters">
    <title>Meters</title>
    <para>
      The number of meters displayed next to the fader is dependent on the
      number of inputs or outputs the channel has, whichever is greater. The
      meters provide a colour-graduated scale from -50 dBfs to +6dBfs. They
      display the instantaneous value of the signal at the monitoring point
      selected by the Pre/Post/Input button. 0dBfs corresponds a value equal
      to the maximum input or output level of your audio hardware,
      independent of it's bit depth. Exceeding 0dBfs does not correspond to
      running out of headroom within the mixer, or in any signal path
      subsequent to that point within the Jack server. It merely means that
      if that signal is connected directly to a hardware port whose
      resolution is less than the 32-bit floating point resolution that
      Ardour uses (i.e. a soundcard), then that port will exceed it's
      maximum output level, resulting in distortion. hitting 0dB within the
      mixer (or any point in the Jack server) means that you have
      approximately 100dB of headroom remaining. as it is unlikely that you
      will reach this point, it is not represented in any special way by the
      meter. Naturally, if the input is selected as the monitoring point for
      the meter, exceeding 0dBfs means that the input of your a/d converter
      has clipped.
    </para>
  </section>

  <section id="mixer-strip-panner">
    <title>Panner</title>
    <para>
      The panner in Ardour is actually two panners. Because any mixer strip
      in Ardour can route any number of streams of audio anywhere, the idea
      of panning can be a complex one. To allow for the current
      stereo-centric mainstream world as well as the multi-speaker
      experimental one, one of two styles of panner will appear here
      depending on the number of outputs the channel strip has. In the
      simple case of mono channel input / stereo output, a single panner
      will be present. The current pan position is represented by a dot (the
      dot is the audio stream) which lies between the letters 'L' and 'R',
      which represent the left and right outputs respectively. To change the
      panning position of the stream, move the mouse while holding down the
      left mouse button. the dot will follow your mouse pointer. To
      introduce sudden changes to the pan setting, place the mouse pointer
      over the desired position and click the middle mouse button. The pan
      control will immediately snap to the mouse pointer position. The
      panner may be bypassed by right-clicking the control and selecting
      <guimenuitem>bypass</guimenuitem> from the drop-down menu. The panner
      will immediately be bypassed. The increased level you notice when the
      panner is bypassed is due to the way panning works. It is not a bug.
      <emphasis>XXX what gain law is used in the panner?</emphasis>
    </para>

    <para>
      In the case of a stereo input / stereo output combination, two panning
      controls will appear, one corresponding to each audio stream. You can
      <emphasis>link</emphasis> the controls together in two different ways
      in this situation, using the direction arrows next to the
      <guibutton>link</guibutton> button. Panners can be linked to travel
      either in opposite directions or to maintain a consistent stereo width
      across the travel of the control. These two modes are represented by
      the orientation of the two arrows next to the
      <guibutton>link</guibutton> button, which point in either the same or
      opposite directions. The <guibutton>link</guibutton> button must be
      engaged before you can change the <emphasis>link</emphasis> mode. To
      link all the panners in a mixer strip, left-click the
      <guibutton>link</guibutton> button, then select the desired link mode
      by pressing the button marked with arrows.
    </para>

    <para>
      Let's get a little more complicated by adding another output to the
      mixer strip. From this point onwards, the panning positions are
      represented with numbered dots on a square field. Orange dots
      represent the outputs, and the numbered dots represent the streams.
      the position of the outputs change according to the number of outputs
      in the strip. This happens in order to allow the most useful
      arrangement of the available space. At some point, adding an output
      will cause the outputs to line up from the top left of the panning
      square towards the centre. this is to allow for the 'multi-speaker big
      sweep' to occur - where the sound is panned from speaker to speaker
      around the room in sequence.
    </para>

    <para>
      Don't forget that you can bypass the panner by right clicking and
      selecting <guimenuitem>bypass</guimenuitem> from the drop-down menu.
      this may simplify your multi-speaker setup, as often in this type of
      project panning between all speakers or outputs is not required on all
      tracks.
    </para>
  </section>

  <section id="mixer-strip-output-selector">
    <title>Output Selector</title>
    <para>
      The output selector allows you to assign the outputs of each mixer
      strip. left-clicking the output selector causes a ready-made list of
      output ports to appear in a drop-down menu, along with edit and
      disconnect options. Selecting <guimenuitem>Edit</guimenuitem> will
      allow you to change the number of outputs the channel has, as well as
      select software and hardware ports to route signals to. For more
      information on the window that appears when you select this option,
      see the <xref linkend="sn-other-windows"/>.
      <guimenuitem>Disconnect</guimenuitem> will leave the number of output
      ports unchanged, but remove all assignments to output ports.
    </para>
  </section>

  <section id="mixer-strip-scratch-pad">
    <title>Scratch Pad</title>
    <para>
      This is the text area below the <guibutton>output</guibutton> button.
      it allows you to enter any notes that you feel may be relevant to that
      track. The notes are stored when you save the session.
    </para>
  </section>
</section>