1
0
mirror of https://github.com/mpv-player/mpv synced 2024-12-25 08:12:17 +00:00

ao: document some functions

This commit is contained in:
wm4 2014-02-28 00:56:10 +01:00
parent 91404e8a19
commit 6b2a929ca7
2 changed files with 35 additions and 3 deletions

View File

@ -209,12 +209,21 @@ done:
return ao;
}
// Uninitialize and destroy the AO.
// cut_audio: if false, block until all remaining audio was played.
void ao_uninit(struct ao *ao, bool cut_audio)
{
ao->driver->uninit(ao, cut_audio);
talloc_free(ao);
}
// Queue the given audio data. Start playback if it hasn't started yet. Return
// the number of samples that was accepted (the core will try to queue the rest
// again later). Should never block.
// data: start pointer for each plane. If the audio data is packed, only
// data[0] is valid, otherwise there is a plane for each channel.
// samples: size of the audio data (see ao->sstride)
// flags: currently AOPLAY_FINAL_CHUNK can be set
int ao_play(struct ao *ao, void **data, int samples, int flags)
{
return ao->driver->play(ao, data, samples, flags);
@ -227,6 +236,11 @@ int ao_control(struct ao *ao, enum aocontrol cmd, void *arg)
return CONTROL_UNKNOWN;
}
// Return size of the buffered data in seconds. Can include the device latency.
// Basically, this returns how much data there is still to play, and how long
// it takes until the last sample in the buffer reaches the speakers. This is
// used for audio/video synchronization, so it's very important to implement
// this correctly.
double ao_get_delay(struct ao *ao)
{
if (!ao->driver->get_delay) {
@ -236,23 +250,32 @@ double ao_get_delay(struct ao *ao)
return ao->driver->get_delay(ao);
}
// Return free size of the internal audio buffer. This controls how much audio
// the core should decode and try to queue with ao_play().
int ao_get_space(struct ao *ao)
{
return ao->driver->get_space(ao);
}
// Stop playback and empty buffers. Essentially go back to the state after
// ao->init().
void ao_reset(struct ao *ao)
{
if (ao->driver->reset)
ao->driver->reset(ao);
}
// Pause playback. Keep the current buffer. ao_get_delay() must return the
// same value as before pausing.
void ao_pause(struct ao *ao)
{
if (ao->driver->pause)
ao->driver->pause(ao);
}
// Resume playback. Play the remaining buffer. If the driver doesn't support
// pausing, it has to work around this and e.g. use ao_play_silence() to fill
// the lost audio.
void ao_resume(struct ao *ao)
{
if (ao->driver->resume)

View File

@ -38,6 +38,8 @@ enum aocontrol {
AOCONTROL_UPDATE_STREAM_TITLE,
};
// If set, then the queued audio data is the last. Note that after a while, new
// data might be written again, instead of closing the AO.
#define AOPLAY_FINAL_CHUNK 1
typedef struct ao_control_vol {
@ -48,11 +50,18 @@ typedef struct ao_control_vol {
struct ao;
struct ao_driver {
// If true, use with encoding only.
bool encode;
// Name used for --ao.
const char *name;
// Description shown with --ao=help.
const char *description;
int (*control)(struct ao *ao, enum aocontrol cmd, void *arg);
// Init the device using ao->format/ao->channels/ao->samplerate. If the
// device doesn't accept these parameters, you can attempt to negotiate
// fallback parameters, and set the ao format fields accordingly.
int (*init)(struct ao *ao);
// See ao_control() etc. in ao.c
int (*control)(struct ao *ao, enum aocontrol cmd, void *arg);
void (*uninit)(struct ao *ao, bool cut_audio);
void (*reset)(struct ao*ao);
int (*get_space)(struct ao *ao);
@ -71,7 +80,7 @@ struct ao_driver {
struct ao {
int samplerate;
struct mp_chmap channels;
int format;
int format; // one of AF_FORMAT_...
int bps; // bytes per second
int sstride; // size of a sample on each plane
// (format_size*num_channels/num_planes)
@ -80,7 +89,7 @@ struct ao {
int buffer_playable_samples;// part of the part of the buffer the AO hasn't
// accepted yet with play()
bool probing; // if true, don't fail loudly on init
bool untimed;
bool untimed; // don't assume realtime playback
bool no_persistent_volume; // the AO does the equivalent of af_volume
bool per_application_mixer; // like above, but volume persists (per app)
const struct ao_driver *driver;