285 lines
11 KiB
Plaintext
285 lines
11 KiB
Plaintext
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.
|
|
|
|
forked-daapd support streaming to AirTunes devices (like the AirPort Express,
|
|
Shairport and various AirPlay speakers).
|
|
|
|
Like iTunes, you can control forked-daapd with Apple Remote, or with a
|
|
compatible Android app like Retune, TunesRemote+ or Hyperfine Remote. Another
|
|
controller is TunesRemoteSE, which is based on Java and runs in Windows, MacOS
|
|
and Linux.
|
|
|
|
|
|
Using Remote
|
|
------------
|
|
|
|
If you plan to use Remote with forked-daapd, read the following sections
|
|
carefully. The pairing process described is similar for other controllers, but
|
|
some do not require pairing.
|
|
|
|
Pairing with Remote on iPod/iPhone
|
|
----------------------------------
|
|
|
|
forked-daapd can be paired with Apple's Remote application for iPod/iPhone/iPad;
|
|
this is how the pairing process works:
|
|
|
|
- start forked-daapd
|
|
- start Remote, go to Settings, 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/iPad, the second
|
|
is the 4-digit pairing code displayed by Remote.
|
|
|
|
If your iPod/iPhone/iPad 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/iPad'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 Settings, 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/iPad 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, ...).
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
A full rescan might take some time, and sometimes you just want a rescan of a
|
|
particular part of your library. In this case the standard "touch" command is
|
|
very usefull, as it will update the timestamps of the arguments and thus trigger
|
|
a rescan.
|
|
|
|
If you change any of the directory settings in the library section of the
|
|
configuration file a rescan is required before the new setting will take effect.
|
|
Currently, this will not be done automatically, so you need to trigger the
|
|
rescan as described above.
|
|
|
|
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.
|