| // Copyright 2020 The Fuchsia Authors. All rights reserved. |
| // Use of this source code is governed by a BSD-style license that can be |
| // found in the LICENSE file. |
| |
| /// A library of protocols for routing media between devices. |
| /// |
| /// This library is based on "targets", which are devices or groups of devices |
| /// which can render media sessions. See `fuchsia.media.sessions2` for media |
| /// session details. |
| /// |
| /// Through the `Discovery` protocol, clients can discover what media targets |
| /// are available on the network, and select them to render media sessions. |
| library fuchsia.media.target; |
| |
| using fuchsia.media; |
| using fuchsia.media.audio; |
| using fuchsia.media.sessions2; |
| |
| /// A unique id for a target. |
| using Id = uint64; |
| |
| /// A user-visible name for a target to display in user interface or read |
| /// in voice interfaces. |
| using DisplayName = string:200; |
| |
| /// A protocol for discovering media targets. |
| [Discoverable] |
| protocol Discovery { |
| compose Group; |
| compose Selector; |
| |
| /// Watches for bindings of media sessions to targets. |
| /// |
| /// A media session is rendered on the target to which it is bound. |
| /// |
| /// First, existing bindings will be returned. Then, bindings added |
| /// and removed since connection will be returned as deltas on the |
| /// initial set. |
| GetNextSessionBinding() -> (SessionBindingWatchEvent event); |
| |
| /// Connects to a target by id. Drops the given channel if no such |
| /// target exists. |
| ConnectToTarget(Id target_id, request<Target> target_request); |
| }; |
| |
| /// A binding between a session and a target, indicating the media session |
| /// is rendered on the target. |
| struct SessionBinding { |
| fuchsia.media.sessions2.SessionId session_id; |
| Id target_id; |
| }; |
| |
| union SessionBindingWatchEvent { |
| /// An already existing binding at the time of connection. |
| 1: SessionBinding existing; |
| /// Indicates the full set of bindings from the time of connection have |
| /// been enumerated. No more `existing` events will be received. |
| 2: Void idle; |
| /// A new binding added since connection. |
| 3: SessionBinding added; |
| /// A binding removed. |
| 4: SessionBinding removed; |
| }; |
| |
| /// A target is a device or group of devices on which media can be rendered, |
| /// such as a speaker which renders audio. |
| protocol Target { |
| compose GroupEditor; |
| compose Group; |
| compose VolumeControl; |
| }; |
| |
| struct TargetChange { |
| Id new_target_id; |
| }; |
| |
| /// A protocol for adding and removing members of a group target. |
| protocol GroupEditor { |
| /// Adds a target to this group target. |
| /// |
| /// If the added target is a group of devices, all the devices in that group |
| /// are added to this group. A group itself cannot be a member of a group. |
| /// |
| /// Returns the id of the new target if a new group was created to fulfill this |
| /// request. |
| AddTarget(Id target_id) -> (TargetChange? target_change) error Error; |
| |
| /// Removes a target from this group. Returns the id of the new target |
| /// if a new group was created to fulfill this request. |
| RemoveTarget(Id target_id) -> (TargetChange? target_change) error Error; |
| }; |
| |
| /// A protocol for watching the members of a group. |
| protocol Group { |
| /// Watches for changes to the set of registered targets. Leave a request |
| /// hanging to get replies when changes occur. New clients will be caught |
| /// up with the state of the world. |
| /// |
| /// First, existing targets will be returned. Then, targets added and removed |
| /// since connection will be returned as deltas on the initial set. |
| GetNextTarget() -> (TargetWatchEvent target_watch_event); |
| }; |
| |
| struct Void { |
| }; |
| |
| union TargetWatchEvent { |
| /// An already existing target at the time of connection. |
| 1: Description existing; |
| /// Indicates the full set of targets from the time of connection have |
| /// been enumerated. No more `existing` events will be received. |
| 2: Void idle; |
| /// A new target added since connection. |
| 3: Description added; |
| /// A target’s description was updated. |
| 4: Description updated; |
| /// A target removed. |
| 5: Id removed; |
| }; |
| |
| /// A protocol to control the volume of target. |
| protocol VolumeControl { |
| /// Binds to the target's volume control. If this target is a group, |
| /// all member volumes are influenced. These settings persist |
| /// for the lifetime of the target. |
| BindVolumeControl(request<fuchsia.media.audio.VolumeControl> volume_control_request); |
| |
| /// Binds to the target's volume control as a member of the given group. |
| /// The request channel is dropped if the target is not a member of the group. |
| /// |
| /// This volume control influences the volume of this target only when it is |
| /// participating as a member of the group. This is used to adjust the balance |
| /// of volume among members of a group. These settings persist for the lifetime |
| /// of the target |
| BindMemberVolumeControl( |
| Id group, |
| request<fuchsia.media.audio.VolumeControl> volume_control_request); |
| }; |
| |
| /// A description of a target. |
| table Description { |
| /// Identifies the target. |
| 1: Id target_id; |
| /// Enumerates of the interoperability features the device supports. |
| 2: CapabilityFlags capability_flags; |
| 3: DisplayName display_name; |
| 4: fuchsia.media.Metadata metadata; |
| }; |
| |
| /// Capabilities of the target. |
| bits CapabilityFlags : uint64 { |
| /// Indicates the target can receive a transfer of a |
| /// media session from another target. |
| TRANSFER_TO = 0x01; |
| /// Indicates the target can transfer a media session |
| /// to another target. |
| TRANSFER_FROM = 0x02; |
| /// Indicates the target can participate in rendering |
| /// media with other devices. |
| MULTI_TARGET_PLAYBACK = 0x04; |
| /// Indicates the target can render video. |
| VIDEO = 0x08; |
| }; |
| |
| /// A protocol for selecting a media target. Commands on this protocol can |
| /// change the target on which a media session is rendered. |
| protocol Selector { |
| /// Renders the media session specified by `session_id` on the target |
| /// specified by `target_id`. |
| BindTarget( |
| fuchsia.media.sessions2.SessionId session_id, |
| Id target_id) -> () error Error; |
| |
| /// Renders the media session specified by `session_id` on the set of |
| /// targets specified by `target_ids`. |
| /// |
| /// This may create a new group target which contains all the specified |
| /// targets as members, if one does not exist. The group target may be |
| /// temporary, only existing for the lifetime of playback, and not |
| /// discoverable through `Discovery`. |
| BindGroupTarget( |
| fuchsia.media.sessions2.SessionId session_id, |
| vector<Id>:100 target_ids |
| ) -> (Id target_id) error Error; |
| }; |
| |
| enum Error { |
| NOT_A_GROUP = 0; |
| UNKNOWN_ON_DOMAIN = 1; |
| CANNOT_BE_GROUPED = 2; |
| NOT_MEMBER_OF_GROUP = 3; |
| TRANSFER_FROM_TARGET_UNSUPPORTED = 4; |
| TRANSFER_TO_TARGET_UNSUPPORTED = 5; |
| MULTI_TARGET_PLAYBACK_UNSUPPORTED = 6; |
| }; |