********
Settings
********

Mopidy has lots of settings. Luckily, you only need to change a few, and stay
ignorant of the rest. Below you can find guides for typical configuration
changes you may want to do, and a complete listing of available settings.


Changing settings
=================

Mopidy reads settings from the file ``~/.mopidy/settings.py``, where ``~``
means your *home directory*. If your username is ``alice`` and you are running
Linux, the settings file should probably be at
``/home/alice/.mopidy/settings.py``.

You can either create the settings file yourself, or run the ``mopidy``
command, and it will create an empty settings file for you.

When you have created the settings file, open it in a text editor, and add
settings you want to change. If you want to keep the default value for setting,
you should *not* redefine it in your own settings file.

A complete ``~/.mopidy/settings.py`` may look as simple as this::

    MPD_SERVER_HOSTNAME = u'::'
    SPOTIFY_USERNAME = u'alice'
    SPOTIFY_PASSWORD = u'mysecret'


Music from Spotify
==================

If you are using the Spotify backend, which is the default, enter your Spotify
Premium account's username and password into the file, like this::

    SPOTIFY_USERNAME = u'myusername'
    SPOTIFY_PASSWORD = u'mysecret'


Music from local storage
========================

If you want use Mopidy to play music you have locally at your machine instead
of using Spotify, you need to change the backend from the default to
:mod:`mopidy.backends.local` by adding the following line to your settings
file::

    BACKENDS = (u'mopidy.backends.local.LocalBackend',)

You may also want to change some of the ``LOCAL_*`` settings. See
:mod:`mopidy.settings`, for a full list of available settings.

.. note::

    Currently, Mopidy supports using Spotify *or* local storage as a music
    source. We're working on using both sources simultaneously, and will
    hopefully have support for this in the 0.3 release.


Generating a tag cache
----------------------

Previously the local storage backend relied purely on ``tag_cache`` files
generated by the original MPD server. To remedy this the command
:command:`mopidy-scan` has been created. The program will scan your current
:attr:`mopidy.settings.LOCAL_MUSIC_PATH` and build a MPD compatible
``tag_cache``.

To make a ``tag_cache`` of your local music available for Mopidy:

#. Ensure that :attr:`mopidy.settings.LOCAL_MUSIC_PATH` points to where your
   music is located. Check the current setting by running::

    mopidy --list-settings

#. Scan your music library. Currently the command outputs the ``tag_cache`` to
   ``stdout``, which means that you will need to redirect the output to a file
   yourself::

    mopidy-scan > tag_cache

#. Move the ``tag_cache`` file to the location
   :attr:`mopidy.settings.LOCAL_TAG_CACHE_FILE` is set to, or change the setting to
   point to where your ``tag_cache`` file is.

#. Start Mopidy, find the music library in a client, and play some local music!


Connecting from other machines on the network
=============================================

As a secure default, Mopidy only accepts connections from ``localhost``. If you
want to open it for connections from other machines on your network, see
the documentation for :attr:`mopidy.settings.MPD_SERVER_HOSTNAME`.


Scrobbling tracks to Last.fm
============================

If you want to submit the tracks you are playing to your `Last.fm
<http://www.last.fm/>`_ profile, make sure you've installed the dependencies
found at :mod:`mopidy.frontends.lastfm` and add the following to your settings
file::

    LASTFM_USERNAME = u'myusername'
    LASTFM_PASSWORD = u'mysecret'


Available settings
==================

.. automodule:: mopidy.settings
    :synopsis: Available settings and their default values
    :members:
    :undoc-members: