alsoft_ambdec.txt

   1 AmbDec Configuration Files
   2 ==========================
   3
   4 AmbDec configuration files were developed by Fons Adriaensen as part of the
   5 AmbDec program <http://kokkinizita.linuxaudio.org/linuxaudio/index.html>.
   6
   7 Starting with OpenAL Soft 1.18, version 3 of the file format is supported as a
   8 means of specifying custom surround sound speaker layouts. These configuration
   9 files are also used to enable the high-quality ambisonic decoder.
  10
  11
  12 File Format
  13 ===========
  14
  15 As of this writing, there is no official documentation of the .ambdec file
  16 format. However, the format as OpenAL Soft sees it is as follows:
  17
  18 The file is plain text. Comments start with a hash/pound character (#). There
  19 may be any amount of whitespace in between the option and parameter values.
  20 Strings are *not* enclosed in quotation marks.
  21
  22 /description <desc:string>
  23 Specifies a text description of the configuration. Ingored by OpenAL Soft.
  24
  25 /version <ver:int>
  26 Declares the format version used by the configuration file. OpenAL Soft
  27 currently only supports version 3.
  28
  29 /dec/chan_mask <mask:hex>
  30 Specifies a hexadecimal mask value of ambisonic input channels used by this
  31 decoder. Counting up from the least significant bit, bit 0 maps to Ambisonic
  32 Channel Number (ACN) 0, bit 1 maps to ACN 1, etc. As an example, a value of 'b'
  33 enables bits 0, 1, and 3 (1011 in binary), which correspond to ACN 0, 1, and 3
  34 (first-order horizontal).
  35
  36 /dec/freq_bands <count:int>
  37 Specifies the number of frequency bands used by the decoder. This must be 1 for
  38 single-band or 2 for dual-band.
  39
  40 /dec/speakers <count:int>
  41 Specifies the number of output speakers to decode to.
  42
  43 /dec/coeff_scale <type:string>
  44 Specifies the scaling used by the decoder coefficients. Currently recognized
  45 types are fuma, sn3d, and n3d, for Furse-Malham (FuMa), semi-normalized (SN3D),
  46 and fully normalized (N3D) scaling, respectively.
  47
  48 /opt/input_scale <name:string>
  49 Specifies the scaling used by the ambisonic input data. As OpenAL Soft renders
  50 the data itself and knows the scaling, this is ignored.
  51
  52 /opt/nfeff_comp <dir:string>
  53 Specifies whether near-field effect compensation is off (not applied at all),
  54 applied on input (faster, less accurate with varying speaker distances) or
  55 output (slower, more accurate with varying speaker distances). Ignored by
  56 OpenAL Soft.
  57
  58 /opt/delay_comp <onoff:bool>
  59 Specifies whether delay compensation is applied for output. This is used to
  60 correct for time variations caused by different speaker distances. As OpenAL
  61 Soft has its own config option for this, this is ignored.
  62
  63 /opt/level_comp <onoff:bool>
  64 Specifies whether gain compensation is applied for output. This is used to
  65 correct for volume variations caused by different speaker distances. As OpenAL
  66 Soft has its own config option for this, this is ignored.
  67
  68 /opt/xover_freq <freq:int>
  69 Specifies the crossover frequency for dual-band decoders. Frequencies less than
  70 this are fed to the low-frequency matrix, and frequencies greater than this are
  71 fed to the high-freqyency matrix. Unused for single-band decoders.
  72
  73 /opt/xover_ratio <decibels:float>
  74 Specifies the volume ratio between the frequency bands. Values greater than 0
  75 decrease the low-frequency output by half the specified value and increase the
  76 high-frequency output by half the specified value, while values less than 0
  77 increase the low-frequency output and decrease the high-frequency output to
  78 similar effect. Unused for single-band decoders.
  79
  80 /speakers/{
  81 Begins the output speaker definitions. A speaker is defined using the add_spkr
  82 command, and there must be a matching number of speaker definitions as the
  83 specified speaker count. The definitions are ended with a "/}".
  84
  85 add_spkr <id:string> <dist:float> <azi:float> <elev:float> <connection:string>
  86 Defines an output speaker. The ID is a string identifier for the output speaker
  87 (see Speaker IDs below). The distance is in meters from the center-point of the
  88 physical speaker array. The azimuth is the horizontal angle of the speaker, in
  89 degrees, where 0 is directly front and positive values go left. The elevation
  90 is the vertical angle of the speaker, in degrees, where 0 is directly front and
  91 positive goes upward. The connection string is the JACK port name the speaker
  92 should connect to. Currently, OpenAL Soft uses the ID and distance, and ignores
  93 the rest.
  94
  95 /lfmatrix/{
  96 Begins the low-frequency decoder matrix definition. The definition should
  97 include an order_gain command to specify the base gain for the ambisonic
  98 orders. Each matrix row is defined using the add_row command, and there must be
  99 a matching number of rows as the number of speakers. Additionally the row
 100 definitions are in the same order as the speaker definitions. The definitions
 101 are ended with a "/}". Only valid for dual-band decoders.
 102
 103 /hfmatrix/{
 104 Begins the high-frequency decoder matrix definition. The definition should
 105 include an order_gain command to specify the base gain for the ambisonic
 106 orders. Each matrix row is defined using the add_row command, and there must be
 107 a matching number of rows as the number of speakers, Additionally the row
 108 definitions are in the same order as the speaker definitions. The definitions
 109 are ended with a "/}". Only valid for dual-band decoders.
 110
 111 /matrix/{
 112 Begins the decoder matrix definition. The definition should include an
 113 order_gain command to specify the base gain for the ambisonic orders. Each
 114 matrix row is defined using the add_row command, and there must be a matching
 115 number of rows as the number of speakers. Additionally the row definitions are
 116 in the same order as the speaker definitions. The definitions are ended with a
 117 "/}". Only valid for single-band decoders.
 118
 119 order_gain <gain:float> <gain:float> <gain:float> <gain:float>
 120 Specifies the base gain for the zeroth-, first-, second-, and third-order
 121 coefficients in the given matrix, automatically scaling the related
 122 coefficients. This should be specified at the beginning of the matrix
 123 definition.
 124
 125 add_row <coefficient:float> ...
 126 Specifies a row of coefficients for the matrix. There should be one coefficient
 127 for each enabled bit in the channel mask, and corresponds to the matching ACN
 128 channel.
 129
 130 /end
 131 Marks the end of the configuration file.
 132
 133
 134 Speaker IDs
 135 ===========
 136
 137 The AmbDec program uses the speaker ID as a label to display in its config
 138 dialog, but does not otherwise use it for any particular purpose. However,
 139 since OpenAL Soft needs to match a speaker definition to an output channel, the
 140 speaker ID is used to identify what output channel it correspond to. Therefore,
 141 OpenAL Soft requires these channel labels to be recognized:
 142
 143 LF = Front left
 144 RF = Front right
 145 LS = Side left
 146 RS = Side right
 147 LB = Back left
 148 RB = Back right
 149 CE = Front center
 150 CB = Back center
 151
 152 Additionally, configuration files for surround51 will acknowledge back speakers
 153 for side channels, and surround51rear will acknowledge side speakers for back
 154 channels, to avoid issues with a configuration expecting 5.1 to use the side
 155 channels when the device is configured for back, or vice-versa.
 156
 157 Furthermore, OpenAL Soft does not require a speaker definition for each output
 158 channel the configuration is used with. So for example a 5.1 configuration may
 159 omit a front center speaker definition, in which case the front center output
 160 channel will not contribute to the ambisonic decode (though OpenAL Soft will
 161 still use it in certain scenarios, such as the AL_EFFECT_DEDICATED_DIALOGUE
 162 effect).
 163
 164
 165 Creating Configuration Files
 166 ============================
 167
 168 Configuration files can be created or modified by hand in a text editor. The
 169 AmbDec program also has a GUI for creating and editing them. However, these
 170 methods rely on you having the coefficients to fill in... they won't be
 171 generated for you.
 172
 173 Another option is to use the Ambisonic Decoder Toolbox
 174 <https://bitbucket.org/ambidecodertoolbox/adt.git>. This is a collection of
 175 MATLAB and GNU Octave scripts that can generate AmbDec configuration files from
 176 an array of speaker definitions (labels and positions). If you're familiar with
 177 using MATLAB or GNU Octave, this may be a good option.
 178
 179 There are plans for OpenAL Soft to include a utility to generate coefficients
 180 and make configuration files. However, calculating proper coefficients for
 181 anything other than regular or semi-regular speaker setups is somewhat of a
 182 black art, so may take some time.