diff --git a/docs/index.rst b/docs/index.rst index feb636d7..29b9b928 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -6,7 +6,7 @@ Contents .. toctree:: :maxdepth: 3 - installation + installation/index development api/index changes diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index 57a401e5..00000000 --- a/docs/installation.rst +++ /dev/null @@ -1,192 +0,0 @@ -************ -Installation -************ - -Mopidy itself is a breeze to install, as it just requires a standard Python -installation. The libraries we depend on to connect to the Spotify service is -far more tricky to get working for the time being. Until installation of these -libraries are either well documented by their developers, or the libraries are -packaged for various Linux distributions, we will supply our own installation -guides here. - - -Dependencies -============ - -- Python >= 2.6 -- Dependencies for at least one Mopidy mixer: - - - *Linux, AlsaMixer:* pyalsaaudio >= 0.2 (Debian/Ubuntu package: - python-alsaaudio) - - *OS X, OsaMixer:* Nothing needed. - -- Dependencies for at least one Mopidy backend: - - - :ref:`despotify` - - :ref:`libspotify` - - - - -.. _despotify: - -despotify backend ------------------ - -To use the despotify backend, you first need to install despotify and spytify. - -.. note:: - - This backend requires a Spotify premium account. - - -Installing despotify -^^^^^^^^^^^^^^^^^^^^ - -*Linux:* Install despotify's dependencies. At Debian/Ubuntu systems:: - - sudo aptitude install libssl-dev zlib1g-dev libvorbis-dev \ - libtool libncursesw5-dev libao-dev - -*OS X:* In OS X you need to have `XCode -`_ installed, and either `MacPorts -`_ or `Homebrew `_. - -*OS X, Homebrew:* Install dependencies:: - - brew install libvorbis ncursesw libao pkg-config - -*OS X, MacPorts:* Install dependencies:: - - sudo port install libvorbis libtool ncursesw libao - -*All OS:* Check out revision 503 of the despotify source code:: - - svn checkout https://despotify.svn.sourceforge.net/svnroot/despotify@503 - -*OS X, MacPorts:* Copy ``despotify/src/Makefile.local.mk.dist`` to -``despotify/src/Makefile.local.mk`` and uncomment the last two lines of the new -file so that it reads:: - - ## If you're on Mac OS X and have installed libvorbisfile - ## via 'port install ..', try uncommenting these lines - CFLAGS += -I/opt/local/include - LDFLAGS += -L/opt/local/lib - -*All OS:* Build and install despotify:: - - cd despotify/src/ - make - sudo make install - - -Installing spytify -^^^^^^^^^^^^^^^^^^ - -spytify's source comes bundled with despotify. - -Build and install spytify:: - - cd despotify/src/bindings/python/ - export PKG_CONFIG_PATH=../../lib # Needed on OS X - make - sudo make install - -To validate that everything is working, run the ``test.py`` script which is -distributed with spytify:: - - python test.py - -The test script should ask for your username and password (which must be for a -Spotify Premium account), ask for a search query, list all your playlists with -tracks, play 10s from a random song from the search result, pause for two -seconds, play for five more seconds, and quit. - - -.. _libspotify: - -libspotify backend ------------------- - -As an alternative to the despotify backend, we are working on a libspotify -backend. To use the libspotify backend you must install libspotify and -pyspotify. - -.. note:: - - This backend requires a Spotify premium account, and it requires you to get - an application key from Spotify before use. - - -Installing libspotify -^^^^^^^^^^^^^^^^^^^^^ - -As libspotify's installation script at the moment is somewhat broken (see this -`GetSatisfaction thread `_ -for details), it is easiest to use the libspotify files bundled with pyspotify. -The files bundled with pyspotify are for 64-bit, so if you run a 32-bit OS, you -must get libspotify from https://developer.spotify.com/en/libspotify/. - - -Installing pyspotify -^^^^^^^^^^^^^^^^^^^^ - -Install pyspotify's dependencies. At Debian/Ubuntu systems:: - - sudo aptitude install python-alsaaudio - -Check out the pyspotify code, and install it:: - - git clone git://github.com/winjer/pyspotify.git - cd pyspotify - export LD_LIBRARY_PATH=$PWD/lib - sudo python setup.py develop - -Apply for an application key at -https://developer.spotify.com/en/libspotify/application-key, download the -binary version, and place the file at ``pyspotify/spotify_appkey.key``. - -Test your libspotify setup:: - - examples/example1.py -u USERNAME -p PASSWORD - -.. note:: - - Until Spotify fixes their installation script, you'll have to set - ``LD_LIBRARY_PATH`` every time you are going to use libspotify (in other - words before starting Mopidy). - - -Spotify settings -================ - -Create a file named ``local.py`` in the directory ``mopidy/settings/``. Enter -your Spotify Premium account's username and password into the file, like this:: - - SPOTIFY_USERNAME = u'myusername' - SPOTIFY_PASSWORD = u'mysecret' - -Currently the despotify backend is the default. If you want to use the -libspotify backend, copy the Spotify application key to -``mopidy/spotify_appkey.key``, and add the following to -``mopidy/mopidy/settings/local.py``:: - - BACKENDS = (u'mopidy.backends.libspotify.LibspotifyBackend',) - -For a full list of available settings, see :mod:`mopidy.settings.default`. - - -Running Mopidy -============== - -To start Mopidy, go to the root of the Mopidy project, then simply run:: - - python mopidy - -When Mopidy says ``Please connect to localhost port 6600 using an MPD client.`` -it's ready to accept connections by any MPD client. You can find a list of tons -of MPD clients at http://mpd.wikia.com/wiki/Clients. We use Sonata, GMPC, -ncmpc, and ncmpcpp during development. The first two are GUI clients, while the -last two are terminal clients. - -To stop Mopidy, press ``CTRL+C``. diff --git a/docs/installation/despotify.rst b/docs/installation/despotify.rst new file mode 100644 index 00000000..e50d3cba --- /dev/null +++ b/docs/installation/despotify.rst @@ -0,0 +1,80 @@ +.. _despotify: + +********************** +despotify installation +********************** + +To use the despotify backend, you first need to install despotify and spytify. + +.. note:: + + This backend requires a Spotify premium account. + + +Installing despotify +==================== + +*Linux:* Install despotify's dependencies. At Debian/Ubuntu systems:: + + sudo aptitude install libssl-dev zlib1g-dev libvorbis-dev \ + libtool libncursesw5-dev libao-dev + +*OS X:* In OS X you need to have `XCode +`_ installed, and either `MacPorts +`_ or `Homebrew `_. + +*OS X, Homebrew:* Install dependencies:: + + brew install libvorbis ncursesw libao pkg-config + +*OS X, MacPorts:* Install dependencies:: + + sudo port install libvorbis libtool ncursesw libao + +*All OS:* Check out revision 503 of the despotify source code:: + + svn checkout https://despotify.svn.sourceforge.net/svnroot/despotify@503 + +*OS X, MacPorts:* Copy ``despotify/src/Makefile.local.mk.dist`` to +``despotify/src/Makefile.local.mk`` and uncomment the last two lines of the new +file so that it reads:: + + ## If you're on Mac OS X and have installed libvorbisfile + ## via 'port install ..', try uncommenting these lines + CFLAGS += -I/opt/local/include + LDFLAGS += -L/opt/local/lib + +*All OS:* Build and install despotify:: + + cd despotify/src/ + make + sudo make install + + +Installing spytify +================== + +spytify's source comes bundled with despotify. + +Build and install spytify:: + + cd despotify/src/bindings/python/ + export PKG_CONFIG_PATH=../../lib # Needed on OS X + make + sudo make install + + +Testing the installation +======================== + +To validate that everything is working, run the ``test.py`` script which is +distributed with spytify:: + + python test.py + +The test script should ask for your username and password (which must be for a +Spotify Premium account), ask for a search query, list all your playlists with +tracks, play 10s from a random song from the search result, pause for two +seconds, play for five more seconds, and quit. +o stop Mopidy, press ``CTRL+C``. + diff --git a/docs/installation/index.rst b/docs/installation/index.rst new file mode 100644 index 00000000..98829e02 --- /dev/null +++ b/docs/installation/index.rst @@ -0,0 +1,80 @@ +************ +Installation +************ + +Mopidy itself is a breeze to install, as it just requires a standard Python +installation. The libraries we depend on to connect to the Spotify service is +far more tricky to get working for the time being. Until installation of these +libraries are either well documented by their developers, or the libraries are +packaged for various Linux distributions, we will supply our own installation +guides here. + +.. toctree:: + :maxdepth: 1 + + despotify + libspotify + + +Dependencies +============ + +- Python >= 2.6 +- Dependencies for at least one Mopidy mixer: + + - AlsaMixer (Linux only) + + - pyalsaaudio >= 0.2 (Debian/Ubuntu package: python-alsaaudio) + + - OsaMixer (OS X only) + + - Nothing needed. + +- Dependencies for at least one Mopidy backend: + + - DespotifyBackend (Linux and OS X) + + - see :ref:`despotify` + + - LibspotifyBackend (Linux only) + + - see :ref:`libspotify` + + +Spotify settings +================ + +Create a file named ``local.py`` in the directory ``mopidy/settings/``. Enter +your Spotify Premium account's username and password into the file, like this:: + + SPOTIFY_USERNAME = u'myusername' + SPOTIFY_PASSWORD = u'mysecret' + + +Switching backend +================= + +Currently the despotify backend is the default. If you want to use the +libspotify backend instead, copy the Spotify application key to +``mopidy/spotify_appkey.key``, and add the following to +``mopidy/mopidy/settings/local.py``:: + + BACKENDS = (u'mopidy.backends.libspotify.LibspotifyBackend',) + +For a full list of available settings, see :mod:`mopidy.settings.default`. + + +Running Mopidy +============== + +To start Mopidy, go to the root of the Mopidy project, then simply run:: + + python mopidy + +When Mopidy says ``Please connect to localhost port 6600 using an MPD client.`` +it's ready to accept connections by any MPD client. You can find a list of tons +of MPD clients at http://mpd.wikia.com/wiki/Clients. We use Sonata, GMPC, +ncmpc, and ncmpcpp during development. The first two are GUI clients, while the +last two are terminal clients. + +To stop Mopidy, press ``CTRL+C``. diff --git a/docs/installation/libspotify.rst b/docs/installation/libspotify.rst new file mode 100644 index 00000000..042a7f2e --- /dev/null +++ b/docs/installation/libspotify.rst @@ -0,0 +1,58 @@ +.. _libspotify: + +*********************** +libspotify installation +*********************** + +As an alternative to the despotify backend, we are working on a libspotify +backend. To use the libspotify backend you must install libspotify and +pyspotify. + +.. note:: + + This backend requires a Spotify premium account, and it requires you to get + an application key from Spotify before use. + + +Installing libspotify +===================== + +As libspotify's installation script at the moment is somewhat broken (see this +`GetSatisfaction thread `_ +for details), it is easiest to use the libspotify files bundled with pyspotify. +The files bundled with pyspotify are for 64-bit, so if you run a 32-bit OS, you +must get libspotify from https://developer.spotify.com/en/libspotify/. + + +Installing pyspotify +==================== + +Install pyspotify's dependencies. At Debian/Ubuntu systems:: + + sudo aptitude install python-alsaaudio + +Check out the pyspotify code, and install it:: + + git clone git://github.com/winjer/pyspotify.git + cd pyspotify + export LD_LIBRARY_PATH=$PWD/lib + sudo python setup.py develop + +Apply for an application key at +https://developer.spotify.com/en/libspotify/application-key, download the +binary version, and place the file at ``pyspotify/spotify_appkey.key``. + + +Testing the installation +======================== + +Test your libspotify setup:: + + examples/example1.py -u USERNAME -p PASSWORD + +.. note:: + + Until Spotify fixes their installation script, you'll have to set + ``LD_LIBRARY_PATH`` every time you are going to use libspotify (in other + words before starting Mopidy). +