Finish Playtime basic usage docs

doc/helgobox/modules/ROOT/pages/app/user-interface/general.adoc

@@ -2,7 +2,8 @@
 
 This page describes the basic usage of common user interface elements in the Helgobox app.
 
-== Drag fields
+[[drag-field]]
+== Drag field
 
 image::playtime::generated/screenshots/elements/toolbar/tempo.png[]
 
@@ -15,7 +16,7 @@ include::partial$app/user-interface/interactions/text-entry.adoc[]
 include::partial$app/user-interface/interactions/reset-to-default.adoc[]
 include::partial$app/user-interface/interactions/fine-adjustment.adoc[]
 
-== Knobs
+== Knob
 
 image::playtime::generated/screenshots/elements/toolbar/play-rate.png[]
 
@@ -28,7 +29,7 @@ include::partial$app/user-interface/interactions/text-entry.adoc[]
 include::partial$app/user-interface/interactions/reset-to-default.adoc[]
 include::partial$app/user-interface/interactions/fine-adjustment.adoc[]
 
-== Sliders
+== Slider
 
 image::playtime::generated/screenshots/elements/track-panel/volume.png[]
 
@@ -39,7 +40,7 @@ include::partial$app/user-interface/interactions/mouse-wheel-scrolling.adoc[]
 include::partial$app/user-interface/interactions/touchpad-panning.adoc[]
 include::partial$app/user-interface/interactions/reset-to-default.adoc[]
 
-== Search lists
+== Search list
 
 image::playtime::generated/screenshots/main/sequences.png[]
 

doc/playtime-clip-engine.adoc

@@ -4,6 +4,14 @@
 
 == Usage
 
+[IMPORTANT]
+====
+**This document is outdated!** The Clip Engine has finally (November 2024) culminated in the final product link:https://www.helgoboss.org/projects/playtime[Playtime 2], which contains both GUI and engine.
+
+The document is kept for historical purposes. Most of the mentioned engine features made it into the final product, but not all. There are also new ones.
+====
+
+
 This section describes how to use the Clip Engine without the Playtime App.
 
 [NOTE]
@@ -17,7 +25,7 @@ For more info, watch the link:https://youtu.be/6iEMKUcwzMs[Clip Engine introduct
 
 [WARNING]
 ====
-At this point, the Clip Engine is in early alpha stage.
+At this point (May 2022), the Clip Engine is in early alpha stage.
 I can't guarantee that projects or presets that you save with the current version can be loaded in future versions of the Clip Engine!
 
 The current version is intended for alpha testing and experimentation, *not* for live usage or building your dream setup.
@@ -295,7 +303,7 @@ Not very polished yet.
 * It's possible to adjust the volume of a clip, not just the volume of column tracks.
 * Adjusting the volume of MIDI clips modifies the velocity.
 
-=== Non-exclusive columnss
+=== Non-exclusive columns
 
 * If requested, a column can play multiple clips simultaneously.
 

doc/playtime/modules/ROOT/nav.adoc

@@ -5,6 +5,7 @@
 ** xref:usage/prepare.adoc[]
 ** xref:usage/create.adoc[]
 ** xref:usage/play.adoc[]
+** xref:usage/grid-controllers.adoc[]
 ** xref:usage/adjust.adoc[]
 ** xref:usage/structure.adoc[]
 ** xref:usage/arrangement.adoc[]
@@ -44,6 +45,10 @@
 * xref:further-concepts.adoc[]
 ** xref:further-concepts/general.adoc[]
 * xref:advanced-usage-scenarios.adoc[]
+** xref:advanced-usage-scenarios/record-performance-as-audio.adoc[]
+** xref:advanced-usage-scenarios/control-with-items.adoc[]
 ** xref:advanced-usage-scenarios/self-playing.adoc[]
+** xref:advanced-usage-scenarios/multiple-instances.adoc[]
 * xref:reaper-actions.adoc[]
+* xref:realearn-targets.adoc[]
 * xref:configuration-files.adoc[]

doc/playtime/modules/ROOT/pages/advanced-usage-scenarios/control-with-items.adoc

@@ -0,0 +1,3 @@
+= Control Playtime with items
+
+TODO

