blob: 01abfafa3552b3090d858cde08f801d4faa53e4a [file] [log] [blame]
// Copyright 2015 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
#ifndef CHROMECAST_PUBLIC_MEDIA_MEDIA_PIPELINE_BACKEND_H_
#define CHROMECAST_PUBLIC_MEDIA_MEDIA_PIPELINE_BACKEND_H_
#include <stdint.h>
#include <string>
#include "cast_key_status.h"
#include "decoder_config.h"
namespace chromecast {
struct Size;
namespace media {
class CastDecoderBuffer;
class DecryptContext;
// Interface for platform-specific output of media.
// A new MediaPipelineBackend will be instantiated for each media player
// instance and raw audio stream. If a backend has both video and audio
// decoders, they must be synchronized.
// If more backends are requested than the platform supports, the unsupported
// extra backends may return nullptr for CreateAudioDecoder/CreateVideoDecoder.
// The basic usage pattern is:
// * Decoder objects created and delegates set, then Initialize called
// * Start/Stop/Pause/Resume used to manage playback state
// * Decoder objects are used to pass actual stream data buffers
// * Backend must make appropriate callbacks on the provided Delegate
// All functions will be called on the media thread. Delegate callbacks
// must be made on this thread also (using provided TaskRunner if necessary).
class MediaPipelineBackend {
public:
// Return code for PushBuffer
enum BufferStatus {
kBufferSuccess,
kBufferFailed,
kBufferPending,
};
class Decoder {
public:
using BufferStatus = MediaPipelineBackend::BufferStatus;
// Delegate methods must be called on the main CMA thread.
class Delegate {
public:
using BufferStatus = MediaPipelineBackend::BufferStatus;
// See comments on PushBuffer. Must not be called with kBufferPending.
virtual void OnPushBufferComplete(BufferStatus status) = 0;
// Must be called after an end-of-stream buffer has been rendered (ie, the
// last real buffer has been sent to the output hardware).
virtual void OnEndOfStream() = 0;
// May be called if a decoder error occurs. No more calls to PushBuffer()
// will be made after this is called.
virtual void OnDecoderError() = 0;
// Must be called when a decryption key status changes.
virtual void OnKeyStatusChanged(const std::string& key_id,
CastKeyStatus key_status,
uint32_t system_code) = 0;
// Must be called when video resolution change is detected by the decoder.
// Only relevant for video decoders.
virtual void OnVideoResolutionChanged(const Size& size) = 0;
protected:
virtual ~Delegate() {}
};
// Provides the delegate for this decoder. Called once before the backend
// is initialized; is never called after the backend is initialized.
virtual void SetDelegate(Delegate* delegate) = 0;
// Pushes a buffer of data for decoding and output. If the implementation
// cannot push the buffer now, it must store the buffer, return
// |kBufferPending| and execute the push at a later time when it becomes
// possible to do so. The implementation must then invoke
// Delegate::OnPushBufferComplete once the push has been completed. Pushing
// a pending buffer should be aborted if Stop is called;
// OnPushBufferComplete need not be invoked in this case.
// If |kBufferPending| is returned, the pipeline will stop pushing any
// further buffers until OnPushBufferComplete is invoked.
// OnPushBufferComplete should be only be invoked to indicate completion of
// a pending buffer push - not for the immediate |kBufferSuccess| return
// case.
// The buffer's lifetime is managed by the caller code - it MUST NOT be
// deleted by the MediaPipelineBackend implementation, and MUST NOT be
// dereferenced after completion of buffer push (i.e.
// returning kBufferSuccess/kBufferFailure for synchronous completion,
// calling OnPushBufferComplete() for kBufferPending case).
virtual BufferStatus PushBuffer(CastDecoderBuffer* buffer) = 0;
protected:
virtual ~Decoder() {}
};
class AudioDecoder : public Decoder {
public:
// Info on pipeline latency: amount of data in pipeline not rendered yet,
// and timestamp of system clock (must be CLOCK_MONOTONIC_RAW) at which
// delay measurement was taken. Both times in microseconds.
struct RenderingDelay {
RenderingDelay()
: delay_microseconds(INT64_MIN), timestamp_microseconds(INT64_MIN) {}
RenderingDelay(int64_t delay_microseconds_in,
int64_t timestamp_microseconds_in)
: delay_microseconds(delay_microseconds_in),
timestamp_microseconds(timestamp_microseconds_in) {}
int64_t delay_microseconds;
int64_t timestamp_microseconds;
};
// Statistics (computed since last call to backend Start).
struct Statistics {
// Reported as webkitAudioBytesDecoded. Counts number of source bytes
// decoded (not decoder output bytes).
uint64_t decoded_bytes;
};
// Provides the audio configuration. Called once before the backend is
// initialized, and again any time the configuration changes (in any state).
// Note that SetConfig() may be called before SetDelegate() is called.
// Returns true if the configuration is a supported configuration.
virtual bool SetConfig(const AudioConfig& config) = 0;
// Sets the volume multiplier for this audio stream.
// The multiplier is in the range [0.0, 1.0]. If not called, a default
// multiplier of 1.0 is assumed. Returns true if successful.
// Only called after the backend has been initialized.
virtual bool SetVolume(float multiplier) = 0;
// Returns the pipeline latency: i.e. the amount of data
// in the pipeline that have not been rendered yet, in microseconds.
// Returns delay = INT64_MIN if the latency is not available.
// Only called when the backend is playing.
virtual RenderingDelay GetRenderingDelay() = 0;
// Returns the playback statistics since last call to backend Start. Only
// called when playing or paused.
virtual void GetStatistics(Statistics* statistics) = 0;
protected:
~AudioDecoder() override {}
};
class VideoDecoder : public Decoder {
public:
// Statistics (computed since last call to backend Start).
struct Statistics {
// Counts number of source bytes decoded (not decoder output).
uint64_t decoded_bytes; // Reported as webkitVideoBytesDecoded.
uint64_t decoded_frames; // Reported as webkitDecodedFrames.
uint64_t dropped_frames; // Reported as webkitDroppedFrames.
};
// Provides the video configuration. Called once before the backend is
// initialized, and again any time the configuration changes (in any state).
// Note that SetConfig() may be called before SetDelegate() is called.
// Returns true if the configuration is a supported configuration.
virtual bool SetConfig(const VideoConfig& config) = 0;
// Returns the playback statistics since last call to backend Start. Only
// called when playing or paused.
virtual void GetStatistics(Statistics* statistics) = 0;
protected:
~VideoDecoder() override {}
};
virtual ~MediaPipelineBackend() {}
// Creates a new AudioDecoder attached to this pipeline. MediaPipelineBackend
// maintains ownership of the decoder object (and must not delete before it's
// destroyed). Will be called zero or more times, all calls made before
// Initialize. May return nullptr if the platform implementation cannot
// support any additional simultaneous playback at this time.
virtual AudioDecoder* CreateAudioDecoder() = 0;
// Creates a new VideoDecoder attached to this pipeline. MediaPipelineBackend
// maintains ownership of the decoder object (and must not delete before it's
// destroyed). Will be called zero or more times, all calls made before
// Initialize. Note: Even if your backend only supports audio, you must
// provide a default implementation of VideoDecoder; one way to do this is to
// inherit from MediaPipelineBackendDefault. May return nullptr if the
// platform implementation cannot support any additional simultaneous playback
// at this time.
virtual VideoDecoder* CreateVideoDecoder() = 0;
// Initializes the backend. This will be called once, after Decoder creation
// but before all other functions. Hardware resources for all decoders should
// be acquired here. Backend is then considered in Initialized state.
// Returns false for failure.
virtual bool Initialize() = 0;
// Places pipeline into playing state. Playback will start at given time once
// buffers are pushed. Called only when in Initialized state. |start_pts| is
// the start playback timestamp in microseconds.
virtual bool Start(int64_t start_pts) = 0;
// Returns pipeline to 'Initialized' state. May be called while playing or
// paused. Buffers cannot be pushed in Initialized state.
virtual void Stop() = 0;
// Pauses media playback. Called only when in playing state.
virtual bool Pause() = 0;
// Resumes media playback. Called only when in paused state.
virtual bool Resume() = 0;
// Gets the current playback timestamp in microseconds. Only called when in
// the "playing" or "paused" states.
virtual int64_t GetCurrentPts() = 0;
// Sets the playback rate. |rate| > 0. If this is not called, a default rate
// of 1.0 is assumed. Returns true if successful. Only called when in
// the "playing" or "paused" states.
virtual bool SetPlaybackRate(float rate) = 0;
};
} // namespace media
} // namespace chromecast
#endif // CHROMECAST_PUBLIC_MEDIA_MEDIA_PIPELINE_BACKEND_H_