// 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.
type AudioRenderUsage = strict enum {
    /// 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 RENDER_USAGE_COUNT uint8 = 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.
type AudioCaptureUsage = strict enum {
    /// 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 CAPTURE_USAGE_COUNT uint8 = 4;

/// The behaviors applied to streams when multiple are active.
type Behavior = strict enum {
    /// 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;
};

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

@discoverable
closed protocol AudioCore {
    /// Creates an AudioRenderer which outputs audio to the default device.
    strict CreateAudioRenderer(resource struct {
        audio_out_request server_end:AudioRenderer;
    });

    /// Creates an AudioCapturer 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.
    ///
    strict CreateAudioCapturerWithConfiguration(resource struct {
        stream_type AudioStreamType;
        configuration AudioCapturerConfiguration;
        audio_capturer_request server_end:AudioCapturer;
    });

    /// Creates 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(https://fxbug.dev/42110275): 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.
    strict CreateAudioCapturer(resource struct {
        loopback bool;
        audio_in_request server_end:AudioCapturer;
    });

    // TODO(https://fxbug.dev/42110311): 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.
    @available(removed=15)
    strict SetSystemGain(struct {
        gain_db float32;
    });

    /// 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.
    @available(removed=15)
    strict SetSystemMute(struct {
        muted bool;
    });

    /// 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.
    @available(removed=15)
    strict -> SystemGainMuteChanged(struct {
        gain_db float32;
        muted bool;
    });

    // 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(https://fxbug.dev/42085388): 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.
    @deprecated
    strict EnableDeviceSettings(struct {
        enabled bool;
    });

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

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

    /// Binds to a volume control protocol for the given usage.
    strict BindUsageVolumeControl(resource struct {
        usage Usage;
        volume_control server_end:fuchsia.media.audio.VolumeControl;
    });

    /// Queries the volume percentage [0, 1] that maps to a `gain_db` value for a particular
    /// `usage`. This is the same mapping as used by the VolumeControl from
    /// `BindUsageVolumeControl`.
    strict GetVolumeFromDb(struct {
        usage Usage;
        gain_db float32;
    }) -> (struct {
        volume float32;
    });

    /// Queries the decibel value that maps to a volume percentage [0, 1] for a particular `usage`.
    /// This is the same mapping as used by the VolumeControl from `BindUsageVolumeControl`.
    strict GetDbFromVolume(struct {
        usage Usage;
        volume float32;
    }) -> (struct {
        gain_db float32;
    });

    /// Sets 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`.
    strict SetInteraction(struct {
        active Usage;
        affected Usage;
        behavior Behavior;
    });

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

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

// Placeholder for routing policies.
// TODO(https://fxbug.dev/42110283): Replace, when routing is handled by a central policy manager.
type AudioOutputRoutingPolicy = strict enum {
    // 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;
};