Starboard Module Reference: player.h

Defines an interface for controlling playback of media elementary streams.

Enums

SbPlayerDecoderState

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.

SbPlayerState

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.

Macros

SB_PLAYER_INITIAL_TICKET

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.

SB_PLAYER_NO_DURATION

The value to pass into SbPlayerCreate's `duration_ptr` argument for cases where the duration is unknown, such as for live streams.

Structs

SbPlayerInfo

Information about the current media playback state.

Members

Members
SbMediaTime
current_media_pts
The position of the playback head, as precisely as possible, in 90KHz ticks (PTS).
SbMediaTime
duration_pts
The known duration of the currently playing media stream, in 90KHz ticks (PTS).
int
frame_width
The width of the currently displayed frame, in pixels, or 0 if not provided by this player.
int
frame_height
The height of the currently displayed frame, in pixels, or 0 if not provided by this player.
bool
is_paused
Whether playback is currently paused.
double
volume
The current player volume in [0, 1].
int
total_video_frames
The number of video frames sent to the player since the creation of the player.
int
dropped_video_frames
The number of video frames decoded but not displayed since the creation of the player.
int
corrupted_video_frames
The number of video frames that failed to be decoded since the creation of the player.

SbPlayer

An opaque handle to an implementation-private structure representing a player.

Functions

SbPlayerCreate

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:

  • 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 will return kSbPlayerInvalid.

Declaration and definitions

SB_EXPORT 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
#if SB_VERSION(3)
    ,
    SbDecodeTargetProvider* provider
#endif  // SB_VERSION(3)
    );

#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*/
#if SB_VERSION(3)
                        ,
                        SbDecodeTargetProvider* /*provider*/
#endif
                        ) {
  return kSbPlayerInvalid;
}

Parameters

Parameters
SbWindow
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.
SbMediaVideoCodec
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.
SbMediaAudioCodec
audio_codec
The audio codec used for the player. The value should never be kSbMediaAudioCodecNone. In addition, the caller must provide a populated audio_header if the audio codec is kSbMediaAudioCodecAac.
SbMediaTime
duration_pts
The expected media duration in 90KHz ticks (PTS). It may be set to SB_PLAYER_NO_DURATION for live streams.
SbDrmSystem
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.
const SbMediaAudioHeader*
audio_header
Note that the caller must provide a populated audio_header if the audio codec is kSbMediaAudioCodecAac. Otherwise, audio_header can be NULL. See media.h for the format of the SbMediaAudioHeader struct.
SbPlayerDeallocateSampleFunc
sample_deallocate_func
SbPlayerDecoderStatusFunc
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.
SbPlayerStatusFunc
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.
void*
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.

SbPlayerDestroy

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

SB_EXPORT void SbPlayerDestroy(SbPlayer player);

#include "starboard/player.h"

void SbPlayerDestroy(SbPlayer /*player*/) {}

Parameters

Parameters
SbPlayer
player
The player to be destroyed.

SbPlayerGetCompositionHandle

Description

Gets a handle that represents the player's video output, for the purpose of composing with SbCompositor, which is currently undefined.

Declaration

SB_EXPORT SbPlayerCompositionHandle
SbPlayerGetCompositionHandle(SbPlayer player);

Parameters

Parameters
SbPlayer
player
The player for which the video output handle is retrieved.

SbPlayerGetInfo

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

SB_EXPORT void SbPlayerGetInfo(SbPlayer player, SbPlayerInfo* out_player_info);

#include "starboard/player.h"

void SbPlayerGetInfo(SbPlayer /*player*/, SbPlayerInfo* /*out_player_info*/) {}

Parameters

Parameters
SbPlayer
player
The player about which information is being retrieved.
SbPlayerInfo*
out_player_info
The information retrieved for the player.

SbPlayerGetTextureId

Description

Gets an OpenGL texture ID that points to the player's video output frame at the time it was called. This function can be called once, and the texture ID will be appropriately remapped to the current video frame when it is drawn.

Declaration

SB_EXPORT uint32_t SbPlayerGetTextureId(SbPlayer player);

Parameters

Parameters
SbPlayer
player
The player for which the texture ID is retrieved.

SbPlayerIsValid

Description

Returns whether the given player handle is valid.

Declaration

static SB_C_INLINE bool SbPlayerIsValid(SbPlayer player) {
  return player != kSbPlayerInvalid;
}

Parameters

Parameters
SbPlayer
player

