WsbMediaAccess.h

Go to the documentation of this file.

/*****************************************************************
|
|   Wasabi - Media Access API
|
|   $Id: WsbMediaAccess.h 12954 2017-03-22 23:31:07Z hwa $
|   Original author: Gilles Boccon-Gibod
|
|   This software is provided to you pursuant to your agreement 
|   with Intertrust Technologies Corporation ("Intertrust"). 
|   This software may be used only in accordance with the terms 
|   of the agreement.
|      
|   Copyright (c) 2008-2014 by Intertrust. All rights reserved. 
|
****************************************************************/
#ifndef _WSB_MEDIA_ACCESS_H_
#define _WSB_MEDIA_ACCESS_H_

/*----------------------------------------------------------------------
|   includes
+---------------------------------------------------------------------*/
#include "WsbTypes.h"
#include "WsbElements.h"
#include "WsbMediaFile.h"

/*----------------------------------------------------------------------
|   types
+---------------------------------------------------------------------*/


typedef struct WSB_MediaSource WSB_MediaSource;


typedef enum {
    WSB_MEDIA_SOURCE_EVENT_STATE_CHANGED = 0,
    WSB_MEDIA_SOURCE_EVENT_PRESENTATION,
    WSB_MEDIA_SOURCE_EVENT_PERIOD,
    WSB_MEDIA_SOURCE_EVENT_INIT_SEGMENT,
    WSB_MEDIA_SOURCE_EVENT_MEDIA_SEGMENT,
    WSB_MEDIA_SOURCE_EVENT_MEDIA_DATA,
    WSB_MEDIA_SOURCE_EVENT_SEEK_DONE,
    WSB_MEDIA_SOURCE_EVENT_START_DONE,
    WSB_MEDIA_SOURCE_EVENT_STOP_DONE,
    WSB_MEDIA_SOURCE_EVENT_FLUSH_DONE
} WSB_MediaSourceEventType;

typedef enum {
    WSB_MEDIA_SOURCE_STATE_IDLE,
    WSB_MEDIA_SOURCE_STATE_RUNNING,
    WSB_MEDIA_SOURCE_STATE_STOPPED
} WSB_MediaSourceState;

typedef enum {
    WSB_MEDIA_PRESENTATION_TYPE_MPEG_DASH
} WSB_MediaPresentationType;

typedef enum {
    WSB_MEDIA_PRESENTATION_MODE_STATIC,
    WSB_MEDIA_PRESENTATION_MODE_DYNAMIC
} WSB_MediaPresentationMode;

typedef enum {
    WSB_MEDIA_CONTAINER_FORMAT_MP4,
    WSB_MEDIA_CONTAINER_FORMAT_MPEG2TS,
    WSB_MEDIA_CONTAINER_FORMAT_FILE
} WSB_MediaContainerFormat;

typedef enum {
    WSB_MEDIA_SEGMENT_TYPE_DASH_ISOFF,
    WSB_MEDIA_SEGMENT_TYPE_DASH_MP2T,
    WSB_MEDIA_SEGMENT_TYPE_SINGLE_FILE
} WSB_MediaSegmentType;

typedef struct {
    WSB_UInt64 bandwidth;
} WSB_MediaSourceStatistics;

typedef struct {
    WSB_UInt32       type; /* see WSB_MediaSourceInfoExtension types */
    WSB_Size         data_size;
    const WSB_UInt8* data;
} WSB_MediaSourceInfoExtension;

typedef struct {
    WSB_MediaType        type;
    WSB_UInt32           format;
    WSB_UInt64           media_duration;
    WSB_UInt32           media_timescale;
    WSB_Size             codec_info_size;
    const unsigned char* codec_info;
} WSB_MediaSourceMediaInfo;

typedef struct {
    WSB_MediaPresentationType type;
    WSB_MediaPresentationMode mode;
    WSB_UInt64                duration;
    WSB_Element*              details;
} WSB_MediaPresentationInfo;

typedef struct {
    WSB_Ordinal  period_index;
    WSB_UInt64   start;
    WSB_UInt64   duration;
    WSB_Element* details;
} WSB_MediaPeriodInfo;

typedef struct {
    WSB_MediaSegmentType            type;
    WSB_Ordinal                     stream_index; 
    const char*                     representation_id;
    WSB_MediaContainerFormat        media_container_format;
    unsigned int                    media_info_count;
    const WSB_MediaSourceMediaInfo* media_infos;
} WSB_MediaInitSegmentInfo;


