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

library fuchsia.media;

[Discoverable]
protocol AudioCore {
    // Create an AudioRenderer which is grouped and handled as part of the
    // AudioRenderUsage specified.  An AudioRenderer will not be able to have
    // its usage changed after creation.  The AudioRenderUsage is used by
    // AudioPolicy to dictate how streams interact with each other.
    CreateAudioRenderer(request<AudioRenderer> audio_out_request);

    // Create an AudioCapturer which either captures from the current default
    // audio input device, or loops-back from the current default audio output
    // device based on value passed for the loopback flag.  AudioCaptureUsage
    // is used by AudioPolicy to dictate how streams interact with each other. A
    // AudioCapturer may change its usage at any time.
    //
    // TODO(mpuryear): Get rid of the loopback flag ASAP. Routing decisions (and
    // security surrounding routing decisions) should be much more sophisticated
    // than this. This is just a placeholder until we have a design in place.
    // Eventually, I suspect that all of this will move up into the audio policy
    // manager and application clients will obtain AudioCapturers from and
    // control through the policy manager.
    CreateAudioCapturer(bool loopback, request<AudioCapturer> audio_in_request);

    // System Gain and Mute
    // TODO(mpuryear): remove this systemwide setting once device-centric
    // settings are plumbed into the system UI. Also, device-centric (and
    // certainly systemwide settings) should be moved out of the
    // accessible-to-all public audio interface and relocated to a more
    // restrictive interface that is only accessible by clients with the
    // appropriate privileges (such as system configuration API, or the
    // governor of audio policy).
    //
    // Mirroring device-centric gain and mute stages, Fuchsia's systemwide Gain
    // and Mute settings are fully independent. Changing the value of one does
    // not change the value of the other. Both have the ability to silence a
    // system (or a device, in the case of device Gain/Mute). If Mute is true,
    // or if Gain is kMutedGain, the system is silenced regardless of the
    // other. Similarly, one's value does not restrict the other's possible
    // values in any way.
    //
    // Sets the system-wide gain in decibels. |db| values are clamped to the
    // range -160db to 0db, inclusive. This setting is applied to all audio
    // output devices. Audio input devices are unaffected. System Gain changes
    // do not affect the System Mute state.
    SetSystemGain(float32 gain_db);

    // Sets/clears the systemwide 'Mute' state for audio output devices. Audio
    // input devices are unaffected. Changes to the System Mute state do not
    // affect the value of System Gain.
    SetSystemMute(bool muted);

    // Provides current values for the systemwide Gain and Mute.
    // When a client connects to Audio, the system enqueues an action (to be
    // executed once the system regains control) to send this newly-connected
    // client a callback with the current systemwide Gain|Mute settings.
    // Further, upon any change to the systemwide Gain|Mute values, the system
    // will trigger all registered callbacks, notifying clients of the new
    // values.
    //
    // Calls to SetSystemMute or SetSystemGain that do NOT result in a change to
    // these values (e.g. calling SetSystemMute(false) when Mute is already
    // false) will not cause the callbacks to be triggered.
    //
    // During and immediately following connecting to Audio, it is essential
    // that clients keep in mind the fundamental single-threaded nature of FIDL.
    // Specifically, if a newly-connected client registers a
    // SystemGainMuteChanged callback before returning, that client will (once
    // the system has subsequent opportunity) be notified via callback of the
    // Gain|Mute settings at the time the connection was established. If
    // however a newly-connected client returns from a FIDL message dispatch
    // (returning control to the FIDL dispatcher), then that client
    // subsequently registers this callback, the client has no way to learn the
    // current Gain|Mute settings until they actually change.
    -> SystemGainMuteChanged(float32 gain_db, bool muted);

    SetRoutingPolicy(AudioOutputRoutingPolicy policy);
};

// A placeholder for various types of simple routing policies. This should be
// replaced when routing policy moves to a more centralized policy manager.
enum AudioOutputRoutingPolicy {
    // AudioRenderers are always connected to all audio outputs which currently
    // in the plugged state (eg; have a connector attached to them)
    ALL_PLUGGED_OUTPUTS = 0;

    // AudioRenderers are only connected to the output stream which most
    // recently entered the plugged state. AudioRenderers move around from
    // output to output as streams are published/unpublished and become
    // plugged/unplugged.
    //
    // This is the initial setting for audio output routing.
    LAST_PLUGGED_OUTPUT = 1;
};