BASS.NET API for the Un4seen BASS Audio Library

BassBASS_StreamCreateFile Method (IntPtr, Int64, Int64, BASSFlag)

BASS.NET API for the Un4seen BASS Audio Library
Creates a sample stream from an MP3, MP2, MP1, OGG, WAV, AIFF or plugin supported memory IntPtr.

This overload implements streaming from memory.

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

public static int BASS_StreamCreateFile(
	IntPtr memory,
	long offset,
	long length,
	BASSFlag flags
)

Parameters

memory
Type: SystemIntPtr
An unmanaged pointer to the memory location as an IntPtr.
offset
Type: SystemInt64
Offset to begin streaming from (unused for memory streams, set to 0).
length
Type: SystemInt64
Data length (needs to be set to the length of the memory stream in bytes which should be played).
flags
Type: Un4seen.BassBASSFlag
Any combination of these flags BASSFlag, needs to casted into an (int) because we needed another method signature here.
BASS_SAMPLE_FLOATUse 32-bit floating-point sample data. WDM drivers or the BASS_STREAM_DECODE flag are required to use this flag in Windows. See Floating-point channels for more info.
BASS_SAMPLE_MONODecode/play the stream (MP3/MP2/MP1 only) in mono, reducing the CPU usage (if it was originally stereo). This flag is automatically applied if BASS_DEVICE_MONO was specified when calling BASS_Init(Int32, Int32, BASSInit, IntPtr, IntPtr).
BASS_SAMPLE_3DUse 3D functionality. This is ignored if BASS_DEVICE_3D wasn't specified when calling BASS_Init(Int32, Int32, BASSInit, IntPtr, IntPtr). 3D streams must be mono. The SPEAKER flags can not be used together with this flag.
BASS_SAMPLE_LOOPLoop the file. This flag can be toggled at any time using BASS_ChannelFlags(Int32, BASSFlag, BASSFlag).
BASS_STREAM_PRESCANEnable pin-point accurate seeking (to the exact byte) on the MP3/MP2/MP1 stream. This also increases the time taken to create the stream, due to the entire file being pre-scanned for the seek points.
BASS_STREAM_AUTOFREEAutomatically free the stream when it ends. This allows you to stream a file and forget about it, as BASS will automatically 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.

Return Value

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

BASS has built-in support for MPEG, OGG, WAV and AIFF files. Support for additional formats is available via add-ons, which can be downloaded from the BASS website: www.un4seen.com.

MPEG 1.0, 2.0 and 2.5 layer 3 (MP3) files are supported, layers 1 (MP1) and 2 (MP2) are also supported. Standard RIFF and RF64 WAV files are supported, with the sample data in a PCM format or compressed with an ACM codec, but the codec is required to be installed on the user's system for the WAV to be decoded. So you should either distribute the codec with your software, or use a codec that comes with Windows (eg. Microsoft ADPCM). All PCM formats from 8 to 32-bit are supported in WAV and AIFF files, but the output will be restricted to 16-bit unless the BASS_SAMPLE_FLOAT flag is used. 64-bit floating-point WAV and AIFF files are also supported, but are rendered in 16-bit or 32-bit floating-point depending on the flags. The file's original resolution is available via BASS_ChannelGetInfo(Int32, BASS_CHANNELINFO).

Chained OGG files containing multiple logical bitstreams are supported, but seeking within them is only fully supported if the BASS_STREAM_PRESCAN flag is used (or the BASS_CONFIG_OGG_PRESCAN config option is enabled) to have them pre-scanned. Without pre-scanning, seeking will only be possible back to the start. The BASS_POS_OGG "mode" can be used with BASS_ChannelGetLength(Int32, BASSMode) to get the number of bitstreams and with BASS_ChannelSetPosition(Int32, Int64, BASSMode) to seek to a particular one. A BASS_SYNC_OGG_CHANGE sync can be set via BASS_ChannelSetSync(Int32, BASSSync, Int64, SYNCPROC, IntPtr) to be informed of when a new bitstream begins during decoding/playback.

Multi-channel (ie. more than stereo) OGG, WAV and AIFF files are supported.

