owntone-server/README

forked-daapd
------------

forked-daapd is a DAAP and RSP media server, with support for Linux and
FreeBSD. It is a complete rewrite of mt-daapd (Firefly Media Server).

DAAP stands for Digital Audio Access Protocol, and is the protocol used
by iTunes and friends to share/stream media libraries over the network.

RSP is Roku's own media sharing protocol. Roku are the makers of the
SoundBridge devices. See <http://www.roku.com>.

The source for this version of forked-daapd can be found here:

  <https://github.com/ejurgensen/forked-daapd.git>

The original (now unmaintained) source can be found here:

  <http://git.debian.org/?p=users/jblache/forked-daapd.git>
  <http://alioth.debian.org/~jblache/forked-daapd/>


Supported clients
-----------------

forked-daapd supports iTunes clients as well as a number of devices similar
to the SoundBridge.

It should be able to serve your media library to any client supporting DAAP
or RSP.

A single forked-daapd instance can handle several clients concurrently,
regardless of the protocol.


Using Remote
------------

If you plan to use Remote with forked-daapd, read the following sections
carefully.

  Pairing with Remote on iPod/iPhone
  ----------------------------------

forked-daapd can be paired with Apple's Remote application for iPod/iPhone;
this is how the pairing process works:
 - start forked-daapd
 - start Remote, go to Choose Library, Add Library
 - prepare a text file with a filename ending with .remote; the filename
   doesn't matter, only the .remote ending does. This file must contain
   two lines: the first line is the name of your iPod/iPhone, the second
   is the 4-digit pairing code displayed by Remote.

   If your iPod/iPhone is named "Foobar" and Remote gives you the pairing
   code 5387, the file content will be:

      Foobar
      5387 

 - move this file somewhere in your library

At this point, you should be done with the pairing process and Remote should
display the name of your forked-daapd library. You can delete the .remote file
once the pairing process is done.

If Remote doesn't display the name of your forked-daapd library at this point,
the pairing process failed.

This will usually be because the .remote file did not contain the correct name
or pairing code. Start over the pairing process and try again.

If in doubt, enable a more verbose level of logging and check that forked-daapd
receives the mDNS announcement from your iPod/iPhone when the pairing code is
displayed by Remote (you can also use avahi-browse for this purpose, see below).
If not, you have a network issue and mDNS doesn't work properly on your network.

If you are unsure about your iPod/iPhone's name, here's how you can check for
the correct value:
 - in a terminal, run avahi-browse -r -k _touch-remote._tcp
 - start Remote, goto Choose Library, Add Library
 - after a couple seconds at most, you should get something similar to this:

+ ath0 IPv4 59eff13ea2f98dbbef6c162f9df71b784a3ef9a3      _touch-remote._tcp   local
= ath0 IPv4 59eff13ea2f98dbbef6c162f9df71b784a3ef9a3      _touch-remote._tcp   local
   hostname = [Foobar.local]
   address = [192.168.1.1]
   port = [49160]
   txt = ["DvTy=iPod touch" "RemN=Remote" "txtvers=1" "RemV=10000" "Pair=FAEA410630AEC05E" "DvNm=Foobar"]

The name of your iPod/iPhone is the value of the DvNm field above. In this
example, the correct value is Foobar.

Watch out for fancy characters; for instance, the name of your device may
include Unicode characters that aren't visually different from plain ASCII
characters (like the single quote if your device name follows the default
scheme of "Foo's iPhone"). If unsure, change the name of your device or
capture the output in a file to extract the real, correct name.

Hit Ctrl-C to terminate avahi-browse.

  Selecting output devices
  ------------------------

Remote gets a list of output devices from the server; this list includes any
and all devices on the network we know of that advertise AirTunes: AirPort
Express, Apple TV, ... It also includes the local audio output, that is, the
sound card on the server (even if there is no soundcard).

By default, if no output is selected when playback starts, the local output
device will be used, following the principle of least surprise (ie not
selecting an output device at random that can be anywhere in the house or
elsewhere). forked-daapd will error out if the local output is not usable
(no soundcard, bad permissions, ...).

There are two ways to select the output devices in Remote:
 - in the settings panel;
 - in the AirPlay panel during playback.

Be aware that the settings panel doesn't show any output device when there
is only one; the one output device that is available is automatically used.

forked-daapd remembers your selection and the individual volume for each
output device; selected devices will be automatically re-selected at the next
server startup, provided they appear in the 5 minutes following the startup
and no playback has occured yet. Again, principle of least surprise.


AirTunes devices
----------------

forked-daapd will discover the AirTunes devices available on your network. For
devices that are password-protected, the device's AirTunes name and password
must be given in the configuration file. See the sample configuration file
for the syntax.


Local audio output
------------------

