blob: 163debf5650d599e74618d22bfdfc7aeb3751e07 [file] [log] [blame] [view]
<link rel="stylesheet" href="../style.css" />
[TOC]
# fuchsia.media.audio
<p><b>Added:7</b></p>
## **PROTOCOLS**
## EffectsController {#EffectsController}
*Defined in [fuchsia.media.audio/effects_controller.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/effects_controller.fidl;l=14)*
### UpdateEffect {#EffectsController.UpdateEffect}
<p>Sends the <code>config</code> message to an audio effect named <code>effect_name</code>. If the
server closes the <code>EffectsController</code> connection for any reason, that
indicates that the effects have been reset and any state associated with
previous <code>UpdateEffect</code> messages have been lost. Clients who wish to re-apply
state should respond by reconnecting and resending any needed <code>UpdateEffect</code>
messages. If a client closes the connection, no state will be lost but the
client will also be unable to determine if and when any state associated with
previous messages have been lost.</p>
<p>Returns success (empty response) if the message was accepted by an
effect named <code>effect_name</code>.</p>
<p>Returns <code>UpdateEffectError.INVALID_CONFIG</code> if an effect with the name
<code>effect_name</code> was found, but the <code>config</code> message was rejected.</p>
<p>Returns <code>UpdateEffectError.NOT_FOUND</code> if no effect with name <code>effect_name</code>
could be located.</p>
#### Request {#EffectsController.UpdateEffect_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>effect_name</code></td>
<td>
<code>string[128]</code>
</td>
</tr>
<tr>
<td><code>config</code></td>
<td>
<code>string</code>
</td>
</tr>
</table>
#### Response {#EffectsController.UpdateEffect_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>result</code></td>
<td>
<code><a class='link' href='#EffectsController_UpdateEffect_Result'>EffectsController_UpdateEffect_Result</a></code>
</td>
</tr>
</table>
## GainControl {#GainControl}
*Defined in [fuchsia.media.audio/gain_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/gain_control.fidl;l=16)*
<p>Enables control and monitoring of audio gain. This interface is typically
a tear-off of other interfaces. For example, <code>fuchsia.media.audio.Renderer</code>
has a <code>BindGainControl</code> method that binds to a gain control that controls
gain for the renderer.</p>
### OnGainMuteChanged {#GainControl.OnGainMuteChanged}
<p>Notifies the client of changes in the current gain/mute values.</p>
#### Response {#GainControl.OnGainMuteChanged_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>gain_db</code></td>
<td>
<code>float32</code>
</td>
</tr>
<tr>
<td><code>muted</code></td>
<td>
<code>bool</code>
</td>
</tr>
</table>
### SetGain {#GainControl.SetGain}
<p>Sets the gain in decibels.</p>
#### Request {#GainControl.SetGain_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>gain_db</code></td>
<td>
<code>float32</code>
</td>
</tr>
</table>
### SetGainWithRamp {#GainControl.SetGainWithRamp}
<p>Smoothly changes gain from its current value to specified value, over the
specified duration (in milliseconds). If 'duration_ns' is 0, gain changes
immediately. Otherwise, gain changes only while the stream is running.</p>
<p>Any active or pending ramp is cancelled by subsequent call to SetGain.</p>
<p>There can be at most 1 active ramp at any time. Any active or pending
ramp is replaced by a later call to SetGainWithRamp (even if duration is
0). In this case gain would ramps directly from its most recent
(mid-ramp) value to the newly-specified one, over the new duration,
using the new easing.</p>
<p>Usage example (using time in seconds):
Time 0
SetGainWithRamp(<code>MUTED_GAIN_DB</code>, 0, SCALE_LINEAR) // Ramp 1
SetGainWithRamp(0.0f, <code>ZX_SEC</code>(4), SCALE_LINEAR) // Ramp 2
Time 3
PlayNoReply(kNoTimestamp, any_media_time)
Time 4
PauseNoReply()
Time 7
PlayNoReply(kNoTimestamp, any_media_time)
Time 8
SetGainWithRamp(<code>MUTED_GAIN_DB</code>, ZX_SEC(1), SCALE_LINEAR) // Ramp 3</p>
<p>Time 0: Ramp 1 completes immediately, changing the gain to <code>MUTED_GAIN_DB</code>.
Ramp 2 is pending, since we are not in playback.
Time 3, Ramp 2 begins ramping from <code>MUTED_GAIN_DB</code> to 0 dB
(scale 0.0=&gt;1.0).
Time 4: Ramp 2 pauses (3s remain). Per <code>SCALE_LINEAR</code>, scale is approx.
0.25.
Time 7: Ramp 2 resumes from most recent value toward the target.
Time 8: Ramp 3 replaces Ramp 2 and starts from current scale
(approx 0.5).
Time 9: Ramp 3 completes; current scale value is now 0.0 (<code>MUTED_GAIN_DB</code>).</p>
#### Request {#GainControl.SetGainWithRamp_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>gain_db</code></td>
<td>
<code>float32</code>
</td>
</tr>
<tr>
<td><code>duration</code></td>
<td>
<code><a class='link' href='../zx/'>zx</a>/<a class='link' href='../zx/#duration'>duration</a></code>
</td>
</tr>
<tr>
<td><code>rampType</code></td>
<td>
<code><a class='link' href='#RampType'>RampType</a></code>
</td>
</tr>
</table>
### SetMute {#GainControl.SetMute}
<p>Sets the mute value. Ramping and mute are fully independent, although
they both affect the scaling that is applied.</p>
#### Request {#GainControl.SetMute_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>muted</code></td>
<td>
<code>bool</code>
</td>
</tr>
</table>
## VolumeControl {#VolumeControl}
*Defined in [fuchsia.media.audio/volume_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/volume_control.fidl;l=13)*
<p>A protocol for controlling volume.</p>
### OnVolumeMuteChanged {#VolumeControl.OnVolumeMuteChanged}
<p>Emitted when the volume or mute state of the audio element changes.</p>
#### Response {#VolumeControl.OnVolumeMuteChanged_Response}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>new_volume</code></td>
<td>
<code>float32</code>
</td>
</tr>
<tr>
<td><code>new_muted</code></td>
<td>
<code>bool</code>
</td>
</tr>
</table>
### SetMute {#VolumeControl.SetMute}
<p>Sets whether the controlled element is muted. Mute is not the same
as setting volume to 0.0; volume will persist for the duration of
a mute. If volume was 0.5 before mute, volume will resume at 0.5
following unmute.</p>
#### Request {#VolumeControl.SetMute_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>mute</code></td>
<td>
<code>bool</code>
</td>
</tr>
</table>
### SetVolume {#VolumeControl.SetVolume}
<p>Sets the volume of the audio element to the given value in
[0.0, 1.0]. If the value is provided is outside of [0.0, 1.0],
the value is clamped before application.</p>
#### Request {#VolumeControl.SetVolume_Request}
<table>
<tr><th>Name</th><th>Type</th></tr>
<tr>
<td><code>volume</code></td>
<td>
<code>float32</code>
</td>
</tr>
</table>
## **STRUCTS**
### EffectsController_UpdateEffect_Response {#EffectsController_UpdateEffect_Response data-text="EffectsController_UpdateEffect_Response"}
*Defined in [fuchsia.media.audio/effects_controller.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/effects_controller.fidl;l=35)*
&lt;EMPTY&gt;
## **ENUMS**
### RampType [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#RampType data-text="RampType"}
Type: <code>uint16</code>
*Defined in [fuchsia.media.audio/gain_control.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/gain_control.fidl;l=90)*
<p>Enumerates gain control ramp types.</p>
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="RampType.SCALE_LINEAR">
<td><h3 id="RampType.SCALE_LINEAR" class="add-link hide-from-toc">SCALE_LINEAR</h3></td>
<td><code>1</code></td>
<td><p>Amplitude scale changes at a fixed rate across the ramp duration.</p>
</td>
</tr>
</table>
### UpdateEffectError [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#UpdateEffectError data-text="UpdateEffectError"}
Type: <code>uint32</code>
*Defined in [fuchsia.media.audio/effects_controller.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/effects_controller.fidl;l=6)*
<table>
<tr><th>Name</th><th>Value</th><th>Description</th></tr>
<tr id="UpdateEffectError.INVALID_CONFIG">
<td><h3 id="UpdateEffectError.INVALID_CONFIG" class="add-link hide-from-toc">INVALID_CONFIG</h3></td>
<td><code>1</code></td>
<td></td>
</tr>
<tr id="UpdateEffectError.NOT_FOUND">
<td><h3 id="UpdateEffectError.NOT_FOUND" class="add-link hide-from-toc">NOT_FOUND</h3></td>
<td><code>2</code></td>
<td></td>
</tr>
</table>
## **UNIONS**
### EffectsController_UpdateEffect_Result [strict](/fuchsia-src/reference/fidl/language/language.md#strict-vs-flexible){:.fidl-attribute} {#EffectsController_UpdateEffect_Result data-text="EffectsController_UpdateEffect_Result"}
*Defined in [fuchsia.media.audio/effects_controller.fidl](https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/effects_controller.fidl;l=35)*
<table>
<tr><th>Ordinal</th><th>Variant</th><th>Type</th><th>Description</th></tr>
<tr id="EffectsController_UpdateEffect_Result.response">
<td><h3 id="EffectsController_UpdateEffect_Result.response" class="add-link hide-from-toc">1</h3></td>
<td><code>response</code></td>
<td>
<code><a class='link' href='#EffectsController_UpdateEffect_Response'>EffectsController_UpdateEffect_Response</a></code>
</td>
<td></td>
</tr>
<tr id="EffectsController_UpdateEffect_Result.err">
<td><h3 id="EffectsController_UpdateEffect_Result.err" class="add-link hide-from-toc">2</h3></td>
<td><code>err</code></td>
<td>
<code><a class='link' href='#UpdateEffectError'>UpdateEffectError</a></code>
</td>
<td></td>
</tr>
</table>
## **CONSTANTS**
<table>
<tr><th>Name</th><th>Value</th><th>Type</th><th>Description</th></tr>
<tr id="MAX_EFFECT_NAME_LENGTH">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/effects_controller.fidl;l=11">MAX_EFFECT_NAME_LENGTH</a></td>
<td>
<code>128</code>
</td>
<td><code>uint32</code></td>
<td></td>
</tr>
<tr id="MAX_GAIN_DB">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/gain_control.fidl;l=87">MAX_GAIN_DB</a></td>
<td>
<code>24</code>
</td>
<td><code>float32</code></td>
<td><p>Maximum permitted gain value.</p>
</td>
</tr>
<tr id="MAX_VOLUME">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/volume_control.fidl;l=7">MAX_VOLUME</a></td>
<td>
<code>1</code>
</td>
<td><code>float32</code></td>
<td><p>The volume value representing the maximum loudness.</p>
</td>
</tr>
<tr id="MIN_VOLUME">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/volume_control.fidl;l=10">MIN_VOLUME</a></td>
<td>
<code>0</code>
</td>
<td><code>float32</code></td>
<td><p>The volume value representing silence.</p>
</td>
</tr>
<tr id="MUTED_GAIN_DB">
<td><a href="https://cs.opensource.google/fuchsia/fuchsia/+/main:sdk/fidl/fuchsia.media.audio/gain_control.fidl;l=84">MUTED_GAIN_DB</a></td>
<td>
<code>-160</code>
</td>
<td><code>float32</code></td>
<td><p>Gain value producing silence. Gain values less than this value are permitted,
but produce the same effect as this value.</p>
</td>
</tr>
</table>