Types

CallbackToken

A callback can be registered by (member)function onXXX(callback, CallbackToken* token = nullptr). With the returned token we can remove the callback by onXXX(nullptr, token).

• Non-null callback: register a callback and return a token(if not null).
• Null callback + non-null token: can remove the callback of given token.
• Null callback + null token: clear all callbacks.

enum MediaType

enum class MediaType : int8_t {
    Unknown = -1,
    Video = 0,
    Audio = 1,
    Subtitle = 3,
};

enum State

enum class State : int8_t {
    NotRunning,
    Stopped = NotRunning,
    Running,
    Playing = Running, /// start/resume to play
    Paused,
};
typedef State PlaybackState;

Current playback state. Set/Get by user.

enum MediaStatus (flags)

Defines the io status of a media stream, Use flags_added/removed() to check the change, for example buffering after seek is Loaded|Prepared|Buffering, and changes to Loaded|Prepared|Buffered when seek completed.

• NoMedia = 0: initial status, not invalid. // what if set an empty url and closed?
• Unloaded = 1: not loaded
• Loading: opening and parsing the media
• Loaded: media is loaded and parsed. player is stopped state. mediaInfo() is available now.
• Prepared: all tracks are buffered and ready to decode frames. tracks failed to open decoder are ignored
• Stalled: insufficient buffering or other interruptions (timeout, user interrupt)
• Buffering: when buffering starts
• Buffered: when buffering ends
• End: reached the end of the current media, no more data to read
• Seeking:
• Invalid: failed to load media because of unsupport format or invalid media source

enum SeekFlag (flags)

enum class SeekFlag {
    /// choose one of FromX
    From0       = 1,    /// relative to time 0
    FromStart   = 1<<1, /// relative to media start position
    FromNow     = 1<<2, /// relative to current position, the seek position can be negative
    Frame       = 1<<6, /* Seek by frame. Seek target is frame count instead of milliseconds. Currently only FromNow|Frame is supported. BUG: avsync */
    /// combine the above values with one of the following
/* KeyFrame forward seek may fail(permission denied) near the end of media if there's no key frame after seek target position*/
    KeyFrame    = 1<<8, /* fast key-frame seek, forward if Backward is not set. It's accurate seek without this flag. Accurate seek is slow and implies backward seek internally.*/
    Fast        = KeyFrame,
    InCache     = 1 << 10, // try to seek in memory cache first. useful for speeding up network stream seeking. Target position must be in range (position(), position() + Player.buffered()]

    Default     = KeyFrame|FromStart
};

enum VideoEffect

enum class VideoEffect {
    Brightness,   /* [-1.0f, 1.0f], default 0 */
    Contrast,     /* [-1.0f, 1.0f], default 0 */
    Hue,          /* [-1.0f, 1.0f], default 0 */
    Saturation,   /* [-1.0f, 1.0f], default 0 */
};

enum ColorSpace

enum ColorSpace: uint8_t {
    ColorSpaceUnknown,     // auto
    ColorSpaceBT709,       // default, sdr
    ColorSpaceBT2100_PQ,   // hdr10
// scRGB, linear sRGB in extended component range. Scene-referred white level, D65 is 80nit. Used on windows
    ColorSpaceSCRGB,
    ColorSpaceExtendedLinearDisplayP3,
// sRGB in extended component range, sRGB transfer function. Available for macOS displays
    ColorSpaceExtendedSRGB,
// linear sRGB in extended component range. Display-referred white level. Can be used in OBS, macOS
    ColorSpaceExtendedLinearSRGB,
};

class MediaEvent

Listen events via Player.onEvent

class MediaEvent {
public:
    int64_t error = 0; // result <0: error code(fourcc?). >=0: special value depending on event
    std::string category;
    std::string detail; // if error, detail can be error string

    union {
        struct {
            int stream;
        } decoder;
    };
};

Predefined events are:

• {timestamp(ms), "render.video", "1st_frame"}: when the first frame is rendererd
• {error, "decoder.audio", "open", stream}: decoder of a stream open error.
• {error, "decoder.video", "open", stream}: decoder of a stream open error.
• {error, "decoder.subtitle", "open", stream}: decoder of a stream open error.
• {0, "decoder.audio", DecoderName, stream}: decoder of a stream is open or changed
• {0, "decoder.video", DecoderName, stream}: decoder of a stream is open or changed
• {track, "decoder.video", "size", {width, height}}: video decoder output size change. MediaInfo.video[track].codec.width/height also changes.
• {0, "decoder.subtitle", DecoderName, stream}: decoder of a stream is open or changed
• {track, "video", "size", {width, height}}: video frame size change before rendering, e.g. change by a filter. MediaInfo.video[track].codec.width/height does not change.
• {progress 0~100, "reader.buffering"}: error is buffering progress
• {0/1, "thread.audio", stream}: decoder thread is started (error = 1) and about to exit(error = 0)
• {0/1, "thread.video", stream}: decoder thread is started (error = 1) and about to exit(error = 0)
• {0/1, "thread.subtitle", stream}: decoder thread is started (error = 1) and about to exit(error = 0)
• {error, "snapshot", saved_file if no error and error string if error < 0}: if snapshot() called
• {0, "cc"}: the 1st closed caption data is decoded. can be used in ui to show CC button to enable/disable cc rendering via Player.setProperty("cc", "0" or "1")
• {0, "metadata"}: metadata update. new metadata can be read from Player.mediaInfo().metadata
• {count, "cache.ranges"}: buffered time ranges added, dropped or merged. count is ranges count. Only for player property "demux.buffer.ranges" is set to a positive int.

struct SnapshotRequest

    struct SnapshotRequest {
        uint8_t* data = nullptr;
        int width = 0;
        int height = 0;
        int stride = 0;
        bool subtitle = false;
    };

• data: rgba data. Created internally or provided by user. If data is provided by user, stride, height and width MUST be also set, and data MUST be valid until snapshot callback is finished.
• width: result width of snapshot image set by user, or the same as current frame width if 0. no renderer transform. if both requested width and height are < 0, then result image is scaled image of current frame with ratio=width/height. no renderer transform. if only one of width and height < 0, then the result size is video renderer viewport size, and all transforms will be applied.
• stride: bytes per line
• subtitle: NOT IMPLEMENTED

enum class PixelFormat

enum class PixelFormat
{
    Unknown = 0,
    YUV420P,
    NV12,
    YUV422P,
    YUV444P,
    P010LE,
    P016LE,
    YUV420P10LE,
    UYVY422,
    RGB24,
    RGBA,           // same as QImage::Format_RGBA8888
    RGBX,           // same as QImage::Format_RGBX8888
    BGRA,           // same as QImage::Format_ARGB32
    BGRX,           // same as QImage::Format_RGB32
    RGB565LE,
    RGB48LE,
    RGB48 = RGB48LE,
    GBRP,
    GBRP10LE,
    XYZ12LE,
    YUVA420P,
    BC1,
    BC3,
    RGBA64,         // name: "rgba64le"
    BGRA64,         // name: "bgra64le"
    RGBP16,         // name: "rgbp16le"
    RGBPF32,        // name: "rgbpf32le"
    BGRAF32,        // name: "bgraf32le"
};