sdk/fidl/fuchsia.media/audio_core.fidl - fuchsia - 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.
 type AudioRenderUsage = strict enum {
     /// 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 RENDER_USAGE_COUNT uint8 = 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.
 type AudioCaptureUsage = strict enum {
     /// 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 CAPTURE_USAGE_COUNT uint8 = 4;

 /// The behaviors applied to streams when multiple are active.
 type Behavior = strict enum {
     /// 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;
 };

 type Usage = strict union {
     1: render_usage AudioRenderUsage;
     2: capture_usage AudioCaptureUsage;
 };

 @discoverable
 closed protocol AudioCore {
     /// Creates an AudioRenderer which outputs audio to the default device.
     strict CreateAudioRenderer(resource struct {
         audio_out_request server_end:AudioRenderer;
     });

     /// Creates an AudioCapturer 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.
     ///
     strict CreateAudioCapturerWithConfiguration(resource struct {
         stream_type AudioStreamType;
         configuration AudioCapturerConfiguration;
         audio_capturer_request server_end:AudioCapturer;
     });

     /// Creates 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(https://fxbug.dev/42110275): 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.
     strict CreateAudioCapturer(resource struct {
         loopback bool;
         audio_in_request server_end:AudioCapturer;
     });

     // TODO(https://fxbug.dev/42110311): 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.
     @available(removed=15)
     strict SetSystemGain(struct {
         gain_db float32;
     });

     /// 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.
     @available(removed=15)
     strict SetSystemMute(struct {
         muted bool;
     });

     /// 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.
     @available(removed=15)
     strict -> SystemGainMuteChanged(struct {
         gain_db float32;
         muted bool;
     });

     // 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(https://fxbug.dev/42085388): 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.
     @deprecated
     strict EnableDeviceSettings(struct {
         enabled bool;
     });

     /// Sets the Usage gain applied to Renderers. By default, the gain for all
     /// render usages is set to Unity (0 db).
     strict SetRenderUsageGain(struct {
         usage AudioRenderUsage;
         gain_db float32;
     });

     /// Sets the Usage gain applied to Capturers. By default, the gain for all
     /// capture usages is set to Unity (0 db).
     strict SetCaptureUsageGain(struct {
         usage AudioCaptureUsage;
         gain_db float32;
     });

     /// Binds to a volume control protocol for the given usage.
     strict BindUsageVolumeControl(resource struct {
         usage Usage;
         volume_control server_end:fuchsia.media.audio.VolumeControl;
     });

     /// Queries the volume percentage [0, 1] that maps to a `gain_db` value for a particular
     /// `usage`. This is the same mapping as used by the VolumeControl from
     /// `BindUsageVolumeControl`.
     strict GetVolumeFromDb(struct {
         usage Usage;
         gain_db float32;
     }) -> (struct {
         volume float32;
     });

     /// Queries the decibel value that maps to a volume percentage [0, 1] for a particular `usage`.
     /// This is the same mapping as used by the VolumeControl from `BindUsageVolumeControl`.
     strict GetDbFromVolume(struct {
         usage Usage;
         volume float32;
     }) -> (struct {
         gain_db float32;
     });

     /// Sets 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`.
     strict SetInteraction(struct {
         active Usage;
         affected Usage;
         behavior Behavior;
     });

     /// Re-initializes the set of rules that are currently governing the interaction of streams in
     /// audio_core.  The default behavior is 'NONE'.
     strict ResetInteractions();

     /// Re-loads the platform policy configuration.  Falls back to a default config if the platform
     /// does not provide a config.
     strict LoadDefaults();
 };

 // Placeholder for routing policies.
 // TODO(https://fxbug.dev/42110283): Replace, when routing is handled by a central policy manager.
 type AudioOutputRoutingPolicy = strict enum {
     // 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.
	type AudioRenderUsage = strict enum {
	/// 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 RENDER_USAGE_COUNT uint8 = 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.
	type AudioCaptureUsage = strict enum {
	/// 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 CAPTURE_USAGE_COUNT uint8 = 4;

	/// The behaviors applied to streams when multiple are active.
	type Behavior = strict enum {
	/// 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;
	};

	type Usage = strict union {
	1: render_usage AudioRenderUsage;
	2: capture_usage AudioCaptureUsage;
	};

	@discoverable
	closed protocol AudioCore {
	/// Creates an AudioRenderer which outputs audio to the default device.
	strict CreateAudioRenderer(resource struct {
	audio_out_request server_end:AudioRenderer;
	});

	/// Creates an AudioCapturer 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.
	///
	strict CreateAudioCapturerWithConfiguration(resource struct {
	stream_type AudioStreamType;
	configuration AudioCapturerConfiguration;
	audio_capturer_request server_end:AudioCapturer;
	});

	/// Creates 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(https://fxbug.dev/42110275): 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.
	strict CreateAudioCapturer(resource struct {
	loopback bool;
	audio_in_request server_end:AudioCapturer;
	});

	// TODO(https://fxbug.dev/42110311): 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.
	@available(removed=15)
	strict SetSystemGain(struct {
	gain_db float32;
	});

	/// 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.
	@available(removed=15)
	strict SetSystemMute(struct {
	muted bool;
	});

	/// 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.
	@available(removed=15)
	strict -> SystemGainMuteChanged(struct {
	gain_db float32;
	muted bool;
	});

	// 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(https://fxbug.dev/42085388): 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.
	@deprecated
	strict EnableDeviceSettings(struct {
	enabled bool;
	});

	/// Sets the Usage gain applied to Renderers. By default, the gain for all
	/// render usages is set to Unity (0 db).
	strict SetRenderUsageGain(struct {
	usage AudioRenderUsage;
	gain_db float32;
	});

	/// Sets the Usage gain applied to Capturers. By default, the gain for all
	/// capture usages is set to Unity (0 db).
	strict SetCaptureUsageGain(struct {
	usage AudioCaptureUsage;
	gain_db float32;
	});

	/// Binds to a volume control protocol for the given usage.
	strict BindUsageVolumeControl(resource struct {
	usage Usage;
	volume_control server_end:fuchsia.media.audio.VolumeControl;
	});

	/// Queries the volume percentage [0, 1] that maps to a `gain_db` value for a particular
	/// `usage`. This is the same mapping as used by the VolumeControl from
	/// `BindUsageVolumeControl`.
	strict GetVolumeFromDb(struct {
	usage Usage;
	gain_db float32;
	}) -> (struct {
	volume float32;
	});

	/// Queries the decibel value that maps to a volume percentage [0, 1] for a particular `usage`.
	/// This is the same mapping as used by the VolumeControl from `BindUsageVolumeControl`.
	strict GetDbFromVolume(struct {
	usage Usage;
	volume float32;
	}) -> (struct {
	gain_db float32;
	});

	/// Sets 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`.
	strict SetInteraction(struct {
	active Usage;
	affected Usage;
	behavior Behavior;
	});

	/// Re-initializes the set of rules that are currently governing the interaction of streams in
	/// audio_core. The default behavior is 'NONE'.
	strict ResetInteractions();

	/// Re-loads the platform policy configuration. Falls back to a default config if the platform
	/// does not provide a config.
	strict LoadDefaults();
	};

	// Placeholder for routing policies.
	// TODO(https://fxbug.dev/42110283): Replace, when routing is handled by a central policy manager.
	type AudioOutputRoutingPolicy = strict enum {
	// 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;
	};