Merge pull request #1422 from trygveaa/docs/service-pulseaudio

docs: Add a note about PulseAudio when running as a service

docs/service.rst

@@ -92,3 +92,46 @@ Service on OS X
 ===============
 
 If you're installing Mopidy on OS X, see :ref:`osx-service`.
+
+
+Configure PulseAudio
+====================
+
+When using PulseAudio, you will typically have a PulseAudio server run by your
+main user. Since Mopidy is running as its own user, it can't access this server
+directly. Running PulseAudio as a system-wide daemon is discouraged by upstream
+(see `here
+<http://www.freedesktop.org/wiki/Software/PulseAudio/Documentation/User/WhatIsWrongWithSystemWide/>`_
+for details). Rather you can configure PulseAudio and Mopidy so Mopidy sends
+the sound to the PulseAudio server already running as your main user.
+
+First, configure PulseAudio to accept sound over tcp from localhost by
+uncommenting or adding the tcp module to :file:`/etc/pulse/default.pa` or
+:file:`$XDG_CONFIG_HOME/pulse/default.pa` (typically
+:file:`~/.config/pulse/default.pa`)::
+
+    ### Network access (may be configured with paprefs, so leave this commented
+    ### here if you plan to use paprefs)
+    #load-module module-esound-protocol-tcp
+    load-module module-native-protocol-tcp auth-ip-acl=127.0.0.1
+    #load-module module-zeroconf-publish
+
+Next, configure Mopidy to use this PulseAudio server::
+
+    [audio]
+    output = pulsesink server=127.0.0.1
+
+After this, restart both PulseAudio and Mopidy::
+
+    pulseaudio --kill
+    start-pulseaudio-x11
+    sudo systemctl restart mopidy
+
+If you are not running any X server, run ``pulseaudio --start`` instead of
+``start-pulseaudio-x11``.
+
+If you don't want to hard code the output in your Mopidy config, you can
+instead of adding any config to Mopidy add this to
+:file:`~mopidy/.pulse/client.conf`::
+
+    default-server=127.0.0.1