[media] tweak GainControl for FIDL readability
This CL updates the fuchsia.media.audio.GainControl definition for
FIDL readability. The changes are:
1) doc comments
2) Rename AudioRamp struct to RampType
3) Change the type of a duration to zx.duration
TEST: no behavior change
Change-Id: Ia80e0b85d5468f825805c92d2601793517431edf
diff --git a/garnet/bin/media/audio_core/audio_capturer_impl.h b/garnet/bin/media/audio_core/audio_capturer_impl.h
index 5b10574..3751467 100644
--- a/garnet/bin/media/audio_core/audio_capturer_impl.h
+++ b/garnet/bin/media/audio_core/audio_capturer_impl.h
@@ -158,7 +158,7 @@
// GainControl interface.
void SetGain(float gain_db) final;
void SetGainWithRamp(float gain_db, zx_duration_t duration_ns,
- fuchsia::media::audio::AudioRamp rampType) final {
+ fuchsia::media::audio::RampType ramp_type) final {
FXL_NOTIMPLEMENTED();
}
void SetMute(bool mute) final;
diff --git a/garnet/bin/media/audio_core/audio_renderer_impl.cc b/garnet/bin/media/audio_core/audio_renderer_impl.cc
index 1ad25d9..a040273 100644
--- a/garnet/bin/media/audio_core/audio_renderer_impl.cc
+++ b/garnet/bin/media/audio_core/audio_renderer_impl.cc
@@ -672,7 +672,7 @@
// is pre-mix and hence is the Source component in the Gain object.
void AudioRendererImpl::SetGainWithRamp(
float gain_db, zx_duration_t duration_ns,
- fuchsia::media::audio::AudioRamp rampType) {
+ fuchsia::media::audio::RampType ramp_type) {
if (gain_db > fuchsia::media::audio::MAX_GAIN_DB ||
gain_db < fuchsia::media::audio::MUTED_GAIN_DB || isnan(gain_db)) {
FXL_LOG(ERROR) << "SetGainWithRamp(" << gain_db << " dB) out of range.";
@@ -681,10 +681,10 @@
}
ForEachDestLink([throttle_ptr = throttle_output_link_.get(), gain_db,
- duration_ns, rampType](auto& link) {
+ duration_ns, ramp_type](auto& link) {
if (link.get() != throttle_ptr) {
link->bookkeeping()->gain.SetSourceGainWithRamp(gain_db, duration_ns,
- rampType);
+ ramp_type);
}
});
@@ -750,8 +750,8 @@
void AudioRendererImpl::GainControlBinding::SetGainWithRamp(
float gain_db, zx_duration_t duration_ns,
- fuchsia::media::audio::AudioRamp rampType) {
- owner_->SetGainWithRamp(gain_db, duration_ns, rampType);
+ fuchsia::media::audio::RampType ramp_type) {
+ owner_->SetGainWithRamp(gain_db, duration_ns, ramp_type);
}
void AudioRendererImpl::GainControlBinding::SetMute(bool mute) {
diff --git a/garnet/bin/media/audio_core/audio_renderer_impl.h b/garnet/bin/media/audio_core/audio_renderer_impl.h
index ea88833..9588927 100644
--- a/garnet/bin/media/audio_core/audio_renderer_impl.h
+++ b/garnet/bin/media/audio_core/audio_renderer_impl.h
@@ -84,7 +84,7 @@
// GainControl interface.
void SetGain(float gain_db) final;
void SetGainWithRamp(float gain_db, zx_duration_t duration_ns,
- fuchsia::media::audio::AudioRamp rampType) final;
+ fuchsia::media::audio::RampType ramp_type) final;
void SetMute(bool muted) final;
void NotifyGainMuteChanged();
// TODO(mpuryear): Notify on SetGainWithRamp.
@@ -113,7 +113,7 @@
// GainControl interface.
void SetGain(float gain_db) final;
void SetGainWithRamp(float gain_db, zx_duration_t duration_ns,
- fuchsia::media::audio::AudioRamp rampType) final;
+ fuchsia::media::audio::RampType ramp_type) final;
void SetMute(bool muted) final;
private:
diff --git a/garnet/bin/media/audio_core/mixer/gain.cc b/garnet/bin/media/audio_core/mixer/gain.cc
index 4d8d5bc..41d3c2d 100644
--- a/garnet/bin/media/audio_core/mixer/gain.cc
+++ b/garnet/bin/media/audio_core/mixer/gain.cc
@@ -22,7 +22,7 @@
// stage), refactor to accept a stage index or a pointer to a ramp-struct.
void Gain::SetSourceGainWithRamp(
float source_gain_db, zx_duration_t duration_ns,
- __UNUSED fuchsia::media::audio::AudioRamp rampType) {
+ __UNUSED fuchsia::media::audio::RampType ramp_type) {
FXL_DCHECK(source_gain_db <= kMaxGainDb);
FXL_DCHECK(duration_ns >= 0) << "Ramp duration cannot be negative";
diff --git a/garnet/bin/media/audio_core/mixer/gain.h b/garnet/bin/media/audio_core/mixer/gain.h
index f9a0773..3f2f011 100644
--- a/garnet/bin/media/audio_core/mixer/gain.h
+++ b/garnet/bin/media/audio_core/mixer/gain.h
@@ -105,10 +105,9 @@
}
// Smoothly change the source gain over the specified period of playback time.
- void SetSourceGainWithRamp(
- float gain_db, zx_duration_t duration_ns,
- fuchsia::media::audio::AudioRamp rampType =
- fuchsia::media::audio::AudioRamp::SCALE_LINEAR);
+ void SetSourceGainWithRamp(float gain_db, zx_duration_t duration_ns,
+ fuchsia::media::audio::RampType ramp_type =
+ fuchsia::media::audio::RampType::SCALE_LINEAR);
void ClearSourceRamp() { source_ramp_duration_ns_ = 0; }
diff --git a/garnet/bin/media/audio_core/test/gain_control_test.cc b/garnet/bin/media/audio_core/test/gain_control_test.cc
index 025b9da..f37d4ed 100644
--- a/garnet/bin/media/audio_core/test/gain_control_test.cc
+++ b/garnet/bin/media/audio_core/test/gain_control_test.cc
@@ -335,7 +335,7 @@
TEST_F(RenderGainControlTest, SetGainMute) { TestSetGainMute(); }
// TODO(mpuryear): Ramp-related tests (render). Relevant FIDL signature is:
-// SetGainWithRamp(float32 gain_db, int64 duration_ns, AudioRamp rampType);
+// SetGainWithRamp(float32 gain_db, int64 duration_ns, RampType ramp_type);
// TODO(mpuryear): Validate GainChange notifications of gainramps.
diff --git a/garnet/bin/media/signal_generator/signal_generator.cc b/garnet/bin/media/signal_generator/signal_generator.cc
index 4e2bfad..7f4ce61 100644
--- a/garnet/bin/media/signal_generator/signal_generator.cc
+++ b/garnet/bin/media/signal_generator/signal_generator.cc
@@ -278,7 +278,7 @@
if (ramp_stream_gain_) {
gain_control_->SetGainWithRamp(
ramp_target_gain_db_, ramp_duration_nsec_,
- fuchsia::media::audio::AudioRamp::SCALE_LINEAR);
+ fuchsia::media::audio::RampType::SCALE_LINEAR);
}
}
diff --git a/sdk/fidl/fuchsia.media.audio/fuchsia.media.audio.api b/sdk/fidl/fuchsia.media.audio/fuchsia.media.audio.api
index 295dca0..17dc75e 100644
--- a/sdk/fidl/fuchsia.media.audio/fuchsia.media.audio.api
+++ b/sdk/fidl/fuchsia.media.audio/fuchsia.media.audio.api
@@ -1,3 +1,3 @@
{
- "fidl/fuchsia.media.audio/gain_control.fidl": "a6ddc572f9c422e2bfdf0d2f2f50b183"
+ "fidl/fuchsia.media.audio/gain_control.fidl": "053d0ed059a82270b9a7115aef3ba76f"
}
\ No newline at end of file
diff --git a/sdk/fidl/fuchsia.media.audio/gain_control.fidl b/sdk/fidl/fuchsia.media.audio/gain_control.fidl
index 3210d19..4a6ec3c 100644
--- a/sdk/fidl/fuchsia.media.audio/gain_control.fidl
+++ b/sdk/fidl/fuchsia.media.audio/gain_control.fidl
@@ -4,65 +4,65 @@
library fuchsia.media.audio;
-enum AudioRamp : uint16 {
- // Scale amplitude changes evenly ("straight-line") across a ramp duration.
- SCALE_LINEAR = 1;
+// fuchsia.media.audio contains definitions relating to audio. Definitions in
+// this file concern control of audio gain.
- // Additional ramp shapes (easings) may be added in the future, including
- // logarithmic (i.e. linear wrt dB), cubic (in/out/inout) or others.
-};
+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.
+ /// 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).
- //
+ /// 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,
- int64 duration_ns,
- AudioRamp rampType);
+ zx.duration duration,
+ RampType 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).
+ /// Sets the mute value. Ramping and mute are fully independent, although
+ /// they both affect the scaling that is applied.
SetMute(bool muted);
- // Provides current gain/mute values to those who register for notification.
+ /// Notifies the client of changes in the current gain/mute values.
//
// TODO(mpuryear): provide ramp-related values in this event, as well.
//
@@ -71,6 +71,19 @@
-> 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.
+};
diff --git a/src/media/playback/mediaplayer/test/fakes/fake_audio_renderer.h b/src/media/playback/mediaplayer/test/fakes/fake_audio_renderer.h
index 547f2d0..91c9660 100644
--- a/src/media/playback/mediaplayer/test/fakes/fake_audio_renderer.h
+++ b/src/media/playback/mediaplayer/test/fakes/fake_audio_renderer.h
@@ -94,7 +94,7 @@
// GainControl interface.
void SetGain(float gain_db) override;
void SetGainWithRamp(float gain_db, zx_duration_t duration_ns,
- fuchsia::media::audio::AudioRamp rampType) final {
+ fuchsia::media::audio::RampType ramp_type) final {
FXL_NOTIMPLEMENTED();
};
void SetMute(bool muted) override;
