diff --git a/docs/config.rst b/docs/config.rst index 5099f04d..63e62622 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -1,3 +1,5 @@ +.. _config: + ************* Configuration ************* diff --git a/docs/ext/http.rst b/docs/ext/http.rst index 83881292..1b5b0119 100644 --- a/docs/ext/http.rst +++ b/docs/ext/http.rst @@ -4,35 +4,77 @@ Mopidy-HTTP *********** -The HTTP extension lets you control Mopidy through HTTP and WebSockets, e.g. -from a web based client. See :ref:`http-api` for details on how to integrate -with Mopidy over HTTP. +Mopidy-HTTP is an extension that lets you control Mopidy through HTTP and +WebSockets, for example from a web client. It is bundled with Mopidy and +enabled by default if all dependencies are available. + +When it is enabled it starts a web server at the port specified by the +:confval:`http/port` config value. + +.. warning:: + + As a simple security measure, the web server is by default only available + from localhost. To make it available from other computers, change the + :confval:`http/hostname` config value. Before you do so, note that the HTTP + extension does not feature any form of user authentication or + authorization. Anyone able to access the web server can use the full core + API of Mopidy. Thus, you probably only want to make the web server + available from your local network or place it behind a web proxy which + takes care or user authentication. You have been warned. + + +Using a web based Mopidy client +=============================== + +Mopidy-HTTP's web server can also host any static files, for example the HTML, +CSS, JavaScript, and images needed for a web based Mopidy client. To host +static files, change the :confval:`http/static_dir` config value to point to +the root directory of your web client, for example:: + + [http] + static_dir = /home/alice/dev/the-client + +If the directory includes a file named ``index.html``, it will be served on the +root of Mopidy's web server. + +If you're making a web based client and wants to do server side development as +well, you are of course free to run your own web server and just use Mopidy's +web server to host the API end points. But, for clients implemented purely in +JavaScript, letting Mopidy host the files is a simpler solution. + +See :ref:`http-api` for details on how to integrate with Mopidy over HTTP. If +you're looking for a web based client for Mopidy, go check out +:ref:`http-clients`. Dependencies ============ +In addition to Mopidy's dependencies, Mopidy-HTTP requires the following: + - cherrypy >= 3.2.2. Available as python-cherrypy3 in Debian/Ubuntu. - ws4py >= 0.2.3. Available as python-ws4py in newer Debian/Ubuntu and from - apt.mopidy.com for older releases of Debian/Ubuntu. + `apt.mopidy.com `__ for older releases of + Debian/Ubuntu. If you're installing Mopidy with pip, you can run the following command to install Mopidy with the extra dependencies for required for Mopidy-HTTP:: pip install --upgrade Mopidy[http] +If you're installing Mopidy from APT, the additional dependencies needed for +Mopidy-HTTP are always included. -Default configuration -===================== + +Configuration +============= + +See :ref:`config` for general help on configuring Mopidy. .. literalinclude:: ../../mopidy/http/ext.conf :language: ini - -Configuration values -==================== - .. confval:: http/enabled If the HTTP extension should be enabled or not. @@ -67,46 +109,3 @@ Configuration values ``$hostname`` and ``$port`` can be used in the name. Set to an empty string to disable Zeroconf for HTTP. - - -Usage -===== - -The extension is enabled by default if all dependencies are available. - -When it is enabled it starts a web server at the port specified by the -:confval:`http/port` config value. - -.. warning:: Security - - As a simple security measure, the web server is by default only available - from localhost. To make it available from other computers, change the - :confval:`http/hostname` config value. Before you do so, note that the HTTP - extension does not feature any form of user authentication or - authorization. Anyone able to access the web server can use the full core - API of Mopidy. Thus, you probably only want to make the web server - available from your local network or place it behind a web proxy which - takes care or user authentication. You have been warned. - - -Using a web based Mopidy client -------------------------------- - -The web server can also host any static files, for example the HTML, CSS, -JavaScript, and images needed for a web based Mopidy client. To host static -files, change the ``http/static_dir`` to point to the root directory of your -web client, e.g.:: - - [http] - static_dir = /home/alice/dev/the-client - -If the directory includes a file named ``index.html``, it will be served on the -root of Mopidy's web server. - -If you're making a web based client and wants to do server side development as -well, you are of course free to run your own web server and just use Mopidy's -web server for the APIs. But, for clients implemented purely in JavaScript, -letting Mopidy host the files is a simpler solution. - -If you're looking for a web based client for Mopidy, go check out -:ref:`http-clients`. diff --git a/docs/ext/local.rst b/docs/ext/local.rst index 9fed4292..5d3562a9 100644 --- a/docs/ext/local.rst +++ b/docs/ext/local.rst @@ -4,27 +4,61 @@ Mopidy-Local ************ -Extension for playing music from a local music archive. +Mopidy-Local is an extension for playing music from your local music archive. +It is bundled with Mopidy and enabled by default. Though, you'll have to scan +your music collection to build a cache of metadata before the Mopidy-Local +will be able to play your music. This backend handles URIs starting with ``local:``. -Dependencies -============ +.. _generating-a-local-library: -None. The extension just needs Mopidy. +Generating a local library +========================== + +The command :command:`mopidy local scan` will scan the path set in the +:confval:`local/media_dir` config value for any audio files and build a +library of metadata. + +To make a local library for your 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 config + +#. Scan your media library.:: + + mopidy local scan + +#. Start Mopidy, find the music library in a client, and play some local music! -Default configuration -===================== +Pluggable library support +========================= + +Local libraries are fully pluggable. What this means is that users may opt to +disable the current default library ``json``, replacing it with a third +party one. When running :command:`mopidy local scan` Mopidy will populate +whatever the current active library is with data. Only one library may be +active at a time. + +To create a new library provider you must create class that implements the +:class:`mopidy.local.Library` interface and install it in the extension +registry under ``local:library``. Any data that the library needs to store on +disc should be stored in :confval:`local/data_dir` using the library name as +part of the filename or directory to avoid any conflicts. + + +Configuration +============= + +See :ref:`config` for general help on configuring Mopidy. .. literalinclude:: ../../mopidy/local/ext.conf :language: ini - -Configuration values -==================== - .. confval:: local/enabled If the local extension should be enabled or not. @@ -61,51 +95,3 @@ Configuration values File extensions to exclude when scanning the media directory. Values should be separated by either comma or newline. - - -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 local library for your local -music... - - -.. _generating-a-local-library: - -Generating a local library --------------------------- - -The command :command:`mopidy local scan` will scan the path set in the -:confval:`local/media_dir` config value for any audio files and build a -library. - -To make a local library for your 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 config - -#. Scan your media library.:: - - mopidy local scan - -#. Start Mopidy, find the music library in a client, and play some local music! - - -Pluggable library support -------------------------- - -Local libraries are fully pluggable. What this means is that users may opt to -disable the current default library ``json``, replacing it with a third -party one. When running :command:`mopidy local scan` mopidy will populate -whatever the current active library is with data. Only one library may be -active at a time. - -To create a new library provider you must create class that implements the -:class:`mopidy.local.Library` interface and install it in the extension -registry under ``local:library``. Any data that the library needs to store on -disc should be stored in :confval:`local/data_dir` using the library name as -part of the filename or directory to avoid any conflicts. diff --git a/docs/ext/mpd.rst b/docs/ext/mpd.rst index fa91f6a2..5b82dce2 100644 --- a/docs/ext/mpd.rst +++ b/docs/ext/mpd.rst @@ -4,8 +4,20 @@ Mopidy-MPD ********** -This extension implements an MPD server to make Mopidy available to :ref:`MPD -clients `. +Mopidy-MPD is an extension that provides a full MPD server implementation to +make Mopidy available to :ref:`MPD clients `. It is bundled with +Mopidy and enabled by default. + +.. warning:: + + As a simple security measure, the HTTP server is by default only available + from localhost. To make it available from other computers, change the + :confval:`mpd/hostname` config value. Before you do so, note that the MPD + server does not support any form of encryption and only a single clear + text password (see :confval:`mpd/password`) for weak authentication. Anyone + able to access the MPD server can control music playback on your computer. + Thus, you probably only want to make the MPD server available from your + local network. You have been warned. MPD stands for Music Player Daemon, which is also the name of the `original MPD server project `_. Mopidy does not depend on the @@ -21,6 +33,7 @@ Limitations This is a non exhaustive list of MPD features that Mopidy doesn't support. Items on this list will probably not be supported in the near future. +- Only a single password is supported. It gives all-or-nothing access. - Toggling of audio outputs is not supported - Channels for client-to-client communication are not supported - Stickers are not supported @@ -38,22 +51,14 @@ near future: - Live update of the music database is not supported -Dependencies -============ +Configuration +============= -None. The extension just needs Mopidy. - - -Default configuration -===================== +See :ref:`config` for general help on configuring Mopidy. .. literalinclude:: ../../mopidy/mpd/ext.conf :language: ini - -Configuration values -==================== - .. confval:: mpd/enabled If the MPD extension should be enabled or not. @@ -95,27 +100,3 @@ Configuration values ``$hostname`` and ``$port`` can be used in the name. Set to an empty string to disable Zeroconf for MPD. - - -Usage -===== - -The extension is enabled by default. To connect to the server, use an :ref:`MPD -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/stream.rst b/docs/ext/stream.rst index 6c6ab21c..88dc5ade 100644 --- a/docs/ext/stream.rst +++ b/docs/ext/stream.rst @@ -4,29 +4,32 @@ Mopidy-Stream ************* -Extension for playing streaming music. +Mopidy-Stream is an extension for playing streaming music. It is bundled with +Mopidy and enabled by default. -The stream backend will handle streaming of URIs matching the -:confval:`stream/protocols` config value, assuming the needed GStreamer plugins -are installed. +This backend does not provide a library or playlist storage. It simply accepts +any URI added to Mopidy's tracklist that matches any of the protocols in the +:confval:`stream/protocols` config value. It then tries to retrieve metadata +and play back the URI using GStreamer. For example, if you're using an MPD +client, you'll just have to find your clients "add URI" interface, and provide +it with the URI of a stream. + +In addition to playing streams, the extension also understands how to extract +streams from a lot of playlist formats. This is convenient as most Internet +radio stations links to playlists instead of directly to the radio streams. + +If you're having trouble playing back a stream, run the ``mopidy deps`` +command to check if you have all relevant GStreamer plugins installed. -Dependencies -============ +Configuration +============= -None. The extension just needs Mopidy. - - -Default configuration -===================== +See :ref:`config` for general help on configuring Mopidy. .. literalinclude:: ../../mopidy/stream/ext.conf :language: ini - -Configuration values -==================== - .. confval:: stream/enabled If the stream extension should be enabled or not. @@ -39,17 +42,3 @@ Configuration values .. confval:: stream/timeout Number of milliseconds before giving up looking up stream metadata. - - -Usage -===== - -This backend does not provide a library or similar. It simply takes any URI -added to Mopidy's tracklist that matches any of the protocols in the -:confval:`stream/protocols` setting and tries to play back the URI using -GStreamer. E.g. if you're using an MPD client, you'll just have to find your -clients "add URI" interface, and provide it with the direct URI of the stream. - -Currently the stream backend can only work with URIs pointing direcly at -streams, and not intermediate playlists which is often used. See :issue:`303` -to track the development of playlist expansion support.