From 636dc6152d2044dd917e7699f62523fb24d8cba1 Mon Sep 17 00:00:00 2001 From: Stein Magnus Jodal Date: Tue, 6 Nov 2012 16:11:45 +0100 Subject: [PATCH] docs: Better installation docs The GStreamer and libspotify/pyspotify docs have been merged into the main installation document. Everything related to OS X have been grouped in one section. The rest have been merged into the "from source" section. --- docs/index.rst | 2 - docs/installation/gstreamer.rst | 98 ----------------------- docs/installation/index.rst | 128 +++++++++++++++++++++++++++---- docs/installation/libspotify.rst | 112 --------------------------- docs/settings.rst | 39 +++++++++- 5 files changed, 148 insertions(+), 231 deletions(-) delete mode 100644 docs/installation/gstreamer.rst delete mode 100644 docs/installation/libspotify.rst diff --git a/docs/index.rst b/docs/index.rst index 0f5ed164..bce84b5a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -39,8 +39,6 @@ User documentation :maxdepth: 3 installation/index - installation/gstreamer - installation/libspotify installation/raspberrypi settings running diff --git a/docs/installation/gstreamer.rst b/docs/installation/gstreamer.rst deleted file mode 100644 index 38dbb86c..00000000 --- a/docs/installation/gstreamer.rst +++ /dev/null @@ -1,98 +0,0 @@ -********************** -GStreamer installation -********************** - -To use Mopidy, you first need to install GStreamer and the GStreamer Python -bindings. - - -Installing GStreamer on Linux -============================= - -GStreamer is packaged for most popular Linux distributions. Search for -GStreamer in your package manager, and make sure to install the Python -bindings, and the "good" and "ugly" plugin sets. - - -Debian/Ubuntu -------------- - -If you use Debian/Ubuntu you can install GStreamer like this:: - - sudo apt-get install python-gst0.10 gstreamer0.10-plugins-good \ - gstreamer0.10-plugins-ugly - -If you install Mopidy from our APT archive, you don't need to install GStreamer -yourself. The Mopidy Debian package will handle it for you. - - -Arch Linux ----------- - -If you use Arch Linux, install the following packages from the official -repository:: - - sudo pacman -S gstreamer0.10-python gstreamer0.10-good-plugins \ - gstreamer0.10-ugly-plugins - - -Installing GStreamer on OS X -============================ - -We have been working with `Homebrew `_ for a -to make all the GStreamer packages easily installable on OS X. - -#. Install `Homebrew `_. - -#. Install the required packages:: - - brew install gst-python gst-plugins-good gst-plugins-ugly - -#. Make sure to include Homebrew's Python ``site-packages`` directory in your - ``PYTHONPATH``. If you don't include this, Mopidy will not find GStreamer - and crash. - - You can either amend your ``PYTHONPATH`` permanently, by adding the - following statement to your shell's init file, e.g. ``~/.bashrc``:: - - export PYTHONPATH=$(brew --prefix)/lib/python2.7/site-packages:$PYTHONPATH - - Or, you can prefix the Mopidy command every time you run it:: - - PYTHONPATH=$(brew --prefix)/lib/python2.7/site-packages mopidy - - Note that you need to replace ``python2.7`` with ``python2.6`` if that's - the Python version you are using. To find your Python version, run:: - - python --version - - -Testing the installation -======================== - -If you now run the ``gst-inspect-0.10`` command (the version number may vary), -you should see a long listing of installed plugins, ending in a summary line:: - - $ gst-inspect-0.10 - ... long list of installed plugins ... - Total count: 218 plugins (1 blacklist entry not shown), 1031 features - -You should be able to produce a audible tone by running:: - - gst-launch-0.10 audiotestsrc ! autoaudiosink - -If you cannot hear any sound when running this command, you won't hear any -sound from Mopidy either, as Mopidy uses GStreamer's ``autoaudiosink`` to play -audio. Thus, make this work before you continue installing Mopidy. - - -Using a custom audio sink -========================= - -If you for some reason want to use some other GStreamer audio sink than -``autoaudiosink``, you can set :attr:`mopidy.settings.OUTPUT` to a partial -GStreamer pipeline description describing the GStreamer sink you want to use. - -Example of ``settings.py`` for OSS4:: - - OUTPUT = u'oss4sink' diff --git a/docs/installation/index.rst b/docs/installation/index.rst index d134ae40..d77db58d 100644 --- a/docs/installation/index.rst +++ b/docs/installation/index.rst @@ -1,8 +1,8 @@ .. _installation: -******************* -Mopidy installation -******************* +************ +Installation +************ There are several ways to install Mopidy. What way is best depends upon your OS and/or distribution. If you want to contribute to the development of Mopidy, @@ -74,25 +74,79 @@ package found in AUR. you're ready to :doc:`run Mopidy `. +OS X: Install from Homebrew and Pip +=================================== + +If you are running OS X, you can install everything needed with Homebrew and +Pip. + +#. Install `Homebrew `_. + + If you are already using Homebrew, make sure your installation is up to + date before you continue:: + + brew update + brew upgrade + +#. Install the required packages from Homebrew:: + + brew install gst-python gst-plugins-good gst-plugins-ugly libspotify + +#. Make sure to include Homebrew's Python ``site-packages`` directory in your + ``PYTHONPATH``. If you don't include this, Mopidy will not find GStreamer + and crash. + + You can either amend your ``PYTHONPATH`` permanently, by adding the + following statement to your shell's init file, e.g. ``~/.bashrc``:: + + export PYTHONPATH=$(brew --prefix)/lib/python2.7/site-packages:$PYTHONPATH + + Or, you can prefix the Mopidy command every time you run it:: + + PYTHONPATH=$(brew --prefix)/lib/python2.7/site-packages mopidy + + Note that you need to replace ``python2.7`` with ``python2.6`` in the above + ``PYTHONPATH`` examples if you are using Python 2.6. To find your Python + version, run:: + + python --version + +#. Next up, you need to install some Python packages. To do so, we use Pip. If + you don't have the ``pip`` command, you can install it now:: + + sudo easy_install pip + +#. Then get, build, and install the latest releast of pyspotify, pylast, pykka, + and Mopidy using Pip:: + + sudo pip install -U pyspotify pylast pykka mopidy + +#. Finally, you need to set a couple of :doc:`settings `, and then + you're ready to :doc:`run Mopidy `. + + Otherwise: Install from source using Pip ======================================== -If you are on OS X or on Linux, but can't install from the APT archive or from -AUR, you can install Mopidy from PyPI using Pip. +If you are on on Linux, but can't install from the APT archive or from AUR, you +can install Mopidy from PyPI using Pip. #. First of all, you need Python >= 2.6, < 3. Check if you have Python and what version by running:: python --version -#. When you install using Pip, you need to make sure you have Pip. If you - don't, this is how you install it on Debian/Ubuntu:: +#. When you install using Pip, you need to make sure you have Pip. You'll also + need a C compiler and the Python development headers to build pyspotify + later. - sudo apt-get install python-setuptools python-pip + This is how you install it on Debian/Ubuntu:: - Or on OS X:: + sudo apt-get install build-essential python-dev python-pip - sudo easy_install pip + And on Arch Linux from the official repository:: + + sudo pacman -S base-devel python2-pip #. Then you'll need to install all of Mopidy's hard dependencies: @@ -100,12 +154,48 @@ AUR, you can install Mopidy from PyPI using Pip. sudo pip install -U pykka - - GStreamer 0.10.x, with Python bindings. See :doc:`gstreamer` for detailed - instructions. + - GStreamer 0.10.x, with Python bindings. GStreamer is packaged for most + popular Linux distributions. Search for GStreamer in your package manager, + and make sure to install the Python bindings, and the "good" and "ugly" + plugin sets. + + If you use Debian/Ubuntu you can install GStreamer like this:: + + sudo apt-get install python-gst0.10 gstreamer0.10-plugins-good \ + gstreamer0.10-plugins-ugly gstreamer0.10-tools + + If you use Arch Linux, install the following packages from the official + repository:: + + sudo pacman -S gstreamer0.10-python gstreamer0.10-good-plugins \ + gstreamer0.10-ugly-plugins #. Optional: If you want Spotify support in Mopidy, you'll need to install - libspotify and the Python bindings, pyspotify. See :doc:`libspotify` for - detailed instructions. + libspotify and the Python bindings, pyspotify. + + #. First, check `pyspotify's changelog `_ to + see what's the latest version of libspotify which it supports. The + versions of libspotify and pyspotify are tightly coupled, so you'll need + to get this right. + + #. Download and install the appropriate version of libspotify for your OS and + CPU architecture from `Spotify + `_. + + For libspotify 12.1.51 for 64-bit Linux the process is as follows:: + + wget https://developer.spotify.com/download/libspotify/libspotify-12.1.51-Linux-x86_64-release.tar.gz + tar zxfv libspotify-12.1.51-Linux-x86_64-release.tar.gz + cd libspotify-12.1.51-Linux-x86_64-release/ + sudo make install prefix=/usr/local + sudo ldconfig + + Remember to adjust the above example for the latest libspotify version + supported by pyspotify, your OS, and your CPU architecture. + + #. Then get, build, and install the latest release of pyspotify using Pip:: + + sudo pip install -U pyspotify #. Optional: If you want to scrobble your played tracks to Last.fm, you need pylast:: @@ -113,9 +203,13 @@ AUR, you can install Mopidy from PyPI using Pip. sudo pip install -U pylast #. Optional: To use MPRIS, e.g. for controlling Mopidy from the Ubuntu Sound - Menu, you need some additional requirements. On Debian/Ubuntu:: + Menu or from an UPnP client via Rygel, you need some additional + dependencies: the Python bindings for libindicate, and the Python bindings + for libdbus, the reference D-Bus library. - sudo apt-get install python-dbus python-indicate + On Debian/Ubuntu:: + + sudo apt-get install python-dbus python-indicate #. Then, to install the latest release of Mopidy:: @@ -123,7 +217,7 @@ AUR, you can install Mopidy from PyPI using Pip. To upgrade Mopidy to future releases, just rerun this command. - Alternatively, if you want to follow Mopidy development closer, you may + Alternatively, if you want to track Mopidy development closer, you may install a snapshot of Mopidy's ``develop`` Git branch using Pip:: sudo pip install mopidy==dev diff --git a/docs/installation/libspotify.rst b/docs/installation/libspotify.rst deleted file mode 100644 index 042034e7..00000000 --- a/docs/installation/libspotify.rst +++ /dev/null @@ -1,112 +0,0 @@ -*********************** -libspotify installation -*********************** - -Mopidy uses `libspotify -`_ for playing music -from the Spotify music service. To use :mod:`mopidy.backends.spotify` you must -install libspotify and `pyspotify `_. - -.. note:: - - This backend requires a paid `Spotify premium account - `_. - - -Installing libspotify -===================== - - -On Linux from APT archive -------------------------- - -If you install from APT, jump directly to :ref:`pyspotify_installation` below. - - -On Linux from source --------------------- - -First, check pyspotify's changelog to see what's the latest version of -libspotify which is supported. The versions of libspotify and pyspotify are -tightly coupled. - -Download and install the appropriate version of libspotify for your OS and CPU -architecture from https://developer.spotify.com/en/libspotify/. - -For libspotify 0.0.8 for 64-bit Linux the process is as follows:: - - wget http://developer.spotify.com/download/libspotify/libspotify-0.0.8-linux6-x86_64.tar.gz - tar zxfv libspotify-0.0.8-linux6-x86_64.tar.gz - cd libspotify-0.0.8-linux6-x86_64/ - sudo make install prefix=/usr/local - sudo ldconfig - -Remember to adjust for the latest libspotify version supported by pyspotify, -your OS and your CPU architecture. - -When libspotify has been installed, continue with -:ref:`pyspotify_installation`. - - -On OS X from Homebrew ---------------------- - -In OS X you need to have `XCode `_ and -`Homebrew `_ installed. Then, to install -libspotify:: - - brew install libspotify - -To update your existing libspotify installation using Homebrew:: - - brew update - brew upgrade - -When libspotify has been installed, continue with -:ref:`pyspotify_installation`. - - -.. _pyspotify_installation: - -Installing pyspotify -==================== - -When you've installed libspotify, it's time for making it available from Python -by installing pyspotify. - - -On Linux from APT archive -------------------------- - -If you run a Debian based Linux distribution, like Ubuntu, see -http://apt.mopidy.com/ for how to use the Mopidy APT archive as a software -source on your system. Then, simply run:: - - sudo apt-get install python-spotify - -This command will install both libspotify and pyspotify for you. - - -On Linux from source -------------------------- - -If you have have already installed libspotify, you can continue with installing -the libspotify Python bindings, called pyspotify. - -On Linux, you need to get the Python development files installed. On -Debian/Ubuntu systems run:: - - sudo apt-get install python-dev - -Then get, build, and install the latest releast of pyspotify using ``pip``:: - - sudo pip install -U pyspotify - - -On OS X from source -------------------- - -If you have already installed libspotify, you can get, build, and install the -latest releast of pyspotify using ``pip``:: - - sudo pip install -U pyspotify diff --git a/docs/settings.rst b/docs/settings.rst index 99064b60..5bc63d7f 100644 --- a/docs/settings.rst +++ b/docs/settings.rst @@ -19,8 +19,8 @@ You can either create the settings file yourself, or run the ``mopidy`` command, and it will create an empty settings file for you. When you have created the settings file, open it in a text editor, and add -settings you want to change. If you want to keep the default value for setting, -you should *not* redefine it in your own settings file. +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/settings.py`` may look as simple as this:: @@ -140,6 +140,41 @@ requirements of the `MPRIS specification `_. The ``TrackList`` and the ``Playlists`` interfaces of the spec are not supported. +Using a 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:: + + $ gst-inspect-0.10 + ... long list of installed plugins ... + Total count: 254 plugins (1 blacklist entry not shown), 1156 features + +Next, you should be able to produce a audible tone by running:: + + gst-launch-0.10 audiotestsrc ! sudioresample ! autoaudiosink + +If you cannot hear any sound when running this command, you won't hear any +sound from Mopidy either, as Mopidy by default uses GStreamer's +``autoaudiosink`` to play audio. Thus, make this work before you file a bug +against Mopidy. + +If you for some reason want to use some other GStreamer audio sink than +``autoaudiosink``, you can set the setting :attr:`mopidy.settings.OUTPUT` to a +partial GStreamer pipeline description describing the GStreamer sink you want +to use. + +Example of ``settings.py`` for using OSS4:: + + OUTPUT = u'oss4sink' + +Again, this is the equivalent of the following ``gst-inspect`` command, so make +this work first:: + + gst-launch-0.10 audiotestsrc ! audioresample ! oss4sink + + Streaming audio through a SHOUTcast/Icecast server ==================================================