X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc_media.h;h=075a1c670f32db3c7bcd16080a1f0b7a37eb1cb5;hb=2d7c19fd30f7562eb8477852991a5ea955a1c691;hp=e21dca2c141d50859d268997a5373dc2dd4a05f1;hpb=47648bd4ca8b4a50990629925b6e4b96b1087f0d;p=vlc diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h index e21dca2c14..075a1c670f 100644 --- a/include/vlc/libvlc_media.h +++ b/include/vlc/libvlc_media.h @@ -31,24 +31,25 @@ #ifndef VLC_LIBVLC_MEDIA_H #define VLC_LIBVLC_MEDIA_H 1 -/***************************************************************************** - * media - *****************************************************************************/ -/** \defgroup libvlc_media libvlc_media +# ifdef __cplusplus +extern "C" { +# endif + +/** \defgroup libvlc_media LibVLC media * \ingroup libvlc - * LibVLC Media + * @ref libvlc_media_t is an abstract representation of a playable media. + * It consists of a media location and various optional meta data. * @{ */ typedef struct libvlc_media_t libvlc_media_t; -/* Meta Handling */ -/** defgroup libvlc_meta libvlc_meta +/** defgroup libvlc_meta LibVLC meta data * \ingroup libvlc_media - * LibVLC Media Meta * @{ */ +/** Meta data types */ typedef enum libvlc_meta_t { libvlc_meta_Title, libvlc_meta_Artist, @@ -93,37 +94,109 @@ typedef enum libvlc_state_t libvlc_Error } libvlc_state_t; -typedef enum libvlc_media_option_t +enum { libvlc_media_option_trusted = 0x2, libvlc_media_option_unique = 0x100 -} libvlc_media_option_t; +}; + +typedef enum libvlc_es_type_t +{ + libvlc_es_unknown = -1, + libvlc_es_audio = 0, + libvlc_es_video = 1, + libvlc_es_text = 2, +} libvlc_es_type_t; + +/** defgroup libvlc_media_stats_t LibVLC media statistics + * \ingroup libvlc_media + * @{ + */ +typedef struct libvlc_media_stats_t +{ + /* Input */ + int i_read_bytes; + float f_input_bitrate; + + /* Demux */ + int i_demux_read_bytes; + float f_demux_bitrate; + int i_demux_corrupted; + int i_demux_discontinuity; + + /* Decoders */ + int i_decoded_video; + int i_decoded_audio; + + /* Video Output */ + int i_displayed_pictures; + int i_lost_pictures; + + /* Audio output */ + int i_played_abuffers; + int i_lost_abuffers; + + /* Stream output */ + int i_sent_packets; + int i_sent_bytes; + float f_send_bitrate; +} libvlc_media_stats_t; +/** @}*/ + +typedef struct libvlc_media_es_t +{ + /* Codec fourcc */ + uint32_t i_codec; + int i_id; + libvlc_es_type_t i_type; + + /* Codec specific */ + int i_profile; + int i_level; + + /* Audio specific */ + unsigned i_channels; + unsigned i_rate; + + /* Video specific */ + unsigned i_height; + unsigned i_width; + +} libvlc_media_es_t; + /** - * Create a media with the given MRL. + * Create a media with a certain given media resource location. * * \param p_instance the instance * \param psz_mrl the MRL to read - * \param p_e an initialized exception pointer - * \return the newly created media + * \return the newly created media or NULL on error */ -VLC_PUBLIC_API libvlc_media_t * libvlc_media_new( +VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_location( libvlc_instance_t *p_instance, - const char * psz_mrl, - libvlc_exception_t *p_e ); + const char * psz_mrl ); /** - * Create a media as an empty node with the passed name. + * Create a media with a certain file path. + * + * \param p_instance the instance + * \param path local filesystem path + * \return the newly created media or NULL on error + */ +VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_path( + libvlc_instance_t *p_instance, + const char *path ); + +/** + * Create a media as an empty node with a given name. * * \param p_instance the instance * \param psz_name the name of the node - * \param p_e an initialized exception pointer - * \return the new empty media + * \return the new empty media or NULL on error */ VLC_PUBLIC_API libvlc_media_t * libvlc_media_new_as_node( libvlc_instance_t *p_instance, - const char * psz_name, - libvlc_exception_t *p_e ); + const char * psz_name ); /** * Add an option to the media. @@ -134,14 +207,13 @@ VLC_PUBLIC_API libvlc_media_t * libvlc_media_new_as_node( * * The options are detailed in vlc --long-help, for instance "--sout-all" * - * \param p_instance the instance + * \param p_md the media descriptor * \param ppsz_options the options (as a string) - * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_media_add_option( libvlc_media_t * p_md, - const char * ppsz_options, - libvlc_exception_t * p_e ); + const char * ppsz_options ); + /** * Add an option to the media with configurable flags. * @@ -151,16 +223,14 @@ VLC_PUBLIC_API void libvlc_media_add_option( * * The options are detailed in vlc --long-help, for instance "--sout-all" * - * \param p_instance the instance + * \param p_md the media descriptor * \param ppsz_options the options (as a string) * \param i_flags the flags for this option - * \param p_e an initialized exception pointer */ VLC_PUBLIC_API void libvlc_media_add_option_flag( libvlc_media_t * p_md, const char * ppsz_options, - libvlc_media_option_t i_flags, - libvlc_exception_t * p_e ); + unsigned i_flags ); /** @@ -168,10 +238,9 @@ VLC_PUBLIC_API void libvlc_media_add_option_flag( * libvlc_media_release() to decrement the reference count of a * media descriptor object. * - * \param p_meta_desc a media descriptor object. + * \param p_md the media descriptor */ -VLC_PUBLIC_API void libvlc_media_retain( - libvlc_media_t *p_meta_desc ); +VLC_PUBLIC_API void libvlc_media_retain( libvlc_media_t *p_md ); /** * Decrement the reference count of a media descriptor object. If the @@ -180,41 +249,58 @@ VLC_PUBLIC_API void libvlc_media_retain( * to all listeners. If the media descriptor object has been released it * should not be used again. * - * \param p_meta_desc a media descriptor object. + * \param p_md the media descriptor */ -VLC_PUBLIC_API void libvlc_media_release( - libvlc_media_t *p_meta_desc ); +VLC_PUBLIC_API void libvlc_media_release( libvlc_media_t *p_md ); /** * Get the media resource locator (mrl) from a media descriptor object * * \param p_md a media descriptor object - * \param p_e an initialized exception object * \return string with mrl of media descriptor object */ -VLC_PUBLIC_API char * libvlc_media_get_mrl( libvlc_media_t * p_md, - libvlc_exception_t * p_e ); +VLC_PUBLIC_API char * libvlc_media_get_mrl( libvlc_media_t * p_md ); /** * Duplicate a media descriptor object. * - * \param p_meta_desc a media descriptor object. + * \param p_md a media descriptor object. */ -VLC_PUBLIC_API libvlc_media_t * libvlc_media_duplicate( libvlc_media_t * ); +VLC_PUBLIC_API libvlc_media_t * libvlc_media_duplicate( libvlc_media_t *p_md ); /** * Read the meta of the media. * - * \param p_meta_desc the media to read + * \param p_md the media descriptor * \param e_meta the meta to read - * \param p_e an initialized exception pointer * \return the media's meta */ -VLC_PUBLIC_API char * libvlc_media_get_meta( - libvlc_media_t *p_meta_desc, - libvlc_meta_t e_meta, - libvlc_exception_t *p_e ); +VLC_PUBLIC_API char * libvlc_media_get_meta( libvlc_media_t *p_md, + libvlc_meta_t e_meta ); + +/** + * Set the meta of the media (this function will not save the meta, call + * libvlc_media_save_meta in order to save the meta) + * + * \param p_md the media descriptor + * \param e_meta the meta to write + * \param psz_value the media's meta + */ +VLC_PUBLIC_API void libvlc_media_set_meta( libvlc_media_t *p_md, + libvlc_meta_t e_meta, + const char *psz_value ); + + +/** + * Save the meta previously set + * + * \param p_md the media desriptor + * \return true if the write operation was successfull + */ +VLC_PUBLIC_API int libvlc_media_save_meta( libvlc_media_t *p_md ); + + /** * Get current state of media descriptor object. Possible media states * are defined in libvlc_structures.c ( libvlc_NothingSpecial=0, @@ -224,21 +310,28 @@ VLC_PUBLIC_API char * libvlc_media_get_meta( * * @see libvlc_state_t * \param p_meta_desc a media descriptor object - * \param p_e an initialized exception object * \return state of media descriptor object */ VLC_PUBLIC_API libvlc_state_t libvlc_media_get_state( - libvlc_media_t *p_meta_desc, - libvlc_exception_t *p_e ); + libvlc_media_t *p_meta_desc ); +/** + * get the current statistics about the media + * @param p_md: media descriptor object + * @param p_stats: structure that contain the statistics about the media + * (this structure must be allocated by the caller) + * @return true if the statistics are available, false otherwise + */ +VLC_PUBLIC_API int libvlc_media_get_stats( libvlc_media_t *p_md, + libvlc_media_stats_t *p_stats ); + /** * Get subitems of media descriptor object. This will increment * the reference count of supplied media descriptor object. Use * libvlc_media_list_release() to decrement the reference counting. * * \param p_md media descriptor object - * \param p_e initalized exception object * \return list of media descriptor subitems or NULL */ @@ -247,42 +340,35 @@ VLC_PUBLIC_API libvlc_state_t libvlc_media_get_state( #define VLC_FORWARD_DECLARE_OBJECT(a) struct a VLC_PUBLIC_API VLC_FORWARD_DECLARE_OBJECT(libvlc_media_list_t *) -libvlc_media_subitems( libvlc_media_t *p_md, - libvlc_exception_t *p_e ); +libvlc_media_subitems( libvlc_media_t *p_md ); /** * Get event manager from media descriptor object. * NOTE: this function doesn't increment reference counting. * * \param p_md a media descriptor object - * \param p_e an initialized exception object * \return event manager object */ VLC_PUBLIC_API libvlc_event_manager_t * - libvlc_media_event_manager( libvlc_media_t * p_md, - libvlc_exception_t * p_e ); + libvlc_media_event_manager( libvlc_media_t * p_md ); /** - * Get duration of media descriptor object item. + * Get duration (in ms) of media descriptor object item. * * \param p_md media descriptor object - * \param p_e an initialized exception object - * \return duration of media item + * \return duration of media item or -1 on error */ VLC_PUBLIC_API libvlc_time_t - libvlc_media_get_duration( libvlc_media_t * p_md, - libvlc_exception_t * p_e ); + libvlc_media_get_duration( libvlc_media_t * p_md ); /** * Get preparsed status for media descriptor object. * * \param p_md media descriptor object - * \param p_e an initialized exception object * \return true if media object has been preparsed otherwise it returns false */ VLC_PUBLIC_API int - libvlc_media_is_preparsed( libvlc_media_t * p_md, - libvlc_exception_t * p_e ); + libvlc_media_is_preparsed( libvlc_media_t * p_md ); /** * Sets media descriptor's user_data. user_data is specialized data @@ -291,12 +377,10 @@ VLC_PUBLIC_API int * * \param p_md media descriptor object * \param p_new_user_data pointer to user data - * \param p_e an initialized exception object */ VLC_PUBLIC_API void libvlc_media_set_user_data( libvlc_media_t * p_md, - void * p_new_user_data, - libvlc_exception_t * p_e); + void * p_new_user_data ); /** * Get media descriptor's user_data. user_data is specialized data @@ -304,12 +388,29 @@ VLC_PUBLIC_API void * an native object that references a libvlc_media_t pointer * * \param p_md media descriptor object - * \param p_e an initialized exception object */ VLC_PUBLIC_API void * - libvlc_media_get_user_data( libvlc_media_t * p_md, - libvlc_exception_t * p_e); + libvlc_media_get_user_data( libvlc_media_t * p_md ); + +/** + * Get media descriptor's elementary streams description + * + * Note, you need to play the media _one_ time with --sout="#description" + * Not doing this will result in an empty array, and doing it more than once + * will duplicate the entries in the array each time. + * + * \param p_md media descriptor object + * \param pp_es address to store an allocated array of Elementary Streams descriptions (must be freed by the caller) + * + * return the number of Elementary Streams + */ +VLC_PUBLIC_API int + libvlc_media_get_es( libvlc_media_t * p_md, libvlc_media_es_t ** pp_es ); /** @}*/ +# ifdef __cplusplus +} +# endif + #endif /* VLC_LIBVLC_MEDIA_H */