X-Git-Url: https://git.sesse.net/?a=blobdiff_plain;f=include%2Fvlc%2Flibvlc_media.h;h=f8b267d7f43e2456af3e761fb1c1999d1b96ad88;hb=978d581b98c07bab07f3e200226fbb29469b9209;hp=88857c41a07c65336884c8d77f957bb0cab793fe;hpb=41b54a0abc868480e67e09f9ce5db348771a4742;p=vlc diff --git a/include/vlc/libvlc_media.h b/include/vlc/libvlc_media.h index 88857c41a0..f8b267d7f4 100644 --- a/include/vlc/libvlc_media.h +++ b/include/vlc/libvlc_media.h @@ -1,26 +1,26 @@ /***************************************************************************** - * libvlc.h: libvlc external API + * libvlc_media.h: libvlc external API ***************************************************************************** - * Copyright (C) 1998-2009 the VideoLAN team + * Copyright (C) 1998-2009 VLC authors and VideoLAN * $Id$ * * Authors: Clément Stenac * Jean-Paul Saman * Pierre d'Herbemont * - * 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. *****************************************************************************/ /** @@ -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, @@ -66,7 +67,7 @@ typedef enum libvlc_meta_t { libvlc_meta_Publisher, libvlc_meta_EncodedBy, libvlc_meta_ArtworkURL, - libvlc_meta_TrackID, + libvlc_meta_TrackID /* Add new meta types HERE */ } libvlc_meta_t; @@ -74,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: @@ -93,16 +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_track_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 @@ -136,32 +143,106 @@ typedef struct libvlc_media_stats_t } libvlc_media_stats_t; /** @}*/ +typedef struct libvlc_media_track_info_t +{ + /* Codec fourcc */ + uint32_t i_codec; + int i_id; + libvlc_track_type_t i_type; + + /* Codec specific */ + int i_profile; + int i_level; + + union { + struct { + /* Audio specific */ + unsigned i_channels; + unsigned i_rate; + } audio; + struct { + /* Video specific */ + unsigned i_height; + unsigned i_width; + } video; + } u; + +} libvlc_media_track_info_t; + /** - * Create a media with the given MRL. + * Create a media with a certain given media resource location, + * for instance a valid URL. + * + * \note To refer to a local file with this function, + * the file://... URI syntax must be used (see IETF RFC3986). + * We recommend using libvlc_media_new_path() instead when dealing with + * local files. + * + * \see libvlc_media_release * * \param p_instance the instance - * \param psz_mrl the MRL to read - * \param p_e an initialized exception pointer - * \return the newly created media + * \param psz_mrl the media location + * \return the newly created media or NULL on error */ -VLC_PUBLIC_API libvlc_media_t * libvlc_media_new( +LIBVLC_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 for 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 + */ +LIBVLC_API libvlc_media_t *libvlc_media_new_path( + libvlc_instance_t *p_instance, + const char *path ); + +/** + * Create a media for an already open file descriptor. + * The file descriptor shall be open for reading (or reading and writing). + * + * Regular file descriptors, pipe read descriptors and character device + * descriptors (including TTYs) are supported on all platforms. + * Block device descriptors are supported where available. + * Directory descriptors are supported on systems that provide fdopendir(). + * Sockets are supported on all platforms where they are file descriptors, + * i.e. all except Windows. + * + * \note This library will not automatically close the file descriptor + * under any circumstance. Nevertheless, a file descriptor can usually only be + * rendered once in a media player. To render it a second time, the file + * descriptor should probably be rewound to the beginning with lseek(). + * + * \see libvlc_media_release + * + * \version LibVLC 1.1.5 and later. + * + * \param p_instance the instance + * \param fd open file descriptor + * \return the newly created media or NULL on error + */ +LIBVLC_API libvlc_media_t *libvlc_media_new_fd( + libvlc_instance_t *p_instance, + int fd ); + + +/** + * 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 - * \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_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. @@ -170,13 +251,17 @@ VLC_PUBLIC_API libvlc_media_t * libvlc_media_new_as_node( * read the media. This allows to use VLC's advanced * reading/streaming options on a per-media basis. * - * The options are detailed in vlc --long-help, for instance "--sout-all" + * The options are detailed in vlc --long-help, for instance + * "--sout-all". Note that all options are not usable on medias: + * specifically, due to architectural issues, video-related options + * such as text renderer options cannot be set on a single media. They + * must be set on the whole libvlc instance instead. * - * \param p_instance the instance + * \param p_md the media descriptor * \param ppsz_options the options (as a string) */ -VLC_PUBLIC_API void libvlc_media_add_option( - libvlc_media_t * p_md, +LIBVLC_API void libvlc_media_add_option( + libvlc_media_t *p_md, const char * ppsz_options ); /** @@ -186,16 +271,20 @@ VLC_PUBLIC_API void libvlc_media_add_option( * read the media. This allows to use VLC's advanced * reading/streaming options on a per-media basis. * - * The options are detailed in vlc --long-help, for instance "--sout-all" + * The options are detailed in vlc --long-help, for instance + * "--sout-all". Note that all options are not usable on medias: + * specifically, due to architectural issues, video-related options + * such as text renderer options cannot be set on a single media. They + * must be set on the whole libvlc instance instead. * - * \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 */ -VLC_PUBLIC_API void libvlc_media_add_option_flag( - libvlc_media_t * p_md, +LIBVLC_API void libvlc_media_add_option_flag( + libvlc_media_t *p_md, const char * ppsz_options, - libvlc_media_option_t i_flags ); + unsigned i_flags ); /** @@ -203,10 +292,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 ); +LIBVLC_API void libvlc_media_retain( libvlc_media_t *p_md ); /** * Decrement the reference count of a media descriptor object. If the @@ -215,10 +303,9 @@ 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 ); +LIBVLC_API void libvlc_media_release( libvlc_media_t *p_md ); /** @@ -227,25 +314,56 @@ VLC_PUBLIC_API void libvlc_media_release( * \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 ); +LIBVLC_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 * ); +LIBVLC_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 + * 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_meta_desc, - libvlc_meta_t e_meta ); +LIBVLC_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 + */ +LIBVLC_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 successful + */ +LIBVLC_API int libvlc_media_save_meta( libvlc_media_t *p_md ); + /** * Get current state of media descriptor object. Possible media states @@ -254,22 +372,24 @@ VLC_PUBLIC_API char * libvlc_media_get_meta( * 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_API libvlc_state_t libvlc_media_get_state( + 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 + * + * \libvlc_return_bool */ -VLC_PUBLIC_API int libvlc_media_get_stats( libvlc_media_t *p_md, +LIBVLC_API int libvlc_media_get_stats( libvlc_media_t *p_md, libvlc_media_stats_t *p_stats ); /** @@ -285,7 +405,7 @@ VLC_PUBLIC_API int libvlc_media_get_stats( libvlc_media_t *p_md, * and this is here for convenience */ #define VLC_FORWARD_DECLARE_OBJECT(a) struct a -VLC_PUBLIC_API VLC_FORWARD_DECLARE_OBJECT(libvlc_media_list_t *) +LIBVLC_API VLC_FORWARD_DECLARE_OBJECT(libvlc_media_list_t *) libvlc_media_subitems( libvlc_media_t *p_md ); /** @@ -295,28 +415,65 @@ libvlc_media_subitems( libvlc_media_t *p_md ); * \param p_md a media descriptor object * \return event manager object */ -VLC_PUBLIC_API libvlc_event_manager_t * - libvlc_media_event_manager( libvlc_media_t * p_md ); +LIBVLC_API libvlc_event_manager_t * + libvlc_media_event_manager( libvlc_media_t *p_md ); /** * 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 + */ +LIBVLC_API libvlc_time_t + 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 + */ +LIBVLC_API void +libvlc_media_parse( libvlc_media_t *p_md ); + +/** + * 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 */ -VLC_PUBLIC_API libvlc_time_t - libvlc_media_get_duration( libvlc_media_t * p_md, - libvlc_exception_t * p_e ); +LIBVLC_API void +libvlc_media_parse_async( libvlc_media_t *p_md ); /** - * Get preparsed status for media descriptor object. + * Get Parsed status for media descriptor object. + * + * \see libvlc_MediaParsedChanged * * \param p_md media descriptor object - * \return true if media object has been preparsed otherwise it returns false + * \return true if media object has been parsed otherwise it returns false + * + * \libvlc_return_bool */ -VLC_PUBLIC_API int - libvlc_media_is_preparsed( libvlc_media_t * p_md ); +LIBVLC_API int + libvlc_media_is_parsed( libvlc_media_t *p_md ); /** * Sets media descriptor's user_data. user_data is specialized data @@ -326,9 +483,8 @@ VLC_PUBLIC_API int * \param p_md media descriptor object * \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_API void + 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 @@ -337,9 +493,29 @@ VLC_PUBLIC_API void * * \param p_md media descriptor object */ -VLC_PUBLIC_API void * - libvlc_media_get_user_data( libvlc_media_t * p_md ); +LIBVLC_API void *libvlc_media_get_user_data( libvlc_media_t *p_md ); + +/** + * Get media descriptor's elementary streams description + * + * Note, you need to call libvlc_media_parse() or play the media at least once + * before calling this function. + * Not doing this will result in an empty array. + * + * \param p_md media descriptor object + * \param tracks address to store an allocated array of Elementary Streams + * descriptions (must be freed by the caller) [OUT] + * + * \return the number of Elementary Streams + */ +LIBVLC_API +int libvlc_media_get_tracks_info( libvlc_media_t *p_md, + libvlc_media_track_info_t **tracks ); /** @}*/ +# ifdef __cplusplus +} +# endif + #endif /* VLC_LIBVLC_MEDIA_H */