Package MSP

stretch~

Ztx-based pitch/time modification of an audio buffer

Description

Use the stretch~ object to perform destructive pitch and time modifications to the contents of a buffer~. object.

Arguments

buffer-name[symbol]

optional

Specifies the name of the buffer which contains the result of destructive pitch/time modifications.

Attributes

basictuning[int]

Sets a tuning standard based on a frequency for A for pitch-correction operations (440 = default, range is 400 - 500)

followglobaltempo[int]

When followgobaltempo is enabled, stretch~ will calculate the current tempo out of the ratio between originaltempo and the current global tempo.

formant[float]: 1.

The word formant , followed by floating point value, sets the amount of formant scaling when pitch shifting is performed.

formantcorrection[int]

The word formantcorrection , followed by a zero or one, disables/enables formant correction when pitch correction is performed.

mode[int]

Sets the timestretching mode to be used. Each mode is optimized for handling different kinds of audio material
Possible values:

'basic' ( Default mode of operation )
This is the default mode of operation.

'monophonic' ( Monophonic sources (voice, flute) )
This mode is best for monophonic instruments (e.g. solo voice, flute, etc.)

'rhythmic' ( Optimizes for transient preservation )
This mode is for time stretched percussion. It provides optimal transient preservation.

'general' ( Balance spectral integrity with transient preservaton )
This mode balances spectral integrity and transient preservation for general cases.

'polyphonic' ( Polyphonic sources (piano, guitar) )
Polyphonic mode is a better choice for instruments such as piano or guitar.

'pads' ( Emphasize spectral quality over transient preservation )
This mode emphasizes spectral quality over transient preservation.

'extremestretch' ( For stretch ratios greater than 2.0 )
This mode is intended for stretch ratios greater 2.0, a more artistic effect is intended.

'efficient' ( Good CPU performance )
This mode is intended for a good CPU performance/quality tradeoff.

originallength[Time Value]

The original length of the the audio file in beats. Used by followglobaltempo to calculate the speed in relation to the global transport speed. Setting the originallength will calculate the originaltempo .

originaltempo[float]

The original tempo of the the audio file. Used by followglobaltempo to calculate the speed in relation to the global transport speed. Setting the originaltempo will calculate the originallength .

pitchcorrection[int]

The word pitchcorrection , followed by a zero or one, enable/disables the formant-corrected chromatic intonation correction. For more extensive real-time intonation correction, use the retune~ object.

pitchshift[float]: 1.

Specifies pitchshift as a factor of the original pitch (i.e. 2.0 = doubling of pitch, .5 = halving of the original pitch, etc.).

pitchshiftcent[int]: 0

Specify pitchshift as positive or negative cent values (i.e. 100 = semitone up, -1200 = octave down). Cents may be specified as ints or floats.

progress_enable[int]: 1

Enable/disable progress bar display when calculating pitch/time shifting.

quality[symbol]

Choose the quality for the timestretching output.
Possible values:

'basic'
'good'
'better'
'best'

readagain[int]: 1

Process audio from original buffer rather than current buffer when pitch or timestretching is done

slurtime[float]: 0.

Set the time it takes for the correction to reach the full correction amount. Typically, notes are a bit unstable at the beginning, because the attack phase of a sound has a higher amount of noise, and because singers gradually adjust their tuning after the onset of the note. The slur time makes the pitch correction sound natural because it models this effect. Higher values will yield a slower adaptation time and it will take longer for the correction to produce the corrected pitch. However, longer slur times will also preserve vibrato better.

stretch[float]: 0.

Set the timestretching as a factor in relation to the length of the current buffer (e.g. 2.0 = double the length, .5 = half the length, etc.).

Common Box Attributes

Below is a list of attributes shared by all objects. If you want to change one of these attributes for an object based on the object box, you need to place the word sendbox in front of the attribute name, or use the object's Inspector.

annotation[symbol]

Sets the text that will be displayed in the Clue window when the user moves the mouse over the object.

background[int]: 0

Adds or removes the object from the patcher's background layer. background 1 adds the object to the background layer, background 0 removes it. Objects in the background layer are shown behind all objects in the default foreground layer.

color[4 floats]

Sets the color for the object box outline.

fontface[int]

Sets the type style used by the object. The options are:

plain
bold
italic
bold italic Possible values:

0 = 'regular'
1 = 'bold'
2 = 'italic'
3 = 'bold italic'

fontname[symbol]

Sets the object's font.

fontsize[float]

Sets the object's font size (in points). Possible values:

'8'
'9'
'10'
'11'
'12'
'13'
'14'
'16'
'18'
'20'
'24'
'30'
'36'
'48'
'64'
'72'

hidden[int]: 0

Toggles whether an object is hidden when the patcher is locked.

hint[symbol]

Sets the text that will be displayed in as a pop-up hint when the user moves the mouse over the object in a locked patcher.

ignoreclick[int]: 0

Toggles whether an object ignores mouse clicks in a locked patcher.

jspainterfile[symbol]

You can override the default appearance of a user interface object by assigning a JavaScript file with code for painting the object. The file must be in the search path.

patching_rect[4 floats]: 0. 0. 100. 0.

Sets the position and size of the object in the patcher window.

position[2 floats]

write-only

Sets the object's x and y position in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its size unchanged.

presentation[int]: 0

Sets whether an object belongs to the patcher's presentation.

presentation_rect[4 floats]: 0. 0. 0. 0.

Sets the x and y position and width and height of the object in the patcher's presentation, leaving its patching position unchanged.

rect[4 floats]

write-only

Sets the x and y position and width and height of the object in both patching and presentation modes (if the object belongs to its patcher's presentation).

size[2 floats]

write-only

Sets the object's width and height in both patching and presentation modes (if the object belongs to its patcher's presentation), leaving its position unchanged.

textcolor[4 floats]

Sets the color for the object's text in RGBA format.

textjustification[int]

Sets the justification for the object's text. Possible values:

0 = 'left'
1 = 'center'
2 = 'right'

varname[symbol]

Sets the patcher's scripting name, which can be used to address the object by name in pattr, scripting messages to thispatcher, and the js object.

Messages

bang

bang message starts processing to modify the contents of the currently referenced buffer.

apply

same as bang

cancel

Cancels the currently running operation.

(mouse)

Double-clicking on stretch~ opens a display window where you can view the results of the pitch/time modifications you have made. The contents of the display window are updated when a modification is completed.

dictionary

You can use a dictionary to define more complex stretching and pitch shifting. You define a point in time (sourcetime, sourcetimesample or sourcetimebbu) and define where this point should be transformed to (desttime, desttimesample or desttimebbu). For expample the dictionary below will

create marker01 which will stretch the file so that the audio at 500 ms will be on the first bar, will pitch-shift the audio down by 100 cents until the next marker
create marker02 which will stretch so the material at 1000 ms will be at 1.2.0 bbu, will pitch-shift the audio by a factor of 1.1 up until the next marker
create marker03 which will stretch the whole sample (“end”) to be twice as long


					{ "marker01" : { "sourcetime" : "500", "desttimebbu" : "1.0.0", "pitchshiftcent" : -100 } , "marker02" : { "sourcetime" : 1000, "desttime" : 1.2.0, "pitchshift" : 1.1 } , "marker03" : { "sourcetime" : “end”, "desttime" : “*2”, } }

Arguments:

dictionary-name [symbol]

set

The word set , followed by the name of an audio buffer, sets the name of the audio buffer referenced by the stretch~ object.