|
a/doc/upmpdcli.txt |
|
b/doc/upmpdcli.txt |
| 1 |
= Upmpdcli: MPD UPnP Renderer Front-End
|
1 |
= Upmpdcli: MPD UPnP Renderer Front-End
|
| 2 |
|
2 |
|
| 3 |
|
3 |
|
| 4 |
*upmpdcli* is an UPnP Media Renderer front-end to *MPD*, the Music Player
|
4 |
*upmpdcli* is an UPnP Media Renderer front-end to *MPD*, the Music Player
|
| 5 |
Daemon. It supports both pure UPnP and the OpenHome ohMedia services.
|
5 |
Daemon. It supports both pure UPnP and the OpenHome ohMedia services.
|
|
|
6 |
|
|
|
7 |
In OpenHome mode, it supports radio streams and has the ability to
|
|
|
8 |
interface to Linn Songcast for playing audio captured on Windows or Mac OS
|
|
|
9 |
X or for multiroom playing.
|
| 6 |
|
10 |
|
| 7 |
[[upmpdcli.security]]
|
11 |
[[upmpdcli.security]]
|
| 8 |
== Security
|
12 |
== Security
|
| 9 |
|
13 |
|
| 10 |
*upmpdcli* is not audited for security issues, and, as far as I
|
14 |
*upmpdcli* is not audited for security issues, and, as far as I
|
|
... |
|
... |
| 20 |
upmpdcli -D -c /etc/upmpdcli.conf
|
24 |
upmpdcli -D -c /etc/upmpdcli.conf
|
| 21 |
|
25 |
|
| 22 |
The `-D` option tells *upmpdcli* to fork and run in background. The `-c`
|
26 |
The `-D` option tells *upmpdcli* to fork and run in background. The `-c`
|
| 23 |
option specifies a configuration file.
|
27 |
option specifies a configuration file.
|
| 24 |
|
28 |
|
| 25 |
The configuration file has a simple `name = value` format.
|
|
|
| 26 |
|
|
|
| 27 |
The configuration parameters can be set from the command line, a
|
29 |
The configuration parameters can be set from the command line, a
|
| 28 |
configuration file, or the environment in this order of priority. It would
|
30 |
configuration file, or the environment in this order of priority. It would
|
| 29 |
be rather confusing to use a mix of methods, so you should probably chose
|
31 |
be rather confusing to use a mix of methods, so you should probably chose
|
| 30 |
one. Some less common parameters can only be set in the configuration file.
|
32 |
one. A majority of parameters can only be set in the configuration file.
|
| 31 |
|
33 |
|
|
|
34 |
The configuration file has a simple `name = value` format.
|
|
|
35 |
|
| 32 |
All parameters have defaults, and a typical installation needs no
|
36 |
All parameters have defaults, and a typical installation will need no
|
| 33 |
modification of the configuration file. If several instances of *upmpdcli*
|
37 |
customisation at all. If several instances of *upmpdcli* run on the same
|
| 34 |
run on the same network, you will want to give them distinct names
|
38 |
network, you will want to give them distinct names (_friendlyname_
|
| 35 |
(_friendlyname_ parameter). The other parameters are only useful in special
|
39 |
parameter). The other parameters are only useful in special situations.
|
| 36 |
situations.
|
|
|
| 37 |
|
40 |
|
| 38 |
The following parameters can be set:
|
41 |
The following parameters can be set by several methods. The parameters
|
|
|
42 |
which can only be set in the configuration file are described further down.
|
| 39 |
|
43 |
|
| 40 |
|========================
|
44 |
|========================
|
| 41 |
|What|Command line|Environment|Config variable
|
45 |
|What|Command line|Environment|Config variable
|
| 42 |
|Configuration file name|-c config|$UPMPD_CONFIG|
|
46 |
|Configuration file name|-c config|$UPMPD_CONFIG|
|
| 43 |
|Host name or IP address where *MPD* runs|-h mpdhost|$UPMPD_HOST|mpdhost
|
47 |
|Host name or IP address where *MPD* runs|-h mpdhost|$UPMPD_HOST|mpdhost
|
| 44 |
|TCP port for *MPD*|-p mpdport|$UPMPD_PORT|mpdport
|
48 |
|TCP port for *MPD*|-p mpdport|$UPMPD_PORT|mpdport
|
| 45 |
|*MPD* password|||mpdpassword
|
|
|
| 46 |
|Do we own the *MPD* queue and fearlessly clear it|-o 0/1||ownqueue
|
|
|
| 47 |
|UPnP "friendly name" for the device. This gets displayed in network search
|
49 |
|UPnP "friendly name" for the device. This gets displayed in network search
|
| 48 |
results.|-f friendlyname|$UPMPD_FRIENDLYNAME|friendlyname
|
50 |
results.|-f friendlyname|$UPMPD_FRIENDLYNAME|friendlyname
|
| 49 |
|Log file name. Leave empty for stderr|-d logfilename||logfilename
|
51 |
|Log file name. Leave empty for stderr|-d logfilename||logfilename
|
| 50 |
|Verbosity level (0-4)|-l loglevel||loglevel
|
52 |
|Verbosity level (0-4)|-l loglevel||loglevel
|
| 51 |
|UPnP network interface|-i iface|$UPMPD_UPNPIFACE|upnpiface
|
53 |
|UPnP network interface|-i iface|$UPMPD_UPNPIFACE|upnpiface
|
| 52 |
|UPnP IP address (if interface not set)|||upnpip
|
|
|
| 53 |
|UPnP port|-p port|$UPMPD_UPNPPORT|upnpport
|
54 |
|UPnP port|-p port|$UPMPD_UPNPPORT|upnpport
|
| 54 |
|UPnP AV support switch|||upnpav
|
|
|
| 55 |
|OpenHome support switch|-O 0/1||openhome
|
|
|
| 56 |
|OpenHome playlist disk persistence (default 1)|||ohmetapersist
|
|
|
| 57 |
|Directory for cached data (/var/cache/upmpdcli or ~/.cache/upmpdcli)|||cachedir
|
|
|
| 58 |
|Path to icon to be displayed by control point. <<upmpdcli.iconpathnote,See
|
|
|
| 59 |
note>>|||iconpath
|
|
|
| 60 |
|Path to HTML file to be used as presentation
|
|
|
| 61 |
page. <<upmpdcli.presentationnote,See note>>|||presentationhtml
|
|
|
| 62 |
|Run a command (or shell script) when a play action is performed. The difference
|
|
|
| 63 |
to onplay is that onstart is called *before* playback is about to begin.|||
|
|
|
| 64 |
onstart
|
|
|
| 65 |
|Run a command (or shell script) when MPD playback is about to begin. Note that
|
|
|
| 66 |
onstart is also called if MPD is controlled from another tool, e.g. by mpc.|||
|
|
|
| 67 |
onplay
|
|
|
| 68 |
|Run a command (or shell script) when MPD playback is about to end. Note that
|
|
|
| 69 |
onstart is also called if MPD is controlled from another tool, e.g. by mpc.|||
|
|
|
| 70 |
onstop
|
|
|
| 71 |
|Run a command (or shell script) when volume is changed.|||onvolumechange
|
|
|
| 72 |
|===========================
|
55 |
|===========================
|
| 73 |
|
56 |
|
| 74 |
[[upmpdcli.iconpathnote]]
|
57 |
|
|
|
58 |
[[upmpdcli.configfile]]
|
|
|
59 |
== Configuration file
|
|
|
60 |
|
|
|
61 |
In addition of the above, the following variables can be set in the
|
|
|
62 |
configuration file:
|
|
|
63 |
|
|
|
64 |
mpdpassword:: Password for connecting to *MPD* (only necessary if
|
|
|
65 |
password access is enabled in the *MPD* configuration file).
|
|
|
66 |
|
|
|
67 |
ownqueue:: If this is set (on by default), we own the *MPD* queue and will
|
|
|
68 |
fearlessly clear it.
|
|
|
69 |
|
|
|
70 |
upnpip:: UPnP IP address to use (if `upnpiface` is not used to select an
|
|
|
71 |
interface).
|
|
|
72 |
|
|
|
73 |
upnpav:: Activate UPnP AV services. This is set by default, but it may be
|
|
|
74 |
useful to switch it off with some too easily confused OpenHome Control
|
|
|
75 |
Points.
|
|
|
76 |
|
|
|
77 |
openhome:: Activate OpenHome services. This is set by default and there is
|
|
|
78 |
little reason to turn this off.
|
|
|
79 |
|
|
|
80 |
ohmetapersist:: OpenHome playlist disk persistence (default 1), no reason
|
|
|
81 |
to turn it off.
|
|
|
82 |
|
|
|
83 |
cachedir:: Directory for cached data (`/var/cache/upmpdcli` or
|
|
|
84 |
`~/.cache/upmpdcli`).
|
|
|
85 |
|
|
|
86 |
iconpath:: Path to an icon to be displayed by Control Points which support
|
| 75 |
*iconpath* note: the UPnP protocol has provisions for a renderer to send
|
87 |
it. The UPnP protocol has provisions for a renderer to send the URL to a
|
| 76 |
the URL to a descriptive icon as part of the device description. The icon
|
88 |
descriptive icon as part of the device description. The icon to use can be
|
| 77 |
to use can be set using the *iconpath* configuration file parameter. Due to
|
89 |
set using the *iconpath* configuration file parameter. Due to current (and
|
| 78 |
current (and probably permanent) *upmpdcli* limitations, the image file
|
90 |
probably permanent) *upmpdcli* limitations, the image file *must* be a
|
| 79 |
*must* be a 64x64 32 bits-per-pixel png file.
|
91 |
64x64 32 bits-per-pixel png file.
|
| 80 |
|
92 |
|
| 81 |
[[upmpdcli.presentationnote]]
|
93 |
presentationhtml:: Path to an HTML file to be used as presentation page. The
|
| 82 |
*presentationhtml* note: the file referenced by the path will only be read
|
94 |
file referenced by the path will only be read once when *upmpdcli* starts,
|
| 83 |
once when *upmpdcli* starts, it can't presently be used for status updates
|
95 |
it can't presently be used for status updates (but I guess that you could
|
| 84 |
(but I guess that you could put a redirect in there, to something more
|
96 |
put a redirect in there, to something more dynamic served by a real HTTP
|
| 85 |
dynamic served by a real HTTP server).
|
97 |
server).
|
| 86 |
|
98 |
|
| 87 |
[[upmpdcli.openhome]]
|
99 |
onplay:: Command to run when MPD playback is about to begin. Note that
|
| 88 |
== OpenHome ohMedia services
|
100 |
`onplay` is also called if MPD is controlled from another tool, e.g. by
|
|
|
101 |
`mpc`.
|
| 89 |
|
102 |
|
| 90 |
The support for ohMedia services (play queue managed by the player instead
|
103 |
onstart:: Command to run when a play action is performed. The difference to
|
| 91 |
of on the control point) is activated by default as of release 0.8.0, only
|
104 |
`onplay` is that `onstart` is called *before* playback is about to begin.
|
| 92 |
an explicit option will turn it off.
|
|
|
| 93 |
|
105 |
|
| 94 |
The previous version default was set to _off_ in the software, and _on_ in
|
106 |
onstop:: Command to run when MPD playback is about to end. Note that
|
| 95 |
the configuration file. As the configuration file is not usually
|
107 |
`onstop` is also called if MPD is controlled from another tool, e.g. by
|
| 96 |
overwritten during an upgrade, if you are upgrading to 0.7.x from an
|
108 |
`mpc`.
|
| 97 |
earlier version and you want to enable the services, you need to set the
|
|
|
| 98 |
option in the configuration file.
|
|
|
| 99 |
|
109 |
|
| 100 |
=== OpenHome Radio service
|
110 |
onvolumechange:: Command to run when sound volume is changed.
|
|
|
111 |
|
|
|
112 |
|
|
|
113 |
=== Radio station definitions
|
| 101 |
|
114 |
|
| 102 |
Recent Upmpdcli versions (after 0.13) implement an OpenHome Radio service
|
115 |
Recent Upmpdcli versions (after 0.13) implement an OpenHome Radio service
|
| 103 |
which allows selecting and listening to internet radio stations. The
|
116 |
which allows selecting and listening to internet radio stations.
|
| 104 |
stations are defined at the end of the configuration file in the following
|
117 |
|
| 105 |
way:
|
118 |
Radio stations can be defined in the configuration (at the end because of
|
|
|
119 |
the use of section indicators). Example:
|
| 106 |
|
120 |
|
| 107 |
----
|
121 |
----
|
| 108 |
[radio The name of the radio]
|
122 |
[radio Radio Teddy]
|
| 109 |
url = http//www.myradio.com/path/to/the/playlist.pls
|
123 |
url = http://opml.radiotime.com/Tune.ashx?id=s80044
|
| 110 |
artUrl = http//www.myradio.com/path/to/the/icon.png
|
124 |
artUrl = http://cdn-radiotime-logos.tunein.com/s80044q.png
|
| 111 |
----
|
125 |
----
|
| 112 |
|
126 |
|
| 113 |
`artUrl` is optional. None of the non-radio parameters can be defined after
|
127 |
The section name must begin with `radio`, the rest will be displayed as the
|
| 114 |
the first `[radio ...]` section (they would not be found).
|
128 |
station name. `url` and `artUrl` designate the playlist or stream, and an
|
|
|
129 |
icon. `artUrl` is optional.
|
| 115 |
|
130 |
|
| 116 |
The default config file contains a bunch of radio entries, copied from the
|
131 |
Radio channels can be accessed by selecting the `Radio` Source from an
|
| 117 |
radiotray app. Replace with your own !
|
132 |
OpenHome Control Point.
|
| 118 |
|
133 |
|
| 119 |
|
134 |
|
| 120 |
[[upmpdcli.songcast]]
|
135 |
[[upmpdcli.songcast]]
|
| 121 |
== Songcast integration
|
136 |
== Songcast integration
|
| 122 |
|
137 |
|