Defines an interface for controlling playback of media elementary streams.
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_pts argument for cases where
the duration is unknown, such as for live streams.
Well-defined value for an invalid player.
The audio write duration when all the audio connectors are local.
The audio write duration when at least one of the audio connectors are remote.
An indicator of whether the decoder can accept more samples.
The decoder is asking for one more sample.
Identify the type of side data accompanied with
SbPlayerSampleInfo, as side
data may come from multiple sources.
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.399) andnd https://www.webmproject.org/docs/container/#BlockAdditionall) . The first 8 bytes of the data contains the value of BlockAddID in big endian format, followed by the content of BlockAdditional.
An indicator of the general playback state.
The player has just been initialized. It is expecting an SbPlayerSeek() call to enter the prerolling state.
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.
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.
The player is presenting media, but it is paused at the end of the stream.
The player has been destroyed, and will send no more callbacks.
An opaque handle to an implementation-private structure representing a player.
typedef struct SbPlayerPrivate* SbPlayer
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
sample_buffer points to the the first buffer.
typedef void(* SbPlayerDeallocateSampleFunc) (SbPlayer player, void *context, const void *sample_buffer)
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 errors, that may set a
error: indicates the
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 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)
The playback related parameters to pass into SbPlayerCreate() and SbPlayerGetPreferredOutputMode().
Provides an appropriate DRM system if the media stream has encrypted portions. It will be
kSbDrmSystemInvalidif the stream does not have encrypted portions.
Contains a populated SbMediaAudioStreamInfo if
kSbMediaAudioCodecNone, the video doesn't have an audio track.
Contains a populated SbMediaVideoStreamInfo if
kSbMediaVideoCodecNone, the video is audio only.
Selects how the decoded video frames will be output. For example,
kSbPlayerOutputModePunchOutindicates that the decoded video frames will be output to a background video layer by the platform, and
kSbPlayerOutputDecodeToTextureindicates that the decoded video frames should be made available for the application to pull via calls to SbPlayerGetCurrentFrame().
Information about the current media playback state.
The position of the playback head, as precisely as possible, in microseconds.
The known duration of the currently playing media stream, in microseconds.
The result of getStartDate for the currently playing media stream, in microseconds since the epoch of January 1, 1601 UTC.
The width of the currently displayed frame, in pixels, or 0 if not provided by this player.
The height of the currently displayed frame, in pixels, or 0 if not provided by this player.
Whether playback is currently paused.
The current player volume in [0, 1].
The number of video frames sent to the player since the creation of the player.
The number of video frames decoded but not displayed since the creation of the player.
The number of video frames that failed to be decoded since the creation of the player.
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.
Information about the samples to be written into SbPlayerWriteSamples().
const void * buffer
Points to the buffer containing the sample data.
Size of the data pointed to by
The timestamp of the sample in SbTime.
Points to an array of side data for the input, when available.
The number of side data pointed by
side_data. It should be set to 0 if there is no side data for the input.
Information about an audio sample. This value can only be used when
Information about a video sample. This value can only be used when
union SbPlayerSampleInfo::@0 @1
The DRM system related info for the media sample. This value is required for encrypted samples. Otherwise, it must be
Side data accompanied with
SbPlayerSampleInfo, it can be arbitrary binary data
coming from multiple sources.
const uint8_t * data
datawill remain valid until SbPlayerDeallocateSampleFunc() is called on the
SbPlayerSampleInfo::bufferthe data is associated with.
The size of the data pointed by
data, in bytes.
player, freeing all associated resources.
Upon calling this method, there should be one call to the player status callback (i.e.
player_status_funcused 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
playerinto any other
SbPlayerfunction once SbPlayerDestroy has been called on that player.
player: The player to be destroyed. Must not be
void SbPlayerDestroy(SbPlayer player)
Returns the audio configurations used by
Returns true when
out_audio_configuration is filled with the information of
the configuration of the audio output devices used by
player. Returns false
index 0 to indicate that there is no audio output for this
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
audio_write_duration, as soon as they are available.
audio_write_duration will be to
kSbPlayerWriteDurationLocal when all audio configurations linked to
local, or if there isn't any audio output. It will be set to
kSbPlayerWriteDurationRemote kSbPlayerWriteDurationRemote for remote or
wireless audio outputs, i.e. one of
The app only guarantees to write
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
there's no written audio inputs.
The app will set
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
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.
bool SbPlayerGetAudioConfiguration(SbPlayer player, int index, SbMediaAudioConfiguration *out_audio_configuration)
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
SbDecodeTarget SbPlayerGetCurrentFrame(SbPlayer player)
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_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.
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
int SbPlayerGetMaximumNumberOfSamplesPerWrite(SbPlayer player, SbMediaType sample_type)
Returns the preferred output mode of the implementation when a video described
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
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.
SbPlayerOutputMode SbPlayerGetPreferredOutputMode(const SbPlayerCreationParam *creation_param)
Returns whether the given player handle is valid.
static bool SbPlayerIsValid(SbPlayer player)
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
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
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.
void SbPlayerSetBounds(SbPlayer player, int z_index, int x, int y, int width, int height)
Set the playback rate of the
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
than 1.0 will make the playback slower than its original speed. When
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
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
player must not be
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
volume: The new player volume. The value must be between
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.
void SbPlayerSetVolume(SbPlayer player, double volume)
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.
void SbPlayerWriteEndOfStream(SbPlayer player, SbMediaType stream_type)
sample_type: The type of sample being written. See the
SbMediaType enum in
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.
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 less than the return value of
void SbPlayerWriteSamples(SbPlayer player, SbMediaType sample_type, const SbPlayerSampleInfo *sample_infos, int number_of_sample_infos)