YiAbstractVideoPlayer.h

Go to the documentation of this file.

// © You i Labs Inc. 2000-2020. All rights reserved.
#ifndef _YI_ABSTRACT_VIDEO_PLAYER_H_
#define _YI_ABSTRACT_VIDEO_PLAYER_H_

#include "network/YiHTTPHeader.h"
#include "network/YiUrl.h"
#include "signal/YiSignal.h"
#include "utility/YiRtti.h"
#include "utility/YiTime.h"
#include "utility/YiTimer.h"

#include <glm/fwd.hpp>

#include <limits>

class CYIAssetTexture;
class CYIAssetVideo;
class CYIClosedCaptionsDispatcher;
class CYIColor;
class CYIMaterial;
class CYIVideoPlayerStateManager;
class CYIVideoSurface;

class CYIAbstractVideoPlayer : public CYISignalHandler
{
    friend class CYIVideoPlayerStateManager;

public:
    using RTTIInstantiatability = CYIRuntimeTypeInfo::NonInstantiableTag;

    enum class MediaState
    {
        Unloaded, 
        Preparing, 
        Ready 
    };

    enum class PlaybackState
    {
        Playing, 
        Paused, 
        Buffering 
    };

    struct PlayerState
    {
        MediaState mediaState;
        PlaybackState playbackState;
    };

    enum class StreamingFormat
    {
        HLS = 0,
        Smooth,
        DASH,
        MP4
    };

    enum class DRMScheme
    {
        None = 0,
        FairPlay,
        PlayReady,
        WidevineModular,
        WidevineModularCustomRequest
    };

    class DRMConfiguration
    {
    public:
        virtual ~DRMConfiguration() = default;

        virtual DRMScheme GetScheme() const = 0;
    };

    enum class ErrorCode
    {
        PlaybackError, 
        UnsupportedFormat, 
        StateTransitionError, 
        DRMError, 
        InitializationError, 
        Unknown 
    };

    struct Error
    {
        Error()
            : errorCode(ErrorCode::Unknown)
        {
        }

        ErrorCode errorCode;
        CYIString message;
        CYIString nativePlayerErrorCode;
    };

    struct TrackInfo
    {
        uint32_t id; 
        CYIString name; 
        CYIString language; 
        TrackInfo(uint32_t id)
            : id(id)
        {
        }
        TrackInfo(uint32_t id, const CYIString &name)
            : id(id)
            , name(name)
        {
        }
        TrackInfo(uint32_t id, const CYIString &name, const CYIString &language)
            : id(id)
            , name(name)
            , language(language)
        {
        }
    };

    struct AudioTrackInfo : public TrackInfo
    {
        static uint32_t DEFAULT_TRACK_ID; 
        AudioTrackInfo()
            : TrackInfo(DEFAULT_TRACK_ID)
            , isValid(false)
        {
        }
        AudioTrackInfo(uint32_t id, const CYIString &name, const CYIString &language)
            : TrackInfo(id, name, language)
            , isValid(true)
        {
        }
        AudioTrackInfo(const TrackInfo &trackInfo)
            : TrackInfo(trackInfo)
            , isValid(true)
        {
        }
        bool isValid; 
    };

    struct ClosedCaptionsTrackInfo : public TrackInfo
    {
        static uint32_t OFF_TRACK_ID; 
        ClosedCaptionsTrackInfo()
            : TrackInfo(OFF_TRACK_ID)
        {
        }
        ClosedCaptionsTrackInfo(uint32_t id, const CYIString &name, const CYIString &language)
            : TrackInfo(id, name, language)
        {
        }
        ClosedCaptionsTrackInfo(const TrackInfo &trackInfo)
            : TrackInfo(trackInfo)
        {
        }
    };

    class BackgroundPlaybackInterface
    {
    public:
        virtual ~BackgroundPlaybackInterface() = default;

        virtual bool IsBackgroundPlaybackEnabled() const = 0;

        virtual void EnableBackgroundPlayback(bool enabled) = 0;

        virtual void SetMetadata(const CYIString &title, const CYIString &text, const CYIUrl &imageUri) = 0;

        virtual void SetRewindIncrementMs(std::chrono::milliseconds increment) = 0;
        virtual void SetFastForwardIncrementMs(std::chrono::milliseconds increment) = 0;

        virtual void SetNotificationColor(const CYIColor &color) = 0;
    };

    class HeadphoneJackInterface
    {
    public:
        virtual ~HeadphoneJackInterface() = default;

        virtual void EnablePauseOnHeadphonesUnplugged(bool enabled) = 0;

