BASS.NET API for the Un4seen BASS Audio LibraryBassFxBASS_FX_TempoCreate Method BASS.NET API for the Un4seen BASS Audio Library
Creates a resampling stream from a decoding channel.

Namespace: Un4seen.Bass.AddOn.Fx
Assembly: Bass.Net (in Bass.Net.dll) Version: 2.4.12.0
Syntax

[DllImportAttribute("bass_fx.dll", CharSet = CharSet.Unicode)]
public static int BASS_FX_TempoCreate(
	int channel,
	BASSFlag flags
)

Parameters

channel
Type: SystemInt32
Stream/music/wma/cd/any other supported add-on format using a decoding channel (use BASS_STREAM_DECODE when creating the channel).
flags
Type: Un4seen.BassBASSFlag
A combination of the following flags (see BASSFlag):
BASS_SAMPLE_LOOPLooped? Note that only complete sample loops are allowed by DirectSound (ie. you can't loop just part of a sample).
BASS_SAMPLE_SOFTWAREForce the sample to not use hardware mixing.
BASS_SAMPLE_3DUse 3D functionality. This is ignored if BASS_DEVICE_3D wasn't specified when calling BASS_Init(Int32, Int32, BASSInit, IntPtr). 3D samples must be mono (use BASS_SAMPLE_MONO).
BASS_SAMPLE_FXRequires DirectX 8 or above: Enable the old implementation of DirectX 8 effects. See the DX8 effect implementations section for details. Use BASS_ChannelSetFX(Int32, BASSFXType, Int32) to add effects to the stream.
BASS_STREAM_AUTOFREEAutomatically free the stream's resources when it has reached the end, or when BASS_ChannelStop(Int32) (or BASS_Stop) is called.
BASS_STREAM_DECODEDecode the sample data, without outputting it. Use BASS_ChannelGetData(Int32, IntPtr, Int32) to retrieve decoded sample data. The BASS_SAMPLE_SOFTWARE, BASS_SAMPLE_3D, BASS_SAMPLE_FX, BASS_STREAM_AUTOFREE and SPEAKER flags can not be used together with this flag.
BASS_SPEAKER_xxxSpeaker assignment flags.
BASS_FX_FREESOURCEFree the source handle as well when the tempo channel is freed.
BASS_FX_TEMPO_ALGO_LINEARUses a linear interpolation mode (simple).
BASS_FX_TEMPO_ALGO_CUBICUses a cubic interpolation mode (recommended, default).
BASS_FX_TEMPO_ALGO_SHANNONUses a 8-tap band-limited Shannon interpolation (complex, but not much better than cubic).

Return Value

Type: Int32
If successful, the tempo stream handle is returned, else 0 is returned. Use BASS_ErrorGetCode to get the error code.
Remarks

Multi-channels are supported.

Use BASS_ChannelSetAttribute(Int32, BASSAttribute, Single)/BASS_ChannelGetAttribute(Int32, BASSAttribute, Single) to get or set the attributes of a tempo stream:

BASS_ATTRIB_TEMPOThe tempo of a channel in percent [-95%...0...+5000%].
BASS_ATTRIB_TEMPO_PITCHThe pitch of a channel in semitones [-60...0...+60].
BASS_ATTRIB_TEMPO_FREQThe sample rate of a channel in Hz (but calculates by the same % as BASS_ATTRIB_TEMPO).
These attributes can either be applied to the tempo channel or the underlying decoding source channel.

ERROR CODEDescription
BASS_ERROR_HANDLEchannel is not valid.
BASS_ERROR_DECODEThe channel is not a decoding channel. Make sure the channel was created using the BASS_STREAM_DECODE or BASS_MUSIC_DECODE flag.
BASS_ERROR_FORMATThe channel's format is not supported. Make sure the channel is either Stereo or Mono.

Tuning the option attributes parameters (see BASS_ChannelSetAttribute(Int32, BASSAttribute, Single)):

The time-stretch algorithm has few parameters that can be tuned to optimize sound quality for certain application. The current default parameters have been chosen by iterative if-then analysis (read: "trial and error") to obtain best subjective sound quality in pop/rock music processing, but in applications processing different kind of sound the default parameter set may result into a sub-optimal result.

  • BASS_ATTRIB_TEMPO_OPTION_USE_AA_FILTER (default = ):

    Use FIR low-pass (anti-alias) filter (gain speed, lose quality)? : =1 / =0.

  • BASS_ATTRIB_TEMPO_OPTION_AA_FILTER_LENGTH (default = 32):

    The FIR low-pass (anti-alias) filter length in taps: between 8 and 128 (should be around %4).

  • BASS_ATTRIB_TEMPO_OPTION_USE_QUICKALGO (default = ):

    Use quicker tempo change algorithm (gain speed, lose quality)? =1 / =0.

  • BASS_ATTRIB_TEMPO_OPTION_SEQUENCE_MS (default = 82):

    This is the default length of a single processing sequence in milliseconds which determines the how the original sound is chopped in the time-stretch algorithm. Larger values mean fewer sequences are used in processing. In principle a larger value sounds better when slowing down the tempo, but worse when increasing the tempo and vice versa.

  • BASS_ATTRIB_TEMPO_OPTION_SEEKWINDOW_MS (default = 14):

    The seeking window default length in milliseconds is for the algorithm that seeks the best possible overlapping location. This determines from how wide a sample "window" the algorithm can use to find an optimal mixing location when the sound sequences are to be linked back together. The bigger this window setting is, the higher the possibility to find a better mixing position becomes, but at the same time large values may cause a "drifting" sound artifact because neighboring sequences can be chosen at more uneven intervals. If there's a disturbing artifact that sounds as if a constant frequency was drifting around, try reducing this setting.

  • BASS_ATTRIB_TEMPO_OPTION_OVERLAP_MS (default = 12):

    Overlap length in milliseconds. When the sound sequences are mixed back together to form again a continuous sound stream, this parameter defines how much the ends of the consecutive sequences will overlap with each other. This shouldn't be that critical parameter. If you reduce the BASS_FX_TEMPO_OPTION_SEQUENCE_MS setting by a large amount, you might wish to try a smaller value on this

  • BASS_ATTRIB_TEMPO_OPTION_PREVENT_CLICK (bool, default = FALSE):

    Prevents clicks when changing the tempo from or over the zero position.

    Note: This involves a slight sound quality compromise by disallowing swapping processing stage order and affecting situations that pitch is decreased from the nominal.

The table below summarizes how the parameters can be adjusted for different applications:

Parameter:Effect:
SEQUENCE_MS

Default value magnitude: Default value is relatively large, chosen for slowing down music tempo.

Larger value affects: Larger value is usually better for slowing down tempo. Growing the value decelerates the "echoing" artifact when slowing down the tempo.

Smaller value affects: Smaller value might be better for speeding up tempo. Reducing the value accelerates the "echoing" artifact when slowing down the tempo.

Music: Default value usually good.

Speech: A smaller value than default might be better.

Effect in CPU burden: Increasing the parameter value reduces computation burden.

SEEKWINDOW_MS

Default value magnitude: Default value is relatively large, chosen for slowing down music tempo.

Larger value affects: Larger value eases finding a good mixing position, but may cause a "drifting" artifact.

Smaller value affects: Smaller reduce possibility to find a good mixing position, but reduce the "drifting" artifact.

Music: Default value usually good, unless a "drifting" artifact is disturbing.

Speech: Default value usually good.

Effect in CPU burden: Increasing the parameter value increases computation burden.

OVERLAP_MS

Default value magnitude: Default value is relatively large, chosen to suit with above parameters.

Larger value affects: --

Smaller value affects: If you reduce the "sequence ms" setting, you might wish to try a smaller value.

Music: --

Speech: --

Effect in CPU burden: Increasing the parameter value increases computation burden.

Performance Optimizations:

  • The time-stretch routine has a 'quick' mode that substantially speeds up the algorithm but may degrade the sound quality by a small amount. This mode is activated by BASS_ATTRIB_TEMPO_OPTION_USE_QUICKALGO and value =1.
  • Intel SSE optimized routines are used with compatible CPUs when floating point sample type is used. SSE optimizations are currently implemented for Win32 platform only. Processors compatible with SSE extension are Intel processors starting from Pentium-III, and AMD processors starting from Athlon XP.
  • AMD 3DNow! optimized routines are used with compatible CPUs when floating point sample type is used, but SSE extension isn't supported . 3DNow! optimizations are currently implemented for Win32 platform only. These optimizations are used in AMD K6-2 and Athlon (classic) CPU's; better performing SSE routines are used with AMD processor starting from Athlon XP.
Examples

Create a playing tempo stream out of a decoding stream and loop it:
VB
' the source channel
Dim stream As Integer = Bass.BASS_StreamCreateFile("test.mp3", 0L, 0L, BASSFlag.BASS_STREAM_DECODE)
' the tempo channel
Dim streamFX As Integer = BassFx.BASS_FX_TempoCreate(stream, BASSFlag.BASS_FX_FREESOURCE)
...
' change the sampling rate by 20%, the streamFX will be played faster
Bass.BASS_ChannelSetAttribute(streamFX, BASSAttribute.BASS_ATTRIB_TEMPO_FREQ, 0.2F)

' change the tempo by -15%, the streamFX will be slower
Bass.BASS_ChannelSetAttribute(streamFX, BASSAttribute.BASS_ATTRIB_TEMPO, -0.15F)

' change the pitch (key) by one octave (12 semitones)
Bass.BASS_ChannelSetAttribute(streamFX, BASSAttribute.BASS_ATTRIB_TEMPO, 12F)
// the source channel
int stream = Bass.BASS_StreamCreateFile("test.mp3", 0L, 0L, BASSFlag.BASS_STREAM_DECODE);
// the tempo channel
int streamFX = BassFx.BASS_FX_TempoCreate(stream, BASSFlag.BASS_FX_FREESOURCE);
...
// change the sampling rate by 20%, the streamFX will be played faster
Bass.BASS_ChannelSetAttribute(streamFX, BASSAttribute.BASS_ATTRIB_TEMPO_FREQ, 0.2f);

// change the tempo by -15%, the streamFX will be slower
Bass.BASS_ChannelSetAttribute(streamFX, BASSAttribute.BASS_ATTRIB_TEMPO, -0.15f);

// change the pitch (key) by one octave (12 semitones)
Bass.BASS_ChannelSetAttribute(streamFX, BASSAttribute.BASS_ATTRIB_TEMPO, 12f);
See Also

Reference