| 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 |
<input> |
| 19 |
<module>module name</module> |
| 20 |
<param name="name1">value</param> |
| 21 |
<param name="name2">value</param> |
| 22 |
<param name="name3">value</param> |
| 23 |
</input> |
| 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 |
<module>oss</module> |
| 33 |
<param name="rate">44100</param> |
| 34 |
<param name="channels">2</param> |
| 35 |
<param name="device">/dev/dsp</param> |
| 36 |
<param name="metadata">1</param> |
| 37 |
<param name="metadatafilename">/home/ices/metadata</param> |
| 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 |
<module>alsa</module> |
| 96 |
<param name="rate">44100</param> |
| 97 |
<param name="channels">2</param> |
| 98 |
<param name="device">hw:0,0</param> |
| 99 |
<param name="periods">2</param> |
| 100 |
<param name="buffer-time">500</param> |
| 101 |
<param name="metadata">1</param> |
| 102 |
<param name="metadatafilename">/home/ices/metadata</param> |
| 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 |
<module>sun</module> |
| 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 |
<module>stdinpcm</module> |
| 136 |
<param name="rate">44100</param> |
| 137 |
<param name="channels">2</param> |
| 138 |
<param name="metadata">1</param> |
| 139 |
<param name="metadatafilename">/home/ices/metadata</param> |
| 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 |
<param name="type">basic</param> |
| 166 |
<param name="file">/path/to/playlist</param> |
| 167 |
<param name="random">0</param> |
| 168 |
<param name="once">0</param> |
| 169 |
<param name="restart-after-reread">1</param> |
| 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 |
<param name="type">script</param> |
| 213 |
<param name="program">/path/to/program</param> |
| 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 |
<module>roar</module> |
| 232 |
<param name="rate">44100</param> |
| 233 |
<param name="channels">stereo</param> |
| 234 |
<param name="codec">ogg_vorbis</param> |
| 235 |
<param name="aiprofile">default</param> |
| 236 |
<param name="dir">monitor</param> |
| 237 |
<param name="device">/tmp/roar</param> |
| 238 |
<param name="server">home::</param> |
| 239 |
<param name="metadata">file</param> |
| 240 |
<param name="metadatafilename">/home/ices/metadata</param> |
| 241 |
<param name="plugin">helloworld text="Hello ices2 users!"</param> |
| 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> |