typedef struct WSB_MediaFileInfo
{
    const char*     url;
    WSB_Size        size;
    WSB_MediaType   media_type;
    WSB_MediaFormat media_format;
} WSB_MediaFileInfo;

typedef struct {
    WSB_MediaSegmentType      type;
    WSB_Ordinal               stream_index; 
    const char*               representation_id;
    WSB_UInt32                segment_index;
    WSB_UInt32                fragment_index;
    WSB_UInt32                duration;
    WSB_UInt32                timescale;
    const char*               url;
    WSB_Position              range_offset;
    WSB_LargeSize             range_length;
    WSB_MediaSourceStatistics stats;
} WSB_MediaSegmentInfo;

typedef struct {
    WSB_UInt32       algorithm_id; 
    bool             reset_iv_at_subsample;
    WSB_UInt8        kid[16];
    const char*      content_id;
    unsigned int     data_size;
    const WSB_UInt8* data;
} WSB_DashCencInfo;

typedef struct {
    WSB_UInt8   profile;
    WSB_UInt8   level;
    WSB_Boolean is_dual_track;
} WSB_DashDvInfo;

typedef struct {
    WSB_MediaSegmentInfo    base;
    const WSB_DashCencInfo* cenc_info;
    const WSB_DashDvInfo*   dv_info;
} WSB_DashIsoFfMediaSegmentInfo;

typedef struct {
    WSB_MediaSegmentType type;
    WSB_Ordinal          stream_index; 
    const char*          representation_id;
    WSB_Ordinal          media_info_id;
    unsigned int         media_data_size;
    const unsigned char* media_data;
} WSB_MediaDataInfo;

typedef struct {
    WSB_MediaDataInfo base;
    WSB_UInt64        dts;
    WSB_UInt64        cts;
    WSB_UInt32        duration;
    WSB_UInt32        flags;
} WSB_DashIsoFfMediaDataInfo;

typedef struct {
    const char*  representation_id;
    const char*  codecs;
    WSB_UInt64   bandwidth;
    WSB_Element* details;
} WSB_MediaRepresentationInfo;

typedef struct {
    const char*  language;
    WSB_Element* details;
} WSB_MediaStreamVariantInfo;

typedef struct {
    WSB_MediaSourceEventType type;
} WSB_MediaSourceEvent;

typedef struct {
    WSB_MediaSourceEvent base;
    WSB_MediaSourceState state;
    WSB_Result           error_code;
    const char*          message;
} WSB_MediaSourceStateChangedEvent;

typedef struct {
    WSB_MediaSourceEvent                base;
    WSB_MediaPresentationInfo*          presentation_info;
    unsigned int                        extension_count;
    const WSB_MediaSourceInfoExtension* extensions;
} WSB_MediaSourcePresentationEvent;

typedef struct {
    WSB_MediaSourceEvent                base;
    WSB_MediaPeriodInfo*                period_info;
    unsigned int                        extension_count;
    const WSB_MediaSourceInfoExtension* extensions;
} WSB_MediaSourcePeriodEvent;

typedef struct {
    WSB_MediaSourceEvent                base;
    const WSB_MediaInitSegmentInfo*     init_segment_info;
    unsigned int                        extension_count;
    const WSB_MediaSourceInfoExtension* extensions;
} WSB_MediaSourceInitSegmentEvent;

typedef struct {
    WSB_MediaSourceEvent                base;
    const WSB_MediaSegmentInfo*         segment_info;
    unsigned int                        extension_count;
    const WSB_MediaSourceInfoExtension* extensions;
} WSB_MediaSourceMediaSegmentEvent;

typedef struct {
    WSB_MediaSourceEvent                base;
    const WSB_MediaDataInfo*            data_info;
    unsigned int                        extension_count;
    const WSB_MediaSourceInfoExtension* extensions;
} WSB_MediaSourceMediaDataEvent;

typedef struct {
    WSB_MediaSourceEvent base;
    WSB_Result           seek_result;
} WSB_MediaSourceSeekDoneEvent;

typedef struct {
    WSB_MediaSourceEvent base;
    WSB_Result           start_result;
} WSB_MediaSourceStartDoneEvent;

typedef struct {
    WSB_MediaSourceEvent base;
    WSB_Result           stop_result;
} WSB_MediaSourceStopDoneEvent;

