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

using fuchsia.media.audio;

/// Usage annotating the purpose of the stream being used to render audio.
/// An AudioRenderer's usage cannot be changed after creation.  The
/// AudioRenderUsage is used by audio policy to dictate how audio streams
/// interact with each other.
enum AudioRenderUsage {
    /// Stream is intended to be used for ambient or background sound. Streams
    /// that can be interrupted without consequence should use this.
    BACKGROUND = 0;

    /// Stream is intended to be used for normal functionality. Streams that
    /// are part of normal functionality should use this.
    MEDIA = 1;

    /// Stream is intended to interrupt any ongoing function of the device.
    /// Streams that are used for interruptions like notifications should use
    /// this.
    INTERRUPTION = 2;

    /// Stream is for interaction with a system agent.  This should be used
    /// in response to a user initiated trigger.
    SYSTEM_AGENT = 3;

    /// Stream is intended to be used for some form of real time user to user
    /// communication. Voice/Video chat should use this.
    COMMUNICATION = 4;
};
const uint8 RENDER_USAGE_COUNT = 5;

/// Usages annotating the purpose of the stream being used to capture audio. The
/// AudioCaptureUsage is used by audio policy to dictate how audio streams
/// interact with each other.
enum AudioCaptureUsage {
    /// Stream is used to capture audio while in the background.  These streams
    /// may be active at any the time and are considered privileged.
    /// Example: Listening for Hotwords
    BACKGROUND = 0;

    /// Stream is intended to be used for normal capture functionality. Streams
    /// that are used for audio capture while the stream creator is in the
    /// foreground should use this.
    /// Example: Voice Recorder
    FOREGROUND = 1;

    /// Stream is for interaction with a system agent.  This should only be used
    /// once a user has signalled their intent to have the interaction with an
    /// interested party.
    /// Examples: Assistant, Siri, Alexa
    SYSTEM_AGENT = 2;

    /// Stream is intended to be used for some form of real time user to user
    /// communication. Voice/Video chat should use this.
    COMMUNICATION = 3;
};
const uint8 CAPTURE_USAGE_COUNT = 4;

/// The behaviors applied to streams when multiple are active.
enum Behavior {
    /// Mix the streams.
    NONE = 0;

    /// Apply a gain to duck the volume of one of the streams. (-14.0db)
    DUCK = 1;

    /// Apply a gain to mute one of the streams. (-160.0db)
    MUTE = 2;
};

union Usage {
    1: AudioRenderUsage render_usage;
    2: AudioCaptureUsage capture_usage;
};

[Discoverable]
protocol AudioCore {
    /// Create an AudioRenderer which outputs audio to the default device.
    CreateAudioRenderer(request<AudioRenderer> audio_out_request);

    /// Create a new Audio Capturer according to the given requirements.
    ///
    /// `pcm_stream_type` sets the stream type of the stream to be delivered.
    /// It causes the source material to be reformatted/resampled if needed
    /// in order to produce the requested stream type.
    ///
    /// `usage` is used by Fuchsia to make decisions about user experience.
    /// See `AudioCaptureUsage` for more details.
    ///
    /// `configuration` must be initialized to a variant, or no capturer
    /// can be created.
    ///
    /// TODO(45240): Implement
    [Transitional]
    CreateAudioCapturerWithConfiguration(
        AudioStreamType stream_type,
        AudioCapturerConfiguration configuration,
        request<AudioCapturer> audio_capturer_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.
    //
    // TODO(34915): Get rid of the loopback flag ASAP. Routing decisions (and
    // security surrounding routing decisions) should be more sophisticated.
    // This is a placeholder until we have a design in place. Eventually, this
    // should move up to an audio policy layer, where application clients obtain
    // and control AudioCapturers.
    CreateAudioCapturer(bool loopback, request<AudioCapturer> audio_in_request);

    // TODO(34948): remove these systemwide settings, once device-centric
    // settings are plumbed into the system UI. Also, device-centric and
    // systemwide settings should be moved out of this 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).

    /// System Gain and Mute
    ///
    /// Fuchsia clients control the volume of individual audio streams via the
    /// fuchsia.media.audio.GainControl protocol. System Gain and Mute affect
    /// all audio output, and are controlled with methods that use the same
    /// concepts as GainControl, namely: independent gain and mute, with change
    /// notifications. Setting System Mute to true leads to the same outcome as
    /// setting System Gain to MUTED_GAIN_DB: all audio output across the system
    /// is silenced.
    ///
    /// Sets the systemwide gain in decibels. `gain_db` values are clamped to
    /// the range -160 db to 0 db, inclusive. This setting is applied to all
    /// audio output devices. Audio input devices are unaffected.
    /// Does not affect System Mute.
    [Transitional, Deprecated]
    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.
    [Transitional, Deprecated]
    SetSystemMute(bool muted);

    /// Provides current values for systemwide Gain and Mute. When a client
    /// connects to AudioCore, the system immediately sends that client a
    /// SystemGainMuteChanged event with the current system Gain|Mute settings.
    /// Subsequent events will be sent when these Gain|Mute values change.
    [Transitional, Deprecated]
    -> SystemGainMuteChanged(float32 gain_db, bool muted);

    // By default, reading and writing device settings files is enabled. This
    // method (which has impact across the entire audio subsystem) allows a test
    // client to temporarily disable, then later enable, that reading/writing.
    // TODO(13578): Move this to the hub, instead of FIDL API. Alternately,
    // simply remove; going forward, HermeticTestEnvironment accepts a
    // parameter that disables device settings writeback during testing.
    EnableDeviceSettings(bool enabled);

    /// Set the Usage gain applied to Renderers. By default, the gain for all
    /// render usages is set to Unity (0 db).
    SetRenderUsageGain(AudioRenderUsage usage, float32 gain_db);

    /// Set the Usage gain applied to Capturers. By default, the gain for all
    /// capture usages is set to Unity (0 db).
    SetCaptureUsageGain(AudioCaptureUsage usage, float32 gain_db);

    /// Binds to a volume control protocol for the given usage.
    BindUsageVolumeControl(Usage usage, request<fuchsia.media.audio.VolumeControl> volume_control);

    /// SetInteraction allows changing how audio_core handles interactions of multiple active
    /// streams simultaneously.  If streams of Usage `active` are processing audio, and streams of
    /// Usage `affected` are as well, the Behavior specified will be applied to the streams of Usage
    /// `affected`.
    SetInteraction(Usage active, Usage affected, Behavior behavior);

    /// Re-initializes the set of rules that are currently governing the interaction of streams in
    /// audio_core.  The default behavior is 'NONE'.
    ResetInteractions();

    /// Re-loads the platform policy configuration.  Falls back to a default config if the platform
    /// does not provide a config.
    LoadDefaults();
};

// Placeholder for routing policies.
// TODO(34922): Replace, when routing is handled by a central 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 default initial setting for audio output routing.
    LAST_PLUGGED_OUTPUT = 1;
};