/// <summary>
/// Starts recording.
/// </summary>
/// <param name="Frequency">The sample rate to record at.</param>
/// <param name="Channels">The number of channels... 1 = mono, 2 = stereo, etc.</param>
/// <param name="Flags">Any combination of <see cref="BassFlags.Byte"/>, <see cref="BassFlags.Float"/> and <see cref="BassFlags.RecordPause"/>.</param>
/// <param name="Procedure">The user defined function to receive the recorded sample data... can be <see langword="null" /> if you do not wish to use a callback.</param>
/// <param name="User">User instance data to pass to the callback function.</param>
/// <returns>If successful, the new recording's handle is returned, else <see langword="false" /> is returned. Use <see cref="LastError"/> to get the error code.</returns>
/// <remarks>
/// Use <see cref="ChannelStop" /> to stop the recording, and <see cref="ChannelPause" /> to pause it.
/// Recording can also be started in a paused state (via the <see cref="BassFlags.RecordPause"/> flag), allowing DSP/FX to be set on it before any data reaches the callback function.
/// <para>The sample data will generally arrive from the recording device in blocks rather than in a continuous stream, so when specifying a very short period between callbacks, some calls may be skipped due to there being no new data available since the last call.</para>
/// <para>
/// When not using a callback (proc = <see langword="null" />), the recorded data is instead retrieved via <see cref="ChannelGetData(int, IntPtr, int)" />.
/// To keep latency at a minimum, the amount of data in the recording buffer should be monitored (also done via <see cref="ChannelGetData(int, IntPtr, int)" />, with the <see cref="DataFlags.Available"/> flag) to check that there is not too much data;
/// freshly recorded data will only be retrieved after the older data in the buffer is.
/// </para>
/// <para><b>Platform-specific</b></para>
/// <para>
/// Multiple simultaneous recordings can be made from the same device on Windows XP and later, but generally not on older Windows.
/// Multiple simultaneous recordings are possible on iOS and OSX, but may not always be on Linux or Windows CE.
/// On OSX and iOS, the device is instructed (when possible) to deliver data at the period set in the HIWORD of flags, even when a callback function is not used.
/// On other platforms, it is up the the system when data arrives from the device.
/// </para>
/// <para>
/// Unlike Bass.Net, a reference to <paramref name="Procedure"/> doesn't need to be held by you manually.
/// ManagedBass automatically holds a reference and frees it when the Channel is freed.
/// </para>
/// </remarks>
/// <exception cref="Errors.Init"><see cref="RecordInit" /> has not been successfully called.</exception>
/// <exception cref="Errors.Busy">
/// The device is busy.
/// An existing recording must be stopped before starting another one.
/// Multiple simultaneous recordings can be made from the same device on Windows XP and Vista, but generally not on older Windows.
/// </exception>
/// <exception cref="Errors.NotAvailable">
/// The recording device is not available.
/// Another application may already be recording with it, or it could be a half-duplex device and is currently being used for playback.
/// </exception>
/// <exception cref="Errors.SampleFormat">
/// The specified format is not supported.
/// If using the <see cref="BassFlags.Float"/> flag, it could be that floating-point recording is not supported.
/// </exception>
/// <exception cref="Errors.Memory">There is insufficient memory.</exception>
/// <exception cref="Errors.Unknown">Some other mystery problem!</exception>
public static int RecordStart(int Frequency, int Channels, BassFlags Flags, RecordProcedure Procedure, IntPtr User = default(IntPtr))
{
var h = BASS_RecordStart(Frequency, Channels, Flags, Procedure, User);
if (h != 0)
{
ChannelReferences.Add(h, 0, Procedure);
}
return(h);
}
/// <summary>
/// Creates a sample stream from an MP3, MP2, MP1, OGG, WAV, AIFF or plugin supported file on the internet, optionally receiving the downloaded data in a callback.
/// </summary>
/// <param name="Url">
/// URL of the file to stream.
/// Should begin with "http://", "https://" or "ftp://", or another add-on supported protocol.
/// The URL can be followed by custom HTTP request headers to be sent to the server;
/// the URL and each header should be terminated with a carriage return and line feed ("\r\n").
/// </param>
/// <param name="Offset">File position to start streaming from. This is ignored by some servers, specifically when the file length is unknown, for example a Shout/Icecast server.</param>
/// <param name="Flags">A combination of <see cref="BassFlags" /></param>
/// <param name="Procedure">Callback function to receive the file as it is downloaded... <see langword="null" /> = no callback.</param>
/// <param name="User">User instance data to pass to the callback function.</param>
/// <returns>If successful, the new stream's handle is returned, else 0 is returned. Use <see cref="LastError" /> to get the error code.</returns>
/// <remarks>
/// <para>
/// Use <see cref="ChannelGetInfo(int, out ChannelInfo)" /> to retrieve information on the format (sample rate, resolution, channels) of the stream.
/// The playback length of the stream can be retrieved using <see cref="ChannelGetLength(int, PositionFlags)" />.
/// </para>
/// <para>
/// When playing the stream, BASS will stall the playback if there is insufficient data to continue playing.
/// Playback will automatically be resumed when sufficient data has been downloaded.
/// <see cref="ChannelIsActive" /> can be used to check if the playback is stalled, and the progress of the file download can be checked with <see cref="StreamGetFilePosition" />.
/// </para>
/// <para>When streaming in blocks (<see cref="BassFlags.StreamDownloadBlocks"/>), be careful not to stop/pause the stream for too long, otherwise the connection may timeout due to there being no activity and the stream will end prematurely.</para>
/// <para>
/// When streaming from Shoutcast servers, metadata (track titles) may be sent by the server.
/// The data can be retrieved with <see cref="ChannelGetTags" />.
/// A sync can also be set (using <see cref="ChannelSetSync" />) so that you are informed when metadata is received.
/// A <see cref="SyncFlags.OggChange"/> sync can be used to be informed of when a new logical bitstream begins in an Icecast/OGG stream.
/// </para>
/// <para>
/// When using an <paramref name="Offset" />, the file length returned by <see cref="StreamGetFilePosition" /> can be used to check that it was successful by comparing it with the original file length.
/// Another way to check is to inspect the HTTP headers retrieved with <see cref="ChannelGetTags" />.
/// </para>
/// <para>Custom HTTP request headers may be ignored by some plugins, notably BassWma.</para>
/// <para>
/// Unlike Bass.Net, a reference to <paramref name="Procedure"/> doesn't need to be held by you manually.
/// ManagedBass automatically holds a reference and frees it when the Channel is freed.
/// </para>
/// <para><b>Platform-specific</b></para>
/// <para>
/// 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 and WMA.
/// On iOS and OSX, CoreAudio codecs are supported, including support for AAC and ALAC.
/// Media Foundation and CoreAudio codecs are only tried after the built-in decoders and any plugins have rejected the file.
/// Built-in support for IMA and Microsoft ADPCM WAV files is provided on Linux/Android/Windows CE, while they are supported via ACM and CoreAudio codecs on Windows and OSX/iOS.
/// </para>
/// </remarks>
/// <exception cref="Errors.Init"><see cref="Init" /> has not been successfully called.</exception>
/// <exception cref="Errors.NotAvailable">Only decoding channels (<see cref="BassFlags.Decode"/>) are allowed when using the <see cref="NoSoundDevice"/> device. The <see cref="BassFlags.AutoFree"/> flag is also unavailable to decoding channels.</exception>
/// <exception cref="Errors.NoInternet">No internet connection could be opened. Can be caused by a bad proxy setting.</exception>
/// <exception cref="Errors.Parameter"><paramref name="Url" /> is not a valid URL.</exception>
/// <exception cref="Errors.Timeout">The server did not respond to the request within the timeout period, as set with <see cref="NetTimeOut"/> config option.</exception>
/// <exception cref="Errors.FileOpen">The file could not be opened.</exception>
/// <exception cref="Errors.FileFormat">The file's format is not recognised/supported.</exception>
/// <exception cref="Errors.Codec">The 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.</exception>
/// <exception cref="Errors.SampleFormat">The sample format is not supported by the device/drivers. If the stream is more than stereo or the <see cref="BassFlags.Float"/> flag is used, it could be that they are not supported.</exception>
/// <exception cref="Errors.Speaker">The 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.</exception>
/// <exception cref="Errors.Memory">There is insufficient memory.</exception>
/// <exception cref="Errors.No3D">Could not initialize 3D support.</exception>
/// <exception cref="Errors.Unknown">Some other mystery problem!</exception>
public static int CreateStream(string Url, int Offset, BassFlags Flags, DownloadProcedure Procedure, IntPtr User = default(IntPtr))
{
var h = BASS_StreamCreateURL(Url, Offset, Flags | BassFlags.Unicode, Procedure, User);
if (h != 0)
{
ChannelReferences.Add(h, 0, Procedure);
}
return(h);
}
/// <summary>
/// Creates a user sample stream.
/// </summary>
/// <param name="Frequency">The default sample rate. The sample rate can be changed using <see cref="ChannelSetAttribute(int, ChannelAttribute, float)" />.</param>
/// <param name="Channels">The number of channels... 1 = mono, 2 = stereo, 4 = quadraphonic, 6 = 5.1, 8 = 7.1. More than stereo requires WDM drivers, and the Speaker flags are ignored.</param>
/// <param name="Flags">A combination of <see cref="BassFlags"/>.</param>
/// <param name="Procedure">The user defined stream writing function (see <see cref="StreamProcedure" />).</param>
/// <param name="User">User instance data to pass to the callback function.</param>
/// <returns>If successful, the new stream's handle is returned, else 0 is returned. Use <see cref="LastError" /> to get the error code.</returns>
/// <remarks>
/// <para>
/// Sample streams allow any sample data to be played through Bass, and are particularly useful for playing a large amount of sample data without requiring a large amount of memory.
/// If you wish to play a sample format that BASS does not support, then you can create a stream and decode the sample data into it.
/// </para>
/// <para>
/// Bass can automatically stream MP3, MP2, MP1, OGG, WAV and AIFF files, using <see cref="CreateStream(string,long,long,BassFlags)" />, and also from HTTP and FTP servers,
/// using <see cref="CreateStream(string,int,BassFlags,DownloadProcedure,IntPtr)" />, <see cref="CreateStream(StreamSystem,BassFlags,FileProcedures,IntPtr)" /> allows streaming from other sources too.
/// </para>
/// <para>However, the callback method must deliver PCM sample data as specified, so opening an MP3 file and just passing that file data will not work here.</para>
/// <para>
/// Unlike Bass.Net, a reference to <paramref name="Procedure"/> doesn't need to be held by you manually.
/// ManagedBass automatically holds a reference and frees it when the Channel is freed.
/// </para>
/// </remarks>
/// <exception cref="Errors.Init"><see cref="Init" /> has not been successfully called.</exception>
/// <exception cref="Errors.NotAvailable">Only decoding channels (<see cref="BassFlags.Decode"/>) are allowed when using the <see cref="NoSoundDevice"/> device. The <see cref="BassFlags.AutoFree"/> flag is also unavailable to decoding channels.</exception>
/// <exception cref="Errors.SampleFormat">The sample format is not supported by the device/drivers. If the stream is more than stereo or the <see cref="BassFlags.Float"/> flag is used, it could be that they are not supported.</exception>
/// <exception cref="Errors.Speaker">The 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.</exception>
/// <exception cref="Errors.Memory">There is insufficient memory.</exception>
/// <exception cref="Errors.No3D">Could not initialize 3D support.</exception>
/// <exception cref="Errors.Unknown">Some other mystery problem!</exception>
public static int CreateStream(int Frequency, int Channels, BassFlags Flags, StreamProcedure Procedure, IntPtr User = default(IntPtr))
{
var h = BASS_StreamCreate(Frequency, Channels, Flags, Procedure, User);
if (h != 0)
{
ChannelReferences.Add(h, 0, Procedure);
}
return(h);
}
/// <summary>
/// Creates a sample stream from an MP3, MP2, MP1, OGG, WAV, AIFF or plugin supported file via user callback functions.
/// </summary>
/// <param name="System">File system to use.</param>
/// <param name="Flags">Any combination of <see cref="BassFlags"/>.</param>
/// <param name="Procedures">The user defined file function (see <see cref="FileProcedures" />).</param>
/// <param name="User">User instance data to pass to the callback functions.</param>
/// <returns>If successful, the new stream's handle is returned, else 0 is returned. Use <see cref="LastError" /> to get the error code.</returns>
/// <remarks>
/// <para>
/// The buffered file system (<see cref="StreamSystem.Buffer"/>) is what is used by <see cref="CreateStream(string, int, BassFlags, DownloadProcedure, IntPtr)" />.
/// As the name suggests, data from the file is buffered so that it's readily available for decoding - BASS creates a thread dedicated to "downloading" the data.
/// This is ideal for when the data is coming from a source that has high latency, like the internet.
/// It's not possible to seek in buffered file streams, until the download has reached the requested position - it's not possible to seek at all if it's being streamed in blocks.
/// </para>
/// <para>
/// The push buffered file system (<see cref="StreamSystem.BufferPush"/>) is the same, except that instead of the file data being pulled from the <see cref="FileReadProcedure" /> function in a "download" thread, the data is pushed to BASS via <see cref="StreamPutFileData(int, IntPtr, int)" />.
/// A <see cref="FileReadProcedure" /> function is still required, to get the initial data used in the creation of the stream.
/// </para>
/// <para>
/// The unbuffered file system (<see cref="StreamSystem.NoBuffer"/>) is what is used by <see cref="CreateStream(string, long, long, BassFlags)" />.
/// In this system, BASS does not do any intermediate buffering - it simply requests data from the file as and when it needs it.
/// This means that reading (<see cref="FileReadProcedure" />) must be quick, otherwise the decoding will be delayed and playback buffer underruns (old data repeated) are a possibility.
/// It's not so important for seeking (<see cref="FileSeekProcedure" />) to be fast, as that is generally not required during decoding, except when looping a file.
/// </para>
/// <para>In all cases, BASS will automatically stall playback of the stream when insufficient data is available, and resume it when enough data does become available.</para>
/// <para><b>Platform-specific</b></para>
/// <para>
/// 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.
/// </para>
/// <para>
/// A copy is made of the <paramref name="Procedures"/> callback function table, so it does not have to persist beyond this function call.
/// Unlike Bass.Net, a reference to <paramref name="Procedures"/> doesn't need to be held by you manually.
/// ManagedBass automatically holds a reference and frees it when the Channel is freed.
/// </para>
/// </remarks>
/// <exception cref="Errors.Init"><see cref="Init" /> has not been successfully called.</exception>
/// <exception cref="Errors.NotAvailable">Only decoding channels (<see cref="BassFlags.Decode"/>) are allowed when using the <see cref="NoSoundDevice"/> device. The <see cref="BassFlags.AutoFree"/> flag is also unavailable to decoding channels.</exception>
/// <exception cref="Errors.Parameter"><paramref name="System" /> is not valid.</exception>
/// <exception cref="Errors.FileFormat">The file's format is not recognised/supported.</exception>
/// <exception cref="Errors.Codec">The 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.</exception>
/// <exception cref="Errors.SampleFormat">The sample format is not supported by the device/drivers. If the stream is more than stereo or the <see cref="BassFlags.Float"/> flag is used, it could be that they are not supported.</exception>
/// <exception cref="Errors.Speaker">The 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.</exception>
/// <exception cref="Errors.Memory">There is insufficient memory.</exception>
/// <exception cref="Errors.No3D">Could not initialize 3D support.</exception>
/// <exception cref="Errors.Unknown">Some other mystery problem!</exception>
public static int CreateStream(StreamSystem System, BassFlags Flags, FileProcedures Procedures, IntPtr User = default(IntPtr))
{
var h = BASS_StreamCreateFileUser(System, Flags, Procedures, User);
if (h != 0)
{
ChannelReferences.Add(h, 0, Procedures);
}
return(h);
}
