[xiph-commits] r8982 - in icecast/branches/kh/ices: conf doc
karl at motherfish-iii.xiph.org
karl at motherfish-iii.xiph.org
Thu Feb 24 13:17:18 PST 2005
Author: karl
Date: 2005-02-24 13:17:13 -0800 (Thu, 24 Feb 2005)
New Revision: 8982
Added:
icecast/branches/kh/ices/conf/ices-oss.xml
Removed:
icecast/branches/kh/ices/conf/ices-live.xml
Modified:
icecast/branches/kh/ices/doc/basic.html
icecast/branches/kh/ices/doc/config.html
Log:
update docs
Deleted: icecast/branches/kh/ices/conf/ices-live.xml
===================================================================
--- icecast/branches/kh/ices/conf/ices-live.xml 2005-02-24 16:48:43 UTC (rev 8981)
+++ icecast/branches/kh/ices/conf/ices-live.xml 2005-02-24 21:17:13 UTC (rev 8982)
@@ -1,114 +0,0 @@
-<?xml version="1.0"?>
-<ices>
-
- <background>0</background> <!-- run in background? (unimplemented) -->
- <realtime>0</realtime> <!-- disable realtime, enabled by default -->
- <user>ices</user> <!-- user to change to when started as root -->
- <logpath>/tmp</logpath> <!-- where log goes. -->
- <logsize>2048</logsize> <!-- the size the log has to get to before cycling -->
- <logfile>ices.log</logfile>
- <loglevel>4</loglevel> <!-- 1=error,2=warn,3=info,4=debug -->
- <consolelog>0</consolelog> <!-- logfile is ignored if this is set to 1 -->
- <pidfile>/var/ices/ices.pid</pidfile> <!-- file to write process id to -->
-
- <stream>
- <!-- global settings for all streams - optional-->
- <name>Example stream name</name>
- <genre>Example genre</genre>
- <description>A short description of your stream</description>
-
- <!-- input module -->
- <!-- This example uses the 'oss' module. It takes input from the -->
- <!-- oss audio device (i.e. line-in), and processes it for live -->
- <!-- encoding. If metadatafilename is set then at start and on USR1 -->
- <!-- the file is read and the comments are added into the stream -->
- <input>
- <module>oss</module>
- <param name="rate">44100</param> <!-- samplerate -->
- <param name="channels">2</param> <!-- number of channels -->
- <param name="device">/dev/dsp</param> <!-- audio device -->
- <param name="metadatafilename">metadata</param>
- </input>
- <!-- more input section can be stated here, and can be switched manually -->
- <!-- by USR2 or whenever the previous input finishes. The order is -->
- <!-- dictated in here and loops aronnd to the first one listed -->
-
- <!-- A runner is a thread that applies the input data to each outgoing -->
- <!-- stream instance defined within it. Multiple runners can be stated -->
- <!-- for use on multiple processors. -->
- <runner>
- <!-- stream instance, used to associate a set of encoding settings -->
- <!-- with output. At the moment 2 outputs can be used, shout and -->
- <!-- savestream. Any number or combination of these outputs can be used -->
- <instance>
- <!-- per instance setting, overriding the global settings - optional-->
- <name>test transmission</name>
- <genre>various</genre>
- <description>low bandwidth stream</description>
-
- <!-- You define hostname and port for the server here, along with -->
- <!-- the source password and mountpoint. If you miss them out -->
- <!-- then any processing will still occur but it won't be sent to -->
- <!-- icecast, useful for encode to file only -->
- <shout>
- <hostname>localhost</hostname>
- <port>8000</port>
- <password>hackme</password>
- <mount>/example1.ogg</mount>
- </shout>
-
- <!-- resample input to the stated samplerate - optional
- the input can change samplerate so this can be used to fix it
- at a certain rate -->
- <resample>
- <out-rate>22050</out-rate>
- </resample>
-
- <!-- stereo->mono downmixing, enabled by setting this to 1 - optional -->
- <downmix>1</downmix>
-
- <!-- Live encoding/reencoding: -->
- <encode>
- <quality>0</quality>
- <!-- usual options for encoding, except from samplerate and chanels -->
- <!-- they are set from input/resample/downmix setting -->
- </encode>
- </instance>
-
- <!-- more instances can be defined -->
- <instance>
- <!-- This instance just writes to file, no connection to icecast -->
- <encode>
- <quality>0</quality>
- </encode>
-
- <!-- writing of files, all but the filename have the defaults-->
- <!-- listed -->
- <savestream>
- <!-- filename expansion, look at strftime for details -->
- <filename>/home/ices/saved-file/%X/stream-%M.ogg</filename>
- <!-- file creation mask, eg 0644 -->
- <fmask>0600</fmask>
- <!-- directory creation mask -->
- <dmask>0700</dmask>
- <!-- seconds to record, 0 disables, defaults to 1 hour -->
- <duration>7200</duration>
- <!-- switch file on stream change -->
- <on-metadata>1</on-metadata>
- <!-- Normally on switchover from a duration timeout, the
- timecode is reset, needed for some players, but disabling
- this prevents modification -->
- <reset-time>0</reset-time>
- </savestream>
-
- </instance>
-
- </runner>
-
- <runner>
- ....
- </runner>
-
- </stream>
-</ices>
-
Added: icecast/branches/kh/ices/conf/ices-oss.xml
===================================================================
--- icecast/branches/kh/ices/conf/ices-oss.xml 2005-02-24 16:48:43 UTC (rev 8981)
+++ icecast/branches/kh/ices/conf/ices-oss.xml 2005-02-24 21:17:13 UTC (rev 8982)
@@ -0,0 +1,116 @@
+<?xml version="1.0"?>
+<ices>
+
+ <background>0</background> <!-- run in background? (unimplemented) -->
+ <realtime>0</realtime> <!-- disable realtime, enabled by default -->
+ <user>ices</user> <!-- user to change to when started as root -->
+ <logpath>/tmp</logpath> <!-- where log goes. -->
+ <logsize>2048</logsize> <!-- the size the log has to get to before cycling -->
+ <logfile>ices.log</logfile>
+ <loglevel>4</loglevel> <!-- 1=error,2=warn,3=info,4=debug -->
+ <consolelog>0</consolelog> <!-- logfile is ignored if this is set to 1 -->
+ <pidfile>/var/ices/ices.pid</pidfile> <!-- file to write process id to -->
+
+ <stream>
+ <!-- global settings for all streams - optional-->
+ <name>Example stream name</name>
+ <genre>Example genre</genre>
+ <description>A short description of your stream</description>
+
+ <!-- input module -->
+ <!-- This example uses the 'oss' module. It takes input from the -->
+ <!-- oss audio device (i.e. line-in), and processes it for live -->
+ <!-- encoding. If metadatafilename is set then at start and on USR1 -->
+ <!-- the file is read and the comments are added into the stream -->
+ <input>
+ <module>oss</module>
+ <param name="rate">44100</param> <!-- samplerate -->
+ <param name="channels">2</param> <!-- number of channels -->
+ <param name="device">/dev/dsp</param> <!-- audio device -->
+ <param name="metadatafilename">metadata</param>
+ </input>
+ <!-- more input section can be stated here, and can be switched manually -->
+ <!-- by USR2 or whenever the previous input finishes. The order is -->
+ <!-- dictated in here and loops aronnd to the first one listed -->
+
+ <!-- A runner is a thread that applies the input data to each outgoing -->
+ <!-- stream instance defined within it. Multiple runners can be stated -->
+ <!-- for use on multiple processors. -->
+ <runner>
+ <!-- stream instance, used to associate a set of encoding settings -->
+ <!-- with output. At the moment 2 outputs can be used, shout and -->
+ <!-- savestream. Any number or combination of these outputs can be used -->
+ <instance>
+ <!-- per instance setting, overriding the global settings - optional-->
+ <name>test transmission</name>
+ <genre>various</genre>
+ <description>low bandwidth stream</description>
+
+ <!-- You define hostname and port for the server here, along with -->
+ <!-- the source password and mountpoint. If you miss them out -->
+ <!-- then any processing will still occur but it won't be sent to -->
+ <!-- icecast, useful for encode to file only -->
+ <shout>
+ <hostname>localhost</hostname>
+ <port>8000</port>
+ <password>hackme</password>
+ <mount>/example1.ogg</mount>
+ </shout>
+
+ <!-- resample input to the stated samplerate - optional
+ the input can change samplerate so this can be used to fix it
+ at a certain rate -->
+ <resample>
+ <out-rate>22050</out-rate>
+ </resample>
+
+ <!-- stereo->mono downmixing, enabled by setting this to 1 - optional -->
+ <downmix>1</downmix>
+
+ <!-- Live encoding/reencoding: -->
+ <encode>
+ <quality>0</quality>
+ <!-- usual options for encoding, except from samplerate and chanels -->
+ <!-- they are set from input/resample/downmix setting -->
+ </encode>
+ </instance>
+
+ <!-- more instances can be defined -->
+ <instance>
+ <!-- This instance just writes to file, no connection to icecast -->
+ <encode>
+ <quality>0</quality>
+ </encode>
+
+ <!-- writing of files, all but the filename have the defaults-->
+ <!-- listed -->
+ <savestream>
+ <!-- filename expansion, look at strftime for details -->
+ <filename>/home/ices/saved-file/%X/stream-%M.ogg</filename>
+ <!-- file creation mask, eg 0644 -->
+ <fmask>0600</fmask>
+ <!-- directory creation mask -->
+ <dmask>0700</dmask>
+ <!-- seconds to record, 0 disables, defaults to 1 hour -->
+ <duration>7200</duration>
+ <!-- switch file on stream change -->
+ <on-metadata>1</on-metadata>
+ <!-- Normally on switchover from a duration timeout, the
+ timecode is reset, needed for some players, but disabling
+ this prevents modification -->
+ <reset-time>0</reset-time>
+ </savestream>
+
+ </instance>
+
+ </runner>
+
+ <!-- define another thread for processing streams
+ <runner>
+ ....
+ </runner>
+ -->
+
+ </stream>
+</ices>
+
Modified: icecast/branches/kh/ices/doc/basic.html
===================================================================
--- icecast/branches/kh/ices/doc/basic.html 2005-02-24 16:48:43 UTC (rev 8981)
+++ icecast/branches/kh/ices/doc/basic.html 2005-02-24 21:17:13 UTC (rev 8982)
@@ -20,7 +20,7 @@
<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>
+ <li>libshout 2.1 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,
@@ -33,6 +33,7 @@
</p>
<ul>
<li>ALSA. driver and libs available at <a HREF="http://www.alsa-project.org">The ALSA site</a>
+ <li>JACK. server and libs available at <a HREF="http://jackit.sourceforge.net/">The JACK site</a>
</ul>
<br>
<h2>What does IceS do ?</h2>
@@ -57,6 +58,7 @@
get live input from a soundcard.
<li>ALSA - Advanced Linux Sound Architecture. Like OSS but with various
improvements for linux based systems.
+ <li>JACK - Get PCM from a JACK server.
<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
Modified: icecast/branches/kh/ices/doc/config.html
===================================================================
--- icecast/branches/kh/ices/doc/config.html 2005-02-24 16:48:43 UTC (rev 8981)
+++ icecast/branches/kh/ices/doc/config.html 2005-02-24 21:17:13 UTC (rev 8982)
@@ -2,7 +2,7 @@
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
- <title>IceS v2.0 Documentation</title>
+ <title>IceS v2.0-kh Documentation</title>
<link rel="STYLESHEET" type="text/css" href="style.css">
</head>
<body>
@@ -10,14 +10,30 @@
<h1>Config File</h1>
<table width="100%"><tr><td bgcolor="#007B79" height="10" align="center"></td></tr></table>
<p>The ices 2 configuration file is in XML format, which is described in detail below.
- There are 2 sample XML files provided which show the two main ways ices is used.<p>
+ There are a few sample XML files provided which show the main ways ices is used.<p>
</p>
+ A live audio feed often comes from a soundcard but may come via a server such as JACK
<ul>
- <li><a href="ices-live.xml">live</a> audio streaming, takes audio from the soundcard which can
- be captured from say the Mic, line-In, or CD.
- <li><a href="ices-playlist.xml">playlist</a> audio streaming, takes pre-encoded Ogg Vorbis files
- and either sends them as-is or re-encodes them to different settings</p>
+ <li>ices-oss.xml
+ <li>ices-alsa.xml
+ <li>ices-jack.xml
</ul>
+ <p>Other possibilities usually involve a playlist, but you may want to invoke a separate
+ program which can produce PCM via a pipe into ices.</p>
+ <ul>
+ <li>ices-pcm.xml
+ <li>ices-playlist.xml
+ </ul>
+ <p>The ices-switch.xml is an example of how you can define a series of inputs. You could
+ use this to switch between a live session and a pre-recorded playlist if it require. All
+ available inputs can be used with this mechanism, but only 1 can be used at any one time.
+ A switch between inputs can occur if an input stops or manual intervention occurs with a
+ USR2 signal.
+ </p>
+ <p>An unusual one is the ices-fixit.xml, which is basically a playlist but just outputs
+ to files and the timer is disabled so that it runs very quickly. This can be used to
+ split files or maybe even repair some Ogg Vorbis files.</p>
+
<h2>General layout</h2>
<pre>
<?xml version="1.0"?>
@@ -50,12 +66,14 @@
<h4>logfile</h4>
<div class=indentedbox>
The name of the logfile created. On log re-opening the existing logfile is
- renamed to <logfile>.1
+ renamed to <logfile>.old. In the case of HUP, renaming is not done as
+ it is often moved/deleted before the signal is sent.
</div>
<h4>logsize</h4>
<div class=indentedbox>
When the log file reaches this size (in kilobytes) then the log file will
- be cycled (the default is 2Meg)
+ be cycled (the default is 2Meg). Sending the HUP signal reopens the log
+ which is another way for logs to be cycled.
</div>
<h4>loglevel</h4>
<div class=indentedbox>
@@ -85,28 +103,26 @@
<p>This describes how the input and outgoing streams are configured.<p>
<pre>
<stream>
- Metadata
- Input
- Instance
+ Global metadata
+ Inputs
+ Runners
</stream>
</pre>
- <h3>Metadata</h3>
+ <h3>Global metadata</h3>
<pre>
- <metadata>
<name>My Stream</name>
<genre>Rock</genre>
<description>A short description of your stream</description>
<url>http://mysite.org</url>
- </metadata>
</pre>
- <p>
+ <div class=indentedbox>
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>
+ </div>
+ <h3>Inputs</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.
@@ -118,102 +134,91 @@
param tags supplied to a module. Details of the module parameters are
shown later.
</p>
+ <h3>Runners</h3>
+ <p>A runner is a thread. You need at least 1, but each runner can process
+ several encodings. As encoding is a CPU intensive task, grouping these
+ into the same runner can help the load on the machine, especially if your
+ machine does other work. Often only 1 runner is needed but you could say
+ that the general rule of thumb is 1 runner per CPU.
+ </p>
+ <p>While a runner may indicate the CPU usage, the actual encoding of the
+ stream is placed within an <instance>. More than 1 instance can be
+ defined within each runner.
+ </p>
+ <pre>
+ <runner>
+ <instance>
+ ...
+ </instance>
+
+ <instance>
+ ...
+ </instance>
+ </runner>
+ </pre>
<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.
+ Each instance defines 1 encoded stream. This means that for multiple
+ bitrate/quality streams, a separate <instance> is needed for each
+ bitrate. Each instance defines a particular set actions that occur on the
+ passed in audio. Any modifications to the input data are isolated to the
+ instance.
</p>
<pre>
- <instance>
- hostname
- port
- password
- mount
- yp
- resample
- downmix
- savefile
- encode
- </instance>
+ <instance>
+ name
+ description
+ genre
+ url
+ resample
+ downmix
+ encode
+ savefile
+ shout
+ </instance>
</pre>
- <h4>hostname</h4>
+ <h4>name, description, genre and url</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 with the .ogg extension.
- </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>
+ These are exactly the same as the ones defined in the global metadata.
+ In here they override the global settings, so often these are not needed
+ </div>
+
+ <h4>Resample</h4>
+ <pre>
+ <resample>
+ <out-rate>22050</out-rate>
+ </resample>
+ </pre>
+ <div class=indentedbox>
+ This is used to force the samples coming from the input to be at a specific
+ samplerate, this can be useful if the input can be varied or if the input can only
+ do 1 samplerate like 48000 and you want to stream at 22050. Reducing the samplerate
+ is one way to reduce the stream bitrate but you lose higher frequency sound.
<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>
+ </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>
+ <h4>Encode</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>
+ <passthru>0</passthru>
</encode>
</pre>
<p>quality</p>
@@ -246,20 +251,113 @@
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>
+ </div>
+ <p>passthru</p>
+ <div class=indentedbox>
+ Set to 1 if you want incoming pre-recoded vorbis (from playlist) to not
+ be re-encoded. This should only really be used if you have a PCM input
+ that needs encoding but a playlist that does not.
+ </div>
+
+ <h4>Savefile</h4>
+ <pre>
+ <savefile>
+ <filename>/archive/ices/%F/stream.ogg</filename>
+ <duration>86400</duration>
+ <fmask>0644<fmask>
+ <dmask>0755<dmask>
+ <on-metadata>1</on-metadata>
+ </savefile>
+ </pre>
+ Sometimes the stream transmitted wants to be saved to disk. This can be useful
+ for live recordings.
+ <p>filename</p>
+ <div class=indentedbox>
+ State a filename for saving the Ogg Vorbis data. Files can be re-opened so
+ you probably want to state a pattern like as shown that allows for expanding
+ at the time it is opened. The % codes can be found in strftime(2) and can
+ apply to directories as well as files.
+ </div>
+
+ <p>duration</p>
+ <div class=indentedbox>
+ After the stated number of seconds, the current save file is closed and then
+ another is automatically re-opened based upon the filename pattern.
+ </div>
+
+ <p>on-metadata</p>
+ <div class=indentedbox>
+ Like above this determines when the save file is closed and the next reopens,
+ in this case new headers (new metadata) triggers the reopening.
+ </div>
+
+ <p>fmask</p>
+ <div class=indentedbox>
+ When a new file is created, it is given the stated mask so that permission
+ access is maintained.
+ </div>
+
+ <p>dmask</p>
+ <div class=indentedbox>
+ It is possible that new directories could be created (if the pattern uses a
+ % code for a directory component), if so, then this states the directory
+ mask.
+ </div>
+
+ <h4>Shout</h4>
+ <p>This is used to define a connection to an icecast server. Several <shout>
+ definitions can be used if you want to state different servers for the same
+ encoded stream. Each shout connection acts independantly from each other but they
+ send the same encoded stream</p>
+
+ <pre>
+ <shout>
+ <hostname>streamingserver.org</hostname>
+ <port>8000<port>
+ <password>hackme<password>
+ <mount>/stream.ogg<mount>
+ <yp>1<yp>
+ <flush-samples>20000<flush-samples>
+ <reconnectdelay>60<reconnectdelay>
+ </shout>
+ </pre>
+ <p>hostname</p>
+ <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>
+ <p>port</p>
+ <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 with the .ogg extension.
+ </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>flush-samples</h4>
+ <div class=indentedbox>
+ This is the trigger level in samples for when ogg pages are sent out. The
+ default is the samplerate which means some data is sent each second.
+ </div>
+ <h4>reconnectdelay</h4>
+ <div class=indentedbox>
+ This is the number of seconds, after a disconnect, that will be left to pass
+ before another connection is attempted.
+ </div>
+</body>
</html>
More information about the commits
mailing list