First shot at Cue documentation, lots of FIXMEs

This is basically the structure + a bunch of stuff to do.
More to follow Really Soon Now (tm)

include/clip-follow-actions.html

@@ -0,0 +1,48 @@
+<h2>Follow Actions</h2>
+
+<p>When the contents of one trigger slots has been played a user-defined number of times, Ardour can stop playing trigger slots or switch to a different trigger slot. This is defined by follow actions, i.e. actions follow the playback of a trigger slot.</p>
+
+<p>
+  Here are the currently available follow actions:
+</p>
+
+<p>FIXME THE ENTIRE TABLE</p>
+
+<table class="dl">
+  <tr><th><kbd class="menu">None</kbd></th>
+  <td>Play the contents of the slot once and stop</td></tr>
+  <tr><th><kbd class="menu">Stop</kbd></th>
+  <td>Stop after playing back the amount of times set with Follow Count or via Follow Length (see below)</td></tr>
+  <tr><th><kbd class="menu">Again</kbd></th>
+  <td>Repeat the contents of the trigger slot over and over again</td></tr>
+  <tr><th><kbd class="menu">Reverse</kbd></th>
+  <td>Play back and go to the previous trigger slot</td></tr>
+  <tr><th><kbd class="menu">Forward</kbd></th>
+  <td>Play back and go to the next trigger slot</td></tr>
+  <tr><th><kbd class="menu">Jump</kbd></th>
+  <td>Play back and jump to a particular scene. Selecting multi-jump and multiple trigger slots will result in randomly playing one of the selected slots.</td></tr>
+</table>
+
+<p>To help distinguishing between them, Ardour will display an icon next to the name of a clip in a slot:</p>
+
+<figure>
+  <img style="width:150px;" src="/images/cue-follow-actions-all-icons.png" alt="Follow Action icons">
+  <figcaption>
+    Follow action icons, top to bottom: None, Stop, Again, Reverse, Forward, Jump to scene B, Multi-Jump
+  </figcaption>
+</figure>
+
+<h2>Follow Actions Probability</h2>
+
+<p>Ardour can help you explore ideas by bringing an element of randomness. You can set two possible follow actions to randonly alternate between, then set the percentage of probability of the left or the right follow action to be triggered. 0% means the left follow action is always chosen, 100% means the right follow action is always chosen. Anything between 0% and 50% will skew the probability towards the left follow action, anything between 50% and 100% will do the same for the right follow action.</p>
+
+<h2>Duration</h2>
+
+<p>Follow Count</p>
+
+<p>How many times to repeat a clip before triggering the Follow Action. FIXME</p>
+
+<p>Follow Length: [] beats</p>
+
+<p>When enabled, follow length is used instead of clip length. FIXME</p>
+

include/clip-launch-options.html

