X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc_media.h;h=1185bf464fb443e8e48158960974a31568fdf345;hb=b5746390cd24c1df6fcc0ac06c8108fcf16dfb5e;hp=9d9d810969bf7d631d75e989f34dc82b71413d25;hpb=b0a1ac2e6378b0b86dd8086cdc8eced01195f098;p=vlc diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h index 9d9d810969..1185bf464f 100644 --- a/include/vlc/libvlc_media.h +++ b/include/vlc/libvlc_media.h @@ -35,24 +35,21 @@ extern "C" { # endif -/***************************************************************************** - * media - *****************************************************************************/ -/** \defgroup libvlc_media libvlc_media +/** \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, @@ -78,7 +75,7 @@ typedef enum libvlc_meta_t { /** * Note the order of libvlc_state_t enum must match exactly the order of - * @see mediacontrol_PlayerStatus, @see input_state_e enums, + * \see mediacontrol_PlayerStatus, \see input_state_e enums, * and VideoLAN.LibVLC.State (at bindings/cil/src/media.cs). * * Expected states by web plugins are: @@ -97,23 +94,22 @@ 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 +typedef enum libvlc_track_type_t { - libvlc_es_unknown = -1, - libvlc_es_audio = 0, - libvlc_es_video = 1, - libvlc_es_text = 2, -} libvlc_es_type_t; + libvlc_track_unknown = -1, + libvlc_track_audio = 0, + libvlc_track_video = 1, + libvlc_track_text = 2, +} libvlc_track_type_t; -/** defgroup libvlc_media_stats_t libvlc_media_stats_t +/** defgroup libvlc_media_stats_t LibVLC media statistics * \ingroup libvlc_media - * LibVLC Media statistics * @{ */ typedef struct libvlc_media_stats_t @@ -147,47 +143,69 @@ typedef struct libvlc_media_stats_t } libvlc_media_stats_t; /** @}*/ -typedef struct libvlc_media_es_t +typedef struct libvlc_media_track_info_t { /* Codec fourcc */ uint32_t i_codec; int i_id; - libvlc_es_type_t i_type; + libvlc_track_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; + union { + struct { + /* Audio specific */ + unsigned i_channels; + unsigned i_rate; + } audio; + struct { + /* Video specific */ + unsigned i_height; + unsigned i_width; + } video; + } u; -} libvlc_media_es_t; +} libvlc_media_track_info_t; /** - * Create a media with the given MRL. + * Create a media with a certain given media resource location. + * + * \see libvlc_media_release * * \param p_instance the instance * \param psz_mrl the MRL to read * \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 ); +/** + * Create a media with a certain file path. + * + * \see libvlc_media_release + * + * \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. * + * \see libvlc_media_release + * * \param p_instance the instance * \param psz_name the name of the node * \return the new empty media or NULL on error */ -VLC_PUBLIC_API libvlc_media_t * libvlc_media_new_as_node( +VLC_PUBLIC_API libvlc_media_t *libvlc_media_new_as_node( libvlc_instance_t *p_instance, const char * psz_name ); @@ -204,7 +222,7 @@ VLC_PUBLIC_API libvlc_media_t * libvlc_media_new_as_node( * \param ppsz_options the options (as a string) */ VLC_PUBLIC_API void libvlc_media_add_option( - libvlc_media_t * p_md, + libvlc_media_t *p_md, const char * ppsz_options ); /** @@ -221,9 +239,9 @@ VLC_PUBLIC_API void libvlc_media_add_option( * \param i_flags the flags for this option */ VLC_PUBLIC_API void libvlc_media_add_option_flag( - libvlc_media_t * p_md, + libvlc_media_t *p_md, const char * ppsz_options, - libvlc_media_option_t i_flags ); + unsigned i_flags ); /** @@ -253,23 +271,33 @@ VLC_PUBLIC_API void libvlc_media_release( libvlc_media_t *p_md ); * \param p_md a media descriptor object * \return string with mrl of media descriptor object */ -VLC_PUBLIC_API char * libvlc_media_get_mrl( libvlc_media_t * p_md ); +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 *p_md ); +VLC_PUBLIC_API libvlc_media_t *libvlc_media_duplicate( libvlc_media_t *p_md ); /** * Read the meta of the media. * + * If the media has not yet been parsed this will return NULL. + * + * This methods automatically calls libvlc_media_parse_async(), so after calling + * it you may receive a libvlc_MediaMetaChanged event. If you prefer a synchronous + * version ensure that you call libvlc_media_parse() before get_meta(). + * + * \see libvlc_media_parse + * \see libvlc_media_parse_async + * \see libvlc_MediaMetaChanged + * * \param p_md the media descriptor * \param e_meta the meta to read * \return the media's meta */ -VLC_PUBLIC_API char * libvlc_media_get_meta( libvlc_media_t *p_md, +VLC_PUBLIC_API char *libvlc_media_get_meta( libvlc_media_t *p_md, libvlc_meta_t e_meta ); /** @@ -278,7 +306,7 @@ VLC_PUBLIC_API char * libvlc_media_get_meta( libvlc_media_t *p_md, * * \param p_md the media descriptor * \param e_meta the meta to write - * \param the media's meta + * \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, @@ -301,20 +329,20 @@ VLC_PUBLIC_API int libvlc_media_save_meta( libvlc_media_t *p_md ); * libvlc_Stopped, libvlc_Ended, * libvlc_Error). * - * @see libvlc_state_t - * \param p_meta_desc a media descriptor object + * \see libvlc_state_t + * \param p_md a media descriptor object * \return state of media descriptor object */ VLC_PUBLIC_API libvlc_state_t libvlc_media_get_state( - libvlc_media_t *p_meta_desc ); + libvlc_media_t *p_md ); /** - * get the current statistics about the media - * @param p_md: media descriptor object - * @param p_stats: structure that contain the statistics about the media + * 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 + * \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 ); @@ -343,7 +371,7 @@ libvlc_media_subitems( libvlc_media_t *p_md ); * \return event manager object */ VLC_PUBLIC_API libvlc_event_manager_t * - libvlc_media_event_manager( libvlc_media_t * p_md ); + libvlc_media_event_manager( libvlc_media_t *p_md ); /** * Get duration (in ms) of media descriptor object item. @@ -352,16 +380,53 @@ VLC_PUBLIC_API libvlc_event_manager_t * * \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_media_get_duration( libvlc_media_t *p_md ); + +/** + * Parse a media. + * + * This fetches (local) meta data and tracks information. + * The method is synchronous. + * + * \see libvlc_media_parse_async + * \see libvlc_media_get_meta + * \see libvlc_media_get_tracks_info + * + * \param p_md media descriptor object + */ +VLC_PUBLIC_API void +libvlc_media_parse( libvlc_media_t *p_md ); /** - * Get preparsed status for media descriptor object. + * Parse a media. + * + * This fetches (local) meta data and tracks information. + * The method is the asynchronous of libvlc_media_parse(). + * + * To track when this is over you can listen to libvlc_MediaParsedChanged + * event. However if the media was already parsed you will not receive this + * event. + * + * \see libvlc_media_parse + * \see libvlc_MediaParsedChanged + * \see libvlc_media_get_meta + * \see libvlc_media_get_tracks_info * * \param p_md media descriptor object - * \return true if media object has been preparsed otherwise it returns false + */ +VLC_PUBLIC_API void +libvlc_media_parse_async( libvlc_media_t *p_md ); + +/** + * Get Parsed status for media descriptor object. + * + * \see libvlc_MediaParsedChanged + * + * \param p_md media descriptor object + * \return true if media object has been parsed otherwise it returns false */ VLC_PUBLIC_API int - libvlc_media_is_preparsed( libvlc_media_t * p_md ); + libvlc_media_is_parsed( libvlc_media_t *p_md ); /** * Sets media descriptor's user_data. user_data is specialized data @@ -372,8 +437,7 @@ VLC_PUBLIC_API int * \param p_new_user_data pointer to user data */ VLC_PUBLIC_API void - libvlc_media_set_user_data( libvlc_media_t * p_md, - void * p_new_user_data ); + libvlc_media_set_user_data( libvlc_media_t *p_md, void *p_new_user_data ); /** * Get media descriptor's user_data. user_data is specialized data @@ -382,23 +446,35 @@ VLC_PUBLIC_API void * * \param p_md media descriptor object */ -VLC_PUBLIC_API void * - libvlc_media_get_user_data( libvlc_media_t * p_md ); +VLC_PUBLIC_API void *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. + * will duplicate the entries in the array each time. Something like this: + * + * @begincode + * libvlc_media_player_t *player = libvlc_media_player_new_from_media(media); + * libvlc_media_add_option_flag(media, "sout=\"#description\""); + * libvlc_media_player_play(player); + * // ... wait until playing + * libvlc_media_player_release(player); + * @endcode + * + * This is very likely to change in next release, and be done at the parsing + * phase. * * \param p_md media descriptor object - * \param pp_es adress to store an allocated array of Elementary Streams descriptions (must be freed by the caller) + * \param tracks 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 ); +VLC_PUBLIC_API +int libvlc_media_get_tracks_info( libvlc_media_t *p_md, + libvlc_media_track_info_t **tracks ); /** @}*/