# ifdef __cplusplus
extern "C" {
+# else
+# include <stdbool.h>
# endif
/*****************************************************************************
*/
typedef enum libvlc_video_marquee_option_t {
libvlc_marquee_Enable = 0,
- libvlc_marquee_Text, /** string argument */
+ libvlc_marquee_Text, /** string argument */
libvlc_marquee_Color,
libvlc_marquee_Opacity,
libvlc_marquee_Position,
*
* \param p_mi the Media Player
* \return 1 if the media player is playing, 0 otherwise
+ *
+ * \libvlc_return_bool
*/
LIBVLC_API int libvlc_media_player_is_playing ( libvlc_media_player_t *p_mi );
*/
LIBVLC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi );
+/**
+ * Callback prototype for audio playback.
+ * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
+ * \param samples pointer to the first audio sample to play back [IN]
+ * \param count number of audio samples to play back
+ * \param pts expected play time stamp (see libvlc_delay())
+ */
+typedef void (*libvlc_audio_play_cb)(void *data, const void *samples,
+ unsigned count, int64_t pts);
+
+/**
+ * Callback prototype for audio pause.
+ * \note The pause callback is never called if the audio is already paused.
+ * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
+ * \param pts time stamp of the pause request (should be elapsed already)
+ */
+typedef void (*libvlc_audio_pause_cb)(void *data, int64_t pts);
+
+/**
+ * Callback prototype for audio resumption (i.e. restart from pause).
+ * \note The resume callback is never called if the audio is not paused.
+ * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
+ * \param pts time stamp of the resumption request (should be elapsed already)
+ */
+typedef void (*libvlc_audio_resume_cb)(void *data, int64_t pts);
+
+/**
+ * Callback prototype for audio buffer flush
+ * (i.e. discard all pending buffers and stop playback as soon as possible).
+ * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
+ */
+typedef void (*libvlc_audio_flush_cb)(void *data, int64_t pts);
+
+/**
+ * Callback prototype for audio buffer drain
+ * (i.e. wait for pending buffers to be played).
+ * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
+ */
+typedef void (*libvlc_audio_drain_cb)(void *data);
+
+/**
+ * Callback prototype for audio volume change.
+ * \param data data pointer as passed to libvlc_audio_set_callbacks() [IN]
+ * \param volume software volume (1. = nominal, 0. = mute)
+ * \param mute muted flag
+ */
+typedef void (*libvlc_audio_set_volume_cb)(void *data,
+ float volume, bool mute);
+
+/**
+ * Set callbacks and private data for decoded audio.
+ * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
+ * to configure the decoded audio format.
+ *
+ * \param mp the media player
+ * \param play callback to play audio samples (must not be NULL)
+ * \param pause callback to pause playback (or NULL to ignore)
+ * \param resume callback to resume playback (or NULL to ignore)
+ * \param flush callback to flush audio buffers (or NULL to ignore)
+ * \param drain callback to drain audio buffers (or NULL to ignore)
+ * \param opaque private pointer for the audio callbacks (as first parameter)
+ * \version LibVLC 1.2.0 or later
+ */
+LIBVLC_API
+void libvlc_audio_set_callbacks( libvlc_media_player_t *mp,
+ libvlc_audio_play_cb play,
+ libvlc_audio_pause_cb pause,
+ libvlc_audio_resume_cb resume,
+ libvlc_audio_flush_cb flush,
+ libvlc_audio_drain_cb drain,
+ void *opaque );
+
+/**
+ * Set callbacks and private data for decoded audio.
+ * Use libvlc_audio_set_format() or libvlc_audio_set_format_callbacks()
+ * to configure the decoded audio format.
+ *
+ * \param mp the media player
+ * \param set_volume callback to apply audio volume,
+ * or NULL to apply volume in software
+ * \version LibVLC 1.2.0 or later
+ */
+LIBVLC_API
+void libvlc_audio_set_volume_callback( libvlc_media_player_t *mp,
+ libvlc_audio_set_volume_cb set_volume );
+
+/**
+ * Callback prototype to setup the audio playback.
+ * This is called when the media player needs to create a new audio output.
+ * \param opaque pointer to the data pointer passed to
+ * libvlc_audio_set_callbacks() [IN/OUT]
+ * \param format 4 bytes sample format [IN/OUT]
+ * \param rate sample rate [IN/OUT]
+ * \param channels channels count [IN/OUT]
+ * \return 0 on success, anything else to skip audio playback
+ */
+typedef int (*libvlc_audio_setup_cb)(void **data, char *format, unsigned *rate,
+ unsigned *channels);
+/**
+ * Callback prototype for audio playback cleanup.
+ * This is called when the media player no longer needs an audio output.
+ * \param opaque data pointer as passed to libvlc_audio_set_callbacks() [IN]
+ */
+typedef void (*libvlc_audio_cleanup_cb)(void *data);
+
+/**
+ * Set decoded audio format. This only works in combination with
+ * libvlc_audio_set_callbacks().
+ *
+ * \param mp the media player
+ * \param setup callback to select the audio format (cannot be NULL)
+ * \param cleanup callback to release any allocated resources (or NULL)
+ * \version LibVLC 1.2.0 or later
+ */
+LIBVLC_API
+void libvlc_audio_set_format_callbacks( libvlc_media_player_t *mp,
+ libvlc_audio_setup_cb setup,
+ libvlc_audio_cleanup_cb cleanup );
+
+/**
+ * Set decoded audio format.
+ * This only works in combination with libvlc_audio_set_callbacks(),
+ * and is mutually exclusive with libvlc_audio_set_format_callbacks().
+ *
+ * \param mp the media player
+ * \param format a four-characters string identifying the sample format
+ * (e.g. "S16N" or "FL32")
+ * \param rate sample rate (expressed in Hz)
+ * \param channels channels count
+ * \version LibVLC 1.2.0 or later
+ */
+LIBVLC_API
+void libvlc_audio_set_format( libvlc_media_player_t *mp, const char *format,
+ unsigned rate, unsigned channels );
/** \bug This might go away ... to be replaced by a broader system */
*
* \param p_mi the Media Player
* \return boolean
+ *
+ * \libvlc_return_bool
*/
LIBVLC_API int libvlc_media_player_will_play( libvlc_media_player_t *p_mi );
*
* \param p_mi the media player
* \return true if the media player can seek
+ *
+ * \libvlc_return_bool
*/
LIBVLC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi );
*
* \param p_mi the media player
* \return true if the media player can pause
+ *
+ * \libvlc_return_bool
*/
LIBVLC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi );
* \version libVLC 1.2.0 or later
*/
LIBVLC_API void libvlc_media_player_navigate( libvlc_media_player_t* p_mi,
- unsigned navigate );
+ unsigned navigate );
/**
* Release (free) libvlc_track_description_t
*
* \param p_mi the media player
* \return the fullscreen status (boolean)
+ *
+ * \libvlc_return_bool
*/
LIBVLC_API int libvlc_get_fullscreen( libvlc_media_player_t *p_mi );
* handled. This is needed for DVD menus to work, as well as a few video
* filters such as "puzzle".
*
- * \note See also libvlc_video_set_key_input().
+ * \see libvlc_video_set_key_input().
*
* \warning This function is only implemented for X11 and Win32 at the moment.
*
* \param p_mi media player
* \param psz_name name of audio output,
* use psz_name of \see libvlc_audio_output_t
- * \return true if function succeded
+ * \return 0 if function succeded, -1 on error
*/
LIBVLC_API int libvlc_audio_output_set( libvlc_media_player_t *p_mi,
const char *psz_name );
*
* \param p_mi media player
* \return the mute status (boolean)
+ *
+ * \libvlc_return_bool
*/
LIBVLC_API int libvlc_audio_get_mute( libvlc_media_player_t *p_mi );
LIBVLC_API void libvlc_audio_set_mute( libvlc_media_player_t *p_mi, int status );
/**
- * Get current audio level.
+ * Get current software audio volume.
*
* \param p_mi media player
- * \return the audio level (int)
+ * \return the software volume in percents
+ * (0 = mute, 100 = nominal / 0dB)
*/
LIBVLC_API int libvlc_audio_get_volume( libvlc_media_player_t *p_mi );
/**
- * Set current audio level.
+ * Set current software audio volume.
*
* \param p_mi media player
- * \param i_volume the volume (int)
+ * \param i_volume the volume in percents (0 = mute, 100 = 0dB)
* \return 0 if the volume was set, -1 if it was out of range
*/
LIBVLC_API int libvlc_audio_set_volume( libvlc_media_player_t *p_mi, int i_volume );