MyFavMirrors/owntone-server
1
0
Fork 0
mirror of https://github.com/owntone/owntone-server.git synced 2024-12-26 07:05:57 -05:00
Code Issues Packages Projects Releases Wiki Activity

[docs] Update README.md with web interface instructions

Browse Source
This commit is contained in:
ejurgensen 2017-12-17 23:28:58 +01:00
parent 37e923bf74
commit 94a3d67559
1 changed files with 122 additions and 153 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

275
README.md
View File

@ -14,10 +14,30 @@ by iTunes and friends to share/stream media libraries over the network.
forked-daapd is a complete rewrite of mt-daapd (Firefly Media Server).
## Contents of this README
## Looking for help?
Before you continue, make sure you know what version of forked-daapd you have,
and what features it was built with (e.g. Spotify support).
How to find out? Go to the [web interface](http://forked-daapd.local:3689) and
check the information in the footer. No web interface? Then check the top of
forked-daapd's log file (usually /var/log/forked-daapd.log).
Note that you are viewing a snapshot of the instructions that may or may not
match the version of forked-daapd that you are using. Go to
[references](#references) to find instructions for previous versions of
forked-daapd.
If you are looking for help on building forked-daapd (not using it), then
please see the
[INSTALL](https://github.com/ejurgensen/forked-daapd/blob/master/INSTALL) file.
## Contents
- [Getting started](#getting-started)
- [Supported clients](#supported-clients)
- [Web interface](#web-interface)
- [Using Remote](#using-remote)
- [AirPlay devices/speakers](#airplay-devicesspeakers)
- [Chromecast](#chromecast)
@ -29,12 +49,13 @@ forked-daapd is a complete rewrite of mt-daapd (Firefly Media Server).
- [Playlists and internet radio](#playlists-and-internet-radio)
- [Artwork](#artwork)
- [Library](#library)
- [Command line and web interface](#command-line-and-web-interface)
- [Command line](#command-line)
- [Spotify](#spotify)
- [LastFM](#lastfm)
- [MPD clients](#mpd-clients)
- [References](#references)
## Getting started
After installation (see [INSTALL](https://github.com/ejurgensen/forked-daapd/blob/master/INSTALL))
@ -43,10 +64,13 @@ do the following:
1. Edit the configuration file (usually `/etc/forked-daapd.conf`) to suit your
needs
2. Start or restart the server (usually `/etc/init.d/forked-daapd restart`)
3. Wait for the library scan to complete. You can follow the progress with
`tail -f /var/log/forked-daapd.log`
4. If you are going to use a remote app, pair it following the procedure
[described below](#using-remote)
3. Go to the web interface [http://forked-daapd.local:3689](http://forked-daapd.local:3689),
or, if that won't work, to [http://[your_server_address_here]:3689](http://[your_server_address_here]:3689)
4. Wait for the library scan to complete
5. If you will be using a remote, e.g. Apple Remote: Start the remote, go to
Settings, Add Library
6. Enter the pair code in the web interface (update the page with F5 if it does
not automatically pick up the pairing request)
## Supported clients
@ -67,6 +91,9 @@ to AirPlay devices.
A single forked-daapd instance can handle several clients concurrently,
regardless of the protocol.
By default all clients on 192.168.* (and the ipv6 equivalent) are allowed to
connect without authentication. You can change that in the configuration file.
Here is a list of working and non-working DAAP and Remote clients. The list is
probably obsolete when you read it :-)
@ -88,72 +115,44 @@ probably obsolete when you read it :-)
| TunesRemote SE | | Remote | Java | Yes (r108) |
## Web interface
You can find forked-daapd's admin web interface at [http://forked-daapd.local:3689](http://forked-daapd.local:3689)
or alternatively at [http://[your_server_address_here]:3689](http://[your_server_address_here]:3689).
Use the web interface to trigger manual library rescans, pair with remotes,
select speakers, authenticate with Spotify, etc.
## Using Remote
If you plan to use Remote for iPod/iPhone/iPad with forked-daapd, read the
following sections. The pairing process described is similar for other
controllers/remotes (e.g. Retune), but some do not require pairing.
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 AirPlay: 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).
### Pairing with Remote on iPod/iPhone
If no output is selected when playback starts, forked-daapd will try to
autoselect a device.
NOTE: These are the instructions for the current version of forked-daapd - for
versions 24.2 and earlier see [here](https://github.com/ejurgensen/forked-daapd/blob/24.2/README.md#using-remote)
forked-daapd remembers your selection and the individual volume for each
output device; selected devices will be automatically re-selected, except if
they return online during playback.
If you just started forked-daapd for the first time, then wait til the library
scan completes before pairing with Remote (see [library](#library)). Otherwise
you risk timeouts. Then do the following.
### Pairing
The Quick Way:
1. Download and run the helper script from [here](https://raw.githubusercontent.com/ejurgensen/forked-daapd/master/scripts/pairinghelper.sh)
Another option is to use mpc (MPD command line client):
1. `mpc sendmessage pairing 5387` (where 5387 is the 4-digit pairing code displayed by Remote)
Or, if that doesn't work:
1. Start forked-daapd
1. Open the [web interface](http://forked-daapd.local:3689)
2. Start Remote, go to Settings, Add Library
3. Look in the log file for a message saying:
```
"Discovered remote 'Foobar' (id 71624..."
```
This tells you the name of your device (Foobar in this example).
If you cannot find this message, it means that forked-daapd did not receive
a mDNS announcement from your Remote. You have a network issue and mDNS
doesn't work properly on your network.
4. Prepare a text file with a filename ending with .remote; the filename
doesn't matter, only the .remote ending does. This first line in the file
must contain the 4-digit pairing code displayed by Remote. (note: previous
versions required the first line to be the device name - see the
instructions linked above).
5. Move this file somewhere in your library
3. Enter the pair code in the web interface (update the page with F5 if it does
not automatically pick up the pairing request)
At this point, you should be done with the pairing process and Remote should
display the name of your forked-daapd library. You should 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. Here are some common reasons:
#### Your library is a network mount
forked-daapd does not get notified about new files on network mounts, so the
.remote file was not detected. You will see no log file messages about the file.
Solution: Set two library paths in the config, and add the .remote file to the
local path. See [Libraries on network mounts](#libraries-on-network-mounts).
If Remote doesn't connect to forked-daapd after you entered the pairing code
something went wrong. Check the log file to see the error message. Here are
some common reasons:
#### You did not enter the correct pairing code
You will see an error in the log about pairing failure with a HTTP response code
that is *not* 0.
Solution: Try again. You can also try the pairinghelper script located in the
scripts-folder of the source or the mpc method described above.
Solution: Try again.
#### No response from Remote, possibly a network issue
If you see an error in the log with either:
@ -188,20 +187,6 @@ Hit Ctrl-C to terminate avahi-browse.
To check for network issues you can try to connect to address and port with
telnet.
### 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 AirPlay: 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).
If no output is selected when playback starts, forked-daapd will try to
autoselect a device.
forked-daapd remembers your selection and the individual volume for each
output device; selected devices will be automatically re-selected, except if
they return online during playback.
## AirPlay devices/speakers
@ -211,14 +196,8 @@ must be given in the configuration file. See the sample configuration file
for the syntax.
If your Apple TV requires device verification (always required by Apple TV4 with
tvOS 10.2) then you must select the device for playback, whereafter a PIN will
be displayed by the Apple TV. The do either of the following:
Alternative 1: Create a file ending with .verification in your music library,
input the PIN, and save the file. Forked-daapd will now pair with the device,
and if you select the device again, playback should start.
Alternative 2: Run "mpc sendmessage verification [PIN]" (requires the mpc tool),
and then select the device again. Playback should start.
tvOS 10.2) then you can do that through the web interface: Select the device and
then enter the PIN that the Apple TV displays.
For troubleshooting, see [using Remote](#using-remote).
@ -230,8 +209,6 @@ is no configuration to be done. This feature relies on streaming the audio in
mp3 to your Chromecast device, which means that mp3 encoding must be supported
by your ffmpeg/libav. See [MP3 network streaming](#mp3-network-streaming-streaming-to-ios).
It is also required that forked-daapd is built with "--enable-chromecast".
## Local audio through ALSA
@ -273,13 +250,15 @@ Note that MP3 encoding must be supported by ffmpeg/libav for this to work. If
it is not available you will see a message in the log file. In Debian/Ubuntu you
get MP3 encoding support by installing the package "libavcodec-extra".
## Remote access
It is possible to access a shared library over the internet. You must have remote
access to the host machine.
It is possible to access a shared library over the internet from a DAAP client
like iTunes. You must have remote access to the host machine.
First log in to the host and forward port 3689 to your local machine. You now need to
broadcast the daap service to iTunes on your local machine. On macOS the command is:
First log in to the host and forward port 3689 to your local machine. You now
need to broadcast the daap service to iTunes on your local machine. On macOS the
command is:
```
dns-sd -P iTunesServer _daap._tcp local 3689 localhost.local 127.0.0.1 "ffid=12345"
@ -289,9 +268,10 @@ The `ffid` key is required but its value does not matter.
Your library will now appear as 'iTunesServer' in iTunes.
## Supported formats
forked-daapd should support pretty much all media formats. It relies on libav
forked-daapd should support pretty much all audio formats. It relies on libav
(or ffmpeg) to extract metadata and decode the files on the fly when the client
doesn't support the format.
@ -364,26 +344,26 @@ forked-daapd caches artwork in a separate cache file. The default path is
file. The cache.db file can be deleted without losing the library and pairing
informations.
## Library
The library is scanned in bulk mode at startup, but the server will be available
even while this scan is in progress. You can follow the progress of the scan in
the log file. When the scan is complete you will see the log message: "Bulk
library scan completed in X sec".
the log file or via the web interface. When the scan is complete you will see
the log message: "Bulk library scan completed in X sec".
The very first scan will take longer than subsequent startup scans, since every
file gets analyzed. At the following startups the server looks for changed files
and only analyzis those.
Changes to the library are reflected in real time after the initial scan. The
directories are monitored for changes and rescanned on the fly. Note that if you
have your library on a network mount then real time updating may not work. Read
below about what to do in that case.
Updates to the library are reflected in real time after the initial scan, so you
do not need to manually start rescans. The directories are monitored for changes
and rescanned on the fly. Note that if you have your library on a network mount
then real time updating may not work. Read below about what to do in that case.
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 below.
You can do this by using "Update library" from the web interface.
Symlinks are supported and dereferenced, but it is best to use them for
directories only.
@ -445,20 +425,22 @@ and speaker information will be kept. Only use this for troubleshooting, it is
not necessary during normal operation.
## Command line
## Command line and web interface
You can choose between:
forked-daapd is meant to be used with the clients mentioned above, so it does
not have a command line interface nor does it have a web interface. You can,
however, to some extent control forked-daapd with [MPD clients](#mpd-clients) or
from the command line by issuing DAAP/DACP commands with a program like curl.
Here is an example of how to do that.
- a [MPD command line client](#mpd-clients) (easiest) like `mpc`
- curl with forked-daapd's JSON API
- curl with DAAP/DACP commands (hardest)
Say you have a playlist with a radio station, and you want to make a script that
starts playback of that station:
Using the JSON API is currently undocumented (TODO).
1. Run 'sqlite3 [your forked-daapd db]'. Use 'select id,title from files' to get
the id of the radio station, and use 'select id,title from playlists' to get
Here is an example of how to use curl with DAAP/DACP. Say you have a playlist
with a radio station, and you want to make a script that starts playback of that
station:
1. Run `sqlite3 [your forked-daapd db]`. Use `select id,title from files` to get
the id of the radio station, and use `select id,title from playlists` to get
the id of the playlist.
2. Convert the two ids to hex.
3. Put the following lines in the script with the relevant ids inserted (also
@ -472,43 +454,32 @@ curl "http://localhost:3689/logout?session-id=50"
```
## Spotify
forked-daapd has support for playback of the tracks in your Spotify library. It
must have been compiled with the `--enable-spotify` option (see
[INSTALL](https://github.com/ejurgensen/forked-daapd/blob/master/INSTALL)).
You must also have libspotify installed, otherwise Spotify integration will not
be available. Unfortunately the library is no longer available from Spotify, and
at the time of writing they have not provided an alternative. You can, however,
still get libspotify here:
forked-daapd has support for playback of the tracks in your Spotify library.
- Debian package (libspotify-dev), see https://apt.mopidy.com
You must also have a Spotify premium account. If you normally log into Spotify
with your Facebook account you must first go to Spotify's web site where you can
get the Spotify username and password that matches your account. With
forked-daapd you cannot login into Spotify with your Facebook username/password.
1. Go to the [web interface](http://forked-daapd.local:3689) and check that your
version of forked-daapd was built with Spotify support.
2. You must have a Spotify premium account. If you normally log into Spotify
with your Facebook account you must first go to Spotify's web site where you
can get the Spotify username and password that matches your account.
3. Make sure you have `libspotify` installed. Unfortunately, it is no longer
available from Spotify, and at the time of writing this they have not
provided an alternative. However, on most Debian-based platforms, you can
still get it like this:
- Add the mopidy repository, see [instructions](https://apt.mopidy.com)
- Install with `apt install libspotify-dev`
The procedure for logging in to Spotify is a two-step procedure due to the
current state of libspotify:
1. Put a file in your forked-daapd library containing two lines, the first being
your Spotify user name, and the second your password. The filename must have
the ending ".spotify"
2. Delete the file again - forked-daapd will have read it.
3. forked-daapd will log in and add all music in your Spotify playlists to its
database. Wait until completed (follow progress in the log file).
4. In a browser, go to [http://forked-daapd.local:3689/oauth](http://forked-daapd.local:3689/oauth)
(the default credentials are "admin"/"unused") and click the link to
authorize forked-daapd with Spotify.
Once the above is in order you can login to Spotify via the web interface. The
procedure for logging in to Spotify is a two-step procedure due to the current
state of libspotify, but the web interface makes both steps available to you.
Spotify will automatically notify forked-daapd about playlist updates, so you
should not need to restart forked-daapd to syncronize with Spotify. However,
Spotify only notifies about playlist updates, not new saved tracks/albums, so
you need to repeat step 4 above to load those.
you need to manually trigger a rescan to get those.
Forked-daapd will not store your password, but will still be able to log you in
forked-daapd will not store your password, but will still be able to log you in
automatically afterwards, because libspotify saves a login token. You can
configure the location of your Spotify user data in the configuration file.
@ -524,27 +495,17 @@ to iTunes.
## LastFM
If forked-daapd was built with LastFM scrobbling enabled (see the
[INSTALL](https://github.com/ejurgensen/forked-daapd/blob/master/INSTALL) file)
you can have it scrobble the music you listen to. To set up scrobbling you must
create a text file with the file name ending ".lastfm". The file must have two
lines: The first is your LastFM user name, and the second is your password. Move
the file to your forked-daapd library. Forked-daapd will then log in and get a
permanent session key.
You can have forked-daapd scrobble the music you listen to. To set up scrobbling
go to the web interface and authorize forked-daapd with your LastFM credentials.
You should delete the .lastfm file immediately after completing the first login.
For safety, forked-daapd will not store your LastFM username/password, only the
session key. The session key does not expire.
To stop scrobbling from forked-daapd, add an empty ".lastfm" file to your
library.
forked-daapd will not store your LastFM username/password, only the session key.
The session key does not expire.
## MPD clients
If forked-daapd was built with support for the [Music Player Deamon](http://musicpd.org/)
protocol (see the [INSTALL](https://github.com/ejurgensen/forked-daapd/blob/master/INSTALL)
file) you can - to some extent - use clients for MPD to control forked-daapd.
You can - to some extent - use clients for MPD to control forked-daapd.
By default forked-daapd listens on port 6600 for MPD clients. You can change
this in the configuration file.
@ -559,7 +520,7 @@ the same way they would running MPD:
on/off, instead repeat off, repeat all and repeat single are supported. Thus setting single on
will result in repeat single, repeat on results in repeat all.
Following table shows what is working for a selection of MPD clients:
The following table shows what is working for a selection of MPD clients:
| Client | Type | Status |
| --------------------------------------------- | ------ | --------------- |
@ -571,8 +532,16 @@ Following table shows what is working for a selection of MPD clients:
The source for this version of forked-daapd can be found here:
https://github.com/ejurgensen/forked-daapd.git
[https://github.com/ejurgensen/forked-daapd.git](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://git.debian.org/?p=users/jblache/forked-daapd.git](http://git.debian.org/?p=users/jblache/forked-daapd.git)
README's for previous versions of forked-daapd:
[forked-daapd version 25.0](https://github.com/ejurgensen/forked-daapd/blob/25.0/README.md)
[forked-daapd version 24.2](https://github.com/ejurgensen/forked-daapd/blob/24.2/README.md)
[forked-daapd version 24.1](https://github.com/ejurgensen/forked-daapd/blob/24.1/README.md)