Class BassEnc

Mime type for Aac.

Declaration

public const string MimeAac = null

Field Value

String

Mime type for Mp3.

Declaration

public const string MimeMp3 = null

Field Value

String

Mime type for Ogg.

Declaration

public const string MimeOgg = null

Field Value

String

ACM codec name to give priority for the formats it supports (e.g. 'l3codecp.acm').

Declaration

public static string ACMLoad { get; set; }

Property Value

String

Proxy server settings when connecting to Icecast and Shoutcast (in the form of "[User:Password@]server:port"... null (default) = don't use a proxy but a direct connection).

Declaration

public static string CastProxy { get; set; }

Property Value

String

Remarks

If only the "server:port" part is specified, then that proxy server is used without any authorization credentials. This setting affects how the following functions connect to servers: CastInit(Int32, String, String, String, String, String, String, String, String, Int32, Boolean), CastGetStats(Int32, EncodeStats, String), CastSetTitle(Int32, String, String). When a proxy server is used, it needs to support the HTTP 'CONNECT' method. The default setting is null (do not use a proxy). Changes take effect from the next internet stream creation call.

The time to wait (in milliseconds) to send data to a cast server (default 5000ms)

Declaration

public static int CastTimeout { get; set; }

Property Value

Int32

Remarks

When an attempt to send data is timed-out, the data is discarded. EncodeSetNotify(Int32, EncodeNotifyProcedure, IntPtr) can be used to receive a notification of when this happens. Changes take immediate effect.

Encoder DSP priority (default -1000) which determines where in the DSP chain the encoding is performed.

Declaration

public static int DSPPriority { get; set; }

Property Value

Int32

Remarks

All DSP with a higher priority will be present in the encoding. Changes only affect subsequent encodings, not those that have already been started.

The maximum queue Length of the async encoder (default 10000, 0 = Unlimited) in milliseconds.

Declaration

public static int Queue { get; set; }

Property Value

Int32

Remarks

When queued encoding is enabled, the queue's Buffer will grow as needed to hold the queued data, up to a limit specified by this config option. Changes only apply to new encoders, not any already existing encoders.

Gets the Version of BassEnc that is loaded.

Declaration

public static Version Version { get; }

Property Value

Version

Retrieves stats from the Shoutcast or Icecast server.

Declaration

public static string CastGetStats(int Handle, EncodeStats Type, string Password)

Parameters

Int32 Handle

The encoder Handle.

EncodeStats Type

The type of stats to retrieve.

String Password

Password when retrieving Icecast server stats... null = use the password provided in the CastInit(Int32, String, String, String, String, String, String, String, String, Int32, Boolean) call. A username can also be included in the form of "username:password".

Returns

String

If successful, true is returned, else false is returned. Use LastError to get the error code.

Remarks

The stats are returned in XML format.

Initializes sending an encoder's output to a Shoutcast or Icecast server.

Example
Start encoding a stereo 44100hz channel to 128kb/s MP3, and send the output to a Shoutcast server.

// setup the encoder
var encoder = BassEnc.EncodeStart(channel, "lame -r -s 44100 -b 128 -", EncodeFlags.NoHeader, null, IntPtr.Zero);

// start the cast
BassEnc.CastInit(encoder, "server.com:8000", "password", BassEnc.MimeMp3, "name", "url", "genre", null, null, 128, true);

Setup PCM encoding on a dummy stream to send pre-encoded MP3 data to a Shoutcast server.

// create a dummy stream to host the encoder
var dummy = Bass.CreateStream(44100, 1, BassFlags.Decode, StreamProcedureType.Dummy);

// setup the PCM encoder
encoder = BassEnc.EncodeStart(dummy, null, EncodeFlags.PCM | EncodeFlags.NoHeader | EncodeFlags.UnlimitedCastDataRate, null, IntPtr.Zero);

// start the cast
BassEnc.CastInit(encoder, "server.com:8000", "password", BassEnc.MimeMp3, "name", "url", "genre", null, null, 128, true);

---

// feed MP3 data to the encoder/caster (repeat periodically)
BassEnc.EncodeWrite(encoder, mp3data, length);

Declaration

public static bool CastInit(int Handle, string Server, string Password, string Content, string Name, string Url, string Genre, string Description, string Headers, int Bitrate, bool Public)

Parameters

Int32 Handle

The encoder handle.

String Server

The server to send to, in the form of "address:port" (Shoutcast v1) resp. "address:port,sid" (Shoutcast v2) or "address:port/mount" (Icecast).

String Password

The server password. A username can be included in the form of "username:password" when connecting to an Icecast or Shoutcast 2 server.

String Content

The MIME type of the encoder output.

MimeMp3, MimeOgg or MimeAac.

String Name

The stream name... null = no name.

String Url

The URL, for example, of the radio station's webpage... null = no URL.

String Genre

The genre... null = no genre.

String Description

Description... null = no description. This applies to Icecast only.

String Headers

Other headers to send to the server... null = none. Each header should end with a carriage return and line feed ("\r\n").

Int32 Bitrate

The bitrate (in kbps) of the encoder output... 0 = undefined bitrate. In cases where the bitrate is a "quality" (rather than CBR) setting, the headers parameter can be used to communicate that instead, eg. "ice-bitrate: Quality 0\r\n".

Boolean Public

Public? If true, the stream is added to the public directory of streams, at shoutcast.com or dir.xiph.org (or as defined in the server config).

Returns

Boolean

If successful, true is returned, else false is returned. Use LastError to get the error code.

Remarks

This function sets up a Shoutcast/Icecast source client, sending the encoder's output to a server, which listeners can then connect to and receive the data from. The Shoutcast and Icecast server software is available from http://www.shoutcast.com/broadcast-tools and http://www.icecast.org/download.php, respectively.

An encoder needs to be started (but with no data sent to it yet) before using this function to setup the sending of the encoder's output to a Shoutcast or Icecast server. If EncodeStart(Int32, String, EncodeFlags, EncodeProcedure, IntPtr) is used, the encoder should be setup to write its output to STDOUT. Due to the length restrictions of WAVE headers/files, the encoder should also be started with the NoHeader flag, and the sample format details sent via the command-line.

Unless the UnlimitedCastDataRate flag is set on the encoder, BASSenc automatically limits the rate that data is processed to real-time speed to avoid overflowing the server's buffer, which means that it is safe to simply try to process data as quickly as possible, eg. when the source is a decoding channel. Encoders set on recording channels are automatically exempt from the rate limiting, as they are inherently real-time. With BASS 2.4.6 or above, also exempt are encoders that are fed in a playback buffer update cycle (including Update(Int32) and ChannelUpdate(Int32, Int32) calls), eg. when the source is a playing channel; that is to avoid delaying the update thread, which could result in playback buffer underruns.

Normally, BASSenc will produce the encoded data (with the help of an encoder) that is sent to a Shoutcast/Icecast server, but it is also possible to send already encoded data to a server (without first decoding and re-encoding it) via the PCM encoding option. The encoder can be set on any BASS channel, as rather than feeding on sample data from the channel, EncodeWrite(Int32, IntPtr, Int32) would be used to feed in the already encoded data. BASSenc does not know what the data's bitrate is in that case, so it is up to the user to process the data at the correct rate (real-time speed).

ServerInit(Int32, String, Int32, Int32, EncodeServer, EncodeClientProcedure, IntPtr) can be used to setup a server that listeners can connect to directly, without a Shoutcast/Icecast server intermediary.

Sends metadata to a Shoutcast 2 server.

Declaration

public static bool CastSendMeta(int Handle, EncodeMetaDataType Type, byte[] Buffer)

Parameters

Int32 Handle

The encoder Handle.

EncodeMetaDataType Type

The type of metadata.

Byte[] Buffer

The XML metadata as an UTF-8 encoded byte array.

Returns

Boolean

If successful, true is returned, else false is returned. Use LastError to get the error code.

Sends metadata to a Shoutcast 2 server.

Declaration

public static bool CastSendMeta(int Handle, EncodeMetaDataType Type, string Metadata)

Parameters

Int32 Handle

The encoder Handle.

EncodeMetaDataType Type

The type of metadata.

String Metadata

The XML metadata to send.

Returns

Boolean

If successful, true is returned, else false is returned. Use LastError to get the error code.

Sets the title of a cast stream.

Declaration

public static bool CastSetTitle(int Handle, byte[] Title, byte[] Url)

Parameters

Int32 Handle

The encoder Handle.

Byte[] Title

encoded byte[] containing the title to set.

Byte[] Url

encoded byte[] containing the URL to go with the title... null = no URL. This applies to Shoutcast only (not Shoutcast 2).

Returns

Boolean

If successful, true is returned, else false is returned. Use LastError to get the error code.

Remarks

The ISO-8859-1 (Latin-1) character set should be used with Shoutcast servers, and UTF-8 with Icecast and Shoutcast 2 servers.

Sets the title (ANSI) of a cast stream.

Declaration

public static bool CastSetTitle(int Handle, string Title, string Url)

Parameters

Int32 Handle

The encoder Handle.

String Title

The title to set.

String Url

URL to go with the title... null = no URL. This applies to Shoutcast only (not Shoutcast 2).

Returns

Boolean

If successful, true is returned, else false is returned. Use LastError to get the error code.

Remarks

The ISO-8859-1 (Latin-1) character set should be used with Shoutcast servers, and UTF-8 with Icecast and Shoutcast 2 servers.

Sends a RIFF chunk to an encoder.

Declaration

public static bool EncodeAddChunk(int Handle, string ID, IntPtr Buffer, int Length)

Parameters

Int32 Handle

The encoder Handle... a HENCODE.

String ID

The 4 character chunk id (e.g. 'bext').

IntPtr Buffer

The buffer containing the chunk data (without the id).

Int32 Length

The number of bytes in the buffer.

Returns

Boolean

If successful, true is returned, else false is returned. Use LastError to get the error code.

Remarks

BassEnc writes the minimum chunks required of a WAV file: "fmt" and "data", and "ds64" and "fact" when appropriate. This function can be used to add other chunks. For example, a BWF "bext" chunk or "INFO" tags.

Chunks can only be added prior to sample data being sent to the encoder. The Pause flag can be used when starting the encoder to ensure that no sample data is sent before additional chunks have been set.

Sends a RIFF chunk to an encoder.

Declaration

public static bool EncodeAddChunk(int Handle, string ID, byte[] Buffer, int Length)

Parameters

Int32 Handle

The encoder Handle... a HENCODE.

String ID

The 4 character chunk id (e.g. 'bext').

Byte[] Buffer

The buffer containing the chunk data (without the id).

Int32 Length

The number of bytes in the buffer.

Returns

Boolean

If successful, true is returned, else false is returned. Use LastError to get the error code.

Remarks

BassEnc writes the minimum chunks required of a WAV file: "fmt" and "data", and "ds64" and "fact" when appropriate. This function can be used to add other chunks. For example, a BWF "bext" chunk or "INFO" tags.

Chunks can only be added prior to sample data being sent to the encoder. The Pause flag can be used when starting the encoder to ensure that no sample data is sent before additional chunks have been set.

Retrieves the channel that an encoder is set on.

Declaration

public static int EncodeGetChannel(int Handle)

Parameters

Int32 Handle

The encoder to get the channel from.

Returns

Int32

If successful, the encoder's channel Handle is returned, else 0 is returned. Use LastError to get the error code.

Retrieves the amount of data queued, sent to or received from an encoder, or sent to a cast server.

Declaration

public static long EncodeGetCount(int Handle, EncodeCount Count)

Parameters

Int32 Handle

The encoder Handle.

EncodeCount Count

The count to retrieve (see EncodeCount).

Returns

Int64

If successful, the requested count (in bytes) is returned, else -1 is returned. Use LastError to get the error code.

Remarks

The queue counts are based on the channel's sample format (floating-point if the FloatingPointDSP option is enabled), while the In count is based on the sample format used by the encoder, which could be different if one of the Floating-point conversion flags is active or the encoder is using an ACM codec (which take 16-bit data).

When the encoder output is being sent to a cast server, the Cast count will match the Out count, unless there have been problems (eg. network timeout) that have caused data to be dropped.

Checks if an encoder is running on a channel.

Declaration

public static PlaybackState EncodeIsActive(int Handle)

Parameters

Int32 Handle

The encoder or channel Handle... a HENCODE, HSTREAM, HMUSIC, or HRECORD.

Returns

PlaybackState

The return value is one of PlaybackState values.

Remarks

When checking if there's an encoder running on a channel, and there are multiple encoders on the channel, Playing will be returned if any of them are active.

If an encoder stops running prematurely, EncodeStop(Int32) should still be called to release resources that were allocated for the encoding.

Moves an encoder (or all encoders on a channel) to another channel.

Declaration

public static bool EncodeSetChannel(int Handle, int Channel)

Parameters

Int32 Handle

The encoder or channel Handle... a HENCODE, HSTREAM, HMUSIC, or HRECORD.

Int32 Channel

The channel to move the encoder(s) to... a HSTREAM, HMUSIC, or HRECORD.

Returns

Boolean

If successful, true is returned, else false is returned. Use LastError to get the error code.

Remarks

The new channel must have the same sample format (rate, channels, resolution) as the old channel, as that is what the encoder is expecting. A channel's sample format is available via .

Sets a callback function on an encoder (or all encoders on a channel) to receive notifications about its status.

Declaration

public static bool EncodeSetNotify(int Handle, EncodeNotifyProcedure Procedure, IntPtr User = null)

Parameters

Int32 Handle

The encoder or channel Handle... a HENCODE, HSTREAM, HMUSIC, or HRECORD.

EncodeNotifyProcedure Procedure

Callback function to receive the notifications... null = no callback.

IntPtr User

User instance data to Password to the callback function.

Returns

Boolean

If successful, true is returned, else false is returned. Use LastError to get the error code.

Remarks

When setting a notification callback on a channel, it only applies to the encoders that are currently set on the channel. Subsequent encoders will not automatically have the notification callback set on them, this function will have to be called again to set them up.

An encoder can only have one notification callback set. Subsequent calls of this function can be used to change the callback function, or disable notifications (Procedure = null).

The status of an encoder and its cast connection (if it has one) is checked when data is sent to the encoder or server, and by EncodeIsActive(Int32). That means an encoder's death will not be detected automatically, and so no notification given, while no data is being encoded.

If the encoder is already dead when setting up a notification callback, the callback will be triggered immediately.

Pauses or resumes encoding on a channel.

Declaration

public static bool EncodeSetPaused(int Handle, bool Paused = true)

Parameters

Int32 Handle

The encoder or channel Handle... a HENCODE, HSTREAM, HMUSIC, or HRECORD.

Boolean Paused

Paused?

Returns

Boolean

If no encoder has been started on the channel, false is returned, otherwise true is returned.

Remarks

When an encoder is paused, no sample data will be sent to the encoder "automatically". Data can still be sent to the encoder "manually" though, via the EncodeWrite(Int32, IntPtr, Int32) function.

Starts encoding on a channel.

Declaration

public static int EncodeStart(int Handle, string CommandLine, EncodeFlags Flags, EncodeProcedure Procedure, IntPtr User = null)

Parameters

Int32 Handle

The channel Handle... a HSTREAM, HMUSIC, or HRECORD.

String CommandLine

The encoder command-line, including the executable filename and any options. Or the output filename if the PCM flag is specified.

EncodeFlags Flags

A combination of BassFlags.

EncodeProcedure Procedure

Optional callback function to receive the encoded data... null = 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).

