Media.hpp 11 KB
Newer Older
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
1 2 3 4 5 6
/*****************************************************************************
 * libvlc_Media.hpp: Media API
 *****************************************************************************
 * Copyright © 2014 the VideoLAN team
 *
 * Authors: Alexey Sokolov <alexey@alexeysokolov.co.cc>
7
 *          Hugo Beauzée-Luyssen <hugo@beauzee.fr>
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26
 *
 * 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 Lesser General Public License for more details.
 *
 * 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.
 *****************************************************************************/

#ifndef LIBVLC_CXX_MEDIA_H
#define LIBVLC_CXX_MEDIA_H

27 28
#include <vector>
#include "common.hpp"
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
29
#include "Internal.hpp"
30
#include "structures.hpp"
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
31

32
namespace VLC
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
33 34
{

Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
35 36
class MediaList;
class MediaPlayer;
37
class EventManager;
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
38

39
class VLCPP_API Media : public Internal<libvlc_media_t>
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
40 41
{
public:
42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63

    enum FromType
    {
        /**
         * Create a media for a certain file path.
         */
        FromPath,
        /**
         * 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 <b>must</b> be used (see IETF RFC3986).
         * We recommend using FromPath instead when dealing with
         * local files.
         */
        FromLocation,
        /**
         * Create a media as an empty node with a given name.
         */
        AsNode,
    };
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
64 65

    /**
66 67 68 69
     * @brief Media Constructs a libvlc Media instance
     * @param instance  A libvlc instance
     * @param mrl       A path, location, or node name, depending on the 3rd parameter
     * @param type      The type of the 2nd argument. \sa{FromType}
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
70
     */
71
    Media(Instance& instance, const std::string& mrl, FromType type);
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
72 73

    /**
74 75
     * Create a media for an already open file descriptor.
     * The file descriptor shall be open for reading (or reading and writing).
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
76 77
     *
     * Regular file descriptors, pipe read descriptors and character device
78 79 80 81 82 83 84 85
     * 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 <b>not</b> automatically close the file descriptor
     * under any circumstance. Nevertheless, a file descriptor can usually only be
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
86 87 88
     * rendered once in a media player. To render it a second time, the file
     * descriptor should probably be rewound to the beginning with lseek().
     *
89 90 91 92
     * \param p_instance the instance
     * \param fd open file descriptor
     * \return the newly created media or NULL on error
     */
93
    Media(Instance& instance, int fd);
94 95 96 97 98

    /**
     * Get media instance from this media list instance. This action will increase
     * the refcount on the media instance.
     * The libvlc_media_list_lock should NOT be held upon entering this function.
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
99
     *
100 101
     * \param p_ml a media list instance
     * \return media instance
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
102
     */
103
    Media(MediaList& list );
104 105 106 107

    /**
     * Copy libvlc_media_t from another to new Media object.
     * \param another existing Media
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
108
     */
109 110 111 112 113 114 115
    Media(const Media& another);

    /**
     * Copy libvlc_media_t from another Media
     * to this Media
     * \param another existing Media
     */
116
    Media& operator=(const Media& another);
117 118 119 120 121 122 123 124 125

    /**
     * Check if 2 Media objects contain the same libvlc_media_t.
     * \param another another Media
     * \return true if they contain the same libvlc_media_t
     */
    bool operator==(const Media& another) const;

    ~Media();
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244

    /**
     * Add an option to the media.
     *
     * This option will be used to determine how the media_player will read
     * the media. This allows to use VLC's advanced reading/streaming options
     * on a per-media basis.
     *
     * \note The options are listed in 'vlc long-help' from the command line,
     * e.g. "-sout-all". Keep in mind that available options and their
     * semantics vary across LibVLC versions and builds.
     *
     * \warning Not all options affects libvlc_media_t objects: Specifically,
     * due to architectural issues most audio and video options, such as text
     * renderer options, have no effects on an individual media. These
     * options must be set through Instance::Instance() instead.
     *
     * \param psz_options  the options (as a string)
     */
    void addOption(const std::string& psz_options);

    /**
     * Add an option to the media with configurable flags.
     *
     * This option will be used to determine how the media_player will 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".
     * 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 psz_options  the options (as a string)
     *
     * \param i_flags  the flags for this option
     */
    void addOptionFlag(const std::string& psz_options, unsigned i_flags);

    /**
     * Get the media resource locator (mrl) from a media descriptor object
     *
     * \return string with mrl of media descriptor object
     */
    std::string mrl();

    /**
     * Duplicate a media descriptor object.
     */
    Media duplicate();

    /**
     * Read the meta of the media.
     *
     * If the media has not yet been parsed this will return NULL.
     *
     * This methods automatically calls Media::parseAsync() , so after
     * calling it you may receive a libvlc_MediaMetaChanged event. If you
     * prefer a synchronous version ensure that you call Media::parse()
     * before get_meta().
     *
     * \see Media::parse()
     *
     * \see Media::parseAsync()
     *
     * \see libvlc_MediaMetaChanged
     *
     * \param e_meta  the meta to read
     *
     * \return the media's meta
     */
    std::string meta(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 e_meta  the meta to write
     *
     * \param psz_value  the media's meta
     */
    void setMeta(libvlc_meta_t e_meta, const std::string& psz_value);

    /**
     * Save the meta previously set
     *
     * \return true if the write operation was successful
     */
    int saveMeta();

    /**
     * Get current state of media descriptor object. Possible media states
     * are defined in libvlc_structures.c ( libvlc_NothingSpecial=0,
     * libvlc_Opening, libvlc_Buffering, libvlc_Playing, libvlc_Paused,
     * libvlc_Stopped, libvlc_Ended, libvlc_Error).
     *
     * \see libvlc_state_t
     *
     * \return state of media descriptor object
     */
    libvlc_state_t state();

    /**
     * Get the current statistics about the media
     *
     * \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
     */
    bool stats(libvlc_media_stats_t * p_stats);

    /**
     * Get event manager from media descriptor object. NOTE: this function
     * doesn't increment reference counting.
     *
     * \return event manager object
     */
245
    EventManager& eventManager();
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283

    /**
     * Get duration (in ms) of media descriptor object item.
     *
     * \return duration of media item or -1 on error
     */
    libvlc_time_t duration();

    /**
     * Parse a media.
     *
     * This fetches (local) meta data and tracks information. The method is
     * synchronous.
     *
     * \see Media::parseAsync()
     *
     * \see Media::meta()
     *
     * \see Media::tracksInfo()
     */
    void parse();

    /**
     * Parse a media.
     *
     * This fetches (local) meta data and tracks information. The method is
     * the asynchronous of 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 Media::parse()
     *
     * \see libvlc_MediaParsedChanged
     *
     * \see Media::meta()
     *
284
     * \see Media::tracks()
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322
     */
    void parseAsync();

    /**
     * Get Parsed status for media descriptor object.
     *
     * \see libvlc_MediaParsedChanged
     *
     * \return true if media object has been parsed otherwise it returns
     * false
     */
    bool isParsed();

    /**
     * Sets media descriptor's user_data. user_data is specialized data
     * accessed by the host application, VLC.framework uses it as a pointer
     * to an native object that references a libvlc_media_t pointer
     *
     * \param p_new_user_data  pointer to user data
     */
    void setUserData(void * p_new_user_data);

    /**
     * Get media descriptor's user_data. user_data is specialized data
     * accessed by the host application, VLC.framework uses it as a pointer
     * to an native object that references a libvlc_media_t pointer
     */
    void * userData();

    /**
     * Get media descriptor's elementary streams description
     *
     * Note, you need to call Media::parse() or play the media at least once
     * before calling this function. Not doing this will result in an empty
     * array.
     *
     * \version LibVLC 2.1.0 and later.
     *
323
     * \return a vector containing all tracks
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
324
     */
325
    std::vector<MediaTrack> tracks();
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
326 327

private:
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
328
    explicit Media(InternalPtr ptr, bool increaseRefCount );
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
329 330 331 332 333 334 335 336 337 338 339 340 341 342 343
    /**
     * Retain a reference to a media descriptor object (libvlc_media_t). Use
     * Media::release() to decrement the reference count of a media
     * descriptor object.
     */
    void retain();

    /**
     * Decrement the reference count of a media descriptor object. If the
     * reference count is 0, then Media::release() will release the media
     * descriptor object. It will send out an libvlc_MediaFreed event to all
     * listeners. If the media descriptor object has been released it should
     * not be used again.
     */
    void release();
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
344

345 346 347
private:
    EventManager* m_eventManager;

Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
348 349
    friend class MediaList;
    friend class MediaPlayer;
350
    friend class EventManager;
Hugo Beauzée-Luyssen's avatar
Hugo Beauzée-Luyssen committed
351 352 353 354 355 356
};

} // namespace VLC

#endif