fuchsia.media.sessions2

Added: 7

PROTOCOLS

ActiveSession

Defined in fuchsia.media.sessions2/discovery.fidl

A protocol for watching the current active media session on the device.

The currently active media session is the most recent existing media session to announce a "Playing" state on the local device, even if it is now paused.

WatchActiveSession

Watches the active session. The first request will be answered immediately with the current active session. Always leave a request hanging to receive a reply when the active session changes.

Request

<EMPTY>

Response

Name	Type
`session`	`client_end:SessionControl?`

Discovery

Defined in fuchsia.media.sessions2/discovery.fidl

Discovery observes the collection of published media sessions and connects clients to them.

ConnectToSession

Connects to a SessionControl for session_id if present. Drops the given channel otherwise.

Request

Name	Type
`session_id`	`SessionId`
`session_control_request`	`server_end:SessionControl`

WatchSessions

Connects a session watcher configured with the given options.

Request

Name	Type
`watch_options`	`WatchOptions`
`session_watcher`	`client_end:SessionsWatcher`

ObserverDiscovery

Defined in fuchsia.media.sessions2/discovery.fidl

ObserverDiscovery observes the collection of published media sessions and connects clients to them for observation without playback controls.

ConnectToSession

Connects to a SessionObserver for session_id if present. Drops the given channel otherwise.

Request

Name	Type
`session_id`	`SessionId`
`session_request`	`server_end:SessionObserver`

WatchSessions

Connects a session watcher configured with the given options.

Request

Name	Type
`watch_options`	`WatchOptions`
`sessions_watcher`	`client_end:SessionsWatcher`

Player

Defined in fuchsia.media.sessions2/player.fidl

Player is a handle for a media player. Unsupported commands are no-ops. Consult PlaybackCapabilities, sent by to learn which commands are supported.

BindVolumeControl

Binds to the session's volume control for control and notifications. If this method is not supported as indicated by the absence of the HAS_GAIN_CONTROL flag in PlayerCapabilities, the channel handle passed as volume_control_request is closed by the service.

Request

Name	Type
`volume_control_request`	`server_end:fuchsia.media.audio/VolumeControl`

NextItem

Changes media to the next item (e.g. next song in playlist). If this method is not supported as indicated by the absence of the CHANGE_TO_NEXT_ITEM flag in PlayerCapabilities, this method does nothing.

Request

<EMPTY>

Pause

Pauses playback and retains position in media. If this method is not supported as indicated by the absence of the PAUSE flag in PlayerCapabilities, this method does nothing.

Request

<EMPTY>

Play

Plays media. If this method is not supported as indicated by the absence of the PLAY flag in PlayerCapabilities, this method does nothing.

Request

<EMPTY>

PrevItem

Changes media to the previous item. If this method is not supported as indicated by the absence of the CHANGE_TO_PREV_ITEM flag in PlayerCapabilities, this method does nothing.

Request

<EMPTY>

Seek

Seeks to a specific position in media. Implementations are free to enter an error state if the position is out of bounds. position is an offset from the beginning of the media. If this method is not supported as indicated by the absence of the SEEK flag in PlayerCapabilities, this method does nothing.

Request

Name	Type
`position`	`zx/Duration`

SetPlaybackRate

Sets the playback rate of the media. This will not change the playback mode. If this method is not supported as indicated by the absense of the SET_PLAYBACK_RATE flag in PlayerCapabilities, this method does nothing.

Request

Name	Type
`playback_rate`	`float32`

SetRepeatMode

Sets repeat mode to any of the supported repeat modes. Whether this method takes effect depends on the PlayerCapabilities and repeat_mode:

OFF is always supported.
GROUP requires the REPEAT_GROUPS capability, and is otherwise ignored.
SINGLE requires the REPEAT_SINGLE capability, and is otherwise ignored.

Request

Name	Type
`repeat_mode`	`RepeatMode`

SetShuffleMode

Sets shuffle mode. If this method is not supported as indicated by the absence of the SHUFFLE flag in PlayerCapabilities, this method does nothing.

Request

Name	Type
`shuffle_on`	`bool`

SkipForward

Skips forward in media by the player's default skip amount. If this method is not supported as indicated by the absence of the SKIP_FORWARD flag in PlayerCapabilities, this method does nothing.

Request

<EMPTY>

SkipReverse

Skips in reverse in media by the player's default skip amount. If this method is not supported as indicated by the absence of the SKIP_REVERSE flag in PlayerCapabilities, this method does nothing.

Request

<EMPTY>

Stop

Stops playback. The session should close.

Request

<EMPTY>

WatchInfoChange

Gets the net player info change using the hanging get pattern.

Request

<EMPTY>

Response

Name	Type
`player_info_delta`	`PlayerInfoDelta`

PlayerControl

Defined in fuchsia.media.sessions2/player.fidl

