// 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.
|
};
|
|
// Ordinal range: 0x0100-0x1ff
|
interface GainControl {
|
// Sets the gain in decibels.
|
0x0101: 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).
|
//
|
0x0102: 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).
|
0x0103: 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?
|
0x0104: -> OnGainMuteChanged(float32 gain_db, bool muted);
|
};
|
|
const float32 MUTED_GAIN_DB = -160.0;
|
|
const float32 MAX_GAIN_DB = 24.0;
|