doc/playtime/modules/ROOT/pages/advanced-usage-scenarios/multiple-instances.adoc

@@ -0,0 +1,3 @@
+= Control Playtime with items
+
+TODO

doc/playtime/modules/ROOT/pages/advanced-usage-scenarios/record-performance-as-audio.adoc

@@ -0,0 +1,3 @@
+= Record performance as multi-track audio
+
+TODO

doc/playtime/modules/ROOT/pages/advanced-usage-scenarios/self-playing.adoc

@@ -1,3 +1,3 @@
 = Playtime playing itself
 
-TODO
+TODO Also called "Meta clips" ... maybe a better name?

doc/playtime/modules/ROOT/pages/realearn-targets.adoc

@@ -0,0 +1,7 @@
+= ReaLearn targets
+
+xref:realearn::introduction.adoc[ReaLearn] offers a bunch of xref:realearn::key-concepts.adoc#target[targets] specific to Playtime. Most of them even support xref:realearn::key-concepts.adoc#feedback[], to power LEDs or displays. That gives you the power to create highly customized controller integrations for Playtime!
+
+To get an impression of that power, you just need to look at Playtime's xref:usage/grid-controllers.adoc[support for grid controllers]. This support is not hard-coded into Playtime. It is implemented solely in the form of xref:realearn::further-concepts/compartment.adoc#compartment-preset[ReaLearn compartment presets].
+
+All targets are described xref:realearn::targets/playtime.adoc[here].

doc/playtime/modules/ROOT/pages/usage.adoc

@@ -7,6 +7,7 @@ A typical Playtime usage scenario, from beginning to end, looks like this:
 . xref:usage/prepare.adoc[]
 . xref:usage/create.adoc[]
 . xref:usage/play.adoc[]
+. xref:usage/grid-controllers.adoc[]
 . xref:usage/adjust.adoc[]
 . xref:usage/structure.adoc[]
 . xref:usage/arrangement.adoc[]

doc/playtime/modules/ROOT/pages/usage/adjust.adoc

@@ -1,3 +1,31 @@
 = Adjust clips
 
-Now that you know how to create play clips, you might want to experiment a bit with
+Now that you know how to create and play clips, you might want change them a bit.
+
+== Editing the clip source
+
+If you are dealing with MIDI clips, you can easily edit the clip xref:key-concepts.adoc#source[]:
+
+. Double-click the xref:user-interface/matrix-area.adoc#slot-cell-content[] area of the desired slot. This should open the clip source in REAPER's MIDI editor.
+. Make changes in the MIDI editor. Any change should be applied right away, if the clip is currently playing.
+. Close the MIDI editor.
+
+Any change can be undone using Playtime's xref:helgobox::app/user-interface/title-bar.adoc#title-bar-undo[] function.
+
+== Adjusting clip properties
+
+Each clip has certain properties in addition to its actual source, which you can adjust.
+
+=== 1. Select the slot
+
+Select the desired slot by clicking the xref:user-interface/matrix-area.adoc#slot-cell-content[] area.
+
+This will show the properties of the clip within that slot in the xref:user-interface/inspector/clip.adoc[] on the right side.
+
+=== 2. Adjust clip properties
+
+Now go ahead and check what properties xref:user-interface/inspector/clip.adoc[are available] in the inspector.
+
+We will just take the example of the *pitch* property. Find the xref:user-interface/inspector/clip.adoc#inspector-clip-pitch[] setting, move your mouse over the number *0.00* semitones and use your mouse wheel or any other xref:helgobox::app/user-interface/general.adoc#drag-field[] interaction to change the pitch. For example, to *12.00* semitones, which corresponds to one octave.
+
+The new pitch will be applied right away or according to the xref:user-interface/inspector/matrix/playback.adoc#inspector-matrix-start-timing[matrix start timing].

doc/playtime/modules/ROOT/pages/usage/arrangement.adoc

