[[TOC]]

= Streaming to Icecast with roard or !SavannahIce and !RoarAudio !PlayList Daemon (rpld) =
This tutorial is to tell you how to setup roard or SavannahIce and !RoarAudio !PlayList Daemon to stream to a Icecast server. This does not cover installing Icecast itself nor using a different RoarAudio server than roard and SavannahIce.

== Introduction and Concept ==
As you may already have noticed the name of !RoarAudio !PlayList Daemon (later rpld)  contains the word PlayList. This name is chosen for a simple reason: In fact rpld is not audio player or something like that. It's a PlayList manager build on top of the RoarAudio sound system. It does:
* Handle playlists
* Push data from files or streams in playlist to the sound server
* It controls playback by passing control information between clients and sound server

It does not:
* Play back anything itself
* Decode or encode audio

However because clients never be in contact with the sound server this may sometimes look a bit like rpld be a full audio player.

As rpld does not handle audio itself setup for streaming is done on roard's/SavannahIce end.

== roard or !SavannahIce? ==
This is the big question we have at the beginning:

There are two different usecases for roard and SavannahIce:
While roard decodes everything, processes the audio and re-encodes the stream SavannahIce just passes as it is.

Here is a small table to help you find out what the best setup is for you:
||=Feature                     =||= roard =||= SavannahIce =||
||=Playlist input              =|| Yes     || Yes           ||
||=Codec converting support    =|| Yes     || Yes¹          ||
||=Resampling support          =|| Yes     || Yes¹          ||
||=Need reencoding             =|| Yes     || No            ||
||=Full metadata support       =|| Yes     || Yes           ||
||=Multiple output streams     =|| Yes¹    || Yes¹          ||
||=Multiple independed streams =|| Yes¹    || Yes¹          ||
¹ This is possible but out of scope of this document.

In general you need pre-encoded with when using SavannahIce but it will drastically reduce the needed CPU time.

== Installation ==
Before we can start you need to install the following software:
* roard from RoarAudio Package is using roard
* savannahice is using SavannahIce.
* rpld (at least version 0.1.4²)
* rpld-tools (if not in rpld package)
* vclt-tools
² For older version please see an older version of this document.

You should also consider to install a nice client for rpld with GUI or something.

If your operating system ships them we suggest you to use those versions and not compile your own binary.

=== Installing on Debian ===
Debian provides all of the needed packages but SavannahIce. Also note that of the writing of this document Debian does not have rpld 0.1.4. See ² above.
Just type as root for a roard based install:
{{{
 # apt-get install roaraudio roarplaylistd roarplaylistd-tools vclt-tools
}}}

Type as root for a SavannahIce based install:
{{{
 # apt-get install roarplaylistd roarplaylistd-tools vclt-tools libroar-dev
}}}
Now install SavannahIce from source.

=== Installing from source ===
Note: This is a very brief description and may or may not be extended later.

First go to http://roaraudio.keep-cool.org/downloads.html and download the packages listed above.

Before you continue you should install the following stuff, too:
* Essential packages for compiling (compiler, linker, make, system headers,...)
* libvorbis
* libshout
* vorbis-tools

Don't forget to install the -dev or -devel packages.
Some more libraries are listed in the READMEs for the packages.

For all the packages the building is done like:
{{{
 $ tar -xvzf package.tar.gz
 $ cd package
 $ ./configure³
 $ make
 # make install
}}}
³ Some packages does not provide this script. If there is non in the package you can safely skip this step.

== Setting up roard ==
After installing roard is basically already ready. All we need to tell it is to stream to to our Icecast server.

To do this we need to set the output driver to ''shout'' and device name to URL of the server including mount point and login. Such a URL may look like this:
{{{
 http://source:hackme@streaming-server.example.org:8000/mountpoint.ogg
}}}

''source is username (this is the default username, do not change if unsure) and ''hackme'' is the password.

=== on Debian ===
There is a configuration file at /etc/default/roaraudio you need to edit.
scroll down to section `Audio and Devices`. Now set the following parameters:
{{{
 ROARD_DRIVER='shout'
 ROARD_DEVICE='http://source:hackme@streaming-server.example.org:8000/mountpoint.ogg'
 ROARD_DRIVER_OPTIONS='sync,codec=ogg_vorbis'
}}}

Note that you need to remove the leading `#`s.

=== Starting manually ===
If you start roard manually you must simply pass the parameters using `-o`, `-O` and `-oO`.

Example:
{{{
 $ roard -o shout -O http://source:hackme@streaming-server.example.org:8000/mountpoint.ogg -oO sync,codec=ogg_vorbis
}}}

== Setting up !SavannahIce ==
SavannahIce does not need any manual setup.

