docs: split user's manual into smaller files

Author: hvianna

docs/README.md

@@ -49,7 +49,7 @@ When uninstalling you'll have the option to also **delete app data -- this will
 
 On Windows, you can also uninstall via Control Panel.
 
-?> See the [User's Manual](users-manual.md) for the complete documentation of audioMotion's features and settings.
+?> See the [User's Manual](user-interface.md) for the complete documentation of audioMotion's features and settings.
 
 ## Credits
 

docs/advanced.md

@@ -0,0 +1,144 @@
+# Advanced Panel
+
+Click **Advanced** in the panel selection buttons to open the Advanced Panel.
+
+![ui-buttons-advanced](img/UI_main_buttons_advanced.png)
+
+## Channel Layout
+
+<div class="advanced-panel highlight-channel-layout"></div>
+
+Selects single or dual channel display, with different layout options:
+
+| Channel Layout | Description |
+|----------------|-------------|
+| **Single**     | Single channel analyzer, representing the combined output of all channels (stereo or surround).
+| **Comb**       | Dual channel analyzer, both channels overlaid. Works best with [**Line Graph** mode](settings.md#analyzer-mode) or [**OUTLINE**](settings.md#effects) switch on.
+| **Horiz**      | Dual channel, side by side - see [Mirror](settings.md#mirror) for additional layout options.
+| **Vert**       | Dual channel, left channel at the top half of the canvas and right channel at the bottom.
+
+The channel layout setting does NOT affect stereo audio output.
+
+?> Surround audio output is currently only supported with **Single** channel layout, and must be enabled in [Configuration > General settings](configuration.md#general-settings).
+
+## Mirror
+
+<div class="advanced-panel highlight-mirror"></div>
+
+Selects a horizontal mirroring effect to the left (low frequencies at the center) or to the right (high frequencies at the center).
+
+| Mirror: Left | Mirror: Right |
+|:-----------:|:-------------:|
+| ![mirror-left](img/mirror-left.png) | ![mirror-right](img/mirror-right.png)
+
+## Import / Export Settings
+
+<div class="advanced-panel highlight-import-export"></div>
+
+Click **Export** to download all current settings in the **Settings** and **Advanced** panels as a JSON file. Use it to [share](https://github.com/hvianna/audioMotion.js/discussions/categories/presets) and store backup copies of your favorite settings.
+
+Click **Import** to load settings from an external JSON file. Please note that this will overwrite all current settings in both the **Settings** and **Advanced** panels.
+
+You can also import [downloaded presets](settings.md#save-manage-presets) this way.
+
+## Bar Spacing
+
+<div class="advanced-panel highlight-bar-spacing"></div>
+
+The amount of spacing between analyzer bars. This setting is only effective in [Bars mode](settings.md#analyzer-mode).
+
+## Fill Opacity
+
+<div class="advanced-panel highlight-fill-opacity"></div>
+
+Transparency of the graph area or bar fill. The [ALPHA](settings.md#effects) switch, when active, has precedence over the Fill Opacity (for Bars mode only).
+
+Effective only for **Graph** [analyzer mode](settings.md#analyzer-mode) or when [OUTLINE](settings.md#effects) switch is on.
+
+!> On **Firefox**, Fill Opacity may not work properly with [Radial](settings.md#effects) analyzer, due to [this bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1164912).
+
+## Line Width
+
+<div class="advanced-panel highlight-line-width"></div>
+
+Thickness of the graph line or outline stroke.
+
+Effective only for **Graph** [analyzer mode](settings.md#analyzer-mode) or when [OUTLINE](settings.md#effects) switch is on.
+
+## Radial Size
+
+<div class="advanced-panel highlight-radial-size"></div>
+
+Configure the radius of the radial analyzer, when [RADIAL](settings.md#effects) switch is on.
+
+## Radial Spin
+
+<div class="advanced-panel highlight-radial-spin"></div>
+
+Configure the radial analyzer spinning speed, when [RADIAL](settings.md#effects) switch is on.
+
+## Frequency Range
+
+<div class="advanced-panel highlight-frequency-range"></div>
+
+The lowest and highest frequencies represented in the spectrum analyzer. You can use this feature to "zoom in" a specific frequency range.
+
+## Frequency Scale
+
+<div class="advanced-panel highlight-frequency-scale"></div>
+
+| Scale    | Description | Frequency distribution preview (10Hz - 24kHz range)
+|----------|-------------|-----------------------------------
+| **BARK** | Bark scale | ![scale-bark](img/scale-bark.png)
+| **LIN**  | Linear scale | ![scale-linear](img/scale-linear.png)
+| **LOG**  | Logarithmic scale | ![scale-log-ansi](img/scale-log-ansi.png)
+| **MEL**  | Mel scale | ![scale-mel](img/scale-mel.png)
+
+Logarithmic scale allows the visualization of proper **octave bands** (see [Analyzer Mode](settings.md#analyzer-mode)) and it's also recommended when using the [**NOTES**](settings.md#x-axis-label) switch.
+
+[*Bark*](https://en.wikipedia.org/wiki/Bark_scale) and [*Mel*](https://en.wikipedia.org/wiki/Mel_scale) are perceptual pitch scales, which may provide better visualization of mid-range frequencies, when compared to log or linear scales.
+
+## Level Scale
+
+<div class="advanced-panel highlight-level-scale"></div>
+
+**LINEAR**  | Switch between linear scale and decibels (logarithmic) to represent bar amplitudes
+
+## Octave Bands
+
+<div class="advanced-panel highlight-octave-bands"></div>
+
+**ANSI**    | Switch between [ANSI/IEC preferred frequencies](https://archive.org/details/gov.law.ansi.s1.11.2004) and [equal-tempered scale](http://hyperphysics.phy-astr.gsu.edu/hbase/Music/et.html) to generate octave bands
+
+## FFT Size
+
+<div class="advanced-panel highlight-fft-size"></div>
+
+Number of samples used for the [Fast Fourier Transform](https://en.wikipedia.org/wiki/Fast_Fourier_transform) performed by the analyzer.
+
+Higher values provide greater detail in the frequency domain (especially for low frequencies), but less detail in the time domain (slower response to changes).
+The default value of **8192** usually provides the best cost/benefit ratio for both domains.
+
+## FFT Smoothing
+
+<div class="advanced-panel highlight-fft-smoothing"></div>
+
+Averaging factor used to smooth FFT data between analysis frames.
+
+Lower values make the analyzer react faster to changes, and may look better with faster tempo songs and/or larger FFT sizes.
+Increase it if the analyzer animation looks too "jumpy".
+
+## Weighting Filter
+
+<div class="advanced-panel highlight-weighting"></div>
+
+[Weighting filter](https://en.wikipedia.org/wiki/Weighting_filter) applied to frequency data for spectrum visualization.
+
+Each filter applies a different curve of gain/attenuation to specific frequency ranges, but the general idea is to adjust the
+visualization of frequencies to which the human ear is more or less sensitive.
+
+![weighting-filters-curves](img/weighting-filters-curves.png)
+
+?> Weighting filters **do NOT** affect audio output. Some filters may impact performance, due to increased real-time data processing.
+
+

docs/configuration.md

@@ -0,0 +1,153 @@
+# Configuration
+
+Click **Configuration** in the main function buttons to open the Configuration panel.
+
+![ui-buttons-config](img/UI_main_buttons_configuration.png)
+
+## Background Image Fit options
+
+![config-enabled-bgfit](img/config-enabled-bgfit.png)
+
+Uncheck options to remove them from the [Background Image Fit](settings.md#background-image-fit) selection box.
+
+## General settings
+
+<img src="img/config-general-settings.png" class="img-right">
+
+### Analyzer height on fullscreen (%)
+
+Height of the analyzer when in fullscreen. This can be used to provide a wider look to the fullscreen analyzer.
+
+You can also use the **Shift** + **Up** and **Down** arrows to adjust the analyzer height during fullscreen visualization.
+
+### Background media source
+
+Choose the source for [Background](settings.md#background) images and videos, or disable this feature.
+
+When set to *Local folder*, only files in the selected folder will be loaded (subfolders are ignored).
+Requires browser support for the [*File System Access API*](known-issues.md).
+
+### Background media max items
+
+Choose the maximum number of media files that can be directly selected in the [Background](settings.md#background) setting.
+
+If your backgrounds folder contains more files, the remaining ones will only be selectable via the *Random image* or *Random video* options.
+
+### Maximum frame rate (FPS)
+
+Maximum desired animation frame rate, in frames per second.
+
+*'Unlimited'* will try to match your monitor's refresh rate, but may increase CPU usage.
+
+### PIP aspect ratio
+
+Choose the aspect ratio of the Picture-In-Picture window.
+
+After entering PIP, the window can be resized and the selected aspect ratio will be preserved.
+
+### Auto-collapse front panel on analyzer hover
+
+Automatically collapses the front panel when you move the mouse cursor over the analyzer area,
+keeping only the main controls visible and expanding the analyzer to use most of the screen.
+
+To expand the front panel again, click the <img src="img/button-expand.png" style="vertical-align: middle"> button or one of the [panel selection buttons](user-interface.md#panel-selection).
+
+### Disable Background Dim when playing video
+
+Ignore the [Background Dim](settings.md#background-dim) setting when playing a video track.
+
+### Disable Background Dim when showing subtitles
+
+Ignore the [Background Dim](settings.md#background-dim) setting when showing subtitles for the current track.
+
+### Remember last music folder
+
+Start the file explorer in the last previously used folder the next time you open audioMotion.
+
+### Remember play queue contents
+
+Automatically restores the contents of the play queue the next time you open audioMotion.
+
+
+## Gradients management
+
+![config-gradients](img/config-gradients.png)
+
+Uncheck gradients to remove them from the [Gradients](settings.md#gradients) selection box.
+
+Move the mouse over a gradient name and click the <img src="img/button-edit-gradient.png" style="vertical-align: middle"> button to clone, edit, delete, or export it (see [**Gradient Editor**](#gradient-editor) below).
+
+Click the **Create Gradient** button to create a new custom gradient, or the **Import Gradient** button to import a downloaded gradient.
+
+?> Visit [Resources > Gradients](https://github.com/hvianna/audioMotion.js/discussions/categories/gradients) in our GitHub Discussions to download community gradients and share your creations too!
+
+## Gradient Editor
+
+The gradient editor is accessed via [Gradients management](#gradients-management), by clicking the **Create Gradient** button, or the <img src="img/button-edit-gradient.png" style="vertical-align: middle"> button next to a gradient's name.
+
+Built-in gradients can't be changed or deleted, but you can clone a built-in gradient and make the changes you'd like. Then disable the built-in gradients you don't want to use by unchecking them in the [Gradients management](#gradients-management) list.
+
+![gradient-editor](img/gradient-editor.png)
+
+At least two colors are required to create a gradient, but you can add as many colors as you like.
+The **offset** must be a number between 0 and 1 - use it to adjust the position of each color inside the gradient.
+
+!> Custom gradients are saved to the browser's internal storage and will only be accessible in the same browser they were saved. **It is recommended that you save backup copies of your custom gradients, by using the Export function.**
+
+## On-screen information display
+
+![config-osd-options](img/config-osd-options.png)
+
+### On-screen display font size
+
+Base font size used for information displayed on canvas.
+
+Customize how long information is displayed on screen when user clicks the analyzer or uses the **D** keyboard shortcut,
+and also on song beginning and end.
+
+You can also toggle the display of album covers and number of tracks.
+
+## Peaks behavior
+
+![config-peaks-behavior](img/config-peaks-behavior.png)
+
+### Gravity
+
+Acceleration for peaks falling down (in thousands of pixels per second squared), when [set to *Drop*](settings.md#peaks).
+
+### Peak fade time
+
+Time in milliseconds for peaks to completely fade out, when [set to *Fade*](settings.md#peaks).
+
+### Peak hold time
+
+Time in milliseconds for peaks to hold their values before they start falling down or fading out.
+
+## Randomize
+
+![config-randomize-settings](img/config-randomize-settings.png)
+
+Select which configuration settings may be changed by [Randomize](settings.md#randomize).
+
+When **User Presets** is checked, Randomize will first load one of your [saved custom presets](settings.md#save-manage-presets) and then choose random values for any other settings checked.
+So if you want to randomize only among your custom presets, uncheck everything else!
+
+## Sensitivity presets
+
+![config-sensitivity-presets](img/config-sensitivity-presets.png)
+
+Customize low, normal and high [Sensitivity](settings.md#sensitivity) presets.
+
+**Min dB** and **Max dB** represent the lowest and highest volume levels to be registered by the analyzer, in decibels.
+
+The **Linear boost** value is used to perform an *n*th-root operation to amplify low energy values, when using the linear [level scale](advanced.md#level-scale).
+
+?> Please note that **0** dB represents the loudest volume possible.
+
+## Subtitles & Video
+
+![config-subtitles](img/config-subtitles.png)
+
+Choose the background, text color and vertical position of subtitles.
+
+

docs/console.md

@@ -0,0 +1,13 @@
+# Console
+
+Click **Console** in the top panel buttons to open the Console.
+
+![ui-buttons-console](img/UI_main_buttons_console.png)
+
+The console records several useful information, like audio and video settings, configuration changes and error messages.
+
+informational and error messages.
+
+![console](img/console.png)
+
+

docs/help.md

@@ -0,0 +1,35 @@
+# Help panel
+
+## Keyboard shortcuts
+
+The following keyboard shortcuts can be used to control the player and change some visualization settings without leaving fullscreen:
+
+| key | action |
+|:----|:-------|
+**0** | pick random values for all [settings affected by Randomize](#randomize-settings)
+**1** - **9** | load a User Preset
+**Shift** + **1** - **9** | save current settings to a User Preset slot
+**Up** / **Down** arrows | volume up / down<br>**+ Shift:** increase / decrease analyzer height on fullscreen
+**Left** / **Right** arrows | previous / next song<br>**Hold** for rewind / fast forward
+**Space** | play / pause
+**Shift+A** / **A** | change [Randomize](#randomize) interval
+**B** | cycle through [Background](#background) options
+**Shift+B** | cycle through [Background Image Fit](#background-image-fit) options
+**C** | toggle Radial analyzer
+**D** | display song information; press again for settings info and again to hide<br>(alternatively, click on analyzer)
+**E** | shuffle play queue
+**F** | toggle fullscreen
+**Shift+G** / **G** | select previous / next gradient
+**H** | toggle FPS display
+**I** | toggle information display at track start/end
+**L** | toggle LEDs effect on analyzer bars
+**Shift+M** / **M** | select previous / next [Analyzer Mode](#analyzer-mode)
+**Shift+N** / **N** | reduce / increase analyzer sensitivity
+**O** | toggle low-resolution mode
+**P** | toggle peaks display
+**Shift+P** | toggle FADE peaks
+**R** | toggle play queue repeat
+**Shift+S** / **S** | toggle display of frequency and level scales
+**T** | toggle flat / shadowed text for on-screen display
+**U** | toggle luminance bars effect
+**Shift+X** / **X** | select previous / next [Reflex](#reflex) style