@@ -1 +1,84 @@
-= Create an arrangement
+= Create an arrangement
+
+Maybe you want to use Playtime for live improvisation only, in which case the basic usage guide would end here. But chances are, you want to go further than that and turn your Playtime matrix into a proper REAPER arrangement at some point.
+
+This is also important if you xref:advanced-usage-scenarios/control-with-items.adoc[control Playtime with items] and your goal is to include the output of Playtime in the final rendering. Unlike traditional instrument plug-ins, Playtime doesn't participate in rendering! footnote:foot[It's possible that this will be improved in the future by introducing a new mode of operation.] Which is why you first need to turn the output into a conventional REAPER arrangement.
+
+There are two ways of building an arrangement.
+
+== Export matrix content
+
+You can export parts of the matrix to the arrangement directly:
+
+=== 1. Make a time selection (optional)
+
+You can influence the start and length of the export on the timeline by creating a time selection on the REAPER timeline. If you don't do that, the length will correspond to the longest exported clip.
+
+=== 2. Export the desired content
+
+* If you want to export all clips in the matrix, right-click the xref:user-interface/matrix-area.adoc#matrix-cell[] and choose xref:user-interface/matrix-menu.adoc#matrix-export-to-arrangement[].
+* If you want to export all clips in a particular column, right-click the corresponding xref:user-interface/matrix-area.adoc#column-cell[] and choose xref:user-interface/column-menu.adoc#column-export-to-arrangement[].
+* If you want to export all clips in a particular row, right-click the corresponding xref:user-interface/matrix-area.adoc#row-cell[] and choose xref:user-interface/row-menu.adoc#row-export-to-arrangement[].
+* If you want to export the primary clip of a slot, right-click the corresponding xref:user-interface/matrix-area.adoc#slot-cell[] and choose xref:user-interface/slot-menu.adoc#slot-export-primary-clip-to-arrangement[].
+
+.Quickly export different parts of your song
+[TIP]
+====
+Maybe you have named the matrix rows so that they represent different parts of your song, such as _Verse_, _Chorus_, _Bridge_ and _Solo_. Now you want to export those parts like this:
+
+* 2x Verse
+* 1x Chorus
+* 1x Bridge
+* 1x Verse
+* 1x Solo
+* 2x Chorus
+
+Making such an export can be done very quickly just by using keyboard keys:
+
+. Select the _Verse_ row cell
+. Press key kbd:[A] 2 times (the shortcut for exporting the selected cell to the arrangement)
+. Select the _Chorus_ row cell
+. Press key kbd:[A] 1 time
+. ...
+
+This works nicely because after exporting a row, Playtime automatically moves the play cursor or the complete time selection to the right.
+====
+
+== Record and write a sequence
+
+Another way to export an arrangement is to record a Playtime performance and write the result to the arrangement. This is done using Playtime's built-in xref:user-interface/toolbar.adoc#toolbar-matrix-sequencer[]:
+
+=== 1. Start recording a new matrix sequence
+
+Press the xref:user-interface/toolbar.adoc#toolbar-record-matrix-sequence[] button in the xref:user-interface/toolbar.adoc#toolbar-matrix-sequencer[] of the xref:user-interface/toolbar.adoc[].
+
+This will always create a new sequence and never overwrite an existing one, so you can press this anytime.
+
+=== 2. Perform your song within Playtime
+
+Playtime will record all play and stop interactions with your matrix.
+
+=== 3. Stop recording the sequence
+
+Press the xref:user-interface/toolbar.adoc#toolbar-record-matrix-sequence[] button again to stop recording.
+
+=== 4. Play sequence (optional)
+
+If you want, you can play the sequence directly within Playtime by pressing the xref:user-interface/toolbar.adoc#toolbar-play-stop-matrix-sequence[].
+
+=== 5. Write the sequence to the arrangement
+
+If you are satisfied, you can write the sequence to the REAPER tracks by pressing xref:user-interface/toolbar.adoc#toolbar-write-to-arrangement[].
+
+== The translation from clips to items
+
+What happens in both cases it that Playtime translates its xref:key-concepts.adoc#clip[clips] into REAPER items.
+
+Ideally, the items - when played back by REAPER - should sound exactly as the clips in Playtime. If you detect deviations, please open a bug report in the link:https://github.com/helgoboss/helgobox/issues[Helgobox issue tracker].
+
+[TIP]
+====
+The resulting items are played back by REAPER alone. Those are conventional REAPER items, there is no connection to Playtime anymore!
+
+That also means that if you share the REAPER project file with other people, they won't need a Playtime installation to play back the arrangement.
+====