== Setting up rpld ==
After you installed rpld the following steps must be done:
* Set up the ''store''. This is where rpld saves playlists and such.
* Import some music.
* Set default pointer
* Hit play button.
* Have fun.

=== Setting up store on Debian for usage with roard ===
On Debian the store is set up by the roarplaylistd package at install.

=== Setting up store manually for usage with roard ===
All you need to do is to run the following command as root:
{{{
 # rpld-storemgr create
}}}

=== Setting up store on Debian for usage with !SavannahIce ===
See next section.

=== Setting up store manually for usage with !SavannahIce ===
All you need to do is to run the following command as root:
{{{
 # rpld-storemgr create SavannahIce http://source:hackme@streaming-server.example.org:8000/mountpoint.ogg
}}}
The URL is the same as for roard above.

=== Change owner of store ===
If you set up your store manually you need to change the owner of the store to your.
To do this run as root:
{{{
 # chown YOUR_USER:YOUR_GROUP /var/lib/roarplaylistd
}}}

You can get the values for ''YOUR_USER'' and ''YOUR_GROUP'' using id:
{{{
 id
}}}
It will list the username under ''uid'' and the group name under ''gid''.

When using Debian the user is "roarplaylistd" and group is "audio".

=== Starting up rpld manually ===
To start rpld run it like this:
{{{
 $ rpld --store-path /var/lib/roarplaylistd
}}}

You can add a `--play` to start it in playing state.

=== Importing some music ===
To import some music you need a playlist of those music. If you already have some playlist skip next section and continue with ''Importing a existing playlist''.

==== Generating a new playlist with dir2vclt ====
To generate a new playlist from a directory you can use the tool ''dir2vclt''. It will generate [[VCLT]] playlist from a directory or single file. Just run it like this:
{{{
 $ dir2vclt /some/data/path/with/music/ new-playlist.vclt
}}}

Note that dir2vclt currently requires absolute path name.

==== Importing a existing playlist ====

To import a existing or just generated playlist you can use the tools ''rpld-addplaylist'' and ''rpld-import'' or using a GUI you have installed. This document will tell you how to use the former tools.

To create a new playlist use:
{{{
 $ rpld-ctl addplaylist 'playlistname'
}}}

To import a existing playlist:
{{{
 $ rpld-import 'playlistname' 'playlisttype' 'playlistfile'
}}}

While `playlisttype` is the type of the playlist:
 VCLT:: The playlist format used by dir2vclt. (recommended)
 M3U:: A common playlist format.
 PLAIN:: Single filename per line format
 XSPF:: Xiph's xspf format.
Others may also be supported.

=== Set default pointer ===
Before we can hit the play button we need to tell rpld what to play.
In our case we most likely have only one Playlist (created and imported above) and want to stream exactly this playlist. If we hit end of playlist we want it to repeat. On a normal player you would just select the first entry in your list and press 'repeat' button. rpld does not have something like that but something better!: Pointers.

The full discussion on pointers, what they are and how they work is out of scope for this document. So I will try to make it as simple as possible: rpld normally plays back it's so called ''Main Queue''. If the queue (which must be manually filled) runs out of songs it stops. To avoid this pointers got invented. Those pointers are rules how to fill the ''Main Queue'' automatically if it runs out of songs to play. Basically they point to playlist entries (songs). This is where they got there name from.

There are two pointers of interest for us: the so called ''current'' and the so called ''default'' pointer. The first one points to a song in a playlist which is played when the ''Main Queue'' runs out of songs. The song is queued and the pointer is moved to the next song in list. This allows us to play a playlist from top to bottom. If it reaches the end of the list it is unset and playback stops. So, now we only need to find out how to repeat the list, right?

To repeat the playlist the ''default pointer'' was invented. It's simply, as the name says, the default value for the ''current pointer''. So if the playback would normally stop the ''current pointer'' just gets set to where the ''default pointer'' points to and playback continues.

So all we need to do to repeat a playlist is to set the ''default pointer'' to the first entry.
If we press play the ''current pointer'' is set to the first song, the song is played back. If it reaches the end of the list it restarts as the ''current pointer'' is reset to the first song in list.

Setting the pointer to the first song in list is very easy, just run:
{{{
 $ rpld-setpointer default num:0 'playlistname'
}}}

Here ''default'' is the name of the pointer and ''num:0'' means the first entry in the list.

If we want to play a playlist in random mode we use the ''current pointer'' and set it to the ''random:'' like this:
{{{
 $ rpld-setpointer current random: 'playlistname'
}}}

In this case the current pointer is not moved forward. Every time the pointer is accessed a random song is selected from the playlist.

=== Pressing play ===
To start playback just hit the playback button in the GUI or client you use or use the following command:
{{{
 $ rpld-ctl play
}}}

=== Have fun ===
Now listen to your music and have a lot fun.