[xiph-cvs] cvs commit: ices/doc basic.html config.html faq.html index.html inputs.html intro.html style.css Makefile.am
Karl Heyes
karl at xiph.org
Mon Dec 29 15:49:25 PST 2003
karl 03/12/29 18:49:25
Added: doc basic.html config.html faq.html index.html
inputs.html intro.html style.css Makefile.am
Log:
Check in work for documentation
Revision Changes Path
1.1 ices/doc/basic.html
Index: basic.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>IceS v2.0 Documentation</title>
<link rel="STYLESHEET" type="text/css" href="style.css">
</head>
<body>
<div class=boxtest>
<h1>Basic setup</h1>
<table width="100%"><tr><td bgcolor="#007B79" height="10" align="center"></td></tr></table>
<br>
<h2>What does IceS require?</h2>
<p>
IceS v2 is not a graphical application, it's purpose is to stream
whatever it is given into a stream for feeding to the Icecast streaming
server. It does however require the following
</p>
<ul>
<li>libogg available at <a HREF="http://www.vorbis.com">www.vorbis.com</a>
<li>libvorbis available at <a HREF="http://www.vorbis.com">www.vorbis.com</a>
<li>libxml2 available at <a HREF="http://xmlsoft.org">xmlsoft</a>
<li>libshout 2 available at <a HREF="http://www.icecast.org">The Icecast site</a>
</ul>
<p>
Please note that in many cases, pre-built packages are split into two,
a run-time package, typically consisting of the actual run-time library
and a development package, consisting of the support files needed to
compile and link the application.
</p>
<p>
The following are optional
</p>
<ul>
<li>ALSA. driver and libs available at <a HREF="http://www.alsa-project.org">The ALSA site</a>
</ul>
<br>
<h2>What does IceS do ?</h2>
<p>
IceS reads audio data from an input and sends the audio data to one or
more files or icecast servers. Before it's actually sent out, some
processing maybe performed, typically resampling and/or downmixing to
produce streams suited to various bandwidth requirements.
</p>
<p>
The streams produced are Ogg Vorbis streams so while icecast 2 is
capable of streaming these streams, other streaming servers may not be.
<p>
<br>
<h2>What input can IceS handle?</h2>
<p>
Several inputs current exist, but some maybe dependant on certain
platforms or if certain drivers or libraries are available.
</p>
<ul>
<li>OSS - Open Sound System. Typically used on linux based systems to
get live input from a soundcard.
<li>ALSA - Advanced Linux Sound Architecture. Like OSS but with various
improvements for linux based systems.
<li>stdinpcm - Uses standard input to receive PCM audio.
<li>playlist - Uses a playlist to read audio files for processing.
<li>sun - like OSS, but for Sun Solaris, also works for OpenBSD
</ul>
<h2>How do you start IceS?</h2>
<p>
The configuration of IceS is done via an XML based config file. Which
you supply as an argument to the program at invocation time. For example
</p>
<BR>
ices /etc/ices.xml
<BR>
</div>
</body>
</html>
<p><p>1.1 ices/doc/config.html
Index: config.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>IceS v2.0 Documentation</title>
<link rel="STYLESHEET" type="text/css" href="style.css">
</head>
<body>
<div class=boxtest>
<h1>Config File</h1>
<table width="100%"><tr><td bgcolor="#007B79" height="10" align="center"></td></tr></table>
<h2>General layout</h2>
<pre>
<?xml version="1.0"?>
<ices>
general settings
stream section
</ices>
</pre>
<h2>General settings</h2>
<p>These apply to IceS as a whole. The example below gives a useful example to work to</p>
<pre>
<background>0<background>
<logpath>/var/log/ices<logpath>
<logfile>ices.log<logfile>
<loglevel>3<loglevel>
<consolelog>0<consolelog>
<pidfile>/var/log/ices/ices.pid<pidfile>
</pre>
<h4>background</h4>
<div class=indentedbox>
Set to 1 if you want IceS to put itself into the background
</div>
<h4>logpath</h4>
<div class=indentedbox>
A directory that can be written to by the user that IceS runs as. This
can be anywhere you want but as log files are created, write access to the
stated must be given.
</div>
<h4>logfile</h4>
<div class=indentedbox>
The name of the logfile created. On log re-opening the existing logfile is
renamed to <logfile>.1
</div>
<h4>loglevel</h4>
<div class=indentedbox>
A number that represents the amount of logging performed.
<ul>
<li>1 - Only error messages are logged
<li>2 - The above and warning messages are logged
<li>3 - The above and information messages are logged
<li>4 - The above and debug messages are logged
</ul>
</div>
<h4>consolelog</h4>
<div class=indentedbox>
A value of 1 will cause the log messages to appear on the console instead
of the log files. Setting this to 1 is generally discouraged as logs are
cycled and writing to screen can cause stalls in the application, which
is a problem for timing critical applications.
</div>
<h4>pidfile</h4>
<div class=indentedbox>
State a filename with path to be created at start time. This file will
then contain a single number which represents the process id of the
running IceS. This process id can then be used to signal the application
of certain events.
</div>
<h2>Stream section</h2>
<p>This describes how the input and outgoing streams are configured<p>
<pre>
<stream>
Metadata
Input
Instance
</stream>
</pre>
<h3>Metadata</h3>
<pre>
<metadata>
<name>My Stream</name>
<genre>Rock</genre>
<description>A short description of your stream</description>
</metadata>
</pre>
<p>
This section describes what metadata information is passed in the headers
at connection time to icecast. This applies to each instance defined within
the stream section but maybe overridden by a per-instance <metadata>
section
</p>
<h3>Input</h3>
<p>
This section deals with getting the audio data into IceS. There are a few
ways that can happen. Typically it's either from a playlist or via a soundcard
</p>
<p>
The layout is consistent between the different input modules. Within the
input section a module tag is needed to identify the module in question. The
rest are made up of param tags specific to the module. There can be several
param tags supplied to a module. Details of the module parameters are
shown later
</p>
<h3>Instance</h3>
<p>
Multiple instances can be defined to allow for multiple encodings, this
is useful for encoding the same input to multiple bitrates. Each instance
defines a particular set actions that occur on the passed in audio. Any
modifications to the input data is isolated to the instance.
</p>
<pre>
<instance>
hostname
port
password
mount
yp
resample
downmix
savefile
encode
</instance>
</pre>
<h4>hostname</h4>
<div class=indentedbox>
State the hostname of the icecast to contact, this can be a name or IP
address and can be ipv4 or ipv6 on systems that support IPv6. The default
is localhost.
</div>
<h4>port</h4>
<div class=indentedbox>
State the port to connect to, this will be the port icecast is listening on,
typically 8000 but can be any.
</div>
<h4>password</h4>
<div class=indentedbox>
For providing a stream, a username/password has to be provided, and must
match what icecast expects.
</div>
<h4>mount</h4>
<div class=indentedbox>
Mountpoints are used to identify a particular stream on a icecast server,
they must begin with / and for the sake of certain listening clients should
end in .ogg
</div>
<h4>yp</h4>
<div class=indentedbox>
By default streams will not be advertised on a YP server unless this is set,
and only then if the icecast if configured to talk to YP servers.
</div>
<h4>Resample</h4>
<pre>
<resample>
<in-rate>44100</in-rate>
<out-rate>22050</out-rate>
</resample>
</pre>
<div class=indentedbox>
<p>
When encoding or re-encoding, there is a point where you take PCM audio
and encode to Ogg Vorbis. In some situations a particular encoded stream may
require a lower samplerate to achieve a lower bitrate. The resample will
modifiy the audio data before it enters the encoder, but does not affect
other instances.
</p>
<p>
The most common values used are 48000, 44100, 22050 and 11025, and is
really only used to resample to a lower samplerate, going to a higher rate
serves no purpose within IceS
</p>
</div>
<h4>Downmix</h4>
<pre>
<downmix>1</downmix>
</pre>
<div class=indentedbox>
Some streams want to reduce the bitrate further, reducing the number of channels
used to just 1. Converting stereo to mono is fairly common and when this is set
to 1 the number of channels encoded is just 1. Like resample, this only affects
the one instance it's enabled in.
</div>
<h4>Savefile</h4>
<pre>
<savefile>/home/ices/dump/stream1.ogg</savefile>
</pre>
<div class=indentedbox>
Sometimes the stream transmitted wants to be saved to disk. This can be useful
for live recordings.
</div>
<h4>encode</h4>
<pre>
<encode>
<quality>0</quality>
<nominal-bitrate>65536</nominal-bitrate>
<maximum-bitrate>131072</maximum-bitrate>
<minimum-bitrate>-1</minimum-bitrate>
<managed>0</managed>
<samplerate>22050</samplerate>
<channels>1</channels>
</encode>
</pre>
<p>quality</p>
<div class=indentedbox>
State a quality measure for the encoder. The range goes from -1 to 10 where -1
is the lowest bitrate selection (default 3), and decimals can also be stated, so
for example 1.5 is valid. The actual bitrate used will depend on the tuning in
the vorbis libs, the samplerate, channels and the audio to encode. A quality of 0
at 44100hz and 2 channels is typically around the 64kbps mark.
</div>
<p>nominal-bitrate</p>
<div class=indentedbox>
State a bitrate that the encoder should try to keep to. This can be used as an
alternative to selecting quality.
</div>
<p>managed</p>
<div class=indentedbox>
State 1 to enable full bitrate management in the encoder. This is used with
nominal-bitrate, maximum-bitrate and minimum-bitrate to produce a stream with
more strict bitrate requirements. Enabling this currently leads to higher CPU
usage.
</div>
<p>maximum-bitrate</p>
<div class=indentedbox>
State bitrate in bits per second to limit max bandwidth used on a stream. Only
applies if managed is enabled.
</div>
<p>minimum-bitrate</p>
<div class=indentedbox>
State bitrate in bits per second to limit minimum bandwidth used on a stream.
Only applies if managed is enabled, this option has very little use so
shouldn't really be needed.
</div>
<p>samplerate</p>
<div class=indentedbox>
State the samplerate used for the encoding, this should be either the same as
the input or the result of the resample. Getting the samplerate wrong will
cause the audio to be represented wrong and therefore sound like it's running
too fast or too slow.
</div>
<p>channels</p>
<div class=indentedbox>
State the number of channels to use in the encoding. This will either be the
number of channels from the input or 1 due to downmix.
</div>
</div>
</body>
</html>
<p><p><p>1.1 ices/doc/faq.html
Index: faq.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>IceS v2.0 Documentation</title>
<link rel="STYLESHEET" type="text/css" href="style.css">
</head>
<body>
<div class=boxtest>
<h1>Frequently Asked Questions</h1>
<table width="100%"><tr><td bgcolor="#007B79" height="10" align="center"></td></tr></table>
<p>
This for those questions people have asked as it wasn't covered
in the documentation
</p>
<h4>Can ices play mp3 files</h4>
<div class=indentedbox>
<p>
No, there hasn't been much interest in handling mp3 with ices2. The
older version ices 0.3 maybe of interest in such cases.
</p>
</div>
<h4>How do I encode from Line-In</h4>
<div class=indentedbox>
<p>
IceS will read from the DSP on the soundcard, but where that gets the
audio from depends on the mixer settings. Use a utility like aumix to
see the settings and change the capture or recording device. Usually the
default is the Mic
<p>
</div>
<h4>When I start ices 2 it seems to get stuck not doing anything</h4>
<div class=indentedbox>
If you are using live input, check to see if something else is holding the
recording device (typically /dev/dsp) open. A good candidate is esd. What
happens is that the driver only allows one application to have the device
open at any one time, a second attempt will just block.
</div>
<h4>Ices reports a message about failing to set samplerate on live input</h4>
<div class=indentedbox>
Some hardware/drivers are limited in the settings they support. Sometimes
they only support one samplerate like 48khz. You have to experiment if the
documentation for the device is not specific.
</div>
</div>
</body>
</html>
<p><p>1.1 ices/doc/index.html
Index: index.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>IceS v2.0 Documentation</title>
<link rel="STYLESHEET" type="text/css" href="style.css">
</head>
<body>
<div class=boxtest>
<h1>IceS v2.0 Documentation<br><br>Table of Contents</h1>
<table width="100%"><tr><td bgcolor="#007B79" height="10" align="center"></td></tr></table>
<ul>
<li>Introduction
<li>Basic Setup
<li>Config File
<li>Input modules
<li>FAQ
</ul>
</div>
</body>
</html>
<p><p>1.1 ices/doc/inputs.html
Index: inputs.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>IceS v2.0 Documentation</title>
<link rel="STYLESHEET" type="text/css" href="style.css">
</head>
<body>
<div class=boxtest>
<h1>Available input modules</h1>
<table width="100%"><tr><td bgcolor="#007B79" height="10" align="center"></td></tr></table>
<p>
Several input modules are available, depending on the platform, drivers
and libraries available. The general layout is defined as
</p>
<pre>
<input>
<module>module name</module>
<param name="name1">value</param>
<param name="name2">value</param>
<param name="name3">value</param>
</input>
</pre>
<h2>Open Sound</h2>
<pre>
<module>oss</module>
<param name="rate">44100</param>
<param name="channels">2</param>
<param name="device">/dev/dsp</param>
<param name="metadata">1</param>
<param name="metadatafilename">/home/ices/metadata</param>
</pre>
<p>
This module is for reading live input from the Open Sound System drivers,
often found on linux systems but are available on others. This will read audio
from the DSP device in a format specified in the parameters provided.
</p>
<p>
The following can be used to configure the module
</p>
<h4>rate</h4>
<div class=indentedbox>
The value is in hertz, 44100 is the samplerate used on CD's, but some drivers
may prefer 48000 (DAT) or you may want to use something lower.
</div>
<h4>channels</h4>
<div class=indentedbox>
The number of channels to record. This is typically 2 for stereo or 1 for mono
</div>
<h4>device</h4>
<div class=indentedbox>
The device to read the audio samples from, it's typically /dev/dsp but
there maybe more than one card installed.
</div>
<h4>metadata</h4>
<div class=indentedbox>
Check for metadata arriving, if any are present then the data is marked
for an update. The metadata is in the form of tag=value, and while Ogg
Vorbis can handle any supplied tags, most players will only do anything
with artist and title.
</div>
<h4>metadatafilename</h4>
<div class=indentedbox>
<p>
The name of the file to open and read the metadata tags from, with this
parameter missing standard input is read. Using a file is often the better
approach. When using the file access the procedure is usually to populate
the file contents then send a SIGUSR1 to the IceS process.
</p>
<p>
The format of the file itself is a simple one comment per line format,
below is a trivial example of the file, other tags can be used but players
tend to only look for artist and title for displaying.
</p>
</div>
<pre>
artist=Queen
title=We Will Rock You
</pre>
<h2>ALSA</h2>
<p>
The Advanced Linux Sound Architecture (ALSA) is a completely different
sound system on linux but provides OSS compatability so the OSS driver
should work with it as well. To use ALSA natively a separate module is used
</p>
<pre>
<module>alsa</module>
<param name="rate">44100</param>
<param name="channels">2</param>
<param name="device">plughw:0,0</param>
<param name="metadata">1</param>
<param name="metadatafilename">/home/ices/metadata</param>
</pre>
The parameters to ALSA are the same for OSS, as it performs the same task,
ie captures audio from the DSP.
<h2>Sun</h2>
<p>
The Sun Solaris DSP input is similar to OSS. It allows for reading from
a soundcard on a Sun Solaris UNIX. OpenBSD also has a sound driver that
is similar to solaris and as such should be able to use this module.
</p>
<pre>
<module>sun</module>
</pre>
<p>
The parameters are the same as the OSS and ALSA modules.
</p>
<h2>StdinPCM</h2>
<pre>
<module>stdinpcm</module>
<param name="rate">44100</param>
<param name="channels">2</param>
<param name="metadata">1</param>
<param name="metadatafilename">/home/ices/metadata</param>
</pre>
<p>
This module should always be available, and as you can see the parameters
are almost the same except for the device. The PCM audio comes from the
standard input so it can be generated from some external app feeding into
a pipe.
</p>
<p>
As it's raw PCM being fed in, it's impossible to determine the samplerate
and channels so make sure the stated parameters match the incoming PCM or
the audio will be encoded wrongly.
</p>
<h2>Playlist</h2>
<p>
The playlist module is used to get audio from some pre-encoded Ogg
Vorbis files. The method of file selection is determined by the playlist
type. The current types are basic and script.
</p>
<h3>Basic</h3>
<pre>
<param name="type">basic</param>
<param name="file">/path/to/playlist</param>
<param name="random">0</param>
<param name="once">0</param>
<param name="restart-after-reread">1</param>
</pre>
<h4>file</h4>
<div class=indentedbox>
State a path to a file which will contain a list of Ogg Vorbis filenames
to play. One per line with lines beginning with '#' being treated as
comments. If a line has a single '-' then standard input is read, which
provides a way of getting some external Ogg Vorbis stream into ices.
</div>
<h4>random</h4>
<div class=indentedbox>
When set to 1, the playlist will be randomised when the playlist is
loaded. By default random is off
</div>
<h4>once</h4>
<div class=indentedbox>
When set to 1, the playlist is gone through once and then ends, this will
cause ices to exit. By default once is off.
</div>
<h4>restart-after-reread</h4>
<div class=indentedbox>
If the playlist is re-read mid way through, which may occur if the
playlist was updated then this will restart at the beginning of the
playlist. By default it's off.
</div>
<h3>Script</h3>
<pre>
<param name="type">basic</param>
<param name="program">/path/to/program</param>
</pre>
<h4>Program</h4>
<div class=indentedbox>
State a path to a program which when run will write to it's standard
output a path to an Ogg Vorbis file. The program can be anything from
an executable to a shell script as long as it starts, writes the
filename to it's standard output and then exits.
</div>
</div>
</body>
</html>
<p><p>1.1 ices/doc/intro.html
Index: intro.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>IceS v2.0 Documentation</title>
<link rel="STYLESHEET" type="text/css" href="style.css">
</head>
<body>
<div class=boxtest>
<h1>Introduction</h1>
<table width="100%"><tr><td bgcolor="#007B79" height="10" align="center"></td></tr></table>
<br> <br> <br>
<h2>What is IceS ?</h2>
<p>
IceS is a source client for a streaming server. The purpose of this client is to
provide an audio stream to a streaming server such that one or more listeners can
access the stream. With this layout, this source client can be situated remotely
from the icecast server.
</p>
<p>
The primary example of a streaming server used is Icecast 2, although others could
be used if certain conditions are met.</p>
<br><br>
<h2>What platforms are supported ?</h2>
<p>
Currently the following Unix platforms are supported:
</p>
<ul>
<li>Linux (Most flavors including Redhat and Debian)
<li>FreeBSD
<li>OpenBSD
<li>Solaris
</ul>
<br> <br>
<h2>Where do I go for questions?</h2>
<p>
IceS is developed and maintained by the same people involved with Icecast 2.
There are several ways to contact the development team
</p>
<h3>Best Ways</h3>
<ul>
<li>Icecast mailing list http://www.xiph.org/archives
<li>Icecast Developers mailing list http://www.xiph.org/archives
<li>Icecast IRC chat room - irc.freenode.net : #icecast
</ul>
<h3>Alternate Ways</h3>
<ul>
<li><a href="mailto:team at icecast.org">team at icecast.org</a>
</ul>
</div>
</body>
</html>
<p><p>1.1 ices/doc/style.css
Index: style.css
===================================================================
.ahem { display: none }
body {
font-family: "Lucida Grande", Verdana, Geneva, Lucida, sans-serif;
background: #000000;
color: #323232;
}
a {
font-weight: bold;
text-decoration: none;
}
a:link { color: #ff0; }
a:visited { color: #cc3; }
a:hover { color: #f00; }
code,pre {
font-size:90%;
color:#ffffff;
font-family:"Courier New",monospace;
background:#777777;
padding:0 0.5em
}
td {
color:#ffffff;
}
pre { padding:0.5em }
blockquote { margin:0.5em }
blockquote p { margin:0 }
.width300 { width:300px; background:red }
.width400 { width:400px; background:blue }
p.ruletest { color:red }
div.boxtest {
border:10px solid;
padding:30px;
background: #555555;
color:#ffffff;
}
div.smallbox{
border:2px solid;
padding:40px;
background: #ffc;
width:600px;
color: #FFFFFF;
}
div.indentedbox {
border:0px solid;
padding:10px;
background: #779;
}
<p>div.content {
border:20px solid;
padding:30px;
background: #ffc;
}
div.content {
width:400px;
voice-family: "\"}\"";
voice-family:inherit;
width:300px;
}
/* CSS1 UAs should see and use 2nd width */
html>body .content { width:300px }
p.ruletest { color: blue }
<p><p><p><p><p>1.1 ices/doc/Makefile.am
Index: Makefile.am
===================================================================
## Process this file with automake to produce Makefile.in
AUTOMAKE_OPTIONS = foreign
docdir = $(datadir)/doc/$(PACKAGE)-$(VERSION)
doc_DATA = basic.html config.html faq.html index.html inputs.html intro.html style.css
EXTRA_DIST = $(doc_DATA)
<p><p>--- >8 ----
List archives: http://www.xiph.org/archives/
Ogg project homepage: http://www.xiph.org/ogg/
To unsubscribe from this list, send a message to 'cvs-request at xiph.org'
containing only the word 'unsubscribe' in the body. No subject is needed.
Unsubscribe messages sent to the list will be ignored/filtered.
More information about the commits
mailing list