Darkice
Overwiew

DarkIce is a live audio streamer. It records audio from an audio interface (sound card), encodes it and sends it to a streaming server. It is important to note that DarkIce is not designed to play streams using a static playlist. Audio sources must be fed into the input jack of your soundcard. From there DarkIce re-encodes the audio out in the format specified.

DarkIce can encode in the ogg/Vorbis and mp3 formats, and is able to send the encoded stream to the following streaming servers:ShoutCast, IceCast 1 and 2, Darwin Streaming Server.

Darkice is available for GNU/Linux OS and Macintosh OS. You can download it form the Darkice homepage.

Different flavours of Darkice

There are two different possibilities about how to use the Darkice streaming software:

  • You can configure it from the Darksnow grafical interface
  • You can directly edit the Darkice configuration file

Darkice install and configuration
Prerequisites

First of all, you will need to download and install the last source tarballs of the following programs and libraries; for main GNU/Linux distributions like Debian, Rad Hat or Gentoo, they are available as precompiled packets in the distribution sources.

NAME FUNCTION version as of FEBRUARY 2006 where to find the LATEST VERSION
Darkice Main streaming software darkice-0.17.tar.gz Darkice homepage
Darksnow Grafical frontend for Darkice darksnow-0.6.tar.gz Darksnow homepage
LAME .mp3 encoder lame-3.96.1.tar.gz LAME homepage
libogg ogg media container libogg-1.1.2.tar.gz xiph community homepage
libvorbis Vorbis encoder libvorbis-1.1.0.tar.gz xiph community homepage

Be aware that DarkIce normally checks the /usr directory for the lame library. This is due to the fact that many Linux distributions include lame as an RPM. To build DarkIce with lame support use the --with-lame-prefix=/usr/local/lib together with the configure script. This is contingent upon building lame from source.

And, of course, as for every other streaming software, you will need to know the following informations about the streaming server: server IP address or hostname, source password, server port (usually 8000).

The darkice.cfg configuration

In a GNU/Linux distribution, you can find an example DarkIce configuration file at /usr/share/doc/darkice/examples/darkice.cfg. Once copied in a location of your choice, you can edit it with any editor and later pass this new configuration to the darkice command.

Otherwise, you can directly "cut and paste" from the example configuration file that you can find at the bottom of this page, change the settings to meet your needs, and finally save it on your computer. Always at the bottom of this page, you will find some remarks about the darkice.cfg configuration file.

Starting Darkice

Again, before starting any streamer make certain the icecast or shoutcast server is up and running. The DarkIce streamer calls the binary file and the configuration file. Here is how an example startup command might appear:

user@host:~$ darkice -c /usr/local/icecast2/conf/darkice.cfg

Check the log files for any messages in case the server fails to start. Set a higher verbosity using the -h option during startup of the DarkIce streamer. Verbosity can be set anywhere between 0 (silent) and 10 (extremely descriptive messages). For example, the following command sets the verbosity of messages to something reasonable while referring to the configuration file found in the /etc directory:

user@host:~$ darkice -v 5 -c /etc/darkice.cfg &

Modify the options and file locations as needed.

Be aware that in older DarkIce releases if you start the streamer in its own terminal window you cannot close the same window. Even if you affix an ampersand (&) to the end of the script you are not guaranteed the process will continue once the terminal window closes.


Darksnow

For those users still uncomfortable with command line options and manually editing configuration files, there is a GUI-frontend for the DarkIce program. Called DarkSnow, this application provides a nice interface and a complete configuration tool for DarkIce. You can download the latest version from the Darksnow homepage.

