| // Copyright 2018 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.audio; |
| |
| enum AudioRamp : uint16 { |
| // Scale amplitude changes evenly ("straight-line") across a ramp duration. |
| SCALE_LINEAR = 1; |
| |
| // Additional ramp shapes (easings) may be added in the future, including |
| // logarithmic (i.e. linear wrt dB), cubic (in/out/inout) or others. |
| }; |
| |
| protocol GainControl { |
| // Sets the gain in decibels. |
| SetGain(float32 gain_db); |
| |
| // Smoothly change 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. |
| // |
| // Any active or pending ramp is cancelled by subsequent call to SetGain. |
| // |
| // 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. |
| // |
| // Usage example (using time in seconds): |
| // Time 0 |
| // SetGainWithRamp(MUTED_GAIN_DB, 0, SCALE_LINEAR) // Ramp 1 |
| // SetGainWithRamp(0.0f, ZX_SEC(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(MUTED_GAIN_DB, ZX_SEC(1), SCALE_LINEAR) // Ramp 3 |
| // |
| // |
| // Time 0: Ramp 1 completes immediately, changing the gain to MUTED_GAIN_DB. |
| // Ramp 2 is pending, since we are not in playback. |
| // Time 3, Ramp 2 begins ramping from MUTED_GAIN_DB to 0 dB |
| // (scale 0.0=>1.0). |
| // Time 4: Ramp 2 pauses (3s remain). Per SCALE_LINEAR, 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 (MUTED_GAIN_DB). |
| // |
| SetGainWithRamp(float32 gain_db, |
| int64 duration_ns, |
| AudioRamp rampType); |
| |
| // Sets the mute value. Ramping and Mute are fully independent, although of |
| // course they both affect the scaling that is applied to the audio |
| // stream(s). |
| SetMute(bool muted); |
| |
| // Provides current gain/mute values to those who register for notification. |
| // |
| // TODO(mpuryear): provide ramp-related values in this event, as well. |
| // |
| // TODO(mpuryear): notify upon ramp milestones (not just SetGain/Mute) -- |
| // upon the start/pause/restart/completion of an active ramp? |
| -> OnGainMuteChanged(float32 gain_db, bool muted); |
| }; |
| |
| const float32 MUTED_GAIN_DB = -160.0; |
| |
| const float32 MAX_GAIN_DB = 24.0; |