Icecast Server/Getting Started

From XiphWiki
Jump to navigation Jump to search

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

Graphic showing the flow from source clients through Icecast to listeners. (click image to enlarge)

The graphic shows how Icecast basically works:

  • A source client connects to the Icecast server on a specified mountpoint.
    (a mountpoint can be described as a file on a normal file system)
  • Listeners access the mountpoints ("files") and can listen to the bitstreams ("file contents").
    (they can connect to these like they would to normal files on a remote server)
  • Icecast offers the bitstream it gets from the source client on a specified mountpoint to all of the mountpoint's listeners in realtime.

Note: you cannot use Icecast with static files (eg. ogg or mp3 files),
it always needs a source client which sends a bitstream!

Getting Icecast

You can download Icecast from icecast.org.

This "Getting Started" is written for Icecast version 2.4.1, but should work with at least every 2.4.x version.

There may be compiled versions on Homebrew (Mac OS) or apt-get (Debian, Ubuntu, etc).
Because these might be outdated, compiling from source is explained in the next step.

Windows users who download and extract the binary package can skip the Compiling step and continue with Configuration.

Compiling

Once you have downloaded the source package you want, you have to extract it.

After that you have to use your console and change directory (cd) to your extracted files.

$ cd /path/to/icecast-source

You then have to run the configuration tool, compile and install it.
(you may have to install additional dependencies first)

When done, run the following commands to finish the installation:

$ ./configure
$ make
$ make install

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. 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 one 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 the 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 want in-depth infos, you should look at the following articles.