Once installed and configured, launch the frontend from any terminal window, typing darksnow. The primary window is defined as "Server Options". Set the server type, IP address, port number, mountpoint and password. Once all the variables have been correctly inserted in the GUI-frontend, you may still have to manually start the streamer from the command line. Unlike earlier versions, the latest DarkSnow does not allow you to launch the application from the GUI. However, it does provide a way to save and reopen existing configuration files.


  • Streaming destination. Here you select to which kind of streaming server you will be connecting. Normally, it will be an Icecast2 server.
  • Server. Specify here the IP address or resolvable name of the server. If the server is running on the same computer as DarkSnow, you can enter localhost here. When using an icecast2 server, this setting must correspond to the entry in the server's configuration file (/etc/icecast2/icecast.xml by default)
  • Port. The port number for the connection. When using an icecast2 server, this corresponds to the entry in the appropriate section in the server configuration file. The default port number for icecast2 connections is 8000.
  • Mount Point. The name by which the server will identify this stream. Some precautions have to be used: when streaming in OGG/Vorbis format, the mount point should always end with the .ogg extension (e.g. mystream.ogg). Also note that any specific server-side options for this mount point (password, fallback mount, etc.) will have to be specified in the server configuration file under the appropriate section.
  • Password. The source password, as defined by the
    entry in the server configuration file. In the StreamBox distribution, this is set by default to source.
  • Verbosity Level. The greater the number you select here, the greater amount of details will be displayed by pressing the Show Details button.
  • Remote/Local dump file. DarkIce can dump the audio stream to an mp3/ogg file, either on the computer where DarkSnow is running (local dump file) or on the computer where the server is running (remote dump file). If you choose to dump locally, DarkIce can add a date prefix to the filename

Properly setting the values in the secondary tabbed window are much more critical for configuring DarkIce. This tabbed window is named "Audio Options".


  • Format. Select if you want to encode the stream in mp3 or ogg/vorbis format. Ogg/vorbis is recommended, because it is a high-quality fully open software audio codec.
  • Bitrate Mode/Bitrate. Here, you can choose the type of compression and the bitrate that will be applied to your audio stream. Supported compression types are: Constant, Variable, and Average. Constant bitrate is the standard compression method, but it doesn't ensure a high quality level on certain "difficult" (full of details) passages of the audio stream. Variable bitrate produces a higher quality output but can increase the size of the stream, and is not considered appropriate to use when streaming over low-bandwidth connections. Average bitrate is a sort of compromise between the two other algorythms, and is the recommended choice for streaming with the Streambox Live-Cd. If you are in doubt, choose the Average bitrate compression method.
  • SampleRate. Select 22050 for mono (1-channel, radio quality), 44100 for stereo (2-channels, CD quality) streaming. If you are in doubt, choose 22050 sample rate.
  • Quality/Bits per sample. The quality of the encoding can be set using values from 0.1 (minimum quality) to 1.0 (maximum quality). This setting only applies when using Variable bitrate and ogg/vorbis format, or when using Variable or Average bitrate and mp3 format.
  • Number of Channels. Select 1 for mono, 2 for stereo streaming.
  • Buffer Size. This setting specifies how many seconds of audio data should be buffered by DarkIce before starting the encoding process. If in doubt, leave the default setting.
  • Device Input. Here, you select which audio device DarkIce should get its input from. If you are using an OSS sound system, you should select one of the /dev/dsp devices. If you are using ALSA, you should select one of the hw devices. If you are using the JACK sound system, you should select one of the jack devices.

Use the third window to determine which format the streamer will use, mp3 or ogg/Vorbis. This screen also sets the bit and sample rates. Select the bit and buffer as well as the number of channels and the default audio device. The items shown in the screenshot are viable and can be implemented on most any streaming box with DarkIce installed. Most default variables should result in a fully functional DarkIce streaming server.


  • Radio Name/Description/URL/Genre. You can choose a name for your web-radio, enter a short description, publish the URL of your webpage on the Internet, and specify which musical genre you are dealing with.
  • Public. If set to yes, the existence of this stream will be advertised on the server's access page.

Now you can start streaming! Click on the Start Streaming button.

If you can see the message "Streaming Status: Started" on the bottom of the window, then everything has worked fine.

If you see the message "Streaming Status: Stopped", then some error has occurred. Click on the Show Details button to see the debugging messages issued by DarkIce.

