diff options
Diffstat (limited to 'docs/ambdec.txt')
| -rw-r--r-- | docs/ambdec.txt | 189 |
1 files changed, 189 insertions, 0 deletions
diff --git a/docs/ambdec.txt b/docs/ambdec.txt new file mode 100644 index 00000000..1f328937 --- /dev/null +++ b/docs/ambdec.txt @@ -0,0 +1,189 @@ +AmbDec Configuration Files +========================== + +AmbDec configuration files were developed by Fons Adriaensen as part of the +AmbDec program <http://kokkinizita.linuxaudio.org/linuxaudio/index.html>. + +The file works by specifying a decoder matrix or matrices which transform +ambisonic channels into speaker feeds. Single-band decoders specify a single +matrix that transforms all frequencies, while dual-band decoders specifies two +matrices where one transforms low frequency sounds and the other transforms +high frequency sounds. See docs/ambisonics.txt for more general information +about ambisonics. + +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. Ignored 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:float> +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-frequency 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. |