docs: Move usage instructions from config to ext pages
This commit is contained in:
Stein Magnus Jodal
parent
f01ac1c550
commit
ad21236155
152
docs/config.rst
152
docs/config.rst
@ -7,10 +7,6 @@ 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 configuration
|
||||
======================
|
||||
|
||||
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
|
||||
@ -35,126 +31,24 @@ A complete ``~/.config/mopidy/mopidy.conf`` may look as simple as this:
|
||||
password = mysecret
|
||||
|
||||
|
||||
.. _music-from-spotify:
|
||||
|
||||
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:
|
||||
|
||||
.. 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:
|
||||
|
||||
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 backend config values. See :ref:`ext-local`, for a complete list.
|
||||
Then you need to generate a tag cache for your local music...
|
||||
|
||||
|
||||
.. _generating-a-tag-cache:
|
||||
|
||||
Generating a 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 the :confval:`local/media_dir` config value points to where your
|
||||
music is located. Check the current setting by running::
|
||||
|
||||
mopidy --show-config
|
||||
|
||||
#. 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
|
||||
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!
|
||||
|
||||
|
||||
.. _use-mpd-on-a-network:
|
||||
|
||||
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 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 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
|
||||
============================
|
||||
|
||||
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:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[scrobbler]
|
||||
username = myusername
|
||||
password = mysecret
|
||||
|
||||
|
||||
.. _install-desktop-file:
|
||||
|
||||
Controlling Mopidy through the Ubuntu Sound Menu
|
||||
================================================
|
||||
|
||||
If you are running Ubuntu and installed Mopidy using the Debian package from
|
||||
APT you should be able to control Mopidy through the `Ubuntu Sound Menu
|
||||
<https://wiki.ubuntu.com/SoundMenu>`_ without any changes.
|
||||
|
||||
If you installed Mopidy in any other way and want to control Mopidy through the
|
||||
Ubuntu Sound Menu, you must install the ``mopidy.desktop`` file which can be
|
||||
found in the ``data/`` dir of the Mopidy source into the
|
||||
``/usr/share/applications`` dir by hand::
|
||||
|
||||
cd /path/to/mopidy/source
|
||||
sudo cp data/mopidy.desktop /usr/share/applications/
|
||||
|
||||
After you have installed the file, start Mopidy in any way, and Mopidy should
|
||||
appear in the Ubuntu Sound Menu. When you quit Mopidy, it will still be listed
|
||||
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`` interface of the spec is not supported.
|
||||
|
||||
|
||||
Using a custom audio sink
|
||||
Core configuration values
|
||||
=========================
|
||||
|
||||
TODO
|
||||
|
||||
|
||||
Default core configuration
|
||||
==========================
|
||||
|
||||
TODO
|
||||
|
||||
|
||||
Advanced configurations
|
||||
=======================
|
||||
|
||||
Custom audio sink
|
||||
-----------------
|
||||
|
||||
If you have successfully installed GStreamer, and then run the ``gst-inspect``
|
||||
or ``gst-inspect-0.10`` command, you should see a long listing of installed
|
||||
plugins, ending in a summary line::
|
||||
@ -190,8 +84,8 @@ this work first::
|
||||
gst-launch-0.10 audiotestsrc ! audioresample ! oss4sink
|
||||
|
||||
|
||||
Streaming audio through a SHOUTcast/Icecast server
|
||||
==================================================
|
||||
Streaming through SHOUTcast/Icecast
|
||||
-----------------------------------
|
||||
|
||||
If you want to play the audio on another computer than the one running Mopidy,
|
||||
you can stream the audio from Mopidy through an SHOUTcast or Icecast audio
|
||||
@ -219,8 +113,8 @@ can use with the ``gst-launch-0.10`` command can be plugged into
|
||||
:confval:`audio/output`.
|
||||
|
||||
|
||||
Custom configuration values
|
||||
===========================
|
||||
New configuration values
|
||||
------------------------
|
||||
|
||||
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,
|
||||
@ -232,9 +126,3 @@ 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
|
||||
==================
|
||||
|
||||
.. note:: TODO: Document config values of the new config system
|
||||
|
||||
@ -6,8 +6,7 @@ Mopidy-Local
|
||||
|
||||
Extension for playing music from a local music archive.
|
||||
|
||||
This backend handles URIs starting with ``file:``. See
|
||||
:ref:`music-from-local-storage` for further instructions on using this backend.
|
||||
This backend handles URIs starting with ``file:``.
|
||||
|
||||
|
||||
Known issues
|
||||
@ -47,3 +46,41 @@ Default configuration
|
||||
|
||||
.. literalinclude:: ../../mopidy/backends/local/ext.conf
|
||||
:language: ini
|
||||
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
If you want use Mopidy to play music you have locally at your machine, you need
|
||||
to review and maybe change some of the local extension config values. See above
|
||||
for a complete list. Then you need to generate a tag cache for your local
|
||||
music...
|
||||
|
||||
|
||||
.. _generating-a-tag-cache:
|
||||
|
||||
Generating a 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 the :confval:`local/media_dir` config value points to where your
|
||||
music is located. Check the current setting by running::
|
||||
|
||||
mopidy --show-config
|
||||
|
||||
#. 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
|
||||
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!
|
||||
|
||||
@ -103,5 +103,21 @@ Usage
|
||||
=====
|
||||
|
||||
The extension is enabled by default. To connect to the server, use an :ref:`MPD
|
||||
client <mpd-clients>`. If you want to connect to the server from another host,
|
||||
you'll need to adjust the value of :confval:`mpd/hostname`.
|
||||
client <mpd-clients>`.
|
||||
|
||||
|
||||
.. _use-mpd-on-a-network:
|
||||
|
||||
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 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 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.
|
||||
|
||||
@ -50,10 +50,40 @@ Usage
|
||||
The extension is enabled by default if all dependencies are available.
|
||||
|
||||
|
||||
Testing the MPRIS API
|
||||
=====================
|
||||
Controlling Mopidy through the Ubuntu Sound Menu
|
||||
------------------------------------------------
|
||||
|
||||
To test, start Mopidy, and then run the following in a Python shell::
|
||||
If you are running Ubuntu and installed Mopidy using the Debian package from
|
||||
APT you should be able to control Mopidy through the :ref:`ubuntu-sound-menu`
|
||||
without any changes.
|
||||
|
||||
If you installed Mopidy in any other way and want to control Mopidy through the
|
||||
Ubuntu Sound Menu, you must install the ``mopidy.desktop`` file which can be
|
||||
found in the ``data/`` dir of the Mopidy source repo into the
|
||||
``/usr/share/applications`` dir by hand::
|
||||
|
||||
cd /path/to/mopidy/source
|
||||
sudo cp data/mopidy.desktop /usr/share/applications/
|
||||
|
||||
If the correct path to the installed ``mopidy.desktop`` file on your system
|
||||
isn't ``/usr/share/applications/mopidy.conf``, you'll need to set the
|
||||
:confval:`mpris/desktop_file` config value.
|
||||
|
||||
After you have installed the file, start Mopidy in any way, and Mopidy should
|
||||
appear in the Ubuntu Sound Menu. When you quit Mopidy, it will still be listed
|
||||
in the Ubuntu Sound Menu, and may be restarted by selecting it there.
|
||||
|
||||
The Ubuntu Sound Menu interacts with Mopidy's MPRIS frontend. The MPRIS
|
||||
frontend supports the minimum requirements of the `MPRIS specification
|
||||
<http://www.mpris.org/>`_. The ``TrackList`` interface of the spec is not
|
||||
supported.
|
||||
|
||||
|
||||
Testing the MPRIS API directly
|
||||
------------------------------
|
||||
|
||||
To use the MPRIS API directly, start Mopidy, and then run the following in a
|
||||
Python shell::
|
||||
|
||||
import dbus
|
||||
bus = dbus.SessionBus()
|
||||
@ -70,3 +100,6 @@ Now you can control Mopidy through the player object. Examples:
|
||||
- To quit Mopidy through D-Bus, run::
|
||||
|
||||
player.Quit(dbus_interface='org.mpris.MediaPlayer2')
|
||||
|
||||
For details on the API, please refer to the `MPRIS specification
|
||||
<http://www.mpris.org/>`_.
|
||||
|
||||
@ -43,4 +43,11 @@ Usage
|
||||
=====
|
||||
|
||||
The extension is enabled by default if all dependencies are available. You just
|
||||
need to add your Last.fm username and password to the config file.
|
||||
need to add your Last.fm username and password to the
|
||||
``~/.config/mopidy/mopidy.conf`` file:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[scrobbler]
|
||||
username = myusername
|
||||
password = mysecret
|
||||
|
||||
@ -12,8 +12,6 @@ uses the official `libspotify
|
||||
`pyspotify <http://github.com/mopidy/pyspotify/>`_ Python bindings for
|
||||
libspotify. This backend handles URIs starting with ``spotify:``.
|
||||
|
||||
See :ref:`music-from-spotify` for further instructions on using this backend.
|
||||
|
||||
.. note::
|
||||
|
||||
This product uses SPOTIFY(R) CORE but is not endorsed, certified or
|
||||
@ -66,3 +64,20 @@ Default configuration
|
||||
|
||||
.. literalinclude:: ../../mopidy/backends/spotify/ext.conf
|
||||
:language: ini
|
||||
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
If you are using the Spotify backend, which is the default, enter your Spotify
|
||||
Premium account's username and password into ``~/.config/mopidy/mopidy.conf``,
|
||||
like this:
|
||||
|
||||
.. code-block:: ini
|
||||
|
||||
[spotify]
|
||||
username = myusername
|
||||
password = mysecret
|
||||
|
||||
This will only work if you have the Spotify Premium subscription. Spotify
|
||||
Unlimited will not work.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user