Use BASS_ChannelGetInfo(Int32, BASS_CHANNELINFO) to retrieve information on the format (sample rate, resolution, channels) of the stream. The playback length of the stream can be retrieved using BASS_ChannelGetLength(Int32, BASSMode).

If length = 0 (use all data up to the end of the file), and the file length increases after creating the stream (ie. the file is still being written), then BASS will play the extra data too, but the length returned by BASS_ChannelGetLength(Int32, BASSMode) will not be updated until the end is reached. The BASS_StreamGetFilePosition(Int32, BASSStreamFilePosition) return values will be updated during playback of the extra data though.

When streaming from memory, the memory must not be freed before the stream is freed. There may be exceptions to that with some add-ons (see the documentation).

To stream a file from the internet, use BASS_StreamCreateURL(String, Int32, BASSFlag, DOWNLOADPROC, IntPtr). To stream from other locations, see BASS_StreamCreateFileUser(BASSStreamSystem, BASSFlag, BASS_FILEPROCS, IntPtr).

Don't forget to pin your memory object when using this overload.

ERROR CODEDescription
BASS_ERROR_INITBASS_Init(Int32, Int32, BASSInit, IntPtr, IntPtr) has not been successfully called.
BASS_ERROR_NOTAVAILOnly decoding channels (BASS_STREAM_DECODE) are allowed when using the "no sound" device. The BASS_STREAM_AUTOFREE flag is also unavailable to decoding channels.
BASS_ERROR_ILLPARAMThe length must be specified when streaming from memory.
BASS_ERROR_FILEFORMThe file's format is not recognised/supported.
BASS_ERROR_NOTAUDIOThe file does not contain audio, or it also contains video and videos are disabled.
BASS_ERROR_CODECThe file uses a codec that's not available/supported. This can apply to WAV and AIFF files, and also MP3 files when using the "MP3-free" BASS version.
BASS_ERROR_FORMATThe sample format is not supported by the device/drivers. If the stream is more than stereo or the BASS_SAMPLE_FLOAT flag is used, it could be that they are not supported.
BASS_ERROR_SPEAKERThe specified SPEAKER flags are invalid. The device/drivers do not support them, they are attempting to assign a stereo stream to a mono speaker or 3D functionality is enabled.
BASS_ERROR_MEMThere is insufficient memory.
BASS_ERROR_NO3DCould not initialize 3D support.
BASS_ERROR_UNKNOWNSome other mystery problem!

Platform-specific

Away from Windows, all mixing is done in software (by BASS), so the BASS_SAMPLE_SOFTWARE flag is unnecessary. The BASS_SAMPLE_FX flag is also ignored.

On Windows and Windows CE, ACM codecs are supported with compressed WAV files. Media Foundation codecs are also supported on Windows 7 and updated versions of Vista, including support for AAC/MP4 and WMA. On iOS and OSX, CoreAudio codecs are supported, adding support for any file formats that have a codec installed. Media Foundation and CoreAudio codecs are only tried after the built-in decoders and any plugins have rejected the file.

Examples

The following example demontrates how to stream from memory:
private GCHandle _hGCFile;
...
// open a file
FileStream fs = File.OpenRead( "test.mp3" );
// get the legth of the file
long length = fs.Length;
// create the buffer which will keep the file in memory
byte[] buffer = new byte[length];
// read the file into the buffer
fs.Read(buffer, 0, (int)length);
// buffer is filled, file can be closed
fs.Close();

// now create a pinned handle, so that the Garbage Collector will not move this object
_hGCFile = GCHandle.Alloc( buffer, GCHandleType.Pinned );
// create the stream (AddrOfPinnedObject delivers the necessary IntPtr)
int stream = Bass.BASS_StreamCreateFile(_hGCFile.AddrOfPinnedObject(),
                  0L, length, BASSFlag.BASS_SAMPLE_FLOAT);

if (stream != 0 && Bass.BASS_ChannelPlay(stream, false) )
{
    // playing...
}
else
{
    Console.WriteLine("Error = {0}", Bass.BASS_ErrorGetCode());
}
...
// when playback has ended and the pinned object is not needed anymore, 
// we need to free the handle!
// Note: calling this method to early will crash the application, 
// since the buffer would be stolen from BASS while still playing!
_hGCFile.Free();
See Also

Reference