| // 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; |
| |
| enum AudioRamp : uint16 { |
| // Amplitude scale changes evenly ("straight-line") across the ramp duration. |
| SCALE_LINEAR = 1; |
| |
| // Additional ramp shapes (easings) may be added in the future, perhaps |
| // including logarithmic (i.e. linear wrt dB), cubic (in/out/inout) or others. |
| }; |
| |
| interface 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, the 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 scalingthat 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; |