-
-
Notifications
You must be signed in to change notification settings - Fork 128
/
encoding_formats.txt
253 lines (191 loc) · 8.58 KB
/
encoding_formats.txt
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
title: Encoding formats
h3. Presentation
Encoders are used to define formats into which raw sources should be encoded by
an output. Syntax for encoder is: @%encoder(parameters...)@ or, if you use
default parameters, @%encoder@.
h4. Formats determine the stream content
In most liquidsoap scripts, the encoding format determines what
kind of data is streamed.
The type of an encoding format depends on its parameter.
For example, @%mp3@ has type @format(audio=2,video=0,midi=0)@
but @%mp3(mono)@ has type @format(audio=1,video=0,midi=0)@.
The type of an output like @output.icecast@
or @output.file@ is something like
@(...,format('a),...,source('a))->source('a)@.
This means that your source will have to have the same type as your format.
For example if you write
@output.file(%mp3,"/tmp/foo.mp3",playlist("~/audio"))@
then the playlist source will have to stream stereo audio.
Thus it will reject mono and video files.
Liquidsoap provides operators that can be used to convert sources
into a format acceptable for a given encoder. For instance, the @mean@
operator transforms any audio source into a mono source and the @audio_to_stereo@
operator transforms any audio source into a stereo source.
h4. Format variables (or lack of, rather..)
You can store an atomic format in a variable, it is a value like another:
@fmt = %mp3@. However, an atomic format is an atomic constant despite its
appearance. You cannot use a variable for one of its parameters: for
example
%%
x = 44100
%vorbis(samplerate=x)
%%
is not allowed,
you must write @%vorbis(samplerate=44100)@.
If you really need to use variables in encoder, for instance if bitrate is given by
a user's configuration, you may alleviate that by generating a pre-defined list of possible
encoders and include it on top of your script using the @%include@ directive.
h3. List of formats and their syntax
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 @mono@ and @stereo@ can be used to indicate
the number of channels (whether is is passed as an integer or a boolean).
h4. MP3
Mp3 encoder comes in 3 flavors:
* @%mp3@ or @%mp3.cbr@: Constant bitrate encoding
* @%mp3.vbr@: Variable bitrate, quality-based encoding.
* @%mp3.abr@: Average bitrate based encoding.
Parameters common to each flavor are:
* @stereo=true/false@, @mono=true/false@: Encode stereo or mono data (default: @stereo@).
* @stereo_mode@: One of: @"stereo"@, @"joint_stereo"@ or @"default"@ (default: @"default"@)
* @samplerate=44100@: Encoded data samplerate (default: @44100@)
* @internal_quality=2@: Lame algorithms internal quality. A value between @0@ and @9@, @0@ being highest quality and @9@ the worst (default: @2@).
* @id3v2=true@: Add an @id3v2@ tag to encoded data (default: @false@). This option is only valid if liquidsoap has been compiled with taglib support.
Parameters for @%mp3@ are:
* @bitrate@: Encoded data fixed bitrate
Parameters for @%mp3.vbr@ are:
* @quality@: Quality of encoded data; ranges from @0@ (highest quality) to @9@ (worst quality).
Parameters for @%mp3.abr@ are:
* @bitrate@: Average bitrate
* @min_bitrate@: Minimun bitrate
* @max_bitrate@: Maximun bitrate
* @hard_min@: Enforce minimal bitrate
Examples:
* Contstant @128@ kbps bitrate encoding: @%mp3(bitrate=128)@
* Variable bitrate with quality @6@ and samplerate of @22050@ Hz: @%mp3.vbr(quality=7,samplerate=22050)@
* Average bitrate with mean of @128@ kbps, maximun bitrate @192@ kbps and @id3v2@ tags: @%mp3.abr(bitrate=128,max_bitrate=192,id3v2=true)@
Optionally, liquidsoap can insert a message within mp3 data. You can set its value using the @msg@ parameter.
Setting it to @""@ disables this feature. This is its default value.
h4. WAV
%%
%wav(stereo=true, channels=2, samplesize=16, header=true, duration=10.)
%%
If @header@ is @false@, the encoder outputs raw PCM. @duration@ is optional
and is used to set the WAV length header.
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.
h4. Ogg
The following formats can be put together in an Ogg container.
The syntax for doing so is @%ogg(x,y,z)@ but it is also
possible to just write @%vorbis(...)@, for example, instead
of @%ogg(%vorbis(...))@.
h5. Vorbis
%%
# 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)
%%
Quality ranges from -0.2 to 1,
but quality -0.2 is only available with the aotuv implementation of libvorbis.
h5. Opus
Opus is a lossy audio compression made especially suitable for interactive real-time applications
over the Internet. Liquidsoap supports Opus data encapsulated into Ogg streams.
The encoder is named @%opus@ and its parameters are as follows. Please refer
to the "Opus documentation":http://www.opus-codec.org/docs/ for information about
their meanings and values.
* @vbr@: one of @"none"@, @"constrained"@ or @"unconstrained"@
* @application@: One of @"audio"@, @"voip"@ or @"restricted_lowdelay"@
* @complexity@: Integer value between @0@ and @10@.
* @max_bandwidth@: One of @"narrow_band"@, @"medium_band"@, @"wide_band"@, @"super_wide_band"@ or @"full_band"@
* @samplerate@: input samplerate. Must be one of: @8000@, @12000@, @16000@, @24000@ or @48000@
* @frame_size@: encoding frame size, in milliseconds. Must be one of: @2.5@, @5.@, @10.@, @20.@, @40.@ or @60.@.
* @bitrate@: encoding bitrate, in @kbps@. Must be a value between @5@ and @512@. You can also set it to @"auto"@.
* @channels@: currently, only @1@ or @2@ channels are allowed.
* @mono@, @stereo@: equivalent to @channels=1@ and @channels=2@.
* @signal@: one of @"voice"@ or @"music"@
h5. Theora
%%
%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)
%%
You can also pass @bitrate=x@ explicitly instead of a quality.
The default dimensions are liquidsoap's default,
from the settings @frame.video.height/width@.
h5. Dirac
%%
%dirac(quality=35,width=w,height=h,
picture_x=0, picture_y=0,
aspect_numerator=1, aspect_denominator=1)
%%
h5. Speex
%%
%speex(stereo=false, samplerate=44100, quality=7,
mode=[wideband|narrowband|ultra-wideband],
frames_per_packet=1,
complexity=none)
%%
You can also control quality using @abr=x@ or @vbr=y@.
h5. Flac
The flac encoding format comes in two flavors:
* @%flac@ is the native flac format, useful for file output but not for streaming purpose
* @%ogg(%flac,...)@ is the ogg/flac format, which can be used to broadcast data with icecast
The parameters are:
%%
%flac(samplerate=44100,
channels=2,
compression=5,
bits_per_sample=16)
%%
@compression@ ranges from 0 to 8 and @bits_per_sample@ should be one of: @8@, @16@ or @32@.
h4. AAC
The syntax for the internal AAC encoder is:
%%
%aac(channels=2, samplerate=44100, bitrate=64, adts=true)
%%
h4. AAC+
The syntax for the internal AAC+ encoder is:
%%
%aacplus(channels=2, samplerate=44100, bitrate=64)
%%
h4. Gstreamer
The @%gstreamer@ encoder can be used to encode streams using the @gstreamer@ multimedia framework.
This encoder extends liquidsoap with all available GStreamer formats which includes most, if not all,
formats available to your operating system.
The encoder's parameters are as follows:
%%
%gstreamer(channels=2,
audio="lamemp3enc",
has_video=true,
video="x264enc",
muxer="mpegtsmux",
metadata="metadata",
log=5,
pipeline="")
%%
Please refer to the "Gstreamer encoder":gstreamer_encoder.html page for a detailed explanation
of this encoder.
h4. External encoders
For a detailed presentation of external encoders, see "this page":external_encoders.html.
%%
%external(channels=2,samplerate=44100,header=true,
restart_on_crash=false,
restart_on_new_track,
restart_after_delay=<int>,
process="")
%%
Only one of @restart_on_new_track@ and @restart_after_delay@ should
be passed. The delay is specified in seconds.
The encoding process is mandatory, and can also be passed directly
as a string, without @process=@.