Add a text file describing AmbDec config file support.

2 files changed, 193 insertions, 6 deletions

diff --git a/alsoft_ambdec.txt b/alsoft_ambdec.txt
new file mode 100644
index 00000000..65965f3b
--- /dev/null
+++ b/alsoft_ambdec.txt
@@ -0,0 +1,182 @@
+AmbDec Configuration Files
+==========================
+
+AmbDec configuration files were developed by Fons Adriaensen as part of the
+AmbDec program <http://kokkinizita.linuxaudio.org/linuxaudio/index.html>.
+
+Starting with OpenAL Soft 1.18, version 3 of the file format is supported as a
+means of specifying custom surround sound speaker layouts. These configuration
+files are also used to enable the high-quality ambisonic decoder.
+
+
+File Format
+===========
+
+As of this writing, there is no official documentation of the .ambdec file
+format. However, the format as OpenAL Soft sees it is as follows:
+
+The file is plain text. Comments start with a hash/pound character (#). There
+may be any amount of whitespace in between the option and parameter values.
+Strings are *not* enclosed in quotation marks.
+
+/description <desc:string>
+Specifies a text description of the configuration. Ingored by OpenAL Soft.
+
+/version <ver:int>
+Declares the format version used by the configuration file. OpenAL Soft
+currently only supports version 3.
+
+/dec/chan_mask <mask:hex>
+Specifies a hexadecimal mask value of ambisonic input channels used by this
+decoder. Counting up from the least significant bit, bit 0 maps to Ambisonic
+Channel Number (ACN) 0, bit 1 maps to ACN 1, etc. As an example, a value of 'b'
+enables bits 0, 1, and 3 (1011 in binary), which correspond to ACN 0, 1, and 3
+(first-order horizontal).
+
+/dec/freq_bands <count:int>
+Specifies the number of frequency bands used by the decoder. This must be 1 for
+single-band or 2 for dual-band.
+
+/dec/speakers <count:int>
+Specifies the number of output speakers to decode to.
+
+/dec/coeff_scale <type:string>
+Specifies the scaling used by the decoder coefficients. Currently recognized
+types are fuma, sn3d, and n3d, for Furse-Malham (FuMa), semi-normalized (SN3D),
+and fully normalized (N3D) scaling, respectively.
+
+/opt/input_scale <name:string>
+Specifies the scaling used by the ambisonic input data. As OpenAL Soft renders
+the data itself and knows the scaling, this is ignored.
+
+/opt/nfeff_comp <dir:string>
+Specifies whether near-field effect compensation is off (not applied at all),
+applied on input (faster, less accurate with varying speaker distances) or
+output (slower, more accurate with varying speaker distances). Ignored by
+OpenAL Soft.
+
+/opt/delay_comp <onoff:bool>
+Specifies whether delay compensation is applied for output. This is used to
+correct for time variations caused by different speaker distances. As OpenAL
+Soft has its own config option for this, this is ignored.
+
+/opt/level_comp <onoff:bool>
+Specifies whether gain compensation is applied for output. This is used to
+correct for volume variations caused by different speaker distances. As OpenAL
+Soft has its own config option for this, this is ignored.
+
+/opt/xover_freq <freq:int>
+Specifies the crossover frequency for dual-band decoders. Frequencies less than
+this are fed to the low-frequency matrix, and frequencies greater than this are
+fed to the high-freqyency matrix. Unused for single-band decoders.
+
+/opt/xover_ratio <decibels:float>
+Specifies the volume ratio between the frequency bands. Values greater than 0
+decrease the low-frequency output by half the specified value and increase the
+high-frequency output by half the specified value, while values less than 0
+increase the low-frequency output and decrease the high-frequency output to
+similar effect. Unused for single-band decoders.
+
+/speakers/{
+Begins the output speaker definitions. A speaker is defined using the add_spkr
+command, and there must be a matching number of speaker definitions as the
+specified speaker count. The definitions are ended with a "/}".
+
+add_spkr <id:string> <dist:float> <azi:float> <elev:float> <connection:string>
+Defines an output speaker. The ID is a string identifier for the output speaker
+(see Speaker IDs below). The distance is in meters from the center-point of the
+physical speaker array. The azimuth is the horizontal angle of the speaker, in
+degrees, where 0 is directly front and positive values go left. The elevation
+is the vertical angle of the speaker, in degrees, where 0 is directly front and
+positive goes upward. The connection string is the JACK port name the speaker
+should connect to. Currently, OpenAL Soft uses the ID and distance, and ignores
+the rest.
+
+/lfmatrix/{
+Begins the low-frequency decoder matrix definition. The definition should
+include an order_gain command to specify the base gain for the ambisonic
+orders. Each matrix row is defined using the add_row command, and there must be
+a matching number of rows as the number of speakers. Additionally the row
+definitions are in the same order as the speaker definitions. The definitions
+are ended with a "/}". Only valid for dual-band decoders.
+
+/hfmatrix/{
+Begins the high-frequency decoder matrix definition. The definition should
+include an order_gain command to specify the base gain for the ambisonic
+orders. Each matrix row is defined using the add_row command, and there must be
+a matching number of rows as the number of speakers, Additionally the row
+definitions are in the same order as the speaker definitions. The definitions
+are ended with a "/}". Only valid for dual-band decoders.
+
+/matrix/{
+Begins the decoder matrix definition. The definition should include an
+order_gain command to specify the base gain for the ambisonic orders. Each
+matrix row is defined using the add_row command, and there must be a matching
+number of rows as the number of speakers. Additionally the row definitions are
+in the same order as the speaker definitions. The definitions are ended with a
+"/}". Only valid for single-band decoders.
+
+order_gain <gain:float> <gain:float> <gain:float> <gain:float>
+Specifies the base gain for the zeroth-, first-, second-, and third-order
+coefficients in the given matrix, automatically scaling the related
+coefficients. This should be specified at the beginning of the matrix
+definition.
+
+add_row <coefficient:float> ...
+Specifies a row of coefficients for the matrix. There should be one coefficient
+for each enabled bit in the channel mask, and corresponds to the matching ACN
+channel.
+
+/end
+Marks the end of the configuration file.
+
+
+Speaker IDs
+===========
+
+The AmbDec program uses the speaker ID as a label to display in its config
+dialog, but does not otherwise use it for any particular purpose. However,
+since OpenAL Soft needs to match a speaker definition to an output channel, the
+speaker ID is used to identify what output channel it correspond to. Therefore,
+OpenAL Soft requires these channel labels to be recognized:
+
+LF = Front left
+RF = Front right
+LS = Side left
+RS = Side right
+LB = Back left
+RB = Back right
+CE = Front center
+CB = Back center
+
+Additionally, configuration files for surround51 will acknowledge back speakers
+for side channels, and surround51rear will acknowledge side speakers for back
+channels, to avoid issues with a configuration expecting 5.1 to use the side
+channels when the device is configured for back, or vice-versa.
+
+Furthermore, OpenAL Soft does not require a speaker definition for each output
+channel the configuration is used with. So for example a 5.1 configuration may
+omit a front center speaker definition, in which case the front center output
+channel will not contribute to the ambisonic decode (though OpenAL Soft will
+still use it in certain scenarios, such as the AL_EFFECT_DEDICATED_DIALOGUE
+effect).
+
+
+Creating Configuration Files
+============================
+
+Configuration files can be created or modified by hand in a text editor. The
+AmbDec program also has a GUI for creating and editing them. However, these
+methods rely on you having the coefficients to fill in... they won't be
+generated for you.
+
+Another option is to use the Ambisonic Decoder Toolbox
+<https://bitbucket.org/ambidecodertoolbox/adt.git>. This is a collection of
+MATLAB and GNU Octave scripts that can generate AmbDec configuration files from
+an array of speaker definitions (labels and positions). If you're familiar with
+using MATLAB or GNU Octave, this may be a good option.
+
+There are plans for OpenAL Soft to include a utility to generate coefficients
+and make configuration files. However, calculating proper coefficients for
+anything other than regular or semi-regular speaker setups is somewhat of a
+black art, so may take some time.
diff --git a/alsoftrc.sample b/alsoftrc.sample
index 353b5573..3a22914d 100644
--- a/alsoftrc.sample
+++ b/alsoftrc.sample
@@ -227,24 +227,29 @@ hq-mode = false
 distance-comp = true
 
 ## quad:
-#  Decoder configuration file for Quadrophonic channel output.
+#  Decoder configuration file for Quadrophonic channel output. See
+#  alsoft_ambdec.txt for a description of the file format.
 quad =
 
 ## surround51:
-#  Decoder configuration file for 5.1 Surround (Side) channel output.
+#  Decoder configuration file for 5.1 Surround (Side) channel output. See
+#  alsoft_ambdec.txt for a description of the file format.
 surround51 =
 
 ## surround51rear:
-#  Decoder configuration file for 5.1 Surround (Rear) channel output.
+#  Decoder configuration file for 5.1 Surround (Rear) channel output. See
+#  alsoft_ambdec.txt for a description of the file format.
 surround51rear =
 
 ## surround61:
-#  Decoder configuration file for 6.1 Surround channel output.
+#  Decoder configuration file for 6.1 Surround channel output. See
+#  alsoft_ambdec.txt for a description of the file format.
 surround61 =
 
 ## surround71:
-#  Decoder configuration file for 7.1 Surround channel output. Note: This can
-#  be used to enable 3D7.1 with the appropriate configuration file and speaker
+#  Decoder configuration file for 7.1 Surround channel output. See
+#  alsoft_ambdec.txt for a description of the file format. Note: This can be
+#  used to enable 3D7.1 with the appropriate configuration file and speaker
 #  placement.
 surround71 =