sdk/fidl/fuchsia.hardware.audio.signalprocessing/equalizer.fidl

// Copyright 2022 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.hardware.audio.signalprocessing;

const MAX_COUNT_EQUALIZER_BANDS uint32 = 64;

/// Type of the equalizer band.
type EqualizerBandType = flexible enum : uint64 {
    /// Increase/decrease in `gain_db` in the vicinity of a `frequency` with an optional `q`.
    PEAK = 1;

    /// Narrow band rejection significantly attenuating a `frequency` with an optional `q`.
    NOTCH = 2;

    /// Decrease gain below a `frequency` with an optional `q`, a.k.a high pass.
    LOW_CUT = 3;

    /// Decrease gain above a `frequency` with an optional `q`, a.k.a low pass.
    HIGH_CUT = 4;

    /// Decrease gain below a `frequency` for a `gain_db` amount with a plateau effect.
    LOW_SHELF = 5;

    /// Decrease gain above a `frequency` for a `gain_db` amount with a plateau effect.
    HIGH_SHELF = 6;
};

/// Parameters for an equalizer Band.
type EqualizerBand = table {
    /// Unique ID for this band, only required to be unique within the corresponding
    /// `Element`, and valid until the channel associated with the `SignalProcessing`
    /// protocol is closed.
    ///
    /// Required.
    1: id uint64;
};

/// Equalizer supported controls specified in `Equalizer`.
type EqualizerSupportedControls = flexible bits : uint64 {
    /// If included, the `frequency` of the equalizer bands can be changed with `SetElementState`.
    CAN_CONTROL_FREQUENCY = 0x1;

    /// If included, the `q` of the equalizer bands can be changed with `SetElementState`.
    CAN_CONTROL_Q = 0x2;

    /// If included, the `type` of the equalizer bands can be changed with `SetElementState`
    /// to `EqualizerBandType` `PEAK`.
    SUPPORTS_TYPE_PEAK = 0x4;

    /// If included, the `type` of the equalizer bands can be changed with `SetElementState`
    /// to `EqualizerBandType` `NOTCH`.
    SUPPORTS_TYPE_NOTCH = 0x8;

    /// If included, the `type` of the equalizer bands can be changed with `SetElementState`
    /// to `EqualizerBandType` `LOW_CUT`.
    SUPPORTS_TYPE_LOW_CUT = 0x10;

    /// If included, the `type` of the equalizer bands can be changed with `SetElementState`
    /// to `EqualizerBandType` `HIGH_CUT`.
    SUPPORTS_TYPE_HIGH_CUT = 0x20;

    /// If included, the `type` of the equalizer bands can be changed with `SetElementState`
    /// to `EqualizerBandType` `LOW_SHELF`.
    SUPPORTS_TYPE_LOW_SHELF = 0x40;

    /// If included, the `type` of the equalizer bands can be changed with `SetElementState`
    /// to `EqualizerBandType` `HIGH_SHELF`.
    SUPPORTS_TYPE_HIGH_SHELF = 0x80;
};

/// Parameters for a `Element` with `type` equal to `EQUALIZER`.
type Equalizer = table {
    /// Equalizers in this protocol are built by a number of bands, each specifying a number of
    /// parameters here and `EqualizerElementState` that can be changed with `SetElementState`.
    /// The number of elements of the `bands` vector determines the number of bands
    /// supported by this processing element.
    ///
    /// Required.
    1: bands vector<EqualizerBand>:MAX_COUNT_EQUALIZER_BANDS;

    /// The controls supported by this equalizer.
    ///
    /// Optional.
    2: supported_controls EqualizerSupportedControls;

    /// If included and true, individual bands can be disabled via `SetElementState`.
    /// If not included or false, the bands are always enabled.
    /// For a band to be functional its enclosing equalizer processing element has to be enabled.
    ///
    /// Optional.
    3: can_disable_bands bool;

    /// Minimum frequency for the bands in Hz.
    ///
    /// Required.
    4: min_frequency uint32;

    /// Maximum frequency for the bands in Hz.
    ///
    /// Required.
    5: max_frequency uint32;

    /// Maximum quality factor, usually denoted by "Q", for the bands.
    /// Indicates how narrow the frequency transition is. Higher Q values imply narrower
    /// notches/peaks and steeper cuts/shelves. Must be positive.
    ///
    /// Optional.
    6: max_q float32;

    /// Minimum gain in dB.
    ///
    /// Optional, but required if `supported_controls` is present and includes `SUPPORTS_TYPE_PEAK`,
    /// `SUPPORTS_TYPE_LOW_SHELF` or `SUPPORTS_TYPE_HIGH_SHELF`.
    7: min_gain_db float32;

    /// Maximum gain in dB.
    ///
    /// Optional, but required if `supported_controls` is present and includes `SUPPORTS_TYPE_PEAK`,
    /// `SUPPORTS_TYPE_LOW_SHELF` or `SUPPORTS_TYPE_HIGH_SHELF`.
    8: max_gain_db float32;
};

/// State for a single band within a `Element` with `type` equal to `EQUALIZER`.
type EqualizerBandState = table {
    /// Unique ID for the band. Must match one of the `id`s specified in `Equalizer` `bands`.
    ///
    /// Required.
    1: id uint64;

    /// Type of band.
    ///
    /// Optional.
    2: type EqualizerBandType;

    /// Center frequency for the band.
    ///
    /// Optional.
    3: frequency uint32;

    /// Quality factor, usually denoted as "Q".
    /// Indicates how narrow the frequency transition is. Higher Q values imply narrower
    /// notches/peaks and steeper cuts/shelves. Must be positive.
    ///
    /// Optional.
    4: q float32;

    /// Gain in dB.
    ///
    /// Optional, but required for `EqualizerBandType` `PEAK`, `LOW_SHELF` and `HIGH_SHELF`.
    /// May not be included for `EqualizerBandType` `NOTCH`, `LOW_CUT` or `HIGH_CUT`.
    5: gain_db float32;

    /// Enable/disable the band. By default all bands are enabled.
    /// Disabling the enclosing processing element by setting `ElementState.enabled` to
    /// false disables the whole equalizer and it does not change this field. For a band to be
    /// functional its enclosing equalizer processing element has to be enabled.
    ///
    /// Optional.
    6: enabled bool;
};

/// State for a `Element` with `type` equal to `EQUALIZER`.
type EqualizerElementState = table {
    /// The number of elements of the `bands_state` vector must be equal or smaller than the
    /// number of elements of the `bands` returned in returned in the corresponding
    /// `Equalizer`. `bands_state` must have at least one element.
    /// The bands controlled by `bands_state` are determined by each `band.id`.
    ///
    /// Required.
    @available(removed=20)
    1: bands_state vector<EqualizerBandState>:MAX_COUNT_EQUALIZER_BANDS;

    /// The number of elements of the `band_states` vector must be equal or smaller than the
    /// number of elements of the `bands` returned in returned in the corresponding
    /// `Equalizer`. `band_states` must have at least one element.
    /// The bands controlled by `band_states` are determined by each `band.id`.
    ///
    /// Required.
    @available(added=20)
    2: band_states vector<EqualizerBandState>:MAX_COUNT_EQUALIZER_BANDS;
};