blob: 25197778829d1c06300b56c4abd0387196e347f9 [file] [log] [blame]
// 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;
using fuchsia.media.audio;
/// Usage annotating the purpose of the stream being used to render audio.
/// An AudioRenderer's usage cannot be changed after creation. The
/// AudioRenderUsage is used by audio policy to dictate how audio streams
/// interact with each other.
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. The
/// AudioCaptureUsage is used by audio policy to dictate how audio streams
/// interact with each other.
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;
/// The behaviors applied to streams when multiple are active.
enum Behavior {
/// Mix the streams.
NONE = 0;
/// Apply a gain to duck the volume of one of the streams. (-14.0db)
DUCK = 1;
/// Apply a gain to mute one of the streams. (-160.0db)
MUTE = 2;
};
union Usage {
1: AudioRenderUsage render_usage;
2: AudioCaptureUsage capture_usage;
};
[Discoverable]
protocol AudioCore {
/// Create an AudioRenderer which outputs audio to the default device.
CreateAudioRenderer(request<AudioRenderer> audio_out_request);
/// Create a new Audio Capturer according to the given requirements.
///
/// `pcm_stream_type` sets the stream type of the stream to be delivered.
/// It causes the source material to be reformatted/resampled if needed
/// in order to produce the requested stream type.
///
/// `usage` is used by Fuchsia to make decisions about user experience.
/// See `AudioCaptureUsage` for more details.
///
/// `configuration` must be initialized to a variant, or no capturer
/// can be created.
///
/// TODO(45240): Implement
[Transitional]
CreateAudioCapturerWithConfiguration(
AudioStreamType stream_type,
AudioCapturerConfiguration configuration,
request<AudioCapturer> audio_capturer_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(34915): Get rid of the loopback flag ASAP. Routing decisions (and
// security surrounding routing decisions) should be more sophisticated.
// This is a placeholder until we have a design in place. Eventually, this
// should move up to an audio policy layer, where application clients obtain
// and control AudioCapturers.
CreateAudioCapturer(bool loopback, request<AudioCapturer> audio_in_request);
// TODO(34948): remove these systemwide settings, once device-centric
// settings are plumbed into the system UI. Also, device-centric and
// systemwide settings should be moved out of this 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).
/// System Gain and Mute
///
/// Fuchsia clients control the volume of individual audio streams via the
/// fuchsia.media.audio.GainControl protocol. System Gain and Mute affect
/// all audio output, and are controlled with methods that use the same
/// concepts as GainControl, namely: independent gain and mute, with change
/// notifications. Setting System Mute to true leads to the same outcome as
/// setting System Gain to MUTED_GAIN_DB: all audio output across the system
/// is silenced.
///
/// Sets the systemwide gain in decibels. `gain_db` values are clamped to
/// the range -160 db to 0 db, inclusive. This setting is applied to all
/// audio output devices. Audio input devices are unaffected.
/// Does not affect System Mute.
[Transitional, Deprecated]
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.
[Transitional, Deprecated]
SetSystemMute(bool muted);
/// Provides current values for systemwide Gain and Mute. When a client
/// connects to AudioCore, the system immediately sends that client a
/// SystemGainMuteChanged event with the current system Gain|Mute settings.
/// Subsequent events will be sent when these Gain|Mute values change.
[Transitional, Deprecated]
-> SystemGainMuteChanged(float32 gain_db, bool muted);
// 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(13578): Move this to the hub, instead of FIDL API. Alternately,
// simply remove; going forward, HermeticTestEnvironment accepts a
// parameter that disables device settings writeback during testing.
EnableDeviceSettings(bool enabled);
/// Set the Usage gain applied to Renderers. By default, the gain for all
/// render usages is set to Unity (0 db).
SetRenderUsageGain(AudioRenderUsage usage, float32 gain_db);
/// Set the Usage gain applied to Capturers. By default, the gain for all
/// capture usages is set to Unity (0 db).
SetCaptureUsageGain(AudioCaptureUsage usage, float32 gain_db);
/// Binds to a volume control protocol for the given usage.
BindUsageVolumeControl(Usage usage, request<fuchsia.media.audio.VolumeControl> volume_control);
/// SetInteraction allows changing how audio_core handles interactions of multiple active
/// streams simultaneously. If streams of Usage `active` are processing audio, and streams of
/// Usage `affected` are as well, the Behavior specified will be applied to the streams of Usage
/// `affected`.
SetInteraction(Usage active, Usage affected, Behavior behavior);
/// Re-initializes the set of rules that are currently governing the interaction of streams in
/// audio_core. The default behavior is 'NONE'.
ResetInteractions();
/// Re-loads the platform policy configuration. Falls back to a default config if the platform
/// does not provide a config.
LoadDefaults();
};
// Placeholder for routing policies.
// TODO(34922): Replace, when routing is handled by a central 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 default initial setting for audio output routing.
LAST_PLUGGED_OUTPUT = 1;
};