        virtual bool IsPausingOnHeadphonesUnplugged() const = 0;
    };

    class VideoRequestHTTPHeadersInterface
    {
    public:
        virtual ~VideoRequestHTTPHeadersInterface() = default;

        virtual std::vector<CYIHTTPHeader> SetHeaders(const std::vector<CYIHTTPHeader> &customHeaders) = 0;

        virtual bool AddHeader(const CYIHTTPHeader &header) = 0;

        virtual bool RemoveHeader(const CYIString &name) = 0;

        virtual void ClearHeaders() = 0;

        virtual std::vector<CYIHTTPHeader> GetHeaders() const = 0;
    };

    struct BufferLength
    {
        std::chrono::milliseconds min;

        std::chrono::milliseconds max;

        BufferLength(std::chrono::milliseconds minIn, std::chrono::milliseconds maxIn)
            : min(minIn)
            , max(maxIn)
        {
        }

        BufferLength()
            : min(0)
            , max(0)
        {
        }
    };

    class BufferingInterface
    {
    public:
        virtual ~BufferingInterface() = default;

        virtual void SetBufferLength(const BufferLength &bufferLength) = 0;

        virtual BufferLength GetBufferLength() const = 0;
    };

    struct TimedMetadataAdditionalDataKeys
    {
        // ID3 Related Keys
        static const CYIString ID3PrivateFrameOwner;

        // DASH Event Message Related Keys
        static const CYIString EventMessageSchemeId;
        static const CYIString EventMessageValue;
        static const CYIString EventMessageTimescale;
        static const CYIString EventMessagePTSDelta;
        static const CYIString EventMessageDuration;
        static const CYIString EventMessageId;
        static const CYIString EventMessageMessageData;
    };

    struct TimedMetadata
    {
        TimedMetadata();

        CYIString identifier; 
        CYIString value; 
        std::chrono::microseconds timestamp; 
        std::chrono::microseconds duration; 
        std::map<CYIString, CYIString> additionalData; 
    };

    class TimedMetadataInterface
    {
    public:
        virtual ~TimedMetadataInterface() = default;

        CYISignal<TimedMetadata> MetadataAvailable;
    };

    class MediaPlaybackControlsInterface
    {
    public:
        class ControlsHandler
        {
        public:
            virtual ~ControlsHandler() = default;

            virtual void OnPlay(CYIAbstractVideoPlayer *pPlayer);

            virtual void OnPause(CYIAbstractVideoPlayer *pPlayer);

            virtual void OnSeek(CYIAbstractVideoPlayer *pPlayer, uint64_t positionMs);

            virtual void OnStop(CYIAbstractVideoPlayer *pPlayer);

            virtual void OnClosedCaptionsEnabled(CYIAbstractVideoPlayer *pPlayer, bool enabled);
        };

        virtual ~MediaPlaybackControlsInterface() = default;

        virtual void EnableMediaPlaybackControl(bool enabled) = 0;

        virtual bool IsMediaPlaybackControlEnabled() const = 0;

        virtual void SetControlsHandler(ControlsHandler *pControlsHandler) = 0;
    };

    virtual ~CYIAbstractVideoPlayer();

    CYIString GetName() const;

    CYIString GetVersion() const;

    struct Statistics
    {
        Statistics();

        bool operator==(const Statistics &other) const;
        bool operator!=(const Statistics &other) const;

        bool isLive;

        float totalBitrateKbps;

        float videoBitrateKbps;

        float audioBitrateKbps;

        float defaultTotalBitrateKbps;

        float defaultVideoBitrateKbps;

        float defaultAudioBitrateKbps;

        float bufferLengthMs;

        float minimumBufferLengthMs;

        float renderedFramesPerSecond;

        float encodedFramesPerSecond;
    };

    Statistics GetStatistics() const;

    void Init();

    void Prepare(const CYIUrl &videoURI, StreamingFormat formatHint, CYIAbstractVideoPlayer::PlaybackState initialState = CYIAbstractVideoPlayer::PlaybackState::Paused, std::unique_ptr<DRMConfiguration> pDRMConfiguration = nullptr, uint64_t startTimeMs = 0);

    void Prepare(const std::shared_ptr<CYIAssetVideo> &videoAsset, StreamingFormat formatHint, CYIAbstractVideoPlayer::PlaybackState initialState = CYIAbstractVideoPlayer::PlaybackState::Paused, std::unique_ptr<DRMConfiguration> pDRMConfiguration = nullptr, uint64_t startTimeMs = 0);

    void Play();

    void Pause();

    void Stop();

