// Copyright 2019 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.

//TODO(fxbug.dev/36191): Move to fuchsia.media.audio

library fuchsia.media;

/// A state of audio usages in which no policy actions are taken on any streams with the usage.
table UsageStateUnadjusted {
};

/// A state of audio usages in which a policy decision has been made to temporarily
/// lower the volume of all streams with this usage.
table UsageStateDucked {
};

/// A state of audio usages in which a policy decision has been made to temporarily
/// mute the volume of all streams with this usage.
table UsageStateMuted {
};

/// The state of audio policy enforcement on a stream or set of streams.
flexible union UsageState {
    1: UsageStateUnadjusted unadjusted;
    2: UsageStateDucked ducked;
    3: UsageStateMuted muted;
};

/// A protocol for listening to changes to the policy state of an audio usage.
///
/// User actions, such as lowering the volume or muting a stream, are not reflected in this
/// API.
protocol UsageWatcher {
    /// Called on first connection and whenever the watched usage changes. The provided
    /// usage will always be the bound usage; it is provided so that an implementation of
    /// this protocol may be bound to more than one usage.
    ///
    /// Clients must respond to acknowledge the event. Clients that do not acknowledge their
    /// events will eventually be disconnected.
    OnStateChanged(Usage usage, UsageState state) -> ();
};

/// A protocol for setting up watchers of audio usages.
[Discoverable]
protocol UsageReporter {
    Watch(
        Usage usage,
        UsageWatcher usage_watcher);
};

/// A protocol for setting up watchers of usage gain.
[Discoverable]
protocol UsageGainReporter {
    // TODO(fxbug.dev/71946): Only report volume-to-gain translation, without
    // including muting/ducking gain adjustments. Determine whether separate
    // muting/ducking gain reporting is necessary
    //
    /// Connects a listener to a stream of usage gain setting changes
    /// for `usage` on the device identified by `device_token`. Usage
    /// Gain is not set directly by any client; it is a translation of
    /// the usage volume setting for each device, summed with active
    /// muting/ducking gain adjustments.
    ///
    /// Devices may map the same volume level to different dbfs, so
    /// a `device_unique_id` is needed to indentify the device.
    ///
    /// `AudioDeviceEnumerator` provides programmatic access to devices
    /// and their unique ids if it is necessary for a client to select
    /// an id at runtime.
    RegisterListener(
        string:36 device_unique_id,
        Usage usage,
        UsageGainListener usage_gain_listener);
};

/// A protocol for watching changes to usage gain settings.
///
/// The channel will close when the device is not present.
protocol UsageGainListener {
    /// Called immediately on connection and afterward any time
    /// the usage gain setting changes.
    ///
    /// Clients must respond to acknowledge the event. Clients that do not acknowledge their
    /// events will eventually be disconnected.
    ///
    /// Note: This API does not have mute reporting implemented; `muted` is always false.
    // TODO(fxbug.dev/54949): Update implementation to report on mute state.
    OnGainMuteChanged(bool muted, float32 gain_dbfs) -> ();
};