docs: More prose and less headers in ext docs
This commit is contained in:
Stein Magnus Jodal
parent
d9e602c128
commit
cc8bf67641
@ -1,3 +1,5 @@
|
||||
.. _config:
|
||||
|
||||
*************
|
||||
Configuration
|
||||
*************
|
||||
|
||||
@ -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 <http://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`.
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -4,8 +4,20 @@
|
||||
Mopidy-MPD
|
||||
**********
|
||||
|
||||
This extension implements an MPD server to make Mopidy available to :ref:`MPD
|
||||
clients <mpd-clients>`.
|
||||
Mopidy-MPD is an extension that provides a full MPD server implementation to
|
||||
make Mopidy available to :ref:`MPD clients <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 <http://mpd.wikia.com/>`_. 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 <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.
|
||||
|
||||
@ -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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user