// 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.
type UsageStateUnadjusted = table {};

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

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

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

/// 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(struct {
        usage Usage;
        state UsageState;
    }) -> ();
};

/// A protocol for setting up watchers of audio usages.
@discoverable
protocol UsageReporter {
    Watch(resource struct {
        usage Usage;
        usage_watcher client_end:UsageWatcher;
    });
};

/// 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(resource struct {
        device_unique_id string:36;
        usage Usage;
        usage_gain_listener client_end:UsageGainListener;
    });
};

/// 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(struct {
        muted bool;
        gain_dbfs float32;
    }) -> ();
};