X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc_media_player.h;h=fd97ff30b2b23ed8ab678b5208339a84ca8fc087;hb=09020b63ba7513eeaff38f1cc40e2b4937c61030;hp=4f47f580c859359498559212ecb6ad54552a9897;hpb=a1416de0dc192cca29948ceaf1017bd14751613a;p=vlc diff --git a/include/vlc/libvlc_media_player.h b/include/vlc/libvlc_media_player.h index 4f47f580c8..fd97ff30b2 100644 --- a/include/vlc/libvlc_media_player.h +++ b/include/vlc/libvlc_media_player.h @@ -101,18 +101,18 @@ typedef enum libvlc_video_marquee_option_t { * * \param p_libvlc_instance the libvlc instance in which the Media Player * should be created. - * \param p_e an initialized exception pointer + * \return a new media player object, or NULL on error. */ -VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t *, libvlc_exception_t * ); +VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new( libvlc_instance_t * ); /** * Create a Media Player object from a Media * * \param p_md the media. Afterwards the p_md can be safely * destroyed. - * \param p_e an initialized exception pointer + * \return a new media player object, or NULL on error. */ -VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t *, libvlc_exception_t * ); +VLC_PUBLIC_API libvlc_media_player_t * libvlc_media_player_new_from_media( libvlc_media_t * ); /** * Release a media_player after use @@ -172,23 +172,21 @@ VLC_PUBLIC_API int libvlc_media_player_is_playing ( libvlc_media_player_t * ); * Play * * \param p_mi the Media Player - * \param p_e an initialized exception pointer + * \return 0 if playback started (and was already started), or -1 on error. */ -VLC_PUBLIC_API void libvlc_media_player_play ( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_media_player_play ( libvlc_media_player_t * ); /** - * Pause + * Toggle pause (no effect if there is no media) * * \param p_mi the Media Player - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_media_player_pause ( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API void libvlc_media_player_pause ( libvlc_media_player_t * ); /** - * Stop + * Stop (no effect if there is no media) * * \param p_mi the Media Player - * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_media_player_stop ( libvlc_media_player_t * ); @@ -292,160 +290,146 @@ VLC_PUBLIC_API void *libvlc_media_player_get_hwnd ( libvlc_media_player_t *p_mi * Get the current movie length (in ms). * * \param p_mi the Media Player - * \param p_e an initialized exception pointer - * \return the movie length (in ms). + * \return the movie length (in ms), or -1 if there is no media. */ -VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_length( libvlc_media_player_t * ); /** * Get the current movie time (in ms). * * \param p_mi the Media Player - * \param p_e an initialized exception pointer - * \return the movie time (in ms). + * \return the movie time (in ms), or -1 if there is no media. */ -VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API libvlc_time_t libvlc_media_player_get_time( libvlc_media_player_t * ); /** - * Set the movie time (in ms). + * Set the movie time (in ms). This has no effect if no media is being played. + * Not all formats and protocols support this. * * \param p_mi the Media Player * \param the movie time (in ms). - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_media_player_set_time( libvlc_media_player_t *, libvlc_time_t, libvlc_exception_t *); +VLC_PUBLIC_API void libvlc_media_player_set_time( libvlc_media_player_t *, libvlc_time_t ); /** * Get movie position. * * \param p_mi the Media Player - * \param p_e an initialized exception pointer - * \return movie position + * \return movie position, or -1. in case of error */ -VLC_PUBLIC_API float libvlc_media_player_get_position( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API float libvlc_media_player_get_position( libvlc_media_player_t * ); /** - * Set movie position. + * Set movie position. 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 f_pos the position - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_media_player_set_position( libvlc_media_player_t *, float, libvlc_exception_t *); +VLC_PUBLIC_API void libvlc_media_player_set_position( libvlc_media_player_t *, float ); /** - * Set movie chapter + * Set movie chapter (if applicable). * * \param p_mi the Media Player * \param i_chapter chapter number to play - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *, int, libvlc_exception_t *); +VLC_PUBLIC_API void libvlc_media_player_set_chapter( libvlc_media_player_t *, int ); /** - * Get movie chapter + * Get movie chapter. * * \param p_mi the Media Player - * \param p_e an initialized exception pointer - * \return chapter number currently playing + * \return chapter number currently playing, or -1 if there is no media. */ -VLC_PUBLIC_API int libvlc_media_player_get_chapter( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_media_player_get_chapter( libvlc_media_player_t * ); /** * Get movie chapter count * * \param p_mi the Media Player - * \param p_e an initialized exception pointer - * \return number of chapters in movie + * \return number of chapters in movie, or -1. */ -VLC_PUBLIC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API int libvlc_media_player_get_chapter_count( libvlc_media_player_t * ); /** - * Will the player play + * Is the player able to play * * \param p_mi the Media Player - * \param p_e an initialized exception pointer * \return boolean */ -VLC_PUBLIC_API int libvlc_media_player_will_play ( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API int libvlc_media_player_will_play( libvlc_media_player_t * ); /** * Get title chapter count * * \param p_mi the Media Player * \param i_title title - * \param p_e an initialized exception pointer - * \return number of chapters in title + * \return number of chapters in title, or -1 */ VLC_PUBLIC_API int libvlc_media_player_get_chapter_count_for_title( - libvlc_media_player_t *, int, libvlc_exception_t *); + libvlc_media_player_t *, int ); /** * Set movie title * * \param p_mi the Media Player * \param i_title title number to play - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_media_player_set_title( libvlc_media_player_t *, int, libvlc_exception_t *); +VLC_PUBLIC_API void libvlc_media_player_set_title( libvlc_media_player_t *, int ); /** * Get movie title * * \param p_mi the Media Player - * \param p_e an initialized exception pointer - * \return title number currently playing + * \return title number currently playing, or -1 */ -VLC_PUBLIC_API int libvlc_media_player_get_title( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API int libvlc_media_player_get_title( libvlc_media_player_t * ); /** * Get movie title count * * \param p_mi the Media Player - * \param p_e an initialized exception pointer - * \return title number count + * \return title number count, or -1 */ -VLC_PUBLIC_API int libvlc_media_player_get_title_count( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API int libvlc_media_player_get_title_count( libvlc_media_player_t * ); /** - * Set previous chapter + * Set previous chapter (if applicable) * * \param p_mi the Media Player - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API void libvlc_media_player_previous_chapter( libvlc_media_player_t * ); /** - * Set next chapter + * Set next chapter (if applicable) * * \param p_mi the Media Player - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_media_player_next_chapter( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API void libvlc_media_player_next_chapter( libvlc_media_player_t * ); /** * Get movie play rate * * \param p_mi the Media Player - * \param p_e an initialized exception pointer - * \return movie play rate + * \return movie play rate, or zero in case of error */ -VLC_PUBLIC_API float libvlc_media_player_get_rate( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API float libvlc_media_player_get_rate( libvlc_media_player_t * ); /** * Set movie play rate * * \param p_mi the Media Player * \param movie play rate to set - * \param p_e an initialized exception pointer + * \return -1 if an error was detected, 0 otherwise (but even then, it might + * not actually work depending on the underlying media protocol) */ -VLC_PUBLIC_API void libvlc_media_player_set_rate( libvlc_media_player_t *, float, libvlc_exception_t *); +VLC_PUBLIC_API int libvlc_media_player_set_rate( libvlc_media_player_t *, float ); /** * Get current movie state * * \param p_mi the Media Player - * \param p_e an initialized exception pointer */ VLC_PUBLIC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player_t *); @@ -453,10 +437,9 @@ VLC_PUBLIC_API libvlc_state_t libvlc_media_player_get_state( libvlc_media_player * Get movie fps rate * * \param p_mi the Media Player - * \param p_e an initialized exception pointer - * \return frames per second (fps) for this playing movie + * \return frames per second (fps) for this playing movie, or 0 if unspecified */ -VLC_PUBLIC_API float libvlc_media_player_get_fps( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API float libvlc_media_player_get_fps( libvlc_media_player_t * ); /** end bug */ @@ -464,35 +447,30 @@ VLC_PUBLIC_API float libvlc_media_player_get_fps( libvlc_media_player_t *, libvl * Does this media player have a video output? * * \param p_md the media player - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API int libvlc_media_player_has_vout( libvlc_media_player_t *, libvlc_exception_t *); +VLC_PUBLIC_API int libvlc_media_player_has_vout( libvlc_media_player_t * ); /** * Is this media player seekable? * * \param p_input the input - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi, libvlc_exception_t *p_e ); +VLC_PUBLIC_API int libvlc_media_player_is_seekable( libvlc_media_player_t *p_mi ); /** * Can this media player be paused? * * \param p_input the input - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi, libvlc_exception_t *p_e ); +VLC_PUBLIC_API int libvlc_media_player_can_pause( libvlc_media_player_t *p_mi ); /** - * Display the next frame + * Display the next frame (if supported) * * \param p_input the libvlc_media_player_t instance - * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_input, - libvlc_exception_t *p_e ); +VLC_PUBLIC_API void libvlc_media_player_next_frame( libvlc_media_player_t *p_input ); @@ -668,7 +646,7 @@ VLC_PUBLIC_API int libvlc_video_get_spu_count( libvlc_media_player_t *, libvlc_e * \return list containing description of available video subtitles */ VLC_PUBLIC_API libvlc_track_description_t * - libvlc_video_get_spu_description( libvlc_media_player_t *, libvlc_exception_t * ); + libvlc_video_get_spu_description( libvlc_media_player_t * ); /** * Set new video subtitle. @@ -687,7 +665,7 @@ VLC_PUBLIC_API void libvlc_video_set_spu( libvlc_media_player_t *, int , libvlc_ * \param p_e an initialized exception pointer * \return the success status (boolean) */ -VLC_PUBLIC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *, const char *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *, const char * ); /** * Get the description of available titles. @@ -697,7 +675,7 @@ VLC_PUBLIC_API int libvlc_video_set_subtitle_file( libvlc_media_player_t *, cons * \return list containing description of available titles */ VLC_PUBLIC_API libvlc_track_description_t * - libvlc_video_get_title_description( libvlc_media_player_t *, libvlc_exception_t * ); + libvlc_video_get_title_description( libvlc_media_player_t * ); /** * Get the description of available chapters for specific title. @@ -708,7 +686,7 @@ VLC_PUBLIC_API libvlc_track_description_t * * \return list containing description of available chapter for title i_title */ VLC_PUBLIC_API libvlc_track_description_t * - libvlc_video_get_chapter_description( libvlc_media_player_t *, int, libvlc_exception_t * ); + libvlc_video_get_chapter_description( libvlc_media_player_t *, int ); /** * Get current crop filter geometry. @@ -734,26 +712,25 @@ VLC_PUBLIC_API void libvlc_video_set_crop_geometry( libvlc_media_player_t *, con * \param p_mediaplayer the media player * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_toggle_teletext( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API void libvlc_toggle_teletext( libvlc_media_player_t * ); /** * Get number of available video tracks. * * \param p_mi media player - * \param p_e an initialized exception * \return the number of available video tracks (int) */ -VLC_PUBLIC_API int libvlc_video_get_track_count( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_video_get_track_count( libvlc_media_player_t * ); /** * Get the description of available video tracks. * * \param p_mi media player * \param p_e an initialized exception - * \return list with description of available video tracks + * \return list with description of available video tracks, or NULL on error */ VLC_PUBLIC_API libvlc_track_description_t * - libvlc_video_get_track_description( libvlc_media_player_t *, libvlc_exception_t * ); + libvlc_video_get_track_description( libvlc_media_player_t * ); /** * Get current video track. @@ -951,12 +928,12 @@ VLC_PUBLIC_API void libvlc_audio_output_list_release( libvlc_audio_output_t * ); * Set the audio output. * Change will be applied after stop and play. * - * \param p_instance libvlc instance + * \param mp media player * \param psz_name name of audio output, * use psz_name of \see libvlc_audio_output_t * \return true if function succeded */ -VLC_PUBLIC_API int libvlc_audio_output_set( libvlc_instance_t *, +VLC_PUBLIC_API int libvlc_audio_output_set( libvlc_media_player_t *, const char * ); /** @@ -995,13 +972,13 @@ VLC_PUBLIC_API char * libvlc_audio_output_device_id( libvlc_instance_t *, int ); /** - * Set device for using + * Set audio output device. Changes are only effective after stop and play. * - * \param p_instance libvlc instance + * \param mp media player * \param psz_audio_output - name of audio output, \see libvlc_audio_output_t * \param psz_device_id device */ -VLC_PUBLIC_API void libvlc_audio_output_device_set( libvlc_instance_t *, +VLC_PUBLIC_API void libvlc_audio_output_device_set( libvlc_media_player_t *, const char *, const char * ); @@ -1009,124 +986,115 @@ VLC_PUBLIC_API void libvlc_audio_output_device_set( libvlc_instance_t *, * Get current audio device type. Device type describes something like * character of output sound - stereo sound, 2.1, 5.1 etc * - * \param p_instance vlc instance - * \param p_e an initialized exception pointer + * \param mp media player * \return the audio devices type \see libvlc_audio_output_device_types_t */ VLC_PUBLIC_API int libvlc_audio_output_get_device_type( - libvlc_instance_t *, libvlc_exception_t * ); + libvlc_media_player_t * ); /** * Set current audio device type. * - * \param p_instance vlc instance + * \param mp vlc instance * \param device_type the audio device type, according to \see libvlc_audio_output_device_types_t * \param p_e an initialized exception pointer */ -VLC_PUBLIC_API void libvlc_audio_output_set_device_type( libvlc_instance_t *, - int, - libvlc_exception_t * ); +VLC_PUBLIC_API void libvlc_audio_output_set_device_type( libvlc_media_player_t *, + int ); /** * Toggle mute status. * - * \param p_instance libvlc instance + * \param mp media player */ -VLC_PUBLIC_API void libvlc_audio_toggle_mute( libvlc_instance_t * ); +VLC_PUBLIC_API void libvlc_audio_toggle_mute( libvlc_media_player_t * ); /** * Get current mute status. * - * \param p_instance libvlc instance + * \param mp media player * \return the mute status (boolean) */ -VLC_PUBLIC_API int libvlc_audio_get_mute( libvlc_instance_t * ); +VLC_PUBLIC_API int libvlc_audio_get_mute( libvlc_media_player_t * ); /** * Set mute status. * - * \param p_instance libvlc instance + * \param mp media player * \param status If status is true then mute, otherwise unmute */ -VLC_PUBLIC_API void libvlc_audio_set_mute( libvlc_instance_t *, int ); +VLC_PUBLIC_API void libvlc_audio_set_mute( libvlc_media_player_t *, int ); /** * Get current audio level. * - * \param p_instance libvlc instance + * \param mp media player * \param p_e an initialized exception pointer * \return the audio level (int) */ -VLC_PUBLIC_API int libvlc_audio_get_volume( libvlc_instance_t * ); +VLC_PUBLIC_API int libvlc_audio_get_volume( libvlc_media_player_t * ); /** * Set current audio level. * - * \param p_instance libvlc instance + * \param mp media player * \param i_volume the volume (int) - * \param p_e an initialized exception pointer + * \return 0 if the volume was set, -1 if it was out of range */ -VLC_PUBLIC_API void libvlc_audio_set_volume( libvlc_instance_t *, int, libvlc_exception_t *); +VLC_PUBLIC_API int libvlc_audio_set_volume( libvlc_media_player_t *, int ); /** * Get number of available audio tracks. * * \param p_mi media player - * \param p_e an initialized exception - * \return the number of available audio tracks (int) + * \return the number of available audio tracks (int), or -1 if unavailable */ -VLC_PUBLIC_API int libvlc_audio_get_track_count( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_audio_get_track_count( libvlc_media_player_t * ); /** * Get the description of available audio tracks. * * \param p_mi media player - * \param p_e an initialized exception - * \return list with description of available audio tracks + * \return list with description of available audio tracks, or NULL */ VLC_PUBLIC_API libvlc_track_description_t * - libvlc_audio_get_track_description( libvlc_media_player_t *, libvlc_exception_t * ); + libvlc_audio_get_track_description( libvlc_media_player_t * ); /** * Get current audio track. * * \param p_mi media player - * \param p_e an initialized exception pointer - * \return the audio track (int) + * \return the audio track (int), or -1 if none. */ -VLC_PUBLIC_API int libvlc_audio_get_track( libvlc_media_player_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_audio_get_track( libvlc_media_player_t * ); /** * Set current audio track. * * \param p_mi media player * \param i_track the track (int) - * \param p_e an initialized exception pointer + * \return 0 on success, -1 on error */ -VLC_PUBLIC_API void libvlc_audio_set_track( libvlc_media_player_t *, int, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_audio_set_track( libvlc_media_player_t *, int ); /** * Get current audio channel. * - * \param p_instance vlc instance - * \param p_e an initialized exception pointer + * \param mp media player * \return the audio channel \see libvlc_audio_output_channel_t */ -VLC_PUBLIC_API int - libvlc_audio_get_channel( libvlc_instance_t *, libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_audio_get_channel( libvlc_media_player_t * ); /** * Set current audio channel. * - * \param p_instance vlc instance + * \param p_mi media player * \param channel the audio channel, \see libvlc_audio_output_channel_t - * \param p_e an initialized exception pointer + * \return 0 on success, -1 on error */ -VLC_PUBLIC_API void libvlc_audio_set_channel( libvlc_instance_t *, - int, - libvlc_exception_t * ); +VLC_PUBLIC_API int libvlc_audio_set_channel( libvlc_media_player_t *, int ); /** @} audio */