Document the master speed.

diff --git a/futatabi.rst b/futatabi.rst
index e17d73787cfb051243389e17df2f5ca17d18767e..e8370ae4a38359fe92fe0a63bbbd56f949b897d7 100644 (file)
--- a/futatabi.rst
+++ b/futatabi.rst
@@ -121,6 +121,53 @@ visible in the top screen and go out live over the network to Nageru.
 Controlling the playback speed
 ''''''''''''''''''''''''''''''
 
+Most slow motion is at 0.5x speed (or equivalently, “2x slow motion”),
+and when you queue a clip from the clip list to the playlist, this is what
+it gets by default. However, you are free to change it to whatever you wish,
+like 0.333x, 0.25x (both are fairly common “super slow” standards) or even 1.0x.
+As long as you are reasonably close to a rational number with low integers
+(e.g. 1/2, 2/3, etc.), Futatabi will do its best to try to reuse as many
+original frames as possible, keeping quality and performance at their highest
+levels.
+
+In addition to the per-clip speed, it is often interesting to change the
+speed *during* playback of a clip. For instance, you could keep normal
+slow motion (0.5x) speed in the run-up to a shot, ramp down to 0.1x to get
+a good look at the actual shot, and then ramp back once it's done.
+When done right and not overused, this can create a dramatic effect that's
+hard to replicate using constant slowdown.
+
+To this effect, Futatabi supports a *master speed* control. It is found at
+the bottom of the window (or you can :ref:`control it using a MIDI device <midi-futatabi>`);
+note that by default, it is locked at 100% until you click the lock button
+to unlock it. (This is particularly important when using a MIDI device, where it is very easy
+to touch a slider inadvertedly, and very hard to set it back exactly at 100%.)
+The master speed control is multiplied in on top of all other speed factors,
+so if you have e.g. a clip at 0.5x and the master speed is set to 70%,
+the clip will effectively play back at 0.35x. The master speed can be set between
+10% and 200%, inclusive.
+
+Note that the master speed control governs the speed of the *output* clock,
+unlike any other speed control in Futatabi. In particular, this means that unlike
+the regular clip speeds, it affects fade times; if fade time is at 0.5 seconds
+and master speed is set to 70%, the fade will take approximately 0.714 seconds
+(0.5 divided by 0.7). It also means that the “remaining time” displays will be
+wrong if master speed is not at 100%. This is because the master speed
+is by nature unpredictable (the user can change it at any time); one cannot
+e.g. delay fades when the master speed is reduced, since turning it back up
+would mean the start of the fade were simply missed. Similarly, it is impossible
+to give a proper estimate of time remaining that takes master speed into account;
+it would be overestimating time significantly, given that the operator is likely
+to turn it back up to 100% again soon.
+
+Finally, note that when changing master speed, the speed is no longer at a
+rational, so most frames will be interpolated frames. If your GPU is not fast
+enough to interpolate every frame (ie., it is reliant on Futatabi's usual
+reuse of original frames), it will drop output frames. Normal behavior will
+resume from the next clip, when the clocks will again go in lockstep (assuming the master
+speed is at 100% at that point). If you're not ramping, or if you're done ramping,
+it's recommended to keep the speed lock on to avoid inadvertedly changing the speed.
+
 .. _coop:
 
 Working with your producer