    struct SeekableRange
    {
        SeekableRange(uint64_t startTimeMs, uint64_t endTimeMs)
            : startTimeMs(startTimeMs)
            , endTimeMs(endTimeMs)
        {
        }

        uint64_t startTimeMs;

        uint64_t endTimeMs;
    };

    std::vector<SeekableRange> GetLiveSeekableRanges() const;

    void Seek(uint64_t seekPositionMs);

    bool SupportsFormat(StreamingFormat streamingFormat, DRMScheme drmScheme = DRMScheme::None);

    uint64_t GetDurationMs() const;

    uint64_t GetCurrentTimeMs() const;

    CYIAbstractVideoPlayer::PlayerState GetPlayerState() const;

    void SetClosedCaptionsEnabled(bool enabled);

    bool AreClosedCaptionsTracksAvailable() const;

    bool SelectClosedCaptionsTrack(uint32_t id);

    std::vector<ClosedCaptionsTrackInfo> GetClosedCaptionsTracks() const;

    ClosedCaptionsTrackInfo GetActiveClosedCaptionsTrack() const;

    /*
        \details Returns the closed captions dispatcher for the player.

        This will return null if the player implementation does not provide control over closed captions rendering.
    */
    CYIClosedCaptionsDispatcher *GetClosedCaptionsDispatcher() const;

    CYIVideoSurface *GetSurface() const;

    bool AreAudioTracksAvailable() const;

    bool SelectAudioTrack(uint32_t id);

    std::vector<AudioTrackInfo> GetAudioTracks() const;

    AudioTrackInfo GetActiveAudioTrack() const;

    bool IsMuted() const;

    void Mute(bool mute);

    void SetMaxBitrate(uint64_t maxBitrate);

    void SetInitialBandwidthHint(uint64_t initialBandwidthHint);

    void SetUserAgent(const CYIString &userAgent);

    const DRMConfiguration *GetDRMConfiguration() const;

    DRMConfiguration *GetDRMConfiguration();

    BackgroundPlaybackInterface *GetBackgroundPlaybackInterface() const;

    HeadphoneJackInterface *GetHeadphoneJackInterface() const;

    BufferingInterface *GetBufferingInterface() const;

    TimedMetadataInterface *GetTimedMetadataInterface() const;

    VideoRequestHTTPHeadersInterface *GetVideoRequestHTTPHeadersInterface();

    MediaPlaybackControlsInterface *GetMediaPlaybackControlsInterface() const;

    using RefreshDRMConfigurationCallback = std::function<std::unique_ptr<CYIAbstractVideoPlayer::DRMConfiguration>(std::unique_ptr<CYIAbstractVideoPlayer::DRMConfiguration>)>;
    void SetRefreshDRMConfigurationCallback(RefreshDRMConfigurationCallback callback);

    CYISignal<> BufferingStarted;

    CYISignal<> BufferingEnded;

    CYISignal<Error> ErrorOccurred;

    CYISignal<> Preparing;

    CYISignal<> Ready;

    CYISignal<> Playing;

    CYISignal<> Paused;

    CYISignal<> PlaybackComplete;

    CYISignal<> Finalized;

    CYISignal<uint64_t> CurrentTimeUpdated;

    CYISignal<uint64_t> DurationChanged;

    CYISignal<bool, uint64_t> SeekCompleted;

    CYISignal<const CYIAbstractVideoPlayer::PlayerState &> PlayerStateChanged;

    CYISignal<std::vector<AudioTrackInfo>> AvailableAudioTracksChanged;

    CYISignal<std::vector<ClosedCaptionsTrackInfo>> AvailableClosedCaptionsTracksChanged;

    CYISignal<float> TotalBitrateChanged;

    CYISignal<float> VideoBitrateChanged;

    CYISignal<float> AudioBitrateChanged;

protected:
    CYIAbstractVideoPlayer();

    const std::shared_ptr<CYIMaterial> &GetVideoMaterial() const;

    void SetVideoSurfaceSize(const glm::ivec2 &size);

    void ChangeInitialPlaybackState(CYIAbstractVideoPlayer::PlaybackState initialState);

    CYIAbstractVideoPlayer::PlaybackState GetRequestedInitialPlaybackState() const;

    void CheckAndNotifyMediaTracksChanged();

    void UpdateCurrentTime();

    void OnRefreshDRMConfiguration();

    CYISignal<Error> NotifyErrorOccurred;

    CYISignal<> NotifyPlaybackComplete;

    CYISignal<uint64_t> NotifyDurationChanged;

    CYISignal<bool, uint64_t> NotifySeekCompleted;

