Debian Codegraph @

doc/inputs.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2
3 <html>
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
6 <title>IceS v2.0 Documentation</title>
7 <link rel="STYLESHEET" type="text/css" href="style.css">
8 </head>
9 <body>
10 <div class=boxtest>
11 <h1>Available input modules</h1>
12 <table width="100%"><tr><td bgcolor="#007B79" height="10" align="center"></td></tr></table>
13 <p>
14 Several input modules are available, depending on the platform, drivers
15 and libraries available. The general layout is defined as
16 </p>
17 <pre>
18 &lt;input&gt;
19 &lt;module&gt;module name&lt;/module&gt;
20 &lt;param name="name1"&gt;value&lt;/param&gt;
21 &lt;param name="name2"&gt;value&lt;/param&gt;
22 &lt;param name="name3"&gt;value&lt;/param&gt;
23 &lt;/input&gt;
24 </pre>
25 <p>
26 For live input you may want to look into various resources on the web for
27 information on sound input. You may find that ALSA for instance supports
28 a particular soundcard better than the Open Sound System.
29 </p>
30 <h2>Open Sound</h2>
31 <pre>
32 &lt;module&gt;oss&lt;/module&gt;
33 &lt;param name="rate"&gt;44100&lt;/param&gt;
34 &lt;param name="channels"&gt;2&lt;/param&gt;
35 &lt;param name="device"&gt;/dev/dsp&lt;/param&gt;
36 &lt;param name="metadata"&gt;1&lt;/param&gt;
37 &lt;param name="metadatafilename"&gt;/home/ices/metadata&lt;/param&gt;
38 </pre>
39 <p>
40 This module is for reading live input from the Open Sound System drivers,
41 often found on linux systems but are available on others. This will read audio
42 from the DSP device in a format specified in the parameters provided.
43 </p>
44 <p>
45 The following can be used to configure the module
46 </p>
47 <h4>rate</h4>
48 <div class=indentedbox>
49 The value is in hertz, 44100 is the samplerate used on CD's, but some drivers
50 may prefer 48000 (DAT) or you may want to use something lower.
51 </div>
52 <h4>channels</h4>
53 <div class=indentedbox>
54 The number of channels to record. This is typically 2 for stereo or 1 for mono
55 </div>
56 <h4>device</h4>
57 <div class=indentedbox>
58 The device to read the audio samples from, it's typically /dev/dsp but
59 there maybe more than one card installed.
60 </div>
61 <h4>metadata</h4>
62 <div class=indentedbox>
63 Check for metadata arriving, if any are present then the data is marked
64 for an update. The metadata is in the form of tag=value, and while Ogg
65 Vorbis can handle any supplied tags, most players will only do anything
66 with artist and title.
67 </div>
68 <h4>metadatafilename</h4>
69 <div class=indentedbox>
70 <p>
71 The name of the file to open and read the metadata tags from, with this
72 parameter missing standard input is read. Using a file is often the better
73 approach. When using the file access the procedure is usually to populate
74 the file contents then send a SIGUSR1 to the IceS process.
75 </p>
76 <p>
77 The format of the file itself is a simple one comment per line format,
78 below is a trivial example of the file, other tags can be used but players
79 tend to only look for artist and title for displaying. The data must be in
80 UTF-8 (this is not checked by ices, however).
81 </p>
82 </div>
83 <pre>
84 artist=Queen
85 title=We Will Rock You
86 </pre>
87
88 <h2>ALSA</h2>
89 <p>
90 The Advanced Linux Sound Architecture (ALSA) is a completely different
91 sound system on linux but provides OSS compatability so the OSS driver
92 should work with it as well. To use ALSA natively a separate module is used
93 </p>
94 <pre>
95 &lt;module&gt;alsa&lt;/module&gt;
96 &lt;param name="rate"&gt;44100&lt;/param&gt;
97 &lt;param name="channels"&gt;2&lt;/param&gt;
98 &lt;param name="device"&gt;hw:0,0&lt;/param&gt;
99 &lt;param name="periods"&gt;2&lt;/param&gt;
100 &lt;param name="buffer-time"&gt;500&lt;/param&gt;
101 &lt;param name="metadata"&gt;1&lt;/param&gt;
102 &lt;param name="metadatafilename"&gt;/home/ices/metadata&lt;/param&gt;
103 </pre>
104 The parameters to ALSA are mostly the same for OSS, as it performs the same
105 task, ie captures audio from the DSP.
106
107 <h4>device</h4>
108 <div class=indentedbox>
109 <p>This is the device name as used in ALSA. This can be a physical device
110 as in the case of "hw:0,0" or a virtual device like one with dsnoop.</p>
111 </div>
112 <h4>periods</h4>
113 <div class=indentedbox>
114 <p>This specifies how many interrupts will be generated (default: 2)</p>
115 </div>
116 <h4>buffer-time</h4>
117 <div class=indentedbox>
118 <p>The size of the buffer measured in mS (default 500)</p>
119 </div>
120
121 <h2>Sun</h2>
122 <p>
123 The Sun Solaris DSP input is similar to OSS. It allows for reading from
124 a soundcard on a Sun Solaris UNIX. OpenBSD also has a sound driver that
125 is similar to solaris and as such should be able to use this module.
126 </p>
127 <pre>
128 &lt;module&gt;sun&lt;/module&gt;
129 </pre>
130 <p>
131 The parameters are the same as the OSS and ALSA modules.
132 </p>
133 <h2>StdinPCM</h2>
134 <pre>
135 &lt;module&gt;stdinpcm&lt;/module&gt;
136 &lt;param name="rate"&gt;44100&lt;/param&gt;
137 &lt;param name="channels"&gt;2&lt;/param&gt;
138 &lt;param name="metadata"&gt;1&lt;/param&gt;
139 &lt;param name="metadatafilename"&gt;/home/ices/metadata&lt;/param&gt;
140 </pre>
141 <p>
142 This module should always be available, and as you can see the parameters
143 are almost the same except for the device. The PCM audio comes from the
144 standard input so it can be generated from some external application feeding
145 into a pipe.
146 </p>
147 <p>
148 As it's raw PCM being fed in, it's impossible to determine the samplerate
149 and channels so make sure the stated parameters match the incoming PCM or
150 the audio will be encoded wrongly.
151 </p>
152
153 <h2>Playlist</h2>
154 <p>
155 The playlist module is used to get audio from some pre-encoded Ogg
156 Vorbis files. IceS currently checks to see if the same file gets
157 played in succession and skips it, this means that having a playlist
158 repeat with only one Ogg file listed won't work.
159 The method of file selection is determined by the playlist
160 type. The current types are basic and script.
161 </p>
162
163 <h3>Basic / M3U / VCLT</h3>
164 <pre>
165 &lt;param name="type"&gt;basic&lt;/param&gt;
166 &lt;param name="file"&gt;/path/to/playlist&lt;/param&gt;
167 &lt;param name="random"&gt;0&lt;/param&gt;
168 &lt;param name="once"&gt;0&lt;/param&gt;
169 &lt;param name="restart-after-reread"&gt;1&lt;/param&gt;
170 </pre>
171 <h4>type</h4>
172 <div class=indentedbox>
173 This is the file format of the playlist.
174 Currently "basic", "m3u" and "vclt" are supported.
175 </div>
176 <h4>file</h4>
177 <div class=indentedbox>
178 State a path to a file which will contain a list of Ogg Vorbis filenames
179 to play.
180 The format of this file depends on the setting of "type".
181 For type "basic" the format is
182 one filename per line with lines beginning with '#' being treated as
183 comments. If a line has a single '-' then standard input is read, which
184 provides a way of getting some external Ogg Vorbis stream into ices.
185 </div>
186 <h4>format</h4>
187 <div class=indentedbox>
188 This sets the used codec for input files.
189 Use "ogg" for generic Ogg handling. In this mode codec specific features
190 will not available but codec is detected on the fly.
191 Currently "vorbis" and "ogg" are supported.
192 By default "vorbis" is used.
193 </div>
194 <h4>random</h4>
195 <div class=indentedbox>
196 When set to 1, the playlist will be randomised when the playlist is
197 loaded. By default random is off
198 </div>
199 <h4>once</h4>
200 <div class=indentedbox>
201 When set to 1, the playlist is gone through once and then ends, this will
202 cause ices to exit. By default once is off.
203 </div>
204 <h4>restart-after-reread</h4>
205 <div class=indentedbox>
206 If the playlist is re-read mid way through, which may occur if the
207 playlist was updated then this will restart at the beginning of the
208 playlist. By default it's off.
209 </div>
210 <h3>Script</h3>
211 <pre>
212 &lt;param name="type"&gt;script&lt;/param&gt;
213 &lt;param name="program"&gt;/path/to/program&lt;/param&gt;
214 </pre>
215 <h4>Program</h4>
216 <div class=indentedbox>
217 State a path to a program which when run will write to it's standard
218 output a path to an Ogg Vorbis file. The program can be anything from
219 an executable to a shell script as long as it starts, writes the
220 filename to it's standard output and then exits.
221 </div>
222
223 <h2>RoarAudio</h2>
224 <p>
225 The RoarAudio module is used to get audio from a RoarAudio Sound Server.
226 This module supports getting both already encoded and raw audio from the
227 sound server. It also allows meta data to be read from the sound server
228 or an file the same way the Open Sound module does.
229 </p>
230 <pre>
231 &lt;module&gt;roar&lt;/module&gt;
232 &lt;param name="rate"&gt;44100&lt;/param&gt;
233 &lt;param name="channels"&gt;stereo&lt;/param&gt;
234 &lt;param name="codec"&gt;ogg_vorbis&lt;/param&gt;
235 &lt;param name="aiprofile"&gt;default&lt;/param&gt;
236 &lt;param name="dir"&gt;monitor&lt;/param&gt;
237 &lt;param name="device"&gt;/tmp/roar&lt;/param&gt;
238 &lt;param name="server"&gt;home::&lt;/param&gt;
239 &lt;param name="metadata"&gt;file&lt;/param&gt;
240 &lt;param name="metadatafilename"&gt;/home/ices/metadata&lt;/param&gt;
241 &lt;param name="plugin"&gt;helloworld text="Hello ices2 users!"&lt;/param&gt;
242 </pre>
243
244 <p>
245 The parameters are similar to the of the other modules.
246 For the audio parameters (rate, channels, codec) the values from libroar's
247 audio info profile "default" are used (normally 44100, 2, pcm_s).
248 The following can be used to configure the module:
249 </p>
250
251 <h4>rate</h4>
252 <div class=indentedbox>
253 The value is in hertz, 44100 is the samplerate used on CD's, but some drivers
254 may prefer 48000 (DAT) or you may want to use something lower.
255 This can also be a symbolic name as supported by libroar.
256 Examples include "cd" and "dat".
257 </div>
258 <h4>channels</h4>
259 <div class=indentedbox>
260 The number of channels to record. This is typically 2 for stereo or 1 for mono.
261 This can also be a symbolic name as supported by libroar.
262 Examples include "stereo" and "mono".
263 </div>
264 <h4>codec</h4>
265 <div class=indentedbox>
266 The codec to read the audio data in from the sound server.
267 Currently the values "default", "pcm_s", "pcm_s_le", "pcm_s_be",
268 "ogg_vorbis", "ogg_opus", "ogg_speex", "ogg_flac" and "ogg_general" are supported.
269 "default" is an alias for "pcm_s" which itself is an alias to "pcm_s_le" or "pcm_s_be" depending
270 on the native byte order of the system. "ogg_general" should not be used.
271 </div>
272 <h4>aiprofile</h4>
273 <div class=indentedbox>
274 Use the given audio info profile from libroar.
275 By default the profile "default" is used.
276 If mixed with rate, channels or codec options the last one set wins.
277 </div>
278
279 <h4>dir</h4>
280 <div class=indentedbox>
281 This is the stream direction. Currently "monitor" and "record" are supported.
282 If set to "monitor" ices2 will stream a copy of the audio played back by
283 sound server to icecast. If set to "record" it will read from soundcard input (e.g. mic).
284 Defaults to "monitor".
285 </div>
286
287 <h4>device, server</h4>
288 <div class=indentedbox>
289 This sets the location of the sound server. Both parameters are equal.
290 The location can be in any form libroar understands.
291 Common values are server addresses in form "/path/to/sock" for UNIX sockets,
292 "hostname" for IPv4 and IPv6 hosts and "node::" for DECnet nodes.
293 A full description of this can be found in the RoarAudio documentation.
294 Defaults to the list of default locations (auto detection) libroar has.
295 </div>
296
297 <h4>metadata</h4>
298 <div class=indentedbox>
299 This is the meta data source. Currently supported values are "none", "file" and "stream".
300 The values "none" and "file" are the same as for the Open Sound module the values "0" and "1".
301 The value "stream" requests meta data from the sound server.
302 Defaults to "stream".
303 </div>
304
305 <h4>metadatafilename</h4>
306 <div class=indentedbox>
307 This setting is the same as "metadatafilename" for the Open Sound module.
308 It is only active when "metadata" is set to "file".
309 </div>
310
311 <h4>plugin</h4>
312 <div class=indentedbox>
313 This setting loads a plugin. The plugin name my be followed by parameters
314 to be passed to the plugin. Between the plugin name and the parameters needs to be a space.
315 Normal libroar plugin parameter parsing rules apply
316 (keys and values separated by "=", key-value-pairs separated by ",").
317 </div>
318
319 </div>
320 </body>
321 </html>