third_party/fuchsia-sdk/fidl/fuchsia.media/audio_core.fidl - fuchsia-benchmarks - Git at Google

 // 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;
 };
	// 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;
	};