====== Pitchfork_&_MPD_with_PulseAudio ======

===== Installation =====
==== Pitchfork ====
  * Download the .tar.bz2 from http://pitchfork.remiss.org/.
  * Ensure you have Apache, PHP, PHP-Pear and MPD installed:
 sudo apt-get install apache2 php5 php-pear mpd
  * Extract the .tar.bz2 to a directory in Apache's document root (specified in **/etc/apache2/sites-available/default**, and defaults to **/var/www**), e.g. to **/var/www/pitchfork**.
  * Give Apache write access to Pitchfork's **config** directory in one way or another, e.g.:
 sudo chmod 777 /var/www/pitchfork/config
  * Copy Pitchfork's configuration file to Apache's **config** directory.  This will change a few PHP options for Pitchfork, such as disabling PHP's Magic Quotes feature.  Note that if you decide to install Pitchfork somewhere other than **/var/www/pitchfork**, you will have to manually edit **pitchfork.conf** to specify directories:
 sudo cp ///var/www/pitchfork///doc/pitchfork.conf /etc/apache2/conf.d/

==== MPD ====
  * Give MPD access to your music.  Check MPD's music location by reading **/etc/mpd.conf**; it defaults to **/var/lib/mpd/music**:
 fgrep ‘music_directory’ /etc/mpd.conf
  * There are a few choices, here, either:
    * Remove that directory from the filesystem and replace it with a same-name symlink to your music directory,
    * Or create numerous symlinks inside that directory to various music directories (e.g. on different SMB mounts),
    * Or you could move/copy your music into that directory, but you'll probably prefer to keep your music somewhere where you can find it, rather than moving it into **/var/lib**, and copying a music collection will waste a lot of hard disk space, so this option is not recommended.
    * Or you could change the "music_directory" configuration option in **/etc/mpd.conf** to point to where your music is stored.
  * Update MPD's database:
 sudo mpd --create-db
  * Now you need to tell MPD to output to PulseAudio.  To do this, open **/etc/mpd.conf** in your favourite text editor (''sudo vi /etc/mpd.conf''), scroll down to the "Audio Output" section, then add this block, ensuring it isn't automatically commented, using whatever "name" value you wish:
 audio_output {
         type    "pulse"
         name    "PulseAudio on //MachineName//"
 }
  * For some reason that I haven't solved so far, MPD will get Access Denied errors to PulseAudio when first trying to play a track.  The only workaround I’ve come up with as yet is to tick the "Don't require authentication" box on the PulseAudio "Configure Local Sound Server" dialog.
  * To allow Pitchfork to control the volume, edit **/etc/mpd.conf** again (''sudo vi /etc/mpd.conf''), scroll down to the "Mixer" section and uncomment the line ** 'mixer_type "software"** '.  This isn't ideal, but I can't figure out how to get MPD to change PulseAudio's volume control (if it's possible at all).
  * Finally restart MPD to activate all your changes:
 sudo /etc/init.d/mpd restart

You should now be able to log into Pitchfork by accessing http://localhost/pitchfork (substituting 'localhost' with the machine's IP address or hostname, if accessing from another computer).  Pitchfork will initially display a configuration page, but all of the defaults can be left, so you can safely just click the 'Save' button.  If everything worked properly, you should see your music and it should be playable.

==== Running PulseAudio as a System-Wide Daemon ====
Normally PulseAudio will run as a per-user service, but on a headless box where you generally won't be logging in to Gnome this isn't very helpful.  As such it's preferable to run PulseAudio as a system-wide daemon so that any user can access it.  There are issues related to running PulseAudio like this, which are detailed on the [[http://www.pulseaudio.org/wiki/SystemWideInstance|relevant page of the PulseAudio site]], but for most purposes they aren't much of a concern.
  * By default PulseAudio is prevented from running like this.  To fix that, open **/etc/default/pulseaudio** in your favourite text editor and change **PULSEAUDIO_SYSTEM_START** to **1** and **DISALLOW_MODULE_LOADING** to **0**.  The latter isn't strictly necessary but is a good idea.  The **init.d** script should work properly, now - including automatically on system boot.
  * Because PulseAudio is no longer running as a user, it can't access the users' home directories for default sink/source and volume configuration options - its home directory is changed to **/var/run/pulse**.  To tell it which sink/source/volume to use, create symlinks to your current configuration:
 sudo mv /var/run/pulse/default-sink /var/run/pulse/default-sink.bak
 sudo mv /var/run/pulse/default-source /var/run/pulse/default-source.bak
 sudo mv /var/run/pulse/volume-restore.table /var/run/pulse/volume-restore.table.bak
 sudo ln -s ~/.pulse/default-sink /var/run/pulse/default-sink
 sudo ln -s ~/.pulse/default-source /var/run/pulse/default-source
 sudo ln -s ~/.pulse/volume-restore.table /var/run/pulse/volume-restore.table
  * MPD won't have access to PulseAudio yet, and I don't know the "proper" way of giving it access, but the cheaty way is to change MPD to run as PulseAudio's user: **pulse**.  Edit **/etc/mpd.conf** and change its **"user"** configuration option to **"pulse"**.
  * MPD will then run as the **pulse** user, so won't have access to its log files and pid file.  As the **pulse** and **mpd** users are both in the **audio** group, just add group read/write permissions to **/var/log/mpd** and its contents, and **/var/run/mpd**:
 sudo chmod -R g+rw /var/log/mpd
 sudo chmod g+rw /var/run/mpd
  * MPD should now be able to play to PulseAudio even when you're not logged into Gnome.

===== Current Issues =====
  * Non-software volume control in MPD needs to be sorted, but while support apparently exists for ALSA and OSS, none seems to exist for PulseAudio.
  * Requiring no authentication in PulseAudio is not a good idea, and a better workaround needs to be figured out.