describe library migration process

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.