Skip to main content

SpecsAudio

SPECS NDK reference for SpecsAudioPlayback and SpecsAudioRecord, the C APIs for PCM audio output and microphone capture.

The SPECS NDK provides two complementary C APIs for audio I/O on SPECS:

  • SpecsAudioPlayback: output PCM audio to speakers or a submix bus
  • SpecsAudioRecord: capture PCM audio from the microphone or other input sources

Both APIs follow the same design pattern: create a config object, open a stream, operate, then stop and close.

SpecsAudioPlayback

SpecsAudioPlayback outputs PCM audio on SPECS to the speaker, a submix bus, or both.

#include <SpecsAudioPlayback.h>
target_link_libraries(myapp specs_audio_playback)

Operating modes

ModeHow it worksUse case
Push mode (default)App calls write() at its own paceStraightforward playback; sufficient for most apps
Pull modeSystem calls your callback when it needs dataLow-latency applications; recommended when timing matters

API version

#define SPECSAUDIOPLAYBACK_API_VERSION 0

Error codes

ConstantValueMeaning
SPECSAUDIOPLAYBACK_OK0Success
SPECSAUDIOPLAYBACK_ERR_GENERAL-1Unspecified error
SPECSAUDIOPLAYBACK_ERR_INVALID_ARG-2Null pointer or out-of-range value
SPECSAUDIOPLAYBACK_ERR_NO_MEMORY-3Allocation failure
SPECSAUDIOPLAYBACK_ERR_NOT_READY-4Service connection not yet established
SPECSAUDIOPLAYBACK_ERR_WOULD_BLOCK-5Buffer full
SPECSAUDIOPLAYBACK_ERR_IO-6I/O error
SPECSAUDIOPLAYBACK_ERR_CLOSED-7Stream already closed
SPECSAUDIOPLAYBACK_ERR_NOT_SUPPORTED-8Feature not supported

Routing destinations

ConstantValueDescription
SPECSAUDIOPLAYBACK_DEST_NONE0No destination (reserved)
SPECSAUDIOPLAYBACK_DEST_SPKR1Speaker output (default)
SPECSAUDIOPLAYBACK_DEST_SUBMIX2Submix/loopback only (no speaker)
SPECSAUDIOPLAYBACK_DEST_BOTH3Speaker + submix simultaneously

Pull-mode callbacks (setNeedDataCallback) require a speaker-inclusive destination (SPKR or BOTH). Using SUBMIX with a pull-mode callback returns SPECSAUDIOPLAYBACK_ERR_NOT_SUPPORTED.

Sample formats

ConstantValueBytes/sampleDescription
SPECSAUDIOPLAYBACK_FORMAT_PCM1612Signed 16-bit integer (default)
SPECSAUDIOPLAYBACK_FORMAT_PCM2423Signed 24-bit integer
SPECSAUDIOPLAYBACK_FORMAT_PCM3234Signed 32-bit integer
SPECSAUDIOPLAYBACK_FORMAT_FLOAT3244Float [-1.0, 1.0]

Use the static inline helper SpecsAudioPlayback_bytesPerSample to compute bytes per sample. It returns 2, 3 or 4 for a SPECSAUDIOPLAYBACK_FORMAT_* constant, or 0 if the format is unknown.

// Since: v1.3.0
static inline unsigned int SpecsAudioPlayback_bytesPerSample(unsigned int fmt);
unsigned int bps = SpecsAudioPlayback_bytesPerSample(format);
size_t frame_bytes = channels * bps;
size_t byte_count = frame_count * frame_bytes;

Lifecycle states

OperationEffectSpeed
streamOpen()Connect to audio service, allocate resources—
start()Begin playback; pull callbacks start firing—
stop()Halt playback, release mixer resources~20 ms
pause()Inject silence; callbacks disabled; graph stays activeFast
resume()Restart from pause; stale buffers droppedInstant
streamClose()Release all resources—

Always call stop() before streamClose().

Opaque handles

// Opaque configuration handle. Create with SpecsAudioPlayback_configCreate(),
// configure with setters, pass to SpecsAudioPlayback_streamOpen(), then destroy
// with SpecsAudioPlayback_configDestroy(). The config object can be reused or
// destroyed after streamOpen() returns.
// Since: v1.3.0
typedef struct SpecsAudioPlayback_Config_t SpecsAudioPlayback_Config_t;