IntPtr User

User instance data to Password to the callback function.

Returns

Int32

The encoder process Handle is returned if the encoder is successfully started, else 0 is returned (use LastError to get the error code).

Remarks

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.

Standard RIFF files are limited to a little over 4GB in size. When writing a WAV file, BASSenc will automatically stop at that point, so that the file is valid. That does not apply when sending data to an encoder though, as the encoder may (possibly via a command-line option) ignore the size restriction, but if it does not, it could mean that the encoder stops after a few hours (depending on the sample format). If longer encodings are needed, the NoHeader flag can be used to omit the WAVE header, and the encoder informed of the sample format via the command-line instead. The 4GB size limit can also be overcome with the RF64 flag, but most encoders are unlikely to support RF64.

When writing an RF64 WAV file, a standard RIFF header will still be written initially, which will only be replaced by an RF64 header at the end if the file size has exceeded the standard limit. When an encoder is used, it is not possible to go back and change the header at the end, so the RF64 header is sent at the beginning in that case.

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 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 FloatingPointDSP option, then the sample data will be 32-bit floating-point, and you'll need to use one of the Floating-point flags if the encoder does not support floating-point sample data. The FloatingPointDSP 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 EncodeWrite(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 Pause flag or the EncodeSetPaused(Int32, Boolean) function.

