BASS_RecordStart

Starts recording.

HRECORD BASS_RecordStart(
    DWORD freq,
    DWORD chans,
    DWORD flags,
    RECORDPROC *proc
    void *user
);

Parameters

freq

The sample rate to record at... 0 = device's current sample rate.

chans

The number of channels... 1 = mono, 2 = stereo, etc. 0 = device's current channel count.

flags

A combination of these flags.

BASS_SAMPLE_8BITS	Use 8-bit resolution. If neither this or the BASS_SAMPLE_FLOAT flag are specified, then the recorded data is 16-bit.
BASS_SAMPLE_FLOAT	Use 32-bit floating-point sample data. See Floating-point channels for info.
BASS_RECORD_PAUSE	Start the recording paused.

The HIWORD - use MAKELONG(flags,period) - can be used to set the period (in milliseconds) between calls to the callback function. The minimum period is 5ms, the maximum is half the BASS_CONFIG_REC_BUFFER setting. If the period specified is outside this range, it is automatically capped. The default is 100ms.

proc

The user defined function to receive the recorded sample data... can be NULL if you do not wish to use a callback.

user

User instance data to pass to the callback function.

Return value

If successful, the new recording's handle is returned, else FALSE is returned. Use BASS_ErrorGetCode to get the error code.

Error codes

BASS_ERROR_INIT	BASS_RecordInit has not been successfully called.
BASS_ERROR_BUSY	The device is busy. An existing recording may need to be stopped before starting another one.
BASS_ERROR_DENIED	Recording permission has not been granted by the user.
BASS_ERROR_FORMAT	The sample format is not supported.
BASS_ERROR_MEM	There is insufficient memory.
BASS_ERROR_UNKNOWN	Some other mystery problem!

Remarks

Use BASS_ChannelFree or BASS_ChannelStop to stop the recording and free its resources. BASS_ChannelPause can be used to pause the recording; it can also be started in a paused state via the BASS_RECORD_PAUSE flag, which allows DSP/FX to be set on it before any data reaches the callback function. Use BASS_ChannelStart to resume a paused recording.

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. A loopback recording device will only deliver data while the corresponding output device is active.

When not using a callback (proc = NULL), the recorded data is instead retrieved via BASS_ChannelGetData. To keep latency at a minimum, the amount of data in the recording buffer should be monitored (also done via BASS_ChannelGetData, with the BASS_DATA_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.

The BASS_POS_END mode can be used with BASS_ChannelSetPosition to limit the length of a recording.

When freq and/or chans is set to 0 for the device's current values, BASS_ChannelGetInfo can be used afterwards to find out what values are being used by the recording.

A recording may end unexpectedly if the device fails, eg. if it is disconnected/disabled. A BASS_SYNC_DEV_FAIL sync can be set via BASS_ChannelSetSync to be informed if that happens. It will not be possible to resume the recording channel then; a new recording channel will need to be created when the device becomes available again.

Platform-specific

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 macOS and iOS, but may not always be on Linux.

Loopback recording is only available on Windows Vista and above. The option to use the device's current sample rate and/or channel count is only available on Windows/macOS/iOS.

On macOS 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.

On macOS and iOS, this function may succeed but only capture silence when recording permission has not been granted. The AVCaptureDevice authorizationStatusForMediaType method (or the AVAudioSession recordPermission method on iOS) can be used to check the permission status.

Example

Start recording at 44100 Hz stereo 16-bit.

HRECORD record = BASS_RecordStart(44100, 2, 0, MyRecordProc, 0);