// Opaque stream handle. Represents an active playback stream. Obtain via
// SpecsAudioPlayback_streamOpen() and release via SpecsAudioPlayback_streamClose().
// Since: v1.3.0
typedef struct SpecsAudioPlayback_Stream_t_ SpecsAudioPlayback_Stream_t;

Configuration functions

// Create/destroy
// Since: v1.3.0
SpecsAudioPlayback_Config_t *SpecsAudioPlayback_configCreate(void);
// Since: v1.3.0
void SpecsAudioPlayback_configDestroy(SpecsAudioPlayback_Config_t *cfg);

// Setters (defaults shown in parentheses)
// Since: v1.3.0
void SpecsAudioPlayback_configSetSampleRate(SpecsAudioPlayback_Config_t *cfg,
unsigned int rate_hz); // default: 48000
// Supported rates: 8000, 16000, 24000, 32000, 44100, 48000. streamOpen() returns
// NULL for any other rate; the stream is never opened at a substituted rate.
// Since: v1.3.0
void SpecsAudioPlayback_configSetChannels(SpecsAudioPlayback_Config_t *cfg,
unsigned int channels); // default: 2
// Since: v1.3.0
void SpecsAudioPlayback_configSetFramesPerBurst(SpecsAudioPlayback_Config_t *cfg,
unsigned int frames); // default: system
// Since: v1.3.0
void SpecsAudioPlayback_configRingCapacityFrames(SpecsAudioPlayback_Config_t *cfg,
unsigned int ringCapacityFrames); // default: 4×burst
// Since: v1.3.0
void SpecsAudioPlayback_configTargetQueueFrames(SpecsAudioPlayback_Config_t *cfg,
unsigned int targetQueueFrames); // default: 2×burst
// Since: v1.3.0
void SpecsAudioPlayback_configStartThresholdFrames(SpecsAudioPlayback_Config_t *cfg,
unsigned int startThresholdFrames); // default: 1×burst
// Since: v1.3.0
void SpecsAudioPlayback_configSetDestination(SpecsAudioPlayback_Config_t *cfg,
unsigned int destination); // default: SPKR
// Since: v1.3.0
void SpecsAudioPlayback_configSetSampleFormat(SpecsAudioPlayback_Config_t *cfg,
unsigned int format); // default: PCM16

// Getters
// Since: v1.3.0
unsigned int SpecsAudioPlayback_configGetSampleRate(const SpecsAudioPlayback_Config_t *cfg);
// Since: v1.3.0
unsigned int SpecsAudioPlayback_configGetChannels(const SpecsAudioPlayback_Config_t *cfg);
// Since: v1.3.0
unsigned int SpecsAudioPlayback_configGetFramesPerBurst(const SpecsAudioPlayback_Config_t *cfg);
// Since: v1.3.0
unsigned int SpecsAudioPlayback_configGetDestination(const SpecsAudioPlayback_Config_t *cfg);
// Since: v1.3.0
unsigned int SpecsAudioPlayback_configGetSampleFormat(const SpecsAudioPlayback_Config_t *cfg);

// Debug
// Since: v1.3.0
const char *SpecsAudioPlayback_configToString(const SpecsAudioPlayback_Config_t *cfg);

Stream functions

// Open/close
// Since: v1.3.0
SpecsAudioPlayback_Stream_t *SpecsAudioPlayback_streamOpen(
const SpecsAudioPlayback_Config_t *cfg); // cfg is NOT retained
// Returns NULL on failure, including an unsupported sample rate.
// Since: v1.3.0
void SpecsAudioPlayback_streamClose(SpecsAudioPlayback_Stream_t *stream);

// Get resolved config after open
// Since: v1.3.0
void SpecsAudioPlayback_streamGetConfig(const SpecsAudioPlayback_Stream_t *stream,
SpecsAudioPlayback_Config_t *dest_cfg);

// State queries
// Since: v1.3.0
int SpecsAudioPlayback_isReady(const SpecsAudioPlayback_Stream_t *stream);
// Since: v1.3.0
int SpecsAudioPlayback_getFramesPerBurst(const SpecsAudioPlayback_Stream_t *stream);
// Since: v1.3.0
int SpecsAudioPlayback_getRingCapacityFrames(const SpecsAudioPlayback_Stream_t *stream);
// Since: v1.3.0
int SpecsAudioPlayback_getTargetQueueFrames(const SpecsAudioPlayback_Stream_t *stream);
// Since: v1.3.0
int SpecsAudioPlayback_getStartThresholdFrames(const SpecsAudioPlayback_Stream_t *stream);

