diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/ambdec.txt | 182 | ||||
| -rw-r--r-- | docs/env-vars.txt | 81 | ||||
| -rw-r--r-- | docs/hrtf.txt | 74 |
3 files changed, 337 insertions, 0 deletions
diff --git a/docs/ambdec.txt b/docs/ambdec.txt new file mode 100644 index 00000000..0afc5064 --- /dev/null +++ b/docs/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. 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. diff --git a/docs/env-vars.txt b/docs/env-vars.txt new file mode 100644 index 00000000..b2268643 --- /dev/null +++ b/docs/env-vars.txt @@ -0,0 +1,81 @@ +Useful Environment Variables + +Below is a list of environment variables that can be set to aid with running or +debugging apps that use OpenAL Soft. They should be set before the app is run. + +*** Logging *** + +ALSOFT_LOGLEVEL +Specifies the amount of logging OpenAL Soft will write out: +0 - Effectively disables all logging +1 - Prints out errors only +2 - Prints out warnings and errors +3 - Prints out additional information, as well as warnings and errors +4 - Same as 3, but also device and context reference count changes. This will + print out *a lot* of info, and is generally not useful unless you're trying + to track a reference leak within the library. + +ALSOFT_LOGFILE +Specifies a filename that logged output will be written to. Note that the file +will be first cleared when logging is initialized. + +*** Overrides *** + +ALSOFT_CONF +Specifies an additional configuration file to load settings from. These +settings will take precedence over the global and user configs, but not other +environment variable settings. + +ALSOFT_DRIVERS +Overrides the drivers config option. This specifies which backend drivers to +consider or not consider for use. Please see the drivers option in +alsoftrc.sample for a list of available drivers. + +ALSOFT_DEFAULT_REVERB +Specifies the default reverb preset to apply to sources. Please see the +default-reverb option in alsoftrc.sample for additional information and a list +of available presets. + +ALSOFT_TRAP_AL_ERROR +Set to "true" or "1" to force trapping AL errors. Like the trap-al-error config +option, this will raise a SIGTRAP signal (or a breakpoint exception under +Windows) when a context-level error is generated. Useful when run under a +debugger as it will break execution right when the error occurs, making it +easier to track the cause. + +ALSOFT_TRAP_ALC_ERROR +Set to "true" or "1" to force trapping ALC errors. Like the trap-alc-error +config option, this will raise a SIGTRAP signal (or a breakpoint exception +under Windows) when a device-level error is generated. Useful when run under a +debugger as it will break execution right when the error occurs, making it +easier to track the cause. + +ALSOFT_TRAP_ERROR +Set to "true" or "1" to force trapping both ALC and AL errors. + +*** Compatibility *** + +__ALSOFT_HALF_ANGLE_CONES +Older versions of OpenAL Soft incorrectly calculated the cone angles to range +between 0 and 180 degrees, instead of the expected range of 0 to 360 degrees. +Setting this to "true" or "1" restores the old buggy behavior, for apps that +were written to expect the incorrect range. + +__ALSOFT_REVERSE_Z +Applications that don't natively use OpenAL's coordinate system have to convert +to it before passing in 3D coordinates. Depending on how exactly this is done, +it can cause correct output for stereo but incorrect Z panning for surround +sound (i.e., sounds that are supposed to be behind you sound like they're in +front, and vice-versa). Setting this to "true" or "1" will negate the localized +Z coordinate to attempt to fix output for apps that have incorrect front/back +panning. + +__ALSOFT_SUSPEND_CONTEXT +Due to the OpenAL spec not being very clear about them, behavior of the +alcSuspendContext and alcProcessContext methods has varied, and because of +that, previous versions of OpenAL Soft had them no-op. Creative's hardware +drivers and the Rapture3D driver, however, use these methods to batch changes, +which some applications make use of to protect against partial updates. In an +attempt to standardize on that behavior, OpenAL Soft has changed those methods +accordingly. Setting this to "ignore" restores the previous no-op behavior for +applications that interact poorly with the new behavior. diff --git a/docs/hrtf.txt b/docs/hrtf.txt new file mode 100644 index 00000000..37a329d2 --- /dev/null +++ b/docs/hrtf.txt @@ -0,0 +1,74 @@ +HRTF Support +============ + +Starting with OpenAL Soft 1.14, HRTFs can be used to enable enhanced +spatialization for both 3D (mono) and multi-channel sources, when used with +headphones/stereo output. This can be enabled using the 'hrtf' config option. + +For multi-channel sources this creates a virtual speaker effect, making it +sound as if speakers provide a discrete position for each channel around the +listener. For mono sources this provides much more versatility in the perceived +placement of sounds, making it seem as though they are coming from all around, +including above and below the listener, instead of just to the front, back, and +sides. + +The default data set is based on the KEMAR HRTF data provided by MIT, which can +be found at <http://sound.media.mit.edu/resources/KEMAR.html>. It's only +available when using 44100hz or 48000hz playback. + + +Custom HRTF Data Sets +===================== + +OpenAL Soft also provides an option to use user-specified data sets, in +addition to or in place of the default set. This allows users to provide their +own data sets, which could be better suited for their heads, or to work with +stereo speakers instead of headphones, or to support more playback sample +rates, for example. + +The file format is specified below. It uses little-endian byte order. + +== +ALchar magic[8] = "MinPHR01"; +ALuint sampleRate; + +ALubyte hrirSize; /* Can be 8 to 128 in steps of 8. */ +ALubyte evCount; /* Can be 5 to 128. */ + +ALubyte azCount[evCount]; /* Each can be 1 to 128. */ + +/* NOTE: hrirCount is the sum of all azCounts */ +ALshort coefficients[hrirCount][hrirSize]; +ALubyte delays[hrirCount]; /* Each can be 0 to 63. */ +== + +The data is described as thus: + +The file first starts with the 8-byte marker, "MinPHR01", to identify it as an +HRTF data set. This is followed by an unsigned 32-bit integer, specifying the +sample rate the data set is designed for (OpenAL Soft will not use it if the +output device's playback rate doesn't match). + +Afterward, an unsigned 8-bit integer specifies how many sample points (or +finite impulse response filter coefficients) make up each HRIR. + +The following unsigned 8-bit integer specifies the number of elevations used +by the data set. The elevations start at the bottom (-90 degrees), and +increment upwards. Following this is an array of unsigned 8-bit integers, one +for each elevation which specifies the number of azimuths (and thus HRIRs) that +make up each elevation. Azimuths start clockwise from the front, constructing +a full circle for the left ear only. The right ear uses the same HRIRs but in +reverse (ie, left = angle, right = 360-angle). + +The actual coefficients follow. Each coefficient is a signed 16-bit sample, +with each HRIR being a consecutive number of sample points. The HRIRs must be +minimum-phase. This allows the use of a smaller filter length, reducing +computation. For reference, the built-in data set uses a 32-point filter while +even the smallest data set provided by MIT used a 128-sample filter (a 4x +reduction by applying minimum-phase reconstruction). Theoretically, one could +further reduce the minimum-phase version down to a 16-point filter with only a +small reduction in quality. + +After the coefficients is an array of unsigned 8-bit delay values, one for +each HRIR. This is the propagation delay (in samples) a signal must wait before +being convolved with the corresponding minimum-phase HRIR filter. |