Controls for a media player. PlayerCapabilities expresses which of the methods in this protocol are supported by the player. Because capabilties are dynamic, and a client cannot always know what capabilities will be supported when the method call reaches the service, calling a method that is not supported is simply ignored. In general, clients should not expect methods to work unless the player indicates sustained support.

BindVolumeControl

Request

Name	Type
`volume_control_request`	`server_end:fuchsia.media.audio/VolumeControl`

NextItem

Request

<EMPTY>

Pause

Pauses playback and retains position in media. If this method is not supported as indicated by the absence of the PAUSE flag in PlayerCapabilities, this method does nothing.

Request

<EMPTY>

Play

Plays media. If this method is not supported as indicated by the absence of the PLAY flag in PlayerCapabilities, this method does nothing.

Request

<EMPTY>

PrevItem

Changes media to the previous item. If this method is not supported as indicated by the absence of the CHANGE_TO_PREV_ITEM flag in PlayerCapabilities, this method does nothing.

Request

<EMPTY>

Seek

Request

Name	Type
`position`	`zx/Duration`

SetPlaybackRate

Request

Name	Type
`playback_rate`	`float32`

SetRepeatMode

Sets repeat mode to any of the supported repeat modes. Whether this method takes effect depends on the PlayerCapabilities and repeat_mode:

OFF is always supported.
GROUP requires the REPEAT_GROUPS capability, and is otherwise ignored.
SINGLE requires the REPEAT_SINGLE capability, and is otherwise ignored.

Request

Name	Type
`repeat_mode`	`RepeatMode`

SetShuffleMode

Sets shuffle mode. If this method is not supported as indicated by the absence of the SHUFFLE flag in PlayerCapabilities, this method does nothing.

Request

Name	Type
`shuffle_on`	`bool`

SkipForward

Skips forward in media by the player's default skip amount. If this method is not supported as indicated by the absence of the SKIP_FORWARD flag in PlayerCapabilities, this method does nothing.

Request

<EMPTY>

SkipReverse

Request

<EMPTY>

Stop

Stops playback. The session should close.

Request

<EMPTY>

Publisher

Defined in fuchsia.media.sessions2/publisher.fidl

Publisher publishes media players so they may be discovered and controlled by clients who have permission to do so.

Publish

Request

Name	Type
`player`	`client_end:Player`
`registration`	`PlayerRegistration`

Response

Name	Type
`session_id`	`SessionId`

SessionControl

Defined in fuchsia.media.sessions2/discovery.fidl

Controls a media session and views its status.

The channel will close if the media session is stopped.

BindVolumeControl

Binds to the session's volume control for control and notifications.

Request

Name	Type
`volume_control_request`	`server_end:fuchsia.media.audio/VolumeControl`

NextItem

Changes media to the next item (e.g. next song in playlist).

Request

<EMPTY>

Pause

Pauses playback and retains position in media

Request

<EMPTY>

Play

Plays media.

Request

<EMPTY>

PrevItem

Changes media to the previous item.

Request

<EMPTY>

Seek

Seeks to a specific position in media. Implementations are free to enter an error state if the position is out of bounds. position is an offset from the beginning of the media.

Request

Name	Type
`position`	`zx/Duration`

SetPlaybackRate

Sets the playback rate of the media. This will not change the playback mode.

Request

Name	Type
`playback_rate`	`float32`

SetRepeatMode

Sets repeat mode to any of the supported repeat modes.

Request

Name	Type
`repeat_mode`	`RepeatMode`

SetShuffleMode

Sets shuffle mode.

Request

Name	Type
`shuffle_on`	`bool`

SkipForward

Skips forward in media by the player's default skip amount.

Request

<EMPTY>

SkipReverse

Skips in reverse in media by the player's default skip amount.

Request

<EMPTY>

Stop

Stops playback. The session should close.

Request

<EMPTY>

WatchStatus

Watches the session status. Leave a request hanging to receive a reply when the session status changes. The first request will be answered immediately with the current state.

Request

<EMPTY>

Response

Name	Type
`session_info_delta`	`SessionInfoDelta`

SessionObserver

Defined in fuchsia.media.sessions2/discovery.fidl

Views a media session's status.

The channel will close if the media session is stopped.

WatchStatus

Watches the session status. Leave a request hanging to receive a reply when the session status changes. The first request will be answered immediately with the current state.

Request

<EMPTY>

Response

Name	Type
`session_info_delta`	`SessionInfoDelta`

SessionsWatcher

Defined in fuchsia.media.sessions2/discovery.fidl

SessionsWatcher watches the collection of published sessions.

SessionRemoved

Called by the registry service when a session is removed from the registered collection.

SessionsWatcher must reply to acknlowledge receipt of the session removal. Delinquent watchers who do not reply will eventually be disconnected.

Request

Name	Type
`session_id`	`SessionId`