// Control
// Since: v1.3.0
int SpecsAudioPlayback_start(SpecsAudioPlayback_Stream_t *stream);
// Since: v1.3.0
int SpecsAudioPlayback_stop(SpecsAudioPlayback_Stream_t *stream);
// Since: v1.3.0
int SpecsAudioPlayback_pause(SpecsAudioPlayback_Stream_t *stream);
// Since: v1.3.0
int SpecsAudioPlayback_resume(SpecsAudioPlayback_Stream_t *stream);

// Push-mode data write
// Returns bytes consumed (may be < byte_count), 0 if write exceeds ring capacity,
// or negative error code.
// Since: v1.3.0
int SpecsAudioPlayback_write(SpecsAudioPlayback_Stream_t *stream,
const void *data, int byte_count);

// Pull-mode callback
// Since: v1.3.0
typedef void (*SpecsAudioPlayback_NeedDataCallback_t)(
SpecsAudioPlayback_Stream_t *stream,
int32_t requested_frames,
uint64_t expected_play_time_ns, // 0 if not yet estimated
void *user_ctx);

// Since: v1.3.0
int SpecsAudioPlayback_setNeedDataCallback(SpecsAudioPlayback_Stream_t *stream,
SpecsAudioPlayback_NeedDataCallback_t cb,
void *user_ctx);

// Listener-relative source pose (spatial audio).
// position_m is a cartesian translation in meters; orientation_xyzw is a
// quaternion in (x, y, z, w) order. The struct is POD and self-contained so
// it can be passed through the public C API without depending on SLAM types.
// Since: v1.3.0
typedef struct SpecsAudioPlayback_Pose_t {
float position_m[3];
float orientation_xyzw[4];
} SpecsAudioPlayback_Pose_t;

// Update the latest listener-relative source pose for a playback stream.
// Pose updates are independent of stream start/stop and audio writes — the
// most recent pose wins. Returns SPECSAUDIOPLAYBACK_ERR_INVALID_ARG if stream
// or pose is NULL or any pose component is non-finite, or
// SPECSAUDIOPLAYBACK_ERR_CLOSED if the stream is already closed.
// Gated by the SPECSAUDIOPLAYBACK_CAP_POSE_UPDATES capability bit.
// Since: v1.3.0
int SpecsAudioPlayback_setPose(SpecsAudioPlayback_Stream_t *stream,
const SpecsAudioPlayback_Pose_t *pose);

Pre-data retry timeout

After SpecsAudioPlayback_start(), the audio service expects audio data within a bounded grace period. If no data has been written when the first callback fires, the service retries the callback for the period controlled by the system property com.snap.os.audio.pre_data_retry_timeout_ms (default 10 000 ms / 10 s). If the grace period expires without any data, callbacks stop and the stream may be evicted. Once the first successful write completes, normal demand-driven callback scheduling resumes and the grace period no longer applies.

Clients that need audio output but can't supply data immediately (for example while waiting for a decoder to initialize) must make sure they begin writing within this window.

Runtime capability detection

SpecsAudioPlayback_getVersionInfo fills a SpecsAudioPlayback_VersionInfo_t with the API version and a capability mask, so you can detect supported features at runtime. Set struct_size before calling. The function returns SPECSAUDIOPLAYBACK_OK on success, or an error code otherwise.

// Since: v1.3.0
typedef struct SpecsAudioPlayback_VersionInfo_t
{
/** Must be sizeof(SpecsAudioPlayback_VersionInfo_t) */
unsigned int struct_size;

/** API version (SPECSAUDIOPLAYBACK_API_VERSION) */
unsigned int api_version;

/** Bitmask of SPECSAUDIOPLAYBACK_CAP_* flags */
unsigned int capability_mask;
} SpecsAudioPlayback_VersionInfo_t;

