Get all active audio subchannels associated with an audio ducking
output
Synopsis:
#include <sys/asoundlib.h>
int snd_ctl_ducking_status_read( snd_ctl_t *handle,
const char* ducking_output,
snd_ducking_priority_status_t **info );
Arguments:
- handle
- The handle for the control connection to the card.
This must be a handle created by
snd_ctl_open().
- ducking_output
- The name of the ducking output to monitor. The ducking output is the audio
concurrency management context or output specified by the audio
configuration file audiomgmt_id key.
- info
- A pointer to location where a snd_ducking_priority_status_t
structure is stored. The structure contains information about the audio
types that are active. If the call is successful, the system allocates
memory for you, therefore it's the responsibility of the caller to free the
allocated memory. This value can't be NULL.
Library:
libasound.so
Use the -l asound option with
qcc
to link against this library.
Description:
The
snd_ctl_ducking_status_read() function gets a list of all the
active audio subchannels and information about their priority and ducking state,
regardless of whether they are audible or not.
Because audio concurrency management handles a PCM link group as a single stream,
this function reports only information for the first subchannel in a group.
Use this function to get information about active audio types after you receive a
SND_CTL_READ_AUDIOMGMT_STATUS_CHG event in an
audiomgmt callback.
The priority and ducking state information is specified in the
snd_ducking_priority_status_t structure that
info points to:
typedef struct snd_ducking_priority_status {
int nsubchns;
snd_ducking_subchn_info_t subchns[];
} snd_ducking_priority_status_t;
This structure includes the following members:
- nsubchns
- The number of active subchannels. Subchannels do not have to be audible to be considered
active.
- subchns
- An array of subchannel ducking information structures.
The subchns member is a variable-sized array of snd_ducking_status_t
structures:
typedef struct snd_ducking_subchn_info
{
pid_t pid;
uint32_t prio;
uint32_t state;
uint32_t ducked_by;
char name[32];
} snd_ducking_subchn_info_t;
The members include:
- pid
- The process ID of the application that opened the audio stream.
- prio
- The priority of the audio type. The higher the number, the higher the priority.
- state
-
The ducking state. The following values are valid:
- SND_PCM_DUCKING_STATE_ACTIVE — Ducking is active
because the stream is active.
- SND_PCM_DUCKING_STATE_HARD_SUSPENDED — The subchannel
is suspended by an audio type with a higher priority.
- SND_PCM_DUCKING_STATE_SOFT_SUSPENDED — The subchannel
is suspended by an audio type of the same priority.
- SND_PCM_DUCKING_STATE_PAUSED — The stream will
transition to SND_PCM_STATUS_PAUSED when unsuspended.
- SND_PCM_DUCKING_STATE_FORCED_ACTIVE — Ducking was
made active using
snd_pcm_channel_audio_ducking().
- SND_PCM_DUCKING_STATE_MUTE_BY_HIGHER — The stream was
ducked by a stream with a higher priority.
- SND_PCM_DUCKING_STATE_MUTE_BY_SAME — The stream was
ducked by a stream with an equal priority.
- SND_PCM_DUCKING_STATE_DUCKED — Ducking is
active.
- ducked_by
-
Describes the audio stream that ducked this active stream. Valid values
are:
- SND_PCM_DUCKED_BY_SAME_PRIO
- SND_PCM_DUCKED_BY_HIGHER_PRIO
- SND_PCM_DUCKED_BY_NONTRANSIENT
Returns:
EOK on success. The priority status information is allocated and populated. The
client application must free the buffer afterwards.
Errors:
- -ENOMEM
- No memory available to build the ducking status reply.
- -EINVAL
- Ducking output not found.
Classification:
QNX Neutrino
Safety: |
|
Cancellation point |
No |
Interrupt handler |
No |
Signal handler |
No |
Thread |
Yes |