The audio section of the configuration file supports 2 parameters for the local
audio device:
 - nickname: this is the name that will be used in the speakers list in Remote
 - card: this is the name/device string (ALSA) or device node (OSS4) to be used
   as the local audio device. Defaults to "default" for ALSA and "/dev/dsp" for
   OSS4.


Supported formats
-----------------

forked-daapd should support pretty much all media formats. It relies on libav
(ffmpeg) to extract metadata and decode the files on the fly when the client
doesn't support the format.

However, libav is not necessarily very good at extracting metadata, so some
formats may cause problems. FLAC, Musepack and WMA use custom metadata
extractors to work around that.

Formats are attributed a code, so any new format will need to be explicitely
added. Currently supported:
 - MPEG4: mp4a, mp4v
 - AAC: alac
 - MP3 (and friends): mpeg
 - FLAC: flac
 - OGG VORBIS: ogg
 - Musepack: mpc
 - WMA: wma (WMA Pro), wmal (WMA Lossless), wmav (WMA video)
 - AIFF: aif
 - WAV: wav


Streaming MPEG4
---------------

Depending on the client application, you may need to optimize your MPEG4 files
for streaming. Stream-optimized MPEG4 files have their metadata at the beginning
of the file, whereas non-optimized files have them at the end.

Not all clients need this; if you're having trouble playing your MPEG4 files,
this is the most probable cause. iTunes, in particular, doesn't handle files
that aren't optimized, though FrontRow does.

Files produced by iTunes are always optimized by default. Files produced by
FAAC and a lot of other encoders are not, though some encoders have an option
for that.

The mp4creator tool from the mpeg4ip suite can be used to optimize MPEG4 files,
with the -optimize option:
  $ mp4creator -optimize foo.m4a

Don't forget to make a backup copy of your file, just in case.

Note that not all tag/metadata editors know about stream optimization and will
happily write the metadata back at the end of the file after you've modified
them. Watch out for that.


Playlists
---------

forked-daapd supports M3U playlists. Just drop your playlist somewhere in
your library with an .m3u extension and it will pick it up.

Support for iTunes Music Library XML format is available as a compile-time
option. By default, metadata from our parsers is preferred over what's in
the iTunes DB; use itunes_overrides = true if you prefer iTunes' metadata.

Smart playlists are not supported at the moment.


Artwork
-------

forked-daapd has /some/ support for artwork, with a number of limitations.

Embedded artwork is not currently supported.

Your artwork must be in PNG or JPEG format, dimensions do not matter;
forked-daapd scales down (never up) the artwork on-the-fly to match the
constraints given by the client. Note, however, that the bigger the picture,
the more time and resources it takes to perform the scaling operation.

As for the naming convention, it is quite simple; consider your foo.mp3 song,
residing at /bar/foo.mp3:
 - if /bar/foo.{png,jpg} exists, this will be used as the artwork for this file;
 - failing that, if /bar/{artwork,cover,Folder}.{png,jpg} exists, it is used.
 - failing that, if /bar/bar.{png,jpg} exists, it will be used

For "groups" (same album name and album artist), the situation is a bit
different:
 - if a file {artwork,cover,Folder}.{png,jpg} is found in one of the directories
   containing files that are part of the group, it is used as the artwork. The
   first file found is used, ordering is not guaranteed;
 - failing that, if [directory name].{png,jpg} is found in one of the
   directories containing files that are part of the group, it is used as the
   artwork. The first file found is used, ordering is not guaranteed;
 - failing that, individual files are examined and the first artwork found is
   used. Here again, ordering is not guaranteed.

{artwork,cover,Folder} are the default, you can add other base names in the
configuration file.

You can use symlinks for the artwork files; the artwork is not scanned/indexed
in any way in the database and there is no caching on forked-daapd's side.


Library
-------

The library is scanned in bulk mode at startup, but the server will be
available even while this scan is in progress. Of course, if files have gone
missing while the server was not running a request for these files will
produce an error until the scan has completed and the file is no longer
offered. Similarly, new files added while the server was not running won't
be offered until they've been scanned.

Changes to the library are reflected in real time after the initial scan. The
directories are monitored for changes and rescanned on the fly.

If you place a file with the filename ending .force-rescan in your library,
you can trigger a full rescan of your library. This will clear all music and
playlists from forked-daapd's database and initiate a fresh bulk scan. Pairing
and speaker information will be kept. Only use this for troubleshooting, it is
not necessary during normal operation.

Symlinks are supported and dereferenced. This does interact in tricky ways
with the above monitoring and rescanning, so you've been warned. Changes to
symlinks themselves won't be taken into account, or not the way you'd expect.

If you use symlinks, do not move around the target of the symlink. Avoid
linking files, as files themselves aren't monitored for changes individually,
so changes won't be noticed unless the file happens to be in a directory that
is monitored.

Bottom line: symlinks are for directories only.