build: Use .ONESHELL.
[paraslash.git] / m4 / lls / audiod.suite.m4
1 m4_define(PROGRAM, para_audiod)
2 m4_define(DEFAULT_CONFIG_FILE, ~/.paraslash/audiod.conf)
3 [suite audiod]
4 version-string = GIT_VERSION()
5 [supercommand para_audiod]
6 purpose = connect to para_server, receive, decode and play audio streams
7 [description]
8 para_audiod runs on a host with an audio device and connects
9 para_server to obtain status information and receive the current audio
10 stream. The stream is transformed through any number of filters and
11 then written to the configured output device.
12
13 Moreover, para_audiod listens on a local socket and sends status
14 information to local clients on request. Access to the local socket
15 can be restricted by means of Unix socket credentials, if available.
16 [/description]
17 m4_include(common-option-section.m4)
18 m4_include(help.m4)
19 m4_include(detailed-help.m4)
20 m4_include(version.m4)
21 m4_include(config-file.m4)
22 m4_include(loglevel.m4)
23 m4_include(logfile.m4)
24 m4_include(color.m4)
25 m4_include(log-timing.m4)
26 m4_include(daemon.m4)
27 m4_include(user.m4)
28 m4_include(group.m4)
29 m4_include(priority.m4)
30 m4_include(per-command-options-section.m4)
31 [option force]
32 summary = force startup
33 short_opt = F
34 [help]
35 If this flag is not given, para_audiod refuses to start if the
36 well-known socket file (see the --socket option) already exists
37 because this usually means that para_audiod is already running and
38 listening on that socket. After a crash or if para_audiod received
39 a SIGKILL signal, a stale socket file might remain and you have to
40 use --force once to force startup of para_audiod.
41 [/help]
42 [option mode]
43 summary = select startup mode
44 arg_info = required_arg
45 arg_type = string
46 typestr = mode
47 values = {AUDIOD_ON = "on", AUDIOD_OFF = "off", AUDIOD_STANDBY = "sb"}
48 default_val = on
49 [help]
50 para_audiod supports three modes of operation: On, off and standby
51 (sb). This option selects the mode that should be used at startup. If
52 mode is "on", para_audiiod connects para_server to receive status
53 information. If the server announces the availability of an audio
54 stream, para_audiod downloads, decodes and plays the audio stream
55 according to the given stream I/O options, see below.
56
57 In "standby" mode, para_audiod only receives the status information
58 from para_server but does not download the audio stream.
59
60 In "off" mode, para_audiod does not connect para_server at all,
61 but still listens on the local socket.
62 [/help]
63 [option socket]
64 short_opt = s
65 summary = path to the well-known socket
66 arg_info = required_arg
67 arg_type = string
68 typestr = path
69 [help]
70 para_audiod listens on a "well-known" socket for connections
71 from para_audioc. This socket is a special file in the file system;
72 its location defaults to /var/paraslash/audiod_sock.$hostname.
73
74 para_audioc, the client program used to connect to para_audiod,
75 opens this socket in order to talk to para_audiod. If the default
76 value for para_audiod is changed, para_audioc must be instructed to
77 use also <path> to connect para_audiod.
78 [/help]
79 [option user-allow]
80 summary = allow this user to connect to audiod
81 arg_info = required_arg
82 arg_type = string
83 typestr = username
84 [help]
85 Allow the user identified by username (either a string or a UID) to
86 connect to para_audiod. This option may be given multiple times. If
87 not specified at all, all users are allowed to connect.
88
89 This feature is based on the ability to send unix credentials through
90 local sockets using ancillary data (SCM_CREDENTIALS). Currently it
91 only works on Linux. On other operating systems the option is silently
92 ignored and all local users are allowed to connect.
93 [/help]
94 [option clock-diff-count]
95 summary = sync clock on startup
96 arg_info = required_arg
97 arg_type = uint32
98 typestr = count
99 [help]
100 Check the clock difference between the host running para_server and
101 the local host running para_audiod this many times before starting
102 any stream I/0. Set this to non-zero for non-local setups if the
103 clocks of these two hosts are not synchronized by ntp or similar.
104 [/help]
105 [option Stream-IO-options]
106 summary = Stream I/O options
107 flag ignored
108 [option receiver]
109 short_opt = r
110 summary = select receiver
111 arg_info = required_arg
112 arg_type = string
113 typestr = receiver_spec
114 default_val = http
115 flag multiple
116 [help]
117 This option may be given multiple times, for each audio format
118 separately. If multiple definitions for an audio format are given,
119 the first one is selected.
120
121 The <receiver_spec> consists of an audio format specifier and one or
122 more receiver arguments, separated by a colon.
123
124 The audio format specifier is a regular expression which specifies
125 the set of audio formats for which this option should apply.
126
127 If any receiver options are present, the whole receiver argument must
128 be quoted:
129
130 -r 'mp3:http -i my.host.org -p 8009'
131
132 Since a single dot '.' matches the name of any audio format, specifying
133 '.' instead of 'mp3' above activates the http receiver for all audio
134 formats.
135 [/help]
136 [option filter]
137 short_opt = f
138 summary = specify the filter configuration
139 arg_info = required_arg
140 arg_type = string
141 typestr = filter_spec
142 flag multiple
143 [help]
144 This option may be given multiple times. The <filter_spec< consists
145 of an audio format specifier (see above), the name of the filter,
146 and any options for that filter. Note that order matters.
147
148 The compiled-in defaults apply to all audio formats for which no
149 --filter option was given. These defaults depend on the receiver
150 being used.
151
152 For HTTP streams, only the decoder for the current audio format
153 is activated. UDP and DCCP streams, on the other hand, are sent
154 FEC-encoded by para_server. In order to play such streams, the
155 receiver output must be FEC-decoded first, i.e. fed to the fecdec
156 filter. Therefore the default for UDP and DCCP streams is to activate
157 the fecdec filter, followed by the decoding filter for the audio
158 format.
159
160 Examples:
161
162 --filter 'mp3:mp3dec'
163
164 --filter 'mp3|aac:compress --inertia 5 --damp 2'
165
166 --filter '.:fecdec'
167 [/help]
168 [option writer]
169 short_opt = w
170 summary = specify one or more stream writers
171 arg_info = required_arg
172 arg_type = string
173 typestr = writer_spec
174 flag multiple
175 [help]
176 May be given multiple times, even multiple times for the same audio
177 format. The default is to use the first supported writer. Example:
178
179 --writer 'aac|wma:oss'
180 [/help]
181 [option stream-delay]
182 summary = specify time interval for client sync
183 arg_info = required_arg
184 arg_type = uint32
185 typestr = count
186 [help]
187 Check the clock difference between the host running para_server and
188 the local host running para_audiod this many times before starting
189 any stream I/0. Set this to non-zero for non-local setups if the
190 clocks of these two hosts are not synchronized by ntp or similar.
191 [/help]