doc/playtime/modules/ROOT/pages/usage/create.adoc

@@ -17,6 +17,8 @@ You should then see a new column named "Column 1" with empty slots that can take
 This didn't just create a new column, it also created a new REAPER track with the same name, the so-called xref:key-concepts.adoc#column-track[]. Playtime will play clips within this column through that track.
 ====
 
+IMPORTANT: Exactly as in REAPER, Playtime columns don't have a type. They can always play both, audio and MIDI clips. The xref:user-interface/track-area.adoc#track-panel-input-type-indicator[] looks a bit as if the column would have a special type, but it really just reflects the input currently selected for recording clips.
+
 .Alternatives
 ****
 Use matrix templates::

doc/playtime/modules/ROOT/pages/usage/grid-controllers.adoc

@@ -0,0 +1,28 @@
+= Use grid controllers
+
+== Introduction
+
+_Grid controllers_ are a unique class of hardware controller designed specifically for clip launching. A well-known example is the Novation Launchpad. These controllers feature a grid of pads with LEDs arranged in rows and columns — exactly like Playtime's xref:key-concepts.adoc#matrix[]!
+
+.Grid controllers are optional!
+TIP: You don't need a grid controller to use Playtime! However, using one adds a tactile dimension to the clip-launching experience, making Playtime feel more like a distinct musical instrument. It’s a fun way to enhance interaction and creativity.
+
+Playtime includes out-of-the-box support for many popular grid controllers. link:https://github.com/helgoboss/helgobox/wiki/Playtime-Controllers[Here] you can find the current list of supported devices.
+
+== Usage
+
+If your controller is on the link:https://github.com/helgoboss/helgobox/wiki/Playtime-Controllers[list of supported devices], here's how you set it up:
+
+. Ensure that Playtime is running and you see its xref:user-interface.adoc[].
+. If the device is already connected to the USB port, **disconnect it** and wait a few seconds!
+. **Connect** the device to the USB port.
+. After waiting for a few seconds, Playtime should show a green success notice at the bottom of the screen.
+
+After that, the device should visually reflect the contents of the Playtime xref:key-concepts.adoc#matrix[] and you should be able to control the matrix with it.
+
+In addition, the device should now appear in the xref:realearn:ROOT:user-interface/settings-dialog.adoc#controllers[ReaLearn controllers] section of the xref:helgobox::app/user-interface/settings-dialog.adoc[]. This is also the place where you can manually set up the device in case it was not auto-detected.
+
+
+== Related videos
+
+video::tkyNCGOVumw[youtube]

doc/playtime/modules/ROOT/pages/usage/play.adoc

@@ -103,6 +103,12 @@ Stopping Playtime playback doesn't just stop all playing clips, it also memorize
 
 Starting Playtime playback will automatically start all _ignited_ clips. If you don't want that, press the xref:user-interface/matrix-area.adoc#matrix-cell-stop[] or xref:user-interface/matrix-area.adoc#column-cell-stop[] button to un-ignite the clips.
 
+.Alternatives
+****
+Conducting a count-in by tapping tempo::
+A neat way to start playback with a new tempo is to stop playback and repeatedly press the xref:user-interface/toolbar.adoc#toolbar-tap-tempo[] button in a "1, 2, 3, 4"-style count-in.
+****
+
 == Playing together with the REAPER arrangement
 
 === Starting playback within REAPER

doc/playtime/modules/ROOT/pages/usage/render.adoc

@@ -1 +1,12 @@
-= Render
+= Render
+
+At the end, you probably want to render/mix-down/export the arrangement xref:usage/arrangement.adoc[created in the previous step] to an audio file.
+
+
+All you need to do is to use REAPER's built-in render functionality as usual:
+
+. Open menu:File[Render...]
+. Change options if desired
+. Press the btn:[Render] button
+
+That's it! Playtime doesn't change anything about the rendering process. In fact, it's not involved anymore at this point.

