Icecast Server/Getting Started

The following is a draft!

It is at best incomplete and at worst completely broken. In any case, it is not an “official” Xiph spec or codec, so use with care.

This article describes how to get an Icecast server up and running. On this resulting server you can connect with a Source Client, like IceS, and stream music or video to listener clients. To get started with using Icecast you should first understand how everything works together.

How it works

The graphic above shows how Icecast basically works.

A source client, for example IceS, connects to the server on a specified mountpoint. A mountpoint could be described as a file on a normal local file system.
The listener accesses the mountpoint – the "file" – and can listen to the content – the stream. The server now offers the stream it gets form the source client on that specified mountpoint. Now listeners can connect to this mountpoint like they would to a normal file on a remote server.

Icecast sends the data it receives from the source client to the listeners, to everyone the same bitstream in realtime.
It is not possible to use Icecast with static files (like ogg or mp3 files), Icecast always needs an source client which sends the bitstream!

Getting Icecast

Before you can actually start to set up the server, you have to download the source code (or alternatively a binary package on Windows). This "Getting Started" is written for the server version 2.4.1, but should work with at least every 2.4.x version.

You can get the latest releases on downloads.xiph.org

Windows users should download the binary package, while others can download the source. There may be compiled versions on Homebrew (Mac OS) or apt-get (Debian, Ubuntu, …), but these could be outdated, so I will explain how to compile form source in the next step.

Windows users who downloaded the binary package – and extracted it to some location – can skip the next step and continue with "The configuration".

Compiling

After downloading the source package you like, you have to extract it. After that you will have to use your console and change directory (cd) to your extracted files.

$ cd /path/to/icecast-source

After doing that you have to run the configuration tool, then compile and install it. You may have to install additional dependencies first, when done, run the following commands.

$ ./configure
$ make
$ make install

The configuration

After installing Icecast, you are just one step away from using it! You have to configure it. Icecast is shipped with a default configuration. The default configuration can be found

on Linux here:

/etc/icecast.xml

or

/etc/icecast2/icecast.xml

on Mac OS here:

/etc/icecast.xml

or

/usr/local/etc/icecast.xml

on Windows here:

/path/to/extracted/icecast/etc/icecast.xml

You can now edit this file and save it to a location where you like it, or just leave it there, however you will need the full path to start the server, so you should remember it. To set up the server you should edit some fields in this xml file, like setting the right passwords, and hostname.

It is never wrong to set up these values, especially if you plan running a public server.

<location>The server's location</location>
<admin>admin@yourdomain.tld</admin>

You always should change the passwords from hackme to something more secure.

<authentication>
    <!-- Sources log in with username 'source' -->
    <source-password>myfancypassword</source-password>
    <!-- Relays log in username 'relay' -->
    <relay-password>youshallnotpass</relay-password>

    <!-- Admin logs in with the username given below -->
    <admin-user>admin</admin-user>
    <admin-password>anotherfancypassword</admin-password>
</authentication>

If you plan to run a public server and/or a server with Yellow Pages listing, you should change the hostname to the hostname/IP where your server can be accessed from.

<!-- This is the hostname other people will use to connect to your server.
It affects mainly the urls generated by Icecast for playlists and yp
listings. -->
<hostname>streams.yourdomain.tld</hostname>

Setting up more advanced things like relays, Yellow Pages listing and various other things will be explained in following in-depth parts of this Getting started.

Starting your first server

To start your first server, type

$ icecast -c /path/to/icecast.xml

into your console. If you did everything correctly Icecast should start and listen for connections on the default port. You can access it by typing http://127.0.0.1:8000/ into your web browser. If you see a page which says Icecast2 Status on top, you have done everything right and finished the basic part of this Getting started!

What next?

If you if you want in-depth infos, you should look at the following articles.

If you want to start streaming, have a look at IceS/Getting Started
If you want to go deeper into configuring your server, have a look at Icecast/Advanced Configuration