When queued encoding is enabled via the Queue flag, the DSP system or EncodeWrite(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 Queue config option. If the limit is exceeded (or there is no free memory), data will be lost; EncodeSetNotify(Int32, EncodeNotifyProcedure, 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 EncodeGetCount(Int32, EncodeCount).

EncodeIsActive(Int32) can be used to check that the encoder is still running. When done encoding, use EncodeStop(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.

Multiple encoders can be set on a channel. For simplicity, the encoder functions 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.

Platform-specific

External encoders are not supported on iOS or Windows CE, so only plain PCM file writing with the PCM flag is possible on those platforms.

Starts encoding on a channel.

Declaration

public static int EncodeStart(int Handle, string CommandLine, EncodeFlags Flags, EncodeProcedure Procedure, IntPtr User, int Limit)

Parameters

Int32 Handle

The channel Handle... a HSTREAM, HMUSIC, or HRECORD.

String CommandLine

The encoder command-line, including the executable filename and any options. Or the output filename if the PCM flag is specified.

EncodeFlags Flags

A combination of BassFlags.

EncodeProcedure Procedure

Optional callback function to receive the encoded data... null = 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).

IntPtr User

User instance data to Password to the callback function.

Int32 Limit

The maximum number of bytes that will be encoded (0 = no limit).

Returns

Int32

The encoder process Handle is returned if the encoder is successfully started, else 0 is returned (use LastError to get the error code).

Remarks

This function works exactly like EncodeStart(Int32, String, EncodeFlags, EncodeProcedure, 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. EncodeSetNotify(Int32, EncodeNotifyProcedure, 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 floating-point 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.