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

using fuchsia.media;

/// Settings related to audio.
///
/// Supported SettingsEpitaph enums:
/// REQUEST_NOT_SUPPORTED, INTERNAL_SERVICE_ERROR, PERSISTENT_STORAGE_ERROR
@discoverable(server="platform")
closed protocol Audio {
    /// Gets the current [AudioSettings]. Returns immediately on first call;
    /// subsequent calls return when the value changes.
    ///
    /// If this call fails, it is considered a fatal error and the channel
    /// will be closed.
    strict Watch() -> (struct {
        settings AudioSettings;
    });

    /// Sets audio settings. Any field not explicitly set in the table performs a
    /// no-op, and will not make any changes.
    strict Set(struct {
        settings AudioSettings;
    }) -> () error Error;
};

/// The source of the volume settings. The volume is set according to the source.
type AudioStreamSettingSource = strict enum {

    /// The volume is set by the user. When the `source` in AudioStreamSettings is
    /// set to this, the audio volume is set to `user_volume`.
    USER = 0;

    /// The system takes control of the volume. This is used when the system constantly
    /// calculates and changes the volume. The volume is not stored for this source.
    SYSTEM = 1;

    /// The system takes control of the volume. This is used when the system changes
    /// the volume, but we still want to play feedback sounds for these changes. The
    /// volume is not stored for this source.
    SYSTEM_WITH_FEEDBACK = 2;
};

type Volume = table {
    /// The volume level ranged [0.0, 1.0]. The level maps to a dbfs value from a volume
    /// curve in the setting service. Not a number (NaN), infinity or negative infinity
    /// will cause SetVolume to fail with INVALID_VALUE.
    1: level float32;

    /// True if the volume should be muted. If this is true, then the volume is silent,
    /// regardless of `level`.
    2: muted bool;
};

type AudioStreamSettings = table {
    /// The audio stream which the settings are applying to.
    1: stream fuchsia.media.AudioRenderUsage;

    /// The volume of `stream` is set according to the volume settings from `source`.
    2: source AudioStreamSettingSource;

    /// User level volume setting. If the `source` is USER, then the volume is set to
    /// `user_volume`.
    3: user_volume Volume;
};

type AudioSettings = table {
    /// Contains the volume setting for all audio stream settings. There should only be
    /// one AudioStreamSettings for each fuchsia.media.AudioRenderUsage.
    1: streams vector<AudioStreamSettings>:5;

    @available(deprecated=8, removed=9)
    2: input AudioInput;
};

@available(deprecated=8, removed=9)
type AudioInput = table {
    /// Whether the audio input is muted. Takes into consideration the hardware state.
    1: muted bool;
};