| // Copyright 2019 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. |
| |
| library fuchsia.media; |
| |
| [Discoverable] |
| protocol AudioCore { |
| // Create an AudioRenderer which is grouped and handled as part of the |
| // AudioRenderUsage specified. An AudioRenderer will not be able to have |
| // its usage changed after creation. The AudioRenderUsage is used by |
| // AudioPolicy to dictate how streams interact with each other. |
| CreateAudioRenderer(request<AudioRenderer> audio_out_request); |
| |
| // Create an AudioCapturer which either captures from the current default |
| // audio input device, or loops-back from the current default audio output |
| // device based on value passed for the loopback flag. |
| // |
| // TODO(mpuryear): Get rid of the loopback flag ASAP. Routing decisions (and |
| // security surrounding routing decisions) should be much more sophisticated |
| // than this. This is just a placeholder until we have a design in place. |
| // Eventually, I suspect that all of this will move up into the audio policy |
| // manager and application clients will obtain AudioCapturers from and |
| // control through the policy manager. |
| CreateAudioCapturer(bool loopback, request<AudioCapturer> audio_in_request); |
| |
| // System Gain and Mute |
| // TODO(mpuryear): remove this systemwide setting once device-centric |
| // settings are plumbed into the system UI. Also, device-centric (and |
| // certainly systemwide settings) should be moved out of the |
| // accessible-to-all public audio interface and relocated to a more |
| // restrictive interface that is only accessible by clients with the |
| // appropriate privileges (such as system configuration API, or the |
| // governor of audio policy). |
| // |
| // Mirroring device-centric gain and mute stages, Fuchsia's systemwide Gain |
| // and Mute settings are fully independent. Changing the value of one does |
| // not change the value of the other. Both have the ability to silence a |
| // system (or a device, in the case of device Gain/Mute). If Mute is true, |
| // or if Gain is kMutedGain, the system is silenced regardless of the |
| // other. Similarly, one's value does not restrict the other's possible |
| // values in any way. |
| // |
| // Sets the system-wide gain in decibels. `db` values are clamped to the |
| // range -160db to 0db, inclusive. This setting is applied to all audio |
| // output devices. Audio input devices are unaffected. System Gain changes |
| // do not affect the System Mute state. |
| SetSystemGain(float32 gain_db); |
| |
| // Sets/clears the systemwide 'Mute' state for audio output devices. Audio |
| // input devices are unaffected. Changes to the System Mute state do not |
| // affect the value of System Gain. |
| SetSystemMute(bool muted); |
| |
| // Provides current values for the systemwide Gain and Mute. |
| // When a client connects to Audio, the system enqueues an action (to be |
| // executed once the system regains control) to send this newly-connected |
| // client a callback with the current systemwide Gain|Mute settings. |
| // Further, upon any change to the systemwide Gain|Mute values, the system |
| // will trigger all registered callbacks, notifying clients of the new |
| // values. |
| // |
| // Calls to SetSystemMute or SetSystemGain that do NOT result in a change to |
| // these values (e.g. calling SetSystemMute(false) when Mute is already |
| // false) will not cause the callbacks to be triggered. |
| // |
| // During and immediately following connecting to Audio, it is essential |
| // that clients keep in mind the fundamental single-threaded nature of FIDL. |
| // Specifically, if a newly-connected client registers a |
| // SystemGainMuteChanged callback before returning, that client will (once |
| // the system has subsequent opportunity) be notified via callback of the |
| // Gain|Mute settings at the time the connection was established. If |
| // however a newly-connected client returns from a FIDL message dispatch |
| // (returning control to the FIDL dispatcher), then that client |
| // subsequently registers this callback, the client has no way to learn the |
| // current Gain|Mute settings until they actually change. |
| -> SystemGainMuteChanged(float32 gain_db, bool muted); |
| |
| SetRoutingPolicy(AudioOutputRoutingPolicy policy); |
| |
| // By default, reading and writing device settings files is enabled. This |
| // method (which has impact across the entire audio subsystem) allows a test |
| // client to temporarily disable, then later enable, that reading/writing. |
| // TODO(mpuryear): Move this to the hub, instead of being a FIDL API. |
| EnableDeviceSettings(bool enabled); |
| |
| // Set the Usage gain applied to Renderers and Capturers. By default the |
| // gain for all render and capture usages is set to Unity(0.0db). |
| SetRenderUsageGain(AudioRenderUsage usage, float32 gain_db); |
| SetCaptureUsageGain(AudioCaptureUsage usage, float32 gain_db); |
| }; |
| |
| /// Usage annotating the purpose of the stream being used to render audio. |
| enum AudioRenderUsage { |
| /// Stream is intended to be used for ambient or background sound. Streams |
| /// that can be interrupted without consequence should use this. |
| BACKGROUND = 0; |
| |
| /// Stream is intended to be used for normal functionality. Streams that |
| /// are part of normal functionality should use this. |
| MEDIA = 1; |
| |
| /// Stream is intended to interrupt any ongoing function of the device. |
| /// Streams that are used for interruptions like notifications should use |
| /// this. |
| INTERRUPTION = 2; |
| |
| /// Stream is for interaction with a system agent. This should be used |
| /// in response to a user initiated trigger. |
| SYSTEM_AGENT = 3; |
| |
| /// Stream is intended to be used for some form of real time user to user |
| /// communication. Voice/Video chat should use this. |
| COMMUNICATION = 4; |
| }; |
| const uint8 RENDER_USAGE_COUNT = 5; |
| |
| /// Usages annotating the purpose of the stream being used to capture audio. |
| enum AudioCaptureUsage { |
| /// Stream is used to capture audio while in the background. These streams |
| /// may be active at any the time and are considered privileged. |
| /// Example: Listening for Hotwords |
| BACKGROUND = 0; |
| |
| /// Stream is intended to be used for normal capture functionality. Streams |
| /// that are used for audio capture while the stream creator is in the |
| /// foreground should use this. |
| /// Example: Voice Recorder |
| FOREGROUND = 1; |
| |
| /// Stream is for interaction with a system agent. This should only be used |
| /// once a user has signalled their intent to have the interaction with an |
| /// interested party. |
| /// Examples: Assistant, Siri, Alexa |
| SYSTEM_AGENT = 2; |
| |
| /// Stream is intended to be used for some form of real time user to user |
| /// communication. Voice/Video chat should use this. |
| COMMUNICATION = 3; |
| }; |
| const uint8 CAPTURE_USAGE_COUNT = 4; |
| |
| union Usage { |
| AudioRenderUsage render_usage; |
| AudioCaptureUsage capture_usage; |
| }; |
| |
| // A placeholder for various types of simple routing policies. This should be |
| // replaced when routing policy moves to a more centralized policy manager. |
| enum AudioOutputRoutingPolicy { |
| // AudioRenderers are always connected to all audio outputs which currently |
| // in the plugged state (eg; have a connector attached to them) |
| ALL_PLUGGED_OUTPUTS = 0; |
| |
| // AudioRenderers are only connected to the output stream which most |
| // recently entered the plugged state. AudioRenderers move around from |
| // output to output as streams are published/unpublished and become |
| // plugged/unplugged. |
| // |
| // This is the initial setting for audio output routing. |
| LAST_PLUGGED_OUTPUT = 1; |
| }; |