Engine Configuration

Amplitude has been built in a way to let you have complete freedom on the behavior of the engine at runtime. You can create several configuration files per device (PC, mobile, console), per platform (Windows, Android, XBOX, PlayStation), or any other criteria your project has to suit, then pick and load the right settings file at runtime.

The config file will let you customize:

• The playback device (output)
• The Amplitude Mixer, called Amplimix (mixer)
• The synchronization with the game/engine (game)
• The path to the buses file (buses_file)
• The name of the driver implementation to use (driver)

output#

object required

The output property helps you define how Amplitude should communicate with the physical audio device. It takes as value a map with the following properties:

frequency#

uint default: 48000

The frequency property defines the audio frequency in Hertz (Hz) of the audio data sent to the audio device by Amplitude. This value may differ from the frequency of the audio device, in such a scenario, the audio data will be resampled from this value to the device’s frequency.

channels#

enum default: Stereo

The channels property sets the number of channels Amplitude will output. It can take as value the name of that channel or the number of channels. Possible values are:

buffer_size#

int default: 1024

This value defines the number of audio bytes used per output. The number of samples to produce for each output will be calculated automatically by dividing this value by the number of channels. It is highly recommended to use a multiple of 2 for the buffer size.

format#

enum default: Float32

The format property specifies the audio format in which Amplitude will send the audio data to the output device. It can take as value the name of the audio format or the audio format ID:

mixer#

object required

The mixer property configures the Amplitude Mixer (Amplimix). It takes as value an object with the following properties:

active_channels#

uint required

Specifies the maximum number of sound channels to render by Amplimix. It equals the number of sounds simultaneously playing in the game. If the maximum number of channels is reached, Amplitude will prioritize the most important channels and virtualize the others.

virtual_channels#

uint required

Specifies the maximum number of virtual channels to use in addition to active channels. Amplimix doesn’t render virtual channels, but all the information about them is still tracked.

pipeline#

array required

It’s inside the pipeline setting you describe the graph in which audio data will be processed before it is sent to the audio device for rendering. This setting takes as value an array of sound processor definitions that will be applied to the audio data. For further explanation about how to set up a pipeline, see the Pipeline & Sound Processors guide.

game#

object required

This setting is used by Amplitude to understand how it should synchronize with the game, how to handle game and sound objects, and how to render sounds in the game environment. This is achieved by specifying a set of inner values in this setting.

listener_fetch_mode#

enum default: Nearest

Since Amplitude allows you to define many listeners at the same time, but only one can render data for a single sound object, this setting is used to define how the engine will pick the right listener for each rendered sound object. Available values are:

By using Nearest or Farthest, different listeners may be used at the same time for each playback. Using Default, First, or Last may ensure that the same listener is used for every playback.

listeners#

uint default: 1

The listeners property specifies the maximum number of listeners to pre-allocate. You will not be able to create more [Listener] objects than that value at runtime.

entities#

uint default: 4096

The entities property specifies the maximum number of game entities to pre-allocate. This value does not represent all the entities of your game or scene but only the approximate number of entities managed by the Amplitude Engine. You will not be able to create more [Entity] objects than that value at runtime.

environments#

uint default: 64

The environments property specifies the maximum number of sound environments to pre-allocate. Sound environments are spaces in the 3D environment of the game where Amplitude may process specific effects and attenuation models. You will not be able to create more [Environment] objects than that value at runtime.

sound_speed#

float default: 343.0

This property sets the speed of sound (in meters per second) in the game. This value will be used by the engine to process some effects like the Doppler effect. If the value is not defined, it will default to 343.0, which is the approximated value of the real speed of sound.

doppler_factor#

float default: 1.0

This property takes a float value greater or equal to 0.0. It will affect how much power is given to the Doppler effect. A value of 0.0 will disable the Doppler effect, while a value of 1.0 will render it as it should. Any other value will affect the sound pitch.

up_axis#

enum default: Y

This property may help you to not perform additional math while integrating Amplitude in your game or your game engine. It specifies the up-axis you use in your game. Possible values are:

This setting will only affect how math operations on vectors and matrices are performed internally in the engine.

obstruction#

object required

The obstruction property lets you set up the way Amplitude will compute sound obstruction in the game. It takes as value an object with the following properties:

• lpf_curve: Set the Low-Pass Filter curve for the obstruction sound processor.
• gain_curve: Set the gain curve for the obstruction sound processor.

occlusion#

object required

The occlusion property works the same as the obstruction property, but it’s used instead to instruct Amplitude on how to process sound occlusion in the game.

track_environments#

boolean default: true

Defines whether the game is tracking environments. This means that the game will compute and send the environment amounts to the engine. This implies that the shapes defined in environments (if any) will not be used.

Setting this value to false will instruct Amplitude to track environment amounts by himself. This way, Amplitude will use the environment shapes and the positions of the entities playing the sounds to compute the environment amounts.

buses_file#

string required

The buses_file property defines the path to the binary (.ambus) file that contains the buses definitions. Only one bus file can be loaded per engine configuration.

driver#

string required

The driver property indicates the name of the audio Driver implementation communicating with the physical audio device. You can implement multiple audio drivers as needed and register them in the engine with the plugin API. Read the Writing Drivers guide to learn how to do it.

Example#

The following example describes an engine configuration file:

{
  "output": {
    "frequency": 44100,
    "channels": 2,
    "buffer_size": 1024,
    "format": "Float32"
  },
  "mixer": {
    "active_channels": 50,
    "virtual_channels": 100,
    "pipeline_type": [
      "AudioSoundProcessor",
      "AudioSoundProcessor",
      "AudioProcessorMixer"
    ],
    "pipeline": [
      {
        "processor": "EffectProcessor"
      },
      {
        "processor": "OcclusionProcessor"
      },
      {
        "dry_processor": "ObstructionProcessor",
        "wet_processor": "EnvironmentProcessor",
        "dry": 0.5,
        "wet": 0.5
      }
    ]
  },
  "game": {
    "listener_fetch_mode": "Nearest",
    "track_environments": true,
    "up_axis": "Y",
    "listeners": 100,
    "entities": 4096,
    "environments": 512,
    "sound_speed": 333,
    "doppler_factor": 1.0,
    "obstruction": {
      "lpf_curve": {
        "parts": [
          {
            "start": {
              "x": 0,
              "y": 0
            },
            "end": {
              "x": 1,
              "y": 1
            },
            "fader": "Linear"
          }
        ]
      },
      "gain_curve": {
        "parts": [
          {
            "start": {
              "x": 0,
              "y": 1
            },
            "end": {
              "x": 1,
              "y": 0
            },
            "fader": "Linear"
          }
        ]
      }
    },
    "occlusion": {
      "lpf_curve": {
        "parts": [
          {
            "start": {
              "x": 0,
              "y": 0
            },
            "end": {
              "x": 1,
              "y": 1
            },
            "fader": "Linear"
          }
        ]
      },
      "gain_curve": {
        "parts": [
          {
            "start": {
              "x": 0,
              "y": 1
            },
            "end": {
              "x": 1,
              "y": 0
            },
            "fader": "Linear"
          }
        ]
      }
    }
  },
  "buses_file": "buses.ambus",
  "driver": "miniaudio"
}