@@ -0,0 +1,51 @@
+<h2>Velocity Sense</h2>
+
+<p>
+  This control defines how much the velocity coming off your MIDI device
+  affects clip's volume. At 0%, which is the default, it doesn't matter how
+  hard you press a key or a pad, the volume will be what you set it to.
+  At 100%, hitting a key as hard as you can produces maximum volume, and
+  pressing the key or a pad really softly produces a barely audible sound.
+</p>
+
+<h2>Launch Style</h2>
+
+<p>FIXME THE ENTIRE TABLE</p>
+
+<table class="dl">
+  <tr><th><kbd class="menu">Trigger</kbd></th>
+  <td>You click and it starts playing until it stops; mouse up and note-off are ignored</td></tr>
+  <tr><th><kbd class="menu">Retrigger</kbd></th>
+  <td>Mouse down or note-on starts or retriggers; mouse up and note-off FIXME</td></tr>
+  <tr><th><kbd class="menu">Gate</kbd></th>
+  <td>plays only as long as you press the play button, quantization setting defines how soon it starts and ends after pressing the button down. Runs till mouse up/note off then to next quantization</td></tr>
+  <tr><th><kbd class="menu">Toggle</kbd></th>
+  <td>Keeps looping until you click it again. runs till next mouse down/NoteOn</td></tr>
+  <tr><th><kbd class="menu">Repeat</kbd></th>
+  <td>Keeps looping, but when you press and hold, it starts from the beginning and plays as far as quantization setting goes, e.g. 1/16 means it repeats the first 1/16 of a bar. plays only quantization extent until mouse up/note off</td></tr>
+</table>
+
+<figure>
+  <img class="mini" style="width:150px;" src="/images/cue-launch-style-all-icons.png" alt="Launch style icons">
+  <figcaption>
+    Launch style icons, top-to-bottom: Trigger, Retrigger, Gate, Toggle, Repeat
+  </figcaption>
+</figure>
+
+<h2>Launch Quantize</h2>
+
+<p>From 4 bars down to 1/64 bar, and None. FIXME</p>
+
+<h2>Legato</h2>
+
+<p>FIXME (also, doesn't work properly yet).</p>
+
+<h2>Cue Isolate</h2>
+
+<p>FIXME, If selected, the slot will not respond to start/stop cue events (does it work?)</p>
+
+<h2 id="follow-options">Follow Options</h2>
+
+<p>
+  FIXME. These options are where you define the transition from one slot to another.
+</p>

include/clip-stretch-options.html

@@ -0,0 +1,39 @@
+<h2>Stretch</h2>
+
+<p>FIXME. Optional. What happens when disabled? Won’t match the current timeline
+tempo: START THE SECTION WITH THIS: ARDOUR ALWAYS MATCHES CURRENT SESSION
+TEMPO, SO TEMPO RAMPS WILL WORK FOR CLIPS</p>
+
+<p>Stretch modes:</p>
+
+<ul>
+  <li><dfn>Crisp</dfn> works best for sounds with fast onset like drums and percussion</li>
+  <li><dfn>Smooth</dfn> is best used for sustained notes like pads</li>
+  <li><dfn>Mixed</dfn> is for anything in between</li>
+</ul>
+
+<h2>BPM</h2>
+
+Displays estimated tempo rounded to the closest integer. You can make half or double of whatever is in that display. You can go as low as almost zero and you will be exhausted after BPM in 6 figures.
+
+<h2>Clip Length</h2>
+
+Measured in beats. Affects the bpm. FIXME
+
+<h2>Length in Bars</h2>
+
+<p>It’s a hint to help you counting. FIXME</p>
+
+<p>1) when a file is loaded, we infer its bpm either by minibpm's estimate, a flag in the filename, metadata (TBD) or other means</p>
+
+<p>2) we assume the clip must have an integer number of beats in it  (simplest case is a one-bar loop with 4 beats in it)</p>
+
+<p>3) ...so we round to the nearest beat length, and set the tempo to *exactly* fit the sample-length into the assumed beat-length</p>
+
+<p>4) the user may recognize a problem:  "this was a 3/4 beat, which was rounded to 4 beats but it should have been 3"</p>
+
+<p>5) if the user changes the beat-length, then the tempo is recalculated for use during stretching</p>
+
+<p>6) someday, we will also allow the sample start and length to be adjusted in a trimmer, and that will also adjust the tempo</p>
+
+<p>7) in all cases the user should be in final control; but our "internal" value for stretching are just sample-start and BPM, end of story</p>

include/cue-window-elements.html

@@ -0,0 +1,78 @@
+<p>
+	For cues, Ardour generally follows the design pattern of other applications
+	that support a grid-based non-linear workflow. Here are themain elements
+	of the <dfn>Cue</dfn> window.
+</p>
+
+<!-- <figure>
+  <img style="width:150px;" src="/images/cue-window.png" alt="The Cue window elements">
+  <figcaption>
+    The Cue window elements
+  </figcaption>
+</figure> -->
+
+<ol>
+	<li>Grid comprised of tracks and cues</li>
+	<li>Processor box</li>
+	<li>Per-track controls</li>
+	<li>Sidebar with the tabs: Clips, Tracks, Sources, Regions</li>
+	<li>Bottom bar with options for clips and trigger slots</li>
+</ol>
+
+<h2>Grid</h2>
+
+<p>Grid: tracks and cues. FIXME</p>
+
+<p>Slot: launch indicator, title, follow action indicator. FIXME
+
+<h2>Playback Indication</h2>
+
+<p>FIXME</p>
+
+<h2>Processor Box</h2>
+
+<p>
+	Similarly to the ordinary track, this is where you assign a virtual
+	instrument to a MIDI track and/or add effects to be applied to all clips
+	in a track regardless of what scene they belong to.
+</p>
+
+<h2>Per-Track Controls</h2>
+
+<p>
+	Again, similarly to ordinary tracks, this is where you tweak the fader
+	and panner positions, mute or solo an entire track.
+</p>
+
+<h2>Sidebar</h2>
+
+<p>
+	Ardour defaults to displaying the Clips tab as the clips browser
+	is commonly used for pulling reusable clips into the project.
+</p>
+
+<p>
+	You can also access the list of tracks, which in the context of the Cue
+	window is mostly useful to mark a track as visible or not visible in the
+	Cue window.
+</p>
+
+<p>
+	Additionally, you can pick a source or a region in the <dfn>Sources</dfn>
+	or <dfn>Regions</dfn> tabs respectively and drop them in the <dfn>Clips</dfn>
+	tab to copy a reusable item to your custom library of clips.
+</p>
+
+<h2>Bottom Bar</h2>
+
+<p>
+	The bottom bar contains three or four groups of controls depending on the
+	type of a clip, audio or MIDI.
+</p>
+
+<ul>
+	<li><dfn>Clip Properties</dfn>: FIXME</li>
+	<li><dfn>Launch Options</dfn>: FIXME</li>
+	<li><dfn>Follow Actions</dfn>: FIXME</li>
+	<li><dfn>Stretch Options</dfn> (audio-only): FIXME</li>
+</ul>