// Retrieve API version and capability mask (caller must set info->struct_size first).
// Since: v1.3.0
int SpecsAudioPlayback_getVersionInfo(SpecsAudioPlayback_VersionInfo_t *info);
SpecsAudioPlayback_VersionInfo_t info;
info.struct_size = sizeof(info);
if (SpecsAudioPlayback_getVersionInfo(&info) == SPECSAUDIOPLAYBACK_OK) {
if (info.capability_mask & SPECSAUDIOPLAYBACK_CAP_PULL_MODE) {
// pull-mode callbacks supported
}
if (info.capability_mask & SPECSAUDIOPLAYBACK_CAP_FORMAT_FLOAT32) {
// float32 format accepted
}
}

Capability bits:

BitMeaning
SPECSAUDIOPLAYBACK_CAP_BASIC_OPENStream can be opened
SPECSAUDIOPLAYBACK_CAP_SIZE_QUERIESBurst/ring/threshold getters work
SPECSAUDIOPLAYBACK_CAP_STUB_WRITEwrite() path present
SPECSAUDIOPLAYBACK_CAP_READY_FLAGisReady() available
SPECSAUDIOPLAYBACK_CAP_PULL_MODEsetNeedDataCallback() supported
SPECSAUDIOPLAYBACK_CAP_FORMAT_FLOAT32Float32 format accepted
SPECSAUDIOPLAYBACK_CAP_MULTI_FORMATMultiple formats selectable
SPECSAUDIOPLAYBACK_CAP_POSE_UPDATESSpecsAudioPlayback_setPose() available

SpecsAudioRecord

SpecsAudioRecord is the SPECS audio capture (mic input) C API. It provides a callback-driven interface for receiving audio frames from the microphone or other audio input sources.

#include <SpecsAudioRecord.h>
target_link_libraries(myapp specs_audio_record)

Required permission: MICROPHONE_RAW. SpecsAudioRecord_streamOpen and SpecsAudioRecord_start are annotated with SPECS_REQUIRES_PERMISSION(MICROPHONE_RAW). The permission is recorded in your library's .snap.permissions manifest at build time; see Permission Annotations and Manifest Embedding.

API version

#define SPECSAUDIORECORD_API_VERSION 0

Error codes

ConstantValueMeaning
SPECSAUDIORECORD_OK0Success
SPECSAUDIORECORD_ERR_GENERAL-1Unspecified error
SPECSAUDIORECORD_ERR_INVALID_ARG-2Null pointer or bad value
SPECSAUDIORECORD_ERR_NO_MEMORY-3Allocation failure
SPECSAUDIORECORD_ERR_NOT_READY-4Service not connected
SPECSAUDIORECORD_ERR_CLOSED-5Stream already closed
SPECSAUDIORECORD_ERR_NOT_SUPPORTED-6Feature not supported
SPECSAUDIORECORD_ERR_TIMEOUT-7awaitReady() timed out

Sample rate constants

ConstantValueRate
SPECSAUDIORECORD_SAMPLERATE_8K18000 Hz
SPECSAUDIORECORD_SAMPLERATE_16K216000 Hz
SPECSAUDIORECORD_SAMPLERATE_22K322050 Hz
SPECSAUDIORECORD_SAMPLERATE_32K432000 Hz
SPECSAUDIORECORD_SAMPLERATE_44K544100 Hz
SPECSAUDIORECORD_SAMPLERATE_48K648000 Hz (default)

Sample formats

ConstantValueBytes/sample
SPECSAUDIORECORD_FORMAT_PCM1612 (default)
SPECSAUDIORECORD_FORMAT_PCM2423
SPECSAUDIORECORD_FORMAT_PCM3234

Bytes per sample helper

SpecsAudioRecord_bytesPerSample is a static inline helper in SpecsAudioRecord.h that returns the bytes per sample for a SPECSAUDIORECORD_FORMAT_* constant: 2 for PCM16, 3 for PCM24, 4 for PCM32, or 0 if the format is unknown. Use it to calculate buffer sizes: buffer_size = num_frames * channels * bytesPerSample.

// Since: v1.3.0
static inline unsigned int SpecsAudioRecord_bytesPerSample(unsigned int fmt);

Audio source types

