darkice.cfg(5)

📦
version 1.6 · 3 versions
, in alpine 3.24

💖 darkice.cfg — the config file for darkice 💖

okay so this is the darkice.cfg(5) page, like the manpage for the config file that runs DarkIce, the live audio streamer. bestie, this is the whole vibe guide to making darkice do what you want, so buckle up 🎀

🌸 NAME 🌸

darkice.cfg — the configuration file for darkice ✨

🦋 DESCRIPTION 🦋

okay so the config file is literally just sections, and inside every section you've got key = value pairs, separated by spaces and/or tabs. that's the whole thing, no cap 💅

[section1]
# this is a whole line comment
key = value
an ugly key name = long value    # this end is a comment too

[section2]
# this is a whole line comment in section 2
key = value
an ugly key name = long value    # this end is a comment too

so a proper DarkIce config file has these sections, periodt:

  • [general]
  • [input]
  • [icecast-0] … [icecast-7]
  • [icecast2-0] … [icecast2-7]
  • [shoutcast-0] … [shoutcast-7]
  • [file-0] … [file-7]

the order of the sections? doesn't matter even a little bit, slay 💫 but [general] and [input] are required (like, mandatory mandatory), and you need at least one of [icecast-x], [icecast2-x], [shoutcast-x] or [file-x] or else what are you even doing here 😭

specifically, these are the sections and values that get recognized:

✨ [general] ✨

this section is the general operational parameters, and yes it's required 👑

required values:

  • duration — how long DarkIce runs, in seconds. if it's 0, it runs forever and ever and ever 🫶
  • bufferSecs — data read from the sound card gets buffered before it's sent to the encoder. each buffer holds this many seconds of samples.

optional values:

  • reconnect — try to reconnect to the server(s) if the connection breaks mid-stream. "yes" or "no". (optional, defaults to "yes") 🔁
  • realtime — use POSIX realtime scheduling, "yes" or "no". (optional, defaults to "yes") ⏱️
  • rtprio — the scheduling priority for the realtime threads. (optional, defaults to 4)

🎀 [input] 🎀

this section describes the input, and it's required too — no input, no stream, iykyk 🌸

required values:

  • device — specifies the device to record from, which can be an OSS DSP device, an ALSA source, a PulseAudio source, or you can use Jack audio:
    • an OSS DSP audio device to record from (e.g. /dev/dsp)
    • an ALSA DSP device name (e.g. hwplug:0,0)
    • for PulseAudio, use "pulseaudio"
    • the string 'jack', to have an unconnected Jack port, or 'jack_auto' to automatically make Jack connect to the first source.
  • sampleRate — the sample rate to record with, samples per second (e.g. 44100 for 44.1kHz CD-quality audio, 22050 for 22kHz or 11025 for 11kHz) 🎵
  • bitsPerSample — number of bits to use for each sample (e.g. 8 bits or 16 bits)
  • channel — number of channels to record (e.g. 1 for mono, 2 for stereo)
  • jackClientName — the name of the jack input channel created by darkice if device=jack is specified.
  • paSourceName — the name of the PulseAudio source to use. it can be "default", an index, or a device string you get from running "pactl list"

👑 [icecast-x] 👑

this section is an output to an IceCast 1.3.x server or a Darwin Streaming Server, while encoding with a lame encoder. you can have at most 8 outputs, numbered 0 … 7. the number lives in the section name (e.g. [icecast-0] … [icecast-7]). your stream will be reachable at http://<server>:<port>/<mountPoint> 🔥

required values:

  • bitrateMode — the bit rate mode of the encoding, either "cbr", "abr" or "vbr" — standing for constant bit rate, average bit rate and variable bit (rate, respectively). use the bitrate and/or quality values to specify the details of the appropriate bit rate mode.
  • bitrate — bit rate to encode to in kBits / sec (e.g. 96). only used when cbr or abr bit rate modes are specified.
  • quality — the quality of encoding, a value between 0.0 .. 1.0 (e.g. 0.8), with 1.0 being the highest quality. use a value greater than 0.0. only used when cbr or vbr bit rate modes are specified.
  • server — the IceCast server's name (e.g. yp.yourserver.com)
  • port — the port to connect to the IceCast server (e.g. 8000)
  • password — the password to use to connect to the IceCast server
  • mountPoint — mount point for the stream on the server

