// 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.
type StreamType = strict enum {
    /// 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'.
type AudioEffectType = table {
    /// Library module associated with the effect, such as 'my_audio_effects.so'.
    1: module_name string:64;
    /// Name of the effect type within the module.
    2: effect_name string:255;
};

/// 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'.
type AudioEffectConfig = table {
    /// Unique identifier of the audio effect instance.
    1: instance_name string:64;
    /// Detailed specification of the audio effect type.
    2: type AudioEffectType;
    /// JSON string of the audio effect configuration to be applied to an audio stream(s).
    3: configuration string:4096;
    /// Rechannelization defined by the effect and applied to the audio stream output; this 
    /// is in addition to channelization provided by the AudioMixGroup.
    4: output_channels uint16;
};

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

/// Audio effects configuration details applied to audio streams within
/// a device's media pipeline.
type AudioMixGroup = struct {
    /// Identifier of the audio effects mix detailed in this object.
    name string:32;
    /// True if the device profile is eligible for loopback capture.
    loopback bool;
    /// Audio effect configurations applied to the specified `streams`.
    effects vector<AudioEffectConfig>:16;
    /// Set of audio effect mixes, each of which consist of various effects configurations.
    inputs vector<box<AudioMixGroup>>:16;
    /// Names of the audio streams to which the `effects` are applied.
    streams vector<StreamType>:8;
    /// 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.
    output_rate uint32;
    /// Channelization of the mix stream output before any effects are applied; effects can apply
    /// additional rechannelization.
    output_channels uint16;
};

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

@discoverable
closed protocol AudioTuner {
    /// Provides names of audio effects classes available for tuning.
    strict GetAvailableAudioEffects() -> (struct {
        effects vector<AudioEffectType>:16;
    });

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

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

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

    /// Deletes the current, tunable audio effects configuration and volume settings
    /// for the given device.
    strict DeleteAudioDeviceProfile(struct {
        device_id string:32;
    }) -> (struct {
        status zx.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.
    strict SetAudioEffectConfig(struct {
        device_id string:32;
        effect AudioEffectConfig;
    }) -> (struct {
        status zx.Status;
    });
};