ConstantValueDescription
SPECSAUDIORECORD_SOURCE_DEFAULT0System-determined
SPECSAUDIORECORD_SOURCE_RAW_MICS1Raw microphone, minimal DSP
SPECSAUDIORECORD_SOURCE_CAMCORDER2Optimized for video recording (default)
SPECSAUDIORECORD_SOURCE_EXTERNAL3External audio input
SPECSAUDIORECORD_SOURCE_VOICE_RECOGNITION4Speech-to-text optimized
SPECSAUDIORECORD_SOURCE_VOICE_CALL5Voice call audio
SPECSAUDIORECORD_SOURCE_BYSTANDER6Wearer-gated output
SPECSAUDIORECORD_SOURCE_CONVERSATION7Bystander-gated output

Lifecycle

streamOpen() → setDataCallback() → awaitReady() → start() → stop() → streamClose()

Always call stop() before streamClose(). Close-without-stop is handled as a safety net but is not the expected usage.

Opaque handles

// Opaque configuration handle. Create with SpecsAudioRecord_configCreate(),
// configure with setters, pass to SpecsAudioRecord_streamOpen(), then destroy
// with SpecsAudioRecord_configDestroy(). The config object can be reused or
// destroyed after streamOpen() returns.
// Since: v1.3.0
typedef struct SpecsAudioRecord_Config_t SpecsAudioRecord_Config_t;

// Opaque stream handle. Represents an active record stream. Obtain via
// SpecsAudioRecord_streamOpen() and release via SpecsAudioRecord_streamClose().
// Since: v1.3.0
typedef struct SpecsAudioRecord_Stream_t_ SpecsAudioRecord_Stream_t;

Configuration functions

// Create/destroy
// Since: v1.3.0
SpecsAudioRecord_Config_t *SpecsAudioRecord_configCreate(void);
// Since: v1.3.0
void SpecsAudioRecord_configDestroy(SpecsAudioRecord_Config_t *cfg);

// Setters (defaults)
// Since: v1.3.0
void SpecsAudioRecord_configSetSampleRate(SpecsAudioRecord_Config_t *cfg,
unsigned int sample_rate); // SAMPLERATE_48K
// Since: v1.3.0
void SpecsAudioRecord_configSetChannels(SpecsAudioRecord_Config_t *cfg,
unsigned int channels); // 1 (mono)
// Since: v1.3.0
void SpecsAudioRecord_configSetFormat(SpecsAudioRecord_Config_t *cfg,
unsigned int format); // FORMAT_PCM16
// Since: v1.3.0
void SpecsAudioRecord_configSetSourceType(SpecsAudioRecord_Config_t *cfg,
unsigned int source_type); // SOURCE_CAMCORDER
// Strict mode: when true, streamOpen fails if the service cannot match the
// exact config. When false, the service may negotiate different parameters.
// Since: v1.3.0
void SpecsAudioRecord_configSetStrict(SpecsAudioRecord_Config_t *cfg,
int is_strict); // default: true

// Getters
// Since: v1.3.0
unsigned int SpecsAudioRecord_configGetSampleRate(const SpecsAudioRecord_Config_t *cfg);
// Since: v1.3.0
unsigned int SpecsAudioRecord_configGetChannels(const SpecsAudioRecord_Config_t *cfg);
// Since: v1.3.0
unsigned int SpecsAudioRecord_configGetFormat(const SpecsAudioRecord_Config_t *cfg);
// Since: v1.3.0
unsigned int SpecsAudioRecord_configGetSourceType(const SpecsAudioRecord_Config_t *cfg);
// Since: v1.3.0
int SpecsAudioRecord_configGetStrict(const SpecsAudioRecord_Config_t *cfg);

// Debug
// Since: v1.3.0
const char *SpecsAudioRecord_configToString(const SpecsAudioRecord_Config_t *cfg);

Stream functions

// Open/close
// Since: v1.3.0
SpecsAudioRecord_Stream_t *SpecsAudioRecord_streamOpen(
const SpecsAudioRecord_Config_t *cfg); // cfg is NOT retained
// Since: v1.3.0
void SpecsAudioRecord_streamClose(SpecsAudioRecord_Stream_t *stream);

// Get resolved config (useful after non-strict negotiation)
// Since: v1.3.0
void SpecsAudioRecord_streamGetConfig(const SpecsAudioRecord_Stream_t *stream,
SpecsAudioRecord_Config_t *dest_cfg);