Response

<EMPTY>

SessionUpdated

Called by the registry service when a session is updated. On first connection, this will be called as many times as needed to communicate the state of the world.

SessionsWatcher must reply to acknowledge receipt of the session info delta. Delinquent watchers who do not reply will eventually be disconnected.

Request

Name	Type
`session_id`	`SessionId`
`session_info_delta`	`SessionInfoDelta`

Response

<EMPTY>

STRUCTS

ImageSizeVariant

Defined in fuchsia.media.sessions2/images.fidl

A variant of an image at a specific size.

Field	Type	Default
`url`	`fuchsia.url/Url`	No default
`width`	`uint32`	No default
`height`	`uint32`	No default

ENUMS

ContentType strict

Type: uint32

Defined in fuchsia.media.sessions2/player.fidl

The type of content playing back, which should be set to the largest applicable value.

Name	Value	Description
OTHER	`1`	Content does not qualify for any of the other values.
AUDIO	`2`	Audio-only content that does not qualify as music.
VIDEO	`3`	Video-only or audio-video content that does not qualify as a TV show or a movie.
MUSIC	`4`	Audio-only content generally recognized as music.
TV_SHOW	`5`	Audio-video content that is part of a television or streaming series.
MOVIE	`6`	Audio-video content consisting of a feature film.

Error strict

Type: uint32

Defined in fuchsia.media.sessions2/player.fidl

Name	Value	Description
OTHER	`1`

InterruptionBehavior strict

Type: uint32

Defined in fuchsia.media.sessions2/player.fidl

The behavior enforced on the player when it is interrupted, such as by an alarm.

Interruptions are detected using the player's usage.

By default the interruption behavior is NONE.

Name	Value	Description
NONE	`0`	Interruptions have no effect on the player and it may continue in spite of reduced audibility.
PAUSE	`1`	With this behavior, when playback is interrupted, the player will be paused until the interruption is over, so the user does not miss any content.

MediaImageType strict

Type: uint32

Defined in fuchsia.media.sessions2/images.fidl

Name	Value	Description
ARTWORK	`0`	Artwork for the playing media.
SOURCE_ICON	`1`	An icon for the source of the playing media (e.g. the player or streaming service).

PlayerState strict

Type: uint32

Defined in fuchsia.media.sessions2/player.fidl

State of a media player.

Name	Value	Description
IDLE	`0`	The initial state of a session if there is no associated media.
PLAYING	`1`	The player is playing.
PAUSED	`2`	The player is paused.
BUFFERING	`3`	The player would be playing, but is temporarily paused for buffering.
ERROR	`4`	The player cannot recover from this state and will close.

RepeatMode strict

Type: uint32

Defined in fuchsia.media.sessions2/player.fidl

Modes of repeating playback of the current media.

Name	Value	Description
OFF	`0`	No repeat.
GROUP	`1`	Repeat the relevant group of media (e.g. playlist).
SINGLE	`2`	Repeat the currently playing media.

TABLES

MediaImage

Defined in fuchsia.media.sessions2/images.fidl

An image for playing media.

Ordinal	Field	Type	Description
1	`image_type`	`MediaImageType`
2	`sizes`	`vector<ImageSizeVariant>:16`	Available variants of the image.

PlayerCapabilities

Defined in fuchsia.media.sessions2/player.fidl

Describes the capabilities of a player.

Ordinal	Field	Type	Description
1	`flags`	`PlayerCapabilityFlags`	Indicates which capabilities are supported by the player. See `PlayerControl` for details.

PlayerInfoDelta

Defined in fuchsia.media.sessions2/player.fidl

When emitted, fields that have changed should be set. The first emission to a new client should be a snapshot.

Ordinal	Field	Type	Description
1	`local`	`bool`	Whether the entry point for the media into our device network is the local machine; this should be true if this is the device streaming from a music service, but false or omitted if this machine is just receiving an audio stream to act as a speaker. If omitted, the value is unchanged. Initially, this value is `true`.
2	`player_status`	`PlayerStatus`	The status of the player. If omitted, all constituent values are unchanged. If a field within `PlayerStatus` is omitted, its value is unchanged. Initial values are indicated for each field in `player_status`.
3	`metadata`	`fuchsia.media/Metadata`	The metadata of the playing media. If omitted, the metadata is unchanged. Initially, there is no metadata.
4	`media_images`	`vector<MediaImage>:16`	The images associated with the playing media. If omitted, the media images are unchanged. An empty vector indicates that there are no media images, which is also the initial state.
5	`player_capabilities`	`PlayerCapabilities`	The capabilities of the player. If omitted, the capabilities are unchanged. Initially, the player is assumed to have no capabilities.
6	`interruption_behavior`	`InterruptionBehavior`	The behavior the player would like to engage in when interrupted by something, such as an alarm. If omitted, the behavior is unchanged. Initially, the value is `NONE`.

