Finish Playtime playback section

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

@@ -6,7 +6,9 @@ Within the app, you can use the following keyboard shortcuts.
 |Shortcut |Purpose
 
 |kbd:[Esc]
-|Hides the app window.
+|[[hide]] Hides the app window.
+
+Hiding the window doesn't completely unload the app, it really just hides the window.
 
 |kbd:[F]
 |Toggles full-screen mode.

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

@@ -5,10 +5,9 @@ It primarily provides general functions, such as window controls, access to sett
 
 image::generated/screenshots/elements/area/window-title-bar-0.png[]
 
-include::partial$generated/elements/title-bar/hide-window.adoc[]
+include::partial$generated/elements/title-bar/close-window.adoc[]
 
-Hiding the window doesn't completely unload the app, it really just hides it.
-In order to close it for good, use xref:helgobox::plug-in/user-interface/menu-bar.adoc#close-app[].
+This has the same effect as pressing xref:helgobox::plug-in/user-interface/menu-bar.adoc#close-app[].
 
 include::partial$generated/elements/title-bar/full-screen.adoc[]
 

doc/helgobox/modules/ROOT/partials/generated/elements/title-bar/close-window.adoc

@@ -0,0 +1,9 @@
+ifdef::pdf-theme[[[title-bar-close-window,Close window]]]
+ifndef::pdf-theme[[[title-bar-close-window,Close window image:generated/screenshots/elements/title-bar/close-window.png[width=50]]]]
+== Close window
+
+image:generated/screenshots/elements/title-bar/close-window.png[Close window, role="related thumb right"]
+
+Closes the app window.
+
+

doc/playtime/modules/ROOT/nav.adoc

@@ -43,5 +43,7 @@
 ** xref:user-interface/keyboard-shortcuts.adoc[]
 * xref:further-concepts.adoc[]
 ** xref:further-concepts/general.adoc[]
+* xref:advanced-usage-scenarios.adoc[]
+** xref:advanced-usage-scenarios/self-playing.adoc[]
 * xref:reaper-actions.adoc[]
 * xref:configuration-files.adoc[]

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

@@ -0,0 +1,5 @@
+= Advanced usage scenarios
+
+In xref:usage.adoc[], we have learned how Playtime is typically used. But it doesn't end there! Playtime is designed in a quite open-ended way, which makes it versatile enough to use it in plenty of other scenarios.
+
+This section explores some of the more advanced usage scenarios.

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

@@ -0,0 +1,3 @@
+= Playtime playing itself
+
+TODO

doc/playtime/modules/ROOT/pages/key-concepts.adoc

@@ -147,9 +147,21 @@ Because of its importance, it's mentioned here already as a key concept.
 
 The _start timing_ decides when a clip actually starts to be played back, after you have triggered its playback.
 
+We distinguish between _quantized_ start timings and _immediate_ start timing.
+
+Quantized start timing::
 By default, the start timing is *1 bar*, which means that the clip will start playing at the beginning of the next bar.
-This is what makes everything in-sync You can change that to arbitrary <<quantization, quantizations>>, such as *2 quarter notes* or *3 bars*.
-Alternatively,
+This is what makes everything in-sync. You can change that to arbitrary <<quantization, quantizations>>, such as *2 quarter notes* or *3 bars*.
+
+Immediate start timing::
+Alternatively, you can use the start timing *Immediately*, which makes the clip start playing instantly when you trigger it. Of course, that means *you* are now in charge to get the timing right.
+
+You can set the start timing for xref:user-interface/inspector/matrix/playback.adoc#inspector-matrix-start-timing[the complete matrix] and override it on xref:user-interface/inspector/column/playback.adoc#inspector-column-start-timing[column] or xref:user-interface/inspector/clip.adoc#inspector-clip-start-timing[clip] level.
+
+[[clip-stop-timing]]
+== Clip stop timing
+
+The clip _stop timing_ is  very similar to the <<clip-start-timing>> but determines when the clip actually stops after you have triggered its stop. In most cases, it makes sense to leave it at its default settings xref:user-interface/inspector/clip.adoc#inspector-clip-stop-timing-like-start-timing[].
 
 == Loop vs. one-shot
 
@@ -196,16 +208,24 @@ The bottom number is called (the *4* in 3/4), _denominator_ and shows the type o
 [[in-sync]]
 == In sync
 
