manual/include/clip-stretch-options.html

<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>
  <li><dfn>Mixed</dfn> is for anything in between</li>
</ul>

<h2>BPM</h2>

<p>
	This is where the estimated tempo is displayed. It can also
	be progressively divided or mutiplied by two.
</p>

<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>
	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>

<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>