    std::unique_ptr<CYIVideoPlayerStateManager> m_pStateManager;

    std::unique_ptr<CYIClosedCaptionsDispatcher> m_pClosedCaptionsDispatcher;

    std::unique_ptr<DRMConfiguration> m_pDRMConfiguration;

    uint64_t m_maxBitrate;

    uint64_t m_initialBandwidthHint;

    uint64_t m_initialStartTimeMs;

    RefreshDRMConfigurationCallback m_refreshDRMConfigurationCallback;

private:
    struct SeekState
    {
        enum class Direction
        {
            Forward, 
            Reverse 
        };

        bool active; 
        Direction direction; 
        uint64_t requestedPositionMs; 
        uint64_t positionBeforeSeekMs; 
    };

    class TimeUpdater : public CYITime::UpdateListener
    {
    public:
        TimeUpdater();
        void SetPlayer(CYIAbstractVideoPlayer *pPlayer);
        virtual bool OnFrameTimeUpdated(std::chrono::microseconds frameTime) override;

    private:
        CYIAbstractVideoPlayer *m_pPlayer;
        uint64_t m_lastUpdateUs;
    };
    friend class TimeUpdater;

#if defined(DOXY)
    // We want to document this private section because users override these methods called by the abstract player.
protected:
#endif

    virtual CYIString GetName_() const;

    virtual CYIString GetVersion_() const;

    virtual Statistics GetStatistics_() const;

    /*
        \details Subclasses can extend this function to do additional work outside of the constructor for initializing the player.

        \sa #Init
    */
    virtual void Init_();

    /*
        \details Subclasses must implement this function to create the correct CYIVideoSurface instance for the CYIAbstractVideoPlayer implementation.

        \note The surface will be stored in m_pVideoSurface and will be cleaned up automatically.
     */
    virtual std::unique_ptr<CYIVideoSurface> CreateSurface_() = 0;

    virtual bool SupportsFormat_(StreamingFormat streamingFormat, DRMScheme drmScheme = DRMScheme::None) const = 0;

    virtual bool HasNativeStartTimeHandling_() const;

    virtual bool HasNativeBitrateEventHandling_() const;

    virtual bool HasNativeSeekEventHandling_() const;

    virtual bool HasInitialBandwidthHintHandling_() const;

    virtual void Prepare_(const CYIUrl &videoURI, StreamingFormat format) = 0;

    virtual void Play_() = 0;

    virtual void Pause_() = 0;

    virtual void Stop_() = 0;

    virtual uint64_t GetDurationMs_() const = 0;

    virtual uint64_t GetCurrentTimeMs_() const = 0;

    virtual std::vector<SeekableRange> GetLiveSeekableRanges_() const = 0;

    virtual void Seek_(uint64_t seekPositionMS) = 0;

    virtual bool SelectAudioTrack_(uint32_t id) = 0;

    virtual std::vector<AudioTrackInfo> GetAudioTracks_() const = 0;

    virtual CYIAbstractVideoPlayer::AudioTrackInfo GetActiveAudioTrack_() const = 0;

    virtual bool IsMuted_() const = 0;

    virtual void Mute_(bool mute) = 0;

    virtual void DisableClosedCaptions_() = 0;

    virtual bool SelectClosedCaptionsTrack_(uint32_t id) = 0;

    virtual std::vector<ClosedCaptionsTrackInfo> GetClosedCaptionsTracks_() const = 0;

    virtual CYIAbstractVideoPlayer::ClosedCaptionsTrackInfo GetActiveClosedCaptionsTrack_() const = 0;

    virtual void GetClosedCaptionsDispatcher_() const;

    virtual void SetMaxBitrate_(uint64_t maxBitrate);

    virtual void SetUserAgent_(const CYIString &userAgent);

    virtual BackgroundPlaybackInterface *GetBackgroundPlaybackInterface_() const;

    virtual HeadphoneJackInterface *GetHeadphoneJackInterface_() const;

    virtual BufferingInterface *GetBufferingInterface_() const;

    virtual TimedMetadataInterface *GetTimedMetadataInterface_() const;

    virtual VideoRequestHTTPHeadersInterface *GetVideoRequestHTTPHeadersInterface_();

    virtual MediaPlaybackControlsInterface *GetMediaPlaybackControlsInterface_() const;

#if defined(DOXY)
private:
#endif

