/usr/share/doc/liquidsoap/html/encoding_formats.html is in liquidsoap 1.0.0-4build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 | <?xml version="1.0"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML \
1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
<meta content="text/html; charset=UTF-8" http-equiv="content-type" />
<title>Liquidsoap :: Encoding formats</title>
<link href="style.css" type="text/css" rel="stylesheet" />
<link href="homepage.css" type="text/css" rel="stylesheet" />
</head>
<body>
<div id="wrapper">
<div id="header">
<div id="logo">
<h1>Liquidsoap</h1>
<h2>audio stream generation</h2>
</div>
<div>
<ul id="menu">
<li id="menu-about">
<a href="index.html">about</a></li>
<li id="menu-doc-index">
<a href="documentation.html">documentation</a></li>
<li id="menu-doc-api">
<a href="reference.html">API</a></li>
<li id="menu-doc-snippets">
<a href="scripts/index.html">snippets</a></li>
<li id="menu-developers">
<a href="http://savonet.rastageeks.org/">developers</a></li>
</ul>
</div>
</div>
<div id="content"><div>
<p>
Since after version 0.9.3, liquidsoap has decoding formats. These are
special values describing how to encode raw data.
Practically, this means that instead of writing:
</p>
<pre>output.icecast.vorbis(quality=0.3,samplerate=44100,...)
</pre>
<p>
you shall now write:
</p>
<pre>output.icecast(%vorbis(quality=0.3,samplerate=44100),etc)
</pre>
<p>
The same goes for <code>output.file</code> and for other formats.
</p>
<h3>List of formats and their syntax</h3>
<p>
All parameters are optional, and the parenthesis are not needed
when no parameter is passed. In the following default values
are shown.
As a special case, the keywords <code>mono</code> and <code>stereo</code> can be used to indicate
the number of channels (whether is is passed as an integer or a boolean).
</p>
<h4>MP3</h4>
<p>
Mp3 encoder comes in 3 flavors:
</p>
<ul>
<li>
<code>%mp3</code> or <code>%mp3.cbr</code>: Constant bitrate encoding</li>
<li>
<code>%mp3.vbr</code>: Variable bitrate, quality-based encoding.</li>
<li>
<code>%mp3.abr</code>: Average bitrate based encoding.</li>
</ul>
<p>
Parameters common to each flavor are:
</p>
<ul>
<li>
<code>stereo=true/false</code>, <code>mono=true/false</code>: Encode stereo or mono data (default: <code>stereo</code>).</li>
<li>
<code>samplerate=44100</code>: Encoded data samplerate (default: <code>44100</code>)</li>
<li>
<code>id3v2=true</code>: Add an <code>id3v2</code> tag to encoded data (default: <code>false</code>). This option is only valid if liquidsoap has been compiled with taglib support. </li>
</ul>
<p>
Parameters for <code>%mp3</code> are:
</p>
<ul>
<li>
<code>bitrate</code>: Encoded data fixed bitrate</li>
</ul>
<p>
Parameters for <code>%mp3.vbr</code> are:
</p>
<ul>
<li>
<code>quality</code>: Quality of encoded data; ranges from <code>0</code> (highest quality) to <code>9</code> (worst quality).</li>
</ul>
<p>
Parameters for <code>%mp3.abr</code> are:
</p>
<ul>
<li>
<code>bitrate</code>: Average bitrate</li>
<li>
<code>min_bitrate</code>: Minimun bitrate</li>
<li>
<code>max_bitrate</code>: Maximun bitrate</li>
<li>
<code>hard_min</code>: Enforce minimal bitrate</li>
</ul>
<p>
Examples:
</p>
<ul>
<li>
Contstant <code>128</code> kbps bitrate encoding: <code>%mp3(bitrate=128)</code></li>
<li>
Variable bitrate with quality <code>6</code> and samplerate of <code>22050</code> Hz: <code>%mp3.vbr(quality=7,samplerate=22050)</code></li>
<li>
Average bitrate with mean of <code>128</code> kbps, maximun bitrate <code>192</code> kbps and <code>id3v2</code> tags: <code>%mp3.abr(bitrate=128,max_bitrate=192,id3v2=true)</code></li>
</ul>
<p>
Additionaly, liquidsoap inserts a message within mp3 data. Currently, this message is: <code>"Liquidsoap/1.0.0-beta3 (Unix; OCaml 3.12.0)"</code>.
We plan on using this data for flows and other services involving liquidsoap. You can set its value using the <code>msg</code> parameter.
Setting it to <code>""</code> disables this feature.
</p>
<h4>WAV</h4>
<pre>%wav(stereo=true, channels=2, samplesize=16, header=true, duration=10.)
</pre>
<p>
If <code>header</code> is <code>false</code>, the encoder outputs raw PCM. <code>duration</code> is optional
and is used to set the WAV length header.
</p>
<p>
Because Liquidsoap encodes a possibly infinite stream, there
is no way to know in advance the duration of encoded data. Since WAV header
has to be written first, by default its length is set to the maximun possible
value. If you know the expected duration of the encoded data and you actually
care about the WAV length header then you should use this parameter.
</p>
<h4>Ogg</h4>
<p>
The following formats can be put together in an Ogg container.
The syntax for doing so is <code>%ogg(x,y,z)</code> but it is also
possible to just write <code>%vorbis(...)</code>, for example, instead
of <code>%ogg(%vorbis(...))</code>.
</p>
<h5>Vorbis</h5>
<pre># Variable bitrate
%vorbis(samplerate=44100, channels=2, quality=0.3)
% Average bitrate
%vorbis.abr(samplerate=44100, channels=2, bitrate=128, max_bitrate=192, min_bitrate=64)
# Constant bitrate
%vorbis.cbr(samplerate=44100, channels=2, bitrate=128)
</pre>
<p>
Quality ranges from -0.2 to 1,
but quality -0.2 is only available with the aotuv implementation of libvorbis.
</p>
<h5>Theora</h5>
<pre>%theora(quality=40,width=w,height=h,
picture_width=w,picture_height=h,
picture_x=0, picture_y=0,
aspect_numerator=1, aspect_denominator=1,
keyframe_frequency=64, vp3_compatible=false,
soft_target=false, buffer_delay=0.1,
speed=0)
</pre>
<p>
You can also pass <code>bitrate=x</code> explicitly instead of a quality.
The default dimensions are liquidsoap's default,
from the settings <code>frame.video.height/width</code>.
</p>
<h5>Dirac</h5>
<pre>%dirac(quality=35,width=w,height=h,
picture_x=0, picture_y=0,
aspect_numerator=1, aspect_denominator=1)
</pre>
<h5>Speex</h5>
<pre>%speex(stereo=false, samplerate=44100, quality=7,
mode=[wideband|narrowband|ultra-wideband],
frames_per_packet=1,
complexity=none)
</pre>
<p>
You can also control quality using <code>abr=x</code> or <code>vbr=y</code>.
</p>
<h5>Flac</h5>
<p>
The flac encoding format comes in two flavors:
</p>
<ul>
<li>
<code>%flac</code> is the native flac format, useful for file output but not for streaming purpose</li>
<li>
<code>%ogg(%flac,...)</code> is the ogg/flac format, which can be used to broadcast data with icecast</li>
</ul>
<p>
The parameters are:
</p>
<pre>%flac(samplerate=44100,
channels=2,
compression=5,
bits_per_sample=16)
</pre>
<p>
<code>compression</code> ranges from 0 to 8 and <code>bits_per_sample</code> should be one of: <code>8</code>, <code>16</code> or <code>32</code>.
</p>
<h4>AAC</h4>
<p>
The syntax for the internal AAC encoder is:
</p>
<pre>%aac(channels=2, samplerate=44100, bitrate=64, adts=true)
</pre>
<h4>AAC+</h4>
<p>
The syntax for the internal AAC+ encoder is:
</p>
<pre>%aacplus(channels=2, samplerate=44100, bitrate=64)
</pre>
<h4>External encoders</h4>
<p>
For a detailed presentation of external encoders, see <a href="external_encoders.html">this page</a>.
</p>
<pre>%external(channels=2,samplerate=44100,header=true,
restart_on_crash=false,
restart_on_new_track,
restart_after_delay=<int>,
process="")
</pre>
<p>
Only one of <code>restart_on_new_track</code> and <code>restart_after_delay</code> should
be passed. The delay is specified in seconds.
The encoding process is mandatory, and can also be passed directly
as a string, without <code>process=</code>.
</p>
<h3>Formats determine the stream content</h3>
<p>
In most liquidsoap scripts, the encoding format determines what
kind of data is streamed.
</p>
<p>
The type of an encoding format depends on its parameter.
For example, <code>%mp3</code> has type <code>format(audio=2,video=0,midi=0)</code>
but <code>%mp3(mono)</code> has type <code>format(audio=1,video=0,midi=0)</code>.
</p>
<p>
The type of an output like <code>output.icecast</code>
or <code>output.file</code> is something like
<code>(...,format('a),...,source('a))->source('a)</code>.
This means that your source will have to have the same type as your format.
</p>
<p>
For example if you write
<code>output.file(%mp3,"/tmp/foo.mp3",playlist("~/audio"))</code>
then the playlist source will have to stream stereo audio.
Thus it will reject mono and video files.
</p>
<h3>Technical details</h3>
<p>
You can store an atomic format in a variable, it is a value like another:
<code>fmt = %mp3</code>. However, an atomic format is an atomic constant despite its
appearance. You cannot use a variable for one of its parameters: for
example
</p>
<pre>x = 44100
%vorbis(samplerate=x)
</pre>
<p>
is not allowed,
you must write <code>%vorbis(samplerate=44100)</code>.
</p>
<p>
In programming languages like ML, the typing of <code>printf</code> is a bit special.
Alone, <code>printf</code> has an esoteric type. Together with its parameter, it
takes a meaningful type, for example <code>printf "An integer: %d\n"</code> has type
<code>int -> unit</code>. So, the format string <code>"An integer: %d\n"</code> is not a string
at all, it has a more complex type, and cannot be manipulated as a string.
Our encoding formats have a similar role, hence the symbol <code>%</code>.
</p>
</div></div>
<div>
<div id="footer"> 2003-2011 Savonet team</div>
</div>
</div>
</body></html>
|