--- /dev/null
+
+<p>
+ <img alt="the Ableton Push 2 surface" src="/images/push2-main.jpg">
+</p>
+<p>
+ Since version 5.4, Ardour has had extensive support for the Ableton
+ Push2. This is an expensive but beautifully engineered control
+ surface primarily targetting the workflow found in Ableton's Live
+ software and other similar tools such as Bitwig. As of version 5.4,
+ Ardour does not offer the same kind of workflow, so we have designed
+ our support for the Push 2 around mixing and editing and musical
+ performance, without the clip/scene oriented approach in Live. This
+ may change in future versions of Ardour.
+</p>
+
+<h2>Connecting the Push 2</h2>
+<p>
+ Plug the USB cable from the Push 2 into a USB2 or USB3 port on your
+ computer. For brighter backlighting, also plug in the power supply
+ (this is not necessary for use).
+</p>
+<p>
+ The Push 2 will be automatically recognized by your operating
+ system, and will appear in any of the lists of possible MIDI ports
+ in both Ardour and other similar software.
+</p>
+<p>
+ To connect the Push 2 to Ardour, open the Preferences dialog, and
+ then click on "Control Surfaces". Click on the "Enable" button
+ in the line that says "Ableton Push 2" in order to activate Ardour's
+ Push 2 support.
+</p>
+<p>
+ Once you select the input and output port, Ardour will initialize
+ the Push 2 and it will be ready to use. You only need do this
+ once: once these ports are connected and your session has been
+ saved, the connections will be made automatically in this and other
+ future sessions.
+</p>
+
+<h2>Push 2 Configuration</h2>
+<p>
+ The only configuration option at this time is whether the pads send
+ aftertouch or polyphonic pressure messages. You can alter this
+ setting via the Push 2 GUI, accessed by double-clicking on the "Push
+ 2" entry in the control surfaces list.
+<p>
+<img alt="the Push 2 configuration dialog"
+ src="/images/push2-gui.png">
+</p>
+
+<h2>Basic Concepts</h2>
+<p>
+ With the Push 2 support in Ardour 5.4, you can do the following
+ things:
+ <dl>
+ <dt>Perform using the 8 x 8 pad "grid"</dt>
+ <dd>The Push 2 has really lovely pressure-sensitive pads that can
+ also generate either aftertouch or note (polyphonic) pressure.</dd>
+ <dt>Global Mixing</dt>
+ <dd>See many tracks at once, and control numerous parameters for each.</dd>
+ <dt>Track/Bus Mixing</dt>
+ <dd>View a single track/bus, with even more parameters for the track.</dd>
+ <dt>Choose the mode/scale, root note and more for the pads</dt>
+ <dd>37 scales are available. Like Live, Ardour offers both
+ "in-key" and "chromatic" pad layouts.</dd>
+ </dl>
+
+ ... plus a variety of tasks related to transport control, selection,
+ import, click track control and more.
+</p>
+
+<h2>Musical Performance</h2>
+<p>
+ Messages sent from the 8x8 pad grid and the "pitch bend bar" are
+ routed to a special MIDI port within Ardour called "Push 2 Pads"
+ (no extra latency is incurred from this routing). Although you can
+ manually connect this port to whatever you wish, the normal
+ behaviour of Ardour's Push 2 support is to connect the pads to the
+ most recently selected MIDI track.
+</p>
+<p>
+ This means that to play a soft-synth/instrument plugin in a given
+ MIDI track with the Push 2, you just need to select that track.
+</p>
+<p>
+ If multiple MIDI tracks are selected at once, the first selected
+ track will be used. Note that messages originating from all other
+ controls on the Push 2 will <em>not</em> not be delivered to the
+ "Push 2 Pads" port. This makes no difference in practice, because
+ the other controls do not send messages that are useful for musical
+ performance.
+</p>
+
+<h2>Global Mix</h2>
+<p>
+ This is the default mode that Ardour will start the Push 2 in. In
+ this mode, the 8 knobs at the top of the device, the 8 buttons below
+ them, the video display and the 8 buttons below that are combined to
+ provide a global view of the session mix.
+</p>
+<p>
+ <img alt="global mix mode on Push2 screen"
+ src="/images/push2-globalmix.png">
+</p>
+<p>
+ The upper buttons are labelled by text in the video display just
+ below them. Pressing one of the buttons changes the function of the
+ knobs, and the parameters that will shown for each track/bus in the
+ display.
+</p>
+<p>
+ As of Ardour 5.4, the possible parameters are:
+ <dl>
+ <dt>Volumes</dt>
+ <dd>The display shows a knob and text displaying
+ the current gain setting for the track, and a meter that
+ corresponds precisely to the meter shown in the Ardour GUI for
+ that track. Changing the meter type (e.g. from Peak to K12) in the
+ GUI will also change it in the Push 2 display. The physical knob
+ will alter track/bus gain.
+ </dd>
+ <dt>Pans</dt>
+ <dd>The display shows a knob indicating the pan direction/azimuth
+ for the corresponding track/bus. Turning the physical knob will
+ pan the track left and right. If the track/bus has no panner
+ (i.e. it has only a single output), no knob is shown and the
+ physical knob will do nothing. </dd>
+ <dt>Pan Widths</dt>
+ <dd><p>For tracks with 2 outputs, the display will show a knob
+ indicating the pan width setting for the corresponding
+ track/bus. The physical knob can be turned to adjust the
+ width.
+ </p>
+ <p>
+ Unlike many DAWs, Ardour's stereo panners have "width"
+ parameter that defaults to 100%. You cannot change the pan
+ direction/azimuth of a track with 100% width, but must first
+ reduce the width in order to pan it. Similarly, a track panned
+ anywhere other than dead center has limits on the maximum
+ width setting. If these concepts are not familiar to you,
+ please be aware than many DAWs use a "panner" that actually
+ implement "balance" and not "panning", hence the difference.
+ </p>
+ </dd>
+ <dt>A Sends</dt>
+ <dd>The display shows a knob indicating the gain level for the
+ first send in that track. If the track has no send, no knob will
+ be shown, and the physical knob for that track will do nothing.
+ </dd>
+ <dt>B Sends, C Sends, D Sends</dt>
+ <dd>Like "A Sends", but for the 2nd, 3rd and 4th sends of a
+ track/bus respectively.
+ </dd>
+ </dl>
+</p>
+<p>
+ To change which tracks are shown while in global mix mode, use the
+ left and right arrow/cursor keys just below and to the right of the
+ display. Tracks and busses that are hidden in Ardour's GUI will also
+ be hidden from display on the Push 2.
+</p>
+<p>
+ To select a track/bus directly from the Push 2, press the
+ corresponding button below the display. The track name will be
+ highlighted, and the selection will change in Ardour's GUI as well
+ (and also any other control surfaces).
+</p>
+
+<h3>Soloing and Muting in Global Mix mode</h3>
+<p>
+ The Solo and Mute buttons to the left of the video display can be
+ used to solo and mute tracks while in Global Mix mode. The operation
+ will be applied to the <em>first</em> currently selected
+ track(s).
+</p>
+<p>
+ There are two indications that one or more tracks are soloed:
+ <ol>
+ <li>The solo button will blink red</li>
+ <li>Track names will be prefixed by "*" if they are soloed, and
+ "-" if they are muted due to soloing.</li>
+ </ol>
+</p>
+<p>
+ To cancel solo, either:
+ <ul>
+ <li>Select the soloed track(s) and press the solo button
+ again</li>
+ <li>Press and hold the solo button for more than 1 second</li>
+ </ul>
+</p>
+
+<h2>Track Mix</h2>
+<p>Track Mix mode allows you to focus on a single track in more detail
+ than is possible in Global Mix mode. To enter (or leave) Track Mix
+ mode, press the "Mix" button.
+</p>
+<p>
+
+</p>
+<p>
+ In Track Mix mode, various aspects of the state of the first
+ selected track/bus will be displayed on the Push 2. Above the
+ display, the first 4 knobs control track volume (gain), pan
+ directiom/azimuth, pan width, and where appropriate, track input
+ trim.
+</p>
+<p>
+ Below the display, 7 buttons provide immediate control of mute,
+ solo, rec-enable, monitoring (input or disk or automatic), solo
+ isolate and solo safe state. When a a track is muted due to other
+ track(s) soloing, the mute button will flash (to differentiate from
+ its state when it is explicitly muted).
+</p>
+<p>
+ The video display also shows meters for the track, which as in
+ Global Mix mode, precisely match the meter type shown in Ardour's
+ GUI. There are also two time displays showing the current playhead
+ position in both musical (beats|bars|ticks) format, and as
+ hours:minutes:seconds.
+</p>
+<p>
+ To change which track is visible in Track Mix mode, use the
+ left/right arrow/cursor keys just below and to the right of the
+ video display.
+</p>
+
+<h2>Scale Selection</h2>
+<p>
+ Press the Scale button to enter Scale mode. The display will look
+ like this:
+</p>
+<p>
+ <img alt="track mix mode on Push2 screen"
+ src="/images/push2-scale.png">
+</p>
+<p>
+ In the center, 37 scales are presented. Scroll through them by
+ either using the cursor/arrow keys to the lower right of the
+ display, or the knobs above the display. The scale will change
+ dynamically as you scroll. You can also scroll in whole pages using
+ the upper right and upper left buttons above the display (they will
+ display "<" and ">" if scrolling is possible).
+</p>
+<p>
+ To change the root note of the scale, press the corresponding button
+ above or below the video display.The button will be lit to indicate
+ your selection (and the text will be highlighted).
+</p>
+<p>
+ By default, Ardour configures the Push 2 pads to use "in-key" mode,
+ where all pads correspond to notes "in" the chosen scale. Notes
+ corresponding to the root note, or the equivalent note in higher
+ octaves, are highlighted with the color of the current target MIDI
+ track.
+</p>
+<p>
+ In
+ "chromatic" mode, the pads correspond to a continuous sequence of
+ notes starting with your selected root note. Pads corresponding to
+ notes in the scale are illuminated; those corresponding to the root
+ note are lit with the color the current target MIDI track. Other
+ pads are left dark, but you can still play them.
+</p>
+<p>
+ To switch between them, press button on the lower left of the video
+ display; the text above it will display the current mode (though it
+ is usually visually self-evident from the pad lighting pattern).
+</p>
+<p>
+ To leave Scale mode, press the "Scale" button again. You may also
+ use the upper left button above the display, though if you have
+ scrolled left, it may require more than one press.
+</p>
+
+<h2>Specific Button/Knob Functions</h2>
+
+<p>
+ In addition to the layouts described above, many (but not all) of
+ the buttons and knobs around the edges of the Push 2 will carry out
+ various functions related to their (illuminated) label. As of Ardour
+ 5.4, this includes:
+ <dl>
+ <dt>Metronome (button and adjacent knob)</dt>
+ <dd>
+ Enables/disables the click (metronome). The knob directly above
+ it will control the volume (gain) of the click.
+ </dd>
+ <dt>Undo/Redo</dt>
+ <dd>
+ Undo or redo the previous editing operation.
+ </dd>
+ <dt>Delete</dt>
+ <dd>
+ Deletes the currently selected region, or range, or
+ note. Equivalent to using Ctrl/Cmd-x on the keyboard.
+ </dd>
+ <dt>Quantize</dt>
+ <dd>
+ If a MIDI region is selected in Ardour, this will open the
+ quantize dialog.
+ </dd>
+ <dt>Duplicate</dt>
+ <dd>
+ Duplicates the current region or range selection.
+ </dd>
+ <dt>Rec-Enable</dt>
+ <dd>
+ Enables and disables Ardour's global record enable state.
+ </dd>
+ <dt>Play</dt>
+ <dd>
+ Starts and stops the transport. Press Shift-Play to return to
+ the session start.
+ </dd>
+ <dt>Add Track</dt>
+ <dd>
+ Opens Ardour's Add Track/Bus dialog.
+ </dd>
+ <dt>Browse</dt>
+ <dd>
+ Open's Ardour's import dialog to select and audition existing
+ audio and MIDI files.
+ </dd>
+ <dt>Master</dt>
+ <dd>
+ Pressing this button jumps directly to Track Mix mode, with the
+ master out bus displayed.
+ </dd>
+ <dt>Cursor arrows</dt>
+ <dd>
+ These are used by some modes to navigate within the display (e.g
+ Scale mode). In other modes, the up/down cursor arrows will
+ scroll the GUI display up and down, while the left/right cursor
+ arrows will generally scroll within the Push 2 display itself.
+ </dd>
+ <dt>Repeat</dt>
+ <dd>
+ Enables/disables loop playback. This will follow Ardour's "loop
+ is mode" preference, just like the loop button in the Ardour
+ GUI.
+ </dd>
+ <dt>Octave buttons</dt>
+ <dd>
+ These shift the root note of the current pad scale up or down by
+ 1 octave.
+ </dd>
+ <dt>Page buttons</dt>
+ <dd>
+ These scroll Ardour's editor display left and right along the
+ timeline.
+ </dd>
+ <dt>Master (top right) knob</dt>
+ <dd>
+ This knob controls the gain/volume of Ardour's main output. If
+ the session has a monitor saec
+ </dd>
+ </dl>
+</p>
+
+