-In the context of rhythmical music, _in sync_ means that everything is synchronized and the timing aligns correctly.
-
-When you play <<loop, loops>> in Playtime, you typically want them to be _in sync_ with each other and with all other rhythmical material on the <<timeline, reference timeline>>.
+In the context of rhythmical music, _in sync_ means that everything is synchronized and the timing aligns correctly. When you play <<loop, loops>> in Playtime, you typically want them to be _in sync_ with each other and with all other rhythmical material on the <<timeline, reference timeline>>.
 
 To achieve this synchronization, the following conditions must be met:
 
-. The start and end positions of the <<clip>> must align *precisely* with a musical <<beat>> in the <<source>>.
-. <<Clip>> playback must start exactly on a beat of the <<timeline>>.
+[[in-sync-correct-section]] Correct start and end position::
+The start and end positions of the <<clip>> must align *precisely* with a musical <<beat>> in the <<source>>.
+
+[[in-sync-beat-aligned-playback]] Beat-aligned start of playback::
+<<clip>> playback must start exactly on a beat of the <<timeline>>.
+
+[[in-sync-playback-with-same-tempo]] Playback with the same tempo::
+The <<clip,clips>> must be played back in the same tempo (or a multiple of it).
+
+When using Playtime's default settings, all conditions are automatically met:
 