// Readiness
// Since: v1.3.0
int SpecsAudioRecord_isReady(const SpecsAudioRecord_Stream_t *stream);
// Block until ready or timeout. Returns SPECSAUDIORECORD_OK or ERR_TIMEOUT.
// Since: v1.3.0
int SpecsAudioRecord_awaitReady(SpecsAudioRecord_Stream_t *stream,
unsigned int timeout_ms);

// Data callback (must be set before start())
// Since: v1.3.0
typedef void (*SpecsAudioRecord_DataCallback_t)(
SpecsAudioRecord_Stream_t *stream,
const void *data, // valid only during callback — copy if needed
int32_t byte_count,
uint64_t timestamp, // milliseconds (0 if unavailable)
void *user_ctx);

// Since: v1.3.0
int SpecsAudioRecord_setDataCallback(SpecsAudioRecord_Stream_t *stream,
SpecsAudioRecord_DataCallback_t cb,
void *user_ctx);

// Control
// Since: v1.3.0
int SpecsAudioRecord_start(SpecsAudioRecord_Stream_t *stream);
// Since: v1.3.0
int SpecsAudioRecord_stop(SpecsAudioRecord_Stream_t *stream);

Threading model

The SpecsAudioRecord data callback fires on an internal service thread. The callback must:

  • Complete quickly (non-blocking)
  • Copy data if it needs to be retained past the callback return
  • Not call stop() or streamClose() from within the callback

Strict and non-strict mode

In strict mode (default), SpecsAudioRecord_streamOpen() fails if the audio service can't exactly match the requested sample rate, channel count, and format. This is the safest mode: you know exactly what you're getting.

In non-strict mode, the service may negotiate different parameters. After streamOpen(), call streamGetConfig() to read back the applied configuration:

SpecsAudioRecord_configSetStrict(cfg, 0); // allow negotiation
SpecsAudioRecord_Stream_t *stream = SpecsAudioRecord_streamOpen(cfg);

// Check what was actually negotiated. SpecsAudioRecord_Config_t is opaque, so
// allocate the destination with configCreate() and free it with configDestroy().
SpecsAudioRecord_Config_t *actual = SpecsAudioRecord_configCreate();
SpecsAudioRecord_streamGetConfig(stream, actual);
unsigned int actual_rate = SpecsAudioRecord_configGetSampleRate(actual);
SpecsAudioRecord_configDestroy(actual);

Runtime capability detection

SpecsAudioRecord_getVersionInfo retrieves the SpecsAudioRecord API version and capability mask so you can detect supported features at runtime. Set info->struct_size before calling.

// Version and capability information structure.
// Use SpecsAudioRecord_getVersionInfo() to populate it. Always set struct_size before calling.
// Since: v1.3.0
typedef struct SpecsAudioRecord_VersionInfo_t
{
/** Must be sizeof(SpecsAudioRecord_VersionInfo_t) */
unsigned int struct_size;

/** API version (SPECSAUDIORECORD_API_VERSION) */
unsigned int api_version;

/** Bitmask of SPECSAUDIORECORD_CAP_* flags */
unsigned int capability_mask;
} SpecsAudioRecord_VersionInfo_t;

// Retrieve API version and capability mask (caller must set info->struct_size first).
// Since: v1.3.0
int SpecsAudioRecord_getVersionInfo(SpecsAudioRecord_VersionInfo_t *info);
Return valueMeaning
SPECSAUDIORECORD_OKVersion info retrieved
SPECSAUDIORECORD_ERR_INVALID_ARGinfo is NULL or struct_size mismatch
SpecsAudioRecord_VersionInfo_t info;
info.struct_size = sizeof(info);
if (SpecsAudioRecord_getVersionInfo(&info) == SPECSAUDIORECORD_OK) {
printf("API Version: %u\n", info.api_version);
printf("Capabilities: 0x%x\n", info.capability_mask);

if (info.capability_mask & SPECSAUDIORECORD_CAP_DATA_CALLBACK) {
printf("Data callback supported\n");
}
}

Capability bits:

BitValueMeaning
SPECSAUDIORECORD_CAP_BASIC_OPEN1u << 0Stream can be opened and connected to the audio service
SPECSAUDIORECORD_CAP_DATA_CALLBACK1u << 1Data callback mechanism is supported
SPECSAUDIORECORD_CAP_READY_FLAG1u << 2Stream readiness can be observed via isReady/awaitReady