// Copyright 2020 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.tuning;

using zx;

/// Usage annotating the purpose of the stream that may be processed in tuning.
enum StreamType {
    /// Stream is intended to be used for ambient or background renderer audio.
    RENDER_BACKGROUND = 0;
    /// Stream is intended to be used for normal renderer functionality.
    RENDER_MEDIA = 1;
    /// Renderer stream is intended to interrupt any ongoing function of the device.
    RENDER_INTERRUPTION = 2;
    /// Stream is for interaction with a system agent renderer.
    RENDER_SYSTEM_AGENT = 3;
    /// Stream is intended to be used for some form of real time user to user
    /// communication render.
    RENDER_COMMUNICATION = 4;
    /// Stream is intended to be used for ultrasound-specific renderer streams.
    /// A standard renderer is not able to assign this usage; rather, an ultrasound
    /// renderer is explicitly created with fuchsia.ultrasound.Factory.
    RENDER_ULTRASOUND = 5;
};

/// Specification of an audio stream effect name and compiled library module.
///
/// A valid `AudioEffectType` includes a specific module and audio effect name,
/// such as module 'google_audio_effects.so' with name 'equalizer'.
table AudioEffectType {
    /// Library module associated with the effect, such as 'my_audio_effects.so'.
    1: string:64 module_name;
    /// Name of the effect type within the module.
    2: string:255 effect_name;
};

/// Details of an audio effect and its configuration to be applied to an audio stream(s).
///
/// An audio effect type can be instantiated multiple times, differentiable by its unique
/// name. For example, an 'equalizer' effect type can be instantiated twice as
/// 'equalizer1' and 'equalizer2'.
table AudioEffectConfig {
    /// Unique identifier of the audio effect instance.
    1: string:64 instance_name;
    /// Detailed specification of the audio effect type.
    2: AudioEffectType type;
    /// JSON string of the audio effect configuration to be applied to an audio stream(s).
    3: string:4096 configuration;
    /// Rechannelization defined by the effect and applied to the audio stream output; this 
    /// is in addition to channelization provided by the AudioMixGroup.
    4: uint16 output_channels;
};

/// Association of a volume level with its decibel value.
struct Volume {
    /// Specific volume level identifier in the range [0.0, 1.0].
    float32 level;
    /// Decibel value of the associated volume level in the range [-120.0, 0.0].
    float32 decibel;
};

/// Audio effects configuration details applied to audio streams within
/// a device's media pipeline.
struct AudioMixGroup {
    /// Identifier of the audio effects mix detailed in this object.
    string:32 name;
    /// True if the device profile is eligible for loopback capture.
    bool loopback;
    /// Audio effect configurations applied to the specified `streams`.
    vector<AudioEffectConfig>:16 effects;
    /// Set of audio effect mixes, each of which consist of various effects configurations.
    vector<AudioMixGroup?>:16 inputs;
    /// Names of the audio streams to which the `effects` are applied.
    vector<StreamType>:8 streams;
    /// Framerate of the mix stage output, which can accommodate upsampling and downsampling.
    /// A different rate may be chosen if the specified rate cannot be accommodated by hardware.
    uint32 output_rate;
    /// Channelization of the mix stream output before any effects are applied; effects can apply
    /// additional rechannelization.
    uint16 output_channels;
};

/// Specification of the audio effects mixes and volume curve for a device.
table AudioDeviceTuningProfile {
    /// Details of the media pipeline effects configuration.
    1: AudioMixGroup pipeline;
    /// Set of associations between volume level and decibel value.
    2: vector<Volume>:16 volume_curve;
};

[Discoverable]
protocol AudioTuner {
    /// Provides names of audio effects classes available for tuning.
    GetAvailableAudioEffects() -> (vector<AudioEffectType>:16 effects);

    /// Provides the current, tunable audio effects configuration and
    /// volume settings for the given device.
    GetAudioDeviceProfile(string:32 device_id) -> (AudioDeviceTuningProfile profile);

    /// Provides the device's current default audio effects configuration and
    /// volume settings, which are read-only and unaffected by the audio tuner.
    GetDefaultAudioDeviceProfile(string:32 device_id) -> (AudioDeviceTuningProfile profile);

    /// Updates the audio effects configuration and volume settings of the given
    /// device with the provided profile.
    SetAudioDeviceProfile(string:32 device_id, AudioDeviceTuningProfile profile)
        -> (zx.status status);

    /// Deletes the current, tunable audio effects configuration and volume settings
    /// for the given device.
    DeleteAudioDeviceProfile(string:32 device_id) -> (zx.status status);

    /// Applies the provided `AudioEffectConfig` to the specified device's tuning profile in the media
    /// pipeline.
    ///
    /// A single audio effect class can be instantiated multiple times, with each instance
    /// able to be applied to the same media pipeline.  The `AudioEffectConfig.instance_name` is scoped
    /// to the specified device.
    ///
    /// For example, two 'equalizer' effect instances named 'equalizer1' and 'equalizer2'
    /// can be applied to the same media pipeline.
    SetAudioEffectConfig(string:32 device_id, AudioEffectConfig effect) -> (zx.status status);
};