typedef struct {
    WSB_MediaSourceEvent base;
    WSB_Result           flush_result;
} WSB_MediaSourceFlushDoneEvent;

typedef struct WSB_MediaSourceListenerInstance WSB_MediaSourceListenerInstance;
typedef struct WSB_MediaSourceListenerInterface WSB_MediaSourceListenerInterface;
typedef struct {
    WSB_MediaSourceListenerInstance*        instance;
    const WSB_MediaSourceListenerInterface* iface;
} WSB_MediaSourceListener;

struct WSB_MediaSourceListenerInterface {
    void (*OnEvent)(const WSB_MediaSourceListener* self, 
                    const WSB_MediaSourceEvent*    event); 
};

typedef struct WSB_MediaSourceCodecFilterInstance WSB_MediaSourceCodecFilterInstance;
typedef struct WSB_MediaSourceCodecFilterInterface WSB_MediaSourceCodecFilterInterface;
typedef struct {
    WSB_MediaSourceCodecFilterInstance*        instance;
    const WSB_MediaSourceCodecFilterInterface* iface;
} WSB_MediaSourceCodecFilter;

struct WSB_MediaSourceCodecFilterInterface {
    int (*IsCodecSupported)(const WSB_MediaSourceCodecFilter* self,
                            WSB_MediaType                     media_type,
                            const char*                       codec); 
};

typedef struct WSB_MediaSourceStreamSelectorInstance WSB_MediaSourceStreamSelectorInstance;
typedef struct WSB_MediaSourceStreamSelectorInterface WSB_MediaSourceStreamSelectorInterface;
typedef struct {
    WSB_MediaSourceStreamSelectorInstance*        instance;
    const WSB_MediaSourceStreamSelectorInterface* iface;
} WSB_MediaSourceStreamSelector;

struct WSB_MediaSourceStreamSelectorInterface {
    int (*SelectStream)(const WSB_MediaSourceStreamSelector* self,
                        WSB_MediaType                        media_type,
                        unsigned int                         stream_count,
                        const WSB_MediaStreamVariantInfo**   streams); 
};

typedef struct WSB_MediaSourceRepresentationSelectorInstance WSB_MediaSourceRepresentationSelectorInstance;
typedef struct WSB_MediaSourceRepresentationSelectorInterface WSB_MediaSourcRepresentationSelectorInterface;
typedef struct {
    WSB_MediaSourceRepresentationSelectorInstance*        instance;
    const WSB_MediaSourceRepresentationSelectorInterface* iface;
} WSB_MediaSourceRepresentationSelector;

struct WSB_MediaSourceRepresentationSelectorInterface {
    int (*SelectRepresentation)(
        const WSB_MediaSourceRepresentationSelector* self,
        WSB_MediaType                                media_type,
        unsigned int                                 representation_count,
        const WSB_MediaRepresentationInfo**          representations,
        const WSB_MediaSourceStatistics*             statistics); 
};

typedef struct {
    WSB_Cardinal max_audio_bytes_in_queue;
    WSB_Cardinal max_video_bytes_in_queue;    /* TS accounted as video */
    WSB_Cardinal max_subtitle_bytes_in_queue;
    WSB_UInt32   max_bitrate;       /* used by default stream selector */
    WSB_UInt32   max_height;        /* used by default stream selector */
    WSB_UInt32   max_width;         /* used by default stream selector */
    const char*  prefered_language; /* used by default stream selector */
    WSB_Boolean  create_stopped;    /* WSB_FALSE by default */
    double       segment_retry_period; /* seconds between failed fetch retries */
} WSB_MediaSourceConfig;

typedef struct {
    WSB_Size audio_bytes_in_queue;
    WSB_Size video_bytes_in_queue;
    WSB_Size audio_duration_in_queue;   /* in milliseconds */
    WSB_Size video_duration_in_queue;   /* in milliseconds */
} WSB_MediaSourceStatus;

typedef enum {
    WSB_MEDIA_DATA_DECRYPTER_TYPE_CENC
} WSB_MediaDataDecrypterType;

typedef enum {
    WSB_MEDIA_DATA_DECRYPTER_KEY_FORMAT_RAW,
    WSB_MEDIA_DATA_DECRYPTER_KEY_FORMAT_SKB
} WSB_MediaDataDecrypterKeyFormat;

