sdk/lib/media/audio/effects/audio_effects.h

// Copyright 2018 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.

// Refer to the accompanying README.md file for detailed API documentation
// (functions, structs and constants).

#ifndef LIB_MEDIA_AUDIO_EFFECTS_AUDIO_EFFECTS_H_
#define LIB_MEDIA_AUDIO_EFFECTS_AUDIO_EFFECTS_H_

#include <stdint.h>
#include <zircon/compiler.h>
#include <zircon/types.h>

#include <limits>

__BEGIN_CDECLS

typedef void* fuchsia_audio_effects_handle_t;
const fuchsia_audio_effects_handle_t FUCHSIA_AUDIO_EFFECTS_INVALID_HANDLE = nullptr;

const uint16_t FUCHSIA_AUDIO_EFFECTS_CHANNELS_ANY = std::numeric_limits<uint16_t>::max();
const uint16_t FUCHSIA_AUDIO_EFFECTS_CHANNELS_SAME_AS_IN = std::numeric_limits<uint16_t>::max() - 1;
const uint16_t FUCHSIA_AUDIO_EFFECTS_CHANNELS_MAX = 256;

const uint32_t FUCHSIA_AUDIO_EFFECTS_BLOCK_SIZE_ANY = 0;
const uint32_t FUCHSIA_AUDIO_EFFECTS_FRAMES_PER_BUFFER_ANY = 0;

const size_t FUCHSIA_AUDIO_EFFECTS_MAX_NAME_LENGTH = 255;

// Flags that may be passed to fuchsia_audio_effects_module_v1::set_usages
const uint32_t FUCHSIA_AUDIO_EFFECTS_USAGE_NONE           = 0;
const uint32_t FUCHSIA_AUDIO_EFFECTS_USAGE_BACKGROUND     = (1 << 0);
const uint32_t FUCHSIA_AUDIO_EFFECTS_USAGE_MEDIA          = (1 << 1);
const uint32_t FUCHSIA_AUDIO_EFFECTS_USAGE_INTERRUPTION   = (1 << 2);
const uint32_t FUCHSIA_AUDIO_EFFECTS_USAGE_SYSTEM_AGENT   = (1 << 3);
const uint32_t FUCHSIA_AUDIO_EFFECTS_USAGE_COMMUNICATION  = (1 << 4);
// Mask of all valid usage flags. Any bits not covered by this mask may be ignored by
// fuchsia_audio_effects_module_v1::set_usages
const uint32_t FUCHSIA_AUDIO_EFFECTS_USAGE_VALID_MASK     = (1 << 5) - 1;

typedef struct {
  char name[FUCHSIA_AUDIO_EFFECTS_MAX_NAME_LENGTH];
  uint16_t incoming_channels;
  uint16_t outgoing_channels;
} fuchsia_audio_effects_description;

typedef struct {
  uint32_t frame_rate;
  uint16_t channels_in;
  uint16_t channels_out;
  // The block size of the effect. If non-zero, the effect will expect that calls to |process| and
  // |process_inplace| will be called with buffers containing multiples of |block_size_frames|
  // frames.
  //
  // Use |FUCHSIA_AUDIO_EFFECTS_BLOCK_SIZE_ANY| to indicate any alignment is acceptable.
  uint32_t block_size_frames;

  // When an effect has a positive filter width, it will shift that signal |signal_latency_frames|.
  //
  // In other words, compute frame 'N', 'signal_latency_frames' prior frames are used in the stream
  // as part of that computation.
  uint32_t signal_latency_frames;

  // The maximum number of frames the effect can handle with a single call to |process| or
  // |process_inplace|.
  //
  // Use |FUCHSIA_AUDIO_EFFECTS_FRAMES_PER_BUFFER_ANY| to indicate any frame count is acceptable.
  uint32_t max_frames_per_buffer;

  // When an effect has a negative filter width, it will impact 'ring_out_frames' frames _after_
  // the frame has played.
  //
  // When a stream idles, there will be at least 'ring_out_frames' additional frames of silence
  // provided to the effect to allow this state to 'ring_out'.
  uint32_t ring_out_frames;
} fuchsia_audio_effects_parameters;

