X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc_media_player.h;h=529e0fde481572907dd445cc61f60972910dd7d6;hb=32653c834194f78086e781bc336ab8c0e35c8c63;hp=8cdbf23c71c6896edf9bbc779ff990212abe7efd;hpb=6a06521577edabfbc7ab1191adede2c86767b7f3;p=vlc diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h index 8cdbf23c71..529e0fde48 100644 --- a/include/vlc/libvlc_media_player.h +++ b/include/vlc/libvlc_media_player.h @@ -33,6 +33,8 @@ # ifdef __cplusplus extern "C" { +# else +# include # endif /***************************************************************************** @@ -84,7 +86,7 @@ typedef struct libvlc_rectangle_t */ 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, @@ -177,6 +179,8 @@ LIBVLC_API libvlc_event_manager_t * libvlc_media_player_event_manager ( libvlc_m * * \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 ); @@ -461,7 +465,141 @@ LIBVLC_API void libvlc_media_player_set_hwnd ( libvlc_media_player_t *p_mi, void */ 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 */ @@ -536,6 +674,8 @@ LIBVLC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t *p_m * * \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 ); @@ -638,6 +778,8 @@ LIBVLC_API unsigned libvlc_media_player_has_vout( 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 ); @@ -646,6 +788,8 @@ 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 ); @@ -665,14 +809,19 @@ LIBVLC_API void libvlc_media_player_next_frame( 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_track_description the structure to release */ -LIBVLC_API void libvlc_track_description_release( libvlc_track_description_t *p_track_description ); +LIBVLC_API void libvlc_track_description_list_release( libvlc_track_description_t *p_track_description ); + +/** + * \deprecated Use libvlc_track_description_list_release instead + */ +LIBVLC_DEPRECATED void libvlc_track_description_release( libvlc_track_description_t *p_track_description ); /** \defgroup libvlc_video LibVLC video controls * @{ @@ -708,6 +857,8 @@ LIBVLC_API void libvlc_set_fullscreen( libvlc_media_player_t *p_mi, int b_fullsc * * \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 ); @@ -734,7 +885,7 @@ void libvlc_video_set_key_input( libvlc_media_player_t *p_mi, unsigned on ); * 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. * @@ -1210,7 +1361,7 @@ LIBVLC_API void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list * \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 ); @@ -1293,6 +1444,8 @@ LIBVLC_API void libvlc_audio_toggle_mute( libvlc_media_player_t *p_mi ); * * \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 ); @@ -1305,18 +1458,19 @@ 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 );