diff options
Diffstat (limited to 'alsoft_ambdec.txt')
| -rw-r--r-- | alsoft_ambdec.txt | 182 |
1 files changed, 0 insertions, 182 deletions
diff --git a/alsoft_ambdec.txt b/alsoft_ambdec.txt deleted file mode 100644 index 0afc5064..00000000 --- a/alsoft_ambdec.txt +++ /dev/null @@ -1,182 +0,0 @@ -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. 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-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. |