SbPlayerSeek

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.)

  • 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).

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.

Declaration and definitions

SB_EXPORT void SbPlayerSeek(SbPlayer player,
                            SbMediaTime seek_to_pts,
                            int ticket);

#include "starboard/player.h"

void SbPlayerSeek(SbPlayer /*player*/,
                  SbMediaTime /*seek_to_pts*/,
                  int /*ticket*/) {}

Parameters

Parameters
SbPlayer
player
The SbPlayer in which the seek operation is being performed.
SbMediaTime
seek_to_pts
The frame at which playback should begin.
int
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.)

SbPlayerSetBounds

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 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

SB_EXPORT void SbPlayerSetBounds(SbPlayer player,
                                 int x,
                                 int y,
                                 int width,
                                 int height);

#include "starboard/player.h"

#if SB_IS(PLAYER_PUNCHED_OUT)

void SbPlayerSetBounds(SbPlayer /*player*/,
                       int /*x*/,
                       int /*y*/,
                       int /*width*/,
                       int /*height*/) {}

#endif  // SB_IS(PLAYER_PUNCHED_OUT)

Parameters

Parameters
SbPlayer
player
The player that is being resized.
int
x
The x-coordinate of the upper-left corner of the player.
int
y
The y-coordinate of the upper-left corner of the player.
int
width
The width of the player, in pixels.
int
height
The height of the player, in pixels.

SbPlayerSetPause

Description

Pauses or unpauses the player. If the player's state is kPlayerStatePrerolling, this function sets the initial pause state for the current seek target.

Declaration and definitions

SB_EXPORT void SbPlayerSetPause(SbPlayer player, bool pause);

#include "starboard/player.h"

void SbPlayerSetPause(SbPlayer /*player*/, bool /*pause*/) {}

Parameters

Parameters
SbPlayer
player
bool
pause

SbPlayerSetVolume

Description

Sets the player's volume.

Declaration and definitions

SB_EXPORT void SbPlayerSetVolume(SbPlayer player, double volume);

#include "starboard/player.h"

void SbPlayerSetVolume(SbPlayer /*player*/, double /*volume*/) {}

Parameters

Parameters
SbPlayer
player
The player in which the volume is being adjusted.
double
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.

SbPlayerWriteEndOfStream

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

SB_EXPORT void SbPlayerWriteEndOfStream(SbPlayer player,
                                        SbMediaType stream_type);

#include "starboard/player.h"

void SbPlayerWriteEndOfStream(SbPlayer /*player*/,
                              SbMediaType /*stream_type*/) {}

Parameters

Parameters
SbPlayer
player
The player to which the marker is written.
SbMediaType
stream_type
The type of stream for which the marker is written.

SbPlayerWriteSample

Description

Writes a sample of the given media type to player's input stream. The lifetime of 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

SB_EXPORT void SbPlayerWriteSample(
    SbPlayer player,
    SbMediaType sample_type,
    const void* sample_buffer,
    int sample_buffer_size,
    SbMediaTime sample_pts,
    const SbMediaVideoSampleInfo* video_sample_info,
    const SbDrmSampleInfo* sample_drm_info);

#include "starboard/player.h"

void SbPlayerWriteSample(SbPlayer /*player*/,
                         SbMediaType /*sample_type*/,
                         const void* /*sample_buffer*/,
                         int /*sample_buffer_size*/,
                         SbMediaTime /*sample_pts*/,
                         const SbMediaVideoSampleInfo* /*video_sample_info*/,
                         const SbDrmSampleInfo* /*sample_drm_info*/) {}

Parameters

Parameters
SbPlayer
player
The player to which the sample is written.
SbMediaType
sample_type
The type of sample being written. See the SbMediaType enum in media.h.
const void*
sample_buffer
A pointer to a buffer with the data for this sample. The buffer is expected to be a portion of a bytestream of the codec type that the player was created with. The buffer should contain a sequence of whole NAL Units for video, or a complete audio frame.
int
sample_buffer_size
The number of bytes in the given sample.
SbMediaTime
sample_pts
The timestamp of the sample in 90KHz ticks (PTS). Note that samples MAY be written "slightly" out of order.
const SbMediaVideoSampleInfo*
video_sample_info
Information about a video sample. This value is required if sample_type is kSbMediaTypeVideo. Otherwise, it must be NULL.
const SbDrmSampleInfo*
sample_drm_info
The DRM system for the media sample. This value is required for encrypted samples. Otherwise, it must be NULL.