typedef struct {
  // A bitmask of the `FUCHSIA_AUDIO_EFFECTS_USAGE_` flags, indicating what usages are represented
  // in the audio frames.
  uint32_t usage_mask;

  // The amount of gain scaling already applied to audio frames before being passed to an effect.
  // Specifically, this represents the _largest_ single gain_dbfs value among this effect's source
  // streams.  It does not account for the accumulated effects of multiple source streams, nor of
  // the actual content of these streams.
  float gain_dbfs;
  // Gain normalized from 0.0 to 1.0 according to the volume curve in use.
  float volume;
} fuchsia_audio_effects_stream_info;

typedef struct {
  // The number of effect types found in the audio_effects lib.  Subsequent APIs that require
  // 'effect_id' will expect values in the range of [ 0, num_effects - 1 ], inclusive.
  uint32_t num_effects;

  // Returns information about this type of effect.
  bool (*get_info)(uint32_t effect_id, fuchsia_audio_effects_description* effect_desc);

  // Returns a 64-bit handle representing an active device effect instance of type ‘effect_id’. In
  // case of failure, FUCHSIA_AUDIO_EFFECTS_INVALID_HANDLE is returned. If channels_in ==
  // channels_out, the created effect must process in-place. Conversely, if channels_in !=
  // channels_out, the effect will never process in-place. Also, the system does not yet handle
  // different channel configurations (i.e. it cannot discern between LRCS and quad).
  fuchsia_audio_effects_handle_t (*create_effect)(uint32_t effect_id, uint32_t frame_rate,
                                                  uint16_t channels_in, uint16_t channels_out,
                                                  const char* config, size_t config_length);

  // Updates the effects operational configuration with the new configuration provided by
  // `config`/`config_length`, replacing any and all configuration values provided when the effect
  // was initially created.
  //
  // Returns `true` iff the new configuration was applied successfully.
  bool (*update_effect_configuration)(fuchsia_audio_effects_handle_t effects_handle,
                                      const char* config, size_t config_length);

  // Deletes an active effect.
  bool (*delete_effect)(fuchsia_audio_effects_handle_t effects_handle);

  // Returns the operational parameters for this instance of the device effect. These parameters
  // are invariant for the lifetime of this effect, based on initial values provided when the
  // client created the effect.
  bool (*get_parameters)(fuchsia_audio_effects_handle_t effects_handle,
                         fuchsia_audio_effects_parameters* effect_params);

  // Synchronously process ‘num_frames’ of audio, in-place. The value of 'num_frames' cannot exceed
  // frame_rate: it must be <= 1 second of audio.
  //
  // `process_inplace` requires that `channels_in` == `channels_out`.
  bool (*process_inplace)(fuchsia_audio_effects_handle_t effects_handle, uint32_t num_frames,
                          float* audio_buff_in_out);

  // Synchronously process ‘num_frames’ from audio_buff_in to audio_buff_out. 'num_frames' cannot
  // exceed frame_rate: it must be <= 1 second of audio. The effect implementation is responsible
  // for allocating the buffer returned in |audio_buf_out|. The frames written into |audio_buf_out|
  // must not be modified until a subsequent call to |process|.
  //
  // `process` requires that `channels_in` != `channels_out`.
  bool (*process)(fuchsia_audio_effects_handle_t effects_handle, uint32_t num_frames,
                  const float* audio_buff_in, float** audio_buff_out);

  // Flushes any cached state this effect identified by `effects_handle`.
  bool (*flush)(fuchsia_audio_effects_handle_t effects_handle);

  // Notifies the effect that properties of the audio frames provided to subsequent calls to
  // `process` or `process_inplace` have changed.
  void (*set_stream_info)(fuchsia_audio_effects_handle_t effects_handle,
                          const fuchsia_audio_effects_stream_info* stream_info);
} fuchsia_audio_effects_module_v1;

// Declare an exported module instance from a loadable plugin module:
//
// DECLARE_FUCHSIA_AUDIO_EFFECTS_MODULE_V1 {
//    .num_effects = 2,
//    .get_info = &my_get_info,
//    ... etc ...
// };
#define DECLARE_FUCHSIA_AUDIO_EFFECTS_MODULE_V1 \
  __EXPORT fuchsia_audio_effects_module_v1 fuchsia_audio_effects_module_v1_instance

__END_CDECLS

#endif  // LIB_MEDIA_AUDIO_EFFECTS_AUDIO_EFFECTS_H_