Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



Existing Icecast documentation can be cryptic; therefore, this howto aims at providing a novice user with a relatively safe way of configuring and running Icecast (the streaming server), MPD, Ices2 or Muse (streaming clients; the apps that send sound to Icecast).

Since you probably want to stream audio to people over the Internet AND run Icecast as a daemon it becomes necessary to take a step or two in making sure that no damage to your system will result if Icecast were to be compromised (i.e., find a way of making sure it doesn't run as root).

Important: This howto was originally written for icecast-2 and ices-2. Previous versions of ices streamed audio using the MP3 format. As of version 2 ices now only supports the OGG format while icecast-2 still retains the ability to accept MP3 streams. This may impact which clients can listen to your stream. If you require a MP3 stream you might prefer looking at Muse (Muse supports both MP3 and OGG files).

Once Icecast is installed you only need to install either Muse or Ices.

For a nifty MP3 to OGG converter, check out Oggasm.

Installing Icecast

USE Flags



# emerge -av icecast

Configuring Icecast

Starting and configuring icecast

icecast 2.3.1-r1 and higher will now by default run as the user icecast and the group nogroup for security purposes.

Note: I had to change the group and owner on the /var/log/icecast directory manually to let the icecast user write there.
chown icecast:nogroup /var/log/icecast

Once you emerge icecast you should be able to run

/etc/init.d/icecast start

Check the file /var/log/icecast/error.log. You should see something similar to this:

File: /var/log/icecast/error.log
[2004-07-19  01:06:32] INFO main/main icecast server started

You should edit /etc/icecast2/icecast.xml and replace the 3 instances of the password hackme with a more secure password. The following tags are:

Sound Feeds

Shoutcast only provides a common interface through which clients can connect to a sound feed, it does not provide a feed directly. To generate a sound feed one of the following daemons must be used:


MPD provides the most flexibility of input, it will be able to decode any audio file (for the most part) and then dump out an ogg vorbis stream.


use flags:


Before you start MPD, configure the mpd.conf file

File: /etc/mpd.conf
audio_output {
    type        "shout"
    name        "my cool stream"
    host        "localhost"
    port        "8000"
    mount       "/example1.ogg"
    password    "hackme"
#   quality     "7.0"
    bitrate     "64"
    format      "44100:16:1"

# Optional Paramters
    user        "source"
    description "here's my long description"
    genre       "jazz"
    public      "no"
} # end of audio_output
#0.13.0 bug workaround
audio_output {
    type "alsa"
    name "fake out"
    driver "null"

The lines above that start with a "#" are comment lines. The other lines have the following meaning:

Start up MPD, and use a music player client to start the stream.

As a workaround for a bug in version 0.13.0, the following also must be added to mpd.conf:


Configuring ices

At this point, we've got icecast up and running. Icecast is now ready to receive the music stream from ices. Let's configure ices:

$ cp /etc/ices2/ices-playlist.xml.dist /etc/ices2/ices-playlist.xml

Edit the ices-playlist.xml and change the following settings:

File: /etc/ices2/ices-playlist.xml
<hostname>$hostname</hostname>                        # replace $hostname with your machine name
<password>$password</password>                        # replace $password with the necessary password from icecast.xml
<param name="file">/path/to/playlist.txt</param>
<mount>/stream_name.ogg</mount>                       # Must include .ogg, replace 'stream_name' w/ a name for your stream

Note: Your stream name needs to end with ".ogg" or most media players will not recognize your icecast stream as an OGG stream.

Starting ices

Now that we have ices and icecast configured you will need to create a playlist for ices to stream to icecast. In this howto we've chosen /home/icecast/playlist.txt file to hold our playlist. The playlist is a text file with one absolute path per OGG file per line. We can create a playlist from an existing directory of OGG files:

$ find /path/to/music -iname "*.ogg" > playlist.txt

Ices will stream each song in the order it is listed in the playlist unless you set the <random> parameter to "1" in the ices-playlist.xml. If the <restart-after-reread> parameter is set to "1", ices will restart the playlist at the first file listed if the playlist is updated while ices is running.

Now let's start ices as the icecast user:

$ /etc/init.d/icecast start
$ ices /etc/ices2/ices-playlist.xml

If no error messages are displayed, you should be able to verify the ices to icecast connection by using your browser to view $hostname:8000/admin/stats.xsl. You should see the mount point /path/to/music.ogg in the list of mount points. If your stream appears you should be able to connect to the stream by using the URL $hostname:8000/path/to/music.ogg.m3u.

If you hear your stream, congratulations! You now have a streaming audio server. After you're done strutting your stuff to your new music stream, close down ices and icecast create startup and shutdown scripts for ices (scroll down to the init scripts section).

$ exit
# killall ices
# /etc/init.d/icecast stop



So the OGG format just won't work for you? Well there is a way to stream MP3 formatted streams using muse and this section will demonstrate how to hook up muse to icecast. I strongly recommend that you follow the previous sections and get icecast and ices working even if you do not want to stream music using the OGG format.

Note: Muse is limited in its abilities to play user created playlists. As far as I can tell there is no way to randomize a playlist at the time it is being streamed. This means that muse will play songs in the order they are listed in your playlist. Also, muse does not send information regarding the current song to icecast.

Important: Muse is a gruff little bear to deal with. It doesn't like being detached from a TTY and has no built-in ability to migrate itself to the background. It refuses to accept playlist files with extensions different than .pls, claiming that such a file does not exist. It also does not have an option to write its logs to a file; it wants to write to standard error. This means that while this howto is designed with logging in mind, it just doesn't work so you will not get logs from muse when started with this howto's startup script. One could attempt to pipe to logger. Feedback and suggestions are welcome.


use flags

  • muse : debug -> Debug support
  • muse : gtk -> GTK+ graphical frontend
  • muse : ncurses -> ncurses based frontend

Running Muse

Now that we've installed muse, we need to create a playlist for it like we do for ices. Muse is picky, however, about the extension of the playlist file so we will use '.pls' as an extension. The file format consists of one path to an MP3 file per line. Let's create a playlist for muse:

$ find $mp3_dir|grep .mp3 > playlist.pls
(OR if you have the string "mp3" in your path)
$ find $mp3_dir -name *.mp3 > playlist.pls

Now, let's test muse.

$ su -
# /etc/init.d/icecast start
# exit
$ muse -C /path/to/playlist.pls -o -e mp3 -b 128 -q 9.0  -c 2 --server localhost -m $stream_name.mp3 -p $passwd

Replace $stream_name with what you want to call the stream and $passwd with the icecast server password. (You may also append your custom port of icecast: --server localhost[:port])

You should be able to verify the muse to icecast connection by using your browser to view $hostname:8000/admin/stats.xsl. You should see the mount point /$stream_name.mp3 in the list of mount points. If your stream appears you should be able to connect to the stream by using the URL $hostname:8000/$stream_name.mp3.m3u.

Kill muse by pressing control-c in the terminal. For more control regarding your stream, run muse in GUI mode by executing

$ muse -g ncurses
$ muse -g gtk2

(depending of what you have compiled in during the emerge)

To run muse as a daemon, scroll down to the init scripts.

Init scripts

Portage may not create startup or shutdown scripts for ices or muse (probably because few people use them as daemons). If you use the muse or ices script, you don't need to start icecast (although you still need the init script) as the muse/ices script will start up icecast if it isn't already on.


(Problem with this /etc/init.d/ices file containing "--chuid icecast" occurs with using Alsa for capture. You will see this error when starting the /etc/init.d/ices: "ALSA lib pcm_hw.c:1357:(_snd_pcm_hw_open) Invalid value for card". To resolve, add "icecast" to the audio group within /etc/group. Another tip, if your user is already within the "audio group, just augment "--chuid your_user". Now I can change metadata as I've got permission to SIGUSR1 ices process. (I believe the icecast.ebuild should add icecast to the audio group itself instead of us doing this manually.)

File: /etc/init.d/ices
# Copyright 1999-2005 Gentoo Technologies, Inc.
# Distributed under the terms of the GNU General Public License v2

depend() {
        need icecast net
        use dns

start() {
        ebegin "Starting ices"
        start-stop-daemon --start --chuid icecast --quiet --exec /usr/bin/ices \
                -- /home/icecast/ices-playlist.xml >/dev/null 2>&1
        eend $?

stop () {
        ebegin "Stopping ices"
        start-stop-daemon --stop --retry 5 --quiet --exec /usr/bin/ices
        eend $?

Which can be executed as

$ su -
# /etc/init.d/ices start

If you want ices and icecast to start on system boot, use rc-update:

# rc-update add ices default


File: /etc/init.d/muse
# Copyright 1999-2005 Gentoo Technologies, Inc.
# Distributed under the terms of the GNU General Public License v2

depend() {
       need icecast net
       use dns

start() {
       ebegin "Starting muse"
       if [ -n "${MUSE_LOG}" -a ! -f "${MUSE_LOG}" ]; then
               touch "${MUSE_LOG}"
               chown icecast:icecast "${MUSE_LOG}"
       MUSE_OPTS="-C $MUSE_PLAYLIST -o -e mp3 -b ${MUSE_BITRATE} -q ${MUSE_QUALITY} -r ${MUSE_RATE} -c 2 -s
       start-stop-daemon --start --background --chuid icecast --quiet --exec /usr/bin/muse \
               -- ${MUSE_OPTS} >"${MUSE_LOG}" 2>&1
       eend $?

stop () {
       ebegin "Stopping muse"
       start-stop-daemon --stop --retry 5 --quiet --exec /usr/bin/muse
       eend $?

We also need to create a file to contain muse's command line parameters:

File: /etc/conf.d/muse
# Config file for muse

Replace $stream_name and $passwd with your MP3 stream's name and your icecast password.

It can now be executed as

$ su -
# /etc/init.d/muse start

If you want muse and icecast to start on system boot, use rc-update:

# rc-update add icecast default
# rc-update add muse default


MPD Errors in the mpd.error.log with: Lost shout connection to localhost:80 : Socket error

  • Some revisions of mpd-0.13.0 had problems connecting to icecast. Revisions from 4893 should be working.
  • Be sure to check libshout's version. If you're using mpd-0.13.0 you should be using >=libshout-2.2.2, which is masked for x86. Otherwise, the connection won't work.
  • mpd-0.12.2 works flawlessly.
  • If you have no 'alsa' or 'ao' outputs, you should add a dummy output, as described in Bug 1525.

Q & A

External Links

Jonathan Fors' guide to Icecast streaming with Linux

Last modified: Thu, 04 Sep 2008 05:55:00 +0000 Hits: 58,651