public/fidl/fuchsia.media/gain_control.fidl

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