PlayerRegistration

Defined in fuchsia.media.sessions2/publisher.fidl

All information required by the media session registry service to register a player so that clients may observe its status and control it.

Ordinal	Field	Type	Description
1	`domain`	`Domain`	The domain on which the player exists. Unset if it is the native Fuchsia domain.
2	`usage`	`fuchsia.media/AudioRenderUsage`	The usage of the player's audio output. By default, this is assumed to be MEDIA.

PlayerStatus

Defined in fuchsia.media.sessions2/player.fidl

Status of a media player.

Ordinal	Field	Type	Description
1	`duration`	`zx/Duration`	Total duration of playing media. If this value is omitted, the duration is unknown, not applicable or unchanged. Initially, the duration is assumed to be unknown.
2	`player_state`	`PlayerState`	State of the player. If this field is omitted, the value is unchanged. Initially, the value is `IDLE`.
3	`timeline_function`	`fuchsia.media/TimelineFunction`	A playback function that describes the position and rate of play through the media as a function of `CLOCK_MONOTONIC`. If this field is omitted, the value is unchanged. Initially, `reference_delta` is 1 and the remaining constituent fields are 0.
4	`repeat_mode`	`RepeatMode`	Repeat mode of the player. If this field is omitted, the value is unchanged. Initially, the value is `NONE`.
5	`shuffle_on`	`bool`	Shuffle mode of the player. If this field is omitted, the value is unchanged. Initially, the value is false.
6	`content_type`	`ContentType`	The type of content playing back. If this field is omitted, the value is unchanged. Initially, the value is `OTHER`.
7	`error`	`Error`	An error the player may have encountered. This field is omitted unless there is an error. Once an error is indicated, it cannot be rescinded.
8	`is_live`	`bool`	Whether the playing media is live (such as television or a live stream). If this field is omitted, the value is unchanged. Initially, the value is false.

SessionInfoDelta

Defined in fuchsia.media.sessions2/discovery.fidl

SessionInfoDelta holds a description of a media session.

Ordinal	Field	Type	Description
1	`domain`	`Domain`	The domain on which the session takes place. A domain identifies a set of mutually compatible media targets and sessions; sessions on a domain may be played back on targets of the same domain. This field is always present.
2	`is_local`	`bool`	Whether the source of the media playback is on this device. This field is present only if known.
3	`is_locally_active`	`bool`	If this is `true`, the playback is taking place local to the device. Playing on the device speaker is local, playing on a remote speaker is not. This is only set when the session is playing back; a paused session is not active. This field is always present.
4	`player_status`	`PlayerStatus`	The status of the player. This field is always present.
5	`metadata`	`fuchsia.media/Metadata`	Metadata describing the media session. This field is always present.
6	`media_images`	`vector<MediaImage>`	Images associated with the media or its source. This field is always present.
7	`player_capabilities`	`PlayerCapabilities`	The capabilities the player of the media implements. This field is always present.

WatchOptions

Defined in fuchsia.media.sessions2/discovery.fidl

Options that specify which sessions are watched when watching the collection.

The watched set is the set of sessions which satisfies all options.

Ordinal	Field	Type	Description
1	`only_active`	`bool`	Watch only the active session. Watches all if not set.
2	`allowed_sessions`	`vector<SessionId>:1000`	Watch only sessions with these allowlisted ids. Watches all if not set.

BITS

PlayerCapabilityFlags strict

Type: uint32

Defined in fuchsia.media.sessions2/player.fidl

Name	Value	Description
PLAY	1	If set, the player can `Play()`.
PAUSE	4	If set, the player can `Pause()`.
SEEK	8	If set, the player can `Seek()`.
SKIP_FORWARD	16	If set, the player can `SkipForward()`.
SKIP_REVERSE	32	If set, the player can `SkipReverse()`.
SHUFFLE	64	If set, the player can shuffle media.
CHANGE_TO_NEXT_ITEM	128
CHANGE_TO_PREV_ITEM	256
HAS_GAIN_CONTROL	512	If set, the player can `BindGainControl()`.
REPEAT_GROUPS	1024	If set, the player can repeat groups.
REPEAT_SINGLE	2048	If set, the player can repeat single media items.
SET_PLAYBACK_RATE	4096	If set, the player can accept playback rate changes.

ALIASES

Name Value Description

Name	Value	Description
Domain	`string`[`1000`]	A domain identifies the ecosystem in which the session takes place. Domains should take the form of `domain://<unique name for protocol>.version` The `\|` symbol is reserved and should not be used in a domain string.
SessionId	`uint64`

Domain

string[1000]

A domain identifies the ecosystem in which the session takes place.

Domains should take the form of

`domain://<unique name for protocol>.version`

The | symbol is reserved and should not be used in a domain string.

SessionId uint64