2015-06-30 21:13:02 +00:00
|
|
|
/*
|
|
|
|
* Copyright (c) 2015 Andrew Kelley
|
|
|
|
*
|
|
|
|
* This file is part of libsoundio, which is MIT licensed.
|
|
|
|
* See http://opensource.org/licenses/MIT
|
|
|
|
*/
|
|
|
|
|
|
|
|
#ifndef SOUNDIO_SOUNDIO_H
|
|
|
|
#define SOUNDIO_SOUNDIO_H
|
|
|
|
|
|
|
|
#include "config.h"
|
2015-07-01 08:02:44 +00:00
|
|
|
#include <stdbool.h>
|
2015-06-30 21:13:02 +00:00
|
|
|
|
|
|
|
#ifdef __cplusplus
|
2015-08-20 21:48:19 +00:00
|
|
|
#define SOUNDIO_EXTERN_C extern "C"
|
|
|
|
#else
|
|
|
|
#define SOUNDIO_EXTERN_C
|
|
|
|
#endif
|
|
|
|
|
|
|
|
#if defined(_WIN32)
|
|
|
|
#if defined(SOUNDIO_BUILDING_LIBRARY)
|
|
|
|
#define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __declspec(dllexport)
|
|
|
|
#else
|
|
|
|
#define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __declspec(dllimport)
|
|
|
|
#endif
|
|
|
|
#else
|
|
|
|
#define SOUNDIO_EXPORT SOUNDIO_EXTERN_C __attribute__((visibility ("default")))
|
2015-07-13 16:17:20 +00:00
|
|
|
#endif
|
2015-06-30 21:13:02 +00:00
|
|
|
|
2015-07-01 08:02:44 +00:00
|
|
|
enum SoundIoError {
|
|
|
|
SoundIoErrorNone,
|
|
|
|
SoundIoErrorNoMem,
|
|
|
|
SoundIoErrorInitAudioBackend,
|
|
|
|
SoundIoErrorSystemResources,
|
|
|
|
SoundIoErrorOpeningDevice,
|
2015-08-04 00:06:38 +00:00
|
|
|
SoundIoErrorNoSuchDevice,
|
2015-07-13 16:17:20 +00:00
|
|
|
SoundIoErrorInvalid,
|
|
|
|
SoundIoErrorBackendUnavailable,
|
2015-07-16 03:57:00 +00:00
|
|
|
SoundIoErrorStreaming,
|
|
|
|
SoundIoErrorIncompatibleDevice,
|
2015-07-25 01:43:14 +00:00
|
|
|
SoundIoErrorNoSuchClient,
|
2015-07-27 23:37:45 +00:00
|
|
|
SoundIoErrorIncompatibleBackend,
|
2015-07-28 20:36:31 +00:00
|
|
|
SoundIoErrorBackendDisconnected,
|
2015-07-29 19:05:27 +00:00
|
|
|
SoundIoErrorInterrupted,
|
2015-07-30 05:39:27 +00:00
|
|
|
SoundIoErrorUnderflow,
|
2015-08-01 20:00:46 +00:00
|
|
|
SoundIoErrorEncodingString,
|
2015-07-01 08:02:44 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
enum SoundIoChannelId {
|
2015-07-28 21:53:54 +00:00
|
|
|
// These channel ids are more commonly supported.
|
2015-07-01 08:02:44 +00:00
|
|
|
SoundIoChannelIdInvalid,
|
|
|
|
SoundIoChannelIdFrontLeft,
|
|
|
|
SoundIoChannelIdFrontRight,
|
|
|
|
SoundIoChannelIdFrontCenter,
|
2015-07-10 06:35:58 +00:00
|
|
|
SoundIoChannelIdLfe,
|
2015-07-01 08:02:44 +00:00
|
|
|
SoundIoChannelIdBackLeft,
|
|
|
|
SoundIoChannelIdBackRight,
|
2015-07-10 06:35:58 +00:00
|
|
|
SoundIoChannelIdFrontLeftCenter,
|
|
|
|
SoundIoChannelIdFrontRightCenter,
|
2015-07-01 08:02:44 +00:00
|
|
|
SoundIoChannelIdBackCenter,
|
|
|
|
SoundIoChannelIdSideLeft,
|
|
|
|
SoundIoChannelIdSideRight,
|
|
|
|
SoundIoChannelIdTopCenter,
|
|
|
|
SoundIoChannelIdTopFrontLeft,
|
|
|
|
SoundIoChannelIdTopFrontCenter,
|
|
|
|
SoundIoChannelIdTopFrontRight,
|
|
|
|
SoundIoChannelIdTopBackLeft,
|
|
|
|
SoundIoChannelIdTopBackCenter,
|
|
|
|
SoundIoChannelIdTopBackRight,
|
|
|
|
|
2015-07-28 21:53:54 +00:00
|
|
|
// These channel ids are less commonly supported.
|
2015-07-10 06:35:58 +00:00
|
|
|
SoundIoChannelIdBackLeftCenter,
|
|
|
|
SoundIoChannelIdBackRightCenter,
|
|
|
|
SoundIoChannelIdFrontLeftWide,
|
|
|
|
SoundIoChannelIdFrontRightWide,
|
|
|
|
SoundIoChannelIdFrontLeftHigh,
|
|
|
|
SoundIoChannelIdFrontCenterHigh,
|
|
|
|
SoundIoChannelIdFrontRightHigh,
|
|
|
|
SoundIoChannelIdTopFrontLeftCenter,
|
|
|
|
SoundIoChannelIdTopFrontRightCenter,
|
|
|
|
SoundIoChannelIdTopSideLeft,
|
|
|
|
SoundIoChannelIdTopSideRight,
|
|
|
|
SoundIoChannelIdLeftLfe,
|
|
|
|
SoundIoChannelIdRightLfe,
|
2015-08-02 05:10:43 +00:00
|
|
|
SoundIoChannelIdLfe2,
|
2015-07-10 06:35:58 +00:00
|
|
|
SoundIoChannelIdBottomCenter,
|
|
|
|
SoundIoChannelIdBottomLeftCenter,
|
|
|
|
SoundIoChannelIdBottomRightCenter,
|
2015-08-02 05:10:43 +00:00
|
|
|
|
|
|
|
// Mid/side recording
|
|
|
|
SoundIoChannelIdMsMid,
|
|
|
|
SoundIoChannelIdMsSide,
|
|
|
|
|
|
|
|
// first order ambisonic channels
|
|
|
|
SoundIoChannelIdAmbisonicW,
|
|
|
|
SoundIoChannelIdAmbisonicX,
|
|
|
|
SoundIoChannelIdAmbisonicY,
|
|
|
|
SoundIoChannelIdAmbisonicZ,
|
|
|
|
|
|
|
|
// X-Y Recording
|
|
|
|
SoundIoChannelIdXyX,
|
|
|
|
SoundIoChannelIdXyY,
|
|
|
|
|
|
|
|
// Other
|
|
|
|
SoundIoChannelIdHeadphonesLeft,
|
|
|
|
SoundIoChannelIdHeadphonesRight,
|
|
|
|
SoundIoChannelIdClickTrack,
|
|
|
|
SoundIoChannelIdForeignLanguage,
|
|
|
|
SoundIoChannelIdHearingImpaired,
|
|
|
|
SoundIoChannelIdNarration,
|
|
|
|
SoundIoChannelIdHaptic,
|
|
|
|
SoundIoChannelIdDialogCentricMix,
|
|
|
|
|
|
|
|
SoundIoChannelIdAux,
|
|
|
|
SoundIoChannelIdAux0,
|
|
|
|
SoundIoChannelIdAux1,
|
|
|
|
SoundIoChannelIdAux2,
|
|
|
|
SoundIoChannelIdAux3,
|
|
|
|
SoundIoChannelIdAux4,
|
|
|
|
SoundIoChannelIdAux5,
|
|
|
|
SoundIoChannelIdAux6,
|
|
|
|
SoundIoChannelIdAux7,
|
|
|
|
SoundIoChannelIdAux8,
|
|
|
|
SoundIoChannelIdAux9,
|
|
|
|
SoundIoChannelIdAux10,
|
|
|
|
SoundIoChannelIdAux11,
|
|
|
|
SoundIoChannelIdAux12,
|
|
|
|
SoundIoChannelIdAux13,
|
|
|
|
SoundIoChannelIdAux14,
|
|
|
|
SoundIoChannelIdAux15,
|
2015-07-01 08:02:44 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
enum SoundIoChannelLayoutId {
|
|
|
|
SoundIoChannelLayoutIdMono,
|
|
|
|
SoundIoChannelLayoutIdStereo,
|
|
|
|
SoundIoChannelLayoutId2Point1,
|
|
|
|
SoundIoChannelLayoutId3Point0,
|
|
|
|
SoundIoChannelLayoutId3Point0Back,
|
|
|
|
SoundIoChannelLayoutId3Point1,
|
|
|
|
SoundIoChannelLayoutId4Point0,
|
|
|
|
SoundIoChannelLayoutIdQuad,
|
|
|
|
SoundIoChannelLayoutIdQuadSide,
|
2015-07-28 21:53:54 +00:00
|
|
|
SoundIoChannelLayoutId4Point1,
|
2015-07-01 08:02:44 +00:00
|
|
|
SoundIoChannelLayoutId5Point0Back,
|
2015-07-28 22:23:08 +00:00
|
|
|
SoundIoChannelLayoutId5Point0Side,
|
2015-07-01 08:02:44 +00:00
|
|
|
SoundIoChannelLayoutId5Point1,
|
|
|
|
SoundIoChannelLayoutId5Point1Back,
|
2015-07-28 22:23:08 +00:00
|
|
|
SoundIoChannelLayoutId6Point0Side,
|
2015-07-01 08:02:44 +00:00
|
|
|
SoundIoChannelLayoutId6Point0Front,
|
|
|
|
SoundIoChannelLayoutIdHexagonal,
|
|
|
|
SoundIoChannelLayoutId6Point1,
|
|
|
|
SoundIoChannelLayoutId6Point1Back,
|
|
|
|
SoundIoChannelLayoutId6Point1Front,
|
|
|
|
SoundIoChannelLayoutId7Point0,
|
|
|
|
SoundIoChannelLayoutId7Point0Front,
|
|
|
|
SoundIoChannelLayoutId7Point1,
|
|
|
|
SoundIoChannelLayoutId7Point1Wide,
|
|
|
|
SoundIoChannelLayoutId7Point1WideBack,
|
|
|
|
SoundIoChannelLayoutIdOctagonal,
|
|
|
|
};
|
|
|
|
|
2015-06-30 21:13:02 +00:00
|
|
|
enum SoundIoBackend {
|
2015-07-01 09:53:53 +00:00
|
|
|
SoundIoBackendNone,
|
2015-07-25 01:43:14 +00:00
|
|
|
SoundIoBackendJack,
|
2015-06-30 21:13:02 +00:00
|
|
|
SoundIoBackendPulseAudio,
|
2015-07-07 09:55:32 +00:00
|
|
|
SoundIoBackendAlsa,
|
2015-08-01 01:52:51 +00:00
|
|
|
SoundIoBackendCoreAudio,
|
2015-08-08 22:22:50 +00:00
|
|
|
SoundIoBackendWasapi,
|
2015-06-30 21:13:02 +00:00
|
|
|
SoundIoBackendDummy,
|
|
|
|
};
|
|
|
|
|
2015-07-30 17:39:10 +00:00
|
|
|
enum SoundIoDeviceAim {
|
|
|
|
SoundIoDeviceAimInput,
|
|
|
|
SoundIoDeviceAimOutput,
|
2015-07-01 08:02:44 +00:00
|
|
|
};
|
|
|
|
|
2015-07-10 09:21:47 +00:00
|
|
|
enum SoundIoFormat {
|
|
|
|
SoundIoFormatInvalid,
|
2015-07-22 22:43:45 +00:00
|
|
|
SoundIoFormatS8, // Signed 8 bit
|
|
|
|
SoundIoFormatU8, // Unsigned 8 bit
|
|
|
|
SoundIoFormatS16LE, // Signed 16 bit Little Endian
|
|
|
|
SoundIoFormatS16BE, // Signed 16 bit Big Endian
|
|
|
|
SoundIoFormatU16LE, // Unsigned 16 bit Little Endian
|
|
|
|
SoundIoFormatU16BE, // Unsigned 16 bit Little Endian
|
|
|
|
SoundIoFormatS24LE, // Signed 24 bit Little Endian using low three bytes in 32-bit word
|
|
|
|
SoundIoFormatS24BE, // Signed 24 bit Big Endian using low three bytes in 32-bit word
|
|
|
|
SoundIoFormatU24LE, // Unsigned 24 bit Little Endian using low three bytes in 32-bit word
|
|
|
|
SoundIoFormatU24BE, // Unsigned 24 bit Big Endian using low three bytes in 32-bit word
|
|
|
|
SoundIoFormatS32LE, // Signed 32 bit Little Endian
|
|
|
|
SoundIoFormatS32BE, // Signed 32 bit Big Endian
|
|
|
|
SoundIoFormatU32LE, // Unsigned 32 bit Little Endian
|
|
|
|
SoundIoFormatU32BE, // Unsigned 32 bit Big Endian
|
|
|
|
SoundIoFormatFloat32LE, // Float 32 bit Little Endian, Range -1.0 to 1.0
|
|
|
|
SoundIoFormatFloat32BE, // Float 32 bit Big Endian, Range -1.0 to 1.0
|
|
|
|
SoundIoFormatFloat64LE, // Float 64 bit Little Endian, Range -1.0 to 1.0
|
|
|
|
SoundIoFormatFloat64BE, // Float 64 bit Big Endian, Range -1.0 to 1.0
|
2015-07-01 08:02:44 +00:00
|
|
|
};
|
|
|
|
|
2015-07-13 16:59:42 +00:00
|
|
|
// For your convenience, Native Endian and Foreign Endian constants are defined
|
|
|
|
// which point to the respective SoundIoFormat values.
|
|
|
|
|
2015-07-10 07:46:03 +00:00
|
|
|
#if defined(SOUNDIO_OS_BIG_ENDIAN)
|
2015-07-10 09:21:47 +00:00
|
|
|
#define SoundIoFormatS16NE SoundIoFormatS16BE
|
|
|
|
#define SoundIoFormatU16NE SoundIoFormatU16BE
|
|
|
|
#define SoundIoFormatS24NE SoundIoFormatS24BE
|
|
|
|
#define SoundIoFormatU24NE SoundIoFormatU24BE
|
|
|
|
#define SoundIoFormatS32NE SoundIoFormatS32BE
|
|
|
|
#define SoundIoFormatU32NE SoundIoFormatU32BE
|
|
|
|
#define SoundIoFormatFloat32NE SoundIoFormatFloat32BE
|
|
|
|
#define SoundIoFormatFloat64NE SoundIoFormatFloat64BE
|
2015-07-13 16:59:42 +00:00
|
|
|
|
|
|
|
#define SoundIoFormatS16FE SoundIoFormatS16LE
|
|
|
|
#define SoundIoFormatU16FE SoundIoFormatU16LE
|
|
|
|
#define SoundIoFormatS24FE SoundIoFormatS24LE
|
|
|
|
#define SoundIoFormatU24FE SoundIoFormatU24LE
|
|
|
|
#define SoundIoFormatS32FE SoundIoFormatS32LE
|
|
|
|
#define SoundIoFormatU32FE SoundIoFormatU32LE
|
|
|
|
#define SoundIoFormatFloat32FE SoundIoFormatFloat32LE
|
|
|
|
#define SoundIoFormatFloat64FE SoundIoFormatFloat64LE
|
|
|
|
|
2015-07-10 07:46:03 +00:00
|
|
|
#elif defined(SOUNDIO_OS_LITTLE_ENDIAN)
|
2015-07-13 16:59:42 +00:00
|
|
|
|
2015-07-10 09:21:47 +00:00
|
|
|
#define SoundIoFormatS16NE SoundIoFormatS16LE
|
|
|
|
#define SoundIoFormatU16NE SoundIoFormatU16LE
|
|
|
|
#define SoundIoFormatS24NE SoundIoFormatS24LE
|
|
|
|
#define SoundIoFormatU24NE SoundIoFormatU24LE
|
|
|
|
#define SoundIoFormatS32NE SoundIoFormatS32LE
|
|
|
|
#define SoundIoFormatU32NE SoundIoFormatU32LE
|
|
|
|
#define SoundIoFormatFloat32NE SoundIoFormatFloat32LE
|
|
|
|
#define SoundIoFormatFloat64NE SoundIoFormatFloat64LE
|
2015-07-13 16:59:42 +00:00
|
|
|
|
|
|
|
#define SoundIoFormatS16FE SoundIoFormatS16BE
|
|
|
|
#define SoundIoFormatU16FE SoundIoFormatU16BE
|
|
|
|
#define SoundIoFormatS24FE SoundIoFormatS24BE
|
|
|
|
#define SoundIoFormatU24FE SoundIoFormatU24BE
|
|
|
|
#define SoundIoFormatS32FE SoundIoFormatS32BE
|
|
|
|
#define SoundIoFormatU32FE SoundIoFormatU32BE
|
|
|
|
#define SoundIoFormatFloat32FE SoundIoFormatFloat32BE
|
|
|
|
#define SoundIoFormatFloat64FE SoundIoFormatFloat64BE
|
|
|
|
|
2015-07-10 10:31:51 +00:00
|
|
|
#else
|
|
|
|
#error unknown byte order
|
2015-07-10 07:46:03 +00:00
|
|
|
#endif
|
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// The size of this struct is OK to use.
|
2015-07-16 03:57:00 +00:00
|
|
|
#define SOUNDIO_MAX_CHANNELS 24
|
2015-07-13 16:17:20 +00:00
|
|
|
struct SoundIoChannelLayout {
|
|
|
|
const char *name;
|
|
|
|
int channel_count;
|
|
|
|
enum SoundIoChannelId channels[SOUNDIO_MAX_CHANNELS];
|
|
|
|
};
|
|
|
|
|
2015-08-08 21:44:31 +00:00
|
|
|
// The size of this struct is OK to use.
|
|
|
|
struct SoundIoSampleRateRange {
|
|
|
|
int min;
|
|
|
|
int max;
|
|
|
|
};
|
|
|
|
|
|
|
|
// The size of this struct is OK to use.
|
2015-07-16 03:57:00 +00:00
|
|
|
struct SoundIoChannelArea {
|
|
|
|
// Base address of buffer.
|
|
|
|
char *ptr;
|
|
|
|
// How many bytes it takes to get from the beginning of one sample to
|
|
|
|
// the beginning of the next sample.
|
|
|
|
int step;
|
|
|
|
};
|
2015-07-14 04:30:37 +00:00
|
|
|
|
2015-07-21 03:13:35 +00:00
|
|
|
// The size of this struct is not part of the API or ABI.
|
|
|
|
struct SoundIo {
|
2015-07-25 05:00:33 +00:00
|
|
|
// Optional. Put whatever you want here. Defaults to NULL.
|
2015-07-21 03:13:35 +00:00
|
|
|
void *userdata;
|
|
|
|
// Optional callback. Called when the list of devices change. Only called
|
|
|
|
// during a call to soundio_flush_events or soundio_wait_events.
|
|
|
|
void (*on_devices_change)(struct SoundIo *);
|
2015-07-28 20:36:31 +00:00
|
|
|
// Optional callback. Called when the backend disconnects. For example,
|
|
|
|
// when the JACK server shuts down. When this happens, listing devices
|
|
|
|
// and opening streams will always fail with
|
|
|
|
// SoundIoErrorBackendDisconnected. This callback is only called during a
|
2015-08-02 05:10:43 +00:00
|
|
|
// call to `soundio_flush_events` or `soundio_wait_events`.
|
|
|
|
// If you do not supply a callback, the default will crash your program
|
|
|
|
// with an error message.
|
2015-07-30 07:46:13 +00:00
|
|
|
void (*on_backend_disconnect)(struct SoundIo *, int err);
|
2015-07-21 03:13:35 +00:00
|
|
|
// Optional callback. Called from an unknown thread that you should not use
|
|
|
|
// to call any soundio functions. You may use this to signal a condition
|
|
|
|
// variable to wake up. Called when soundio_wait_events would be woken up.
|
|
|
|
void (*on_events_signal)(struct SoundIo *);
|
2015-07-21 05:55:30 +00:00
|
|
|
|
2015-07-25 01:43:14 +00:00
|
|
|
// Optional: Application name.
|
|
|
|
// PulseAudio uses this for "application name".
|
|
|
|
// JACK uses this for `client_name`.
|
2015-07-27 23:37:45 +00:00
|
|
|
// Must not contain a colon (":").
|
2015-07-21 05:55:30 +00:00
|
|
|
const char *app_name;
|
2015-07-25 02:16:48 +00:00
|
|
|
|
|
|
|
// Optional: JACK info and error callbacks.
|
|
|
|
// By default, libsoundio sets these to empty functions in order to
|
|
|
|
// silence stdio messages from JACK. You may override the behavior by
|
2015-07-25 05:00:33 +00:00
|
|
|
// setting these to `NULL` or providing your own function. These are
|
|
|
|
// registered with JACK regardless of whether `soundio_connect_backend`
|
|
|
|
// succeeds.
|
2015-07-25 02:16:48 +00:00
|
|
|
void (*jack_info_callback)(const char *msg);
|
|
|
|
void (*jack_error_callback)(const char *msg);
|
2015-07-25 05:00:33 +00:00
|
|
|
|
|
|
|
// Read-only. After calling `soundio_connect` or `soundio_connect_backend`,
|
|
|
|
// this field tells which backend is currently connected.
|
|
|
|
enum SoundIoBackend current_backend;
|
2015-07-21 03:13:35 +00:00
|
|
|
};
|
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// The size of this struct is not part of the API or ABI.
|
2015-07-01 08:02:44 +00:00
|
|
|
struct SoundIoDevice {
|
2015-07-13 16:17:20 +00:00
|
|
|
// Read-only. Set automatically.
|
2015-07-01 08:02:44 +00:00
|
|
|
struct SoundIo *soundio;
|
2015-07-10 09:21:47 +00:00
|
|
|
|
2015-07-30 17:26:36 +00:00
|
|
|
// `id` is a string of bytes that uniquely identifies this device.
|
|
|
|
// `name` is user-friendly UTF-8 encoded text to describe the device.
|
2015-07-30 17:46:25 +00:00
|
|
|
// If the same physical device supports both input and output, that makes
|
|
|
|
// one SoundIoDevice for the input and one SoundIoDevice for the output.
|
|
|
|
// In this case, the `id` of each SoundIoDevice will be the same, and the
|
2015-08-13 00:11:03 +00:00
|
|
|
// `aim` field will be different. Additionally, if the device supports raw
|
|
|
|
// mode, there may be up to four devices with the same id: one for each
|
|
|
|
// value of `is_raw` and one for each value of `aim`.
|
2015-07-30 17:26:36 +00:00
|
|
|
char *id;
|
2015-07-01 08:02:44 +00:00
|
|
|
char *name;
|
2015-07-08 07:42:17 +00:00
|
|
|
|
2015-07-30 17:39:10 +00:00
|
|
|
// Tells whether this device is an input device or an output device.
|
|
|
|
enum SoundIoDeviceAim aim;
|
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// Channel layouts are handled similarly to sample format; see those docs.
|
|
|
|
// If this information is missing due to a `probe_error`, `layouts`
|
|
|
|
// will be NULL. It's OK to modify this data, for example calling
|
|
|
|
// soundio_sort_channel_layouts on it.
|
|
|
|
// Devices are guaranteed to have at least 1 channel layout.
|
|
|
|
struct SoundIoChannelLayout *layouts;
|
|
|
|
int layout_count;
|
|
|
|
struct SoundIoChannelLayout current_layout;
|
2015-07-10 06:35:58 +00:00
|
|
|
|
2015-07-10 09:21:47 +00:00
|
|
|
// A device is either a raw device or it is a virtual device that is
|
|
|
|
// provided by a software mixing service such as dmix or PulseAudio (see
|
|
|
|
// `is_raw`). If it is a raw device, `current_format` is meaningless;
|
|
|
|
// the device has no current format until you open it. On the other hand,
|
|
|
|
// if it is a virtual device, `current_format` describes the destination
|
|
|
|
// sample format that your audio will be converted to. Or, if you're the
|
|
|
|
// lucky first application to open the device, you might cause the
|
|
|
|
// `current_format` to change to your format. Generally, you want to
|
|
|
|
// ignore `current_format` and use whatever format is most convenient
|
|
|
|
// for you which is supported by the device, because when you are the only
|
|
|
|
// application left, the mixer might decide to switch `current_format` to
|
|
|
|
// yours. You can learn the supported formats via `formats` and
|
|
|
|
// `format_count`. If this information is missing due to a probe error,
|
|
|
|
// `formats` will be `NULL`. If `current_format` is unavailable, it will be
|
|
|
|
// set to `SoundIoFormatInvalid`.
|
2015-07-13 16:17:20 +00:00
|
|
|
// Devices are guaranteed to have at least 1 format available.
|
2015-07-10 09:21:47 +00:00
|
|
|
enum SoundIoFormat *formats;
|
|
|
|
int format_count;
|
|
|
|
enum SoundIoFormat current_format;
|
|
|
|
|
2015-07-22 22:43:45 +00:00
|
|
|
// Sample rate is the number of frames per second.
|
2015-07-10 09:21:47 +00:00
|
|
|
// Sample rate is handled very similar to sample format; see those docs.
|
|
|
|
// If sample rate information is missing due to a probe error, the field
|
2015-08-08 21:44:31 +00:00
|
|
|
// will be set to 0 or NULL.
|
|
|
|
// Devices which have `probe_error` set to `SoundIoErrorNone` are
|
|
|
|
// guaranteed to have at least 1 sample rate available.
|
|
|
|
struct SoundIoSampleRateRange *sample_rates;
|
|
|
|
int sample_rate_count;
|
2015-07-10 09:21:47 +00:00
|
|
|
int sample_rate_current;
|
2015-07-08 07:42:17 +00:00
|
|
|
|
2015-08-14 05:54:15 +00:00
|
|
|
// Software latency in seconds. If any of these values are unknown or
|
|
|
|
// irrelevant, they are set to 0.0.
|
|
|
|
// For PulseAudio and WASAPI these values are unknown until you open a
|
|
|
|
// stream.
|
|
|
|
double software_latency_min;
|
|
|
|
double software_latency_max;
|
|
|
|
double software_latency_current;
|
2015-07-10 09:21:47 +00:00
|
|
|
|
2015-07-25 05:00:33 +00:00
|
|
|
// Raw means that you are directly opening the hardware device and not
|
|
|
|
// going through a proxy such as dmix, PulseAudio, or JACK. When you open a
|
|
|
|
// raw device, other applications on the computer are not able to
|
2015-07-10 09:21:47 +00:00
|
|
|
// simultaneously access the device. Raw devices do not perform automatic
|
|
|
|
// resampling and thus tend to have fewer formats available.
|
2015-07-08 06:29:09 +00:00
|
|
|
bool is_raw;
|
2015-07-10 09:21:47 +00:00
|
|
|
|
|
|
|
// Devices are reference counted. See `soundio_device_ref` and
|
|
|
|
// `soundio_device_unref`.
|
|
|
|
int ref_count;
|
|
|
|
|
|
|
|
// This is set to a SoundIoError representing the result of the device
|
|
|
|
// probe. Ideally this will be SoundIoErrorNone in which case all the
|
|
|
|
// fields of the device will be populated. If there is an error code here
|
|
|
|
// then information about formats, sample rates, and channel layouts might
|
|
|
|
// be missing.
|
|
|
|
int probe_error;
|
2015-07-01 08:02:44 +00:00
|
|
|
};
|
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// The size of this struct is not part of the API or ABI.
|
2015-07-10 09:42:29 +00:00
|
|
|
struct SoundIoOutStream {
|
2015-07-14 04:30:37 +00:00
|
|
|
// Populated automatically when you call soundio_outstream_create.
|
2015-07-01 08:02:44 +00:00
|
|
|
struct SoundIoDevice *device;
|
2015-07-14 04:30:37 +00:00
|
|
|
|
|
|
|
// Defaults to SoundIoFormatFloat32NE, followed by the first one supported.
|
2015-07-10 09:21:47 +00:00
|
|
|
enum SoundIoFormat format;
|
2015-07-14 04:30:37 +00:00
|
|
|
|
2015-07-22 22:43:45 +00:00
|
|
|
// Sample rate is the number of frames per second.
|
2015-07-14 04:30:37 +00:00
|
|
|
// Defaults to 48000 (and then clamped into range).
|
2015-07-08 07:42:17 +00:00
|
|
|
int sample_rate;
|
2015-07-14 04:30:37 +00:00
|
|
|
|
|
|
|
// Defaults to Stereo, if available, followed by the first layout supported.
|
2015-07-13 16:17:20 +00:00
|
|
|
struct SoundIoChannelLayout layout;
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-08-14 05:54:15 +00:00
|
|
|
// Ignoring hardware latency, this is the number of seconds it takes for
|
|
|
|
// the last sample in a full buffer to be played.
|
|
|
|
// After you call `soundio_outstream_open`, this value is replaced with the
|
|
|
|
// actual software latency, as near to this value as possible.
|
|
|
|
// On systems that support clearing the buffer, this defaults to a large
|
|
|
|
// latency, potentially upwards of 2 seconds, with the understanding that
|
|
|
|
// you will call `soundio_outstream_clear_buffer` when you want to reduce
|
|
|
|
// the latency to 0. On systems that do not support clearing the buffer,
|
|
|
|
// this defaults to a reasonable lower latency value.
|
|
|
|
// If the device has unknown software latency min and max values, you may
|
|
|
|
// still set this, but you might not get the value you requested.
|
|
|
|
// For PulseAudio, if you set this value to non-default, it sets
|
2015-08-04 19:25:15 +00:00
|
|
|
// `PA_STREAM_ADJUST_LATENCY` and is the value used for `maxlength` and
|
2015-08-04 20:09:45 +00:00
|
|
|
// `tlength`.
|
2015-08-14 05:54:15 +00:00
|
|
|
// For JACK, this value is always equal to `software_latency_current` of
|
|
|
|
// the device.
|
|
|
|
double software_latency;
|
2015-07-14 04:30:37 +00:00
|
|
|
|
2015-07-16 20:37:41 +00:00
|
|
|
// Defaults to NULL. Put whatever you want here.
|
2015-07-01 08:02:44 +00:00
|
|
|
void *userdata;
|
2015-07-23 22:04:41 +00:00
|
|
|
// In this callback, you call `soundio_outstream_begin_write` and
|
2015-08-04 07:56:03 +00:00
|
|
|
// `soundio_outstream_end_write` as many times as necessary to write
|
2015-08-05 04:57:46 +00:00
|
|
|
// at minimum `frame_count_min` frames and at maximum `frame_count_max`
|
|
|
|
// frames. `frame_count_max` will always be greater than 0. Note that you
|
|
|
|
// should write as many frames as you can; `frame_count_min` might be 0 and
|
|
|
|
// you can still get a buffer underflow if you always write
|
|
|
|
// `frame_count_min` frames. See `sio_sine.c` for example.
|
|
|
|
// For Dummy, ALSA, and PulseAudio, `frame_count_min` will be 0. For JACK
|
|
|
|
// and CoreAudio `frame_count_min` will be equal to `frame_count_max`.
|
|
|
|
void (*write_callback)(struct SoundIoOutStream *,
|
|
|
|
int frame_count_min, int frame_count_max);
|
2015-07-23 22:04:41 +00:00
|
|
|
// This optional callback happens when the sound device runs out of buffered
|
|
|
|
// audio data to play. After this occurs, the outstream waits until the
|
|
|
|
// buffer is full to resume playback.
|
2015-07-24 21:03:49 +00:00
|
|
|
// This is called from the `write_callback` thread context.
|
2015-07-23 22:04:41 +00:00
|
|
|
void (*underflow_callback)(struct SoundIoOutStream *);
|
|
|
|
// Optional callback. `err` is always SoundIoErrorStreaming.
|
2015-07-16 03:57:00 +00:00
|
|
|
// SoundIoErrorStreaming is an unrecoverable error. The stream is in an
|
|
|
|
// invalid state and must be destroyed.
|
2015-07-23 22:04:41 +00:00
|
|
|
// If you do not supply `error_callback`, the default callback will print
|
|
|
|
// a message to stderr and then call `abort`.
|
2015-07-25 05:00:33 +00:00
|
|
|
// This is called from the `write_callback` thread context.
|
2015-07-16 03:57:00 +00:00
|
|
|
void (*error_callback)(struct SoundIoOutStream *, int err);
|
2015-07-13 16:17:20 +00:00
|
|
|
|
2015-07-25 05:00:33 +00:00
|
|
|
// Optional: Name of the stream. Defaults to "SoundIoOutStream"
|
|
|
|
// PulseAudio uses this for the stream name.
|
|
|
|
// JACK uses this for the client name of the client that connects when you
|
|
|
|
// open the stream.
|
2015-07-27 23:37:45 +00:00
|
|
|
// Must not contain a colon (":").
|
2015-07-21 03:13:35 +00:00
|
|
|
const char *name;
|
|
|
|
|
2015-07-27 23:37:45 +00:00
|
|
|
// Optional: Hint that this output stream is nonterminal. This is used by
|
|
|
|
// JACK and it means that the output stream data originates from an input
|
|
|
|
// stream. Defaults to `false`.
|
|
|
|
bool non_terminal_hint;
|
|
|
|
|
2015-07-22 07:04:17 +00:00
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// computed automatically when you call soundio_outstream_open
|
|
|
|
int bytes_per_frame;
|
2015-07-16 03:57:00 +00:00
|
|
|
int bytes_per_sample;
|
2015-07-22 07:04:17 +00:00
|
|
|
|
|
|
|
// If setting the channel layout fails for some reason, this field is set
|
|
|
|
// to an error code. Possible error codes are: SoundIoErrorIncompatibleDevice
|
|
|
|
int layout_error;
|
2015-07-01 08:02:44 +00:00
|
|
|
};
|
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// The size of this struct is not part of the API or ABI.
|
2015-07-10 09:42:29 +00:00
|
|
|
struct SoundIoInStream {
|
2015-07-14 04:30:37 +00:00
|
|
|
// Populated automatically when you call soundio_outstream_create.
|
2015-07-01 08:02:44 +00:00
|
|
|
struct SoundIoDevice *device;
|
2015-07-14 04:30:37 +00:00
|
|
|
|
|
|
|
// Defaults to SoundIoFormatFloat32NE, followed by the first one supported.
|
2015-07-10 09:21:47 +00:00
|
|
|
enum SoundIoFormat format;
|
2015-07-14 04:30:37 +00:00
|
|
|
|
2015-07-22 22:43:45 +00:00
|
|
|
// Sample rate is the number of frames per second.
|
2015-07-14 04:30:37 +00:00
|
|
|
// Defaults to max(sample_rate_min, min(sample_rate_max, 48000))
|
2015-07-08 07:42:17 +00:00
|
|
|
int sample_rate;
|
2015-07-14 04:30:37 +00:00
|
|
|
|
|
|
|
// Defaults to Stereo, if available, followed by the first layout supported.
|
2015-07-13 16:17:20 +00:00
|
|
|
struct SoundIoChannelLayout layout;
|
2015-07-14 04:30:37 +00:00
|
|
|
|
2015-08-14 05:54:15 +00:00
|
|
|
// Ignoring hardware latency, this is the number of seconds it takes for a
|
|
|
|
// captured sample to become available for reading.
|
|
|
|
// After you call `soundio_instream_open`, this value is replaced with the
|
|
|
|
// actual software latency, as near to this value as possible.
|
|
|
|
// A higher value means less CPU usage. Defaults to a large value,
|
|
|
|
// potentially upwards of 2 seconds.
|
|
|
|
// If the device has unknown software latency min and max values, you may
|
|
|
|
// still set this, but you might not get the value you requested.
|
|
|
|
// For PulseAudio, if you set this value to non-default, it sets
|
2015-07-30 04:50:12 +00:00
|
|
|
// `PA_STREAM_ADJUST_LATENCY` and is the value used for `fragsize`.
|
2015-08-14 05:54:15 +00:00
|
|
|
// For JACK, this value is always equal to `software_latency_current` of
|
|
|
|
// the device.
|
|
|
|
double software_latency;
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-16 20:37:41 +00:00
|
|
|
// Defaults to NULL. Put whatever you want here.
|
2015-07-01 08:02:44 +00:00
|
|
|
void *userdata;
|
2015-07-23 22:04:41 +00:00
|
|
|
// In this function call `soundio_instream_begin_read` and
|
2015-08-05 04:57:46 +00:00
|
|
|
// `soundio_instream_end_read` as many times as necessary to read at
|
|
|
|
// minimum `frame_count_min` frames and at maximum `frame_count_max`
|
|
|
|
// frames. If you return from `read_callback` without having read
|
|
|
|
// `frame_count_min`, the frames will be dropped. `frame_count_max` is how
|
|
|
|
// many frames are available to read.
|
|
|
|
void (*read_callback)(struct SoundIoInStream *, int frame_count_min, int frame_count_max);
|
2015-07-23 22:04:41 +00:00
|
|
|
// Optional callback. `err` is always SoundIoErrorStreaming.
|
|
|
|
// SoundIoErrorStreaming is an unrecoverable error. The stream is in an
|
|
|
|
// invalid state and must be destroyed.
|
|
|
|
// If you do not supply `error_callback`, the default callback will print
|
|
|
|
// a message to stderr and then abort().
|
2015-07-24 21:03:49 +00:00
|
|
|
// This is called from the `read_callback` thread context.
|
2015-07-23 22:04:41 +00:00
|
|
|
void (*error_callback)(struct SoundIoInStream *, int err);
|
2015-07-13 16:17:20 +00:00
|
|
|
|
2015-07-25 05:00:33 +00:00
|
|
|
// Optional: Name of the stream. Defaults to "SoundIoInStream";
|
|
|
|
// PulseAudio uses this for the stream name.
|
|
|
|
// JACK uses this for the client name of the client that connects when you
|
|
|
|
// open the stream.
|
2015-07-27 23:37:45 +00:00
|
|
|
// Must not contain a colon (":").
|
2015-07-21 03:13:35 +00:00
|
|
|
const char *name;
|
|
|
|
|
2015-07-29 01:47:28 +00:00
|
|
|
// Optional: Hint that this input stream is nonterminal. This is used by
|
|
|
|
// JACK and it means that the data received by the stream will be
|
|
|
|
// passed on or made available to another stream. Defaults to `false`.
|
|
|
|
// stream. Defaults to `false`.
|
|
|
|
bool non_terminal_hint;
|
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// computed automatically when you call soundio_instream_open
|
|
|
|
int bytes_per_frame;
|
2015-07-16 03:57:00 +00:00
|
|
|
int bytes_per_sample;
|
2015-07-24 03:55:36 +00:00
|
|
|
|
|
|
|
// If setting the channel layout fails for some reason, this field is set
|
|
|
|
// to an error code. Possible error codes are: SoundIoErrorIncompatibleDevice
|
|
|
|
int layout_error;
|
2015-07-01 08:02:44 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
// Main Context
|
|
|
|
|
2015-07-18 07:22:32 +00:00
|
|
|
// Create a SoundIo context. You may create multiple instances of this to
|
|
|
|
// connect to multiple backends.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT struct SoundIo * soundio_create(void);
|
|
|
|
SOUNDIO_EXPORT void soundio_destroy(struct SoundIo *soundio);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
|
2015-07-25 02:16:48 +00:00
|
|
|
// This is a convenience function you could implement yourself if you wanted
|
|
|
|
// to. It tries `soundio_connect_backend` on all available backends in order.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_connect(struct SoundIo *soundio);
|
2015-07-13 16:17:20 +00:00
|
|
|
// Instead of calling `soundio_connect` you may call this function to try a
|
2015-08-01 01:53:39 +00:00
|
|
|
// specific backend.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_connect_backend(struct SoundIo *soundio, enum SoundIoBackend backend);
|
|
|
|
SOUNDIO_EXPORT void soundio_disconnect(struct SoundIo *soundio);
|
2015-07-01 09:53:53 +00:00
|
|
|
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT const char *soundio_strerror(int error);
|
|
|
|
SOUNDIO_EXPORT const char *soundio_backend_name(enum SoundIoBackend backend);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-22 22:43:45 +00:00
|
|
|
// Returns the number of available backends.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_backend_count(struct SoundIo *soundio);
|
2015-07-22 22:43:45 +00:00
|
|
|
// get the available backend at the specified index
|
|
|
|
// (0 <= index < `soundio_backend_count`)
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT enum SoundIoBackend soundio_get_backend(struct SoundIo *soundio, int index);
|
2015-07-13 16:17:20 +00:00
|
|
|
|
2015-07-23 18:56:05 +00:00
|
|
|
// Returns whether libsoundio was compiled with `backend`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT bool soundio_have_backend(enum SoundIoBackend backend);
|
2015-07-23 18:56:05 +00:00
|
|
|
|
2015-07-29 19:05:27 +00:00
|
|
|
// When you call this, the `on_devices_change` and `on_events_signal` callbacks
|
2015-07-20 05:36:50 +00:00
|
|
|
// might be called. This is the only time those callbacks will be called.
|
2015-07-29 19:05:27 +00:00
|
|
|
// This must be called from the same thread as the thread in which you call
|
|
|
|
// these functions:
|
|
|
|
// * `soundio_input_device_count`
|
|
|
|
// * `soundio_output_device_count`
|
|
|
|
// * `soundio_get_input_device`
|
|
|
|
// * `soundio_get_output_device`
|
|
|
|
// * `soundio_default_input_device_index`
|
|
|
|
// * `soundio_default_output_device_index`
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT void soundio_flush_events(struct SoundIo *soundio);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-29 19:05:27 +00:00
|
|
|
// This function calls `soundio_flush_events` then blocks until another event
|
|
|
|
// is ready or you call `soundio_wakeup`. Be ready for spurious wakeups.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT void soundio_wait_events(struct SoundIo *soundio);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-29 19:05:27 +00:00
|
|
|
// Makes `soundio_wait_events` stop blocking.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT void soundio_wakeup(struct SoundIo *soundio);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
// Channel Layouts
|
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// Returns whether the channel count field and each channel id matches in
|
|
|
|
// the supplied channel layouts.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT bool soundio_channel_layout_equal(
|
2015-07-13 16:17:20 +00:00
|
|
|
const struct SoundIoChannelLayout *a,
|
2015-07-01 08:02:44 +00:00
|
|
|
const struct SoundIoChannelLayout *b);
|
|
|
|
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT const char *soundio_get_channel_name(enum SoundIoChannelId id);
|
2015-07-28 18:28:07 +00:00
|
|
|
// Given UTF-8 encoded text which is the name of a channel such as
|
|
|
|
// "Front Left", "FL", or "front-left", return the corresponding
|
|
|
|
// SoundIoChannelId. Returns SoundIoChannelIdInvalid for no match.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT enum SoundIoChannelId soundio_parse_channel_id(const char *str, int str_len);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_channel_layout_builtin_count(void);
|
|
|
|
SOUNDIO_EXPORT const struct SoundIoChannelLayout *soundio_channel_layout_get_builtin(int index);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-27 18:27:41 +00:00
|
|
|
// Get the default builtin channel layout for the given number of channels.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT const struct SoundIoChannelLayout *soundio_channel_layout_get_default(int channel_count);
|
2015-07-27 18:27:41 +00:00
|
|
|
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_channel_layout_find_channel(
|
2015-07-01 08:02:44 +00:00
|
|
|
const struct SoundIoChannelLayout *layout, enum SoundIoChannelId channel);
|
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// Populates the name field of layout if it matches a builtin one.
|
2015-07-10 06:35:58 +00:00
|
|
|
// returns whether it found a match
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT bool soundio_channel_layout_detect_builtin(struct SoundIoChannelLayout *layout);
|
2015-07-10 06:35:58 +00:00
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// Iterates over preferred_layouts. Returns the first channel layout in
|
|
|
|
// preferred_layouts which matches one of the channel layouts in
|
|
|
|
// available_layouts. Returns NULL if none matches.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT const struct SoundIoChannelLayout *soundio_best_matching_channel_layout(
|
2015-07-13 16:17:20 +00:00
|
|
|
const struct SoundIoChannelLayout *preferred_layouts, int preferred_layout_count,
|
|
|
|
const struct SoundIoChannelLayout *available_layouts, int available_layout_count);
|
|
|
|
|
|
|
|
// Sorts by channel count, descending.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT void soundio_sort_channel_layouts(struct SoundIoChannelLayout *layouts, int layout_count);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
|
|
|
|
|
|
|
// Sample Formats
|
|
|
|
|
2015-07-30 07:46:13 +00:00
|
|
|
// Returns -1 on invalid format.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_get_bytes_per_sample(enum SoundIoFormat format);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-10 09:21:47 +00:00
|
|
|
static inline int soundio_get_bytes_per_frame(enum SoundIoFormat format, int channel_count) {
|
|
|
|
return soundio_get_bytes_per_sample(format) * channel_count;
|
2015-07-01 08:02:44 +00:00
|
|
|
}
|
|
|
|
|
2015-07-22 22:43:45 +00:00
|
|
|
// Sample rate is the number of frames per second.
|
2015-07-10 09:21:47 +00:00
|
|
|
static inline int soundio_get_bytes_per_second(enum SoundIoFormat format,
|
2015-07-01 08:02:44 +00:00
|
|
|
int channel_count, int sample_rate)
|
|
|
|
{
|
2015-07-10 09:21:47 +00:00
|
|
|
return soundio_get_bytes_per_frame(format, channel_count) * sample_rate;
|
2015-07-01 08:02:44 +00:00
|
|
|
}
|
|
|
|
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT const char * soundio_format_string(enum SoundIoFormat format);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
2015-07-10 07:46:03 +00:00
|
|
|
|
2015-07-01 08:02:44 +00:00
|
|
|
// Devices
|
|
|
|
|
2015-08-02 05:10:43 +00:00
|
|
|
// When you call `soundio_flush_events`, a snapshot of all device state is
|
|
|
|
// saved and these functions merely access the snapshot data. When you want
|
|
|
|
// to check for new devices, call `soundio_flush_events`. Or you can call
|
|
|
|
// `soundio_wait_events` to block until devices change. If an error occurs
|
|
|
|
// scanning devices in a background thread, `on_backend_disconnect` is called
|
|
|
|
// with the error code.
|
|
|
|
|
|
|
|
// Get the number of input devices.
|
|
|
|
// Returns -1 if you never called `soundio_flush_events`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_input_device_count(struct SoundIo *soundio);
|
2015-08-02 05:10:43 +00:00
|
|
|
// Get the number of output devices.
|
|
|
|
// Returns -1 if you never called `soundio_flush_events`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_output_device_count(struct SoundIo *soundio);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-22 22:43:45 +00:00
|
|
|
// Always returns a device. Call soundio_device_unref when done.
|
2015-07-24 03:55:36 +00:00
|
|
|
// `index` must be 0 <= index < soundio_input_device_count
|
2015-08-04 19:25:15 +00:00
|
|
|
// Returns NULL if you never called `soundio_flush_events` or if you provide
|
|
|
|
// invalid parameter values.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_input_device(struct SoundIo *soundio, int index);
|
2015-07-22 22:43:45 +00:00
|
|
|
// Always returns a device. Call soundio_device_unref when done.
|
2015-07-24 03:55:36 +00:00
|
|
|
// `index` must be 0 <= index < soundio_output_device_count
|
2015-08-04 19:25:15 +00:00
|
|
|
// Returns NULL if you never called `soundio_flush_events` or if you provide
|
|
|
|
// invalid parameter values.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT struct SoundIoDevice *soundio_get_output_device(struct SoundIo *soundio, int index);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-20 05:36:50 +00:00
|
|
|
// returns the index of the default input device
|
2015-08-02 05:10:43 +00:00
|
|
|
// returns -1 if there are no devices or if you never called
|
|
|
|
// `soundio_flush_events`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_default_input_device_index(struct SoundIo *soundio);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-20 05:36:50 +00:00
|
|
|
// returns the index of the default output device
|
2015-08-02 05:10:43 +00:00
|
|
|
// returns -1 if there are no devices or if you never called
|
|
|
|
// `soundio_flush_events`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_default_output_device_index(struct SoundIo *soundio);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT void soundio_device_ref(struct SoundIoDevice *device);
|
|
|
|
SOUNDIO_EXPORT void soundio_device_unref(struct SoundIoDevice *device);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT bool soundio_device_equal(
|
2015-07-01 08:02:44 +00:00
|
|
|
const struct SoundIoDevice *a,
|
|
|
|
const struct SoundIoDevice *b);
|
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// Sorts channel layouts by channel count, descending.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT void soundio_device_sort_channel_layouts(struct SoundIoDevice *device);
|
2015-07-13 16:17:20 +00:00
|
|
|
|
2015-07-20 07:00:43 +00:00
|
|
|
// Convenience function. Returns whether `format` is included in the device's
|
|
|
|
// supported formats.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT bool soundio_device_supports_format(struct SoundIoDevice *device,
|
2015-07-14 04:30:37 +00:00
|
|
|
enum SoundIoFormat format);
|
|
|
|
|
2015-07-20 07:00:43 +00:00
|
|
|
// Convenience function. Returns whether `layout` is included in the device's
|
|
|
|
// supported channel layouts.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT bool soundio_device_supports_layout(struct SoundIoDevice *device,
|
2015-07-14 04:30:37 +00:00
|
|
|
const struct SoundIoChannelLayout *layout);
|
2015-07-13 16:59:42 +00:00
|
|
|
|
2015-08-08 21:44:31 +00:00
|
|
|
// Convenience function. Returns whether `sample_rate` is included in the
|
|
|
|
// device's supported sample rates.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT bool soundio_device_supports_sample_rate(struct SoundIoDevice *device,
|
2015-08-08 21:44:31 +00:00
|
|
|
int sample_rate);
|
|
|
|
|
|
|
|
// Convenience function. Returns the available sample rate nearest to
|
|
|
|
// `sample_rate`, rounding up.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_device_nearest_sample_rate(struct SoundIoDevice *device,
|
2015-08-08 21:44:31 +00:00
|
|
|
int sample_rate);
|
|
|
|
|
2015-07-01 08:02:44 +00:00
|
|
|
|
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// Output Streams
|
2015-07-22 22:43:45 +00:00
|
|
|
// Allocates memory and sets defaults. Next you should fill out the struct fields
|
|
|
|
// and then call `soundio_outstream_open`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT struct SoundIoOutStream *soundio_outstream_create(struct SoundIoDevice *device);
|
2015-07-24 21:03:49 +00:00
|
|
|
// You may not call this function from the `write_callback` thread context.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT void soundio_outstream_destroy(struct SoundIoOutStream *outstream);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-08-14 05:54:15 +00:00
|
|
|
// After you call this function, `software_latency` is set to the correct
|
|
|
|
// value.
|
2015-07-30 03:55:28 +00:00
|
|
|
// The next thing to do is call `soundio_instream_start`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_outstream_open(struct SoundIoOutStream *outstream);
|
2015-07-30 03:55:28 +00:00
|
|
|
|
|
|
|
// After you call this function, `write_callback` will be called.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_outstream_start(struct SoundIoOutStream *outstream);
|
2015-07-13 16:17:20 +00:00
|
|
|
|
2015-07-16 03:57:00 +00:00
|
|
|
// Call this function when you are ready to begin writing to the device buffer.
|
2015-07-20 23:52:07 +00:00
|
|
|
// * `outstream` - (in) The output stream you want to write to.
|
|
|
|
// * `areas` - (out) The memory addresses you can write data to. It is OK to
|
|
|
|
// modify the pointers if that helps you iterate.
|
2015-08-05 04:57:46 +00:00
|
|
|
// * `frame_count` - (in/out) Provide the number of frames you want to write.
|
|
|
|
// Returned will be the number of frames you can actually write, which is
|
|
|
|
// also the number of frames that will be written when you call
|
|
|
|
// `soundio_outstream_end_write`. The value returned will always be less
|
|
|
|
// than or equal to the value provided.
|
|
|
|
// It is your responsibility to call this function exactly as many times as
|
|
|
|
// necessary to meet the `frame_count_min` and `frame_count_max` criteria from
|
|
|
|
// `write_callback`. See `sio_sine.c` for example.
|
2015-07-24 21:03:49 +00:00
|
|
|
// You must call this function only from the `write_callback` thread context.
|
2015-08-04 07:56:03 +00:00
|
|
|
// After calling this function, write data to `areas` and then call
|
|
|
|
// `soundio_outstream_end_write`.
|
2015-08-05 04:57:46 +00:00
|
|
|
// If you call this function with `frame_count` less than the `frame_count_min`
|
|
|
|
// parameter from `write_callback` it returns SoundIoErrorInvalid.
|
|
|
|
// If this function returns an error, do not call `soundio_outstream_end_write`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_outstream_begin_write(struct SoundIoOutStream *outstream,
|
2015-07-16 03:57:00 +00:00
|
|
|
struct SoundIoChannelArea **areas, int *frame_count);
|
|
|
|
|
2015-07-22 22:43:45 +00:00
|
|
|
// Commits the write that you began with `soundio_outstream_begin_write`.
|
2015-07-24 21:03:49 +00:00
|
|
|
// You must call this function only from the `write_callback` thread context.
|
2015-07-30 05:39:27 +00:00
|
|
|
// This function might return `SoundIoErrorUnderflow` but don't count on it.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_outstream_end_write(struct SoundIoOutStream *outstream);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-30 03:55:28 +00:00
|
|
|
// Clears the output stream buffer.
|
2015-07-24 21:03:49 +00:00
|
|
|
// You must call this function only from the `write_callback` thread context.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_outstream_clear_buffer(struct SoundIoOutStream *outstream);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-16 20:37:41 +00:00
|
|
|
// If the underyling device supports pausing, this pauses the stream and
|
|
|
|
// prevents `write_callback` from being called. Otherwise this returns
|
|
|
|
// `SoundIoErrorIncompatibleDevice`.
|
2015-07-24 21:03:49 +00:00
|
|
|
// You must call this function only from the `write_callback` thread context.
|
2015-08-25 00:42:57 +00:00
|
|
|
// Pausing when already paused or unpausing when already unpaused has no
|
|
|
|
// effect and always returns SoundIoErrorNone.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_outstream_pause(struct SoundIoOutStream *outstream, bool pause);
|
2015-07-16 20:37:41 +00:00
|
|
|
|
|
|
|
|
2015-07-01 08:02:44 +00:00
|
|
|
|
|
|
|
|
2015-07-13 16:17:20 +00:00
|
|
|
// Input Streams
|
2015-07-22 22:43:45 +00:00
|
|
|
// Allocates memory and sets defaults. Next you should fill out the struct fields
|
|
|
|
// and then call `soundio_instream_open`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT struct SoundIoInStream *soundio_instream_create(struct SoundIoDevice *device);
|
2015-07-30 03:55:28 +00:00
|
|
|
// You may not call this function from `read_callback`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT void soundio_instream_destroy(struct SoundIoInStream *instream);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-08-14 05:54:15 +00:00
|
|
|
// After you call this function, `software_latency` is set to the correct
|
|
|
|
// value.
|
2015-07-30 03:55:28 +00:00
|
|
|
// The next thing to do is call `soundio_instream_start`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_instream_open(struct SoundIoInStream *instream);
|
2015-07-01 08:02:44 +00:00
|
|
|
|
2015-07-30 03:55:28 +00:00
|
|
|
// After you call this function, `read_callback` will be called.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_instream_start(struct SoundIoInStream *instream);
|
2015-07-07 00:16:03 +00:00
|
|
|
|
2015-07-22 22:43:45 +00:00
|
|
|
// Call this function when you are ready to begin reading from the device
|
|
|
|
// buffer.
|
|
|
|
// * `instream` - (in) The input stream you want to read from.
|
|
|
|
// * `areas` - (out) The memory addresses you can read data from. It is OK
|
2015-08-04 07:56:03 +00:00
|
|
|
// to modify the pointers if that helps you iterate. There might be a "hole"
|
|
|
|
// in the buffer. To indicate this, `areas` will be `NULL` and `frame_count`
|
|
|
|
// tells how big the hole is in frames.
|
2015-08-05 04:57:46 +00:00
|
|
|
// * `frame_count` - (in/out) - Provide the number of frames you want to read;
|
|
|
|
// returns the number of frames you can actually read. The returned value
|
|
|
|
// will always be less than or equal to the provided value. If the provided
|
|
|
|
// value is less than `frame_count_min` from `read_callback` this function
|
|
|
|
// returns with SoundIoErrorInvalid.
|
2015-07-22 22:43:45 +00:00
|
|
|
// It is your responsibility to call this function no more and no fewer than the
|
2015-08-05 04:57:46 +00:00
|
|
|
// correct number of times according to the `frame_count_min` and
|
|
|
|
// `frame_count_max` criteria from `read_callback`. See sio_microphone.c for an
|
|
|
|
// example.
|
2015-07-24 21:03:49 +00:00
|
|
|
// You must call this function only from the `read_callback` thread context.
|
2015-07-23 22:04:41 +00:00
|
|
|
// After calling this function, read data from `areas` and then use
|
|
|
|
// `soundio_instream_end_read` to actually remove the data from the buffer
|
|
|
|
// and move the read index forward. `soundio_instream_end_read` should not be
|
|
|
|
// called if the buffer is empty (`frame_count` == 0), but it should be called
|
|
|
|
// if there is a hole.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_instream_begin_read(struct SoundIoInStream *instream,
|
2015-07-22 22:43:45 +00:00
|
|
|
struct SoundIoChannelArea **areas, int *frame_count);
|
2015-07-23 22:04:41 +00:00
|
|
|
// This will drop all of the frames from when you called
|
|
|
|
// `soundio_instream_begin_read`.
|
2015-07-24 21:03:49 +00:00
|
|
|
// You must call this function only from the `read_callback` thread context.
|
|
|
|
// You must call this function only after a successful call to
|
|
|
|
// `soundio_instream_begin_read`.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_instream_end_read(struct SoundIoInStream *instream);
|
2015-07-06 08:05:22 +00:00
|
|
|
|
2015-07-16 20:37:41 +00:00
|
|
|
// If the underyling device supports pausing, this pauses the stream and
|
|
|
|
// prevents `read_callback` from being called. Otherwise this returns
|
|
|
|
// `SoundIoErrorIncompatibleDevice`.
|
2015-07-24 21:03:49 +00:00
|
|
|
// You must call this function only from the `read_callback` thread context.
|
2015-08-25 00:42:57 +00:00
|
|
|
// Pausing when already paused or unpausing when already unpaused has no
|
|
|
|
// effect and always returns SoundIoErrorNone.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_instream_pause(struct SoundIoInStream *instream, bool pause);
|
2015-07-16 20:37:41 +00:00
|
|
|
|
2015-07-06 08:05:22 +00:00
|
|
|
|
|
|
|
// Ring Buffer
|
|
|
|
struct SoundIoRingBuffer;
|
2015-07-22 22:43:45 +00:00
|
|
|
// `requested_capacity` in bytes.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT struct SoundIoRingBuffer *soundio_ring_buffer_create(struct SoundIo *soundio, int requested_capacity);
|
|
|
|
SOUNDIO_EXPORT void soundio_ring_buffer_destroy(struct SoundIoRingBuffer *ring_buffer);
|
|
|
|
SOUNDIO_EXPORT int soundio_ring_buffer_capacity(struct SoundIoRingBuffer *ring_buffer);
|
2015-07-06 08:05:22 +00:00
|
|
|
|
|
|
|
// don't write more than capacity
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT char *soundio_ring_buffer_write_ptr(struct SoundIoRingBuffer *ring_buffer);
|
2015-07-22 22:43:45 +00:00
|
|
|
// `count` in bytes.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT void soundio_ring_buffer_advance_write_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
|
2015-07-06 08:05:22 +00:00
|
|
|
|
|
|
|
// don't read more than capacity
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT char *soundio_ring_buffer_read_ptr(struct SoundIoRingBuffer *ring_buffer);
|
2015-07-22 22:43:45 +00:00
|
|
|
// `count` in bytes.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT void soundio_ring_buffer_advance_read_ptr(struct SoundIoRingBuffer *ring_buffer, int count);
|
2015-07-06 08:05:22 +00:00
|
|
|
|
2015-07-22 22:43:45 +00:00
|
|
|
// Returns how many bytes of the buffer is used, ready for reading.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_ring_buffer_fill_count(struct SoundIoRingBuffer *ring_buffer);
|
2015-07-06 08:05:22 +00:00
|
|
|
|
2015-07-22 22:43:45 +00:00
|
|
|
// Returns how many bytes of the buffer is free, ready for writing.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT int soundio_ring_buffer_free_count(struct SoundIoRingBuffer *ring_buffer);
|
2015-07-06 08:05:22 +00:00
|
|
|
|
2015-07-22 22:43:45 +00:00
|
|
|
// Must be called by the writer.
|
2015-08-20 21:48:19 +00:00
|
|
|
SOUNDIO_EXPORT void soundio_ring_buffer_clear(struct SoundIoRingBuffer *ring_buffer);
|
2015-06-30 21:13:02 +00:00
|
|
|
|
|
|
|
#endif
|