doc/playtime/modules/ROOT/pages/usage/structure.adoc

@@ -1 +1,41 @@
-= Structure the song
+= Structure the song
+
+Playtime's xref:user-interface/matrix-area.adoc[] suits itself for organizing the clips into a musical structure.
+
+== Rename slots
+
+Renaming a slot is as easy as selecting the xref:user-interface/matrix-area.adoc#slot-cell[] and pressing kbd:[F2], or right-clicking the cell and selecting xref:user-interface/slot-menu.adoc#slot-rename-primary-clip[].
+
+== Add more columns
+
+You can add more columns, for example one column per instrument.
+
+You can rename a column or its corresponding xref:key-concepts.adoc#column-track[] by selecting the xref:user-interface/matrix-area.adoc#column-cell[] and pressing kbd:[F2], or right-clicking the cell and selecting xref:user-interface/column-menu.adoc#column-rename-column-or-track[].
+
+== Drag and drop things
+
+You can freely drag and drop slot contents or other things. Check out the following links to learn more about it:
+
+* xref:user-interface/matrix-area.adoc#column-drag-and-drop[]
+* xref:user-interface/matrix-area.adoc#row-drag-and-drop[]
+* xref:user-interface/matrix-area.adoc#slot-drag-and-drop[]
+
+== Add more rows
+
+You can add more rows if you are running out of vertical space for your clips. Just press the xref:user-interface/matrix-area.adoc#matrix-add-row[] button or right-click a xref:user-interface/matrix-area.adoc#row-cell[] and choose xref:user-interface/row-menu.adoc#row-insert-row-below[].
+
+Renaming works just as with columns.
+
+== Use colors to spice things up
+
+There are two things in a xref:key-concepts.adoc#matrix[] that can get individual colors: Tracks and clips.
+
+In order to change the color of a track, click the xref:user-interface/track-area.adoc#track-panel-label[] to select the track. Then change the color in the xref:user-interface/inspector/track.adoc[] on the right. This sets the color of the REAPER track.
+
+In order to change the color of an individual clip, select the xref:user-interface/matrix-area.adoc#slot-cell[] and change the color in the xref:user-interface/inspector/clip.adoc[] on the right.
+
+== Build scenes
+
+One particular way to make use of rows of the matrix is to consider a row as a xref:key-concepts.adoc#scene[] - a part within a song. By organizing your clips into scenes, the scene column on the left of the matrix basically turns into a playlist for your song, which is very convenient if you want to xref:usage/arrangement.adoc[turn the song into an arrangement].
+
+One function which greatly helps to build scenes (apart from drag-and-drop and copy-and-paste) is xref:user-interface/row-menu.adoc#row-build-scene-from-currently-playing-clips[], which you can access by right-clicking the xref:user-interface/matrix-area.adoc#row-cell-label[] of an empty row.

doc/playtime/modules/ROOT/pages/user-interface/inspector/slot.adoc

@@ -6,4 +6,11 @@ include::partial$generated/elements/inspector/slot/clip-picker.adoc[]
 
 For details about the actual clip, see xref:user-interface/inspector/clip.adoc[].
 
-TIP: Right-clicking one of the clips opens the xref:user-interface/clip-menu.adoc[].
+TIP: Right-clicking one of the clips opens the xref:user-interface/clip-menu.adoc[].
+
+[[clip-drag-and-drop]]
+.Drag-and-drop support
+****
+Move a clip to another slot::
+Drag one clip onto another slot in order to move it there.
+****

doc/playtime/modules/ROOT/pages/user-interface/matrix-area.adoc

@@ -48,6 +48,7 @@ include::partial$generated/elements/column-cell.adoc[]
 
 If you don't see the upper part, check xref:user-interface/settings-dialog.adoc#settings-show-column-numbers[].
 
+[[column-drag-and-drop]]
 .Drag-and-drop support
 ****
 Reorder column::
@@ -76,6 +77,7 @@ TIP: Right-clicking this area opens the xref:user-interface/column-menu.adoc[].
 
 include::partial$generated/elements/row-cell.adoc[]
 
+[[row-drag-and-drop]]
 .Drag-and-drop support
 ****
 Reorder row::