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