Defines an interface for controlling playback of media elementary streams.
An indicator of whether the decoder can accept more samples.
Values
kSbPlayerDecoderStateNeedsData - The decoder is asking for one more sample.kSbPlayerDecoderStateBufferFull - The decoder is not ready for any more samples, so do not send them.Note that this enum value has been deprecated and the SbPlayerimplementation should no longer use this value.kSbPlayerDecoderStateDestroyed - The player has been destroyed, and will send no more callbacks.Values
kSbPlayerOutputModeDecodeToTexture - Requests for SbPlayer to produce an OpenGL texture that the client mustdraw every frame with its graphics rendering. It may be that we get atexture handle, but cannot perform operations like glReadPixels on it if itis DRM-protected, or it may not support DRM-protected content at all. Whenthis output mode is provided to SbPlayerCreate(), the application will beable to pull frames via calls to SbPlayerGetCurrentFrame().kSbPlayerOutputModePunchOut - Requests for SbPlayer to use a “punch-out” output mode, where video isrendered to the far background, and the graphics plane is automaticallycomposited on top of the video by the platform. The client must punch analpha hole out of the graphics plane for video to show through. In thiscase, changing the video bounds must be tightly synchronized between theplayer and the graphics plane.kSbPlayerOutputModeInvalid - An invalid output mode.An indicator of the general playback state.
Values
kSbPlayerStateInitialized - The player has just been initialized. It is expecting an SbPlayerSeek()call to enter the prerolling state.kSbPlayerStatePrerolling - The player is prerolling, collecting enough data to fill the pipelinebefore presentation starts. After the first preroll is completed, thereshould always be a video frame to render, even if the player goes back toPrerolling after a Seek.kSbPlayerStatePresenting - The player is presenting media, and it is either paused or activelyplaying in real-time. Note that the implementation should use thisstate to signal that the preroll has been finished.kSbPlayerStateEndOfStream - The player is presenting media, but it is paused at the end of the stream.kSbPlayerStateDestroyed - The player has been destroyed, and will send no more callbacks.kSbPlayerStateError - The player encountered an error. It expects an SbPlayerDestroy() callto tear down the player. Calls to other functions may be ignored andcallbacks may not be triggered.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.
The value to pass into SbPlayerCreate's duration_ptr argument for cases where the duration is unknown, such as for live streams.
Information about the current media playback state.
Members
An opaque handle to an implementation-private structure representing a player.
Description
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:
Declaration and definitions
#include "starboard/player.h"
#if !SB_HAS(PLAYER)
#error "SbPlayerCreate requires SB_HAS(PLAYER)."
#endif
SbPlayer SbPlayerCreate(SbWindow /*window*/,
SbMediaVideoCodec /*video_codec*/,
SbMediaAudioCodec /*audio_codec*/,
SbMediaTime /*duration_pts*/,
SbDrmSystem /*drm_system*/,
const SbMediaAudioHeader* /*audio_header*/,
SbPlayerDeallocateSampleFunc /*sample_deallocate_func*/,
SbPlayerDecoderStatusFunc /*decoder_status_func*/,
SbPlayerStatusFunc /*player_status_func*/,
void* /*context*/,
SbPlayerOutputMode /*output_mode*/,
SbDecodeTargetGraphicsContextProvider* /*provider*/) {
return kSbPlayerInvalid;
}
Parameters
Description
Creates a URL-based SbPlayer that will be displayed on window for the specified URL url, 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.
In many ways this function is similar to SbPlayerCreate, but it is missing the input arguments related to the configuration and format of the audio and video stream, as well as the DRM system. The DRM system for a player created with SbPlayerCreateWithUrl can be set after creation using SbPlayerSetDrmSystem. Because the DRM system is not available at the time of SbPlayerCreateWithUrl, it takes in a callback, encrypted_media_init_data_encountered_cb, which is run when encrypted media initial data is encountered.
Declaration and definitions
#include "starboard/player.h"
#if !SB_HAS(PLAYER)
#error "SbPlayerCreateWithUrl requires SB_HAS(PLAYER)."
#endif
#if SB_HAS(PLAYER_WITH_URL)
SbPlayer SbPlayerCreateWithUrl(
const char* /* url */,
SbWindow /* window */,
SbMediaTime /* duration_pts */,
SbPlayerStatusFunc /* player_status_func */,
SbPlayerEncryptedMediaInitDataEncounteredCB /* cb */,
void* /* context */) {
// Stub.
return kSbPlayerInvalid;
}
// TODO: Actually move this to a separate file or get rid of these URL
// player stubs altogether.
void SbPlayerSetDrmSystem(SbPlayer player, SbDrmSystem drm_system) { /* Stub */
}
#endif // SB_HAS(PLAYER_WITH_URL)
Parameters
Description
Destroys player, freeing all associated resources. Each callback must receive one more callback to say that the player was destroyed. Callbacks may be in-flight when SbPlayerDestroy is called, and should be ignored once this function is called.
It is not allowed to pass player into any other SbPlayer function once SbPlayerDestroy has been called on that player.
Declaration and definitions
#include "starboard/player.h"
void SbPlayerDestroy(SbPlayer /*player*/) {}
Parameters
Description
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.
Declaration and definitions
#include "starboard/player.h"
#if !SB_HAS(PLAYER)
#error "This file requires SB_HAS(PLAYER)."
#endif
SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer /*player*/) {
return kSbDecodeTargetInvalid;
}
Parameters
Description
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.
Declaration and definitions
#include "starboard/player.h"
void SbPlayerGetInfo(SbPlayer /*player*/, SbPlayerInfo* /*out_player_info*/) {}
Parameters
Description
Returns whether the given player handle is valid.
Declaration
static SB_C_INLINE bool SbPlayerIsValid(SbPlayer player) {
return player != kSbPlayerInvalid;
}
Parameters
Declaration and definitions
#include "starboard/player.h"
#if !SB_HAS(PLAYER)
#error "This file requires SB_HAS(PLAYER)."
#endif
bool SbPlayerOutputModeSupported(SbPlayerOutputMode /*output_mode*/,
SbMediaVideoCodec /*codec*/,
SbDrmSystem /*drm_system*/) {
return false;
}
Parameters
Description
Returns true if the given URL player output mode is supported by the platform. If this function returns true, it is okay to call SbPlayerCreate() with the given output_mode.
Declaration
SB_EXPORT bool SbPlayerOutputModeSupportedWithUrl(
SbPlayerOutputMode output_mode);
Parameters
Description
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_pts, or the closest it can get. (Some players can only seek to I-Frames, for example.)
Declaration and definitions
#include "starboard/player.h"
void SbPlayerSeek(SbPlayer /*player*/,
SbMediaTime /*seek_to_pts*/,
int /*ticket*/) {}
Parameters
Description
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.
Declaration and definitions
#include "starboard/player.h"
#if !SB_HAS(PLAYER)
#error "This file requires SB_HAS(PLAYER)."
#endif
void SbPlayerSetBounds(SbPlayer /*player*/,
int /*z_index*/,
int /*x*/,
int /*y*/,
int /*width*/,
int /*height*/) {
}
Parameters
Description
Sets the DRM system of a running URL-based SbPlayer created with SbPlayerCreateWithUrl. This may only be run once for a given SbPlayer.
Declaration
SB_EXPORT void SbPlayerSetDrmSystem(SbPlayer player, SbDrmSystem drm_system);
Parameters
Description
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.
Declaration and definitions
#include "starboard/player.h"
#if !SB_HAS(PLAYER)
#error "This file requires SB_HAS(PLAYER)."
#endif
bool SbPlayerSetPlaybackRate(SbPlayer /*player*/, double /*playback_rate*/) {
return false;
}
Parameters
Description
Sets the player's volume.
Declaration and definitions
#include "starboard/player.h"
void SbPlayerSetVolume(SbPlayer /*player*/, double /*volume*/) {}
Parameters
Description
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.
Declaration and definitions
#include "starboard/player.h"
void SbPlayerWriteEndOfStream(SbPlayer /*player*/,
SbMediaType /*stream_type*/) {}
Parameters
Description
Writes a single sample of the given media type to player's input stream. Its data may be passed in via more than one buffers. The lifetime of sample_buffers, sample_buffer_sizes, video_sample_info, and sample_drm_info (as well as member subsample_mapping contained inside it) are not guaranteed past the call to SbPlayerWriteSample. That means that before returning, the implementation must synchronously copy any information it wants to retain from those structures.
Declaration and definitions
#include "starboard/player.h"
#if !SB_HAS(PLAYER)
#error "This file requires SB_HAS(PLAYER)."
#endif
void SbPlayerWriteSample(SbPlayer /*player*/,
SbMediaType /*sample_type*/,
#if SB_API_VERSION >= 6
const void* const* /*sample_buffers*/,
const int* /*sample_buffer_sizes*/,
#else // SB_API_VERSION >= 6
const void** /*sample_buffers*/,
int* /*sample_buffer_sizes*/,
#endif // SB_API_VERSION >= 6
int /*number_of_sample_buffers*/,
SbMediaTime /*sample_pts*/,
const SbMediaVideoSampleInfo* /*video_sample_info*/,
const SbDrmSampleInfo* /*sample_drm_info*/) {
}
Parameters