BASS.NET API for the Un4seen BASS Audio Library

BassEncBASS_Encode_StartUser Method

BASS.NET API for the Un4seen BASS Audio Library
Sets up a user-provided encoder on a channel.

This overload implements UNICODE cmdlines. The BASS_UNICODE flag will be added automatically, since all .Net strings are always unicode.

Namespace:  Un4seen.Bass.AddOn.Enc
Assembly:  Bass.Net (in Bass.Net.dll) Version: 2.4.17.5
Syntax

public static int BASS_Encode_StartUser(
	int handle,
	string filename,
	BASSEncode flags,
	ENCODERPROC proc,
	IntPtr user
)

Parameters

handle
Type: SystemInt32
The channel handle... a HSTREAM, HMUSIC, or HRECORD.
filename
Type: SystemString
Output filename... = no output file.
flags
Type: Un4seen.Bass.AddOn.EncBASSEncode
A combination of these flags (see BASSEncode):
BASS_ENCODE_FP_8BIT, BASS_ENCODE_FP_16BIT, BASS_ENCODE_FP_24BIT, BASS_ENCODE_FP_32BITWhen you want to encode a floating-point channel, but the encoder does not support 32-bit floating-point sample data, then you can use one of these flags to have the sample data converted to 8/16/24/32 bit integer data before it's passed on to the encoder. These flags are ignored if the channel's sample data isn't floating-point.
BASS_ENCODE_FP_AUTOConvert floating-point sample data back to the channel's format (8/16 bit integer) if the data is only floating-point due to the BASS_CONFIG_FLOATDSP option being enabled.
BASS_ENCODE_DITHERApply dither (TPDF) when converting floating-point sample data to integer.
BASS_ENCODE_QUEUEQueue data to feed the encoder asynchronously. This prevents the data source (DSP system or BASS_Encode_Write(Int32, IntPtr, Int32) call) getting blocked by the encoder, but if data is queud more quickly than the encoder can process it, that could result in lost data.
BASS_ENCODE_LIMITLimit the data rate to real-time speed, by introducing a delay when the rate is too high. With BASS 2.4.6 or above, this flag is ignored when the encoder is fed in a playback buffer update cycle (including BASS_Update(Int32) and BASS_ChannelUpdate(Int32, Int32) calls), to avoid possibly causing playback buffer underruns. Except for in those instances, this flag is applied automatically when the encoder is feeding a Shoutcast or Icecast server.
BASS_ENCODE_CAST_NOLIMITDon't limit the data rate (to real-time speed) when sending to a Shoutcast or Icecast server.
BASS_ENCODE_PAUSEStart the encoder paused.
BASS_ENCODE_AUTOFREEAutomatically free the encoder when the source channel is freed.
BASS_UNICODEfilename is Unicode (16-bit characters) (not needed here, since the overloads already take care of it).
proc
Type: Un4seen.Bass.AddOn.EncENCODERPROC
Callback function to receive the sample data and return the encoded data.
user
Type: SystemIntPtr
User instance data to pass to the callback function.

Return Value

Type: Int32
The encoder process handle is returned if the encoder is successfully started, else 0 is returned (use BASS_ErrorGetCode to get the error code).
Remarks

This function allows user-provided encoders to be used, which is most useful for platforms where external encoders are unavailable for use with BASS_Encode_Start(Int32, String, BASSEncode, ENCODEPROC, IntPtr). For example, the LAME library could be used with this function instead of the standalone LAME executable with BASS_Encode_Start(Int32, String, BASSEncode, ENCODEPROC, IntPtr).

Internally, the sending of sample data to the encoder is implemented via a DSP callback on the channel. That means when the channel is played (or BASS_ChannelGetData(Int32, IntPtr, Int32) is called if it is a decoding channel), the sample data will be sent to the encoder at the same time. It also means that if the BASS_CONFIG_FLOATDSP option is enabled, the sample data will be 32-bit floating-point, and one of the BASS_ENCODE_FP flags will be required if the encoder does not support floating-point sample data. The BASS_CONFIG_FLOATDSP setting should not be changed while encoding is in progress.

By default, the encoder DSP has a priority setting of -1000, which determines where in the DSP chain the encoding is performed. That can be changed via the BASS_CONFIG_ENCODE_PRIORITY config option.

Besides the automatic DSP system, data can also be manually fed to the encoder via the BASS_Encode_Write(Int32, IntPtr, Int32) function. Both methods can be used together, but in general, the 'automatic' system ought to be paused when using the 'manual' system, via the BASS_ENCODE_PAUSE flag or the BASS_Encode_SetPaused(Int32, Boolean) function. Data fed to the encoder manually does not go through the source channel's DSP chain, so any DSP/FX set on the channel will not be applied to the data.

When queued encoding is enabled via the BASS_ENCODE_QUEUE flag, the DSP system or BASS_Encode_Write(Int32, IntPtr, Int32) call will just buffer the data, and the data will then be fed to the encoder by another thread. The buffer will grow as needed to hold the queued data, up to a limit specified by the BASS_CONFIG_ENCODE_QUEUE config option. If the limit is exceeded (or there is no free memory), data will be lost; BASS_Encode_SetNotify(Int32, ENCODENOTIFYPROC, IntPtr) can be used to be notified of that occurrence. The amount of data that is currently queued, as well as the queue limit and how much data has been lost, is available from BASS_Encode_GetCount(Int32, BASSEncodeCount).

When done encoding, use BASS_Encode_Stop(Int32) or BASS_Encode_StopEx(Int32, Boolean) to close the encoder.

Multiple encoders can be set on a channel. For convenience, most of the encoder functions will accept either an encoder handle or a channel handle. When a channel handle is used, the function is applied to all encoders that are set on that channel.

ERROR CODEDescription
BASS_ERROR_HANDLEhandle is not valid.
BASS_ERROR_CREATEThe file could not be created.
BASS_ERROR_UNKNOWNSome other mystery problem!

See Also

Reference