From 3a386f05add5e3af025cb320a8d3c4f316a95db0 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 21:49:29 +0200 Subject: [PATCH 01/45] docs: Add empty troubleshooting page --- docs/index.rst | 1 + docs/troubleshooting.rst | 14 ++++++++++++++ 2 files changed, 15 insertions(+) create mode 100644 docs/troubleshooting.rst diff --git a/docs/index.rst b/docs/index.rst index aae7e675..bdd50d00 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -45,6 +45,7 @@ User documentation config running clients/index + troubleshooting authors licenses changes diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst new file mode 100644 index 00000000..d29a5d2f --- /dev/null +++ b/docs/troubleshooting.rst @@ -0,0 +1,14 @@ +.. _troubleshooting: + +*************** +Troubleshooting +*************** + +TODO: + +- --show-config +- --list-deps +- Issue tracker +- Reporting bugs +- Mailing list +- IRC channel From 8a1f2ab6087961d3f4cbd022fd09b1c2ffad5a0c Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 21:56:39 +0200 Subject: [PATCH 02/45] docs: Rename 'changes' to 'changelog' --- docs/{changes.rst => changelog.rst} | 8 ++++---- docs/index.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) rename docs/{changes.rst => changelog.rst} (99%) diff --git a/docs/changes.rst b/docs/changelog.rst similarity index 99% rename from docs/changes.rst rename to docs/changelog.rst index 2bff6c67..ae4c5d9d 100644 --- a/docs/changes.rst +++ b/docs/changelog.rst @@ -1,8 +1,8 @@ -******* -Changes -******* +********* +Changelog +********* -This change log is used to track all major changes to Mopidy. +This changelog is used to track all major changes to Mopidy. v0.14.0 (UNRELEASED) ==================== diff --git a/docs/index.rst b/docs/index.rst index bdd50d00..29153155 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -48,7 +48,7 @@ User documentation troubleshooting authors licenses - changes + changelog Reference documentation From d0f2a77e78d54d5f067baa9d218185b9a4f8ba86 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 22:01:21 +0200 Subject: [PATCH 03/45] docs: Reorganize frontpage sections --- docs/index.rst | 50 +++++++++++++++++++++++--------------------------- 1 file changed, 23 insertions(+), 27 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 29153155..7a663cd3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,28 +14,18 @@ network which can control UPnP MediaRenderers (see :ref:`upnp-clients`), or any :ref:`MPD client `. MPD clients are available for most platforms, including Windows, Mac OS X, Linux, Android, and iOS. -To install Mopidy, start by reading :ref:`installation`. +To get started with Mopidy, start by reading :ref:`installation`. If you get stuck, we usually hang around at ``#mopidy`` at `irc.freenode.net `_ and also got a `mailing list at Google Groups `_. If you stumble into a bug or got a feature request, please create an issue in the `issue -tracker `_. +tracker `_. The `source code +`_ may also be of help. -Project resources -================= - -- `Documentation `_ -- `Source code `_ -- `Issue tracker `_ -- `CI server `_ -- IRC: ``#mopidy`` at `irc.freenode.net `_ -- Mailing list: `mopidy@googlegroups.com `_ - - -User documentation -================== +Introduction +============ .. toctree:: :maxdepth: 2 @@ -46,29 +36,35 @@ User documentation running clients/index troubleshooting + + +Extensions +========== + +TODO + + +About +===== + +.. toctree:: + :maxdepth: 1 + authors licenses changelog -Reference documentation -======================= - -.. toctree:: - :maxdepth: 2 - - api/index - modules/index - - -Development documentation -========================= +Development +=========== .. toctree:: :maxdepth: 2 development extensiondev + api/index + modules/index Indices and tables From 3302e18abe531b93bcb2f378ac85e5982bd00cf2 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 22:05:00 +0200 Subject: [PATCH 04/45] docs: Add empty 'contributing' page --- docs/contributing.rst | 13 +++++++++++++ docs/index.rst | 1 + 2 files changed, 14 insertions(+) create mode 100644 docs/contributing.rst diff --git a/docs/contributing.rst b/docs/contributing.rst new file mode 100644 index 00000000..ca013e2f --- /dev/null +++ b/docs/contributing.rst @@ -0,0 +1,13 @@ +.. _contributing: + +************ +Contributing +************ + +TODO: + +- Getting started +- Making changes +- Testing +- Submitting changes +- Additional resources diff --git a/docs/index.rst b/docs/index.rst index 7a663cd3..9dd9d218 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,6 +61,7 @@ Development .. toctree:: :maxdepth: 2 + contributing development extensiondev api/index From 6cee13b5f7f5322607085e5d65f9189e14c15a28 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 22:12:18 +0200 Subject: [PATCH 05/45] docs: Tweak authors page --- docs/authors.rst | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/docs/authors.rst b/docs/authors.rst index 97a2dd2b..c740a160 100644 --- a/docs/authors.rst +++ b/docs/authors.rst @@ -6,11 +6,7 @@ Contributors to Mopidy in the order of appearance: .. include:: ../AUTHORS - -Showing your appreciation -========================= - If you already enjoy Mopidy, or don't enjoy it and want to help us making Mopidy better, the best way to do so is to contribute back to the community. You can contribute code, documentation, tests, bug reports, or help other -users, spreading the word, etc. +users, spreading the word, etc. See :ref:`contributing` for a head start. From 86dc02d794a4629c23cdd59093aa41d0829684f0 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 22:12:42 +0200 Subject: [PATCH 06/45] docs: Reduce depth of development ToC --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 9dd9d218..6b883b8e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -59,7 +59,7 @@ Development =========== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 contributing development From 7e5ff4bfae90e10d8d9ef43f9ae067f0e06a195c Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 22:23:22 +0200 Subject: [PATCH 07/45] docs: Updated intro --- README.rst | 26 ++++++++++++++------------ docs/index.rst | 25 ++++++++++++++----------- docs/modules/backends/stream.rst | 2 ++ 3 files changed, 30 insertions(+), 23 deletions(-) diff --git a/README.rst b/README.rst index b572cdab..f667b7db 100644 --- a/README.rst +++ b/README.rst @@ -2,18 +2,16 @@ Mopidy ****** -.. image:: https://secure.travis-ci.org/mopidy/mopidy.png?branch=develop +Mopidy is a music server which can play music both from multiple sources, like +your local hard drive, radio streams, and from Spotify and SoundCloud. Searches +combines results from all music sources, and you can mix tracks from all +sources in your play queue. Your playlists from Spotify or SoundCloud are also +available for use. -Mopidy is a music server which can play music both from your local hard drive -and from Spotify. Searches returns results from both your local hard drive and -from Spotify, and you can mix tracks from both sources in your play queue. Your -Spotify playlists are also available for use, though we don't support modifying -them yet. - -To control your music server, you can use the Ubuntu Sound Menu on the machine -running Mopidy, any device on the same network which can control UPnP -MediaRenderers, or any MPD client. MPD clients are available for most -platforms, including Windows, Mac OS X, Linux, Android and iOS. +To control your Mopidy music server, you can use one of Mopidy's web clients, +the Ubuntu Sound Menu, any device on the same network which can control UPnP +MediaRenderers, or any MPD client. MPD clients are available for many +platforms, including Windows, OS X, Linux, Android and iOS. To get started with Mopidy, check out `the docs `_. @@ -21,6 +19,10 @@ To get started with Mopidy, check out `the docs `_. - `Source code `_ - `Issue tracker `_ - `CI server `_ +- `Download development snapshot `_ + - IRC: ``#mopidy`` at `irc.freenode.net `_ - Mailing list: `mopidy@googlegroups.com `_ -- `Download development snapshot `_ +- Twitter: `@mopidy `_ + +.. image:: https://secure.travis-ci.org/mopidy/mopidy.png?branch=develop diff --git a/docs/index.rst b/docs/index.rst index 6b883b8e..5485f33f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -2,17 +2,18 @@ Mopidy ****** -Mopidy is a music server which can play music both from your :ref:`local hard -drive ` and from :ref:`Spotify `. Searches -returns results from both your local hard drive and from Spotify, and you can -mix tracks from both sources in your play queue. Your Spotify playlists are -also available for use, though we don't support modifying them yet. +Mopidy is a music server which can play music both from multiple sources, like +your :ref:`local hard drive `, :ref:`radio streams +`, and from :ref:`Spotify ` and SoundCloud. +Searches combines results from all music sources, and you can mix tracks from +all sources in your play queue. Your playlists from Spotify or SoundCloud are +also available for use. -To control your music server, you can use the :ref:`Ubuntu Sound Menu -` on the machine running Mopidy, any device on the same -network which can control UPnP MediaRenderers (see :ref:`upnp-clients`), or any -:ref:`MPD client `. MPD clients are available for most platforms, -including Windows, Mac OS X, Linux, Android, and iOS. +To control your Mopidy music server, you can use one of Mopidy's :ref:`web +clients `, the :ref:`Ubuntu Sound Menu `, any +device on the same network which can control :ref:`UPnP MediaRenderers +`, or any :ref:`MPD client `. MPD clients are +available for many platforms, including Windows, OS X, Linux, Android and iOS. To get started with Mopidy, start by reading :ref:`installation`. @@ -21,7 +22,9 @@ If you get stuck, we usually hang around at ``#mopidy`` at `irc.freenode.net `_. If you stumble into a bug or got a feature request, please create an issue in the `issue tracker `_. The `source code -`_ may also be of help. +`_ may also be of help. If you want to stay +up to date on Mopidy developments, you can follow `@mopidy +`_ on Twitter. Introduction diff --git a/docs/modules/backends/stream.rst b/docs/modules/backends/stream.rst index 73e53048..2843a7e9 100644 --- a/docs/modules/backends/stream.rst +++ b/docs/modules/backends/stream.rst @@ -1,3 +1,5 @@ +.. _stream-backend: + *********************************************** :mod:`mopidy.backends.stream` -- Stream backend *********************************************** From d2b9eda335fc173e8f224f7cfb42deef5cd4d43f Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 22:33:39 +0200 Subject: [PATCH 08/45] docs: Fix wording --- docs/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.rst b/docs/index.rst index 5485f33f..214ddd6c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -18,7 +18,7 @@ available for many platforms, including Windows, OS X, Linux, Android and iOS. To get started with Mopidy, start by reading :ref:`installation`. If you get stuck, we usually hang around at ``#mopidy`` at `irc.freenode.net -`_ and also got a `mailing list at Google Groups +`_ and also have a `mailing list at Google Groups `_. If you stumble into a bug or got a feature request, please create an issue in the `issue tracker `_. The `source code From 5fb16eb1ea75652fc46edabf8a3812ebe6cb0939 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 22:54:55 +0200 Subject: [PATCH 09/45] docs: Add extension registry --- docs/ext/index.rst | 33 +++++++++++++++++++++++++++++++++ docs/index.rst | 9 ++------- 2 files changed, 35 insertions(+), 7 deletions(-) create mode 100644 docs/ext/index.rst diff --git a/docs/ext/index.rst b/docs/ext/index.rst new file mode 100644 index 00000000..a94295ec --- /dev/null +++ b/docs/ext/index.rst @@ -0,0 +1,33 @@ +********** +Extensions +********** + +Here you can find a list of packages that extend Mopidy with additional +functionality. This list is moderated and updated on a regular basis. If you +want your package to show up here, follow the :ref:`guide on creating +extensions `. + + +Bundled with Mopidy +=================== + +These extensions are created and maintained by Mopidy's core developers. They +are installed together with Mopidy and are enabled by default. + +.. toctree:: + :glob: + + ** + + +External extensions +=================== + +These extensions are created and maintained by other developers. + + +Mopidy-SoundCloud +----------------- + +To play music from `SoundCloud `_ check out +`Mopidy-SoundCloud `_. diff --git a/docs/index.rst b/docs/index.rst index 214ddd6c..dd89c679 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -31,22 +31,17 @@ Introduction ============ .. toctree:: - :maxdepth: 2 + :maxdepth: 3 installation/index installation/raspberrypi config running + ext/index clients/index troubleshooting -Extensions -========== - -TODO - - About ===== From 6072bbe0b8e9012eb0f4a68b8a2502db196521d6 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 23:01:56 +0200 Subject: [PATCH 10/45] docs: Move scrobbler docs to new ext registry --- docs/ext/index.rst | 1 + docs/ext/scrobbler.rst | 46 +++++++++++++++++++++++ docs/modules/frontends/scrobbler.rst | 6 --- mopidy/frontends/scrobbler/__init__.py | 52 +++----------------------- mopidy/frontends/scrobbler/ext.conf | 4 ++ 5 files changed, 56 insertions(+), 53 deletions(-) create mode 100644 docs/ext/scrobbler.rst delete mode 100644 docs/modules/frontends/scrobbler.rst create mode 100644 mopidy/frontends/scrobbler/ext.conf diff --git a/docs/ext/index.rst b/docs/ext/index.rst index a94295ec..bfa3237f 100644 --- a/docs/ext/index.rst +++ b/docs/ext/index.rst @@ -15,6 +15,7 @@ These extensions are created and maintained by Mopidy's core developers. They are installed together with Mopidy and are enabled by default. .. toctree:: + :maxdepth: 2 :glob: ** diff --git a/docs/ext/scrobbler.rst b/docs/ext/scrobbler.rst new file mode 100644 index 00000000..1d7b3d4b --- /dev/null +++ b/docs/ext/scrobbler.rst @@ -0,0 +1,46 @@ +**************** +Mopidy-Scrobbler +**************** + +This extension scrobbles the music you play to your `Last.fm +`_ profile. + +.. note:: + + This extension requires a free user account at Last.fm. + + +Dependencies +============ + +.. literalinclude:: ../../requirements/scrobbler.txt + + +Configuration values +==================== + +.. confval:: scrobbler/enabled + + If the scrobbler extension should be enabled or not. + +.. confval:: scrobbler/username + + Your Last.fm username. + +.. confval:: scrobbler/password + + Your Last.fm password. + + +Default configuration +===================== + +.. literalinclude:: ../../mopidy/frontends/scrobbler/ext.conf + :language: ini + + +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. diff --git a/docs/modules/frontends/scrobbler.rst b/docs/modules/frontends/scrobbler.rst deleted file mode 100644 index 2af9fcff..00000000 --- a/docs/modules/frontends/scrobbler.rst +++ /dev/null @@ -1,6 +0,0 @@ -*********************************************** -:mod:`mopidy.frontends.scrobbler` -- Scrobbler -*********************************************** - -.. automodule:: mopidy.frontends.scrobbler - :synopsis: Music scrobbler frontend diff --git a/mopidy/frontends/scrobbler/__init__.py b/mopidy/frontends/scrobbler/__init__.py index f3127040..a60823d7 100644 --- a/mopidy/frontends/scrobbler/__init__.py +++ b/mopidy/frontends/scrobbler/__init__.py @@ -1,53 +1,10 @@ from __future__ import unicode_literals +import os + import mopidy from mopidy import exceptions, ext -from mopidy.utils import config, formatting - - -default_config = """ -[scrobbler] -enabled = true -username = -password = -""" - -__doc__ = """ -Frontend which scrobbles the music you play to your -`Last.fm `_ profile. - -.. note:: - - This frontend requires a free user account at Last.fm. - -**Dependencies** - -.. literalinclude:: ../../../requirements/scrobbler.txt - -**Configuration** - -.. confval:: scrobbler/enabled - - If the scrobbler extension should be enabled or not. - -.. confval:: scrobbler/username - - Your Last.fm username. - -.. confval:: scrobbler/password - - Your Last.fm password. - -**Default config** - -.. code-block:: ini - -%(config)s - -**Usage** - -The frontend is enabled by default if all dependencies are available. -""" % {'config': formatting.indent(default_config)} +from mopidy.utils import config class Extension(ext.Extension): @@ -57,7 +14,8 @@ class Extension(ext.Extension): version = mopidy.__version__ def get_default_config(self): - return default_config + conf_file = os.path.join(os.path.dirname(__file__), 'ext.conf') + return open(conf_file).read() def get_config_schema(self): schema = config.ExtensionConfigSchema() diff --git a/mopidy/frontends/scrobbler/ext.conf b/mopidy/frontends/scrobbler/ext.conf new file mode 100644 index 00000000..4fded92f --- /dev/null +++ b/mopidy/frontends/scrobbler/ext.conf @@ -0,0 +1,4 @@ +[scrobbler] +enabled = true +username = +password = From 0e9da33147b0cd4a7566e6010a1916052937c9bc Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 23:25:57 +0200 Subject: [PATCH 11/45] docs: Move HTTP to ext registry and API section --- docs/api/http.rst | 439 ++++++++++++++++++++++++ docs/api/index.rst | 1 + docs/ext/http.rst | 101 ++++++ docs/modules/frontends/http.rst | 8 - mopidy/frontends/http/__init__.py | 532 +----------------------------- mopidy/frontends/http/ext.conf | 8 + 6 files changed, 554 insertions(+), 535 deletions(-) create mode 100644 docs/api/http.rst create mode 100644 docs/ext/http.rst delete mode 100644 docs/modules/frontends/http.rst create mode 100644 mopidy/frontends/http/ext.conf diff --git a/docs/api/http.rst b/docs/api/http.rst new file mode 100644 index 00000000..16546683 --- /dev/null +++ b/docs/api/http.rst @@ -0,0 +1,439 @@ +.. _http-api: + +******** +HTTP API +******** + +The :ref:`ext-http` extension makes Mopidy's :ref:`core-api` available over +HTTP using WebSockets. We also provide a JavaScript wrapper, called +:ref:`Mopidy.js ` around the HTTP API for use both from browsers and +Node.js. + +.. warning:: API stability + + Since the HTTP API exposes our internal core API directly it is to be + regarded as **experimental**. We cannot promise to keep any form of + backwards compatibility between releases as we will need to change the core + API while working out how to support new use cases. Thus, if you use this + API, you must expect to do small adjustments to your client for every + release of Mopidy. + + From Mopidy 1.0 and onwards, we intend to keep the core API far more + stable. + + +.. _websocket-api: + +WebSocket API +============= + +The web server exposes a WebSocket at ``/mopidy/ws/``. The WebSocket gives you +access to Mopidy's full API and enables Mopidy to instantly push events to the +client, as they happen. + +On the WebSocket we send two different kind of messages: The client can send +JSON-RPC 2.0 requests, and the server will respond with JSON-RPC 2.0 responses. +In addition, the server will send event messages when something happens on the +server. Both message types are encoded as JSON objects. + + +Event messages +-------------- + +Event objects will always have a key named ``event`` whose value is the event +type. Depending on the event type, the event may include additional fields for +related data. The events maps directly to the :class:`mopidy.core.CoreListener` +API. Refer to the ``CoreListener`` method names is the available event types. +The ``CoreListener`` method's keyword arguments are all included as extra +fields on the event objects. Example event message:: + + {"event": "track_playback_started", "track": {...}} + + +JSON-RPC 2.0 messaging +---------------------- + +JSON-RPC 2.0 messages can be recognized by checking for the key named +``jsonrpc`` with the string value ``2.0``. For details on the messaging format, +please refer to the `JSON-RPC 2.0 spec +`_. + +All methods (not attributes) in the :ref:`core-api` is made available through +JSON-RPC calls over the WebSocket. For example, +:meth:`mopidy.core.PlaybackController.play` is available as the JSON-RPC method +``core.playback.play``. + +The core API's attributes is made available through setters and getters. For +example, the attribute :attr:`mopidy.core.PlaybackController.current_track` is +available as the JSON-RPC method ``core.playback.get_current_track``. + +Example JSON-RPC request:: + + {"jsonrpc": "2.0", "id": 1, "method": "core.playback.get_current_track"} + +Example JSON-RPC response:: + + {"jsonrpc": "2.0", "id": 1, "result": {"__model__": "Track", "...": "..."}} + +The JSON-RPC method ``core.describe`` returns a data structure describing all +available methods. If you're unsure how the core API maps to JSON-RPC, having a +look at the ``core.describe`` response can be helpful. + + +.. _mopidy-js: + +Mopidy.js JavaScript library +============================ + +We've made a JavaScript library, Mopidy.js, which wraps the WebSocket and gets +you quickly started with working on your client instead of figuring out how to +communicate with Mopidy. + + +Getting the library for browser use +----------------------------------- + +Regular and minified versions of Mopidy.js, ready for use, is installed +together with Mopidy. When the HTTP extension is enabled, the files are +available at: + +- http://localhost:6680/mopidy/mopidy.js +- http://localhost:6680/mopidy/mopidy.min.js + +You may need to adjust hostname and port for your local setup. + +Thus, if you use Mopidy to host your web client, like described above, you can +load the latest version of Mopidy.js by adding the following script tag to your +HTML file: + +.. code-block:: html + + + +If you don't use Mopidy to host your web client, you can find the JS files in +the Git repo at: + +- ``mopidy/frontends/http/data/mopidy.js`` +- ``mopidy/frontends/http/data/mopidy.min.js`` + + +Getting the library for Node.js use +----------------------------------- + +If you want to use Mopidy.js from Node.js instead of a browser, you can install +Mopidy.js using npm:: + + npm install mopidy + +After npm completes, you can import Mopidy.js using ``require()``: + +.. code-block:: js + + var Mopidy = require("mopidy").Mopidy; + + +Getting the library for development on the library +-------------------------------------------------- + +If you want to work on the Mopidy.js library itself, you'll find a complete +development setup in the ``js/`` dir in our repo. The instructions in +``js/README.md`` will guide you on your way. + + +Creating an instance +-------------------- + +Once you got Mopidy.js loaded, you need to create an instance of the wrapper: + +.. code-block:: js + + var mopidy = new Mopidy(); + +When you instantiate ``Mopidy()`` without arguments, it will connect to +the WebSocket at ``/mopidy/ws/`` on the current host. Thus, if you don't host +your web client using Mopidy's web server, or if you use Mopidy.js from a +Node.js environment, you'll need to pass the URL to the WebSocket end point: + +.. code-block:: js + + var mopidy = new Mopidy({ + webSocketUrl: "ws://localhost:6680/mopidy/ws/" + }); + +It is also possible to create an instance first and connect to the WebSocket +later: + +.. code-block:: js + + var mopidy = new Mopidy({autoConnect: false}); + // ... do other stuff, like hooking up events ... + mopidy.connect(); + + +Hooking up to events +-------------------- + +Once you have a Mopidy.js object, you can hook up to the events it emits. To +explore your possibilities, it can be useful to subscribe to all events and log +them: + +.. code-block:: js + + mopidy.on(console.log.bind(console)); + +Several types of events are emitted: + +- You can get notified about when the Mopidy.js object is connected to the + server and ready for method calls, when it's offline, and when it's trying to + reconnect to the server by looking at the events ``state:online``, + ``state:offline``, ``reconnectionPending``, and ``reconnecting``. + +- You can get events sent from the Mopidy server by looking at the events with + the name prefix ``event:``, like ``event:trackPlaybackStarted``. + +- You can introspect what happens internally on the WebSocket by looking at the + events emitted with the name prefix ``websocket:``. + +Mopidy.js uses the event emitter library `BANE +`_, so you should refer to BANE's +short API documentation to see how you can hook up your listeners to the +different events. + + +Calling core API methods +------------------------ + +Once your Mopidy.js object has connected to the Mopidy server and emits the +``state:online`` event, it is ready to accept core API method calls: + +.. code-block:: js + + mopidy.on("state:online", function () { + mopidy.playback.next(); + }); + +Any calls you make before the ``state:online`` event is emitted will fail. If +you've hooked up an errback (more on that a bit later) to the promise returned +from the call, the errback will be called with an error message. + +All methods in Mopidy's :ref:`core-api` is available via Mopidy.js. The core +API attributes is *not* available, but that shouldn't be a problem as we've +added (undocumented) getters and setters for all of them, so you can access the +attributes as well from JavaScript. + +Both the WebSocket API and the JavaScript API are based on introspection of the +core Python API. Thus, they will always be up to date and immediately reflect +any changes we do to the core API. + +The best way to explore the JavaScript API, is probably by opening your +browser's console, and using its tab completion to navigate the API. You'll +find the Mopidy core API exposed under ``mopidy.playback``, +``mopidy.tracklist``, ``mopidy.playlists``, and ``mopidy.library``. + +All methods in the JavaScript API have an associated data structure describing +the Python params it expects, and most methods also have the Python API +documentation available. This is available right there in the browser console, +by looking at the method's ``description`` and ``params`` attributes: + +.. code-block:: js + + console.log(mopidy.playback.next.params); + console.log(mopidy.playback.next.description); + +JSON-RPC 2.0 limits method parameters to be sent *either* by-position or +by-name. Combinations of both, like we're used to from Python, isn't supported +by JSON-RPC 2.0. To further limit this, Mopidy.js currently only supports +passing parameters by-position. + +Obviously, you'll want to get a return value from many of your method calls. +Since everything is happening across the WebSocket and maybe even across the +network, you'll get the results asynchronously. Instead of having to pass +callbacks and errbacks to every method you call, the methods return "promise" +objects, which you can use to pipe the future result as input to another +method, or to hook up callback and errback functions. + +.. code-block:: js + + var track = mopidy.playback.getCurrentTrack(); + // => ``track`` isn't a track, but a "promise" object + +Instead, typical usage will look like this: + +.. code-block:: js + + var printCurrentTrack = function (track) { + if (track) { + console.log("Currently playing:", track.name, "by", + track.artists[0].name, "from", track.album.name); + } else { + console.log("No current track"); + } + }; + + mopidy.playback.getCurrentTrack().then( + printCurrentTrack, console.error.bind(console)); + +The first function passed to ``then()``, ``printCurrentTrack``, is the callback +that will be called if the method call succeeds. The second function, +``console.error``, is the errback that will be called if anything goes wrong. +If you don't hook up an errback, debugging will be hard as errors will silently +go missing. + +For debugging, you may be interested in errors from function without +interesting return values as well. In that case, you can pass ``null`` as the +callback: + +.. code-block:: js + + mopidy.playback.next().then(null, console.error.bind(console)); + +The promise objects returned by Mopidy.js adheres to the `CommonJS Promises/A +`_ standard. We use the +implementation known as `when.js `_. Please +refer to when.js' documentation or the standard for further details on how to +work with promise objects. + + +Cleaning up +----------- + +If you for some reason want to clean up after Mopidy.js before the web page is +closed or navigated away from, you can close the WebSocket, unregister all +event listeners, and delete the object like this: + +.. code-block:: js + + // Close the WebSocket without reconnecting. Letting the object be garbage + // collected will have the same effect, so this isn't strictly necessary. + mopidy.close(); + + // Unregister all event listeners. If you don't do this, you may have + // lingering references to the object causing the garbage collector to not + // clean up after it. + mopidy.off(); + + // Delete your reference to the object, so it can be garbage collected. + mopidy = null; + + +Example to get started with +--------------------------- + +1. Make sure that you've installed all dependencies required by + :ref:`ext-http`. + +2. Create an empty directory for your web client. + +3. Change the :confval:`http/static_dir` config value to point to your new + directory. + +4. Start/restart Mopidy. + +5. Create a file in the directory named ``index.html`` containing e.g. "Hello, + world!". + +6. Visit http://localhost:6680/ to confirm that you can view your new HTML file + there. + +7. Include Mopidy.js in your web page: + + .. code-block:: html + + + +8. Add one of the following Mopidy.js examples of how to queue and start + playback of your first playlist either to your web page or a JavaScript file + that you include in your web page. + + "Imperative" style: + + .. code-block:: js + + var consoleError = console.error.bind(console); + + var trackDesc = function (track) { + return track.name + " by " + track.artists[0].name + + " from " + track.album.name; + }; + + var queueAndPlayFirstPlaylist = function () { + mopidy.playlists.getPlaylists().then(function (playlists) { + var playlist = playlists[0]; + console.log("Loading playlist:", playlist.name); + mopidy.tracklist.add(playlist.tracks).then(function (tlTracks) { + mopidy.playback.play(tlTracks[0]).then(function () { + mopidy.playback.getCurrentTrack().then(function (track) { + console.log("Now playing:", trackDesc(track)); + }, consoleError); + }, consoleError); + }, consoleError); + }, consoleError); + }; + + var mopidy = new Mopidy(); // Connect to server + mopidy.on(console.log.bind(console)); // Log all events + mopidy.on("state:online", queueAndPlayFirstPlaylist); + + Approximately the same behavior in a more functional style, using chaining + of promisies. + + .. code-block:: js + + var consoleError = console.error.bind(console); + + var getFirst = function (list) { + return list[0]; + }; + + var extractTracks = function (playlist) { + return playlist.tracks; + }; + + var printTypeAndName = function (model) { + console.log(model.__model__ + ": " + model.name); + // By returning the playlist, this function can be inserted + // anywhere a model with a name is piped in the chain. + return model; + }; + + var trackDesc = function (track) { + return track.name + " by " + track.artists[0].name + + " from " + track.album.name; + }; + + var printNowPlaying = function () { + // By returning any arguments we get, the function can be inserted + // anywhere in the chain. + var args = arguments; + return mopidy.playback.getCurrentTrack().then(function (track) { + console.log("Now playing:", trackDesc(track)); + return args; + }); + }; + + var queueAndPlayFirstPlaylist = function () { + mopidy.playlists.getPlaylists() + // => list of Playlists + .then(getFirst, consoleError) + // => Playlist + .then(printTypeAndName, consoleError) + // => Playlist + .then(extractTracks, consoleError) + // => list of Tracks + .then(mopidy.tracklist.add, consoleError) + // => list of TlTracks + .then(getFirst, consoleError) + // => TlTrack + .then(mopidy.playback.play, consoleError) + // => null + .then(printNowPlaying, consoleError); + }; + + var mopidy = new Mopidy(); // Connect to server + mopidy.on(console.log.bind(console)); // Log all events + mopidy.on("state:online", queueAndPlayFirstPlaylist); + +9. The web page should now queue and play your first playlist every time your + load it. See the browser's console for output from the function, any errors, + and all events that are emitted. + diff --git a/docs/api/index.rst b/docs/api/index.rst index 5a210812..6ba44999 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -11,3 +11,4 @@ API reference core audio frontends + http diff --git a/docs/ext/http.rst b/docs/ext/http.rst new file mode 100644 index 00000000..5c7ba79b --- /dev/null +++ b/docs/ext/http.rst @@ -0,0 +1,101 @@ +.. _ext-http: + +*********** +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. + + +Known issues +============ + +https://github.com/mopidy/mopidy/issues?labels=HTTP+frontend + + +Dependencies +============ + +.. literalinclude:: ../../requirements/http.txt + + +Configuration values +==================== + +.. confval:: http/enabled + + If the HTTP extension should be enabled or not. + +.. confval:: http/hostname + + Which address the HTTP server should bind to. + + ``127.0.0.1`` + Listens only on the IPv4 loopback interface + ``::1`` + Listens only on the IPv6 loopback interface + ``0.0.0.0`` + Listens on all IPv4 interfaces + ``::`` + Listens on all interfaces, both IPv4 and IPv6 + +.. confval:: http/port + + Which TCP port the HTTP server should listen to. + +.. confval:: http/static_dir + + Which directory the HTTP server should serve at "/" + + Change this to have Mopidy serve e.g. files for your JavaScript client. + "/mopidy" will continue to work as usual even if you change this setting. + + +Default configuration +===================== + +.. literalinclude:: ../../mopidy/frontends/http/ext.conf + :language: ini + + +Setup +===== + +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. + diff --git a/docs/modules/frontends/http.rst b/docs/modules/frontends/http.rst deleted file mode 100644 index 31366bd1..00000000 --- a/docs/modules/frontends/http.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _http-frontend: - -********************************************* -:mod:`mopidy.frontends.http` -- HTTP frontend -********************************************* - -.. automodule:: mopidy.frontends.http - :synopsis: HTTP and WebSockets frontend diff --git a/mopidy/frontends/http/__init__.py b/mopidy/frontends/http/__init__.py index 32d55f23..99399e11 100644 --- a/mopidy/frontends/http/__init__.py +++ b/mopidy/frontends/http/__init__.py @@ -1,533 +1,10 @@ from __future__ import unicode_literals +import os + import mopidy from mopidy import exceptions, ext -from mopidy.utils import config, formatting - - -default_config = """ -[http] -enabled = true -hostname = 127.0.0.1 -port = 6680 -static_dir = - -[logging.levels] -cherrypy = warning -""" - -__doc__ = """ -The HTTP frontends lets you control Mopidy through HTTP and WebSockets, e.g. -from a web based client. - -**Issues** - -https://github.com/mopidy/mopidy/issues?labels=HTTP+frontend - -**Dependencies** - -.. literalinclude:: ../../../requirements/http.txt - -**Configuration** - -.. confval:: http/enabled - - If the HTTP extension should be enabled or not. - -.. confval:: http/hostname - - Which address the HTTP server should bind to. - - ``127.0.0.1`` - Listens only on the IPv4 loopback interface - ``::1`` - Listens only on the IPv6 loopback interface - ``0.0.0.0`` - Listens on all IPv4 interfaces - ``::`` - Listens on all interfaces, both IPv4 and IPv6 - -.. confval:: http/port - - Which TCP port the HTTP server should listen to. - -.. confval:: http/static_dir - - Which directory the HTTP server should serve at "/" - - Change this to have Mopidy serve e.g. files for your JavaScript client. - "/mopidy" will continue to work as usual even if you change this setting. - -**Default config** - -.. code-block:: ini - -%(config)s - - -Setup -===== - -The frontend 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 - frontend 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. - - -WebSocket API -============= - -.. warning:: API stability - - Since this frontend exposes our internal core API directly it is to be - regarded as **experimental**. We cannot promise to keep any form of - backwards compatibility between releases as we will need to change the core - API while working out how to support new use cases. Thus, if you use this - API, you must expect to do small adjustments to your client for every - release of Mopidy. - - From Mopidy 1.0 and onwards, we intend to keep the core API far more - stable. - -The web server exposes a WebSocket at ``/mopidy/ws/``. The WebSocket gives you -access to Mopidy's full API and enables Mopidy to instantly push events to the -client, as they happen. - -On the WebSocket we send two different kind of messages: The client can send -JSON-RPC 2.0 requests, and the server will respond with JSON-RPC 2.0 responses. -In addition, the server will send event messages when something happens on the -server. Both message types are encoded as JSON objects. - - -Event messages --------------- - -Event objects will always have a key named ``event`` whose value is the event -type. Depending on the event type, the event may include additional fields for -related data. The events maps directly to the :class:`mopidy.core.CoreListener` -API. Refer to the ``CoreListener`` method names is the available event types. -The ``CoreListener`` method's keyword arguments are all included as extra -fields on the event objects. Example event message:: - - {"event": "track_playback_started", "track": {...}} - - -JSON-RPC 2.0 messaging ----------------------- - -JSON-RPC 2.0 messages can be recognized by checking for the key named -``jsonrpc`` with the string value ``2.0``. For details on the messaging format, -please refer to the `JSON-RPC 2.0 spec -`_. - -All methods (not attributes) in the :ref:`core-api` is made available through -JSON-RPC calls over the WebSocket. For example, -:meth:`mopidy.core.PlaybackController.play` is available as the JSON-RPC method -``core.playback.play``. - -The core API's attributes is made available through setters and getters. For -example, the attribute :attr:`mopidy.core.PlaybackController.current_track` is -available as the JSON-RPC method ``core.playback.get_current_track``. - -Example JSON-RPC request:: - - {"jsonrpc": "2.0", "id": 1, "method": "core.playback.get_current_track"} - -Example JSON-RPC response:: - - {"jsonrpc": "2.0", "id": 1, "result": {"__model__": "Track", "...": "..."}} - -The JSON-RPC method ``core.describe`` returns a data structure describing all -available methods. If you're unsure how the core API maps to JSON-RPC, having a -look at the ``core.describe`` response can be helpful. - - -Mopidy.js JavaScript library -============================ - -We've made a JavaScript library, Mopidy.js, which wraps the WebSocket and gets -you quickly started with working on your client instead of figuring out how to -communicate with Mopidy. - - -Getting the library for browser use ------------------------------------ - -Regular and minified versions of Mopidy.js, ready for use, is installed -together with Mopidy. When the HTTP frontend is running, the files are -available at: - -- http://localhost:6680/mopidy/mopidy.js -- http://localhost:6680/mopidy/mopidy.min.js - -You may need to adjust hostname and port for your local setup. - -Thus, if you use Mopidy to host your web client, like described above, you can -load the latest version of Mopidy.js by adding the following script tag to your -HTML file: - -.. code-block:: html - - - -If you don't use Mopidy to host your web client, you can find the JS files in -the Git repo at: - -- ``mopidy/frontends/http/data/mopidy.js`` -- ``mopidy/frontends/http/data/mopidy.min.js`` - - -Getting the library for Node.js use ------------------------------------ - -If you want to use Mopidy.js from Node.js instead of a browser, you can install -Mopidy.js using npm:: - - npm install mopidy - -After npm completes, you can import Mopidy.js using ``require()``: - -.. code-block:: js - - var Mopidy = require("mopidy").Mopidy; - - -Getting the library for development on the library --------------------------------------------------- - -If you want to work on the Mopidy.js library itself, you'll find a complete -development setup in the ``js/`` dir in our repo. The instructions in -``js/README.md`` will guide you on your way. - - -Creating an instance --------------------- - -Once you got Mopidy.js loaded, you need to create an instance of the wrapper: - -.. code-block:: js - - var mopidy = new Mopidy(); - -When you instantiate ``Mopidy()`` without arguments, it will connect to -the WebSocket at ``/mopidy/ws/`` on the current host. Thus, if you don't host -your web client using Mopidy's web server, or if you use Mopidy.js from a -Node.js environment, you'll need to pass the URL to the WebSocket end point: - -.. code-block:: js - - var mopidy = new Mopidy({ - webSocketUrl: "ws://localhost:6680/mopidy/ws/" - }); - -It is also possible to create an instance first and connect to the WebSocket -later: - -.. code-block:: js - - var mopidy = new Mopidy({autoConnect: false}); - // ... do other stuff, like hooking up events ... - mopidy.connect(); - - -Hooking up to events --------------------- - -Once you have a Mopidy.js object, you can hook up to the events it emits. To -explore your possibilities, it can be useful to subscribe to all events and log -them: - -.. code-block:: js - - mopidy.on(console.log.bind(console)); - -Several types of events are emitted: - -- You can get notified about when the Mopidy.js object is connected to the - server and ready for method calls, when it's offline, and when it's trying to - reconnect to the server by looking at the events ``state:online``, - ``state:offline``, ``reconnectionPending``, and ``reconnecting``. - -- You can get events sent from the Mopidy server by looking at the events with - the name prefix ``event:``, like ``event:trackPlaybackStarted``. - -- You can introspect what happens internally on the WebSocket by looking at the - events emitted with the name prefix ``websocket:``. - -Mopidy.js uses the event emitter library `BANE -`_, so you should refer to BANE's -short API documentation to see how you can hook up your listeners to the -different events. - - -Calling core API methods ------------------------- - -Once your Mopidy.js object has connected to the Mopidy server and emits the -``state:online`` event, it is ready to accept core API method calls: - -.. code-block:: js - - mopidy.on("state:online", function () { - mopidy.playback.next(); - }); - -Any calls you make before the ``state:online`` event is emitted will fail. If -you've hooked up an errback (more on that a bit later) to the promise returned -from the call, the errback will be called with an error message. - -All methods in Mopidy's :ref:`core-api` is available via Mopidy.js. The core -API attributes is *not* available, but that shouldn't be a problem as we've -added (undocumented) getters and setters for all of them, so you can access the -attributes as well from JavaScript. - -Both the WebSocket API and the JavaScript API are based on introspection of the -core Python API. Thus, they will always be up to date and immediately reflect -any changes we do to the core API. - -The best way to explore the JavaScript API, is probably by opening your -browser's console, and using its tab completion to navigate the API. You'll -find the Mopidy core API exposed under ``mopidy.playback``, -``mopidy.tracklist``, ``mopidy.playlists``, and ``mopidy.library``. - -All methods in the JavaScript API have an associated data structure describing -the Python params it expects, and most methods also have the Python API -documentation available. This is available right there in the browser console, -by looking at the method's ``description`` and ``params`` attributes: - -.. code-block:: js - - console.log(mopidy.playback.next.params); - console.log(mopidy.playback.next.description); - -JSON-RPC 2.0 limits method parameters to be sent *either* by-position or -by-name. Combinations of both, like we're used to from Python, isn't supported -by JSON-RPC 2.0. To further limit this, Mopidy.js currently only supports -passing parameters by-position. - -Obviously, you'll want to get a return value from many of your method calls. -Since everything is happening across the WebSocket and maybe even across the -network, you'll get the results asynchronously. Instead of having to pass -callbacks and errbacks to every method you call, the methods return "promise" -objects, which you can use to pipe the future result as input to another -method, or to hook up callback and errback functions. - -.. code-block:: js - - var track = mopidy.playback.getCurrentTrack(); - // => ``track`` isn't a track, but a "promise" object - -Instead, typical usage will look like this: - -.. code-block:: js - - var printCurrentTrack = function (track) { - if (track) { - console.log("Currently playing:", track.name, "by", - track.artists[0].name, "from", track.album.name); - } else { - console.log("No current track"); - } - }; - - mopidy.playback.getCurrentTrack().then( - printCurrentTrack, console.error.bind(console)); - -The first function passed to ``then()``, ``printCurrentTrack``, is the callback -that will be called if the method call succeeds. The second function, -``console.error``, is the errback that will be called if anything goes wrong. -If you don't hook up an errback, debugging will be hard as errors will silently -go missing. - -For debugging, you may be interested in errors from function without -interesting return values as well. In that case, you can pass ``null`` as the -callback: - -.. code-block:: js - - mopidy.playback.next().then(null, console.error.bind(console)); - -The promise objects returned by Mopidy.js adheres to the `CommonJS Promises/A -`_ standard. We use the -implementation known as `when.js `_. Please -refer to when.js' documentation or the standard for further details on how to -work with promise objects. - - -Cleaning up ------------ - -If you for some reason want to clean up after Mopidy.js before the web page is -closed or navigated away from, you can close the WebSocket, unregister all -event listeners, and delete the object like this: - -.. code-block:: js - - // Close the WebSocket without reconnecting. Letting the object be garbage - // collected will have the same effect, so this isn't strictly necessary. - mopidy.close(); - - // Unregister all event listeners. If you don't do this, you may have - // lingering references to the object causing the garbage collector to not - // clean up after it. - mopidy.off(); - - // Delete your reference to the object, so it can be garbage collected. - mopidy = null; - - -Example to get started with ---------------------------- - -1. Make sure that you've installed all dependencies required by the HTTP - frontend. - -2. Create an empty directory for your web client. - -3. Change the :confval:`http/static_dir` config value to point to your new - directory. - -4. Start/restart Mopidy. - -5. Create a file in the directory named ``index.html`` containing e.g. "Hello, - world!". - -6. Visit http://localhost:6680/ to confirm that you can view your new HTML file - there. - -7. Include Mopidy.js in your web page: - - .. code-block:: html - - - -8. Add one of the following Mopidy.js examples of how to queue and start - playback of your first playlist either to your web page or a JavaScript file - that you include in your web page. - - "Imperative" style: - - .. code-block:: js - - var consoleError = console.error.bind(console); - - var trackDesc = function (track) { - return track.name + " by " + track.artists[0].name + - " from " + track.album.name; - }; - - var queueAndPlayFirstPlaylist = function () { - mopidy.playlists.getPlaylists().then(function (playlists) { - var playlist = playlists[0]; - console.log("Loading playlist:", playlist.name); - mopidy.tracklist.add(playlist.tracks).then(function (tlTracks) { - mopidy.playback.play(tlTracks[0]).then(function () { - mopidy.playback.getCurrentTrack().then(function (track) { - console.log("Now playing:", trackDesc(track)); - }, consoleError); - }, consoleError); - }, consoleError); - }, consoleError); - }; - - var mopidy = new Mopidy(); // Connect to server - mopidy.on(console.log.bind(console)); // Log all events - mopidy.on("state:online", queueAndPlayFirstPlaylist); - - Approximately the same behavior in a more functional style, using chaining - of promisies. - - .. code-block:: js - - var consoleError = console.error.bind(console); - - var getFirst = function (list) { - return list[0]; - }; - - var extractTracks = function (playlist) { - return playlist.tracks; - }; - - var printTypeAndName = function (model) { - console.log(model.__model__ + ": " + model.name); - // By returning the playlist, this function can be inserted - // anywhere a model with a name is piped in the chain. - return model; - }; - - var trackDesc = function (track) { - return track.name + " by " + track.artists[0].name + - " from " + track.album.name; - }; - - var printNowPlaying = function () { - // By returning any arguments we get, the function can be inserted - // anywhere in the chain. - var args = arguments; - return mopidy.playback.getCurrentTrack().then(function (track) { - console.log("Now playing:", trackDesc(track)); - return args; - }); - }; - - var queueAndPlayFirstPlaylist = function () { - mopidy.playlists.getPlaylists() - // => list of Playlists - .then(getFirst, consoleError) - // => Playlist - .then(printTypeAndName, consoleError) - // => Playlist - .then(extractTracks, consoleError) - // => list of Tracks - .then(mopidy.tracklist.add, consoleError) - // => list of TlTracks - .then(getFirst, consoleError) - // => TlTrack - .then(mopidy.playback.play, consoleError) - // => null - .then(printNowPlaying, consoleError); - }; - - var mopidy = new Mopidy(); // Connect to server - mopidy.on(console.log.bind(console)); // Log all events - mopidy.on("state:online", queueAndPlayFirstPlaylist); - -9. The web page should now queue and play your first playlist every time your - load it. See the browser's console for output from the function, any errors, - and all events that are emitted. -""" % {'config': formatting.indent(default_config)} +from mopidy.utils import config class Extension(ext.Extension): @@ -537,7 +14,8 @@ class Extension(ext.Extension): version = mopidy.__version__ def get_default_config(self): - return default_config + conf_file = os.path.join(os.path.dirname(__file__), 'ext.conf') + return open(conf_file).read() def get_config_schema(self): schema = config.ExtensionConfigSchema() diff --git a/mopidy/frontends/http/ext.conf b/mopidy/frontends/http/ext.conf new file mode 100644 index 00000000..8f8f2a1e --- /dev/null +++ b/mopidy/frontends/http/ext.conf @@ -0,0 +1,8 @@ +[http] +enabled = true +hostname = 127.0.0.1 +port = 6680 +static_dir = + +[logging.levels] +cherrypy = warning From 7a4475b3d655a0dcad8d4dffa54eb15188dd6a41 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 23:27:16 +0200 Subject: [PATCH 12/45] docs: Unbreak link from changelog --- docs/changelog.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/changelog.rst b/docs/changelog.rst index ae4c5d9d..ab97bf08 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -333,7 +333,7 @@ We've added an HTTP frontend for those wanting to build web clients for Mopidy! **HTTP frontend** - Added new optional HTTP frontend which exposes Mopidy's core API through - JSON-RPC 2.0 messages over a WebSocket. See :ref:`http-frontend` for further + JSON-RPC 2.0 messages over a WebSocket. See :ref:`http-api` for further details. - Added a JavaScript library, Mopidy.js, to make it easier to develop web based From 21f2e5c8b09e6d426daae82509c0a009374f91f0 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 23:34:12 +0200 Subject: [PATCH 13/45] docs: Unbreak links from HTTP client page --- docs/clients/http.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/clients/http.rst b/docs/clients/http.rst index 5381eaff..d67dbb7b 100644 --- a/docs/clients/http.rst +++ b/docs/clients/http.rst @@ -4,14 +4,14 @@ HTTP clients ************ -Mopidy added an :ref:`HTTP frontend ` in 0.10 which provides the +Mopidy added an :ref:`HTTP frontend ` in 0.10 which provides the building blocks needed for creating web clients for Mopidy with the help of a WebSocket and a JavaScript library provided by Mopidy. This page will list any HTTP/web Mopidy clients. If you've created one, please notify us so we can include your client on this page. -See :ref:`http-frontend` for details on how to build your own web client. +See :ref:`http-api` for details on how to build your own web client. woutervanwijk/Mopidy-Webclient From 82d2ecd41e376039a93d0ae995cf7ce3e1547f33 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 23:38:45 +0200 Subject: [PATCH 14/45] docs: Move MPRIS to ext registry --- docs/ext/mpris.rst | 70 ++++++++++++++++++++++++++++ docs/modules/frontends/mpris.rst | 8 ---- mopidy/frontends/mpris/__init__.py | 74 ++---------------------------- mopidy/frontends/mpris/ext.conf | 3 ++ 4 files changed, 76 insertions(+), 79 deletions(-) create mode 100644 docs/ext/mpris.rst delete mode 100644 docs/modules/frontends/mpris.rst create mode 100644 mopidy/frontends/mpris/ext.conf diff --git a/docs/ext/mpris.rst b/docs/ext/mpris.rst new file mode 100644 index 00000000..b1c23278 --- /dev/null +++ b/docs/ext/mpris.rst @@ -0,0 +1,70 @@ +************ +Mopidy-MPRIS +************ + +This extension lets you control Mopidy through the Media Player Remote +Interfacing Specification (`MPRIS `_) D-Bus interface. + +An example of an MPRIS client is the :ref:`ubuntu-sound-menu`. + + +Dependencies +============ + +- D-Bus Python bindings. The package is named ``python-dbus`` in + Ubuntu/Debian. + +- ``libindicate`` Python bindings is needed to expose Mopidy in e.g. the + Ubuntu Sound Menu. The package is named ``python-indicate`` in + Ubuntu/Debian. + +- An ``.desktop`` file for Mopidy installed at the path set in the + :confval:`mpris/desktop_file` config value. See :ref:`install-desktop-file` + for details. + + +Configuration values +==================== + +.. confval:: mpris/enabled + + If the MPRIS extension should be enabled or not. + +.. confval:: mpris/desktop_file + + Location of the Mopidy ``.desktop`` file. + + +Default configuration +===================== + +.. literalinclude:: ../../mopidy/frontends/mpris/ext.conf + :language: ini + + +Usage +===== + +The extension is enabled by default if all dependencies are available. + + +Testing the MPRIS API +===================== + +To test, start Mopidy, and then run the following in a Python shell:: + + import dbus + bus = dbus.SessionBus() + player = bus.get_object('org.mpris.MediaPlayer2.mopidy', + '/org/mpris/MediaPlayer2') + +Now you can control Mopidy through the player object. Examples: + +- To get some properties from Mopidy, run:: + + props = player.GetAll('org.mpris.MediaPlayer2', + dbus_interface='org.freedesktop.DBus.Properties') + +- To quit Mopidy through D-Bus, run:: + + player.Quit(dbus_interface='org.mpris.MediaPlayer2') diff --git a/docs/modules/frontends/mpris.rst b/docs/modules/frontends/mpris.rst deleted file mode 100644 index e0ec63da..00000000 --- a/docs/modules/frontends/mpris.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _mpris-frontend: - -*********************************************** -:mod:`mopidy.frontends.mpris` -- MPRIS frontend -*********************************************** - -.. automodule:: mopidy.frontends.mpris - :synopsis: MPRIS frontend diff --git a/mopidy/frontends/mpris/__init__.py b/mopidy/frontends/mpris/__init__.py index 5be9c6cf..7601d81f 100644 --- a/mopidy/frontends/mpris/__init__.py +++ b/mopidy/frontends/mpris/__init__.py @@ -4,76 +4,7 @@ import os import mopidy from mopidy import exceptions, ext -from mopidy.utils import formatting, config - - -default_config = """ -[mpris] -enabled = true -desktop_file = /usr/share/applications/mopidy.desktop -""" - -__doc__ = """ -Frontend which lets you control Mopidy through the Media Player Remote -Interfacing Specification (`MPRIS `_) D-Bus -interface. - -An example of an MPRIS client is the `Ubuntu Sound Menu -`_. - -**Dependencies** - -- D-Bus Python bindings. The package is named ``python-dbus`` in - Ubuntu/Debian. - -- ``libindicate`` Python bindings is needed to expose Mopidy in e.g. the - Ubuntu Sound Menu. The package is named ``python-indicate`` in - Ubuntu/Debian. - -- An ``.desktop`` file for Mopidy installed at the path set in the - :confval:`mpris/desktop_file` config value. See :ref:`install-desktop-file` - for details. - -**Configuration** - -.. confval:: mpris/enabled - - If the MPRIS extension should be enabled or not. - -.. confval:: mpris/desktop_file - - Location of the Mopidy ``.desktop`` file. - -**Default config** - -.. code-block:: ini - -%(config)s - -**Usage** - -The frontend is enabled by default if all dependencies are available. - -**Testing the frontend** - -To test, start Mopidy, and then run the following in a Python shell:: - - import dbus - bus = dbus.SessionBus() - player = bus.get_object('org.mpris.MediaPlayer2.mopidy', - '/org/mpris/MediaPlayer2') - -Now you can control Mopidy through the player object. Examples: - -- To get some properties from Mopidy, run:: - - props = player.GetAll('org.mpris.MediaPlayer2', - dbus_interface='org.freedesktop.DBus.Properties') - -- To quit Mopidy through D-Bus, run:: - - player.Quit(dbus_interface='org.mpris.MediaPlayer2') -""" % {'config': formatting.indent(default_config)} +from mopidy.utils import config class Extension(ext.Extension): @@ -83,7 +14,8 @@ class Extension(ext.Extension): version = mopidy.__version__ def get_default_config(self): - return default_config + conf_file = os.path.join(os.path.dirname(__file__), 'ext.conf') + return open(conf_file).read() def get_config_schema(self): schema = config.ExtensionConfigSchema() diff --git a/mopidy/frontends/mpris/ext.conf b/mopidy/frontends/mpris/ext.conf new file mode 100644 index 00000000..b83411c2 --- /dev/null +++ b/mopidy/frontends/mpris/ext.conf @@ -0,0 +1,3 @@ +[mpris] +enabled = true +desktop_file = /usr/share/applications/mopidy.desktop From b7546eed0b24af8bdf18116e175bad927fe75211 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Thu, 11 Apr 2013 23:58:42 +0200 Subject: [PATCH 15/45] docs: Move MPD to ext registry --- docs/ext/mpd.rst | 107 +++++++++++++++++++++++++++++++ mopidy/frontends/mpd/__init__.py | 103 ++--------------------------- mopidy/frontends/mpd/ext.conf | 7 ++ 3 files changed, 119 insertions(+), 98 deletions(-) create mode 100644 docs/ext/mpd.rst create mode 100644 mopidy/frontends/mpd/ext.conf diff --git a/docs/ext/mpd.rst b/docs/ext/mpd.rst new file mode 100644 index 00000000..fc5a3082 --- /dev/null +++ b/docs/ext/mpd.rst @@ -0,0 +1,107 @@ +.. _ext-mpd: + +********** +Mopidy-MPD +********** + +This extension implements an MPD server to make Mopidy available to :ref:`MPD +clients `. + +MPD stands for Music Player Daemon, which is also the name of the `original MPD +server project `_. Mopidy does not depend on the +original MPD server, but implements the MPD protocol itself, and is thus +compatible with clients for the original MPD server. + +For more details on our MPD server implementation, see +:mod:`mopidy.frontends.mpd`. + + +Known issues +============ + +https://github.com/mopidy/mopidy/issues?labels=MPD+frontend + + +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. + +- Toggling of audio outputs is not supported +- Channels for client-to-client communication are not supported +- Stickers are not supported +- Crossfade is not supported +- Replay gain is not supported +- ``count`` does not provide any statistics +- ``stats`` does not provide any statistics +- ``list`` does not support listing tracks by genre +- ``decoders`` does not provide information about available decoders + +The following items are currently not supported, but should be added in the +near future: + +- Modifying stored playlists is not supported +- ``tagtypes`` is not supported +- Browsing the file system is not supported +- Live update of the music database is not supported + + +Dependencies +============ + +None. The extension just needs Mopidy. + + +Configuration values +==================== + +.. confval:: mpd/enabled + + If the MPD extension should be enabled or not. + +.. confval:: mpd/hostname + + Which address the MPD server should bind to. + + ``127.0.0.1`` + Listens only on the IPv4 loopback interface + ``::1`` + Listens only on the IPv6 loopback interface + ``0.0.0.0`` + Listens on all IPv4 interfaces + ``::`` + Listens on all interfaces, both IPv4 and IPv6 + +.. confval:: mpd/port + + Which TCP port the MPD server should listen to. + +.. confval:: mpd/password + + The password required for connecting to the MPD server. If blank, no + password is required. + +.. confval:: mpd/max_connections + + The maximum number of concurrent connections the MPD server will accept. + +.. confval:: mpd/connection_timeout + + Number of seconds an MPD client can stay inactive before the connection is + closed by the server. + + +Default configuration +===================== + +.. literalinclude:: ../../mopidy/frontends/mpd/ext.conf + :language: ini + + +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`. diff --git a/mopidy/frontends/mpd/__init__.py b/mopidy/frontends/mpd/__init__.py index 69297374..d0f082ae 100644 --- a/mopidy/frontends/mpd/__init__.py +++ b/mopidy/frontends/mpd/__init__.py @@ -1,104 +1,10 @@ from __future__ import unicode_literals +import os + import mopidy from mopidy import ext -from mopidy.utils import config, formatting - - -default_config = """ -[mpd] -enabled = true -hostname = 127.0.0.1 -port = 6600 -password = -max_connections = 20 -connection_timeout = 60 -""" - -__doc__ = """The MPD server frontend. - -MPD stands for Music Player Daemon. MPD is an independent project and server. -Mopidy implements the MPD protocol, and is thus compatible with clients for the -original MPD server. - -**Issues** - -https://github.com/mopidy/mopidy/issues?labels=MPD+frontend - -**Dependencies** - -None - -**Configuration** - -.. confval:: mpd/enabled - - If the MPD extension should be enabled or not. - -.. confval:: mpd/hostname - - Which address the MPD server should bind to. - - ``127.0.0.1`` - Listens only on the IPv4 loopback interface - ``::1`` - Listens only on the IPv6 loopback interface - ``0.0.0.0`` - Listens on all IPv4 interfaces - ``::`` - Listens on all interfaces, both IPv4 and IPv6 - -.. confval:: mpd/port - - Which TCP port the MPD server should listen to. - -.. confval:: mpd/password - - The password required for connecting to the MPD server. If blank, no - password is required. - -.. confval:: mpd/max_connections - - The maximum number of concurrent connections the MPD server will accept. - -.. confval:: mpd/connection_timeout - - Number of seconds an MPD client can stay inactive before the connection is - closed by the server. - -**Default config** - -.. code-block:: ini - -%(config)s - -**Usage:** - -The frontend is enabled by default. - -**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. - -- Toggling of audio outputs is not supported -- Channels for client-to-client communication are not supported -- Stickers are not supported -- Crossfade is not supported -- Replay gain is not supported -- ``count`` does not provide any statistics -- ``stats`` does not provide any statistics -- ``list`` does not support listing tracks by genre -- ``decoders`` does not provide information about available decoders - -The following items are currently not supported, but should be added in the -near future: - -- Modifying stored playlists is not supported -- ``tagtypes`` is not supported -- Browsing the file system is not supported -- Live update of the music database is not supported -""" % {'config': formatting.indent(default_config)} +from mopidy.utils import config class Extension(ext.Extension): @@ -108,7 +14,8 @@ class Extension(ext.Extension): version = mopidy.__version__ def get_default_config(self): - return default_config + conf_file = os.path.join(os.path.dirname(__file__), 'ext.conf') + return open(conf_file).read() def get_config_schema(self): schema = config.ExtensionConfigSchema() diff --git a/mopidy/frontends/mpd/ext.conf b/mopidy/frontends/mpd/ext.conf new file mode 100644 index 00000000..bf77100c --- /dev/null +++ b/mopidy/frontends/mpd/ext.conf @@ -0,0 +1,7 @@ +[mpd] +enabled = true +hostname = 127.0.0.1 +port = 6600 +password = +max_connections = 20 +connection_timeout = 60 From 12938df3a1d374a421b961f8e321aa851c940004 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 00:04:55 +0200 Subject: [PATCH 16/45] docs: Unbreak links to MPRIS docs --- docs/clients/mpris.rst | 6 +++--- docs/clients/upnp.rst | 22 +++++++++++----------- docs/ext/mpris.rst | 2 ++ 3 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docs/clients/mpris.rst b/docs/clients/mpris.rst index 28da63ed..141a2371 100644 --- a/docs/clients/mpris.rst +++ b/docs/clients/mpris.rst @@ -8,9 +8,9 @@ MPRIS clients Specification. It's a spec that describes a standard D-Bus interface for making media players available to other applications on the same system. -Mopidy's :ref:`MPRIS frontend ` currently implements all -required parts of the MPRIS spec, plus the optional playlist interface. It does -not implement the optional tracklist interface. +Mopidy's :ref:`MPRIS frontend ` currently implements all required +parts of the MPRIS spec, plus the optional playlist interface. It does not +implement the optional tracklist interface. .. _ubuntu-sound-menu: diff --git a/docs/clients/upnp.rst b/docs/clients/upnp.rst index 567fb04f..c90227e2 100644 --- a/docs/clients/upnp.rst +++ b/docs/clients/upnp.rst @@ -37,18 +37,18 @@ How to make Mopidy available as an UPnP MediaRenderer With the help of `the Rygel project `_ Mopidy can be made available as an UPnP MediaRenderer. Rygel will interface with Mopidy's -:ref:`MPRIS frontend `, and make Mopidy available as a -MediaRenderer on the local network. Since this depends on the MPRIS frontend, -which again depends on D-Bus being available, this will only work on Linux, and -not OS X. MPRIS/D-Bus is only available to other applications on the same host, -so Rygel must be running on the same machine as Mopidy. +:ref:`MPRIS frontend `, and make Mopidy available as a MediaRenderer +on the local network. Since this depends on the MPRIS frontend, which again +depends on D-Bus being available, this will only work on Linux, and not OS X. +MPRIS/D-Bus is only available to other applications on the same host, so Rygel +must be running on the same machine as Mopidy. -1. Start Mopidy and make sure the :ref:`MPRIS frontend ` is - working. It is activated by default, but you may miss dependencies or be - using OS X, in which case it will not work. Check the console output when - Mopidy is started for any errors related to the MPRIS frontend. If you're - unsure it is working, there are instructions for how to test it on the - :ref:`MPRIS frontend ` page. +1. Start Mopidy and make sure the :ref:`MPRIS frontend ` is working. + It is activated by default, but you may miss dependencies or be using OS X, + in which case it will not work. Check the console output when Mopidy is + started for any errors related to the MPRIS frontend. If you're unsure it is + working, there are instructions for how to test it on the :ref:`MPRIS + frontend ` page. 2. Install Rygel. On Debian/Ubuntu:: diff --git a/docs/ext/mpris.rst b/docs/ext/mpris.rst index b1c23278..88510d98 100644 --- a/docs/ext/mpris.rst +++ b/docs/ext/mpris.rst @@ -1,3 +1,5 @@ +.. _ext-mpris: + ************ Mopidy-MPRIS ************ From 08117841c1c71f9fdd3e75b738820bbd1d2068ba Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 00:05:56 +0200 Subject: [PATCH 17/45] docs: Move Spotify to ext registry --- docs/ext/spotify.rst | 68 ++++++++++++++++++++++++++ docs/index.rst | 2 +- docs/modules/backends/spotify.rst | 8 --- mopidy/backends/spotify/__init__.py | 75 ++--------------------------- mopidy/backends/spotify/ext.conf | 7 +++ 5 files changed, 81 insertions(+), 79 deletions(-) create mode 100644 docs/ext/spotify.rst delete mode 100644 docs/modules/backends/spotify.rst create mode 100644 mopidy/backends/spotify/ext.conf diff --git a/docs/ext/spotify.rst b/docs/ext/spotify.rst new file mode 100644 index 00000000..0d3729b2 --- /dev/null +++ b/docs/ext/spotify.rst @@ -0,0 +1,68 @@ +.. _ext-spotify: + +************** +Mopidy-Spotify +************** + +An extension for playing music from Spotify. + +`Spotify `_ is a music streaming service. The backend +uses the official `libspotify +`_ library and the +`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 + otherwise approved in any way by Spotify. Spotify is the registered + trade mark of the Spotify Group. + + +Known issues +============ + +https://github.com/mopidy/mopidy/issues?labels=Spotify+backend + + +Dependencies +============ + +.. literalinclude:: ../../requirements/spotify.txt + + +Configuration values +==================== + +.. confval:: spotify/enabled + + If the Spotify extension should be enabled or not. + +.. confval:: spotify/username + + Your Spotify Premium username. + +.. confval:: spotify/password + + Your Spotify Premium password. + +.. confval:: spotify/bitrate + + The preferred audio bitrate. Valid values are 96, 160, 320. + +.. confval:: spotify/timeout + + Max number of seconds to wait for Spotify operations to complete. + +.. confval:: spotify/cache_dir + + Path to the Spotify data cache. Cannot be shared with other Spotify apps. + + +Default configuration +===================== + +.. literalinclude:: ../../mopidy/backends/spotify/ext.conf + :language: ini diff --git a/docs/index.rst b/docs/index.rst index dd89c679..e5d21385 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,7 +4,7 @@ Mopidy Mopidy is a music server which can play music both from multiple sources, like your :ref:`local hard drive `, :ref:`radio streams -`, and from :ref:`Spotify ` and SoundCloud. +`, and from :ref:`Spotify ` and SoundCloud. Searches combines results from all music sources, and you can mix tracks from all sources in your play queue. Your playlists from Spotify or SoundCloud are also available for use. diff --git a/docs/modules/backends/spotify.rst b/docs/modules/backends/spotify.rst deleted file mode 100644 index b410f272..00000000 --- a/docs/modules/backends/spotify.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _spotify-backend: - -************************************************* -:mod:`mopidy.backends.spotify` -- Spotify backend -************************************************* - -.. automodule:: mopidy.backends.spotify - :synopsis: Backend for the Spotify music streaming service diff --git a/mopidy/backends/spotify/__init__.py b/mopidy/backends/spotify/__init__.py index c26a42e7..d26c9cd3 100644 --- a/mopidy/backends/spotify/__init__.py +++ b/mopidy/backends/spotify/__init__.py @@ -1,77 +1,11 @@ from __future__ import unicode_literals +import os + import mopidy from mopidy import ext from mopidy.exceptions import ExtensionError -from mopidy.utils import config, formatting - - -default_config = """ -[spotify] -enabled = true -username = -password = -bitrate = 160 -timeout = 10 -cache_dir = $XDG_CACHE_DIR/mopidy/spotify -""" - -__doc__ = """A backend for playing music from Spotify - -`Spotify `_ is a music streaming service. The backend -uses the official `libspotify -`_ library and the -`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 - otherwise approved in any way by Spotify. Spotify is the registered - trade mark of the Spotify Group. - -**Issues** - -https://github.com/mopidy/mopidy/issues?labels=Spotify+backend - -**Dependencies** - -.. literalinclude:: ../../../requirements/spotify.txt - -**Configuration** - -.. confval:: spotify/enabled - - If the Spotify extension should be enabled or not. - -.. confval:: spotify/username - - Your Spotify Premium username. - -.. confval:: spotify/password - - Your Spotify Premium password. - -.. confval:: spotify/bitrate - - The preferred audio bitrate. Valid values are 96, 160, 320. - -.. confval:: spotify/timeout - - Max number of seconds to wait for Spotify operations to complete. - -.. confval:: spotify/cache_dir - - Path to the Spotify data cache. Cannot be shared with other Spotify apps. - -**Default config** - -.. code-block:: ini - -%(config)s -""" % {'config': formatting.indent(default_config)} +from mopidy.utils import config class Extension(ext.Extension): @@ -81,7 +15,8 @@ class Extension(ext.Extension): version = mopidy.__version__ def get_default_config(self): - return default_config + conf_file = os.path.join(os.path.dirname(__file__), 'ext.conf') + return open(conf_file).read() def get_config_schema(self): schema = config.ExtensionConfigSchema() diff --git a/mopidy/backends/spotify/ext.conf b/mopidy/backends/spotify/ext.conf new file mode 100644 index 00000000..83bf191a --- /dev/null +++ b/mopidy/backends/spotify/ext.conf @@ -0,0 +1,7 @@ +[spotify] +enabled = true +username = +password = +bitrate = 160 +timeout = 10 +cache_dir = $XDG_CACHE_DIR/mopidy/spotify From 7c01db842d62133391c60642297a5ed20d714996 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 00:07:59 +0200 Subject: [PATCH 18/45] docs: Remove empty dummy backend docs --- docs/modules/backends/dummy.rst | 7 ------- 1 file changed, 7 deletions(-) delete mode 100644 docs/modules/backends/dummy.rst diff --git a/docs/modules/backends/dummy.rst b/docs/modules/backends/dummy.rst deleted file mode 100644 index 03b2e6ce..00000000 --- a/docs/modules/backends/dummy.rst +++ /dev/null @@ -1,7 +0,0 @@ -********************************************************* -:mod:`mopidy.backends.dummy` -- Dummy backend for testing -********************************************************* - -.. automodule:: mopidy.backends.dummy - :synopsis: Dummy backend used for testing - :members: From 8bcf1de21c51ec0bdc24409e848244e2fdd0d302 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 00:13:22 +0200 Subject: [PATCH 19/45] docs: Move stream to ext registry --- docs/ext/stream.rst | 42 ++++++++++++++++++++++++ docs/index.rst | 8 ++--- docs/modules/backends/stream.rst | 9 ------ mopidy/backends/stream/__init__.py | 52 +++--------------------------- mopidy/backends/stream/ext.conf | 9 ++++++ 5 files changed, 60 insertions(+), 60 deletions(-) create mode 100644 docs/ext/stream.rst delete mode 100644 docs/modules/backends/stream.rst create mode 100644 mopidy/backends/stream/ext.conf diff --git a/docs/ext/stream.rst b/docs/ext/stream.rst new file mode 100644 index 00000000..3d7ea7d3 --- /dev/null +++ b/docs/ext/stream.rst @@ -0,0 +1,42 @@ +.. _ext-stream: + +************* +Mopidy-Stream +************* + +Extension for playing streaming music. + +The stream backend will handle streaming of URIs matching the +:confval:`stream/protocols` config value, assuming the needed GStreamer plugins +are installed. + + +Known issues +============ + +https://github.com/mopidy/mopidy/issues?labels=Stream+backend + + +Dependencies +============ + +None. The extension just needs Mopidy. + + +Configuration values +==================== + +.. confval:: stream/enabled + + If the stream extension should be enabled or not. + +.. confval:: stream/protocols + + Whitelist of URI schemas to allow streaming from. + + +Default configuration +===================== + +.. literalinclude:: ../../mopidy/backends/stream/ext.conf + :language: ini diff --git a/docs/index.rst b/docs/index.rst index e5d21385..16518f53 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -4,10 +4,10 @@ Mopidy Mopidy is a music server which can play music both from multiple sources, like your :ref:`local hard drive `, :ref:`radio streams -`, and from :ref:`Spotify ` and SoundCloud. -Searches combines results from all music sources, and you can mix tracks from -all sources in your play queue. Your playlists from Spotify or SoundCloud are -also available for use. +`, and from :ref:`Spotify ` and SoundCloud. Searches +combines results from all music sources, and you can mix tracks from all +sources in your play queue. Your playlists from Spotify or SoundCloud are also +available for use. To control your Mopidy music server, you can use one of Mopidy's :ref:`web clients `, the :ref:`Ubuntu Sound Menu `, any diff --git a/docs/modules/backends/stream.rst b/docs/modules/backends/stream.rst deleted file mode 100644 index 2843a7e9..00000000 --- a/docs/modules/backends/stream.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. _stream-backend: - -*********************************************** -:mod:`mopidy.backends.stream` -- Stream backend -*********************************************** - -.. automodule:: mopidy.backends.stream - :synopsis: Backend for playing audio streams - :members: diff --git a/mopidy/backends/stream/__init__.py b/mopidy/backends/stream/__init__.py index 11918500..904c9a7f 100644 --- a/mopidy/backends/stream/__init__.py +++ b/mopidy/backends/stream/__init__.py @@ -1,53 +1,10 @@ from __future__ import unicode_literals +import os + import mopidy from mopidy import ext -from mopidy.utils import config, formatting - - -default_config = """ -[stream] -enabled = true -protocols = - http - https - mms - rtmp - rtmps - rtsp -""" - -__doc__ = """ -A backend for playing music for streaming music. - -This backend will handle streaming of URIs matching the -:confval:`stream/protocols` config value, assuming the needed GStreamer plugins -are installed. - -**Issues** - -https://github.com/mopidy/mopidy/issues?labels=Stream+backend - -**Dependencies** - -None - -**Configuration** - -.. confval:: stream/enabled - - If the stream extension should be enabled or not. - -.. confval:: stream/protocols - - Whitelist of URI schemas to allow streaming from. - -**Default config** - -.. code-block:: ini - -%(config)s -""" % {'config': formatting.indent(default_config)} +from mopidy.utils import config class Extension(ext.Extension): @@ -57,7 +14,8 @@ class Extension(ext.Extension): version = mopidy.__version__ def get_default_config(self): - return default_config + conf_file = os.path.join(os.path.dirname(__file__), 'ext.conf') + return open(conf_file).read() def get_config_schema(self): schema = config.ExtensionConfigSchema() diff --git a/mopidy/backends/stream/ext.conf b/mopidy/backends/stream/ext.conf new file mode 100644 index 00000000..9caafac1 --- /dev/null +++ b/mopidy/backends/stream/ext.conf @@ -0,0 +1,9 @@ +[stream] +enabled = true +protocols = + http + https + mms + rtmp + rtmps + rtsp From ae7543a985dd1864948ef2b0d866b87fe9014473 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 00:17:48 +0200 Subject: [PATCH 20/45] docs: Move local to ext registry --- docs/config.rst | 2 +- docs/ext/local.rst | 49 +++++++++++++++++++++++++++ docs/index.rst | 9 +++-- docs/modules/backends/local.rst | 8 ----- mopidy/backends/local/__init__.py | 56 +++---------------------------- mopidy/backends/local/ext.conf | 5 +++ 6 files changed, 64 insertions(+), 65 deletions(-) create mode 100644 docs/ext/local.rst delete mode 100644 docs/modules/backends/local.rst create mode 100644 mopidy/backends/local/ext.conf diff --git a/docs/config.rst b/docs/config.rst index cd75e6dc..097695d1 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -60,7 +60,7 @@ 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:`local-backend`, for a complete list. +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... diff --git a/docs/ext/local.rst b/docs/ext/local.rst new file mode 100644 index 00000000..aa18cd5c --- /dev/null +++ b/docs/ext/local.rst @@ -0,0 +1,49 @@ +.. _ext-local: + +************ +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. + + +Known issues +============ + +https://github.com/mopidy/mopidy/issues?labels=Local+backend + + +Dependencies +============ + +None. The extension just needs Mopidy. + + +Configuration values +==================== + +.. confval:: local/enabled + + If the local extension should be enabled or not. + +.. confval:: local/media_dir + + Path to directory with local media files. + +.. confval:: local/playlists_dir + + Path to playlists directory with m3u files for local media. + +.. confval:: local/tag_cache_file + + Path to tag cache for local media. + + +Default configuration +===================== + +.. literalinclude:: ../../mopidy/backends/local/ext.conf + :language: ini diff --git a/docs/index.rst b/docs/index.rst index 16518f53..bbf57fb5 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -3,11 +3,10 @@ Mopidy ****** Mopidy is a music server which can play music both from multiple sources, like -your :ref:`local hard drive `, :ref:`radio streams -`, and from :ref:`Spotify ` and SoundCloud. Searches -combines results from all music sources, and you can mix tracks from all -sources in your play queue. Your playlists from Spotify or SoundCloud are also -available for use. +your :ref:`local hard drive `, :ref:`radio streams `, +and from :ref:`Spotify ` and SoundCloud. Searches combines results +from all music sources, and you can mix tracks from all sources in your play +queue. Your playlists from Spotify or SoundCloud are also available for use. To control your Mopidy music server, you can use one of Mopidy's :ref:`web clients `, the :ref:`Ubuntu Sound Menu `, any diff --git a/docs/modules/backends/local.rst b/docs/modules/backends/local.rst deleted file mode 100644 index 9ac93bc8..00000000 --- a/docs/modules/backends/local.rst +++ /dev/null @@ -1,8 +0,0 @@ -.. _local-backend: - -********************************************* -:mod:`mopidy.backends.local` -- Local backend -********************************************* - -.. automodule:: mopidy.backends.local - :synopsis: Backend for playing music files on local storage diff --git a/mopidy/backends/local/__init__.py b/mopidy/backends/local/__init__.py index 0367cf15..1a676e4a 100644 --- a/mopidy/backends/local/__init__.py +++ b/mopidy/backends/local/__init__.py @@ -1,57 +1,10 @@ from __future__ import unicode_literals +import os + import mopidy from mopidy import ext -from mopidy.utils import config, formatting - - -default_config = """ -[local] -enabled = true -media_dir = $XDG_MUSIC_DIR -playlists_dir = $XDG_DATA_DIR/mopidy/local/playlists -tag_cache_file = $XDG_DATA_DIR/mopidy/local/tag_cache -""" - -__doc__ = """A backend 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. - -**Issues** - -https://github.com/mopidy/mopidy/issues?labels=Local+backend - -**Dependencies** - -None - -**Configuration** - -.. confval:: local/enabled - - If the local extension should be enabled or not. - -.. confval:: local/media_dir - - Path to directory with local media files. - -.. confval:: local/playlists_dir - - Path to playlists directory with m3u files for local media. - -.. confval:: local/tag_cache_file - - Path to tag cache for local media. - -**Default config** - -.. code-block:: ini - -%(config)s -""" % {'config': formatting.indent(default_config)} +from mopidy.utils import config class Extension(ext.Extension): @@ -61,7 +14,8 @@ class Extension(ext.Extension): version = mopidy.__version__ def get_default_config(self): - return default_config + conf_file = os.path.join(os.path.dirname(__file__), 'ext.conf') + return open(conf_file).read() def get_config_schema(self): schema = config.ExtensionConfigSchema() diff --git a/mopidy/backends/local/ext.conf b/mopidy/backends/local/ext.conf new file mode 100644 index 00000000..54c3ab78 --- /dev/null +++ b/mopidy/backends/local/ext.conf @@ -0,0 +1,5 @@ +[local] +enabled = true +media_dir = $XDG_MUSIC_DIR +playlists_dir = $XDG_DATA_DIR/mopidy/local/playlists +tag_cache_file = $XDG_DATA_DIR/mopidy/local/tag_cache From ee021b7cf0b6fb11c7b67e6e7f62895beb466962 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 00:27:00 +0200 Subject: [PATCH 21/45] docs: Use proper headers in mixer docs --- mopidy/audio/mixers/auto.py | 8 ++++++-- mopidy/audio/mixers/fake.py | 7 +++++-- mopidy/audio/mixers/nad.py | 8 ++++++-- 3 files changed, 17 insertions(+), 6 deletions(-) diff --git a/mopidy/audio/mixers/auto.py b/mopidy/audio/mixers/auto.py index f1dde3f9..6b76e1a1 100644 --- a/mopidy/audio/mixers/auto.py +++ b/mopidy/audio/mixers/auto.py @@ -2,11 +2,15 @@ This is Mopidy's default mixer. -**Dependencies** + +Dependencies +============ None -**Configuration** + +Configuration +============= If this wasn't the default, you would set the :confval:`audio/mixer` config value to ``autoaudiomixer`` to use this mixer. diff --git a/mopidy/audio/mixers/fake.py b/mopidy/audio/mixers/fake.py index 98afca2a..589610ce 100644 --- a/mopidy/audio/mixers/fake.py +++ b/mopidy/audio/mixers/fake.py @@ -1,10 +1,13 @@ """Fake mixer for use in tests. -**Dependencies** +Dependencies +============ None -**Configuration** + +Configuration +============= Set the :confval:`audio/mixer:` config value to ``fakemixer`` to use this mixer. diff --git a/mopidy/audio/mixers/nad.py b/mopidy/audio/mixers/nad.py index 9259d291..bbbaee71 100644 --- a/mopidy/audio/mixers/nad.py +++ b/mopidy/audio/mixers/nad.py @@ -3,11 +3,15 @@ The NAD amplifier must be connected to the machine running Mopidy using a serial cable. -**Dependencies** + +Dependencies +============ .. literalinclude:: ../../../../requirements/external_mixers.txt -**Configuration** + +Configuration +============= Set the :confval:`audio/mixer` config value to ``nadmixer`` to use it. You probably also needs to add some properties to the :confval:`audio/mixer` config From 079f5847331181e8403b92f427daa3323fda959d Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 00:28:18 +0200 Subject: [PATCH 22/45] docs: Link from MPD module docs to ext docs --- docs/modules/frontends/mpd.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/modules/frontends/mpd.rst b/docs/modules/frontends/mpd.rst index f25b90f2..750d19bb 100644 --- a/docs/modules/frontends/mpd.rst +++ b/docs/modules/frontends/mpd.rst @@ -2,6 +2,8 @@ :mod:`mopidy.frontends.mpd` -- MPD server ***************************************** +For details on how to use Mopidy's MPD server, see :ref:`ext-mpd`. + .. automodule:: mopidy.frontends.mpd :synopsis: MPD server frontend From f01ac1c5501b8c44ea340fe4a308acd6ad7f184e Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 00:30:16 +0200 Subject: [PATCH 23/45] docs: Rename docs section --- docs/index.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index bbf57fb5..a50acd4e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -26,8 +26,8 @@ up to date on Mopidy developments, you can follow `@mopidy `_ on Twitter. -Introduction -============ +Usage +===== .. toctree:: :maxdepth: 3 From ad21236155ba081e01c2fcdf646be6c29154fd95 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 00:54:47 +0200 Subject: [PATCH 24/45] docs: Move usage instructions from config to ext pages --- docs/config.rst | 152 ++++++----------------------------------- docs/ext/local.rst | 41 ++++++++++- docs/ext/mpd.rst | 20 +++++- docs/ext/mpris.rst | 39 ++++++++++- docs/ext/scrobbler.rst | 9 ++- docs/ext/spotify.rst | 19 +++++- 6 files changed, 138 insertions(+), 142 deletions(-) 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. From 1550d553d37e299dae7bb64ef0b710e1f9c775f6 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 01:06:11 +0200 Subject: [PATCH 25/45] docs: Fix broken reference in MPRIS ext docs --- docs/ext/mpris.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ext/mpris.rst b/docs/ext/mpris.rst index bf8963c1..eb55ef54 100644 --- a/docs/ext/mpris.rst +++ b/docs/ext/mpris.rst @@ -21,8 +21,8 @@ Dependencies Ubuntu/Debian. - An ``.desktop`` file for Mopidy installed at the path set in the - :confval:`mpris/desktop_file` config value. See :ref:`install-desktop-file` - for details. + :confval:`mpris/desktop_file` config value. See usage section below for + details. Configuration values From 3de39b5a4c9d90d9ece51ce56c5647e8fd8272c5 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 01:06:21 +0200 Subject: [PATCH 26/45] docs: Document core config values --- docs/config.rst | 74 +++++++++++++++++++++++++++++++++++++++++++-- mopidy/config.py | 22 +++----------- mopidy/default.conf | 17 +++++++++++ 3 files changed, 93 insertions(+), 20 deletions(-) create mode 100644 mopidy/default.conf diff --git a/docs/config.rst b/docs/config.rst index 6f4877b2..b6cf8402 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -34,13 +34,83 @@ A complete ``~/.config/mopidy/mopidy.conf`` may look as simple as this: Core configuration values ========================= -TODO +.. confval:: audio/mixer + + Audio mixer to use. + + Expects a GStreamer mixer to use, typical values are: ``alsamixer``, + ``pulsemixer``, ``ossmixer``, and ``oss4mixer``. + + Setting this to blank turns off volume control. ``software`` can be used to + force software mixing in the application. + +.. confval:: audio/mixer_track + + Audio mixer track to use. + + Name of the mixer track to use. If this is not set we will try to find the + master output track. As an example, using ``alsamixer`` you would typically + set this to ``Master`` or ``PCM``. + +.. confval:: audio/output + + Audio output to use. + + Expects a GStreamer sink. Typical values are ``autoaudiosink``, + ``alsasink``, ``osssink``, ``oss4sink``, ``pulsesink``, and ``shout2send``, + and additional arguments specific to each sink. You can use the command + ``gst-inspect-0.10`` to see what output properties can be set on the sink. + For example: ``gst-inspect-0.10 shout2send`` + +.. confval:: logging/console_format + + The log format used for informational logging. + + See `the Python logging docs + `_ for + details on the format. + +.. confval:: logging/debug_format + + The log format used for debug logging. + + See `the Python logging docs + `_ for + details on the format. + +.. confval:: logging/debug_file + + The file to dump debug log data to when Mopidy is run with the + :option:`--save-debug-log` option. + +.. confval:: logging.levels/* + + The ``logging.levels`` config section can be used to change the log level + for specific parts of Mopidy during development or debugging. Each key in + the config section should match the name of a logger. The value is the log + level to use for that logger, one of ``debug``, ``info``, ``warning``, + ``error``, or ``critical``. + +.. confval:: proxy/hostname + + Proxy server to use for communication with the Internet. + + Currently only used by the Spotify extension. + +.. confval:: proxy/username + + Username for the proxy server, if required. + +.. confval:: proxy/password + + Password for the proxy server, if required. Default core configuration ========================== -TODO +.. literalinclude:: ../mopidy/default.conf + :language: ini Advanced configurations diff --git a/mopidy/config.py b/mopidy/config.py index 88fc3419..04c7c16e 100644 --- a/mopidy/config.py +++ b/mopidy/config.py @@ -1,27 +1,13 @@ from __future__ import unicode_literals +import os + from mopidy.utils import config -default_config = """ -[logging] -console_format = %(levelname)-8s %(message)s -debug_format = %(levelname)-8s %(asctime)s [%(process)d:%(threadName)s] %(name)s\n %(message)s -debug_file = mopidy.log +default_config_file = os.path.join(os.path.dirname(__file__), 'default.conf') +default_config = open(default_config_file).read() -[logging.levels] -pykka = info - -[audio] -mixer = autoaudiomixer -mixer_track = -output = autoaudiosink - -[proxy] -hostname = -username = -password = -""" config_schemas = {} # TODO: use ordered dict? config_schemas['logging'] = config.ConfigSchema() diff --git a/mopidy/default.conf b/mopidy/default.conf new file mode 100644 index 00000000..1d7d7338 --- /dev/null +++ b/mopidy/default.conf @@ -0,0 +1,17 @@ +[logging] +console_format = %(levelname)-8s %(message)s +debug_format = %(levelname)-8s %(asctime)s [%(process)d:%(threadName)s] %(name)s\n %(message)s +debug_file = mopidy.log + +[logging.levels] +pykka = info + +[audio] +mixer = autoaudiomixer +mixer_track = +output = autoaudiosink + +[proxy] +hostname = +username = +password = From 3280f0413220d8ea1ab26eb51a8e25ffc57ec437 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 01:23:05 +0200 Subject: [PATCH 27/45] docs: Update config system introduction --- docs/config.rst | 43 +++++++++++++++++++++++++------------------ docs/ext/index.rst | 2 ++ docs/index.rst | 2 +- 3 files changed, 28 insertions(+), 19 deletions(-) diff --git a/docs/config.rst b/docs/config.rst index b6cf8402..ad1d8ba7 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -2,24 +2,9 @@ Configuration ************* -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. - -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 configuration file yourself, or run the ``mopidy`` -command, and it will create an empty settings file for you. - -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/mopidy.conf`` may look as simple as this: +Mopidy has a lot of config values you can tweak, but you only need to change a +few to get up and running. A complete ``~/.config/mopidy/mopidy.conf`` may be +as simple as this: .. code-block:: ini @@ -30,6 +15,28 @@ A complete ``~/.config/mopidy/mopidy.conf`` may look as simple as this: username = alice password = mysecret +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 +configuration file yourself, or run the ``mopidy`` command, and it will create +an empty settings file for you and print what config values must be set +to successfully start Mopidy. + +When you have created the configuration file, open it in a text editor, and add +the config values you want to change. If you want to keep the default for a +config value, you **should not** add it to ``~/.config/mopidy/mopidy.conf``. + +To see what's the effective configuration for your Mopidy installation, you can +run ``mopidy --show-config``. It will print your full effective config with +passwords masked out so that you safely can share the output with others for +debugging. + +You can find a description of all config values belonging to Mopidy's core +below, together with their default values. In addition, all :ref:`extensions +` got additional config values. The extension's config values and config +defaults are documented on the :ref:`extension pages `. + Core configuration values ========================= diff --git a/docs/ext/index.rst b/docs/ext/index.rst index bfa3237f..b11821d4 100644 --- a/docs/ext/index.rst +++ b/docs/ext/index.rst @@ -1,3 +1,5 @@ +.. _ext: + ********** Extensions ********** diff --git a/docs/index.rst b/docs/index.rst index a50acd4e..47778bc8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -35,8 +35,8 @@ Usage installation/index installation/raspberrypi config - running ext/index + running clients/index troubleshooting From bfceb45609a5bc7ba5f86eab767b0a22f86433a3 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 01:31:52 +0200 Subject: [PATCH 28/45] docs: Remove default config from audio class --- mopidy/audio/actor.py | 9 --------- 1 file changed, 9 deletions(-) diff --git a/mopidy/audio/actor.py b/mopidy/audio/actor.py index 5d92f3c4..af0a0c68 100644 --- a/mopidy/audio/actor.py +++ b/mopidy/audio/actor.py @@ -26,15 +26,6 @@ MB = 1 << 20 class Audio(pykka.ThreadingActor): """ Audio output through `GStreamer `_. - - **Default config:** - - .. code-block:: ini - - [audio] - mixer = autoaudiomixer - mixer_track = - output = autoaudiosink """ #: The GStreamer state mapped to :class:`mopidy.audio.PlaybackState` From 0c090499c58f1525712cf2d3f0de61a42395e657 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 01:34:21 +0200 Subject: [PATCH 29/45] docs: Document 'config' arg to frontend actors --- docs/api/frontends.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/api/frontends.rst b/docs/api/frontends.rst index 58436c03..6da5d337 100644 --- a/docs/api/frontends.rst +++ b/docs/api/frontends.rst @@ -13,9 +13,12 @@ The following requirements applies to any frontend implementation: `_ actor, called the "main actor" from here on. -- The main actor MUST accept a constructor argument ``core``, which will be an - :class:`ActorProxy ` for the core actor. This object - gives access to the full :ref:`core-api`. +- The main actor MUST accept two constructor arguments: + + - ``config``, which is a dict structure with the entire Mopidy configuration. + + - ``core``, which will be an :class:`ActorProxy ` for + the core actor. This object gives access to the full :ref:`core-api`. - It MAY use additional actors to implement whatever it does, and using actors in frontend implementations is encouraged. From 2281b6256656cb07ab872f1e265bcdc8078ca26e Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 01:36:28 +0200 Subject: [PATCH 30/45] docs: Show additional ToC level for API and modules --- docs/index.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/index.rst b/docs/index.rst index 47778bc8..ff63bece 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,6 +61,14 @@ Development contributing development extensiondev + + +Reference +========= + +.. toctree:: + :maxdepth: 2 + api/index modules/index From 11d01124c8fd92cfe089a045cb3b445be1644a96 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 01:37:11 +0200 Subject: [PATCH 31/45] docs: Update troubleshooting todo --- docs/troubleshooting.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index d29a5d2f..9bfc3400 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -8,6 +8,7 @@ TODO: - --show-config - --list-deps +- SIGUSR1 for thread traceback logging - Issue tracker - Reporting bugs - Mailing list From 29ac5f0cc75ee34ca075a81ef6c0da25e5582ed2 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 11:30:36 +0200 Subject: [PATCH 32/45] js: Update link to HTTP API docs --- js/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/js/README.md b/js/README.md index 9601b64a..27803f25 100644 --- a/js/README.md +++ b/js/README.md @@ -41,8 +41,8 @@ After npm completes, you can import Mopidy.js using ``require()``: Using the library ----------------- -See Mopidy's [HTTP frontend -documentation](http://docs.mopidy.com/en/latest/modules/frontends/http/). +See Mopidy's [HTTP API +documentation](http://docs.mopidy.com/en/latest/api/http/). Building from source From 7b9095adba96201752b0149b50e58eef0482069c Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 21:24:31 +0200 Subject: [PATCH 33/45] docs: More structure to the ext page --- docs/ext/index.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/ext/index.rst b/docs/ext/index.rst index b11821d4..af51e9bb 100644 --- a/docs/ext/index.rst +++ b/docs/ext/index.rst @@ -13,11 +13,11 @@ extensions `. Bundled with Mopidy =================== -These extensions are created and maintained by Mopidy's core developers. They -are installed together with Mopidy and are enabled by default. +These extensions are maintained by Mopidy's core developers. They are installed +together with Mopidy and are enabled by default. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :glob: ** @@ -26,11 +26,19 @@ are installed together with Mopidy and are enabled by default. External extensions =================== -These extensions are created and maintained by other developers. +These extensions are maintained outside Mopidy's core, often by other +developers. Mopidy-SoundCloud ----------------- -To play music from `SoundCloud `_ check out -`Mopidy-SoundCloud `_. +Provides a backend for playing music from the `SoundCloud +`_ service. + +Author: + Janez Troha +PyPI: + `Mopidy-SoundCloud `_ +GitHub: + `dz0ny/mopidy-soundcloud `_ From 69c2a2d32c798758d28e34885920319853111028 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 21:35:33 +0200 Subject: [PATCH 34/45] docs: Reorder default config and confval descriptions --- docs/config.rst | 14 +++++++------- docs/ext/http.rst | 18 +++++++++--------- docs/ext/local.rst | 14 +++++++------- docs/ext/mpd.rst | 14 +++++++------- docs/ext/mpris.rst | 14 +++++++------- docs/ext/scrobbler.rst | 14 +++++++------- docs/ext/spotify.rst | 14 +++++++------- docs/ext/stream.rst | 14 +++++++------- 8 files changed, 58 insertions(+), 58 deletions(-) diff --git a/docs/config.rst b/docs/config.rst index ad1d8ba7..07ebffc2 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -38,6 +38,13 @@ below, together with their default values. In addition, all :ref:`extensions defaults are documented on the :ref:`extension pages `. +Default core configuration +========================== + +.. literalinclude:: ../mopidy/default.conf + :language: ini + + Core configuration values ========================= @@ -113,13 +120,6 @@ Core configuration values Password for the proxy server, if required. -Default core configuration -========================== - -.. literalinclude:: ../mopidy/default.conf - :language: ini - - Advanced configurations ======================= diff --git a/docs/ext/http.rst b/docs/ext/http.rst index 5c7ba79b..0ca1046c 100644 --- a/docs/ext/http.rst +++ b/docs/ext/http.rst @@ -21,6 +21,13 @@ Dependencies .. literalinclude:: ../../requirements/http.txt +Default configuration +===================== + +.. literalinclude:: ../../mopidy/frontends/http/ext.conf + :language: ini + + Configuration values ==================== @@ -53,14 +60,7 @@ Configuration values "/mopidy" will continue to work as usual even if you change this setting. -Default configuration -===================== - -.. literalinclude:: ../../mopidy/frontends/http/ext.conf - :language: ini - - -Setup +Usage ===== The extension is enabled by default if all dependencies are available. @@ -81,7 +81,7 @@ When it is enabled it starts a web server at the port specified by the 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 diff --git a/docs/ext/local.rst b/docs/ext/local.rst index a446ffc7..fc89e69a 100644 --- a/docs/ext/local.rst +++ b/docs/ext/local.rst @@ -21,6 +21,13 @@ Dependencies None. The extension just needs Mopidy. +Default configuration +===================== + +.. literalinclude:: ../../mopidy/backends/local/ext.conf + :language: ini + + Configuration values ==================== @@ -41,13 +48,6 @@ Configuration values Path to tag cache for local media. -Default configuration -===================== - -.. literalinclude:: ../../mopidy/backends/local/ext.conf - :language: ini - - Usage ===== diff --git a/docs/ext/mpd.rst b/docs/ext/mpd.rst index 0d669d79..b4d0e1c8 100644 --- a/docs/ext/mpd.rst +++ b/docs/ext/mpd.rst @@ -53,6 +53,13 @@ Dependencies None. The extension just needs Mopidy. +Default configuration +===================== + +.. literalinclude:: ../../mopidy/frontends/mpd/ext.conf + :language: ini + + Configuration values ==================== @@ -92,13 +99,6 @@ Configuration values closed by the server. -Default configuration -===================== - -.. literalinclude:: ../../mopidy/frontends/mpd/ext.conf - :language: ini - - Usage ===== diff --git a/docs/ext/mpris.rst b/docs/ext/mpris.rst index eb55ef54..125f8fec 100644 --- a/docs/ext/mpris.rst +++ b/docs/ext/mpris.rst @@ -25,6 +25,13 @@ Dependencies details. +Default configuration +===================== + +.. literalinclude:: ../../mopidy/frontends/mpris/ext.conf + :language: ini + + Configuration values ==================== @@ -37,13 +44,6 @@ Configuration values Location of the Mopidy ``.desktop`` file. -Default configuration -===================== - -.. literalinclude:: ../../mopidy/frontends/mpris/ext.conf - :language: ini - - Usage ===== diff --git a/docs/ext/scrobbler.rst b/docs/ext/scrobbler.rst index af9f9e5b..a0496b37 100644 --- a/docs/ext/scrobbler.rst +++ b/docs/ext/scrobbler.rst @@ -16,6 +16,13 @@ Dependencies .. literalinclude:: ../../requirements/scrobbler.txt +Default configuration +===================== + +.. literalinclude:: ../../mopidy/frontends/scrobbler/ext.conf + :language: ini + + Configuration values ==================== @@ -32,13 +39,6 @@ Configuration values Your Last.fm password. -Default configuration -===================== - -.. literalinclude:: ../../mopidy/frontends/scrobbler/ext.conf - :language: ini - - Usage ===== diff --git a/docs/ext/spotify.rst b/docs/ext/spotify.rst index 63ccefec..4bb5b7a3 100644 --- a/docs/ext/spotify.rst +++ b/docs/ext/spotify.rst @@ -31,6 +31,13 @@ Dependencies .. literalinclude:: ../../requirements/spotify.txt +Default configuration +===================== + +.. literalinclude:: ../../mopidy/backends/spotify/ext.conf + :language: ini + + Configuration values ==================== @@ -59,13 +66,6 @@ Configuration values Path to the Spotify data cache. Cannot be shared with other Spotify apps. -Default configuration -===================== - -.. literalinclude:: ../../mopidy/backends/spotify/ext.conf - :language: ini - - Usage ===== diff --git a/docs/ext/stream.rst b/docs/ext/stream.rst index 3d7ea7d3..5669640c 100644 --- a/docs/ext/stream.rst +++ b/docs/ext/stream.rst @@ -23,6 +23,13 @@ Dependencies None. The extension just needs Mopidy. +Default configuration +===================== + +.. literalinclude:: ../../mopidy/backends/stream/ext.conf + :language: ini + + Configuration values ==================== @@ -33,10 +40,3 @@ Configuration values .. confval:: stream/protocols Whitelist of URI schemas to allow streaming from. - - -Default configuration -===================== - -.. literalinclude:: ../../mopidy/backends/stream/ext.conf - :language: ini From 7387acd017dd85e9ef776902a94473633704a7c4 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 21:44:14 +0200 Subject: [PATCH 35/45] docs: A note about stream backend usage --- docs/ext/stream.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/ext/stream.rst b/docs/ext/stream.rst index 5669640c..bb30e924 100644 --- a/docs/ext/stream.rst +++ b/docs/ext/stream.rst @@ -40,3 +40,17 @@ Configuration values .. confval:: stream/protocols Whitelist of URI schemas to allow streaming from. + + +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. From b300924e2bbbe7ec8921ba4fccf08e0787fba273 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 21:46:09 +0200 Subject: [PATCH 36/45] docs: Link from HTTP ext to HTTP clients page --- docs/ext/http.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/ext/http.rst b/docs/ext/http.rst index 0ca1046c..65bddb73 100644 --- a/docs/ext/http.rst +++ b/docs/ext/http.rst @@ -99,3 +99,5 @@ 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`. From 2730dccecd44f4c4933a82333112bf0ed23c72cc Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Fri, 12 Apr 2013 23:47:58 +0200 Subject: [PATCH 37/45] docs: Add troubleshooting tips --- docs/troubleshooting.rst | 59 ++++++++++++++++++++++++++++++++++------ 1 file changed, 51 insertions(+), 8 deletions(-) diff --git a/docs/troubleshooting.rst b/docs/troubleshooting.rst index 9bfc3400..4a634a99 100644 --- a/docs/troubleshooting.rst +++ b/docs/troubleshooting.rst @@ -4,12 +4,55 @@ Troubleshooting *************** -TODO: +If you run into problems with Mopidy, we usually hang around at ``#mopidy`` at +`irc.freenode.net `_ and also have a `mailing list at +Google Groups `_. +If you stumble into a bug or got a feature request, please create an issue in +the `issue tracker `_. -- --show-config -- --list-deps -- SIGUSR1 for thread traceback logging -- Issue tracker -- Reporting bugs -- Mailing list -- IRC channel +When you're debugging yourself or asking for help, there are some tools built +into Mopidy that you should know about. + + +Effective configuration +======================= + +The command :option:`mopidy --show-config` will print your full effective +configuration the way Mopidy sees it after all defaults and all config files +have been merged into a single config document. Any secret values like +passwords are masked out, so the output of the command should be safe to share +with others for debugging. + + +Installed dependencies +====================== + +The command :option:`mopidy --list-deps` will list the paths to and versions of +any dependency Mopidy or the extensions might need to work. This is very useful +data for checking that you're using the right versions, and that you're using +the right installation if you have multiple installations of a dependency on +your system. + + +Debug logging +============= + +If you run :option:`mopidy -v`, Mopidy will output debug log to stdout. If you +run :option:`mopidy --save-debug-log`, it will save the debug log to the file +``mopidy.log`` in the directory you ran the command from. + +If you want to turn on more or less logging for some component, see the +docs for the :confval:`logging.levels/*` config section. + + +Debugging deadlocks +=================== + +If Mopidy hangs without and obvious explanation, you can send the ``SIGUSR1`` +signal to the Mopidy process. If Mopidy's main thread is still responsive, it +will log a traceback for each running thread, showing what the threads are +currently doing. This is a very useful tool for understanding exactly how the +system is deadlocking. If you have the ``pkill`` command installed, you can use +this by simply running:: + + pkill -SIGUSR1 mopidy From 6076a0f117bad2132627bc240e331a5b041ce9e6 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 00:28:45 +0200 Subject: [PATCH 38/45] Fix flake8 warnings --- mopidy/scanner.py | 4 ++-- mopidy/utils/config.py | 9 +++++---- mopidy/utils/log.py | 2 +- tests/exceptions_test.py | 3 ++- tests/utils/config_test.py | 3 ++- 5 files changed, 12 insertions(+), 9 deletions(-) diff --git a/mopidy/scanner.py b/mopidy/scanner.py index 0c78839b..d28d328a 100644 --- a/mopidy/scanner.py +++ b/mopidy/scanner.py @@ -154,8 +154,8 @@ class Scanner(object): self.fakesink.connect('handoff', self.process_handoff) self.uribin = gst.element_factory_make('uridecodebin') - self.uribin.set_property('caps', - gst.Caps(b'audio/x-raw-int; audio/x-raw-float')) + self.uribin.set_property( + 'caps', gst.Caps(b'audio/x-raw-int; audio/x-raw-float')) self.uribin.connect('pad-added', self.process_new_pad) self.pipe = gst.element_factory_make('pipeline') diff --git a/mopidy/utils/config.py b/mopidy/utils/config.py index 09278535..21846fbb 100644 --- a/mopidy/utils/config.py +++ b/mopidy/utils/config.py @@ -253,7 +253,8 @@ class ExpandedPath(bytes): class Path(ConfigValue): - """File system path that will be expanded with mopidy.utils.path.expand_path + """File system path that will be expanded with + mopidy.utils.path.expand_path Supports: optional, choices and secret. """ @@ -275,9 +276,9 @@ class ConfigSchema(object): """Logical group of config values that correspond to a config section. Schemas are set up by assigning config keys with config values to - instances. Once setup :meth:`convert` can be called with a list of - ``(key, value)`` tuples to process. For convienience we also support - :meth:`format` method that can used for printing out the converted values. + instances. Once setup :meth:`convert` can be called with a list of ``(key, + value)`` tuples to process. For convienience we also support :meth:`format` + method that can used for printing out the converted values. """ # TODO: Use collections.OrderedDict once 2.6 support is gone (#344) def __init__(self): diff --git a/mopidy/utils/log.py b/mopidy/utils/log.py index db9a0c7c..ff593e09 100644 --- a/mopidy/utils/log.py +++ b/mopidy/utils/log.py @@ -3,7 +3,7 @@ from __future__ import unicode_literals import logging import logging.handlers -from . import deps, versioning +from . import versioning def setup_logging(config, verbosity_level, save_debug_log): diff --git a/tests/exceptions_test.py b/tests/exceptions_test.py index 12a18338..c1dd7634 100644 --- a/tests/exceptions_test.py +++ b/tests/exceptions_test.py @@ -29,7 +29,8 @@ class ExceptionsTest(unittest.TestCase): exceptions.ConfigError, exceptions.MopidyException)) def test_config_error_provides_getitem(self): - exception = exceptions.ConfigError({'field1': 'msg1', 'field2': 'msg2'}) + exception = exceptions.ConfigError( + {'field1': 'msg1', 'field2': 'msg2'}) self.assertEqual('msg1', exception['field1']) self.assertEqual('msg2', exception['field2']) self.assertItemsEqual(['field1', 'field2'], exception) diff --git a/tests/utils/config_test.py b/tests/utils/config_test.py index bf26b2e7..c823427b 100644 --- a/tests/utils/config_test.py +++ b/tests/utils/config_test.py @@ -441,7 +441,8 @@ class LogLevelConfigSchemaTest(unittest.TestCase): def test_format(self): schema = config.LogLevelConfigSchema() expected = ['[levels]', 'baz = info', 'foo.bar = debug'] - result = schema.format('levels', {'foo.bar': logging.DEBUG, 'baz': logging.INFO}) + result = schema.format( + 'levels', {'foo.bar': logging.DEBUG, 'baz': logging.INFO}) self.assertEqual('\n'.join(expected), result) From fb6a91f23eac41cf2091e50a4000c238b0d4ea39 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 00:32:31 +0200 Subject: [PATCH 39/45] docs: Remove duplicate description of pkill -SIGUSR1 --- docs/development.rst | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/docs/development.rst b/docs/development.rst index 776b004d..283600b4 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -294,23 +294,6 @@ Using this setup you can now run Mopidy with ``PROFILE=silent mopidy`` if you for instance want to test Spotify without any actual audio output. -Debugging deadlocks -=================== - -Between the numerous Pykka threads and GStreamer interactions there can -sometimes be a potential for deadlocks. In an effort to make these slightly -simpler to debug Mopidy registers a ``SIGUSR1`` signal handler which logs the -traceback of all alive threads. - -To trigger the signal handler, you can use the ``pkill`` command to -send the ``SIGUSR1`` signal to any Mopidy processes:: - - pkill -SIGUSR1 mopidy - -If you check the log, you should now find one log record with a full traceback -for each of the currently alive threads in Mopidy. - - Writing documentation ===================== From e737edf5ec90f1739c53c0b584fd10357dade8b7 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 00:32:54 +0200 Subject: [PATCH 40/45] docs: Started on new contribution docs --- docs/contributing.rst | 88 ++++++++++++++++++++++++++++++++++++++++--- docs/development.rst | 44 ---------------------- 2 files changed, 82 insertions(+), 50 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index ca013e2f..7d768a4d 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -4,10 +4,86 @@ Contributing ************ -TODO: +If you are thinking about making Mopidy better, or you just want to hack on it, +that’s great. Here are some tips to get you started. -- Getting started -- Making changes -- Testing -- Submitting changes -- Additional resources + +Getting started +=============== + +1. Make sure you have a `GitHub account `_. + +2. `Submit `_ a ticket for your + issue, assuming one does not already exist. Clearly describe the issue + including steps to reproduce when it is a bug. + +3. Fork the repository on GitHub. + + +Making changes +============== + +1. Clone your fork on GitHub to your computer. + +2. Install dependencies as described in the :ref:`installation` section. + +3. Checkout a new branch (usually based on develop) and name it accordingly to + what you intend to do. + + - Features get the prefix ``feature/`` + + - Bug fixes get the prefix ``fix/`` + + - Improvements to the documentation get the prefix ``docs/`` + + +Testing +======= + +Mopidy got quite good test coverage, and we would like all new code going into +Mopidy to come with tests. + +1. To run tests, you need a couple of dependencies. They can be installed using + ``pip``:: + + pip install -r requirements/tests.txt + +2. Then, to run all tests, go to the project directory and run:: + + nosetests + + To run tests with test coverage statistics, remember to specify the tests + dir:: + + nosetests --with-coverage tests/ + +3. Check the code for errors and style issues using flake8:: + + flake8 . + +For more documentation on testing, check out the `nose documentation +`_. + + +Submitting changes +================== + +- One branch per feature or fix. + +- Follow the style guide, especially make sure ``flake8`` does not complain + about anything. + +- Send a pull request to the ``develop`` branch. + + +Additional resources +==================== + +- `Issue tracker `_ + +- `Mailing List `_ + +- `General GitHub documentation `_ + +- `GitHub pull request documentation + `_ diff --git a/docs/development.rst b/docs/development.rst index 283600b4..193f6ae8 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -161,50 +161,6 @@ Commit guidelines - Merge feature branches with ``--no-ff`` to keep track of the merge. -Running tests -============= - -To run tests, you need a couple of dependencies. They can be installed through -Debian/Ubuntu package management:: - - sudo apt-get install python-coverage python-mock python-nose - -Or, they can be installed using ``pip``:: - - sudo pip install -r requirements/tests.txt - -Then, to run all tests, go to the project directory and run:: - - nosetests - -For example:: - - $ nosetests - ............................................................................. - ............................................................................. - ............................................................................. - ............................................................................. - ............................................................................. - ............................................................................. - ............................................................................. - ............................................................................. - ............................................................................. - ............................................................................. - ............................................................................. - ............................................................................. - ............................................................................. - ............................................................. - ----------------------------------------------------------------------------- - 1062 tests run in 7.4 seconds (1062 tests passed) - -To run tests with test coverage statistics, remember to specify the tests dir:: - - nosetests --with-coverage tests/ - -For more documentation on testing, check out the `nose documentation -`_. - - Continuous integration ====================== From 8362fbcdc53413067d8feb56040bf38e729e73cf Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 00:38:58 +0200 Subject: [PATCH 41/45] docs: Add page on versioning --- docs/development.rst | 17 ----------------- docs/index.rst | 1 + docs/versioning.rst | 23 +++++++++++++++++++++++ 3 files changed, 24 insertions(+), 17 deletions(-) create mode 100644 docs/versioning.rst diff --git a/docs/development.rst b/docs/development.rst index 193f6ae8..c53fbd2a 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -6,23 +6,6 @@ Development of Mopidy is coordinated through the IRC channel ``#mopidy`` at ``irc.freenode.net`` and through `GitHub `_. -Release schedule -================ - -We intend to have about one timeboxed feature release every month -in periods of active development. The feature releases are numbered 0.x.0. The -features added is a mix of what we feel is most important/requested of the -missing features, and features we develop just because we find them fun to -make, even though they may be useful for very few users or for a limited use -case. - -Bugfix releases, numbered 0.x.y, will be released whenever we discover bugs -that are too serious to wait for the next feature release. We will only release -bugfix releases for the last feature release. E.g. when 0.3.0 is released, we -will no longer provide bugfix releases for the 0.2 series. In other words, -there will be just a single supported release at any point in time. - - Feature wishlist ================ diff --git a/docs/index.rst b/docs/index.rst index ff63bece..439850a4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -50,6 +50,7 @@ About authors licenses changelog + versioning Development diff --git a/docs/versioning.rst b/docs/versioning.rst new file mode 100644 index 00000000..cc7f58bc --- /dev/null +++ b/docs/versioning.rst @@ -0,0 +1,23 @@ +********** +Versioning +********** + +Mopidy uses `Semantic Versioning `_, but since we're still +pre-1.0 that doesn't mean much yet. + + +Release schedule +================ + +We intend to have about one feature release every month in periods of active +development. The feature releases are numbered 0.x.0. The features added is a +mix of what we feel is most important/requested of the missing features, and +features we develop just because we find them fun to make, even though they may +be useful for very few users or for a limited use case. + +Bugfix releases, numbered 0.x.y, will be released whenever we discover bugs +that are too serious to wait for the next feature release. We will only release +bugfix releases for the last feature release. E.g. when 0.14.0 is released, we +will no longer provide bugfix releases for the 0.13 series. In other words, +there will be just a single supported release at any point in time. This is to +not spread our limited resources too thin. From cf42161e1e2a2f7d41f5a910f56bfe48268ff215 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 00:53:32 +0200 Subject: [PATCH 42/45] docs: Move how to run from Git instructions --- docs/contributing.rst | 29 +++++++++++++++++++- docs/development.rst | 62 ------------------------------------------- 2 files changed, 28 insertions(+), 63 deletions(-) diff --git a/docs/contributing.rst b/docs/contributing.rst index 7d768a4d..52194702 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -37,10 +37,35 @@ Making changes - Improvements to the documentation get the prefix ``docs/`` +.. _run-from-git: + +Running Mopidy from Git +======================= + +If you want to hack on Mopidy, you should run Mopidy directly from the Git +repo. + +1. Go to the Git repo root:: + + cd mopidy/ + +2. To get a ``mopidy`` executable, run:: + + python setup.py develop + +3. Now you can run the Mopidy command, and it will run using the code + in the Git repo:: + + mopidy + + If you do any changes to the code, you'll just need to restart ``mopidy`` + to see the changes take effect. + + Testing ======= -Mopidy got quite good test coverage, and we would like all new code going into +Mopidy has quite good test coverage, and we would like all new code going into Mopidy to come with tests. 1. To run tests, you need a couple of dependencies. They can be installed using @@ -79,6 +104,8 @@ Submitting changes Additional resources ==================== +- IRC channel: ``#mopidy`` at `irc.freenode.net `_ + - `Issue tracker `_ - `Mailing List `_ diff --git a/docs/development.rst b/docs/development.rst index c53fbd2a..af451ef7 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -2,68 +2,6 @@ Development *********** -Development of Mopidy is coordinated through the IRC channel ``#mopidy`` at -``irc.freenode.net`` and through `GitHub `_. - - -Feature wishlist -================ - -We maintain our collection of sane or less sane ideas for future Mopidy -features as `issues `_ at GitHub -labeled with `the "wishlist" label -`_. Feel free to vote -up any feature you would love to see in Mopidy, but please refrain from adding -a comment just to say "I want this too!". You are of course free to add -comments if you have suggestions for how the feature should work or be -implemented, and you may add new wishlist issues if your ideas are not already -represented. - - -.. _run-from-git: - -Run Mopidy from Git repo -======================== - -If you want to contribute to the development of Mopidy, you should run Mopidy -directly from the Git repo. - -#. First of all, install Mopidy in the recommended way for your OS and/or - distribution, like described at :ref:`installation`. You can have a - system-wide installation of the last Mopidy release in addition to the Git - repo which you run from when you code on Mopidy. - -#. Then install Git, if haven't already. For Ubuntu/Debian:: - - sudo apt-get install git-core - - On OS X using Homebrew:: - - sudo brew install git - -#. Clone the official Mopidy repository:: - - git clone git://github.com/mopidy/mopidy.git - - or your own fork of it:: - - git clone git@github.com:mygithubuser/mopidy.git - -#. You can then run Mopidy directly from the Git repository:: - - cd mopidy/ # Move into the Git repo dir - python mopidy # Run python on the mopidy source code dir - -How you update your clone depends on whether you cloned the official Mopidy -repository or your own fork, whether you have made any changes to the clone -or not, and whether you are currently working on a feature branch or not. In -other words, you'll need to learn Git. - -For an introduction to Git, please visit `git-scm.com `_. -Also, please read the rest of our developer documentation before you start -contributing. - - Code style ========== From b0e281b90a48713aed138f867e35a60e2ccf8eba Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 00:53:49 +0200 Subject: [PATCH 43/45] docs: Extract codestyle to own page --- docs/codestyle.rst | 63 ++++++++++++++++++++++++++++++++++++++++++ docs/development.rst | 66 -------------------------------------------- docs/index.rst | 1 + 3 files changed, 64 insertions(+), 66 deletions(-) create mode 100644 docs/codestyle.rst diff --git a/docs/codestyle.rst b/docs/codestyle.rst new file mode 100644 index 00000000..ae58d2d8 --- /dev/null +++ b/docs/codestyle.rst @@ -0,0 +1,63 @@ +********** +Code style +********** + +- Always import ``unicode_literals`` and use unicode literals for everything + except where you're explicitly working with bytes, which are marked with the + ``b`` prefix. + + Do this:: + + from __future__ import unicode_literals + + foo = 'I am a unicode string, which is a sane default' + bar = b'I am a bytestring' + + Not this:: + + foo = u'I am a unicode string' + bar = 'I am a bytestring, but was it intentional?' + +- Follow :pep:`8` unless otherwise noted. `flake8 + `_ should be used to check your code + against the guidelines. + +- Use four spaces for indentation, *never* tabs. + +- Use CamelCase with initial caps for class names:: + + ClassNameWithCamelCase + +- Use underscore to split variable, function and method names for + readability. Don't use CamelCase. + + :: + + lower_case_with_underscores + +- Use the fact that empty strings, lists and tuples are :class:`False` and + don't compare boolean values using ``==`` and ``!=``. + +- Follow whitespace rules as described in :pep:`8`. Good examples:: + + spam(ham[1], {eggs: 2}) + spam(1) + dict['key'] = list[index] + +- Limit lines to 80 characters and avoid trailing whitespace. However note that + wrapped lines should be *one* indentation level in from level above, except + for ``if``, ``for``, ``with``, and ``while`` lines which should have two + levels of indentation:: + + if (foo and bar ... + baz and foobar): + a = 1 + + from foobar import (foo, bar, ... + baz) + +- For consistency, prefer ``'`` over ``"`` for strings, unless the string + contains ``'``. + +- Take a look at :pep:`20` for a nice peek into a general mindset useful for + Python coding. diff --git a/docs/development.rst b/docs/development.rst index af451ef7..580178f1 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -2,72 +2,6 @@ Development *********** -Code style -========== - -- Always import ``unicode_literals`` and use unicode literals for everything - except where you're explicitly working with bytes, which are marked with the - ``b`` prefix. - - Do this:: - - from __future__ import unicode_literals - - foo = 'I am a unicode string, which is a sane default' - bar = b'I am a bytestring' - - Not this:: - - foo = u'I am a unicode string' - bar = 'I am a bytestring, but was it intentional?' - -- Follow :pep:`8` unless otherwise noted. `pep8.py - `_ or `flake8 - `_ can be used to check your code - against the guidelines, however remember that matching the style of the - surrounding code is also important. - -- Use four spaces for indentation, *never* tabs. - -- Use CamelCase with initial caps for class names:: - - ClassNameWithCamelCase - -- Use underscore to split variable, function and method names for - readability. Don't use CamelCase. - - :: - - lower_case_with_underscores - -- Use the fact that empty strings, lists and tuples are :class:`False` and - don't compare boolean values using ``==`` and ``!=``. - -- Follow whitespace rules as described in :pep:`8`. Good examples:: - - spam(ham[1], {eggs: 2}) - spam(1) - dict['key'] = list[index] - -- Limit lines to 80 characters and avoid trailing whitespace. However note that - wrapped lines should be *one* indentation level in from level above, except - for ``if``, ``for``, ``with``, and ``while`` lines which should have two - levels of indentation:: - - if (foo and bar ... - baz and foobar): - a = 1 - - from foobar import (foo, bar, ... - baz) - -- For consistency, prefer ``'`` over ``"`` for strings, unless the string - contains ``'``. - -- Take a look at :pep:`20` for a nice peek into a general mindset useful for - Python coding. - - Commit guidelines ================= diff --git a/docs/index.rst b/docs/index.rst index 439850a4..6f5ef95f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -61,6 +61,7 @@ Development contributing development + codestyle extensiondev From 2ac1cc45824e0b7b7271c31d8b1f595805ae4f20 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 00:56:08 +0200 Subject: [PATCH 44/45] docs: Link to code style from contributions docs --- docs/codestyle.rst | 2 ++ docs/contributing.rst | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/codestyle.rst b/docs/codestyle.rst index ae58d2d8..4b6e7448 100644 --- a/docs/codestyle.rst +++ b/docs/codestyle.rst @@ -1,3 +1,5 @@ +.. _codestyle: + ********** Code style ********** diff --git a/docs/contributing.rst b/docs/contributing.rst index 52194702..70326145 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -95,8 +95,8 @@ Submitting changes - One branch per feature or fix. -- Follow the style guide, especially make sure ``flake8`` does not complain - about anything. +- Follow the :ref:`style guide `_, especially make sure ``flake8`` + does not complain about anything. - Send a pull request to the ``develop`` branch. From ad1904023e7a876562efe283aa52d5f53705adab Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Sat, 13 Apr 2013 01:01:25 +0200 Subject: [PATCH 45/45] docs: Rename dev docs to devtools --- docs/contributing.rst | 2 +- docs/{development.rst => devtools.rst} | 52 +++++--------------------- docs/index.rst | 2 +- 3 files changed, 11 insertions(+), 45 deletions(-) rename docs/{development.rst => devtools.rst} (73%) diff --git a/docs/contributing.rst b/docs/contributing.rst index 70326145..215aea65 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -93,7 +93,7 @@ For more documentation on testing, check out the `nose documentation Submitting changes ================== -- One branch per feature or fix. +- One branch per feature or fix. Keep branches small and on topic. - Follow the :ref:`style guide `_, especially make sure ``flake8`` does not complain about anything. diff --git a/docs/development.rst b/docs/devtools.rst similarity index 73% rename from docs/development.rst rename to docs/devtools.rst index 580178f1..7b5b2f81 100644 --- a/docs/development.rst +++ b/docs/devtools.rst @@ -1,19 +1,8 @@ -*********** -Development -*********** +***************** +Development tools +***************** -Commit guidelines -================= - -- We follow the development process described at - `nvie.com `_. - -- Keep commits small and on topic. - -- If a commit looks too big you should be working in a feature branch not a - single commit. - -- Merge feature branches with ``--no-ff`` to keep track of the merge. +Here you'll find description of the development tools we use. Continuous integration @@ -38,8 +27,8 @@ code. So, if you're out of work, the code coverage and pylint data at the CI server should give you a place to start. -Protocol debugging -================== +Protocol debugger +================= Since the main interface provided to Mopidy is through the MPD protocol, it is crucial that we try and stay in sync with protocol developments. In an attempt @@ -82,35 +71,12 @@ both to use ``tests/data/advanced_tag_cache`` for their tag cache and playlists. -Setting profiles during development -=================================== - -While developing Mopidy switching settings back and forth can become an all too -frequent occurrence. As a quick hack to get around this you can structure your -settings file in the following way:: - - import os - profile = os.environ.get('PROFILE', '').split(',') - - if 'shoutcast' in profile: - OUTPUT = u'lame ! shout2send mount="/stream"' - elif 'silent' in profile: - OUTPUT = u'fakesink' - MIXER = None - - SPOTIFY_USERNAME = u'xxxxx' - SPOTIFY_PASSWORD = u'xxxxx' - -Using this setup you can now run Mopidy with ``PROFILE=silent mopidy`` -if you for instance want to test Spotify without any actual audio output. - - -Writing documentation +Documentation writing ===================== To write documentation, we use `Sphinx `_. See their -site for lots of documentation on how to use Sphinx. To generate HTML or LaTeX -from the documentation files, you need some additional dependencies. +site for lots of documentation on how to use Sphinx. To generate HTML from the +documentation files, you need some additional dependencies. You can install them through Debian/Ubuntu package management:: diff --git a/docs/index.rst b/docs/index.rst index 6f5ef95f..199ba31c 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -60,7 +60,7 @@ Development :maxdepth: 1 contributing - development + devtools codestyle extensiondev