BASS.NET API for the Un4seen BASS Audio LibraryBassEncBASS_Encode_Start Method (Int32, String, BASSEncode, ENCODEPROC, IntPtr, Int32)BASS.NET API for the Un4seen BASS Audio Library
Sets up an 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.12.0
Syntax

public static int BASS_Encode_Start(
	int handle,
	string cmdline,
	BASSEncode flags,
	ENCODEPROC proc,
	IntPtr user,
	int limit
)

Parameters

handle
Type: SystemInt32
The channel handle... a HSTREAM, HMUSIC, or HRECORD.
cmdline
Type: SystemString
The encoder command-line, including the executable filename and any options. Or the output filename if the BASS_ENCODE_PCM flag is specified.
flags
Type: Un4seen.Bass.AddOn.EncBASSEncode
A combination of these flags (see BASSEncode):
BASS_ENCODE_PCMWrite plain PCM sample data to a file, without an encoder. The output filename is given in the cmdline parameter, or it can be to not write a file.
BASS_ENCODE_AIFFSend an AIFF header to the encoder instead of a WAVE header.
BASS_ENCODE_NOHEADDon't send a WAVE header to the encoder. If this flag is used then the sample format must be passed to the encoder some other way (eg. via the command-line).
BASS_ENCODE_RF64Write a BWF RF64 WAVE header instead of a standard header.
BASS_ENCODE_WFEXTSend the sample format information to the encoder in WAVEFORMATEXTENSIBLE form instead of WAVEFORMATEX form. This flag is ignored if the BASS_ENCODE_NOHEAD flag is used.
BASS_ENCODE_BIGENDSend big-endian sample data to the encoder, else little-endian.
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_MONOConvert to mono (if not already).
BASS_ENCODE_AUTOFREEAutomatically free the encoder when the source channel is freed.
BASS_UNICODEcmdline is Unicode (16-bit characters) (not needed here, since the overloads already take care of it).
proc
Type: Un4seen.Bass.AddOn.EncENCODEPROC
Optional callback function to receive the encoded data... = no callback. To have the encoded data received by a callback function, the encoder needs to be told to output to STDOUT (instead of a file).
user
Type: SystemIntPtr
User instance data to pass to the callback function.
limit
Type: SystemInt32
The maximum number of bytes that will be encoded (0=no limit).

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 works exactly like BASS_Encode_Start(Int32, String, BASSEncode, ENCODEPROC, IntPtr), but with a limit parameter added, which is the maximum number of bytes that will be encoded (0=no limit). Once the limit is hit, the encoder will die. BASS_Encode_SetNotify(Int32, ENCODENOTIFYPROC, IntPtr) can be used to be notified of that occurrence. One thing to note is that the limit is applied after any conversion due to the BASS_ENCODE_FP flags.

This can be useful in situations where the encoder needs to know in advance how much data it will be receiving. For example, when using a callback function with a file format that stores the length in the header, as the header cannot then be updated at the end of encoding. The length is communicated to the encoder via the WAVE header, so it requires that the BASS_ENCODE_NOHEAD flag is not used.

The encoder must be told (via the command-line) to expect input from STDIN, rather than a file. The command-line should also tell the encoder what filename to write it's output to, unless you're using a callback function, in which case it should be told to write it's output to STDOUT.

No user interaction with the encoder is possible, so anything that would cause the encoder to require the user to press any keys should be avoided. For example, if the encoder asks whether to overwrite files, the encoder should be instructed to always overwrite (via the command-line), or you should delete the existing file before starting the encoder.

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

The encoder DSP has a priority setting of -1000, so if you want to set DSP/FX on the channel and have them present in the encoding, set their priority above that.

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 be paused when using the "manual" system, by use of the BASS_ENCODE_PAUSE flag or the BASS_Encode_SetPaused(Int32, Boolean) function.

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

BASS_Encode_IsActive(Int32) can be used to check that the encoder is still running. When done encoding, use BASS_Encode_Stop(Int32) to close the encoder.

The returned process handle can be used to do things like change the encoder's priority and get it's exit code. See the System.Diagnostics namespace for details.

Multiple encoders can be set on a channel. For simplicity, the encoder functions (ie. BASS_Encode_IsActive/SetPaused/Stop/Write) will accept either an encoder handle or a channel handle. When using a channel handle, the function is applied to all encoders that are set on that channel.

ERROR CODEDescription
BASS_ERROR_HANDLEhandle is not valid.
BASS_ERROR_FILEOPENCouldn't start the encoder. Check that the executable exists.
BASS_ERROR_CREATEThe PCM file couldn't be created.
BASS_ERROR_UNKNOWNSome other mystery problem!

Platform-specific

External encoders are not supported on Android or iOS or Windows CE, so only plain PCM file writing with the BASS_ENCODE_PCM flag is possible on those platforms. User-provided encoders can be used via BASS_Encode_StartUser(Int32, String, BASSEncode, ENCODERPROC, IntPtr).

Examples

Start encoding a channel to an MP3 file (output.mp3) using LAME with the standard preset settings:
VB
BassEnc.BASS_Encode_Start(channel, "lame --alt-preset standard - output.mp3", 
        0, Nothing, IntPtr.Zero)
' start the channel playing & encoding
Bass.BASS_ChannelPlay(channel, False)
BassEnc.BASS_Encode_Start(channel, "lame --alt-preset standard - output.mp3", 
        0, null, IntPtr.Zero);
// start the channel playing & encoding
Bass.BASS_ChannelPlay(channel, false);
Start writing a channel to a WAV file (output.wav):
VB
BassEnc.BASS_Encode_Start(channel, "output.wav", 
        BASSEncode.BASS_ENCODE_PCM, Nothing, IntPtr.Zero)
' start the channel playing & encoding
Bass.BASS_ChannelPlay(channel, False)
BassEnc.BASS_Encode_Start(channel, "output.wav", 
        BASSEncode.BASS_ENCODE_PCM, null, IntPtr.Zero);
// start the channel playing & encoding
Bass.BASS_ChannelPlay(channel, false);
See Also

Reference