Commit fd235541 authored by Thomas B. Rücker's avatar Thomas B. Rücker 😊

Ugly merge of docs for beta1 as generator failed

parent e445065a
......@@ -16,7 +16,7 @@
<div class="section">
<h2>Icecast 2.4.1 Docs &mdash; Admin Interface</h2>
<h2>Icecast 2.4.99.1 Docs &mdash; Admin Interface</h2>
<div class="article">
......@@ -140,4 +140,4 @@ To see the XML document that is applied to each admin XSLT, just remove the <cod
</div>
</body>
</html>
\ No newline at end of file
</html>
......@@ -16,7 +16,7 @@
<div class="section">
<h2>Icecast 2.4.1 Docs &mdash; Authentication</h2>
<h2>Icecast 2.4.99.1 Docs &mdash; Authentication</h2>
<div class="article">
<h3 id="listener-authentication">Listener Authentication</h3>
......@@ -356,4 +356,4 @@ stream is active. For these <code>admin</code> is set to <code>1</code> in POST
</div>
</body>
</html>
\ No newline at end of file
</html>
......@@ -16,7 +16,7 @@
<div class="section">
<h2>Icecast 2.4.1 Docs &mdash; Basic Setup</h2>
<h2>Icecast 2.4.99.1 Docs &mdash; Basic Setup</h2>
<div class="article">
<h3 id="basic-requirements">Basic Requirements</h3>
......@@ -88,4 +88,4 @@ source password - from <code>&lt;source-password&gt;</code> </p>
</div>
</body>
</html>
\ No newline at end of file
</html>
This diff is collapsed.
This diff is collapsed.
......@@ -16,7 +16,7 @@
<div class="section">
<h2>Icecast 2.4.1 Docs &mdash; FAQ</h2>
<h2>Icecast 2.4.99.1 Docs &mdash; FAQ</h2>
<div class="article">
<h3 id="general-questions">General Questions</h3>
......@@ -53,4 +53,4 @@ it on the fly.</p>
</div>
</body>
</html>
\ No newline at end of file
</html>
......@@ -16,7 +16,7 @@
<div class="section">
<h2>Icecast 2.4.1 Docs &mdash; Glossary</h2>
<h2>Icecast 2.4.99.1 Docs &mdash; Glossary</h2>
<div class="article">
<dl>
......@@ -48,4 +48,4 @@ Icecast will then move all clients currently connected to the now defunct mountp
</div>
</body>
</html>
\ No newline at end of file
</html>
......@@ -16,7 +16,7 @@
<div class="section">
<h2>Icecast 2.4.1 Docs &mdash; Table of Contents</h2>
<h2>Icecast 2.4.99.1 Docs &mdash; Table of Contents</h2>
<div class="article">
<h3 id="pages">Pages</h3>
......@@ -39,7 +39,7 @@
</div>
<div class="article">
<h3 id="icecast-241-readme">Icecast 2.4.1 Readme</h3>
<h3 id="icecast-241-readme">Icecast 2.4.99.1 Readme</h3>
<p>Icecast is a streaming media server which currently supports Ogg
Vorbis and MP3 audio streams. It can be used to create an Internet
radio station or a privately running jukebox and many things in
......@@ -96,4 +96,4 @@ at irc.freenode.net, channel #icecast, if you have any troubles.</p>
</div>
</body>
</html>
\ No newline at end of file
</html>
......@@ -16,11 +16,11 @@
<div class="section">
<h2>Icecast 2.4.1 Docs &mdash; Introduction</h2>
<h2>Icecast 2.4.99.1 Docs &mdash; Introduction</h2>
<div class="article">
<h3 id="what-is-icecast">What is Icecast?</h3>
<p>Icecast is a streaming media server which currently supports Ogg Vorbis and MP3 audio streams. It can be used to create an Internet radio station or a privately running jukebox and many things in between. It is very versatile in that new formats can be added relatively easily and supports open standards for commuincation and interaction.</p>
<p>Icecast is a streaming media server which currently supports Ogg Vorbis, Opus, Theora and WebM streams, MP3 and AAC streams are known to work. It can be used to create an Internet radio station or a privately running jukebox and many things in between. It is very versatile in that new formats can be added relatively easily and supports open standards for commuincation and interaction.</p>
<p>There are two major parts to most streaming media servers: the component providing the content (what we call source clients) and the component which is responsible for serving that content to listeners (this is the function of icecast).</p>
</div>
......@@ -56,8 +56,8 @@
<p>Best Ways:</p>
<ul>
<li>Icecast mailing list <a href="http://www.xiph.org/archives">http://www.xiph.org/archives</a></li>
<li>Icecast Developers mailing list <a href="http://www.xiph.org/archives">http://www.xiph.org/archives</a></li>
<li>Icecast mailing list <a href="http://lists.xiph.org/mailman/listinfo/icecast">http://lists.xiph.org/mailman/listinfo/icecast</a></li>
<li>Icecast Developers mailing list <a href="http://lists.xiph.org/mailman/listinfo/icecast-dev">http://lists.xiph.org/mailman/listinfo/icecast-dev</a></li>
<li>Icecast IRC chat room - irc.freenode.net : #icecast</li>
</ul>
......@@ -70,4 +70,4 @@
</div>
</body>
</html>
\ No newline at end of file
</html>
......@@ -16,7 +16,7 @@
<div class="section">
<h2>Icecast 2.4.1 Docs &mdash; Relaying</h2>
<h2>Icecast 2.4.99.1 Docs &mdash; Relaying</h2>
<div class="article">
<h3 id="overview">Overview</h3>
......@@ -92,4 +92,4 @@ in the stream itself) then the <code>&lt;relay-shoutcast-metadata&gt;</code> nee
</div>
</body>
</html>
\ No newline at end of file
</html>
......@@ -16,7 +16,8 @@
<div class="section">
<h2>Icecast 2.4.1 Docs &mdash; Server Statistics</h2>
<h2>Icecast 2.4.99.1 Docs &mdash; Server Statistics</h2>
<div class="article">
<h3 id="overview">Overview</h3>
......@@ -36,17 +37,22 @@ API and will change it, even completely, between versions!<br />
<strong>The preferred ways are custom XSLT, JSON and raw XML.</strong></p>
</div>
<!-- FIXME -->
<div class="article">
<h3 id="json">JSON API, machine readable data</h3>
<p>Since version 2.4.0 Icecast includes a basic JSON API (<code>/status-json.xsl</code>) based on a xml2json template by Doeke Zanstra
(see <code>xml2json.xslt</code>). It exposes the same set of server statistics that are available through the web interface and
should fulfil basic user needs. The intention is to not break backwards compatibility of this interface in the future,
still we recommend to design robust software that can deal with possible changes like addition or removal of variables.
Also note that not all variables are available all the time and availability may change at runtime due to stream type, etc.</p>
</div>
<div class="article">
<h3 id="xslt_advanced">Advanced machine readable data, XSLT generated</h3>
<p>Icecast uses the very powerful libXSLT engine to transform its internal raw statistical data into custom tailored interfaces.
Many people have written custom XSLT code that produces e.g. plain text “now playing”, XSPF, VCLT, munin interface data, etc. </p>
<p>Since version 2.4.0 Icecast includes a basic JSON API (<code>/status-json.xsl</code>) based on a xml2json template by Doeke Zanstra
(see <code>xml2json.xslt</code>). It exposes a basic set of server statistics that should fulfil basic user needs. The intention is
to not break backwards compatibility of this interface in the future, still we recommend to design robust software that
can deal with possible changes like addition or removal of variables.</p>
</div>
<div class="article">
......@@ -55,6 +61,8 @@ can deal with possible changes like addition or removal of variables.</p>
<p>This section contains information about the raw XML server statistics data available inside Icecast. An example
stats XML tree will be shown and each element will be described. The following example stats tree will be used: </p>
<!-- FIXME -->
<div class="highlight"><pre><code class="language-xml" data-lang="xml"><span class="nt">&lt;icestats&gt;</span>
<span class="nt">&lt;admin&gt;</span>icemaster@localhost<span class="nt">&lt;/admin&gt;</span>
<span class="nt">&lt;client_connections&gt;</span>649<span class="nt">&lt;/client_connections&gt;</span>
......@@ -65,7 +73,7 @@ stats XML tree will be shown and each element will be described. The following e
<span class="nt">&lt;listener_connections&gt;</span>90<span class="nt">&lt;/listener_connections&gt;</span>
<span class="nt">&lt;listeners&gt;</span>0<span class="nt">&lt;/listeners&gt;</span>
<span class="nt">&lt;location&gt;</span>Earth<span class="nt">&lt;/location&gt;</span>
<span class="nt">&lt;server_id&gt;</span>Icecast 2.4.0<span class="nt">&lt;/server_id&gt;</span>
<span class="nt">&lt;server_id&gt;</span>Icecast 2.5<span class="nt">&lt;/server_id&gt;</span>
<span class="nt">&lt;source_client_connections&gt;</span>164<span class="nt">&lt;/source_client_connections&gt;</span>
<span class="nt">&lt;source_relay_connections&gt;</span>0<span class="nt">&lt;/source_relay_connections&gt;</span>
<span class="nt">&lt;source_total_connections&gt;</span>164<span class="nt">&lt;/source_total_connections&gt;</span>
......
......@@ -16,17 +16,21 @@
<div class="section">
<h2>Icecast 2.4.1 Docs &mdash; Win32 Specifics</h2>
<h2>Icecast 2.4.99.1 Docs &mdash; Win32 Specifics</h2>
<div class="article">
<p>The Win32 port of Icecast 2 is a simple command line application,
it used to be a UI framework around the core Icecast 2 server. </p>
<p>The GUI is no longer necessary as Icecast has achieved all of its
functionality in its web interface.</p>
<p>Most of the features of Icecast 2 are available in the Win32 port.<br />
<strong>A notable absence is IPv6 support.</strong></p>
<p>If there is sufficient user interest we may reintroduce the Icecast GUI
and capability to start Icecast as a Windows Service.</p>
<p>We are planning to reintroduce the capability to start Icecast
as a Windows Service in the 2.5.0 release.</p>
</div>
......
......@@ -16,16 +16,18 @@
<div class="section">
<h2>Icecast 2.4.1 Docs &mdash; YP Directories</h2>
<h2>Icecast 2.4.99.1 Docs &mdash; YP Directories</h2>
<div class="article">
<h3 id="overview">Overview</h3>
<p>A YP (Yellow Pages) directory is a listing of broadcast streams. Icecast 2 has it own YP directory located at
<p>A YP directory is a listing of broadcast streams. Icecast has it own YP directory located at
<a href="http://dir.xiph.org">http://dir.xiph.org</a>. Currently Icecast can only be listed in an Icecast-supported YP directory.<br />
This means that you cannot list your stream in the Shoutcast YP directory.</p>
This means that you cannot list your stream in the Shoutcast YP directory, due to their terms of service.</p>
<p>In the Icecast configuration file are all the currently available YP directory servers. Listing your stream in a YP is
a combination of settings in the Icecast configuration file and also in your source client.</p>
a combination of settings in the Icecast configuration file and also in your source client. It is of great importance
to configure Icecast correctly, as even one wrong setting can prevent listings to be accepted by a YP directory.</p>
</div>
......@@ -42,22 +44,88 @@ If Icecast has been built with YP support, then the following configuration opti
<p>Multiple directory XML chunks can be specified in order to be listed in multiple directories.</p>
<h4 id="further-options-that-play-a-significant-role-in-yp-listings">Further options that play a significant role in YP listings</h4>
<h5 id="hostname"><code>&lt;hostname&gt;</code></h5>
<p>The hostname option <strong>MUST</strong> be set to a name that resolves to the machine this Icecast server runs on.</p>
<h5 id="listener-socketport"><code>&lt;listener-socket&gt;&lt;port&gt;</code></h5>
<p>The <strong>first</strong> <code>listener-socke</code>+<code>port</code> entry is used to build the URL advertized to the YP server.</p>
<h5 id="listener-socketbind-address"><code>&lt;listener-socket&gt;&lt;bind-address&gt;</code></h5>
<p>If you don’t specify an explicit <code>bind-address</code>, including <code>::</code> and <code>0.0.0.0</code>, then the default
bind behaviour of your operating system will apply, this may have unexpected consequences for dual-stack
(IPv6 and IPv4) setups.</p>
<p>If your hostname resolves to both an AAAA and an A record (IPv6 and IPv4), then you <strong>MUST</strong> verify,
that Icecast listens to both. If in doubt create two listener-socket entries and use <code>::</code> and <code>0.0.0.0</code>
as the respective <code>bind-address</code>.</p>
<h5 id="admin-contact"><code>&lt;admin&gt;</code> contact</h5>
<p>If you are listing on a YP, then this field <strong>MUST</strong> contain a valid email address of a technical contact
on your side. YP admins will use this to reach you in case your server is misconfigured and causes problems
for the YP directory. An invalid or unreachable address is likely to get your radio/server/network banned from YP.</p>
<h5 id="verifying-the-advertized-url">Verifying the advertized URL</h5>
<p>After adjusting the settings and configuring your source client, you should verify setup: <br />
Go to the Icecast web interface, specifically the admin part <code>/admin/</code> and look for the <code>listenurl</code> values
of your streams. These URLs <strong>MUST</strong> work from the public internet, or your listings will fail.</p>
<p>This is also one of the checks performed by a YP server. Common misconfigurations are:<br />
* <code>&lt;hostname&gt;</code> set to <code>localhost</code>
* <code>&lt;hostname&gt;</code> set to some address that does <strong>NOT</strong> point to the Icecast server
* hostname has AAAA record but Icecast not bound to <code>::</code>
* multiple <code>&lt;listener-socket&gt;</code> entries, but the first one is not publicly reachable</p>
</div>
<div class="article">
<h3 id="configuring-your-source-client-for-yp-support">Configuring Your Source Client for YP Support</h3>
<p>This is usually covered in the source client documentation. More specifically, the source client needs to provide
the HTTP header <code>Ice-Public: 1</code> on connect in order to enable YP listing of the stream.<br />
This can however be overridden in mount point settings, refer to “<a href="config-file.html#mountsettings">Icecast Config File</a>
This can however be overridden in the server side mount point settings, refer to “<a href="config-file.html#mountsettings">Icecast Config File</a>
for further details.<br />
If a mountpoint is being listed on a YP, then you will see some additional statistics relating to the YP such as
<code>last-touch</code>, <code>currently-playing</code>, etc.</p>
</div>
<div class="article">
<h3 id="troubleshooting">Troubleshooting</h3>
<p>As with all Icecast problems, the error log is the goto place to start. If necessary temporary increase the log level to
<code>4</code> (debug) and reload the Icecast config. All relevant messages will contain <code>YP</code>. Especially those messages that tell
you that something <code>failed</code> will contain important hints and or messages from the YP server. If your entry submission
is directly rejected the server will tell why, if your entry gets delisted after submission, then you will see
updates/touches fail. Depending on the YP server the stream reachability check will be deferred, so you will see
a successfull initial submission, but if your stream is found to be unreachable it will be delisted and updates will fail.
Please note that YP directories will check both IPv6 and IPv4 availability of streams. See the list of common misconfigurations
for further hints.</p>
<p>Should you still have problems listing on <a href="dir.xiph.org">http://dir.xiph.org</a>, then please:
* set your logging to <code>4</code> (debug)
* reload/restart Icecast
* make sure your streams are running and marked public (either by source setting or mountpoint override)
* wait for <strong>one hour</strong>
* filter the error log for messages from the last hour, that are beginning with <code>yp/</code>
* join the <a href="Icecast users mailing list">http://lists.xiph.org/mailman/listinfo/icecast</a> (else the following step will fail!)
* send a mail to <a href="icecast@xiph.org">mailto:icecast@xiph.org</a> containing:
1. The public URL of your Icecast server - e.g. <code>http://icecast.example.org:8000/</code> (Even if you have removed the status pages! This does <strong>NOT</strong> mean your homepage.)
2. The <code>&lt;hostname&gt;</code>, <code>&lt;listen-socket&gt;</code> and <code>&lt;directory&gt;</code> sections of your <code>icecast.xml</code>
3. The <em>filtered</em> error.log prepared previously (as an attachment)
* wait for replies from the mailing list</p>
</div>
</div>
<div class="footer">
<p><a href="https://plus.google.com/100957455777699991449/about">
<img alt="Google+" title="Find uns on Google+" src="/assets/img/google-plus.svg" style="width: 20px;">
</a>
</p>
<p>&copy; 2004-2014 Xiph.Org. All rights reserved.</p>
<p>Support icecast development at <a href="http://icecast.org">icecast.org</a></p>
</div>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment