Merge pull request #142 from OzGav/DSP

Add DSP settings info

docs/dsp/parametriceq.md

@@ -0,0 +1,39 @@
+---
+title: DSP Parametric Equalizer
+description: Explanation of the use and effect of the DSP Parametric Equalizer filter
+---
+
+# Parametric Equalizer
+
+A Parametric Equalizer (PEQ) is a [powerful tool](https://www.masteringbox.com/learn/parametric-eq) for fine-tuning audio. Unlike simpler tone controls, a PEQ allows precise adjustment of specific frequency ranges.
+
+PEQs can be used to tailor the sound to a room's acoustics, compensate for speaker or headphone characteristics, or to fine-tune the frequency balance to personal taste.
+
+Multiple PEQ filters can be added to the MA signal path if desired.
+
+## Usage
+
+### Frequency Band Adjustment
+
+Unlimited bands can be added to the PEQ. For each band it is possible to control:
+
+- **Frequency:** The center frequency to be adjusted (e.g., 100Hz for bass, 1kHz for midrange, 10kHz for treble).
+
+- **Gain:** How much boost (increased volume) or cut (decreased volume) to be applied to that frequency, measured in decibels (dB).
+
+- **Q (Quality Factor):** This determines the width of the frequency range affected. A higher Q means a narrower, more focused adjustment, while a lower Q creates a broader, gentler change.
+
+- **Filter Type:** This determines the [shape of the adjustment](https://www.musicguymixing.com/eq-filters/). The available options are Peak (aka Bell), High Shelf, Low Shelf, High Pass, Low Pass, and Notch. 
+
+### Presets
+
+If you have measured your speakers, or want to correct your headphones with [AutoEQ](https://autoeq.app/), you can automatically import a preset into this filter.
+
+Music Assistant accepts [Equalizer APO's Parametric EQ](https://equalizerapo.com) file format which is widely adopted in various applications, and this import functionality also works seamlessly with [Room EQ Wizard](https://www.roomeqwizard.com) (REW)'s `Export filter settings as text file format`.
+While not all filter types are supported (Modal, BP, LSC x dB, HS x dB, AP, LS with dB slope, HS with dB slope), the most important ones are functional.
+
+Currently, the Preamp option is not supported. This may change in the future.
+
+It is possible to import Equalizer presets from various sources including, [EasyEffects](https://wwmm.github.io/easyeffects/) (as APO preset) and REW-compatible presets from [HouseCurve](https://housecurve.com/)
+
+The Equalizer can also be exported for use in other applications. For example, the data could be used in: APO, another Music Assistant instance, or EasyEffects.

docs/dsp/tonecontrols.md

@@ -0,0 +1,18 @@
+---
+title: DSP Tone Controls
+description: Explanation of the use and effect of the DSP Tone Controls filter
+---
+
+# Tone Controls
+
+Tone controls provide simple frequency adjustments, which allows the boosting or reducing of the bass and treble regions of the music sent to the player.
+
+## Usage
+
+There are three controls available, Bass, Mid and Treble. These correspond to a range of frequencies centred on 100Hz, 900Hz and 9000Hz. Boosting or cutting the volume of the audio signal around these centres is accomplished by adjusting the three sliders.
+
+## Technical Details
+
+The tone controls apply a basic three frequency [Parametric Equaliser](parametriceq.md) filter to the audio signal utilising the Peak (aka Bell) filter type. The following image shows the resultant effect of setting all three controls to +4.0dB
+
+![Tone Controls](../assets/screenshots/tone-controls.jpg)

docs/player-support/index.md

@@ -23,3 +23,30 @@ Players can only be deleted if they are unavailable or disabled. Deleting a play
 Audio quality is the principal reason why native MA players are developed. These players provide the highest quality playback experience. HA players should work and may work well but they may also have been written with a basic objective such as enabling text to speech. Therefore, if there is a MA player available and a HA integration then you should always choose the MA player. 
 
 A sample rate above 48kHz or a bit depth above 16 is considered High Resolution (Hi Res)
+
+## DSP Settings
+
+This functionality is available in MA 2.4.0 and later.
+
+All providers have the option to apply [Digital Signal Processing](https://en.wikipedia.org/wiki/Digital_signal_processing) (DSP) filters to the audio stream. DSP lets you shape and refine the audio with a variety of filters. Use it to tailor the sound to a room's acoustics, compensate for speaker characteristics, and fine-tune the frequency balance to personal taste.
+
+The DSP option is found in the MA settings for each player which means that each player has its own independently configurable DSP settings.
+
+DSP settings will be disabled for all groups except AirPlay and Snapcast.
+
+The DSP path consists of an INPUT pre-amplifier for initial gain control, followed by optional audio filters that can be added between input and output (multiple times if desired). The following filters are avialable:
+
+- [Parametric Equalizer](../dsp/parametriceq.md)
+- [Tone Controls](../dsp/tonecontrols.md)
+
+The path ends with an OUTPUT stage that provides both gain control and a limiter (enabled by default) to prevent signal clipping.
+
+The DSP settings can be enabled and disabled via a toggle which allows easy [A-B testing](https://www.youtube.com/watch?v=KefGjPYyIO4)
+
+The line on the left of the DSP settings represents the audio path, in sequential order, from the audio file (top) to the player (bottom).
+
+A dot on the line represents a component that changes the signal. The lack of a dot indicates that the particular component has been disabled.
+
+Using the icons at the top of the view, the additional filters can be reordered, disabled/enabled or deleted.
+
+![DSP image](../assets/screenshots/dsp.jpg)

mkdocs.yml

@@ -23,6 +23,8 @@ nav:
     - General: usage.md
     - UI: ui.md
     - Groups: faq/groups.md
+    - DSP Parametric EQ: dsp/parametriceq.md
+    - DSP Tone Controls: dsp/tonecontrols.md
     - How Do I...: faq/how-to.md
     - I Want To Stream To: faq/stream-to.md
     - Technical Info: faq/tech-info.md