SpecsForegroundAudioSession
SPECS NDK reference for SpecsForegroundAudioSession, which registers audio content, call and audio focus sessions with the system coordinator.
SpecsForegroundAudioSession provides platform-managed foreground audio sessions on SPECS. Apps register an audio content session (for example music or podcast playback), a call session (incoming or active voice call), or an audio focus session (raw audio hardware reservation) with the system coordinator. The coordinator arbitrates priority between active sessions and lets the platform UI publish and control playback and call state.
Higher-priority sessions preempt lower-priority sessions. When a higher-priority session becomes active, the previously active lower-priority session receives an onInactive callback with a reason describing the preemption.
Include and link
#include <SpecsForegroundAudioSessionCoordinator.h>
// Transitively includes:
// SpecsForegroundAudioSession.h — enums, data structs, callback tables
target_link_libraries(myapp specs_foreground_audio)
Foreground audio session result codes
// Since: v1.3.0
typedef enum SpecsForegroundAudioSession_Result {
SPECS_FOREGROUND_AUDIO_SESSION_SUCCESS = 0,
SPECS_FOREGROUND_AUDIO_SESSION_ERROR_GENERIC = -1,
SPECS_FOREGROUND_AUDIO_SESSION_ERROR_BAD_ARGUMENT = -2, // NULL pointer, etc.
SPECS_FOREGROUND_AUDIO_SESSION_ERROR_NOT_IMPLEMENTED = -3,
SPECS_FOREGROUND_AUDIO_SESSION_ERROR_INVALID_STATE = -4,
} SpecsForegroundAudioSession_Result;
Foreground audio session priority
// Since: v1.3.0
typedef enum SpecsForegroundAudioSession_Priority {
SPECS_FOREGROUND_AUDIO_SESSION_PRIORITY_UNSET = 0,
SPECS_FOREGROUND_AUDIO_SESSION_PRIORITY_LOW = 10, // background music
SPECS_FOREGROUND_AUDIO_SESSION_PRIORITY_MEDIUM = 20, // media playback
SPECS_FOREGROUND_AUDIO_SESSION_PRIORITY_LOW_PRIORITY_CALL = 25, // call below BT HFP calls
SPECS_FOREGROUND_AUDIO_SESSION_PRIORITY_HIGH = 30, // BT HFP call, AI assistant, etc.
SPECS_FOREGROUND_AUDIO_SESSION_PRIORITY_HIGH_PRIORITY_CALL = 35, // call above BT HFP calls
} SpecsForegroundAudioSession_Priority;
Foreground audio session inactive reason
// Since: v1.3.0
typedef enum SpecsForegroundAudioSession_InactiveReason {
SPECS_FOREGROUND_AUDIO_SESSION_INACTIVE_REASON_UNSET = 0,
SPECS_FOREGROUND_AUDIO_SESSION_INACTIVE_REASON_HIGHER_PRIORITY_SESSION = 1,
SPECS_FOREGROUND_AUDIO_SESSION_INACTIVE_REASON_SAME_PRIORITY_SESSION = 2,
SPECS_FOREGROUND_AUDIO_SESSION_INACTIVE_REASON_USER_ACTION = 3,
} SpecsForegroundAudioSession_InactiveReason;
Foreground audio session kinds
| Kind | Purpose | Subscription type | Register with |
|---|---|---|---|
| Audio content | Music, podcasts, video playback audio | SpecsForegroundAudioContentSessionSubscription | SpecsForegroundAudioSessionCoordinator_registerAudioContentSession() |
| Call | Phone / voice call | SpecsForegroundCallSessionSubscription | SpecsForegroundAudioSessionCoordinator_registerCallSession() |
| Audio focus | Reserve audio hardware (in, out, or both) without content/call state | SpecsForegroundAudioFocusSessionSubscription | SpecsForegroundAudioSessionCoordinator_registerFocusSession() |
All three kinds share a base set of callbacks (onClosed, onInactive, onActive, getAudioClientIds) and add kind-specific callbacks for state queries and control actions.
Audio content sessions
An audio content session publishes playback state and content metadata to the SPECS platform UI and receives media control actions from it.
Content state and metadata
// Playback state of a content session.
// Since: v1.3.0
typedef struct SpecsForegroundAudioSession_AudioState {
bool isPlaying;
int8_t volume; // 0-100 inclusive
const char *sourceDisplayName; // borrowed; valid for call duration
int64_t positionMilliseconds; // < 0 for live streams
int64_t durationMilliseconds; // < 0 for live streams
} SpecsForegroundAudioSession_AudioState;
// Key-value content metadata.
// Since: v1.3.0
typedef enum SpecsForegroundAudioSession_ContentAttributeKey {
SPECS_FOREGROUND_AUDIO_SESSION_CONTENT_ATTRIBUTE_KEY_UNSET = 0,
SPECS_FOREGROUND_AUDIO_SESSION_CONTENT_ATTRIBUTE_KEY_TITLE = 1,
SPECS_FOREGROUND_AUDIO_SESSION_CONTENT_ATTRIBUTE_KEY_ARTIST = 2,
SPECS_FOREGROUND_AUDIO_SESSION_CONTENT_ATTRIBUTE_KEY_ALBUM = 3,
SPECS_FOREGROUND_AUDIO_SESSION_CONTENT_ATTRIBUTE_KEY_ALBUM_ART_URI = 4,
SPECS_FOREGROUND_AUDIO_SESSION_CONTENT_ATTRIBUTE_KEY_PICTURE_IN_PICTURE_TEXTURE_ID = 5,
} SpecsForegroundAudioSession_ContentAttributeKey;
// Since: v1.3.0
typedef struct SpecsForegroundAudioSession_AudioContentAttribute {
SpecsForegroundAudioSession_ContentAttributeKey key;
const char *value; // borrowed; valid for call duration
} SpecsForegroundAudioSession_AudioContentAttribute;
// Since: v1.3.0
typedef struct SpecsForegroundAudioSession_AudioContent {
const SpecsForegroundAudioSession_AudioContentAttribute *attributes; // borrowed
size_t attributeCount;
} SpecsForegroundAudioSession_AudioContent;
Control actions
SpecsForegroundAudioSession_ControlAction is a tagged union describing media control actions sent from the platform UI to the session:
// Since: v1.3.0
typedef enum SpecsForegroundAudioSession_ControlActionType {
SPECS_FOREGROUND_AUDIO_SESSION_CONTROL_ACTION_PLAY_PAUSE = 1,
SPECS_FOREGROUND_AUDIO_SESSION_CONTROL_ACTION_NEXT = 2,
SPECS_FOREGROUND_AUDIO_SESSION_CONTROL_ACTION_PREVIOUS = 3,
SPECS_FOREGROUND_AUDIO_SESSION_CONTROL_ACTION_SEEK = 4,
} SpecsForegroundAudioSession_ControlActionType;
// Since: v1.3.0
typedef struct SpecsForegroundAudioSession_ControlActionPlayPauseData {
bool play; // true to play, false to pause
} SpecsForegroundAudioSession_ControlActionPlayPauseData;
// Since: v1.3.0
typedef struct SpecsForegroundAudioSession_ControlActionSeekData {
int64_t deltaMilliseconds; // signed seek offset in ms (positive = forward)
} SpecsForegroundAudioSession_ControlActionSeekData;
// Since: v1.3.0
typedef struct SpecsForegroundAudioSession_ControlAction {
SpecsForegroundAudioSession_ControlActionType type;
union {
SpecsForegroundAudioSession_ControlActionPlayPauseData playPause; // type == PLAY_PAUSE
SpecsForegroundAudioSession_ControlActionSeekData seek; // type == SEEK
} data;
} SpecsForegroundAudioSession_ControlAction;
Audio content callback table
// Since: v1.3.0
typedef struct SpecsForegroundAudioContentSession_Callbacks {
void *userData; // opaque pointer passed to every callback
// Base
void (*onClosed)(void *userData); // session closed by service
void (*onInactive)(void *userData,
SpecsForegroundAudioSession_InactiveReason reason);
void (*onActive)(void *userData);
void (*getAudioClientIds)(void *userData,
const int64_t **outIds, size_t *outCount);
// Content-specific
void (*getState)(void *userData,
SpecsForegroundAudioSession_AudioState *outState);
void (*getActiveAudioContent)(void *userData,
SpecsForegroundAudioSession_AudioContent *outContent);
void (*getActions)(void *userData,
const SpecsForegroundAudioSession_ControlAction **outActions,
size_t *outCount);
void (*getAudioContentList)(void *userData,
const SpecsForegroundAudioSession_AudioContent **outList,
size_t *outCount);
bool (*performAction)(void *userData,
const SpecsForegroundAudioSession_ControlAction *action);
} SpecsForegroundAudioContentSession_Callbacks;
Audio content subscription APIs
// Notify listeners that playback state has changed.
// Since: v1.3.0
SpecsForegroundAudioSession_Result
SpecsForegroundAudioContentSessionSubscription_onStateChanged(
SpecsForegroundAudioContentSessionSubscription *subscription,
const SpecsForegroundAudioSession_AudioState *state);
// Notify listeners that the active content metadata has changed.
// Since: v1.3.0
SpecsForegroundAudioSession_Result
SpecsForegroundAudioContentSessionSubscription_onContentChanged(
SpecsForegroundAudioContentSessionSubscription *subscription,
const SpecsForegroundAudioSession_AudioContent *content);
// Close the subscription and unregister the session.
// After this call the subscription handle is invalid.
// Since: v1.3.0
SpecsForegroundAudioSession_Result
SpecsForegroundAudioContentSessionSubscription_close(
SpecsForegroundAudioContentSessionSubscription *subscription);
Call sessions
A call session publishes phone or voice call state to the SPECS platform UI and receives answer, end and mute requests from it.
// Since: v1.3.0
typedef struct SpecsForegroundAudioSession_CallState {
bool isActive; // call connected
bool isIncoming; // incoming / ringing
const char *callerDisplayName; // borrowed; valid for call duration
const char *callerId; // borrowed; valid for call duration
bool isMuted;
const char *callerPhotoUri; // borrowed; may be NULL
} SpecsForegroundAudioSession_CallState;
// Since: v1.3.0
typedef struct SpecsForegroundCallSession_Callbacks {
void *userData;
// Base (same shape as content sessions)
void (*onClosed)(void *userData);
void (*onInactive)(void *userData,
SpecsForegroundAudioSession_InactiveReason reason);
void (*onActive)(void *userData);
void (*getAudioClientIds)(void *userData,
const int64_t **outIds, size_t *outCount);
// Call-specific
void (*getState)(void *userData,
SpecsForegroundAudioSession_CallState *outState);
bool (*answer)(void *userData); // accept an incoming call
bool (*end)(void *userData); // end an active call
bool (*setMuted)(void *userData, bool muted);
} SpecsForegroundCallSession_Callbacks;
// Since: v1.3.0
SpecsForegroundAudioSession_Result
SpecsForegroundCallSessionSubscription_onStateChanged(
SpecsForegroundCallSessionSubscription *subscription,
const SpecsForegroundAudioSession_CallState *state);
// Since: v1.3.0
SpecsForegroundAudioSession_Result
SpecsForegroundCallSessionSubscription_close(
SpecsForegroundCallSessionSubscription *subscription);
Audio focus sessions
Audio focus sessions reserve audio hardware (input, output, or both) without managing content or call state. Use an audio focus session when an app needs raw access to capture or playback without participating in the content metadata and call surfaces.
// Since: v1.3.0
typedef enum SpecsForegroundAudioSession_FocusType {
SPECS_FOREGROUND_AUDIO_SESSION_FOCUS_TYPE_UNSET = 0,
SPECS_FOREGROUND_AUDIO_SESSION_FOCUS_TYPE_AUDIO_IN = 1, // mic capture
SPECS_FOREGROUND_AUDIO_SESSION_FOCUS_TYPE_AUDIO_OUT = 2, // speaker playback
SPECS_FOREGROUND_AUDIO_SESSION_FOCUS_TYPE_AUDIO_IN_OUT = 3, // voice-call style
} SpecsForegroundAudioSession_FocusType;
// Since: v1.3.0
typedef struct SpecsForegroundAudioFocusSession_Callbacks {
void *userData;
// Base
void (*onClosed)(void *userData);
void (*onInactive)(void *userData,
SpecsForegroundAudioSession_InactiveReason reason);
void (*onActive)(void *userData);
void (*getAudioClientIds)(void *userData,
const int64_t **outIds, size_t *outCount);
// Focus-specific
void (*getOwnerDisplayName)(void *userData, const char **outName);
void (*getFocusType)(void *userData,
SpecsForegroundAudioSession_FocusType *outType);
} SpecsForegroundAudioFocusSession_Callbacks;
// Since: v1.3.0
SpecsForegroundAudioSession_Result
SpecsForegroundAudioFocusSessionSubscription_close(
SpecsForegroundAudioFocusSessionSubscription *subscription);
Coordinator lifecycle and registration
The SpecsForegroundAudioSessionCoordinator connects your app to the SPECS foreground audio service and registers sessions of each kind. Each registration returns an opaque subscription handle.
// Since: v1.3.0
typedef struct SpecsForegroundAudioSessionCoordinator
SpecsForegroundAudioSessionCoordinator;
// Opaque subscription handles returned by the register functions.
// Since: v1.3.0
typedef struct SpecsForegroundAudioContentSessionSubscription SpecsForegroundAudioContentSessionSubscription;
// Since: v1.3.0
typedef struct SpecsForegroundCallSessionSubscription SpecsForegroundCallSessionSubscription;
// Since: v1.3.0
typedef struct SpecsForegroundAudioFocusSessionSubscription SpecsForegroundAudioFocusSessionSubscription;
// Create a coordinator and connect to the platform audio session service.
// Only one coordinator should be created per process.
// Since: v1.3.0
SpecsForegroundAudioSession_Result
SpecsForegroundAudioSessionCoordinator_create(
SpecsForegroundAudioSessionCoordinator **outCoordinator);
// Destroy the coordinator. All subscriptions should be closed first.
// Passing NULL is a no-op.
// Since: v1.3.0
SpecsForegroundAudioSession_Result
SpecsForegroundAudioSessionCoordinator_delete(
SpecsForegroundAudioSessionCoordinator *coordinator);
// Register an audio content session.
// Since: v1.3.0
SpecsForegroundAudioSession_Result
SpecsForegroundAudioSessionCoordinator_registerAudioContentSession(
SpecsForegroundAudioSessionCoordinator *coordinator,
SpecsForegroundAudioSession_Priority priority,
const SpecsForegroundAudioContentSession_Callbacks *callbacks,
SpecsForegroundAudioContentSessionSubscription **outSubscription);
// Register a phone / voice call session (typically HIGH priority).
// Since: v1.3.0
SpecsForegroundAudioSession_Result
SpecsForegroundAudioSessionCoordinator_registerCallSession(
SpecsForegroundAudioSessionCoordinator *coordinator,
SpecsForegroundAudioSession_Priority priority,
const SpecsForegroundCallSession_Callbacks *callbacks,
SpecsForegroundCallSessionSubscription **outSubscription);
// Register an audio focus session.
// Since: v1.3.0
SpecsForegroundAudioSession_Result
SpecsForegroundAudioSessionCoordinator_registerFocusSession(
SpecsForegroundAudioSessionCoordinator *coordinator,
SpecsForegroundAudioSession_Priority priority,
const SpecsForegroundAudioFocusSession_Callbacks *callbacks,
SpecsForegroundAudioFocusSessionSubscription **outSubscription);
Memory and ownership. Callback structs are owned by the caller and must remain valid until the subscription is closed. const char * fields in state structs are borrowed for the duration of the call; consumers must copy to retain. Array out-params use the const T **outArray, size_t *outCount shape and are callee-owned, valid until the next invocation of the same callback.
SpecsPlayer integration. SpecsPlayer doesn't register a foreground audio session by default. To have the player register with the coordinator and manage audio focus for you, call SpecsPlayer_setAudioSessionEnabled(player, true) before SpecsPlayer_open*(); see SpecsPlayer. Leave it disabled if your app manages audio focus through the SpecsForegroundAudioSession API directly.