X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=include%2Fclip-stretch-options.html;h=1b461a853639c185770d30150ce0016332b980a1;hb=71afa472a61c8d63fb8932c06b3ab83bf3aecbda;hp=04753b9537d5fb71958418ea748d0778254c392f;hpb=5b86e5a46b9c22c955753f1f24ae611bec7ae9b1;p=ardour-manual

diff --git a/include/clip-stretch-options.html b/include/clip-stretch-options.html
index 04753b9..1b461a8 100644
--- a/include/clip-stretch-options.html
+++ b/include/clip-stretch-options.html
@@ -1,11 +1,32 @@
-<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>
+<h2>Stretching</h2>
+
+<p>
+	When you load an audio clip into a trigger slot, Ardour applies some
+	heuristics to estimate its temo in beats per minute. Unless a metadata
+	in the file source provides information,
+	<a href="https://github.com/breakfastquay/minibpm">minibpm</a> is used
+	to analyze and detect the file's BPM.
+</p>
+
+<p>
+	After tempo is estimated, the clip is time-stretched to match the
+	session's tempo map. This means that should session's tempo change over
+	time (in either ramped or constant mode), all audio clips will be
+	re-stretched to accomodate for that.
+</p>
+
+<p>
+	Disabling stretching when original clip's tempo doesn't match that of the
+	session will most of the times make the clip audibly go out of sync with
+	the beat.
+</p>
 
 <p>Stretch modes:</p>
 
+<p>
+	Once stretching is enabled, you have several options how to apply it:
+</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>
@@ -14,26 +35,35 @@ TEMPO, SO TEMPO RAMPS WILL WORK FOR CLIPS</p>
 
 <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
+<p>
+	This is where the estimated tempo is displayed. It can also
+	be progressively divided or mutiplied by two.
+</p>
 
-<h2>Length in Bars</h2>
+<p>
+	Supposing, session's tempo is currently 120bpm and original clip's tempo
+	is 90bpm. Stretching the clip to match session's tempo will make it sound
+	faster that it originally is.
+</p>
 
-<p>It’s a hint to help you counting. FIXME</p>
+<p>
+	If the estimated clip's tempo is divided by 2, stretching the resulted
+	45bpm back to 120bpm will make the clip sound faster. Vice versa,
+	multiplying the original clip's tempo by 2 and then stretching it down
+	from 180bpm to 120bpm will make the clip sound slower than it originally is.
+</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>
+<h2>Clip Length</h2>
 
-<p>5) if the user changes the beat-length, then the tempo is recalculated for use during stretching</p>
+<p>
+	This control allows adjusting the estimated tempo in a finer manner,
+	by changing the amount of beats it takes to play the clip in the selected
+	trigger slot. The change is immediately displayed in the BPM field above.
+</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>
+<h2>Length in Bars</h2>
 
-<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>
\ No newline at end of file
+<p>
+	This is an estimate of the clip's length as measured in bars for two
+	popular time signatures: 4/4 and 3/4.
+</p>