Merge remote-tracking branch 'mixxx/2.3' into 2.4

source/chapters/advanced_topics.rst

@@ -233,3 +233,41 @@ using sends for effects. This gives Mixxx access to the extensive collection of
 Make sure the correct multichannel audio interface has been selected in Jack
 (Jack settings visible bottom left). Note that Mixxx possibly labels its Jack
 ports as :guilabel:`Portaudio`.
+
+.. _advanced-migrate-settings:
+
+Migrate your Mixxx library and settings to a new computer
+=========================================================
+
+If you move to a new computer, or to another operating system on the same computer, you can take your existing Mixxx setup with you. This includes your track library, settings, controller mappings and broadcast profiles.
+
+You don't necessarily need to be able to run your previous Mixxx installation, all you need is your :ref:`settings directory <appendix-settings-files>` and the music directories you imported into your Mixxx library via :menuselection:`Preferences --> Library`.
+
+Preparation
+-----------
+
+* If you still have access to your Mixxx installation open Mixxx, go to :menuselection:`Preferences --> Library` and uncheck :guilabel:`Rescan on startup`. If you are not able to start Mixxx anymore, e.g. if you only managed to recover your settings directory, you can do this manually in the settings file: open :file:`mixxx.cfg` with a text editor, delete the line with :file:`RescanOnStartup` and save the file.
+* Make a copy of both the Mixxx settings directory and your music directories. Put all in a save place. **Do not restructure your music directories!**
+* Install you new operating system, get your new PC ready.
+* Get the current stable Mixxx version from `the official download page <https://mixxx.org/download/>`_.
+* Install Mixxx, though **don't run it, yet!**
+
+Migration
+---------
+
+* Put your Mixxx settings directory in the appropriate location, see :ref:`appendix-settings-files`. In case you already started Mixxx previously, make sure to rename or delete your existing settings directory in order to avoid any file conflicts.
+* Copy your music directories to the new computer.
+* Start Mixxx.
+* If you've put the settings directory in the correct location Mixxx should not ask you for your music directories and all your settings should be as before.
+* Go to :menuselection:`Preferences --> Library` and **Relink** each of your music directories as described in :ref:`configuration-import`.
+
+Now, all your music files should be available, all your playlists, crates and your session histories be restored. Configure a sound output and test if you can play all tracks as before. Note that this will obviously not include your external libraries (iTunes, Traktor etc.), you need to configure those again.
+
+Known issues
+------------
+
+If you migrated to another operating system, operating system version or another Mixxx version, the used
+audio decoders may have changed which may cause beatgrids and cue points appear shifted, i.e. they are
+set off from the desired points in the audio stream. Unfortunately, there is no automatic fix available, yet.
+As of now you need to shift cues for each track individually with the cue shift buttons in the beatgrid editing
+controls section, see :ref:`interface-waveform`.

source/chapters/appendix/settings_directory.rst

@@ -13,6 +13,8 @@ The Mixxx settings directory contains all user data and settings of your Mixxx i
 Location
 --------
 
+You can navigate to the settings directory location manually as described below. Since Mixxx 2.3 you can also open this directory in your file browser from within Mixxx: go to :menuselection:`Preferences --> Library`, scroll to the bottom of the page and click on :guilabel:`Open Mixxx Settings Directory`.
+
 .. hint:: On Windows, the :file:`AppData` folder is hidden, as well as all files and
           directories beginning with a dot '.' on Linux. So if you have not already,
           you will need to set your file manager to show hidden files and folders.

source/chapters/preferences/beat_detection.rst

@@ -80,3 +80,6 @@ follow the note below.
 
 .. note:: If the detected BPM value is not sufficiently accurate but very close
           to an integer value, try to set the BPM value manually to the integer.
+
+For more granular adjustments there are beatgrid controls close to the
+:ref:`interface-waveform` of each deck in the main interface.

source/chapters/user_interface.rst

@@ -203,6 +203,25 @@ then toggling the :menuselection:`Skin Settings --> Parallel Waveforms` option.
              which differ primarily in the level of detail shown in the
              waveform, in :menuselection:`Preferences --> Waveforms --> Waveform type`.
 
+  Right next to the waveform view there are controls to adjust the :term:`beatgrid`.
+  You may stretch, compress or shift the beatgrid in case it was not detected
+  correctly (see :ref:`configuration-bpm-detection`). There are also controls to shift
+  cue points in case they are set off after decoder changes, for example when you migrated
+  your Mixxx library to another compouter or operating system. These controls are
+  hidden by default and need to be enabled in the skin settings menu.
+
+  .. figure:: ../_static/2.3/latenight-beatgrid-controls.png
+     :align: center
+     :width: 100%
+     :figwidth: 100%
+     :alt: Mixxx default skin (LateNight) - Beatgrid editing controls
+     :figclass: pretty-figures
+
+     Beatgrid editing controls in the default Mixxx skin (LateNight, PaleMoon theme)
+
+  In Deere skin, these controls are located in the expandable BPM section inside
+  the decks.
+
 **Waveform overview**
   The smaller, zoomed-out version of the waveform shows the various markers
   within the track as well as the waveform envelope of the entire track. This is