optional values:

  • sampleRate — the sample rate of the encoded mp3 output. if not specified, defaults to the value of the input sample rate.
  • channel — number of channels for the mp3 output (e.g. 1 for mono, 2 for stereo). if not specified, defaults to the value of the input sample rate. (yes bestie, the page literally says "sample rate" there, we're just reporting the news 🙈)
  • name — name of the stream
  • description — description of the stream
  • url — url related to the stream
  • genre — genre of the stream
  • public — "yes" or "no", whether the stream is public
  • remoteDumpFile — the file the IceCast server should dump the contents of this stream to on its side.
  • localDumpFile — dump the same mp3 data sent to the IceCast server to this local file.
  • fileAddDate — "yes" or "no" if you want to automatically insert a date string in the localDumpFile name before its extension, or at the end of the file name if there's no extension present
  • fileDateFormat — the date format to use for appending the date to the dump file name. defaults to "[%m-%d-%Y-%H-%M-%S]". all format strings acceptable by strftime() can be used, see the strftime man page for details. only applicable if fileAddDate is "true". 🗓️
  • lowpass — lowpass filter setting for the lame encoder, in Hz. frequencies above the specified value will be cut. if not set or set to 0, the encoder's default behaviour is used. if set to -1, the filter is disabled.
  • highpass — highpass filter setting for the lame encoder, in Hz. frequencies below the specified value will be cut. if not set or set to 0, the encoder's default behaviour is used. if set to -1, the filter is disabled.
  • compression — compression level of the FLAC encoder. an integer value between 0 (fast, least compression) and 8 (slow, most compression). if not set, the encoder's default value (5) is used.

🌈 [icecast2-x] 🌈

this section is an output to an IceCast2 server, while encoding with the ogg vobis encoder. at most 8 outputs, numbered 0 … 7, with the number in the section name (e.g. [icecast2-0] … [icecast2-7]). the stream will be reachable at http://<server>:<port>/<mountPoint> ⭐

DarkIce supports both fixed bitrate and variable bitrate vorbis streams. when you're using fixed bitrate, specify the bitrate with the bitrate field. when you're using variable bitrate, specify the quality of the stream with the quality field, which is a value between 0.0 and 1.0 💫

required values:

  • format — format of the stream sent to the IceCast2 server. supported formats are 'vorbis', 'opus', 'flac', 'mp3', 'mp2', 'aac' and 'aacp'.
  • bitrateMode — the bit rate mode of the encoding, either "cbr", "abr" or "vbr", standing for constant bit rate, average bit rate and variable bit (rate) respectively. use the bitrate and/or quality values to specify the details of the appropriate bit rate mode. Ogg Opus only supports 'cbr' and 'abr'.
  • bitrate — bit rate to encode to in kBits / sec (e.g. 96). only used when cbr or abr bit rate modes are specified.
  • quality — the quality of encoding, a value between 0.0 .. 1.0 (e.g. 0.8), with 1.0 being the highest quality. use a value greater than 0.0. only used when vbr bit rate mode is specified for Ogg Vorbis format, or in vbr and abr modes for mp3 and mp2 format.
  • server — the IceCast2 server's name (e.g. yp.yourserver.com)
  • port — the port to connect to the IceCast server (e.g. 8000)
  • password — the password to use to connect to the IceCast2 server
  • mountPoint — mount point for the stream on the server

optional values:

  • sampleRate — the sample rate of the encoded output. if not specified, defaults to the value of the input sample rate. 👀 please note that Ogg Opus only supports 48kHz sample rate, and will resample to this rate.
  • channel — number of channels for the output (e.g. 1 for mono, 2 for stereo). if not specified, defaults to the value of the input sample rate. (again, that's the page's own words, we don't make the rules 😭) different channels for input and output are only supported for mp3, but not for Ogg Vorbis.
  • maxBitrate — the maximum bitrate of the stream. only used when in cbr mode and in Ogg Vorbis format.
  • name — name of the stream
  • description — description of the stream
  • url — url related to the stream
  • genre — genre of the stream
  • public — "yes" or "no", whether the stream is public
  • localDumpFile — dump the same Ogg Vorbis data sent to the IceCast2 server to this local file.
  • fileAddDate — "yes" or "no" if you want to automatically insert a date string in the localDumpFile name before its extension, or at the end of the file name if there's no extension present
  • fileDateFormat — the date format to use for appending the date to the dump file name. defaults to "[%m-%d-%Y-%H-%M-%S]". all format strings acceptable by strftime() can be used, see the strftime man page for details. only applicable if fileAddDate is "true".
  • lowpass — lowpass filter setting for the lame encoder, in Hz. frequencies above the specified value will be cut. if not set or set to 0, the encoder's default behaviour is used. if set to -1, the filter is disabled. only has effect if the mp3 or mp2 format is used.
  • highpass — highpass filter setting for the lame encoder, in Hz. frequencies below the specified value will be cut. if not set or set to 0, the encoder's default behaviour is used. if set to -1, the filter is disabled. only has effect if the mp3 or mp2 format is used.

💜 [shoutcast-x] 💜

this section is an output to a ShoutCast server, while encoding with a lame encoder. at most 8 outputs, numbered 0 … 7, with the number in the section name (e.g. [shoutcast-0] … [shoutcast-7]). the stream will be reachable at http://<server>:<port-1>/ 🎧

required values:

  • bitrateMode — the bit rate mode of the encoding, either "cbr", "abr" or "vbr", standing for constant bit rate, average bit rate and variable bit (rate) respectively. use the bitrate and/or quality values to specify the details of the appropriate bit rate mode.
  • bitrate — bit rate to encode to in kBits / sec (e.g. 96). only used when cbr or abr bit rate modes are specified.

(bestie this is only part 1, there's more coming — don't go anywhere 💅)

Okay so, still rolling through the server-output values — here's the rest of the lineup, bestie:

  • quality — the quality of encoding, a value between 0.0 .. 1.0 (e.g. 0.8), with 1.0 being the highest quality. Use a value greater than 0.0. Only used when cbr or vbr bit rate modes are specified. ✨
  • server — the ShoutCast server's name (e.g. yp.yourserver.com).
  • port — the source port to connect to the ShoutCast server (e.g. 8001).
  • password — the password to use to connect to the ShoutCast server. 🔐

🌸 Optional values 🌸

  • mountPoint — mount point for the stream on the server. Only works on Darwin Streaming Server; the original Shoutcast server does not support mount points. 🫶
  • sampleRate — the sample rate of the encoded mp3 output. If not specified, defaults to the value of the input sample rate.
  • channel — number of channels for the mp3 output (e.g. 1 for mono, 2 for stereo). If not specified, defaults to the value of the input sample rate. (yes, sample rate — that's what it says 💅)
  • name — name of the stream.
  • url — url related to the stream.
  • genre — genre of the stream.
  • public — "yes" or "no", whether the stream is public.
  • irc — IRC information related to the stream.
  • aim — AIM information related to the stream.
  • icq — ICQ information related to the stream.
  • lowpass — lowpass filter setting for the lame encoder, in Hz. Frequencies above the specified value will be cut. If not set or set to 0, the encoder's default behaviour is used. If set to -1, the filter is disabled.
  • highpass — highpass filter setting for the lame encoder, in Hz. Frequencies below the specified value will be cut. If not set or set to 0, the encoder's default behaviour is used. If set to -1, the filter is disabled.
  • localDumpFile — dump the same mp3 data sent to the ShoutCast server to this local file. 🎧
  • fileAddDate — "yes" or "no" if you want to automatically insert a date string in the localDumpFile name before its extension or at the end of file name if no extension present.
  • fileDateFormat — the date format to use for appending the date to the dump file name. Defaults to "[%m-%d-%Y-%H-%M-%S]". All format strings acceptable by strftime() can be used, see the strftime man page for details. Only applicable is fileAddDate is "true".

🎀 [file-x] 🎀

This section describes an output to a local file in either Ogg Vorbis or mp3 format. There may be at most 8 outputs, numbered from 0 ... 7. The number is included in the section name (e.g. [file-0] ... [file-7]). 💖

✨ Required values ✨

  • format — format to encode in. Must be either 'mp3', 'mp2', 'vorbis', 'opus', 'aac' or 'aacp'.
  • bitrateMode — the bit rate mode of the encoding, either "cbr", "abr" or "vbr", standing for constant bit rate, average bit rate and variable bit respectively. Use the bitrate and/or quality values to specify details of the appropriate bit rate mode.
  • bitrate — bit rate to encode to in kBits / sec (e.g. 96). Only used when cbr or abr bit rate modes are specified.
  • quality — the quality of encoding, a value between 0.0 .. 1.0 (e.g. 0.8), with 1.0 being the highest quality. Use a value greater than 0.0. Only used when cbr or vbr bit rate modes are specified.
  • fileName — the name of the local file to save the encoded data into.

🦋 Optional values 🦋

  • sampleRate — the sample rate of the encoded mp3 output. If not specified, defaults to the value of the input sample rate. Only used if the output format is mp3.
  • lowpass — lowpass filter setting for the lame encoder, in Hz. Frequencies above the specified value will be cut. If not set or set to 0, the encoder's default behaviour is used. If set to -1, the filter is disabled. Only used if the output format is mp3.
  • highpass — highpass filter setting for the lame encoder, in Hz. Frequencies below the specified value will be cut. If not set or set to 0, the encoder's default behaviour is used. If set to -1, the filter is disabled. Only used if the output format is mp3.

A sample configuration file follows. This file makes DarkIce stream for 1 minute (60 seconds) from the audio device /dev/dsp at 22.05kHz, 16 bit stereo. It will build up a connection to the IceCast server yp.yourserver.com on port 8000 with the password "hackme". The stream will be encoded to 96 kb/s mp3 with quality 0.8, and will be reachable at http://yp.yourserver.com:8000/live96 to mp3 players. The encoding session will be stored by IceCast in the file /tmp/server-dump.mp3 on the server side, and also by DarkIce in the file /tmp/encoder-dump.mp3 on the encoder side. 🔥

[general]
duration        = 60
bufferSecs      = 5

[input]
device          = /dev/dsp
sampleRate      = 22050
bitsPerSample   = 16
channel         = 2

[icecast-0]
bitrateMode     = cbr
bitrate         = 96
quality         = 0.8
server          = yp.yourserver.com
port            = 8000
password        = hackme
mountPoint      = live96
name            = DarkIce trial
description     = This is only a trial
url             = http://www.yourserver.com
genre           = live
public          = no
remoteDumpFile  = /tmp/server-dump.mp3
localDumpFile   = /tmp/encoder-dump.mp3
fileAddDate     = no

The following sample configuration file simply encodes the 16 bit stereo 44.1 kHz sound card input into Ogg Vorbis at average bit rate 96 kb/s for 60 seconds, and saves it in the local file at /tmp/save.ogg. 🌸

[general]
duration        = 60
bufferSecs      = 5

[input]
device          = /dev/dsp
sampleRate      = 44100
bitsPerSample   = 16
channel         = 2

[file-0]
format          = vorbis
bitrateMode     = abr
bitrate         = 96
fileName        = /tmp/save.ogg

A bit more complicated sample follows. This one makes DarkIce stream for 1 hour (3600 seconds) from the audio device /dev/dsp at 44.1kHz, 16 bit stereo. 👑

It will build up a connection to an IceCast server yp.your-ice-server.com on port 8000 with the password "ice-hackme". The sound for this stream will be cut at 10500 Hz from above. The stream will be encoded to average bit rate 96 kb/s mp3 and resampled to 22.05kHz and 1 channel (mono). The stream will be reachable at http://yp.your-ice-server.com:8000/live96 to mp3 players. The encoding session will be stored by IceCast in the file /tmp/live96.mp3 on the server side. 🦋

It will also connect to a ShoutCast server at yp.your-shout-server.com on port 8001 with the password "shout-hackme" This stream will be encoded to constant bit rate 128 kb/s mp3 with quality 0.8, and will be reachable at http://yp.your-shout-server.com:8000 to mp3 players. 🎀

[general]
duration        = 3600
bufferSecs      = 5

[input]
device          = /dev/dsp
sampleRate      = 22050
bitsPerSample   = 16
channel         = 2

[icecast-0]
sampleRate      = 22050
channel         = 1
bitrateMode     = abr
bitrate         = 96
lowpass         = 10500
server          = yp.your-ice-server.com
port            = 8000
password        = ice-hackme
mountPoint      = live96
name            = DarkIce trial
description     = This is only a trial
url             = http://www.yourserver.com
genre           = live
public          = yes
remoteDumpFile  = /tmp/live96.mp3

[shoutcast-0]
bitrateMode     = cbr
bitrate         = 128
quality         = 0.8
server          = yp.your-shout-server.com
port            = 8001
password        = shout-hackme
name            = DarkIce trial
url             = http://www.yourserver.com
genre           = live
public          = yes
irc             = irc.yourserver.com
aim             = aim here
icq             = I see you too

💀 BUGS 💀

Lots of bugs. That's it. That's the section. 😭

👀 SEE ALSO 👀

💖 AUTHOR 💖

Akos Maroy <darkeye@tyrell.hu>

💖 And that's the whole darkice.cfg(5) from DarkIce, dated April 3, 2024 — slay, bye bestie! 💖

📦 where this page comes from