/*****************************************************************************
* libvlc_media_player.h: libvlc_media_player external API
*****************************************************************************
- * Copyright (C) 1998-2010 the VideoLAN team
+ * Copyright (C) 1998-2010 VLC authors and VideoLAN
* $Id$
*
* Authors: Clément Stenac <zorglub@videolan.org>
* Jean-Paul Saman <jpsaman@videolan.org>
* Pierre d'Herbemont <pdherbemont@videolan.org>
*
- * This program is free software; you can redistribute it and/or modify
- * it under the terms of the GNU General Public License as published by
- * the Free Software Foundation; either version 2 of the License, or
+ * This program is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation; either version 2.1 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
- * GNU General Public License for more details.
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Lesser General Public License for more details.
*
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
+ * You should have received a copy of the GNU Lesser General Public License
+ * along with this program; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
*****************************************************************************/
/**
} libvlc_audio_output_t;
+/**
+ * Description for audio output device.
+ */
+typedef struct libvlc_audio_output_device_t
+{
+ struct libvlc_audio_output_device_t *p_next; /**< Next entry in list */
+ char *psz_device; /**< Device identifier string */
+ char *psz_description; /**< User-friendly device description */
+ /* More fields may be added here in later versions */
+} libvlc_audio_output_device_t;
+
/**
* Rectangle type for video geometry
*/
libvlc_navigate_right
} libvlc_navigate_mode_t;
+/**
+ * Enumeration of values used to set position (e.g. of video title).
+ */
+typedef enum libvlc_position_t {
+ libvlc_position_disable=-1,
+ libvlc_position_center,
+ libvlc_position_left,
+ libvlc_position_right,
+ libvlc_position_top,
+ libvlc_position_top_left,
+ libvlc_position_top_right,
+ libvlc_position_bottom,
+ libvlc_position_bottom_left,
+ libvlc_position_bottom_right
+} libvlc_position_t;
+
/**
* Create an empty Media Player object
*
*
* \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 );
* \param mp the media player
* \param setup callback to select the video format (cannot be NULL)
* \param cleanup callback to release any allocated resources (or NULL)
- * \version LibVLC 1.2.0 or later
+ * \version LibVLC 2.0.0 or later
*/
LIBVLC_API
void libvlc_video_set_format_callbacks( libvlc_media_player_t *mp,
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 linear volume (1. = nominal, 0. = mute)
+ * \param volume software volume (1. = nominal, 0. = mute)
* \param mute muted flag
*/
typedef void (*libvlc_audio_set_volume_cb)(void *data,
*
* \param mp the media player
* \param play callback to play audio samples (must not be NULL)
- * \param set_volume callback to set audio volume, or NULL for software volume
- * \param opaque private pointer for the two callbacks (as first parameter)
- * \version LibVLC 1.2.0 or later
+ * \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 2.0.0 or later
*/
LIBVLC_API
void libvlc_audio_set_callbacks( libvlc_media_player_t *mp,
libvlc_audio_play_cb play,
- libvlc_audio_set_volume_cb set_volume,
+ 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 2.0.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 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
+ * \version LibVLC 2.0.0 or later
*/
LIBVLC_API
void libvlc_audio_set_format_callbacks( libvlc_media_player_t *mp,
* and is mutually exclusive with libvlc_audio_set_format_callbacks().
*
* \param mp the media player
- * \param fourcc a four-characters string identifying the sample format
+ * \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
+ * \version LibVLC 2.0.0 or later
*/
LIBVLC_API
void libvlc_audio_set_format( libvlc_media_player_t *mp, const char *format,
LIBVLC_API void libvlc_media_player_set_time( libvlc_media_player_t *p_mi, libvlc_time_t i_time );
/**
- * Get movie position.
+ * Get movie position as percentage between 0.0 and 1.0.
*
* \param p_mi the Media Player
* \return movie position, or -1. in case of error
LIBVLC_API float libvlc_media_player_get_position( libvlc_media_player_t *p_mi );
/**
- * Set movie position. This has no effect if playback is not enabled.
+ * Set movie position as percentage between 0.0 and 1.0.
+ * This has no effect if playback is not enabled.
* This might not work depending on the underlying input format and protocol.
*
* \param p_mi the Media Player
*
* \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 );
*
* \param p_mi the Media Player
* \param navigate the Navigation mode
- * \version libVLC 1.2.0 or later
+ * \version libVLC 2.0.0 or later
*/
LIBVLC_API void libvlc_media_player_navigate( libvlc_media_player_t* p_mi,
unsigned navigate );
+/**
+ * Set if, and how, the video title will be shown when media is played.
+ *
+ * \param p_mi the media player
+ * \param position position at which to display the title, or libvlc_position_disable to prevent the title from being displayed
+ * \param timeout title display timeout in milliseconds (ignored if libvlc_position_disable)
+ * \version libVLC 2.1.0 or later
+ */
+LIBVLC_API void libvlc_media_player_set_video_title_display( libvlc_media_player_t *p_mi, libvlc_position_t position, unsigned int timeout );
+
/**
* 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 LIBVLC_API
+void libvlc_track_description_release( libvlc_track_description_t *p_track_description );
/** \defgroup libvlc_video LibVLC video controls
* @{
*
* \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 the media player
* \return the video pixel height or 0 if not applicable
*/
-LIBVLC_DEPRECATED
+LIBVLC_DEPRECATED LIBVLC_API
int libvlc_video_get_height( libvlc_media_player_t *p_mi );
/**
* \param p_mi the media player
* \return the video pixel width or 0 if not applicable
*/
-LIBVLC_DEPRECATED
+LIBVLC_DEPRECATED LIBVLC_API
int libvlc_video_get_width( libvlc_media_player_t *p_mi );
/**
* Set new video subtitle.
*
* \param p_mi the media player
- * \param i_spu new video subtitle to select
+ * \param i_spu video subtitle track to select (i_id from track description)
* \return 0 on success, -1 if out of range
*/
-LIBVLC_API int libvlc_video_set_spu( libvlc_media_player_t *p_mi, unsigned i_spu );
+LIBVLC_API int libvlc_video_set_spu( libvlc_media_player_t *p_mi, int i_spu );
/**
* Set new video subtitle file.
*/
LIBVLC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *p_mi, const char *psz_subtitle );
+/**
+ * Get the current subtitle delay. Positive values means subtitles are being
+ * displayed later, negative values earlier.
+ *
+ * \param p_mi media player
+ * \return time (in microseconds) the display of subtitles is being delayed
+ * \version LibVLC 2.0.0 or later
+ */
+LIBVLC_API int64_t libvlc_video_get_spu_delay( libvlc_media_player_t *p_mi );
+
+/**
+ * Set the subtitle delay. This affects the timing of when the subtitle will
+ * be displayed. Positive values result in subtitles being displayed later,
+ * while negative values will result in subtitles being displayed earlier.
+ *
+ * The subtitle delay will be reset to zero each time the media changes.
+ *
+ * \param p_mi media player
+ * \param i_delay time (in microseconds) the display of subtitles should be delayed
+ * \return 0 on success, -1 on error
+ * \version LibVLC 2.0.0 or later
+ */
+LIBVLC_API int libvlc_video_set_spu_delay( libvlc_media_player_t *p_mi, int64_t i_delay );
+
/**
* Get the description of available titles.
*
* Get current video track.
*
* \param p_mi media player
- * \return the video track (int) or -1 if none
+ * \return the video track ID (int) or -1 if no active input
*/
LIBVLC_API int libvlc_video_get_track( libvlc_media_player_t *p_mi );
* Set video track.
*
* \param p_mi media player
- * \param i_track the track (int)
+ * \param i_track the track ID (i_id field from track description)
* \return 0 on success, -1 if out of range
*/
LIBVLC_API
/**
- * Get the list of available audio outputs
+ * Gets the list of available audio outputs
*
* \param p_instance libvlc instance
* \return list of available audio outputs. It must be freed it with
* In case of error, NULL is returned.
*/
LIBVLC_API libvlc_audio_output_t *
- libvlc_audio_output_list_get( libvlc_instance_t *p_instance );
+libvlc_audio_output_list_get( libvlc_instance_t *p_instance );
/**
- * Free the list of available audio outputs
+ * Frees the list of available audio outputs
*
* \param p_list list with audio outputs for release
*/
-LIBVLC_API void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list );
+LIBVLC_API
+void libvlc_audio_output_list_release( libvlc_audio_output_t *p_list );
/**
- * Set the audio output.
- * Change will be applied after stop and play.
+ * Sets the audio output.
+ * \note Any change will take be effect only after playback is stopped and
+ * restarted. Audio output cannot be changed while playing.
*
* \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 );
+ const char *psz_name );
/**
- * Get count of devices for audio output, these devices are hardware oriented
- * like analor or digital output of sound card
- *
- * \param p_instance libvlc instance
- * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
- * \return number of devices
+ * Backward compatibility stub. Do not use in new code.
+ * Use libvlc_audio_output_device_list_get() instead.
+ * \return always 0.
*/
-LIBVLC_API int libvlc_audio_output_device_count( libvlc_instance_t *p_instance,
- const char *psz_audio_output );
+LIBVLC_DEPRECATED LIBVLC_API
+int libvlc_audio_output_device_count( libvlc_instance_t *, const char * );
/**
- * Get long name of device, if not available short name given
+ * Backward compatibility stub. Do not use in new code.
+ * Use libvlc_audio_output_device_list_get() instead.
+ * \return always NULL.
+ */
+LIBVLC_DEPRECATED LIBVLC_API
+char *libvlc_audio_output_device_longname( libvlc_instance_t *, const char *,
+ int );
+
+/**
+ * Backward compatibility stub. Do not use in new code.
+ * Use libvlc_audio_output_device_list_get() instead.
+ * \return always NULL.
+ */
+LIBVLC_DEPRECATED LIBVLC_API
+char *libvlc_audio_output_device_id( libvlc_instance_t *, const char *, int );
+
+/**
+ * Gets a list of audio output devices for a given audio output.
+ * \see libvlc_audio_output_device_set().
+ *
+ * \note Not all audio outputs support this. In particular, an empty (NULL)
+ * list of devices does <b>not</b> imply that the specified audio output does
+ * not work.
+ *
+ * \note The list might not be exhaustive.
+ *
+ * \warning Some audio output devices in the list might not actually work in
+ * some circumstances. By default, it is recommended to not specify any
+ * explicit audio device.
*
* \param p_instance libvlc instance
- * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
- * \param i_device device index
- * \return long name of device
+ * \param psz_aout audio output name
+ * (as returned by libvlc_audio_output_list_get())
+ * \return A NULL-terminated linked list of potential audio output devices.
+ * It must be freed it with libvlc_audio_output_device_list_release()
+ * \version LibVLC 2.1.0 or later.
*/
-LIBVLC_API char * libvlc_audio_output_device_longname( libvlc_instance_t *p_instance,
- const char *psz_audio_output,
- int i_device );
+LIBVLC_API libvlc_audio_output_device_t *
+libvlc_audio_output_device_list_get( libvlc_instance_t *p_instance,
+ const char *aout );
/**
- * Get id name of device
+ * Frees a list of available audio output devices.
*
- * \param p_instance libvlc instance
- * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
- * \param i_device device index
- * \return id name of device, use for setting device, need to be free after use
+ * \param p_list list with audio outputs for release
+ * \version LibVLC 2.1.0 or later.
*/
-LIBVLC_API char * libvlc_audio_output_device_id( libvlc_instance_t *p_instance,
- const char *psz_audio_output,
- int i_device );
+LIBVLC_API void libvlc_audio_output_device_list_release(
+ libvlc_audio_output_device_t *p_list );
/**
- * Set audio output device. Changes are only effective after stop and play.
+ * Configures an explicit audio output device for a given audio output plugin.
+ * A list of possible devices can be obtained with
+ * libvlc_audio_output_device_list_get().
+ *
+ * \note This function does not select the specified audio output plugin.
+ * libvlc_audio_output_set() is used for that purpose.
+ *
+ * \warning The syntax for the device parameter depends on the audio output.
+ * This is not portable. Only use this function if you know what you are doing.
+ * Some audio outputs do not support this function (e.g. PulseAudio, WASAPI).
+ * Some audio outputs require further parameters (e.g. ALSA: channels map).
*
* \param p_mi media player
* \param psz_audio_output - name of audio output, \see libvlc_audio_output_t
* \param psz_device_id device
+ * \return Nothing. Errors are ignored.
*/
LIBVLC_API void libvlc_audio_output_device_set( libvlc_media_player_t *p_mi,
- const char *psz_audio_output,
- const char *psz_device_id );
+ const char *psz_audio_output,
+ const char *psz_device_id );
/**
- * Get current audio device type. Device type describes something like
- * character of output sound - stereo sound, 2.1, 5.1 etc
- *
- * \param p_mi media player
- * \return the audio devices type \see libvlc_audio_output_device_types_t
+ * Stub for backward compatibility.
+ * \return always -1.
*/
+LIBVLC_DEPRECATED
LIBVLC_API int libvlc_audio_output_get_device_type( libvlc_media_player_t *p_mi );
/**
- * Set current audio device type.
- *
- * \param p_mi vlc instance
- * \param device_type the audio device type,
- according to \see libvlc_audio_output_device_types_t
+ * Stub for backward compatibility.
*/
-LIBVLC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *p_mi,
- int device_type );
+LIBVLC_DEPRECATED
+LIBVLC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *,
+ int );
/**
* Toggle mute status.
*
* \param p_mi media player
+ * \warning Toggling mute atomically is not always possible: On some platforms,
+ * other processes can mute the VLC audio playback stream asynchronously. Thus,
+ * there is a small race condition where toggling will not work.
+ * See also the limitations of libvlc_audio_set_mute().
*/
LIBVLC_API void libvlc_audio_toggle_mute( libvlc_media_player_t *p_mi );
* Get current mute status.
*
* \param p_mi media player
- * \return the mute status (boolean)
+ * \return the mute status (boolean) if defined, -1 if undefined/unapplicable
*/
LIBVLC_API int libvlc_audio_get_mute( libvlc_media_player_t *p_mi );
*
* \param p_mi media player
* \param status If status is true then mute, otherwise unmute
+ * \warning This function does not always work. If there are no active audio
+ * playback stream, the mute status might not be available. If digital
+ * pass-through (S/PDIF, HDMI...) is in use, muting may be unapplicable. Also
+ * some audio output plugins do not support muting at all.
+ * \note To force silent playback, disable all audio tracks. This is more
+ * efficient and reliable than mute.
*/
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 );
* Get current audio track.
*
* \param p_mi media player
- * \return the audio track (int), or -1 if none.
+ * \return the audio track ID or -1 if no active input.
*/
LIBVLC_API int libvlc_audio_get_track( libvlc_media_player_t *p_mi );
* Set current audio track.
*
* \param p_mi media player
- * \param i_track the track (int)
+ * \param i_track the track ID (i_id field from track description)
* \return 0 on success, -1 on error
*/
LIBVLC_API int libvlc_audio_set_track( libvlc_media_player_t *p_mi, int i_track );
projects / vlc / blobdiff