include/mixing-linear-nonlinear-workflows.html

@@ -0,0 +1,14 @@
+<p>
+	You can combine the linear workflow, i.e. working with regions on the
+	timeline, and the non-linear workflow, i.e. launching clips from trigger
+	slots and setting up follow actions.
+</p>
+
+<p>FIXME GENERAL ORDER OF ACTION:</p>
+
+<ol>
+<li>1. Set up follow actions, follow count etc. It's up to you if you want transitions between scenes through follow actions. You can set slots to use Again follow action and add markers treiggering cues where you need them and adding "stop all cues" marker where you need all cues off.</li>
+<li>Add cue markers.</li>
+<li>Add the "stop all cues" marker</li>
+<li>Draw/record your non-repeatable regions the usual way on the timeline/canvas.</li>
+</ol>

include/non-linear-workflow-principles.html

@@ -0,0 +1,122 @@
+<p>
+	The Cue window allows working with music ideas in a non-linear fashion.
+	Instead of navigating the timeline and placing regions of audio and MIDI
+	data at a particular point in time, you deal with short clips that contain
+	rhythmic and melodic patterns and can be triggered to play a certain amount
+	of times, then automatically trigger another clip to be played.
+</p>
+
+<p>
+	The concept has been introduced and popularized by Ableton and since then
+	found its way into many other applications. Ardour draws many ideas from
+	Ableton Live, as well as from several other digital audio workstations,
+	and adapts them to Ardour's specifics. If you are familiar with Live, you
+	will find many aspects familiar, but you should not expect the Cue's feature
+	set to be a 100% copy of that from any other application.
+</p>
+
+<p>
+	Here are some basics concepts of the non-linear workflow shared by multiple
+	applications including Ardour.
+</p>
+
+<h2>Grid and scenes</h2>
+
+<p>
+	All clips are organized in a kind of a grid. The grid provides an overview
+	of all the musical ideas, all the rhythmic patterns, short melodies, and sound
+	effects that you can use in a composition.
+</p>
+<p>
+	One dimension of the grid, usually represented by a track, would accumulate
+	clips played with roughly the same kind of an instrument, e.g. all drum
+	patterns, or all basslines etc.
+</p>
+<p>
+	The other dimension, usually called scenes (or cues, in Ardour) would
+	organize these clips so that you would be able to play multiple clips at
+	the same time by pressing just one button. So if you want a particular
+	bassline played along a particular drum sequence, you would place them in
+	the same scene.
+</p>
+
+<p>
+	Ardour specifics are explained in the
+	<a href="@@cue-window-elements">Cue window elements</a> chapter.
+</p>
+
+<h2>Slots and clips</h2>
+
+<p>
+	Cells in a grid are usually called slots. They are a kind of a container
+	that can hold an audio or a MIDI clip. Typically, a clip can be loaded
+	into a slot from a disk by pointing the file selector to it, or loaded
+	from a pre-recorded library of reusable clips, or recorded in place.
+	You will find more information about that in the
+	<a href="@@populating-the-cue-grid">Populating the cue grid</a> chapter.
+</p>
+
+<h2>Launching</h2>
+
+<p>
+	In a non-linear workflow, a clip can be triggered to play in multiple ways.
+	Most of the time it's either pressing a corresponding silicon pad on an
+	external grid controller attached via MIDI, or scrolling the mouse wheel
+	downwards over the slot that contains the clip, or just clicking a 'Play'
+	button next to clip's name.
+</p>
+
+<p>
+	Usually you can configure a slot to respond to some ways to trigger clip
+	playback and ignore others. We'll talk about it in the
+	<a href="@@clip-launch-options">Clip Launch Options</a> chapter.
+</p>
+
+<h2>Follow actions</h2>
+
+<p>
+	A clip can play in a loop until you stop it directly, or it can play
+	a user-defined amoutn of time and the trigger another clip in the track.
+	Say, you start a composition with one rhythmic pattern played four times
+	and you want the next rhythmic patterns to play eight times, then move
+	to a third one.
+</p>
+
+<p>
+	This is typically achieved through so called follow actions. In an example
+	above, for the first clip (or, rather, slot) you can set a follow count
+	(4 times), and use the follow action usually called "Next". This will get
+	the clip in that first slot to play 4 times then trigger the playback of
+	a clip in the second slot.
+</p>
+
+<p>
+	Every application has its own set of follow actions. Most common ones are
+	repeating the clip indefinitely, triggering the previous/next slot,
+	or jumping to a slot in a particular scene.
+</p>
+
+<p>
+	You can read more about follow actions in Ardour
+	<a href="@@clip-follow-actions">here</a>.
+</p>
+
+<h2>Musical time and stretching</h2>
+
+<p>
+	In a non-linear workflow, all work is happening in musical time: both audio
+	and MIDI clips are measured in bars and beats.
+</p>
+
+<p>
+	By default, an application that supports a non-linear workflow will attempt
+	to estimate beats per minute in an audio clip and then stretch or squeeze
+	the clip so that it would match the bpm of the session and wrap neatly around
+	bars. That way, a clip that originally has a different tempo that the one in
+	the session would stay in sync with other clips.
+</p>
+
+<p>
+	Stretch options in Ardour are explained
+	<a href="@@clip-stretch-options">here</a>.
+</p>