    void CheckAndNotifyAudioTracksChanged();
    void CheckAndNotifyClosedCaptionsTracksChanged();
    void CheckAndNotifyBitrateChanged();
    void OnNotifyErrorOccurred(Error error);
    void OnNotifyPlaybackComplete();
    void OnNotifyDurationChanged(uint64_t duration);
    void UpdateSeekState(uint64_t positionBeforeSeekMs, uint64_t requestedPositionMs);
    void OnNotifySeekCompleted(bool success, uint64_t positionAfterSeekMs);
    void ClearCachedTrackData();
    void OnStateReady();
    void OnStateUnloaded();
    void ClearClosedCaptions();
    void SetTimeUpdatesEnabled(bool enabled);

    bool m_audioTracksAvailable;
    std::vector<AudioTrackInfo> m_audioTracksCache;

    float m_cachedTotalBitrate;
    float m_cachedVideoBitrate;
    float m_cachedAudioBitrate;

    std::unique_ptr<CYIVideoSurface> m_pVideoSurface;
    uint64_t m_lastNotifiedTime;
    TimeUpdater m_timeUpdater;
    PlaybackState m_initialPlaybackState;
    PlaybackState m_requestedInitialPlaybackState;
    CYITimer m_mediaTracksRefreshTimer;
    CYITimer m_bitrateRefreshTimer;
    bool m_isMuted;
    SeekState m_seekState;

    bool m_closedCaptionsTracksAvailable;
    std::vector<ClosedCaptionsTrackInfo> m_closedCaptionsTracksCache;
    uint32_t m_previousClosedCaptionsTrackId;
    static const ClosedCaptionsTrackInfo CLOSED_CAPTIONS_OFF_TRACK;

    YI_TYPE_BASES(CYIAbstractVideoPlayer)
    YI_DISALLOW_COPY_AND_ASSIGN(CYIAbstractVideoPlayer)
};

// Audio tracks
bool operator==(const CYIAbstractVideoPlayer::AudioTrackInfo &audioTrackL, const CYIAbstractVideoPlayer::AudioTrackInfo &audioTrackR);
bool operator!=(const CYIAbstractVideoPlayer::AudioTrackInfo &audioTrackL, const CYIAbstractVideoPlayer::AudioTrackInfo &audioTrackR);

// Closed captions tracks
bool operator==(const CYIAbstractVideoPlayer::ClosedCaptionsTrackInfo &closedCaptionsTrackL, const CYIAbstractVideoPlayer::ClosedCaptionsTrackInfo &closedCaptionsTrackR);
bool operator!=(const CYIAbstractVideoPlayer::ClosedCaptionsTrackInfo &closedCaptionsTrackL, const CYIAbstractVideoPlayer::ClosedCaptionsTrackInfo &closedCaptionsTrackR);

// Timed Metadata
bool operator==(const CYIAbstractVideoPlayer::TimedMetadata &timedMetadataL, const CYIAbstractVideoPlayer::TimedMetadata &timedMetadataR);
bool operator!=(const CYIAbstractVideoPlayer::TimedMetadata &timedMetadataL, const CYIAbstractVideoPlayer::TimedMetadata &timedMetadataR);

//States
bool operator==(const CYIAbstractVideoPlayer::PlayerState &playerStateL, const CYIAbstractVideoPlayer::PlayerState &playerStateR);
bool operator==(const CYIAbstractVideoPlayer::PlayerState &playerState, const CYIAbstractVideoPlayer::MediaState &mediaState);
bool operator==(const CYIAbstractVideoPlayer::MediaState &mediaState, const CYIAbstractVideoPlayer::PlayerState &playerState);
bool operator==(const CYIAbstractVideoPlayer::PlayerState &playerState, const CYIAbstractVideoPlayer::PlaybackState &playbackState);
bool operator==(const CYIAbstractVideoPlayer::PlaybackState &playbackState, const CYIAbstractVideoPlayer::PlayerState &playerState);

bool operator!=(const CYIAbstractVideoPlayer::PlayerState &playerStateL, const CYIAbstractVideoPlayer::PlayerState &playerStateR);
bool operator!=(const CYIAbstractVideoPlayer::PlayerState &playerState, const CYIAbstractVideoPlayer::MediaState &mediaState);
bool operator!=(const CYIAbstractVideoPlayer::MediaState &mediaState, const CYIAbstractVideoPlayer::PlayerState &playerState);
bool operator!=(const CYIAbstractVideoPlayer::PlayerState &playerState, const CYIAbstractVideoPlayer::PlaybackState &playbackState);
bool operator!=(const CYIAbstractVideoPlayer::PlaybackState &playbackState, const CYIAbstractVideoPlayer::PlayerState &playerState);

#endif //ifndef _YI_ABSTRACT_VIDEO_PLAYER_H_