typedef enum {
    WSB_SEEK_FLAG_BOTH,
    WSB_SEEK_FLAG_VIDEO_ONLY,
    WSB_SEEK_FLAG_AUDIO_ONLY
} WSB_MediaSourceSeekFlag;

typedef enum {
    WSB_FLUSH_FLAG_BOTH,
    WSB_FLUSH_FLAG_VIDEO_ONLY,
    WSB_FLUSH_FLAG_AUDIO_ONLY
} WSB_MediaSourceFlushFlag;

typedef enum {
    WSB_RESUME_FLAG_FROM_CURRENT_POSITON,
    WSB_RESUME_FLAG_CATCHUP_TO_LIVE
} WSB_MediaSourceResumeFlag;

/*----------------------------------------------------------------------
|   constants
+---------------------------------------------------------------------*/
#define WSB_MEDIA_SOURCE_TIMEOUT_INFINITE ((WSB_Int32)(-1))

/* WSB_DashIsoFfMediaDataInfo flags */
#define WSB_DASH_ISOFF_MEDIA_DATA_FLAG_SYNC    1

/* WSB_MediaSourceInfoExtension types */
#define WSB_MEDIA_SOURCE_INFO_EXTENSION_TYPE_PSSH 0x70737368  /* 'pssh' */

/* Return values for stream and representation selectors */
#define WSB_MEDIA_SOURCE_USE_DEFAULT_SELECTOR    (-1)
#define WSB_MEDIA_SOURCE_NO_COMPATIBLE_SELECTION (-2)

/*----------------------------------------------------------------------
|   functions
+---------------------------------------------------------------------*/
#if defined(__cplusplus)
extern "C" {
#endif

WSB_EXPORT WSB_Result
WSB_MediaSource_Create(
    const char*                                  url, 
    const char*                                  mime_type,
    const WSB_MediaSourceListener*               listener,
    const WSB_MediaSourceCodecFilter*            codec_filter,
    const WSB_MediaSourceStreamSelector*         stream_selector,
    const WSB_MediaSourceRepresentationSelector* representation_selector,
    const WSB_MediaSourceConfig*                 config,
    WSB_MediaSource**                            source);

WSB_EXPORT WSB_Result
WSB_MediaSource_Start(WSB_MediaSource* self, WSB_MediaSourceResumeFlag resume_flag);

WSB_EXPORT WSB_Result
WSB_MediaSource_Stop(WSB_MediaSource* self);

WSB_EXPORT WSB_Result
WSB_MediaSource_Flush(WSB_MediaSource* self, WSB_MediaSourceFlushFlag flush_flag);

WSB_EXPORT WSB_Result
WSB_MediaSource_Advance(WSB_MediaSource* self,
                        WSB_Int32        timeout);

WSB_EXPORT WSB_Result
WSB_MediaSource_Seek(WSB_MediaSource*         self,
                     WSB_UInt64               position_in_ms,
                     WSB_MediaSourceSeekFlag seek_flag);

WSB_EXPORT WSB_Result
WSB_MediaSource_ReselectStreams(WSB_MediaSource* self);

WSB_EXPORT WSB_Result
WSB_MediaSource_GetStatus(WSB_MediaSource*       self,
                          WSB_MediaSourceStatus* status);

WSB_EXPORT WSB_Result
WSB_MediaSource_Destroy(WSB_MediaSource* self); 

typedef struct WSB_MediaDataDecrypter WSB_MediaDataDecrypter;

WSB_EXPORT WSB_Result
WSB_MediaDataDecrypter_Create(WSB_MediaDataDecrypterType      type,
                              const void*                     init_info,
                              WSB_MediaDataDecrypterKeyFormat key_format,
                              const WSB_UInt8*                key,
                              unsigned int                    key_size,
                              WSB_MediaDataDecrypter**        decrypter);

WSB_EXPORT WSB_Result
WSB_MediaDataDecrypter_Decrypt(WSB_MediaDataDecrypter* self,
                               const WSB_UInt8*        in,
                               unsigned int            in_size,
                               WSB_UInt8*              out,
                               unsigned int*           out_size);

WSB_EXPORT WSB_Result
WSB_MediaDataDecrypter_Destroy(WSB_MediaDataDecrypter* self);

#if defined(__cplusplus)
}
#endif

#endif /* _WSB_MEDIA_ACCESS_H_ */