-When using Playtime's default settings, both conditions are automatically met.
+* <<in-sync-playback-with-same-tempo>> is met because by default, Playtime starts and stops a clip _recording_ quantized to a 1-bar grid (see xref:clip-start-timing[]).
+* <<in-sync-beat-aligned-playback>> is met because by default, Playtime starts and stops clip _playback_ quantized to a 1-bar grid (see xref:clip-start-timing[]).
+* <<in-sync-playback-with-same-tempo>> is met because by default, Playtime adjusts the tempo of a clip to the current project tempo (see xref:user-interface/inspector/clip.adoc#inspector-clip-sync-to-project-tempo[]).
 
 [TIP]
 ====
@@ -215,7 +235,7 @@ Concerning the first condition:
 * If the start point is located between beats or the length falls between bars, the loop will be _out of sync_.
 * By selecting a <<quantization,quantized>> start/stop timing, such as "1 bar", Playtime ensures that your loop's start point and length are perfectly beat-aligned with sample precision!
 * If you choose immediate start/stop timing, it's your responsibility to ensure that the start point and length are musically appropriate.
-However, achieving perfect timing with a button or foot pedal press is close to impossible.
+Achieving perfect timing with a button or foot pedal press is close to impossible.
 ====
 
 [[quantization]]

doc/playtime/modules/ROOT/pages/reaper-actions.adoc

@@ -4,6 +4,7 @@ Playtime provides the following REAPER actions in addition to the xref:helgobox:
 
 [#show-hide-playtime]
 Helgobox/Playtime: Show/hide Playtime::
-If there's no Helgobox instance with a Playtime matrix in the current project, this action adds one and shows the matrix. If there is one already, it shows or hides the app.
+If there's no Helgobox instance with a Playtime matrix in the current project, this action adds one and shows the matrix. If there is one already, it shows or hides the app window. This doesn't completely unload the app, it really just hides the window.
+
 +
 The default shortcut is kbd:[Shift+Cmd/Ctrl+P].

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

@@ -1 +1,3 @@
-= Adjust clips
+= Adjust clips
+
+Now that you know how to create play clips, you might want to experiment a bit with

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

@@ -22,7 +22,7 @@ This didn't just create a new column, it also created a new REAPER track with th
 Use matrix templates::
 Instead of creating the column manually, you could also have started with a template by pressing the xref:user-interface/matrix-area.adoc#matrix-mixed-template-button[], for example.
 
-Importing existing tracks::
+Import existing tracks::
 Maybe you have existing tracks already that you want to use as xref:key-concepts.adoc#column-track[column tracks]. In that case, select them, right-click xref:user-interface/matrix-area.adoc#matrix-cell-settings[] and choose xref:user-interface/matrix-menu.adoc#matrix-insert-column-for-each-selected-track[].
 ****
 
@@ -185,5 +185,5 @@ Maybe you already have a MIDI clip and want to slowly add some notes by playing
 . Play some MIDI notes on your music keyboard. They will be recorded into the playing clip. You will hear them on the next repetition.
 . When you are done, press the same button again.
 
-Many of the above aspects can be combined, which gives you a maximum of flexibility.
+TIP: Many of the above aspects can be combined, which gives you a maximum of flexibility.
 ****

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

@@ -1 +1,124 @@
-= Play clips
+= Play clips
+
+As soon as you have some clips in the matrix, you can play them!
+
+Unlike items on the REAPER timeline, you can start and stop clips totally freely. There are no rules, which makes Playtime very suitable for improvisation.
+
+== Playing clips using the app
+
+The obvious way to play a clip is to use your mouse: Press the xref:user-interface/matrix-area.adoc#slot-cell-trigger[] button of its containing xref:key-concepts.adoc#slot[]:
+
+* If Playtime's transport was stopped before you pressed the button (see xref:user-interface/toolbar.adoc#toolbar-start-stop-playback[] button in the toolbar), Playtime and your clip should start playing immediately.
+* If Playtime's transport was playing already, the clip should start playing according to the configured xref:key-concepts.adoc#clip-start-timing[], by default at the next bar.
+
+You can stop the clip by pressing the xref:user-interface/matrix-area.adoc#slot-cell-trigger[same button] again, which now appears as a stop icon. The clip should stop playing according to the configured xref:key-concepts.adoc#clip-stop-timing[].
+
+TIP: You can xref:helgobox::app/user-interface/keyboard-shortcuts.adoc#hide[hide] or xref:helgobox::app/user-interface/title-bar.adoc#title-bar-close-window[close] the app window at any time. This will not affect playback or recording. Playtime also works without its user interface!
+
+== Playing clips using a MIDI keyboard
+
+Playtime allows you to play your clips by pressing keys on your MIDI keyboard:
+
+. Press the xref:user-interface/toolbar.adoc#toolbar-show-hide-midi-triggers[] button. This should reveal small MIDI trigger areas on the right side of each slot cell.
+. Press the MIDI trigger area of the slot that you want to play. It should turn red.
+. Press a key on your MIDI keyboard. Playtime should pick it up. If not, see xref:user-interface/toolbar.adoc#midi-trigger-troubleshooting[].
+. Press the key once. The clip should start playing.
+. Press the key again. The clip should stop.
+
+
+.Variations
+****
+Play as long as you press the key::
+By default, pressing the key toggles between _playing_ and _stopped_. You can change that, for example on column level, by setting xref:user-interface/inspector/column/playback.adoc#inspector-column-trigger-mode[] to xref:user-interface/inspector/column/playback.adoc#inspector-column-trigger-mode-momentary[]. Then pressing the key down will start playback and releasing it will stop playback. This goes very well with xref:key-concepts.adoc#clip-start-timing[] xref:user-interface/inspector/clip.adoc#inspector-clip-start-timing-immediately[].
+
+Restart when pressing the key again::
+Another xref:user-interface/inspector/column/playback.adoc#inspector-column-trigger-mode[] is xref:user-interface/inspector/column/playback.adoc#inspector-column-trigger-mode-retrigger[]: Tapping the key once will start playback and tapping it again will trigger a restart.
+
+Play with different velocities::
+Maybe you want to play the clip with a lower volume when hitting the key softly and with a higher volume when hitting it hard. You can achieve this and fine-tune the effect by adjusting xref:user-interface/inspector/matrix/playback.adoc#inspector-matrix-velocity-sensitivity[]. This is of course also adjustable on xref:user-interface/inspector/column/playback.adoc#inspector-column-velocity-sensitivity[column] and xref:user-interface/inspector/clip.adoc#inspector-clip-velocity-sensitivity[clip] level.
+****
+
+
+.Suitable for finger drumming!
+[NOTE]
+====
+Triggering clips via MIDI happens in real-time! As with any other instrument plug-in that you use in REAPER, the latency depends on the block size set in REAPER.
+
+So if you use xref:key-concepts.adoc#clip-start-timing[] xref:user-interface/inspector/clip.adoc#inspector-clip-start-timing-immediately[] and set the block size in REAPER menu:Options[Settings... > Device] low enough (e.g. 256 samples), you will not perceive any delay between pressing the key and hearing the sound.
+====
+
+.Is Playtime a sampler?
+[TIP]
+====
+When playing Playtime via MIDI, it helps to look at it as a kind of sampler. But instead of playing single tones, you usually trigger complete musical _phrases_, either as MIDI or audio.
+
+You are basically working on a higher level. Each of the triggered phrases in turn can trigger samplers or synthesizers ... or even xref:advanced-usage-scenarios/self-playing.adoc[Playtime itself].
+====
+
+== Playing and stopping multiple clips
+
+You can play all clips in a row at once by pressing the xref:user-interface/matrix-area.adoc#row-cell-play-scene[] button at the very left.
+
+You can permanently stop all clips in a column at once by pressing the xref:user-interface/matrix-area.adoc#column-cell-stop[] button in the xref:user-interface/matrix-area.adoc#column-cell[] at the top of the column. Double-clicking this button stops the clips abruptly.
+
+You can permanently stop all clips in the complete matrix at once by pressing the xref:user-interface/matrix-area.adoc#matrix-cell-stop[] button in the xref:user-interface/matrix-area.adoc#matrix-cell[] at the top-left of the matrix area. Double-clicking this button stops the clips abruptly.
+
+== Playing multiple clips
+
+The fun starts when playing multiple clips simultaneously.
+
+=== Columns in exclusive mode
+
+By default, playback within one column is limited to just one slot. We call this xref:user-interface/inspector/column/playback.adoc#inspector-column-exclusive-mode[], because one slot has the exclusive right of playing.
+
+.Exclusive mode
+====
+Let's say you have clip A in the first column cell 1 and clip B in the second column cell.
+
+. Trigger clip A and wait until it started playing
+. Now, trigger clip B
+
+You will see that clip A stops and clip B takes over.
+====
+
+*The consequence is:* If you want to play multiple slots simultaneously, you would need to create a new column. Musically, that makes a lot of sense. It is very common in clip launchers to have one column per instrument. And one instrument can normally only play one phrase at a time. Alternating between those phrases is often exactly what people want.
+
+=== Columns in non-exclusive mode
+
+Playtime is a quite relaxed fellow and allows you to opt out of the exclusive mode. The easiest way to do this is to press the xref:user-interface/matrix-area.adoc#column-cell-exclusive-mode[] button in the xref:user-interface/matrix-area.adoc#column-cell[].
+
+After disabling exclusive mode, you can play multiple clips within that column, as your heart desires.
+
+=== Playing in sync
+
+Usually when playing multiple clips within a clip launcher, one expects those clips to play perfectly xref:key-concepts.adoc#in-sync[in sync] with each other. This "perfectly in sync" is by default given in Playtime, but it all depends on how each of the clips is configured.
+
+If you have messed with xref:key-concepts.adoc#clip-start-timing[], xref:user-interface/inspector/clip.adoc#inspector-clip-start-position[], xref:user-interface/inspector/clip.adoc#inspector-clip-length[] or xref:user-interface/inspector/clip.adoc#inspector-clip-sync-to-project-tempo[], your clips might get out of sync. If this happens, and you don't know why, revisit xref:key-concepts.adoc#in-sync[] to deepen your understanding.
+
+== Starting and stopping Playtime playback
+
+Playtime's playback can be started and stopped xref:helgobox::key-concepts.adoc#instance[instance-wide], using either the xref:user-interface/toolbar.adoc#toolbar-start-stop-playback[] button in the xref:user-interface/toolbar.adoc#toolbar-transport-section[] or the kbd:[Space] key.
+
+Stopping Playtime playback doesn't just stop all playing clips, it also memorizes them, so that next time you start playback, they will play again. We call those memorized clips _ignited_ clips. Ignited clips have a circle around their xref:user-interface/matrix-area.adoc#slot-cell-trigger[play button].
+
+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.
+
+== Playing together with the REAPER arrangement
+
+=== Starting playback within REAPER
+
+Maybe you already have some items on the REAPER timeline that you want to improvise over using Playtime. All you need to do for this is to start playback within REAPER:
+
+. Click somewhere into the REAPER main window in order to switch focus to REAPER.
+. Press kbd:[Space] to start REAPER playback.
+
+Playtime will now play synchronized to the arrangement. Changing the REAPER play cursor position will automatically retrigger Playtime's clip so that they stay in sync.
+
+=== Full transport synchronization
+
+Maybe you would like to always play together with the REAPER arrangement, even if you start playback within Playtime:
+
+. Set xref:user-interface/inspector/matrix/playback.adoc#inspector-matrix-transport-sync[] in the xref:user-interface/inspector/matrix.adoc[] to *Full*
+. Press kbd:[Space] within Playtime.
+
+REAPER should start playing as well.