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

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

NameType
session_id SessionId
session_control_request server_end<SessionControl>

WatchSessions

Connects a session watcher configured with the given options.

Request

NameType
watch_options WatchOptions
session_watcher 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

NameType
session_id SessionId
session_request server_end<SessionObserver>

WatchSessions

Connects a session watcher configured with the given options.

Request

NameType
watch_options WatchOptions
sessions_watcher 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

NameType
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

NameType
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

NameType
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

NameType
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

NameType
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

NameType
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

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

NameType
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

NameType
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

NameType
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

NameType
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

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

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

NameType
player Player
registration PlayerRegistration

Response

NameType
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

NameType
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

NameType
position zx/Duration

SetPlaybackRate

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

Request

NameType
playback_rate float32

SetRepeatMode

Sets repeat mode to any of the supported repeat modes.

Request

NameType
repeat_mode RepeatMode

SetShuffleMode

Sets shuffle mode.

Request

NameType
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

NameType
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

NameType
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

NameType
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

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

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

NameValueDescription
1

Content does not qualify for any of the other values.

2

Audio-only content that does not qualify as music.

3

Video-only or audio-video content that does not qualify as a TV show or a movie.

4

Audio-only content generally recognized as music.

5

Audio-video content that is part of a television or streaming series.

6

Audio-video content consisting of a feature film.

Error strict

Type: uint32

Defined in fuchsia.media.sessions2/player.fidl

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

NameValueDescription
0

Interruptions have no effect on the player and it may continue in spite of reduced audibility.

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

NameValueDescription
0

Artwork for the playing media.

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.

NameValueDescription
0

The initial state of a session if there is no associated media.

1

The player is playing.

2

The player is paused.

3

The player would be playing, but is temporarily paused for buffering.

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.

NameValueDescription
0

No repeat.

1

Repeat the relevant group of media (e.g. playlist).

2

Repeat the currently playing media.

TABLES

MediaImage

Defined in fuchsia.media.sessions2/images.fidl

An image for playing media.

OrdinalFieldTypeDescription
image_type MediaImageType
sizes vector<ImageSizeVariant>:16

Available variants of the image.

PlayerCapabilities

Defined in fuchsia.media.sessions2/player.fidl

Describes the capabilities of a player.

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

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

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.

metadata fuchsia.media/Metadata

The metadata of the playing media.

If omitted, the metadata is unchanged. Initially, there is no metadata.

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.

player_capabilities PlayerCapabilities

The capabilities of the player.

If omitted, the capabilities are unchanged. Initially, the player is assumed to have no capabilities.

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.

OrdinalFieldTypeDescription
domain Domain

The domain on which the player exists. Unset if it is the native Fuchsia domain.

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.

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

player_state PlayerState

State of the player.

If this field is omitted, the value is unchanged. Initially, the value is IDLE.

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.

repeat_mode RepeatMode

Repeat mode of the player.

If this field is omitted, the value is unchanged. Initially, the value is NONE.

shuffle_on bool

Shuffle mode of the player.

If this field is omitted, the value is unchanged. Initially, the value is false.

content_type ContentType

The type of content playing back.

If this field is omitted, the value is unchanged. Initially, the value is OTHER.

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.

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.

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

is_local bool

Whether the source of the media playback is on this device.

This field is present only if known.

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.

player_status PlayerStatus

The status of the player.

This field is always present.

metadata fuchsia.media/Metadata

Metadata describing the media session.

This field is always present.

media_images vector<MediaImage>

Images associated with the media or its source.

This field is always present.

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.

OrdinalFieldTypeDescription
only_active bool

Watch only the active session. Watches all if not set.

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

NameValueDescription
1

If set, the player can Play().

4

If set, the player can Pause().

8

If set, the player can Seek().

16

If set, the player can SkipForward().

32

If set, the player can SkipReverse().

64

If set, the player can shuffle media.

128
256
512

If set, the player can BindGainControl().

1024

If set, the player can repeat groups.

2048

If set, the player can repeat single media items.

4096

If set, the player can accept playback rate changes.

ALIASES

NameValueDescription
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