If you wish, you can save the configuration settings you just entered. This way, you will be able to load them later if you need to run DarkIce again. To accomplish this, use the Open Configuration / Save Configuration commands under the File menu.

When you quit DarkSnow, you will be prompted if you want to quit DarkIce as well. Remember ! DarkIce is the program which is doing the streaming, so killing DarkIce means to stop streaming to the server. You can choose to quit DarkSnow and leave DarkIce running if you want to continue streaming with the same settings.

If you wish, you can set a username and a password that any listener should supply in order to access the stream. This is done by changing the server configuration file.


Example of darkice.cfg

# sample DarkIce configuration file, edit for your needs before using # see the darkice.cfg man page for details # this section describes general aspects of the live streaming session [general] duration = 0 # duration of encoding, in seconds. # 0 means forever bufferSecs = 5 # size of internal slip buffer, in seconds # this section describes the audio input that will be streamed [input] device = /dev/dsp # OSS DSP soundcard device for the audio input sampleRate = 44100 # sample rate in Hz. try 11025, 22050 or 44100 bitsPerSample = 16 # bits per sample. try 16 channel = 2 # channels. 1 = mono, 2 = stereo # this section describes a streaming connection to an IceCast2 server # there may be up to 8 of these sections, named [icecast2-0] . [icecast2-7] # these can be mixed with [icecast-x] and [shoutcast-x] sections [icecast2-0] bitrateMode = cbr # average bit rate format = mp3 # format of the stream: mp3 bitrate = 128 # bitrate of the stream sent to the server server = test.mydomain.com # host name of the server port = 8000 # port of the IceCast2 server, usually 8000 password = letmein # source password to the IceCast2 server mountPoint = test # mount point of this stream on the IceCast2 server name = mp3 music test # name of the stream description = mp3 music test # description of the stream url = http://test.mydomain.com # URL related to the stream genre = test # genre of the stream public = no # advertise this stream? [icecast2-1] bitrateMode = abr # average bit rate format = vorbis # format of the stream: ogg vorbis quality = 0.8 # encoding quality bitrate = 96 # bitrate of the stream sent to the server server = test.mydomain.com # host name of the server port = 8000 # port of the IceCast2 server, usually 8000 password = letusin # source password to the IceCast2 server mountPoint = test.ogg # mount point of this stream on the IceCast2 server name = ogg vorbis music test # name of the stream description = ogg vorbis music test # description of the stream url = http://test.mydomain.com # URL related to the stream genre = music # genre of the stream public = no # advertise this stream?

In this example, the first section states that the encoding continues forever and that there is an initial 5 second buffer. The next section specifies the device to which DarkIce should look for audio input or in this case, /dev/dsp. Next, set the sample rate. Because streaming music is the format in this example set the sample rate for 44100. The default is 22050. Next, choose the bits per sample. 16 is a good figure to use initially. You may opt to set this to a value of 8 later or when streaming low quality audio. The same applies to the last option; 1 is for mono sound and 2 equates to stereo sound.

The next two sections are designed for custom streams connecting to an icecast2 server. Included with the default distribution file are other sections explaining the connection process to icecast1 and Shoutcast servers.

Choose the default bit rate. If selecting "vbr" for variable bit rate pick a value that defines the desired quality. Select whether to stream in MP3 or Ogg Vorbis format and set the bitrate and the server name. Next, choose the default port. 8000 is the normal default port, 8001 and others can be used just as effectively. This must be the same port number used by the icecast or Shoutcast server and the password must also match that of the icecast server.

Selecting the proper mountpoint can also be a tricky process. If streaming MP3 specify the default name or, as defined in the example configuration, test. When streaming in Ogg Vorbis format add an .ogg suffix to the end of the mountpoint name. This helps the client player decide which codec to use. The name, description and URL variables provide more information regarding the type of stream. The genre variable defines the type of stream. The public variable advertises the stream on public forums so that others can locate this streaming server.