starboard/player.h

// Copyright 2016 The Cobalt Authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Module Overview: Starboard Player module
//
// Defines an interface for controlling playback of media elementary streams.

#ifndef STARBOARD_PLAYER_H_
#define STARBOARD_PLAYER_H_

#include "starboard/configuration.h"

#include "starboard/decode_target.h"
#include "starboard/drm.h"
#include "starboard/export.h"
#include "starboard/media.h"
#include "starboard/types.h"
#include "starboard/window.h"

#ifdef __cplusplus
extern "C" {
#endif

// --- Types -----------------------------------------------------------------

// An indicator of whether the decoder can accept more samples.
typedef enum SbPlayerDecoderState {
  // The decoder is asking for one more sample.
  kSbPlayerDecoderStateNeedsData,
} SbPlayerDecoderState;

// An indicator of the general playback state.
typedef enum SbPlayerState {
  // The player has just been initialized. It is expecting an SbPlayerSeek()
  // call to enter the prerolling state.
  kSbPlayerStateInitialized,

  // The player is prerolling, collecting enough data to fill the pipeline
  // before presentation starts. After the first preroll is completed, there
  // should always be a video frame to render, even if the player goes back to
  // Prerolling after a Seek.
  kSbPlayerStatePrerolling,

  // The player is presenting media, and it is either paused or actively playing
  // in real-time. Note that the implementation should use this state to signal
  // that the preroll has been finished.
  kSbPlayerStatePresenting,

  // The player is presenting media, but it is paused at the end of the stream.
  kSbPlayerStateEndOfStream,

  // The player has been destroyed, and will send no more callbacks.
  kSbPlayerStateDestroyed,
} SbPlayerState;

typedef enum SbPlayerError {
  kSbPlayerErrorDecode,
  // The playback capability of the player has changed, likely because of a
  // change of the system environment.  For example, the system may support vp9
  // decoding with an external GPU.  When the external GPU is detached, this
  // error code can signal the app to retry the playback, possibly with h264.
  kSbPlayerErrorCapabilityChanged,
  // The max value of SbPlayer error type. It should always at the bottom
  // of SbPlayerError and never be used.
  kSbPlayerErrorMax,
} SbPlayerError;

typedef enum SbPlayerOutputMode {
  // Requests for SbPlayer to produce an OpenGL texture that the client must
  // draw every frame with its graphics rendering. It may be that we get a
  // texture handle, but cannot perform operations like glReadPixels on it if it
  // is DRM-protected, or it may not support DRM-protected content at all.  When
  // this output mode is provided to SbPlayerCreate(), the application will be
  // able to pull frames via calls to SbPlayerGetCurrentFrame().
  kSbPlayerOutputModeDecodeToTexture,

  // Requests for SbPlayer to use a "punch-out" output mode, where video is
  // rendered to the far background, and the graphics plane is automatically
  // composited on top of the video by the platform. The client must punch an
  // alpha hole out of the graphics plane for video to show through.  In this
  // case, changing the video bounds must be tightly synchronized between the
  // player and the graphics plane.
  kSbPlayerOutputModePunchOut,

  // An invalid output mode.
  kSbPlayerOutputModeInvalid,
} SbPlayerOutputMode;

// The playback related parameters to pass into SbPlayerCreate() and
// SbPlayerGetPreferredOutputMode().
typedef struct SbPlayerCreationParam {
  // Provides an appropriate DRM system if the media stream has encrypted
  // portions.  It will be |kSbDrmSystemInvalid| if the stream does not have
  // encrypted portions.
  SbDrmSystem drm_system;

#if SB_API_VERSION >= 15
  // Contains a populated SbMediaAudioStreamInfo if |audio_stream_info.codec|
  // isn't |kSbMediaAudioCodecNone|.  When |audio_stream_info.codec| is
  // |kSbMediaAudioCodecNone|, the video doesn't have an audio track.
  SbMediaAudioStreamInfo audio_stream_info;
  // Contains a populated SbMediaVideoStreamInfo if |video_stream_info.codec|
  // isn't |kSbMediaVideoCodecNone|.  When |video_stream_info.codec| is
  // |kSbMediaVideoCodecNone|, the video is audio only.
  SbMediaVideoStreamInfo video_stream_info;
#else   // SB_API_VERSION >= 15
  // Contains a populated SbMediaAudioSampleInfo if |audio_sample_info.codec|
  // isn't |kSbMediaAudioCodecNone|.  When |audio_sample_info.codec| is
  // |kSbMediaAudioCodecNone|, the video doesn't have an audio track.
  SbMediaAudioSampleInfo audio_sample_info;
  // Contains a populated SbMediaVideoSampleInfo if |video_sample_info.codec|
  // isn't |kSbMediaVideoCodecNone|.  When |video_sample_info.codec| is
  // |kSbMediaVideoCodecNone|, the video is audio only.
  SbMediaVideoSampleInfo video_sample_info;
#endif  // SB_API_VERSION >= 15

  // Selects how the decoded video frames will be output.  For example,
  // |kSbPlayerOutputModePunchOut| indicates that the decoded video frames will
  // be output to a background video layer by the platform, and
  // |kSbPlayerOutputDecodeToTexture| indicates that the decoded video frames
  // should be made available for the application to pull via calls to
  // SbPlayerGetCurrentFrame().
  SbPlayerOutputMode output_mode;
} SbPlayerCreationParam;

// Identify the type of side data accompanied with |SbPlayerSampleInfo|, as side
// data may come from multiple sources.
typedef enum SbPlayerSampleSideDataType {
  // The side data comes from the BlockAdditional data in the Matroska/Webm
  // container, as specified in
  // https://tools.ietf.org/id/draft-lhomme-cellar-matroska-03.html#rfc.section.7.3.39
  // and https://www.webmproject.org/docs/container/#BlockAdditional.
  // The first 8 bytes of the data contains the value of BlockAddID in big
  // endian format, followed by the content of BlockAdditional.
  kMatroskaBlockAdditional,
} SbPlayerSampleSideDataType;

// Side data accompanied with |SbPlayerSampleInfo|, it can be arbitrary binary
// data coming from multiple sources.
typedef struct SbPlayerSampleSideData {
  SbPlayerSampleSideDataType type;
  // |data| will remain valid until SbPlayerDeallocateSampleFunc() is called on
  // the |SbPlayerSampleInfo::buffer| the data is associated with.
  const uint8_t* data;
  // The size of the data pointed by |data|, in bytes.
  size_t size;
} SbPlayerSampleSideData;

// Information about the samples to be written into SbPlayerWriteSamples().
typedef struct SbPlayerSampleInfo {
  SbMediaType type;
  // Points to the buffer containing the sample data.
  const void* buffer;
  // Size of the data pointed to by |buffer|.
  int buffer_size;
  // The timestamp of the sample in microseconds since Windows epoch UTC.
  int64_t timestamp;

  // Points to an array of side data for the input, when available.
  SbPlayerSampleSideData* side_data;
  // The number of side data pointed by |side_data|.  It should be set to 0 if
  // there is no side data for the input.
  int side_data_count;

  union {
    // Information about an audio sample. This value can only be used when
    // |type| is kSbMediaTypeAudio.
    SbMediaAudioSampleInfo audio_sample_info;
    // Information about a video sample. This value can only be used when |type|
    // is kSbMediaTypeVideo.
    SbMediaVideoSampleInfo video_sample_info;
  };

  // The DRM system related info for the media sample. This value is required
  // for encrypted samples. Otherwise, it must be |NULL|.
  const SbDrmSampleInfo* drm_info;
} SbPlayerSampleInfo;

// Information about the current media playback state.
#if SB_API_VERSION >= 15
typedef struct SbPlayerInfo {
#else   // SB_API_VERSION >= 15
typedef struct SbPlayerInfo2 {
#endif  // SB_API_VERSION >= 15
  // The position of the playback head, as precisely as possible, in
  // microseconds.
  int64_t current_media_timestamp;

  // The known duration of the currently playing media stream, in microseconds.
  int64_t duration;

  // The result of getStartDate for the currently playing media stream, in
  // microseconds since the epoch of January 1, 1601 UTC.
  int64_t start_date;

  // The width of the currently displayed frame, in pixels, or 0 if not provided
  // by this player.
  int frame_width;

  // The height of the currently displayed frame, in pixels, or 0 if not
  // provided by this player.
  int frame_height;

  // Whether playback is currently paused.
  bool is_paused;

  // The current player volume in [0, 1].
  double volume;

  // The number of video frames sent to the player since the creation of the
  // player.
  int total_video_frames;

  // The number of video frames decoded but not displayed since the creation of
  // the player.
  int dropped_video_frames;

  // The number of video frames that failed to be decoded since the creation of
  // the player.
  int corrupted_video_frames;

  // The rate of playback.  The video is played back in a speed that is
  // proportional to this.  By default it is 1.0 which indicates that the
  // playback is at normal speed.  When it is greater than one, the video is
  // played in a faster than normal speed.  When it is less than one, the video
  // is played in a slower than normal speed.  Negative speeds are not
  // supported.
  double playback_rate;
#if SB_API_VERSION >= 15
} SbPlayerInfo;
#else   // SB_API_VERSION >= 15
} SbPlayerInfo2;
#endif  // SB_API_VERSION >= 15

// An opaque handle to an implementation-private structure representing a
// player.
typedef struct SbPlayerPrivate* SbPlayer;

// Callback for decoder status updates, called in response to a call to
// SbPlayerSeek() or SbPlayerWriteSample(). This callback will never be called
// until at least one call to SbPlayerSeek has occurred. |ticket| will be set to
// the ticket passed into the last received call to SbPlayerSeek() at the time
// this callback was dispatched. This is to distinguish status callbacks for
// interrupting seeks. These callbacks will happen on a different thread than
// the calling thread, and it is not valid to call SbPlayer functions from
// within this callback. After an update with kSbPlayerDecoderStateNeedsData,
// the user of the player will make at most one call to SbPlayerWriteSample() or
// SbPlayerWriteEndOfStream(). The player implementation should update the
// decoder status again after such call to notify its user to continue writing
// more frames.
typedef void (*SbPlayerDecoderStatusFunc)(SbPlayer player,
                                          void* context,
                                          SbMediaType type,
                                          SbPlayerDecoderState state,
                                          int ticket);

// Callback for player status updates. These callbacks will happen on a
// different thread than the calling thread, and it is not valid to call
// SbPlayer functions from within this callback.
typedef void (*SbPlayerStatusFunc)(SbPlayer player,
                                   void* context,
                                   SbPlayerState state,
                                   int ticket);

// Callback for player errors, that may set a |message|.
// |error|: indicates the error code.
// |message|: provides specific informative diagnostic message about the error
//            condition encountered. It is ok for the message to be an empty
//            string or NULL if no information is available.
typedef void (*SbPlayerErrorFunc)(SbPlayer player,
                                  void* context,
                                  SbPlayerError error,
                                  const char* message);

// Callback to free the given sample buffer data.  When more than one buffer
// are sent in SbPlayerWriteSample(), the implementation only has to call this
// callback with |sample_buffer| points to the first buffer.
typedef void (*SbPlayerDeallocateSampleFunc)(SbPlayer player,
                                             void* context,
                                             const void* sample_buffer);

// --- Constants -------------------------------------------------------------

// The value to pass into SbPlayerCreate's |duration_pts| argument for cases
// where the duration is unknown, such as for live streams.
#define SB_PLAYER_NO_DURATION (-1)

// The value of the initial ticket held by the player before the first seek.
// The player will use this ticket value to make the first call to
// SbPlayerStatusFunc with kSbPlayerStateInitialized.
#define SB_PLAYER_INITIAL_TICKET (0)

// Well-defined value for an invalid player.
#define kSbPlayerInvalid ((SbPlayer)NULL)

#if SB_API_VERSION >= 15

// The audio write duration when all the audio connectors are local.
#define kSbPlayerWriteDurationLocal (1000000 / 2)  // 0.5 seconds

// The audio write duration when at least one of the audio connectors are
// remote.
#define kSbPlayerWriteDurationRemote (1000000 * 10)  // 10 seconds

#endif  // SB_API_VERSION >= 15

// Returns whether the given player handle is valid.
static inline bool SbPlayerIsValid(SbPlayer player) {
  return player != kSbPlayerInvalid;
}

// --- Functions -------------------------------------------------------------

// Creates a player that will be displayed on |window| for the specified
// |video_codec| and |audio_codec|, acquiring all resources needed to operate
// it, and returning an opaque handle to it. The expectation is that a new
// player will be created and destroyed for every playback.
//
// This function returns the created player. Note the following:
// - The associated decoder of the returned player should be assumed to not be
//   in |kSbPlayerDecoderStateNeedsData| until SbPlayerSeek() has been called
//   on it.
// - It is expected either that the thread that calls SbPlayerCreate is the same
//   thread that calls the other |SbPlayer| functions for that player, or that
//   there is a mutex guarding calls into each |SbPlayer| instance.
// - If there is a platform limitation on how many players can coexist
//   simultaneously, then calls made to this function that attempt to exceed
//   that limit must return |kSbPlayerInvalid|. Multiple calls to SbPlayerCreate
//   must not cause a crash.
//
// |window|: The window that will display the player. |window| can be
//   |kSbWindowInvalid| for platforms where video is only displayed on a
//   particular window that the underlying implementation already has access to.
//
// |video_codec|: The video codec used for the player. If |video_codec| is
//   |kSbMediaVideoCodecNone|, the player is an audio-only player. If
//   |video_codec| is any other value, the player is an audio/video decoder.
//   This can be set to |kSbMediaVideoCodecNone| to play a video with only an
//   audio track.
//
// |audio_codec|: The audio codec used for the player. The caller must provide a
//   populated |audio_sample_info| if audio codec is |kSbMediaAudioCodecAac|.
//   Can be set to |kSbMediaAudioCodecNone| to play a video without any audio
//   track.  In such case |audio_sample_info| must be NULL.
//
// |drm_system|: If the media stream has encrypted portions, then this
//   parameter provides an appropriate DRM system, created with
//   |SbDrmCreateSystem()|. If the stream does not have encrypted portions,
//   then |drm_system| may be |kSbDrmSystemInvalid|.
//
// |audio_sample_info|: Note that the caller must provide a populated
//   |audio_sample_info| if the audio codec is |kSbMediaAudioCodecAac|.
//   Otherwise, |audio_sample_info| can be NULL. See media.h for the format of
//   the |SbMediaAudioSampleInfo| struct.
//
//   Note that |audio_specific_config| is a pointer and the content it points to
//   is no longer valid after this function returns.  The implementation has to
//   make a copy of the content if it is needed after the function returns.
//
// |max_video_capabilities|: This string communicates the max video capabilities
//   required to the platform. The web app will not provide a video stream
//   exceeding the maximums described by this parameter. Allows the platform to
//   optimize playback pipeline for low quality video streams if it knows that
//   it will never adapt to higher quality streams. The string uses the same
//   format as the string passed in to SbMediaCanPlayMimeAndKeySystem(), for
//   example, when it is set to "width=1920; height=1080; framerate=15;", the
//   video will never adapt to resolution higher than 1920x1080 or frame per
//   second higher than 15 fps. When the maximums are unknown, this will be set
//   to NULL.
//
// |sample_deallocator_func|: If not |NULL|, the player calls this function
//   on an internal thread to free the sample buffers passed into
//   SbPlayerWriteSample().
//
// |decoder_status_func|: If not |NULL|, the decoder calls this function on an
//   internal thread to provide an update on the decoder's status. No work
//   should be done on this thread. Rather, it should just signal the client
//   thread interacting with the decoder.
//
// |player_status_func|: If not |NULL|, the player calls this function on an
//   internal thread to provide an update on the playback status. No work
//   should be done on this thread. Rather, it should just signal the client
//   thread interacting with the decoder.
//
// |player_error_func|: If not |NULL|, the player calls this function on an
//   internal thread to provide an update on the error status. This callback is
//   responsible for setting the media error message.
//
// |context|: This is passed to all callbacks and is generally used to point
//   at a class or struct that contains state associated with the player.
//
// |output_mode|: Selects how the decoded video frames will be output.  For
//   example, kSbPlayerOutputModePunchOut indicates that the decoded video
//   frames will be output to a background video layer by the platform, and
//   kSbPlayerOutputDecodeToTexture indicates that the decoded video frames
//   should be made available for the application to pull via calls to
//   SbPlayerGetCurrentFrame().
//
// |provider|: Only present in Starboard version 3 and up.  If not |NULL|,
//   then when output_mode == kSbPlayerOutputModeDecodeToTexture, the player MAY
//   use the provider to create SbDecodeTargets on the renderer thread. A
//   provider may not always be needed by the player, but if it is needed, and
//   the provider is not given, the player will fail by returning
//   |kSbPlayerInvalid|.
//
// If |NULL| is passed to any of the callbacks (|sample_deallocator_func|,
// |decoder_status_func|, |player_status_func|, or |player_error_func| if it
// applies), then |kSbPlayerInvalid| must be returned.
SB_EXPORT SbPlayer
SbPlayerCreate(SbWindow window,
               const SbPlayerCreationParam* creation_param,
               SbPlayerDeallocateSampleFunc sample_deallocate_func,
               SbPlayerDecoderStatusFunc decoder_status_func,
               SbPlayerStatusFunc player_status_func,
               SbPlayerErrorFunc player_error_func,
               void* context,
               SbDecodeTargetGraphicsContextProvider* context_provider);

// Returns the preferred output mode of the implementation when a video
// described by |creation_param| is played.  It is assumed that it is okay to
// call SbPlayerCreate() with the same video described by |creation_param|,
// with its |output_mode| member replaced by the returned output mode.
// When the caller has no preference on the output mode, it will set
// |creation_param->output_mode| to |kSbPlayerOutputModeInvalid|, and the
// implementation can return its preferred output mode based on the information
// contained in |creation_param|.  The caller can also set
// |creation_param->output_mode| to its preferred output mode, and the
// implementation should return the same output mode if it is supported,
// otherwise the implementation should return an output mode that it is
// supported, as if |creation_param->output_mode| is set to
// |kSbPlayerOutputModeInvalid| prior to the call.
// Note that it is not the responsibility of this function to verify whether the
// video described by |creation_param| can be played on the platform, and the
// implementation should try its best effort to return a valid output mode.
// |creation_param| must not be NULL.
SB_EXPORT SbPlayerOutputMode
SbPlayerGetPreferredOutputMode(const SbPlayerCreationParam* creation_param);

// Destroys |player|, freeing all associated resources.
//  * Upon calling this method, there should be one call to the player status
//    callback (i.e. |player_status_func| used in the creation of the player)
//    which indicates the player is destroyed. Note, the callback has to be
//    in-flight when SbPlayerDestroyed is called.
//  * No more other callbacks should be issued after this function returns.
//  * It is not allowed to pass |player| into any other |SbPlayer| function
//    once SbPlayerDestroy has been called on that player.
// |player|: The player to be destroyed. Must not be |kSbPlayerInvalid|.
SB_EXPORT void SbPlayerDestroy(SbPlayer player);

// Tells the player to freeze playback (if playback has already started),
// reset or flush the decoder pipeline, and go back to the Prerolling state.
// The player should restart playback once it can display the frame at
// |seek_to_timestamp|, or the closest it can get. (Some players can only seek
// to I-Frames, for example.)
//
// - Seek must be called before samples are sent when starting playback for
//   the first time, or the client never receives the
//   |kSbPlayerDecoderStateNeedsData| signal.
// - A call to seek may interrupt another seek.
// - After this function is called, the client should not send any more audio
//   or video samples until |SbPlayerDecoderStatusFunc| is called back with
//   |kSbPlayerDecoderStateNeedsData| for each required media type.
//   |SbPlayerDecoderStatusFunc| is the |decoder_status_func| callback function
//   that was specified when the player was created (SbPlayerCreate).
//
// |player|: The SbPlayer in which the seek operation is being performed.
//   Must not be |kSbPlayerInvalid|.

// |seek_to_timestamp|: The frame at which playback should begin.
// |ticket|: A user-supplied unique ID that is be passed to all subsequent
//   |SbPlayerDecoderStatusFunc| calls. (That is the |decoder_status_func|
//   callback function specified when calling SbPlayerCreate.)
//
//   The |ticket| value is used to filter calls that may have been in flight
//   when SbPlayerSeek was called. To be very specific, once SbPlayerSeek has
//   been called with ticket X, a client should ignore all
//   |SbPlayerDecoderStatusFunc| calls that do not pass in ticket X.
#if SB_API_VERSION >= 15
SB_EXPORT void SbPlayerSeek(SbPlayer player,
                            int64_t seek_to_timestamp,
                            int ticket);
#else   // SB_API_VERSION >= 15
SB_EXPORT void SbPlayerSeek2(SbPlayer player,
                             int64_t seek_to_timestamp,
                             int ticket);
#endif  // SB_API_VERSION >= 15

// Writes samples of the given media type to |player|'s input stream. The
// lifetime of |sample_infos|, and the members of its elements like |buffer|,
// |video_sample_info|, and |drm_info| (as well as member |subsample_mapping|
// contained inside it) are not guaranteed past the call to
// SbPlayerWriteSamples(). That means that before returning, the implementation
// must synchronously copy any information it wants to retain from those
// structures.
//
// SbPlayerWriteSamples() allows writing of multiple samples in one call.
//
// |player|: The player to which the sample is written. Must not be
//   |kSbPlayerInvalid|.

// |sample_type|: The type of sample being written. See the |SbMediaType|
//   enum in media.h.
// |sample_infos|: A pointer to an array of SbPlayerSampleInfo with
//   |number_of_sample_infos| elements, each holds the data for an sample, i.e.
//   a sequence of whole NAL Units for video, or a complete audio frame.
//   |sample_infos| cannot be assumed to live past the call into
//   SbPlayerWriteSamples(), so it must be copied if its content will be used
//   after SbPlayerWriteSamples() returns.
// |number_of_sample_infos|: Specify the number of samples contained inside
//   |sample_infos|.  It has to be at least one, and at most the return value
//   of SbPlayerGetMaximumNumberOfSamplesPerWrite().
#if SB_API_VERSION >= 15
SB_EXPORT void SbPlayerWriteSamples(SbPlayer player,
#else   // SB_API_VERSION >= 15
SB_EXPORT void SbPlayerWriteSample2(SbPlayer player,
#endif  // SB_API_VERSION >= 15
                                    SbMediaType sample_type,
                                    const SbPlayerSampleInfo* sample_infos,
                                    int number_of_sample_infos);

// Returns the maximum number of samples that can be written in a single call
// to SbPlayerWriteSamples(). Returning a value greater than one can improve
// performance by allowing SbPlayerWriteSamples() to write multiple samples in
// one call.
//
// Note that this feature is currently disabled in Cobalt where
// SbPlayerWriteSamples() will always be called with one sample.
//
// |player|: The player for which the number is retrieved.
// |sample_type|: The type of sample for which the number is retrieved. See the
//   |SbMediaType| enum in media.h.
SB_EXPORT int SbPlayerGetMaximumNumberOfSamplesPerWrite(
    SbPlayer player,
    SbMediaType sample_type);

// Writes a marker to |player|'s input stream of |stream_type| indicating that
// there are no more samples for that media type for the remainder of this
// media stream. This marker is invalidated, along with the rest of the stream's
// contents, after a call to SbPlayerSeek.
//
// |player|: The player to which the marker is written.
// |stream_type|: The type of stream for which the marker is written.
SB_EXPORT void SbPlayerWriteEndOfStream(SbPlayer player,
                                        SbMediaType stream_type);

// Sets the player bounds to the given graphics plane coordinates. The changes
// do not take effect until the next graphics frame buffer swap. The default
// bounds for a player is the full screen.  This function is only relevant when
// the |player| is created with the kSbPlayerOutputModePunchOut output mode, and
// if this is not the case then this function call can be ignored.
//
// This function is called on every graphics frame that changes the video
// bounds. For example, if the video bounds are being animated, then this will
// be called at up to 60 Hz. Since the function could be called up to once per
// frame, implementors should take care to avoid related performance concerns
// with such frequent calls.
//
// |player|: The player that is being resized. Must not be |kSbPlayerInvalid|.
// |z_index|: The z-index of the player.  When the bounds of multiple players
//            are overlapped, the one with larger z-index will be rendered on
//            top of the ones with smaller z-index.
// |x|: The x-coordinate of the upper-left corner of the player.
// |y|: The y-coordinate of the upper-left corner of the player.
// |width|: The width of the player, in pixels.
// |height|: The height of the player, in pixels.
SB_EXPORT void SbPlayerSetBounds(SbPlayer player,
                                 int z_index,
                                 int x,
                                 int y,
                                 int width,
                                 int height);

// Set the playback rate of the |player|.  |rate| is default to 1.0 which
// indicates the playback is at its original speed.  A |rate| greater than one
// will make the playback faster than its original speed.  For example, when
// |rate| is 2, the video will be played at twice the speed as its original
// speed.  A |rate| less than 1.0 will make the playback slower than its
// original speed.  When |rate| is 0, the playback will be paused.
// The function returns true when the playback rate is set to |playback_rate| or
// to a rate that is close to |playback_rate| which the implementation supports.
// It returns false when the playback rate is unchanged, this can happen when
// |playback_rate| is negative or if it is too high to support.
//
// |player| must not be |kSbPlayerInvalid|.
SB_EXPORT bool SbPlayerSetPlaybackRate(SbPlayer player, double playback_rate);

// Sets the player's volume.
//
// |player|: The player in which the volume is being adjusted. Must not be
//   |kSbPlayerInvalid|.
// |volume|: The new player volume. The value must be between |0.0| and |1.0|,
//   inclusive. A value of |0.0| means that the audio should be muted, and a
//   value of |1.0| means that it should be played at full volume.
SB_EXPORT void SbPlayerSetVolume(SbPlayer player, double volume);

// Gets a snapshot of the current player state and writes it to
// |out_player_info|. This function may be called very frequently and is
// expected to be inexpensive.
//
// |player|: The player about which information is being retrieved. Must not be
//   |kSbPlayerInvalid|.
// |out_player_info|: The information retrieved for the player.

#if SB_API_VERSION >= 15
SB_EXPORT void SbPlayerGetInfo(SbPlayer player, SbPlayerInfo* out_player_info);
#else   // SB_API_VERSION >= 15
SB_EXPORT void SbPlayerGetInfo2(SbPlayer player,
                                SbPlayerInfo2* out_player_info2);
#endif  // SB_API_VERSION >= 15

// Given a player created with the kSbPlayerOutputModeDecodeToTexture
// output mode, it will return a SbDecodeTarget representing the current frame
// to be rasterized.  On GLES systems, this function must be called on a
// thread with an EGLContext current, and specifically the EGLContext that will
// be used to eventually render the frame.  If this function is called with a
// |player| object that was created with an output mode other than
// kSbPlayerOutputModeDecodeToTexture, kSbDecodeTargetInvalid is returned.
//
// |player| must not be |kSbPlayerInvalid|.
SB_EXPORT SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player);

// Returns the audio configurations used by |player|.
//
// Returns true when |out_audio_configuration| is filled with the information of
// the configuration of the audio output devices used by |player|.  Returns
// false for |index| 0 to indicate that there is no audio output for this
// |player|.  Returns false for |index| greater than 0 to indicate that there
// are no more audio output configurations other than the ones already returned.
//
// The app will use the information returned to determine audio related
// behaviors, like:
//
//   Audio Write Duration: Audio write duration is how far past the current
//       playback position the app will write audio samples. The app will write
//       all samples between |current_playback_position| and
//       |current_playback_position| + |audio_write_duration|, as soon as they
//       are available.
//
//       |audio_write_duration| will be to `kSbPlayerWriteDurationLocal` when
//       all audio configurations linked to |player| is local, or if there isn't
//       any audio output.  It will be set to `kSbPlayerWriteDurationRemote` for
//       remote or wireless audio outputs, i.e. one of
//       `kSbMediaAudioConnectorBluetooth` or `kSbMediaAudioConnectorRemote*`.
//
//       The app only guarantees to write |audio_write_duration| past
//       |current_playback_position|, but the app is free to write more samples
//       than that.  So the platform shouldn't rely on this for flow control.
//       The platform should achieve flow control by sending
//       `kSbPlayerDecoderStateNeedsData` less frequently.
//
//       The platform is responsible for guaranteeing that when only
//       |audio_write_duration| audio samples are written at a time, no playback
//       issues occur (such as transient or indefinite hanging).
//
// The audio configurations should be available as soon as possible, and they
// have to be available when the |player| is at `kSbPlayerStatePresenting`,
// unless the audio codec is |kSbMediaAudioCodecNone| or there's no written
// audio inputs.
//
// The app will set |audio_write_duration| to `kSbPlayerWriteDurationLocal`
// when the audio configuration isn't available (i.e. the function returns false
// when index is 0).  The platform has to make the audio configuration
// available immediately after the SbPlayer is created, if it expects the app to
// treat the platform as using wireless audio outputs.
//
// Once at least one audio configurations are returned, the return values and
// their orders shouldn't change during the life time of |player|.  The platform
// may inform the app of any changes by sending
// `kSbPlayerErrorCapabilityChanged` to request a playback restart.
//
// |player|: The player about which information is being retrieved. Must not be
//   |kSbPlayerInvalid|.
// |index|: The index of the audio output configuration.  Must be greater than
//   or equal to 0.
// |out_audio_configuration|: The information about the audio output, refer to
//   |SbMediaAudioConfiguration| for more details.  Must not be NULL.
#if SB_API_VERSION >= 15
SB_EXPORT bool SbPlayerGetAudioConfiguration(
    SbPlayer player,
    int index,
    SbMediaAudioConfiguration* out_audio_configuration);
#endif  // SB_API_VERSION >= 15

#ifdef __cplusplus
}  // extern "C"
#endif

#endif  // STARBOARD_PLAYER_H_