1
'\" -*- coding: us-ascii -*-
3
.if \n(.g .ds T> \\F[\n[.fam]]
7
.if \n(.g .mso www.tmac
8
.TH entrans 1 0.10.2 "" ""
10
entrans \- build and run GStreamer pipeline
16
.if (\nx>(\n(.l/2)) .nr x (\n(.l/5)
18
[OPTION]\&... {--} {PIPELINE-OPTION}\&...
23
\fBentrans\fR builds and runs a GStreamer pipeline, primarily intended for
24
transcoding, encoding or recording purposes.
26
On the one hand, it is much like
27
\fBgst-launch\fR(1) in that it has no ambitions to go beyond command-line
28
(or script) driven processing.
30
On the other hand, it has quite a few enhancements that provide application-level
31
functionality sufficiently comfortable and suitable for
32
plain-and-simple (and robust) transcoding, encoding or recording
33
using the GStreamer framework and plugins:
36
Pipeline to run can be specified manually, or can be built dynamically
37
based on inputstream and pipeline fragments
38
(see OPERATION), which takes
39
care of most of the boilerplate (and of some pitfalls to watch out for
40
with transcoding pipelines, see also MUXING PIPELINES).
43
Provides some typically relevant (configurable) interesting info
44
regarding the pipeline (elements, properties, queues, \&...) and
45
caps flowing in pipeline.
48
Regular progress updates are provided.
51
Limited support for tag setting (whenever a
52
\*(T<TagSetter\*(T> is present).
55
Property configuration support; settings can be applied from what is
56
stored in a config file and there is also some custom support for
57
setting popular options (e.g. bitrate).
60
Last but not least (convenient), processing can be restricted to
61
specific portions of the input(stream) (mind REQUIREMENTS).
64
Graceful shutdown of processing at any time,
65
and still well-formed output as result
68
Another (technical) difference is that it is written
70
.URL http://www.python.org/ python
72
using the python bindings for the GStreamer framework (gst-python),
73
which makes many of the enhancements much more comfortable to implement
74
and easy to adjust (to taste).
76
As already alluded to above, \fBentrans\fR fundamentally operates
77
in one of the following ways, also loosely called modes:
81
The pipeline to construct, run and manage is explictly given
82
manually (see \*(T<\fB\-\-raw\fR\*(T>).
83
On the one hand, this mode allows full freedom in
84
pipeline construction and can be great for diagnosing and
86
On the other hand, if this freedom is not properly used, all sorts
87
of things can go wrong (blocking, \&...) see MUXING PIPELINES and
88
REQUIREMENTS [do not even try to run in this mode if what is stated
89
there is not fully clear and understood].
90
For now, this mode is also required for performing
91
e.g. video-passthrough transcoding (perhaps more appropriately
92
called re-muxing in this case).
97
is applied to the inputstream, which will
98
automagically provide all the streams present in the input in
99
their decoded raw (video, audio or other, e.g. text) form.
100
Each of these streams is then connected to an instance of a pipeline
101
(fragment) given by \*(T<\fB\-\-video\fR\*(T>, \*(T<\fB\-\-audio\fR\*(T>
102
or \*(T<\fB\-\-other\fR\*(T>, each typically containing filters and/or
103
encoder. An optional subsequent step is trying to connect this to an
104
appropriately selected muxer for the output.
106
In any case, no (advanced) error processing or sane-ness checking
107
is performed on either pipeline or pipeline fragments.
108
As such, linking, negotiation or other matters can very well fail,
109
e.g. if fragments do not contain encoder elements that are compatible
110
with the muxer in question. It is also possible for some
111
parts of the pipeline to simply remain disconnected and
112
the corresponding stream being effectively discarded (this might
113
also be used as a feature ;-) ).
114
Reporting on any of these occurrences is of course done in as much
115
as the pipeline provides info on what is happening.
117
Though this may sound ominous, in practice, this comes down to
118
either things working out just nicely
119
or finding out about something going wrong in a more or less fast and
121
Having a look at EXAMPLES should increases chances on the former
122
being the case, and should even provide enough for a jump-start based on some
123
GStreamer experience.
125
Processing can be halted at any time by sending a \*(T<SIGINT\*(T>
126
or \*(T<SIGTERM\*(T> signal to \fBentrans\fR.
127
This will make \fBentrans\fR block the data-flow and send an end-of-stream event
128
through the pipeline to ensure graceful termination of streaming.
129
As such, it should be noted that termination may not occur instantly,
130
it might take a moment for things to run out
131
(particularly with some \fIqueue\fRs around).
133
If in rare cases this mechanism were to fail, sending such a signal
134
a second time will forego any attempts at graceful shutdown
135
and will make \fBentrans\fR end things the hard way with \fIno\fR
136
guarantee on the output being \fIfully\fR OK
137
(it will most likely not be) \&...
142
Due to the way the python interpreter handles signals,
143
even the above may not work if things are messed up \fIseriously\fR,
144
e.g. when python interpreter is caught up somewhere in GStreamer backend code.
145
This, however, has only been known to happen as a prelude
146
to finding some serious application bug or GStreamer plugin/core bug.
147
Regardless, e.g. \*(T<SIGKILL\*(T> is then your friend \&...
150
\fBentrans\fR accepts the options presented in the following sections,
151
most of which have shortname (one-letter) or longname forms.
152
The ordering of the options is not strict, and options can be single-valued
156
In the former case, which is the default unless otherwise
157
indicated below, only the value given last is retained.
158
In particular, this includes boolean options.
159
If such an option is given, the corresponding setting is turned on.
160
The setting can also be explictly turned off
161
by providing the corresponding
162
\*(T<\fB\-\-no\-\fR\*(T>\fIlongname\fR option.
165
Otherwise, for multi-valued options, all values given are taken into
167
In these cases, it may sometimes also be possible to pass several values per
168
single option occurrence, by comma-separating these values as indicated in each
169
such case below. This will typically be the case in those instances where there
170
can be no ambiguity since the supplied value does not include
173
\*(T<\fB\-h\fR\*(T>, \*(T<\fB\-\-help\fR\*(T>
174
Show a brief help message.
175
.SS "PIPELINE OPTIONS"
176
At least one of the following options should be provided
177
following \*(T<\fB\-\-\fR\*(T> (in each case, see \fBgst-launch\fR(1) for
178
the syntax of \fIpipeline-description\fR).
179
Clearly, as explained previously, the former option excludes
180
all of the latter ones.
182
\*(T<\fB\-\-raw \fR\*(T>\fIpipeline-description\fR
183
Makes \fBentrans\fR run in raw mode, and provides
184
the complete pipeline for this mode of operation.
186
Again, this should be used with expertise and being aware of comments
187
in MUXING PIPELINES and REQUIREMENTS.
189
\*(T<\fB\-\-video\fR\*(T>\*(T<\fB[:\fIstreamnumber\fB]\fR\*(T>\*(T<\fB \fR\*(T>\fIpipeline-description\fR
190
\fIpipeline-description\fR
191
describes a pipeline fragment for video data processing,
192
typically consisting of 0 or more filters followed by an encoder.
194
\*(T<\fB\-\-audio\fR\*(T>\*(T<\fB[:\fIstreamnumber\fB]\fR\*(T>\*(T<\fB \fR\*(T>\fIpipeline-description\fR
195
Similar to \*(T<\fB\-\-video\fR\*(T>, except that it provides
196
a pipeline for (optionally) processing and encoding audio data.
198
\*(T<\fB\-\-other\fR\*(T>\*(T<\fB[:\fIstreamnumber\fB]\fR\*(T>\*(T<\fB \fR\*(T>\fIpipeline-description\fR
199
Similar to the above options, except that it provides
200
a pipeline for (optionally) processing and/or encoding data
201
that does not fit in the above categories, e.g. subtitles.
203
\*(T<\fB\-\-decoder \fR\*(T>\fIdecoder-factory\fR
204
Use \fIdecoder-factory\fR instead of
205
the default \fIdecodebin\fR to construct the decoding
206
part of the pipeline in dynamic mode (as mentioned earlier).
207
The given element should have compatible behaviour/signals
208
with \fIdecodebin\fR, such as for instance the
209
new experimental \fIdecodebin2\fR.
211
The above (partial) pipelines should typically have an encoder as last
212
element. In any case, it should best not be a generic element, as that
213
might cause confusion as to how to link to the muxer (see also
216
It is also possible to close any of the above
217
pipeline fragments by ending it with a sink element. In this case,
218
the resulting stream will not be muxed and each can
219
have independent output, e.g. streamed to a file.
220
As each of these would evidently need to have distinct names,
221
there is (extremely) limited support for variable substitutions.
222
Each (video and audio) stream that dynamically becomes available is
223
(independently) numbered, starting from 1, and as such
224
assigned an (audio or video) stream number.
225
Any element property of type \*(T<string\*(T> will be
226
subject to having \*(T<${vn}\*(T>, \*(T<${an}\*(T>
227
and \*(T<${on}\*(T> replaced by the video, audio and other
228
stream number (at that time) respectively in video, audio or other
230
If any of the above have a \fIstreamnumber\fR appended,
231
then that fragment will only apply to that particular stream, otherwise
232
it will be the default fragment. If no specific or default fragment
233
has been provided for a particular stream, then that stream will be discarded.
234
This effect is similar to the use of \*(T<\fB\-\-vn\fR\*(T>, \*(T<\fB\-\-an\fR\*(T>
235
or \*(T<\fB\-\-on\fR\*(T> (see next section).
237
As an additional convenience, all (partial) pipelines passed to \fBentrans\fR
238
will perform a simple form of glob-expansion for raw video and
239
audio mimetypes in capsfilters. That is, e.g. \*(T<video/*\*(T>
240
will be expanded to raw video mimetypes
241
(also distributing properties if any, of course).
242
This allows e.g. for scaling without particular attention for what colorspace
243
may be in use at a particular stage.
244
.SS "INPUT/OUTPUT OPTIONS"
245
The option in this section are only applicable
246
in dynamic mode, so incompatible with \*(T<\fB\-\-raw\fR\*(T>.
248
\*(T<\fB\-i \fR\*(T>\fIuri\fR, \*(T<\fB\-\-input \fR\*(T>\fIuri\fR
249
Indicates the input source. If \fIuri\fR is a
250
valid URI, then a proper source element will be selected, otherwise it is simply
251
taken as a (relative) path of an inputfile. If \fIuri\fR is
252
\*(T<\-\*(T>, then stdin will be used as input.
254
\*(T<\fB\-o \fR\*(T>\fIuri\fR, \*(T<\fB\-\-output \fR\*(T>\fIuri\fR
255
Indicates the output destination. If \fIoutput\fR is a
256
valid URI, then a corresponding sink element is selected, otherwise
257
it is taken as a (relative) path of an outputfile
258
(output to stdout is not supported).
259
The (file)suffix of \fIuri\fR is used to automagically
260
choose an appropriate muxer, which can be overridden with
261
\*(T<\fB\-\-muxer\fR\*(T>
263
\*(T<\fB\-\-muxer \fR\*(T>\fImux-element\fR
264
Use \fImux-element\fR in stead of the automatically
265
selected one, or if one fails to be auto-selected.
266
\fImux-element\fR must be of \*(T<Muxer\*(T> class.
268
As mentioned in the previous section, all streams found in the input are
269
assigned a stream number and considered for processing, unless somehow
270
restricted by the following options.
273
\*(T<\fB\-\-vn \fR\*(T>\fIstreamnumber[,\&...]\fR, \*(T<\fB\-\-an \fR\*(T>\fIstreamnumber[,\&...]\fR, \*(T<\fB\-\-on \fR\*(T>\fIstreamnumber[,\&...]\fR
274
[multi-valued] Only the video, audio or other streams with (respectively) listed
275
\fIstreamnumber\fR will be considered, others disregarded.
276
Furthermore, streams of each type will be muxed into the target in the order
277
in which their \fIstreamnumber\fRs are given in these options,
278
and in overall first video, then audio and others.
280
\*(T<\fB\-\-sync\-link\fR\*(T>
281
This option is mainly meant for testing and diagnostic purposes.
282
It basically disables the stream(re)-ordering mechanism as implied by and
283
explained in the above option (though still retains stream selection).
285
\*(T<\fB\-\-at \fR\*(T>\fItag[,\&...]\fR
286
[multi-valued] Audio streams can (though need not) be accompanied by a language tag
287
(typically a 2- or 3-letter language code). The regular expression
289
is matched against each detected audio stream's language tag and only
290
streams without language tag or streams with a matching language tag are
291
processed, others disregarded. This selection method \fIcannot\fR
292
be combined with the above streamnumber based selection.
297
The current (or another?) method of
298
implementing this selection may very well not work with all muxer elements. As
299
such, this option can be given a try, but if not successful, the much more
300
robust \*(T<\fB\-\-an\fR\*(T> should be used instead. The proper
301
number(s) to use for this may be derived from (ordered) tag information that is
302
provided by some elements and reported at start-up.
305
\*(T<\fB\-\-stamp\fR\*(T>
306
This is enabled by default, and makes \fBentrans\fR insert an \fIidentity\fR element
307
(with single-segment True) before the connected pipeline-fragment
308
to perform timestamp re-sequencing. This is typically useful when
309
muxing into a format that records timestamps (and does not hurt
310
when the format does not).
312
Whereas no specific dependencies exist for all other options,
313
the REQUIREMENTS section applies particularly
314
to the following options (in more or less degree).
316
\*(T<\fB\-c \fR\*(T>\fI[[(]format[)]:]t1-t2[,\&...]\fR, \*(T<\fB\-\-cut \fR\*(T>\fI[[(]format[)]:]t1-t2[,\&...]\fR
318
Only process the indicated sections of the pipeline (by default the complete
319
input is processed). The option \*(T<\fB\-s\fR\*(T> determines the method used
320
for selecting the desired data.
322
If no \fIformat\fR is provided,
323
the \fItN\fR parameters can be given in timecode format
324
HH:MM:SS.FRACTION or as a (video)framenumber, which is a number following
325
\*(T<f\*(T> or \*(T<F\*(T>. Any buffer that
326
overlaps with the indicated section is taken into account. The last indicated
327
section may be open-ended, i.e. the end point may be omitted.
330
However, if \fIformat\fR is the nickname of a pre-defined
331
or custom format (defined by some element in the pipeline), then it is used as
332
unit for the \fItN\fR numbers.
333
In this case, option \*(T<\fB\-s\fR\*(T> below must select a seek-based method,
334
and the seek will be executed in \fIformat\fR if it is provided
335
without matching (\&...), otherwise the given units will be (query) converted
336
to time format first, and these results will be used to seek in time.
338
\*(T<\fB\-s \fR\*(T>\fImethod\fR, \*(T<\fB\-\-section \fR\*(T>\fImethod\fR
339
Possible choices for \fImethod\fR are:
343
Sections are selected by means of regular GStreamer seeks.
344
A flushing seek is performed for the first section,
345
segment seek for the others, and a normal seek for the last section.
346
This is also the default method and is OK for most circumstances.
347
In some cases, however, the other methods may be in order,
348
e.g. when (the driving element in) the pipeline does not support
349
some type of seek that would be used.
352
This is similar to the case above, but each seek is also a keyframe seek,
353
that is, the actual selection may not be exactly the one
354
that was requested but may start at the nearest keyframe
355
preceding the desired start.
356
This would typically be required when performing re-muxing
357
without fully decoding and re-encoding the material.
360
In this case, the pipeline is run from the start (without any seeks)
361
and all but the desired sections are disregarded.
362
The decision whether or not to drop a piece of data is based on its timestamp.
363
This is the recommended (only possible) method to use
364
when performing A/V sync correction using data-timestamp shifting,
365
e.g. by means of the \fIshift\fR element. It can also be used
366
to end a live source(s) driven pipeline after a specified duration.
369
This method applies in case any/all of the above fail, e.g. some element
370
does not support seek or unreliable timestamps are produced in the pipeline.
371
No seeks or anything special is done, the pipeline is run from the start and all but the
372
indicated sections is dropped. Timestamps on the datastream are disregarded,
373
and the incoming data is restamped based on framecount and framerate
374
(video), or on sample count and samplerate (audio).
375
In particular, audio cutting is performed up to sample precision.
378
Note that the last 2 methods require the desired sections to be in ascending
379
order, whereas the former methods make it possible to select sections
380
that are out-of-order with regards to the input material.
383
Perform (audio) sample precision selection, that is, it is possible for only parts of
384
buffers to be passed or dropped. This is done by default
385
in the \*(T<cut\*(T> method above, but not for the other methods.
387
\*(T<\fB\-\-dam\fR\*(T>
388
Indicate, or rather, confirm that \fIdam\fR elements are being used
389
in \fIraw\fR pipelines.
390
Otherwise, surrogate dam elements will be searched for and used instead.
391
These are identified as elements whose name is of the form
392
\*(T<dam\fI<digits>\fR\*(T>.
394
\*(T<\fB\-f \fR\*(T>\fIframerate\fR, \*(T<\fB\-\-framerate \fR\*(T>\fIframerate\fR
395
The framerate that is used for framenumber to time conversion is normally
396
auto-detected (soon enough) within the pipeline. If this were not to succeed,
397
then \fIframerate\fR,
398
specified as \fINUM[/DENOM]\fR,
399
is used as a fallback instead of the otherwise default 25/1.
401
\*(T<\fB\-b\fR\*(T>, \*(T<\fB\-\-block\-overrun\fR\*(T>
402
This makes \fBentrans\fR prevent automatic adjustments to queues
403
(in a \fIdecodebin\fR), thereby keeping them at fixed size.
405
Despite all the automagic, the pipeline may stall in exotic cases
406
(e.g. some strange behaving element/muxer, \&...). A good first thing to try
407
then is to configure queues at a larger-than-default setting (see for example
408
following section) and to use this option to ensure they really remain
409
configured as intended without any other influence.
410
.SS "PIPELINE CONFIGURATION"
411
Although element properties are typically set in the pipeline descriptions,
412
the following options can be useful for dynamically created elements (see for
413
instance the dvd example in EXAMPLES) or when it is desired to configure a property
414
syntactically separated from the pipeline on the command line.
416
\*(T<\fB\-\-set\-prop \fR\*(T>\fIelement:prop:value[:time] \fR\*(T<\fB\fR\*(T>
417
Sets property \fIprop\fR of
418
\fIelement\fR to \fIvalue\fR,
419
where \fIelement\fR can either be an element-type, or the
420
name or full path-string of a specific element.
421
If \fIprop\fR is a \*(T<GST_CONTROLLABLE\*(T>
422
property (use \fBgst-inspect\fR(1) to determine this),
423
then a (pipeline media) \fItime\fR at which
425
should be set to this particular \fIvalue\fR
426
(using the controller framework) can be given as well.
428
In general, a value given for a property within the pipeline description
429
will override any value provided this way. In case of \fIqueue\fRs,
430
however, both \fIdecodebin\fR and \fBentrans\fR will override some
431
properties' values in order to minimize the possibility of blocking.
432
Though it is not recommended, \*(T<\fBset\-prop\fR\*(T> can be used
433
to forcibly overwrite such aforementioned defaults.
435
The rank of an element (as a plugin feature), which (a.o.) determines whether or
436
not it is considered for auto-plugging (in dynamic mode) is considered
437
as a pseudo-property \*(T<pf_rank\*(T> and can therefore be set
440
\*(T<\fB\-\-vb \fR\*(T>\fIvkbitrate\fR, \*(T<\fB\-\-ab \fR\*(T>\fIakbitrate\fR
441
Sets the \*(T<bitrate\*(T> property of any video or audio element to
442
\fIvkbitrate\fR [ * 1000] or
443
\fIakbitrate\fR [ * 1000] respectively,
444
depending on whether the property expects to be provided with (k)bitrate.
446
\*(T<\fB\-\-vq \fR\*(T>\fIvquality\fR, \*(T<\fB\-\-aq \fR\*(T>\fIaquality\fR
447
Sets either the \*(T<quality\*(T> or \*(T<quantizer\*(T>
448
property of any video or audio element to \fIvquality\fR or
449
\fIaquality\fR respectively.
451
\*(T<\fB\-\-pass \fR\*(T>\fIpass\fR
452
Sets the \*(T<pass\*(T> property of any video element to
454
must be \*(T<1\*(T> or \*(T<2\*(T>.
456
\*(T<\fB\-t \fR\*(T>\fItag:value\fR\*(T<\fB \fR\*(T>
458
\fBentrans\fR locates a \*(T<TagSetter\*(T> in
459
the pipeline and sets each given \fItag\fR to
462
A list of possible tags can be found in
463
.URL http://www.gstreamer.net/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstTagList.html "GStreamer core documentation"
465
.SS "REPORTING OPTIONS"
466
By default, \fBentrans\fR reports the following items at startup:
469
an overview of elements found in the pipeline,
470
along with the current values of properties that differ from their
471
usual (default) setting;
472
tags announced by an element are considered as a pseudo-property
473
\*(T<tag\*(T> of the element
476
a set of distinct caps that have been found flowing through the pipeline,
479
the (video) queues found in the pipeline (with their neighbours),
480
and their maximum capacity settings (size, buffers, time)
482
After that, it provides the following in regular intervals, if already available
486
(time) position in input stream,
489
movie time: position in output stream, and the total expected output movie time
492
processing speed: ratio of elapsed (input) stream time to elapsed CPU time
495
ETA: expected time to completion of processing;
496
this calculation \fIalways\fR uses elapsed system clock time,
497
regardless of options below,
500
amount of buffers presently contained in the queues reported at startup,
503
if a specific output file can be identified, (combined) bitrate so far.
505
The following options can influence some of this behaviour:
507
\*(T<\fB\-d \fR\*(T>\fIdelay\fR, \*(T<\fB\-\-delay \fR\*(T>\fIdelay\fR
508
Sets the interval between progress updates to \fIdelay\fR
509
seconds. The default delay is 2 seconds.
511
\*(T<\fB\-\-timeout \fR\*(T>\fItimeout\fR
512
As an \fBentrans\fR run spins up, it transitions through a number of stages, which
513
should normally follow each other in pretty rapid succession.
514
\fItimeout\fR, by default 4, is the maximum interval
515
(in seconds) that will be allowed between such stages. If the interval is exceeded,
516
\fBentrans\fR may simply abort altogether or try to recover the situation
517
(depending on the stage), the success of which depends on the cause
518
(e.g. a misbehaving element, or a badly constructed pipeline, \&...).
519
Evidently, a high \fItimeout\fR value essentially renders
520
this check mute. Setting it to 0 completely disables this check as well
521
as some other mechanisms employed to support it, and is not normally advisable.
523
\*(T<\fB\-\-progress\-fps\fR\*(T>
524
Makes regular reports also provide processing speed in fps, which is calculated
525
using either auto-detected framerate or provided by \*(T<\fB\-f\fR\*(T>.
527
\*(T<\fB\-\-progress\-real\fR\*(T>
528
Calculate processing speed based on elapsed system clock time (instead of CPU-time).
530
In the following, \fIproppattern\fR
531
is a regular expression that will be matched a combination of
532
an \fIelement\fR and (optionally) one its properties
533
\fIprop\fR. More precisely, this combination
534
matches if the regular expression matches any of the following:
537
\fIelement's factory name\fR.\fIprop\fR
540
\fIelement's name\fR.\fIprop\fR
543
\fIelement's path name\fR.\fIprop\fR
545
In each case, the last part is omitted if there is no
546
\fIprop\fR in the context in question.
548
Similarly, \fImsgpattern\fR is matched against
549
expressions as above, but with \fIprop\fR replaced by
550
\fImessage type name\fR.\fImessage structure name\fR
551
Again, in each case, the last part is omitted if there is no structure for the
555
Output messages posted on the pipeline's bus
558
Provide output on property changes of the pipeline's elements.
559
This output can be filtered using \*(T<\fB\-x\fR\*(T>
561
\*(T<\fB\-\-short\-caps\fR\*(T>
562
Do not perform complete caps to string conversion, instead replace e.g. buffers
563
with their (string) type representation.
564
This can make for more comfortable display of e.g. Vorbis and Theora related caps.
566
\*(T<\fB\-\-ignore\-msg \fR\*(T>\fImsgpattern[,\&...]\fR\*(T<\fB \fR\*(T>, \*(T<\fB\-\-display\-msg \fR\*(T>\fImsgpattern[,\&...]\fR\*(T<\fB \fR\*(T>
567
[multi-valued] If message reporting is enabled by \*(T<\fB\-m\fR\*(T>,
568
only report on those that match \*(T<\fB\-\-display\-msg\fR\*(T>
569
or do not match \*(T<\fB\-\-ignore\-msg\fR\*(T>
571
\*(T<\fB\-x \fR\*(T>\fIproppattern[,\&...]\fR\*(T<\fB \fR\*(T>, \*(T<\fB\-\-exclude \fR\*(T>\fIproppattern[,\&...]\fR\*(T<\fB \fR\*(T>, \*(T<\fB\-\-include \fR\*(T>\fIproppattern[,\&...]\fR\*(T<\fB \fR\*(T>
572
[multi-valued] If property change reporting is enabled by \*(T<\fB\-v\fR\*(T>,
573
only report those on properties that match \*(T<\fB\-\-include\fR\*(T>
574
or do not match \*(T<\fB\-\-exclude\fR\*(T>
576
\*(T<\fB\-\-display\-prop \fR\*(T>\fIproppattern[,\&...]\fR\*(T<\fB \fR\*(T>, \*(T<\fB\-\-ignore\-prop \fR\*(T>\fIproppattern[,\&...]\fR\*(T<\fB \fR\*(T>
577
[multi-valued] An element's property (value) is reported at start-up if and only if
578
it matches an expression given in \*(T<\fB\-\-display\-prop\fR\*(T>
579
or its value differs from the usual and it does not match
580
\*(T<\fB\-\-ignore\-prop\fR\*(T>.
581
Also, in any case, an element's presence in the pipeline is at least
582
mentioned by default, unless the element (by itself) matches
583
\*(T<\fB\-\-ignore\-prop\fR\*(T>
584
.SS "CONFIGURATION OPTIONS"
585
Each \fBentrans\fR option \(embe it one affecting \fBentrans\fR'
586
run-time behaviour or affecting pipeline element (properties)\(em
587
can also be provided on a more permanent basis using a configuration
589
Such a file consists of sections, led by
590
a \*(T<[section]\*(T> header and
591
followed by \*(T<name: value\*(T> entries,
592
\*(T<name=value\*(T> is also accepted.
593
Note that leading whitespace is removed from values.
594
Lines beginning with \*(T<#\*(T> or
595
\*(T<;\*(T> are ignored and may be used to
598
In the special section \*(T<[options]\*(T>,
599
each entry \*(T<name: value\*(T>
600
is equivalent to providing \*(T<\fB\-\-\fR\*(T>\fIname\fR\*(T<\fB
601
\fR\*(T>\fIvalue\fR on the command-line,
602
where \fIname\fR must be an option's longname.
603
The name of any other section is interpreted as an element-type
604
or an element, with each entry providing a value for a property.
605
Otherwise put, each \*(T<prop: value\*(T>
607
\*(T<[\fIelement\fR]\*(T>
608
is equivalent to mentioning it in \*(T<\fB\-\-set\-prop\fR\*(T> as
609
\fIelement:prop:value\fR
611
By default, the configuration file is called \*(T<\fI.gst\-entrans\fR\*(T>
612
and is searched for in the current directory and in the user's home directory
614
Any setting provided on the command line for a single-valued option
615
(e.g. a boolean option) overrides a similar value given in a configuration file,
616
whereas values provided for multi-valued ones append to those already provided.
618
\*(T<\fB\-\-config \fR\*(T>\fIfile\fR
619
Use \fIfile\fR \fIinstead\fR of any
620
default configuration file.
622
\*(T<\fB\-\-profile \fR\*(T>\fIfile\fR
623
Load \fIfile\fR \fIafter\fR other
624
configuration files, either default ones or given by \*(T<\fB\-\-config\fR\*(T>.
625
This option derives its name from its use in loading certain export or
626
encoder profiles (e.g. MPEG1, MPEG2, etc),
627
which are mainly a collection of presets for certain properties that can
628
be kept in corresponding profile configuration files.
629
.SS "MISCELLANEOUS OPTIONS"
631
\*(T<\fB\-\-save \fR\*(T>\fImessage:file[:append][,\&...] \fR\*(T<\fB\fR\*(T>
633
Makes \fBentrans\fR save a custom element \fImessage\fR to
635
that is, the string representation of the message's structure is saved
636
(followed by a \fBlinefeed\fR).
637
If \fIappend\fR is true (e.g. \*(T<1\*(T>, \*(T<t\*(T>,
638
\*(T<T\*(T>), then all messages are appended to \fIfile\fR,
639
otherwise the default is to truncate \fIfile\fR whenever
640
\fImessage\fR is received, thereby saving only the
641
most recently received \fImessage\fR.
643
it might be noted here there was a change in version 0.10.15 in a structure's
644
string representation with respect to usage of a terminating \fB;\fR.
646
\fIfile\fR will be subject to having \*(T<${n}$\*(T>
647
replaced by the name of the element sending \fImessage\fR.
649
More examples of pipelines can also be found in \fBgst-launch\fR(1);
650
the ones below are primarily meant to illustrate some of
651
\fBentrans\fR' features.
653
In each case, everything could also be written on one line, without the backslash
654
character. In some cases, some particular quoting is needed to prevent
655
(mis)interpretation by the shell.
657
\fBBasic transcoding\fR
661
entrans.py \-i dvd://2 \-o dvd.ogm \-\-short\-caps \-\- \e
662
\-\-video ! theoraenc \-\-audio audioconvert ! vorbisenc
665
Transcodes complete title 2 from a DVD into a mixed Ogg containing all video
666
and audio tracks (but no subtitles) using default settings, while preventing
667
some extensive caps display.
669
\fBSelected stream transcoding\fR
673
entrans.py \-\-set\-prop dvdreadsrc:device:/mnt \-i dvd://2 \-o dvd.mkv \e
674
\-\-set\-prop dvdsubdec:pf_rank:128 \-\-on 6,12 \-\-an 1,2 \-\-vq 4 \-\-ab 256 \-\- \e
675
\-\-video ffenc_mpeg4 \-\-audio audioconvert ! lame \e
676
\-\-other ffmpegcolorspace ! ffenc_mpeg4 ! matroskamux ! filesink location='sub\-${on}.mkv'
679
Transcodes video and selected audio tracks from a DVD image mounted at /mnt
680
into a Matroska file, using the indicated fixed quantization and bitrate for
681
video and audio respectively. Some selected subtitle tracks are also encoded
682
as separate video streams into other Matroska files. Note that the rank of
683
the \fIdvdsubdec\fR must be increased for a subtitle stream to be
684
considered for decoding and subsequently made available.
686
\fBExtensive progress update transcoding\fR
690
entrans.py \-i example\-in.avi \-o example\-out.mkv \-\- \e
691
\-\-video tee name=tee ! queue ! theoraenc \e
692
tee. ! queue ! timeoverlay ! xvimagesink sync=false qos=false \e
693
\-\-audio audioconvert ! lame
696
Transcodes into Matroska using Theora and MP3 codecs, while providing for
697
(excessive) live preview progress info.
699
\fBPartial stream transcoding\fR
703
entrans.py \-i dvd://2 \-o dvd.mkv \-c chapter:5\- \-\-short\-caps \-\- \e
704
\-\-video ! identity single\-segment=true ! ffenc_mpeg4 \e
705
\-\-audio audioconvert ! identity single\-segment=true ! vorbisenc
708
Transcodes all video and audio tracks from a DVD title 2 (chapter 5 to the end)
709
into Matroska using MPEG4 and Vorbis codecs (while catering for properly
710
timestamped input for the container which records these faithfully for posterity).
712
\fBPass-through transcoding\fR
716
entrans.py \-s seek\-key \-c 60\-180 \-\-dam \-\- \-\-raw \e
717
filesrc location=example\-in.avi ! avidemux name=demux \e
718
avimux name=mux ! filesink location=example\-out.avi \e
719
demux.video_00 ! queue ! dam ! queue ! mux.video_0 \e
720
demux.audio_00 ! queue ! dam ! queue ! mad ! audioconvert ! lame ! mux.audio_0
723
Transcodes a particular section from an AVI file into another AVI file without
724
re-encoding video (but does re-encode audio, which is
725
recommended). The output will range from (approximately) 60 seconds into the
726
input up to 180 seconds; actually there will be a (key)seek to the nearest
727
keyframe just before the 60 seconds point to ensure the integrity of later
728
decoding of the output.
729
In addition, \fBentrans\fR will report changes on any object's properties, except
730
for any (pad's) caps.
732
The pipeline above uses raw mode, and as such must abide
733
by some rules and recommendations in pipeline building (see MUXING PIPELINES),
734
which leads in particular to the above abundance in \fIqueue\fRs.
735
With some extra configuration, pass-through could also be performed in
736
dynamic mode as follows (assuming that \*(T<video/mpeg\*(T> properly
737
describes the encoded video content):
741
entrans.py \-s seek\-key \-c 60\-180 \-\-decoder decodebin2 \e
742
\-\-set\-prop 'decodebin2:caps:video/mpeg;audio/x\-raw\-int;audio/x\-raw\-float' \e
743
\-i example\-in.avi \-o example\-out.avi \-\- \e
744
\-\-video capsfilter caps=video/mpeg \e
745
\-\-audio audioconvert ! lame
752
entrans.py \-s cut\-time \-c 0\-60 \-v \-x '.*caps' \-\-dam \-\- \-\-raw \e
753
v4l2src queue\-size=16 ! video/x\-raw\-yuv,framerate=25/1,width=384,height=576 ! \e
754
stamp sync\-margin=2 silent=false progress=0 ! queue ! \e
755
dam ! ffenc_mpeg4 name=venc \e
756
alsasrc buffer\-time=1000000 ! audio/x\-raw\-int,rate=48000,channels=1 ! queue ! \e
757
dam ! audioconvert ! queue ! lame name=aenc \e
758
avimux name=mux ! filesink location=rec.avi aenc. ! mux. venc. ! mux.
761
Records 1 minute of video and audio from a video4linux device and features
762
additional synchronization and reporting on object property changes (if any),
763
which includes reports on frame drops or duplications, although
764
(pad's) caps changes are excluded for convenience.
766
\fB2-pass transcoding\fR
770
entrans.py \-i example\-in.avi \-o /dev/null \-\-muxer avimux \-\-vb 1200 \-\-pass 1 \e
771
\-\-save astat:astat.log \-\- \-\-video ffenc_mpeg4 \e
772
\-\-audio audioconvert ! astat ! fakesink
773
SCALE="$(cat astat.log | sed 's/astat, scale=(double)//' | sed 's/;//')"
774
entrans.py \-i example\-in.avi \-o example\-out.avi \-\-vb 1200 \-\-pass 2 \e
775
\-\-tag 'comment:2\-pass demonstration' \-\- \e
776
\-\-video ffenc_mpeg4 \-\-audio audioconvert ! volume volume=$SCALE ! lame
779
Performs 2-pass transcoding from one AVI into another. The first pass also
780
determines and saves the maximum volume scaling that can safely be applied
781
without having to resort to clipping. It does not bother performing audio encoding
782
or producing an output file. Although the particular (encoder compatible) muxer
783
is hardly relevant here, one is nevertheless indicated explicitly
784
as a reasonablechoice cannot be determined
785
from \*(T</dev/null\*(T>. After some scripting to retrieve the
786
saved value from a file, the second pass performs volume scaling and encoding.
787
It also sets a comment (tag) in the resulting file to note its lofty goal.
789
\fBConfiguration file\fR
794
ignore\-prop=.*src.*,.*sink.*,dam.*,queue.*,identity.*,.*decodebin.*
795
display\-prop=.*\e.tag,.*\e.bitrate$,.*bframes,.*quantizer,.*\e.pass,.*\e.queue\-size
806
A basic, though adequate configuration file that filters out some
807
(usually less interesting) information on some technical
808
technical elements, while making sure on the other hand that some other
809
settings get displayed in any case. In addition, an element's properties
810
can be given defaults (other than the hardcoded ones), and the rank
811
of \fIdvdsubdec\fR is increased so that subtitles streams will
814
\fBProfile configuration\fR
816
Some examples of (encoding) profiles that can be passed to
817
\*(T<\fB\-\-profile\fR\*(T> (each profile is in a separate file).
818
Note that profiles also impose
819
constraints on e.g. width and height which are not automagically
820
enforced; one must still take care of this by means of e.g. proper scaling.
821
Similarly, the elements that are to perform the required encoding
822
must be properly (manually) specified, though their configuration
823
is then taken care of by the examples below.
829
# 44.1kHz, 16b, 2ch, mp2
841
rc\-buffer\-size = 320
842
rc\-buffer\-aggressivity = 99
853
# 44.1kHz, 16b, 2ch, mp2
864
# ntsc: gop\-size = 18
867
rc\-buffer\-size = 1792
868
rc\-buffer\-aggressivity = 99
880
# 32|44.1|48kHz, 16b, 2ch, mp2
888
# 1000 <= bitrate <= 9000
892
# ntsc: gop\-size = 18
897
rc\-buffer\-size = 1792
898
rc\-buffer\-aggressivity = 99
906
# 353|704|720 x 240|288|480|576
907
# 48kHz, 16b, 2ch, mp2|ac3
915
# 1000 <= bitrate <= 9800
919
# ntsc: gop\-size = 18
922
rc\-buffer\-size = 1792
923
rc\-buffer\-aggressivity = 99
929
Evidently, there must be a basic GStreamer framework installation,
930
the extent of which and available plugins determine the processing scope that
932
Beyond this, it is highly recommended for the \fIdam\fR element to be available,
933
which is part of the plugins supplied along with \fBentrans\fR.
934
More (technical) details and motivation can be found in the documentation for
935
\fIdam\fR, but suffice it to say that without \fIdam\fR the following notes apply:
938
For \*(T<\fB\-\-seek\fR\*(T>, only the methods
939
\*(T<seek\*(T> and \*(T<seek\-key\*(T> are available.
940
However, for reasons explained in \fIdam\fR documentation and in
941
MUXING PIPELINES, even these methods can not be considered reliable,
942
either functional or technical.
943
As such, only full (uninterrupted) pipeline transcoding is really available.
945
As a technical note, this unreliability could be alleviated by
946
having the functionality to drop out-of-segment-bound buffers not only in sinks
947
or in some elements, but as a specific ability in
951
The graceful (signal initiated) termination usually
952
also relies on \fIdam\fR, and is quite sturdy in this case.
953
However, and fortunately, there is also an alternative fall-back implementation
954
that will take care of this in the vast majority of circumstances.
956
Note that in case of dynamic pipelines, the availability of the \fIdam\fR element
957
in the system is auto-detected, and the proper pipeline-construction action is
958
taken accordingly. In raw mode, however, it must be explictly confirmed (by
959
\*(T<\fB\-\-dam\fR\*(T>) that \fIdam\fRs are properly used, otherwise none will
960
be assumed present and only restricted operation is then available, as indicated
961
above. Proper usage of \fIdam\fR is subject to comments in MUXING PIPELINES,
962
but basically comes down to putting a \fIdam\fR as upstream as possible in each
963
independent stream, e.g. preceding some queue. Alternatively, such a queue could
964
be used as surrogate dam by naming it
965
\*(T<dam\fI<digits>\fR\*(T>.
966
.SH "GNONLIN COMPARISON"
967
On the one hand, one might compare in the sense that both GNonLin and \fBentrans\fR
968
aim to create media files while allowing for non-linear editing/cutting.
969
On the other hand, \fBentrans\fR is quite complementary and can actually be combined
970
with GNonLin, for example
974
entrans.py \-\- \-\-raw gnlcomposition. '(' name=comp gnlfilesource \e
975
location=test.avi start=0 duration=20000000000 media\-start=0 \e
976
media\-duration=20000000000 caps=video/x\-raw\-yuv ')' \e
977
comp.src ! ffenc_mpeg4 ! queue ! avimux ! filesink location=test\-gnonlin.avi
980
That being the case, why this alternative and yet another program, rather than
981
being content with e.g. GNonLin (and \fBgst-launch\fR(1)) ?
983
First and foremost, as a matter of style. The above example pipeline looks and
984
feels rather contrived (and that's only the video part!), and is not much of a
985
\fIpipeline\fR in that e.g. \fIgnlcomposition\fR is
986
really (deliberately) not so much a pipeline than it is more of a bag (serving
987
its intended purpose well). On the other hand, Un*x pipelines have a long
988
standing beauty (and a.o. adaptability and flexibility), and a (traditional)
989
GStreamer pipeline continues in that tradition. In that sense, \fBentrans\fR'
990
(and \fBgst-launch\fR(1)) approach is an ode to pipeline and its
991
inherent simplicity and clarity of intent.
992
In particular, typical \fBentrans\fR pipelines are only slightly different than
993
playback pipelines, and the cutting/seeking mechanism is pretty identical.
994
In that way, an \fBentrans\fR media file creation is very close to a
995
(non-linear) playback session (and closer than a GNonLin equivalent would be).
997
Secondly, there are some technical reasons. Particular care has been given
998
in \fBentrans\fR to the non-linear cutting functionality to make sure it operates
999
with great precision in a variety of circumstances. In this area;
1002
GNonLin, in particular \fIgnlcomposition\fR, may (and has been
1003
known to) experience some frame-dropping near end-of-stream due to its
1004
(asynchronous) technique of EOS-event generation
1007
GNonLin only relies on segment seek, as does \fBentrans\fR usually, which
1008
is fine when dealing with elements that support what and how they are supposed
1009
to. However (and unfortunately), elements are not always so perfect (for
1010
example, \fIdvdreadsrc\fR does not support segment seek).
1011
In such cases, \fBentrans\fR has some plain-and-simple alternative methods that can
1012
still get the (cutting) job done.
1014
So, the idea and intention basically is; if you can play it, you can \fBentrans\fR
1015
it (with a similar pipeline, and precision in various circumstances).
1016
.SH "MUXING PIPELINES"
1017
As mentioned earlier, one might run into some pitfalls when constructing
1018
a (raw) pipeline, most of which are taken care of by \fBentrans\fR when runnning in
1022
To begin with, the pipeline must be properly built and linked,
1023
in particular to the muxer element, which typically only has request pads.
1024
For linking and subsequent negotiation to succeed, a stream must manage
1025
to get the request pad it really needs and is compatible with. That means that
1026
the element connecting to the muxer (or trying so) should provide enough
1027
(static) information to identify the corresponding muxer pad (template).
1028
As this information is typically derived from the connecting element's
1029
pad templates, it is not quite comfortable to try connecting a generic
1030
element (e.g. \fIqueue\fR). If this were needed, or there is some
1031
or the other problem connecting to the muxer, then it may be helpful to use
1032
a capsfilter (aka as a filtered connection) or to specifically
1033
indicate the desired muxer pad (by a name corresponding to the intended
1034
template, as in example Pass-through transcoding),
1035
see also \fBgst-launch\fR(1) for specific syntax in either case.
1037
\fBMuxer and Queue\fR.
1038
In the particular case of a transcoding pipeline (having some media-file
1039
as source), some other care is needed to make sure it does not stall, i.e.
1040
simply block without any notification (or an application having
1041
a chance to do something about it). Specifically, a muxer will often block a
1042
thread on its incoming pad until it has enough data across all of its pads for
1043
it to make a decision as to what to mux in next.
1044
Evidently, if a single (demuxer) thread were having to provide data to several
1045
pads, then stalling would almost surely occur. As such, each of these
1046
pads/streams should have its own thread. In case of live sources, this is
1047
usually already the case, e.g. separate video and audio capturing threads.
1048
However, when transcoding, and therefore demuxing an input file, a
1049
\fIqueue\fR should be inserted into each outgoing stream to act as
1050
a thread boundary and supply a required separate thread.
1051
In addition, this multi-threading will evidently also spread processing across
1052
several CPUs (if available) and improve performance. In this respect, it
1053
can also be beneficial to use more than 1 \fIqueue\fR/thread per
1054
stream; one that performs filter processing (if any) and one that performs
1057
Note that similar stalling can also occur in some variations of these
1058
circumstances. For instance, \fItee\fR could have the role of
1059
demuxer in the above story, and/or a collection of several sinks in a
1060
pipeline could act as a muxer in the above story, since they will each also
1061
block a thread in PAUSED state (when the pipeline is trying to make it to
1062
that state). Another such situation can arise (temporarily) when pads are
1063
blocked as part of the seek-mechanism. In any case, the remedy is the same;
1064
use \fIqueue\fRs to prevent one thread from having to go around in
1065
too many places, and ending up stuck in one of them.
1067
\fBMuxer and Time(stamps)\fR.
1068
Even if the above is taken into account, the time-sensitivity of a typical
1069
muxer may lead to (at first sight mysterious) stalling (in transcoding
1070
pipelines). That is, a muxer will usually examine the timestamps of the incoming
1071
data, select the oldest of these to be put into the outgoing stream and then
1072
wait for new data to arrive on this selected input stream (i.e. keep other
1073
streams/threads wait'ing).
1074
It follows easily that if there is a gap, imbalance,
1075
imperfection, irregularity (or however described) in timestamps between various
1076
incoming streams, a muxer will then consistently/continuously
1077
expect/want more data on 1 particular pad (for some
1078
amount proportional to the irregularity).
1079
For some time, this need could be satisfied by the \fIqueue\fRs
1080
that are present in this stream. At some point, however, these may not hold
1081
enough data and will need further input from the upstream demuxer element.
1082
However, for this demuxer to provide data for 1 of its (outgoing) streams, it
1083
will also need to output data for the other streams, and this ends up
1084
into the other streams' \fIqueue\fRs. Unfortunately, in
1085
this situation those queues cannot send out any data, as the muxer is
1086
holding their threads (blocked). Hence, they will (soon) fillup and then in
1087
turn block the demuxer thread trying to insert data, until there is again space
1088
available. Consequently, a deadlock circle ensues; muxer waiting for new
1089
data from queue, waiting for data from demuxer, waiting for space to put this
1090
into another stream queue, waiting to unload data into the muxer.
1091
Note that this deadlock phenomenom will not occur with live (recording) pipelines,
1092
as the various threads are then not joined to a single demuxer (thread),
1093
though it is then likely to manifest itself it by loss of (live) input data.
1095
There a number of possible causes for the irregularities mentioned above.
1098
Rarely, but not impossibly so, the problem may be inherent in the very input
1099
medium itself. Or there could be a problem with a (experimental) demuxer
1100
that might produce incorrect timestamps.
1103
If a (segment) seek is performed in a pipeline \fIwithout\fR
1104
using \fIdam\fR, it is quite likely that some stream(s) may perform proper
1105
filtering of out-of-segment-bound data, and that other(s) may not. This would
1106
then cause a typical imbalance between the various streams.
1109
If timestamps are being resequenced in some incoming streams (e.g. by
1110
\fIidentity\fR), but not in the other ones, there is an obvious imbalance.
1113
Though more exotic, even if \fIdam\fR is being used, one must take care to perform
1114
this filtering \fIbefore\fR (the by now
1115
clearly essential) \fIqueue\fR in the respective stream,
1116
particularly when several distinct sections are to be cut out of the input.
1117
After all, if \fIqueue\fR were placed before \fIdam\fR, then the
1118
latter does not have a chance to drop unneeded buffers soon enough.
1119
As such, if a muxer tries to get the first piece of data on a
1120
particular pad following the gap between the sections, these
1121
\fIqueue\fRs would fillup and be effectively as if they were not
1124
\fBDynamic mode services\fR.
1125
Dynamic mode takes care of (most of) the above as follows:
1128
Pipeline building is performed almost completely automagically.
1129
Of course, this does not mean it can fit a square into a circle, so some
1130
consideration for compatibility and negotiation is still in order.
1133
\fIqueue\fRs are inserted where needed and/or useful,
1134
either by \fIdecodebin\fR or by \fBentrans\fR
1137
Whenever available (recommended), \fIdam\fR is used and inserted in proper locations.
1139
.URL http://www.gstreamer.net/ "GStreamer homepage"
1141
\fBgst-launch\fR(1),
1142
.URL http://gentrans.sourceforge.net/ "entrans plugins"
1144
Mark Nauwelaerts <\*(T<mnauw@users.sourceforge.net\*(T>>
added
removed
docs/manual/entrans.1
