docs: Update config page howtos
This commit is contained in:
Stein Magnus Jodal
parent
18d34d6ffc
commit
130347f994
@ -1,32 +1,38 @@
|
||||
********
|
||||
Settings
|
||||
********
|
||||
*************
|
||||
Configuration
|
||||
*************
|
||||
|
||||
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.
|
||||
Mopidy has quite a few config values to tweak. 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 listing of the available config
|
||||
values.
|
||||
|
||||
|
||||
Changing settings
|
||||
=================
|
||||
Changing configuration
|
||||
======================
|
||||
|
||||
Mopidy reads settings from the file ``~/.config/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/.config/mopidy/settings.py``.
|
||||
Mopidy primarily reads config from the file ``~/.config/mopidy/mopidy.conf``,
|
||||
where ``~`` means your *home directory*. If your username is ``alice`` and you
|
||||
are running Linux, the settings file should probably be at
|
||||
``/home/alice/.config/mopidy/mopidy.conf``.
|
||||
|
||||
You can either create the settings file yourself, or run the ``mopidy``
|
||||
You can either create the configuration 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
|
||||
When you have created the configuration file, open it in a text editor, and add
|
||||
settings you want to change. If you want to keep the default value for a
|
||||
setting, you should *not* redefine it in your own settings file.
|
||||
|
||||
A complete ``~/.config/mopidy/settings.py`` may look as simple as this::
|
||||
A complete ``~/.config/mopidy/mopidy.conf`` may look as simple as this:
|
||||
|
||||
MPD_SERVER_HOSTNAME = u'::'
|
||||
SPOTIFY_USERNAME = u'alice'
|
||||
SPOTIFY_PASSWORD = u'mysecret'
|
||||
.. code-block:: ini
|
||||
|
||||
[mpd]
|
||||
hostname = ::
|
||||
|
||||
[spotify]
|
||||
username = alice
|
||||
password = mysecret
|
||||
|
||||
|
||||
.. _music-from-spotify:
|
||||
@ -35,10 +41,16 @@ 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::
|
||||
Premium account's username and password into the file, like this:
|
||||
|
||||
SPOTIFY_USERNAME = u'myusername'
|
||||
SPOTIFY_PASSWORD = u'mysecret'
|
||||
.. code-block:: ini
|
||||
|
||||
[spotify]
|
||||
username = myusername
|
||||
password = mysecret
|
||||
|
||||
This will only work if you have the Spotify Premium subscription. Spotify
|
||||
Unlimited will not work.
|
||||
|
||||
|
||||
.. _music-from-local-storage:
|
||||
@ -48,9 +60,8 @@ Music from local storage
|
||||
|
||||
If you want use Mopidy to play music you have locally at your machine instead
|
||||
of or in addition to using Spotify, you need to review and maybe change some of
|
||||
the ``LOCAL_*`` settings. See :mod:`mopidy.settings`, for a full list of
|
||||
available settings. Then you need to generate a tag cache for your local
|
||||
music...
|
||||
the local backend config values. See :ref:`local-backend`, for a complete list.
|
||||
Then you need to generate a tag cache for your local music...
|
||||
|
||||
|
||||
.. _generating-a-tag-cache:
|
||||
@ -58,28 +69,26 @@ music...
|
||||
Generating a tag cache
|
||||
----------------------
|
||||
|
||||
Before Mopidy 0.3 the local storage backend relied purely on ``tag_cache``
|
||||
files generated by the original MPD server. To remedy this the command
|
||||
:command:`mopidy-scan` was created. The program will scan your current
|
||||
:attr:`mopidy.settings.LOCAL_MUSIC_PATH` and build a MPD compatible
|
||||
``tag_cache``.
|
||||
The program :command:`mopidy-scan` will scan the path set in the
|
||||
:confval:`local/media_dir` config value for any media files 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
|
||||
#. Ensure that the :confval:`local/media_dir` config value points to where your
|
||||
music is located. Check the current setting by running::
|
||||
|
||||
mopidy --list-settings
|
||||
mopidy --show-config
|
||||
|
||||
#. Scan your music library. The command outputs the ``tag_cache`` to
|
||||
``stdout``, which means that you will need to redirect the output to a file
|
||||
yourself::
|
||||
#. Scan your media library. The command outputs the ``tag_cache`` to
|
||||
standard output, 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.
|
||||
set in the :confval:`local/tag_cache_file` config value, or change the
|
||||
config value to point to where your ``tag_cache`` file is.
|
||||
|
||||
#. Start Mopidy, find the music library in a client, and play some local music!
|
||||
|
||||
@ -91,14 +100,14 @@ 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`.
|
||||
the documentation for the :confval:`mpd/hostname` config value.
|
||||
|
||||
If you open up Mopidy for your local network, you should consider turning on
|
||||
MPD password authentication by setting
|
||||
:attr:`mopidy.settings.MPD_SERVER_PASSWORD` to the password you want to use.
|
||||
If the password is set, Mopidy will require MPD clients to provide the password
|
||||
before they can do anything else. Mopidy only supports a single password, and
|
||||
do not support different permission schemes like the original MPD server.
|
||||
MPD password authentication by setting the :confval:`mpd/password` config value
|
||||
to the password you want to use. If the password is set, Mopidy will require
|
||||
MPD clients to provide the password before they can do anything else. Mopidy
|
||||
only supports a single password, and do not support different permission
|
||||
schemes like the original MPD server.
|
||||
|
||||
|
||||
Scrobbling tracks to Last.fm
|
||||
@ -107,10 +116,13 @@ 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.scrobbler` and add the following to your
|
||||
settings file::
|
||||
settings file:
|
||||
|
||||
LASTFM_USERNAME = u'myusername'
|
||||
LASTFM_PASSWORD = u'mysecret'
|
||||
.. code-block:: ini
|
||||
|
||||
[scrobbler]
|
||||
username = myusername
|
||||
password = mysecret
|
||||
|
||||
|
||||
.. _install-desktop-file:
|
||||
@ -137,7 +149,7 @@ in the Ubuntu Sound Menu, and may be restarted by selecting it there.
|
||||
The Ubuntu Sound Menu interacts with Mopidy's MPRIS frontend,
|
||||
:mod:`mopidy.frontends.mpris`. The MPRIS frontend supports the minimum
|
||||
requirements of the `MPRIS specification <http://www.mpris.org/>`_. The
|
||||
``TrackList`` and the ``Playlists`` interfaces of the spec are not supported.
|
||||
``TrackList`` interface of the spec is not supported.
|
||||
|
||||
|
||||
Using a custom audio sink
|
||||
@ -161,13 +173,16 @@ sound from Mopidy either, as Mopidy by default uses GStreamer's
|
||||
against Mopidy.
|
||||
|
||||
If you for some reason want to use some other GStreamer audio sink than
|
||||
``autoaudiosink``, you can set the setting :attr:`mopidy.settings.OUTPUT` to a
|
||||
``autoaudiosink``, you can set the :confval:`audio/output` config value to a
|
||||
partial GStreamer pipeline description describing the GStreamer sink you want
|
||||
to use.
|
||||
|
||||
Example of ``settings.py`` for using OSS4::
|
||||
Example ``mopidy.conf`` for using OSS4:
|
||||
|
||||
OUTPUT = u'oss4sink'
|
||||
.. code-block:: ini
|
||||
|
||||
[audio]
|
||||
output = oss4sink
|
||||
|
||||
Again, this is the equivalent of the following ``gst-inspect`` command, so make
|
||||
this work first::
|
||||
@ -186,33 +201,37 @@ server simultaneously. To use the SHOUTcast output, do the following:
|
||||
#. Install, configure and start the Icecast server. It can be found in the
|
||||
``icecast2`` package in Debian/Ubuntu.
|
||||
|
||||
#. Set :attr:`mopidy.settings.OUTPUT` to ``lame ! shout2send``. An Ogg Vorbis
|
||||
encoder could be used instead of the lame MP3 encoder.
|
||||
#. Set the :confval:`audio/output` config value to ``lame ! shout2send``. An
|
||||
Ogg Vorbis encoder could be used instead of the lame MP3 encoder.
|
||||
|
||||
#. You might also need to change the ``shout2send`` default settings, run
|
||||
``gst-inspect-0.10 shout2send`` to see the available settings. Most likely
|
||||
you want to change ``ip``, ``username``, ``password``, and ``mount``. For
|
||||
example, to set the username and password, use:
|
||||
``lame ! shout2send username="foobar" password="s3cret"``.
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[audio]
|
||||
output = lame ! shout2send username="alice" password="secret"
|
||||
|
||||
Other advanced setups are also possible for outputs. Basically, anything you
|
||||
can use with the ``gst-launch-0.10`` command can be plugged into
|
||||
:attr:`mopidy.settings.OUTPUT`.
|
||||
:confval:`audio/output`.
|
||||
|
||||
|
||||
Custom settings
|
||||
===============
|
||||
Custom configuration values
|
||||
===========================
|
||||
|
||||
Mopidy's settings validator will stop you from defining any settings in your
|
||||
settings file that Mopidy doesn't know about. This may sound obnoxious, but it
|
||||
helps you detect typos in your settings, and deprecated settings that should be
|
||||
removed or updated.
|
||||
Mopidy's settings validator will stop you from defining any config values in
|
||||
your settings file that Mopidy doesn't know about. This may sound obnoxious,
|
||||
but it helps us detect typos in your settings, and deprecated settings that
|
||||
should be removed or updated.
|
||||
|
||||
If you're extending Mopidy in some way, and want to use Mopidy's settings
|
||||
system, you can prefix your settings with ``CUSTOM_`` to get around the
|
||||
settings validator. We recommend that you choose names like
|
||||
``CUSTOM_MYAPP_MYSETTING`` so that multiple custom extensions to Mopidy can be
|
||||
used at the same time without any danger of naming collisions.
|
||||
If you're extending Mopidy, and want to use Mopidy's configuration
|
||||
system, you can add new sections to the config without triggering the config
|
||||
validator. We recommend that you choose a good and unique name for the config
|
||||
section so that multiple extensions to Mopidy can be used at the same time
|
||||
without any danger of naming collisions.
|
||||
|
||||
|
||||
Available settings
|
||||
@ -42,7 +42,7 @@ User documentation
|
||||
|
||||
installation/index
|
||||
installation/raspberrypi
|
||||
settings
|
||||
config
|
||||
running
|
||||
clients/index
|
||||
authors
|
||||
|
||||
@ -42,7 +42,7 @@ in the same way as you get updates to the rest of your distribution.
|
||||
sudo apt-get update
|
||||
sudo apt-get install mopidy
|
||||
|
||||
#. Finally, you need to set a couple of :doc:`settings </settings>`, and then
|
||||
#. Finally, you need to set a couple of :doc:`config values </config>`, and then
|
||||
you're ready to :doc:`run Mopidy </running>`.
|
||||
|
||||
When a new release of Mopidy is out, and you can't wait for you system to
|
||||
@ -89,8 +89,8 @@ package found in AUR.
|
||||
install `python2-pylast
|
||||
<https://aur.archlinux.org/packages/python2-pylast/>`_ from AUR.
|
||||
|
||||
#. Finally, you need to set a couple of :doc:`settings </settings>`, and then
|
||||
you're ready to :doc:`run Mopidy </running>`.
|
||||
#. Finally, you need to set a couple of :doc:`config values </config>`, and
|
||||
then you're ready to :doc:`run Mopidy </running>`.
|
||||
|
||||
|
||||
OS X: Install from Homebrew and Pip
|
||||
@ -140,8 +140,8 @@ Pip.
|
||||
|
||||
sudo pip install -U pyspotify pylast mopidy
|
||||
|
||||
#. Finally, you need to set a couple of :doc:`settings </settings>`, and then
|
||||
you're ready to :doc:`run Mopidy </running>`.
|
||||
#. Finally, you need to set a couple of :doc:`config values </config>`, and
|
||||
then you're ready to :doc:`run Mopidy </running>`.
|
||||
|
||||
|
||||
Otherwise: Install from source using Pip
|
||||
@ -264,5 +264,5 @@ can install Mopidy from PyPI using Pip.
|
||||
|
||||
sudo pip install mopidy==dev
|
||||
|
||||
#. Finally, you need to set a couple of :doc:`settings </settings>`, and then
|
||||
you're ready to :doc:`run Mopidy </running>`.
|
||||
#. Finally, you need to set a couple of :doc:`config values </config>`, and
|
||||
then you're ready to :doc:`run Mopidy </running>`.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user