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 the high-quality ambisonic decoder.
  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-freqyency 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
 159 Additionally, configuration files for surround51 will acknowledge back speakers
 160 for side channels, and surround51rear will acknowledge side speakers for back
 161 channels, to avoid issues with a configuration expecting 5.1 to use the side
 162 channels when the device is configured for back, or vice-versa.
 163
 164 Furthermore, OpenAL Soft does not require a speaker definition for each output
 165 channel the configuration is used with. So for example a 5.1 configuration may
 166 omit a front center speaker definition, in which case the front center output
 167 channel will not contribute to the ambisonic decode (though OpenAL Soft will
 168 still use it in certain scenarios, such as the AL_EFFECT_DEDICATED_DIALOGUE
 169 effect).
 170
 171
 172 Creating Configuration Files
 173 ============================
 174
 175 Configuration files can be created or modified by hand in a text editor. The
 176 AmbDec program also has a GUI for creating and editing them. However, these
 177 methods rely on you having the coefficients to fill in... they won't be
 178 generated for you.
 179
 180 Another option is to use the Ambisonic Decoder Toolbox
 181 <https://bitbucket.org/ambidecodertoolbox/adt.git>. This is a collection of
 182 MATLAB and GNU Octave scripts that can generate AmbDec configuration files from
 183 an array of speaker definitions (labels and positions). If you're familiar with
 184 using MATLAB or GNU Octave, this may be a good option.
 185
 186 There are plans for OpenAL Soft to include a utility to generate coefficients
 187 and make configuration files. However, calculating proper coefficients for
 188 anything other than regular or semi-regular speaker setups is somewhat of a
 189 black art, so may take some time.