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

// fuchsia.media.audio contains definitions relating to audio. Definitions in
// this file concern control of audio gain.

using zx;

/// Enables control and monitoring of audio gain. This interface is typically
/// a tear-off of other interfaces. For example, `fuchsia.media.audio.Renderer`
/// has a `BindGainControl` method that binds to a gain control that controls
/// gain for the renderer.
protocol GainControl {
    /// Sets the gain in decibels.
    SetGain(float32 gain_db);

    /// 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.
    ///
    /// 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,
                    zx.duration duration,
                    RampType rampType);

    /// Sets the mute value. Ramping and mute are fully independent, although
    /// they both affect the scaling that is applied.
    SetMute(bool muted);

    /// Notifies the client of changes in the current gain/mute values.
    //
    // 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);
};

/// Gain value producing silence. Gain values less than this value are permitted,
/// but produce the same effect as this value.
const float32 MUTED_GAIN_DB = -160.0;

/// Maximum permitted gain value.
const float32 MAX_GAIN_DB = 24.0;

/// Enumerates gain control ramp types.
enum RampType : uint16 {
    /// Amplitude scale changes at a fixed rate across the ramp duration.
    SCALE_LINEAR = 1;

    // TODO(mpuryear) Additional ramp shapes (easings) may be added in the
    // future, perhaps including logarithmic (i.e. linear wrt dB), cubic
    // (in/out/inout) or others.
};