include/playing-back-the-cues.html

@@ -0,0 +1,13 @@
+<h2>How To Play Back Individual Slots</h2>
+
+<p>By clicking play button. FIXME</p>
+
+<p>By scrolling the mouse wheel. FIXME</p>
+
+<p>Stopping the slot playback. FIXME</p>
+
+<h2>How To Play Back An Entire Cue</h2>
+
+<p>Launching a cue. FIXME</p>
+
+<p>Stopping a cue. FIXME</p>

include/populating-the-cue-grid.html

@@ -0,0 +1,19 @@
+<h2>Adding tracks</h2>
+
+<h2>Loading clips to slots</h2>
+
+<p>Via right-click menu. FIXME</p>
+
+<p>Via Clip Properties box. FIXME</p>
+
+<p>From the Clips library. FIXME</p>
+
+<p>By bouncing from the timeline. FIXME</p>
+
+<h2>Setting Clip Properties</h2>
+
+<p>General settings. FIXME</p>
+
+<p>Audio-specific settings. FIXME</p>
+
+<p>MIDI-specific settings. FIXME</p>

master-doc.txt

@@ -1493,6 +1493,84 @@ include: managing-custom-clips.html
 part: chapter
 ---
 
+---
+title: Cue
+link: cue
+part: part
+---
+
+---
+title: Non-Linear Workflow Principles
+link: non-linear-workflow-principles
+include: non-linear-workflow-principles.html
+uri: cue/non-linear-workflow-principles
+part: chapter
+---
+
+---
+title: Cue window elements
+link: cue-window-elements
+include: cue-window-elements.html
+uri: cue/cue-window-elements
+part: chapter
+---
+
+---
+title: Setting Up Cues
+link: setting-up-cues
+include: setting-up-cues.html
+uri: cue/setting-up-cues
+part: chapter
+---
+
+---
+title: Populating the Cue Grid
+link: populating-the-cue-grid
+include: populating-the-cue-grid.html
+uri: cue/setting-up-cues/populating-the-cue-grid
+part: subchapter
+---
+
+---
+title: Playing Back the Cues
+link: playing-back-the-cues
+include: playing-back-the-cues.html
+uri: cue/setting-up-cues/playing-back-the-cues
+part: subchapter
+---
+
+---
+title: Setting Up Launch Options
+link: clip-launch-options
+include: clip-launch-options.html
+uri: cue/setting-up-cues/clip-launch-options
+part: subchapter
+---
+
+---
+title: Setting Up Follow Actions
+link: clip-follow-actions
+include: clip-follow-actions.html
+uri: cue/setting-up-cues/clip-follow-actions
+part: subchapter
+---
+
+---
+title: Setting Up Stretch Options
+link: clip-stretch-options
+include: clip-stretch-options.html
+uri: cue/setting-up-cues/clip-stretch-options
+part: subchapter
+---
+
+---
+title: Mixing Linear and Non-Linear Workflows
+link: mixing-linear-nonlinear-workflows
+include: mixing-linear-nonlinear-workflows.html
+uri: cue/mixing-linear-nonlinear-workflows
+part: chapter
+---
+
 ---
 title: Arranging
 part: part