diff --git a/docs/config.rst b/docs/config.rst index 097695d1..6f4877b2 100644 --- a/docs/config.rst +++ b/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 -`_ 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 -`_ 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 `_. 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 diff --git a/docs/ext/local.rst b/docs/ext/local.rst index aa18cd5c..a446ffc7 100644 --- a/docs/ext/local.rst +++ b/docs/ext/local.rst @@ -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! diff --git a/docs/ext/mpd.rst b/docs/ext/mpd.rst index fc5a3082..0d669d79 100644 --- a/docs/ext/mpd.rst +++ b/docs/ext/mpd.rst @@ -103,5 +103,21 @@ Usage ===== The extension is enabled by default. To connect to the server, use an :ref:`MPD -client `. If you want to connect to the server from another host, -you'll need to adjust the value of :confval:`mpd/hostname`. +client `. + + +.. _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. diff --git a/docs/ext/mpris.rst b/docs/ext/mpris.rst index 88510d98..bf8963c1 100644 --- a/docs/ext/mpris.rst +++ b/docs/ext/mpris.rst @@ -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 +`_. 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 +`_. diff --git a/docs/ext/scrobbler.rst b/docs/ext/scrobbler.rst index 1d7b3d4b..af9f9e5b 100644 --- a/docs/ext/scrobbler.rst +++ b/docs/ext/scrobbler.rst @@ -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 diff --git a/docs/ext/spotify.rst b/docs/ext/spotify.rst index 0d3729b2..63ccefec 100644 --- a/docs/ext/spotify.rst +++ b/docs/ext/spotify.rst @@ -12,8 +12,6 @@ uses the official `libspotify `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.