1
<?xml version="1.0" encoding="ISO-8859-1"?>
2
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
5
<!ENTITY % url-entities SYSTEM "url.entities">
6
<!ENTITY % text-entities SYSTEM "text.entities">
7
<!ENTITY % version-entities SYSTEM "version.entities">
12
<!ENTITY GStreamer "<application>GStreamer</application>">
13
<!ENTITY sect-requirements "<xref linkend='requirements'/>">
14
<!ENTITY sect-muxing-pipelines "<xref linkend='muxing-pipelines'/>">
15
<!ENTITY sect-examples "<xref linkend='examples'/>">
16
<!ENTITY dam "<element repos='entrans'>dam</element>">
17
<!ENTITY shift "<element repos='entrans'>shift</element>">
18
<!ENTITY identity "<element repos='core'>identity</element>">
21
<refentry id="entrans" xmlns:xi="http://www.w3.org/2003/XInclude">
23
<refentrytitle id="entrans_name">&entrans;</refentrytitle>
24
<manvolnum>1</manvolnum>
27
<refnamediv id="name">
28
<refname>&entrans;</refname>
29
<refpurpose>build and run GStreamer pipeline</refpurpose>
33
<releaseinfo>Version &GST_VERSION;</releaseinfo>
34
<!-- minor abuse to make into man header -->
35
<date>&GST_VERSION;</date>
38
<!-- body begins here -->
39
<refsynopsisdiv id="synopsis">
41
<command>entrans</command>
42
<arg choice='opt' rep='repeat'>OPTION</arg>
43
<arg choice='req'>--</arg>
44
<arg choice='req' rep='repeat'>PIPELINE-OPTION</arg>
49
<refsect1 id="description"><title>Description</title>
52
&entrans; builds and runs a &GStreamer; pipeline, primarily intended for
53
transcoding, encoding or recording purposes.
57
On the one hand, it is much like
58
&gst-launch; in that it has no ambitions to go beyond command-line
59
(or script) driven processing.
63
On the other hand, it has quite a few enhancements that provide application-level
64
functionality sufficiently comfortable and suitable for
65
plain-and-simple (and robust) transcoding, encoding or recording
66
using the &GStreamer; framework and plugins:
70
Pipeline to run can be specified manually, or can be built dynamically
71
based on inputstream and pipeline fragments
72
(see <xref linkend="operation"/>), which takes
73
care of most of the boilerplate (and of some pitfalls to watch out for
74
with transcoding pipelines, see also §-muxing-pipelines;).
79
Provides some typically relevant (configurable) interesting info
80
regarding the pipeline (elements, properties, queues, …) and
81
caps flowing in pipeline.
86
Regular progress updates are provided.
91
Limited support for tag setting (whenever a
92
<interfacename>TagSetter</interfacename> is present).
97
Property configuration support; settings can be applied from what is
98
stored in a config file and there is also some custom support for
99
setting <quote>popular options</quote> (e.g. bitrate).
104
Last but not least (convenient), processing can be restricted to
105
specific portions of the input(stream) (mind §-requirements;).
110
Graceful shutdown of processing at any time,
111
and still well-formed output as result
112
(mind §-requirements;).
116
Another (technical) difference is that it is written
117
in <ulink url="&url-python;">python</ulink>,
118
using the python bindings for the &GStreamer; framework (gst-python),
119
which makes many of the enhancements much more comfortable to implement
120
and easy to adjust (to taste).
124
<refsect1 id="operation"><title>Operation</title>
127
As already alluded to above, &entrans; fundamentally operates
128
in one of the following ways, also loosely called modes:
132
<title>Raw mode</title>
134
The pipeline to construct, run and manage is explictly given
135
manually (see <option>--raw</option>).
136
On the one hand, this mode allows full freedom in
137
pipeline construction and can be great for diagnosing and
139
On the other hand, if this freedom is not properly used, all sorts
140
of things can go wrong (blocking, …) see §-muxing-pipelines; and
141
§-requirements; [do not even try to run in this mode if what is stated
142
there is not fully clear and understood].
143
For now, this mode is also required for performing
144
e.g. video-passthrough transcoding (perhaps more appropriately
145
called re-muxing in this case).
151
<title>Dynamic mode</title>
153
<element>decodebin</element>
154
is applied to the inputstream, which will
155
automagically provide all the streams present in the input in
156
their decoded raw (video, audio or other, e.g. text) form.
157
Each of these streams is then connected to an instance of a pipeline
158
(fragment) given by <option>--video</option>, <option>--audio</option>
159
or <option>--other</option>, each typically containing filters and/or
160
encoder. An optional subsequent step is trying to connect this to an
161
appropriately selected muxer for the output.
166
In any case, no (advanced) error processing or sane-ness checking
167
is performed on either pipeline or pipeline fragments.
168
As such, linking, negotiation or other matters can very well fail,
169
e.g. if fragments do not contain encoder elements that are compatible
170
with the muxer in question. It is also possible for some
171
parts of the pipeline to simply remain disconnected and
172
the corresponding stream being effectively discarded (this might
173
also be used as a feature ;-) ).
174
Reporting on any of these occurrences is of course done in as much
175
as the pipeline provides info on what is happening.
178
Though this may sound ominous, in practice, this comes down to
179
either things working out just nicely
180
or finding out about something going wrong in a more or less fast and
182
Having a look at §-examples; should increases chances on the former
183
being the case, and should even provide enough for a jump-start based on some
184
&GStreamer; experience.
187
Processing can be halted at any time by sending a <parameter>SIGINT</parameter>
188
or <parameter>SIGTERM</parameter> signal to &entrans;.
189
This will make &entrans; block the data-flow and send an end-of-stream event
190
through the pipeline to ensure graceful termination of streaming.
191
As such, it should be noted that termination may not occur instantly,
192
it might take a moment for things to <quote>run out</quote>
193
(particularly with some <element>queue</element>s around).
196
If in rare cases this mechanism were to fail, sending such a signal
197
a second time will forego any attempts at graceful shutdown
198
and will make &entrans; end things the hard way with <emphasis>no</emphasis>
199
guarantee on the output being <emphasis>fully</emphasis> OK
200
(it will most likely not be) …
205
Due to the way the python interpreter handles signals,
206
even the above may not work if things are messed up <emphasis>seriously</emphasis>,
207
e.g. when python interpreter is caught up somewhere in &GStreamer; backend code.
208
This, however, has only been known to happen as a prelude
209
to finding some serious application bug or &GStreamer; plugin/core bug.
210
Regardless, e.g. <parameter>SIGKILL</parameter> is then your friend …
216
<refsect1 id="options"><title>Options</title>
218
<para>&entrans; accepts the options presented in the following sections,
219
most of which have shortname (one-letter) or longname forms.
220
The ordering of the options is not strict, and options can be single-valued
225
In the former case, which is the default unless otherwise
226
indicated below, only the value given last is retained.
227
In particular, this includes boolean options.
228
If such an option is given, the corresponding setting is turned <quote>on</quote>.
229
The setting can also be explictly turned <quote>off</quote>
230
by providing the corresponding
231
<option>--no-<replaceable>longname</replaceable></option> option.
236
Otherwise, for multi-valued options, all values given are taken into
238
In these cases, it may sometimes also be possible to pass several values per
239
single option occurrence, by comma-separating these values as indicated in each
240
such case below. This will typically be the case in those instances where there
241
can be no ambiguity since the supplied value does not include
242
<quote>free-text</quote>.
250
<term><option>-h</option></term>
251
<term><option>--help</option></term>
253
<para>Show a brief help message.</para>
258
<refsect2 id="pipeline-options"><title>Pipeline options</title>
261
At least one of the following options should be provided
262
following <option>--</option> (in each case, see &gst-launch; for
263
the syntax of <replaceable>pipeline-description</replaceable>).
264
Clearly, as explained previously, the former option excludes
265
all of the latter ones.
269
<option>--raw <replaceable>pipeline-description</replaceable></option>
272
<para>Makes &entrans; run in raw mode, and provides
273
the complete pipeline for this mode of operation.
276
Again, this should be used with expertise and being aware of comments
277
in §-muxing-pipelines; and §-requirements;.
282
<term><option>--video<optional>:<replaceable>streamnumber</replaceable></optional>
283
<replaceable>pipeline-description</replaceable></option></term>
286
<replaceable>pipeline-description</replaceable>
287
describes a pipeline fragment for video data processing,
288
typically consisting of 0 or more filters followed by an encoder.
290
</listitem></varlistentry>
292
<term><option>--audio<optional>:<replaceable>streamnumber</replaceable></optional>
293
<replaceable>pipeline-description</replaceable></option></term>
295
<para>Similar to <option>--video</option>, except that it provides
296
a pipeline for (optionally) processing and encoding audio data.
301
<term><option>--other<optional>:<replaceable>streamnumber</replaceable></optional>
302
<replaceable>pipeline-description</replaceable></option></term>
304
<para>Similar to the above options, except that it provides
305
a pipeline for (optionally) processing and/or encoding data
306
that does not fit in the above categories, e.g. subtitles.
311
<term><option>--decoder
312
<replaceable>decoder-factory</replaceable></option></term>
314
<para>Use <replaceable>decoder-factory</replaceable> instead of
315
the default <element>decodebin</element> to construct the decoding
316
part of the pipeline in dynamic mode (as mentioned earlier).
317
The given element should have compatible behaviour/signals
318
with <element>decodebin</element>, such as for instance the
319
new experimental <element>decodebin2</element>.
324
The above (partial) pipelines should typically have an encoder as last
325
element. In any case, it should best not be a generic element, as that
326
might cause confusion as to how to link to the muxer (see also
327
§-muxing-pipelines;).
330
It is also possible to <quote>close</quote> any of the above
331
pipeline fragments by ending it with a sink element. In this case,
332
the resulting stream will not be muxed and each can
333
have independent output, e.g. streamed to a file.
334
As each of these would evidently need to have distinct names,
335
there is (extremely) limited support for variable substitutions.
336
Each (video and audio) stream that dynamically becomes available is
337
(independently) numbered, starting from 1, and as such
338
assigned an (audio or video) stream number.
339
Any element property of type <type>string</type> will be
340
subject to having <literal>${vn}</literal>, <literal>${an}</literal>
341
and <literal>${on}</literal> replaced by the video, audio and other
342
stream number (at that time) respectively in video, audio or other
344
If any of the above have a <replaceable>streamnumber</replaceable> appended,
345
then that fragment will only apply to that particular stream, otherwise
346
it will be the default fragment. If no specific or default fragment
347
has been provided for a particular stream, then that stream will be discarded.
348
This effect is similar to the use of <option>--vn</option>, <option>--an</option>
349
or <option>--on</option> (see next section).
352
As an additional convenience, all (partial) pipelines passed to &entrans;
353
will perform a simple form of glob-expansion for raw video and
354
audio mimetypes in capsfilters. That is, e.g. <literal>video/*</literal>
355
will be expanded to raw video mimetypes
356
(also distributing properties if any, of course).
357
This allows e.g. for scaling without particular attention for what colorspace
358
may be in use at a particular stage.
362
<refsect2 id="io-options"><title>Input/output options</title>
365
The option in this section are only applicable
366
in dynamic mode, so incompatible with <option>--raw</option>.
370
<term><option>-i <replaceable>uri</replaceable></option></term>
371
<term><option>--input <replaceable>uri</replaceable></option></term>
374
Indicates the input source. If <replaceable>uri</replaceable> is a
375
valid URI, then a proper source element will be selected, otherwise it is simply
376
taken as a (relative) path of an inputfile. If <replaceable>uri</replaceable> is
377
<literal>-</literal>, then stdin will be used as input.
382
<term><option>-o <replaceable>uri</replaceable></option></term>
383
<term><option>--output <replaceable>uri</replaceable></option></term>
386
Indicates the output destination. If <replaceable>output</replaceable> is a
387
valid URI, then a corresponding sink element is selected, otherwise
388
it is taken as a (relative) path of an outputfile
389
(output to stdout is not supported).
390
The (file)suffix of <replaceable>uri</replaceable> is used to automagically
391
choose an appropriate muxer, which can be overridden with
392
<option>--muxer</option>
397
<term><option>--muxer <replaceable>mux-element</replaceable></option></term>
400
Use <replaceable>mux-element</replaceable> in stead of the automatically
401
selected one, or if one fails to be auto-selected.
402
<replaceable>mux-element</replaceable> must be of <literal>Muxer</literal> class.
409
As mentioned in the previous section, all streams found in the input are
410
assigned a stream number and considered for processing, unless somehow
411
restricted by the following options.
416
<term><option>--vn <replaceable>streamnumber<optional>,…</optional></replaceable></option></term>
417
<term><option>--an <replaceable>streamnumber<optional>,…</optional></replaceable></option></term>
418
<term><option>--on <replaceable>streamnumber<optional>,…</optional></replaceable></option></term>
421
[multi-valued] Only the video, audio or other streams with (respectively) listed
422
<replaceable>streamnumber</replaceable> will be considered, others disregarded.
423
Furthermore, streams of each type will be muxed into the target in the order
424
in which their <replaceable>streamnumber</replaceable>s are given in these options,
425
and in overall first video, then audio and others.
430
<term><option>--sync-link</option></term>
433
This option is mainly meant for testing and diagnostic purposes.
434
It basically disables the stream(re)-ordering mechanism as implied by and
435
explained in the above option (though still retains stream selection).
440
<term><option>--at <replaceable>tag<optional>,…</optional></replaceable></option></term>
443
[multi-valued] Audio streams can (though need not) be accompanied by a language tag
444
(typically a 2- or 3-letter language code). The regular expression
445
<replaceable>tag</replaceable>
446
is matched against each detected audio stream's language tag and only
447
streams without language tag or streams with a matching language tag are
448
processed, others disregarded. This selection method <emphasis>cannot</emphasis>
449
be combined with the above streamnumber based selection.
453
<!-- <title>Warning</title> -->
454
<para> The current (or another?) method of
455
implementing this selection may very well not work with all muxer elements. As
456
such, this option can be given a try, but if not successful, the much more
457
robust <option>--an</option> should be used instead. The proper
458
number(s) to use for this may be derived from (ordered) tag information that is
459
provided by some elements and reported at start-up.
466
<term><option>--stamp</option></term>
469
This is enabled by default, and makes &entrans; insert an &identity; element
470
(with single-segment True) before the connected pipeline-fragment
471
to perform timestamp re-sequencing. This is typically useful when
472
muxing into a format that records timestamps (and does not hurt
473
when the format does not).
482
<refsect2 id="basic-options"><title>Basic options</title>
485
Whereas no specific dependencies exist for all other options,
486
the §-requirements; section applies particularly
487
to the following options (in more or less degree).
491
<replaceable><optional><optional>(</optional><replaceable>format</replaceable><optional>)</optional>:</optional>t1-t2<optional>,…</optional></replaceable></option></term>
493
<replaceable><optional><optional>(</optional><replaceable>format</replaceable><optional>)</optional>:</optional>t1-t2<optional>,…</optional></replaceable></option></term>
497
Only process the indicated sections of the pipeline (by default the complete
498
input is processed). The option <option>-s</option> determines the method used
499
for selecting the desired data.
502
If no <replaceable>format</replaceable> is provided,
503
the <replaceable>tN</replaceable> parameters can be given in timecode format
504
HH:MM:SS.FRACTION or as a (video)framenumber, which is a number following
505
<literal>f</literal> or <literal>F</literal>. Any buffer that
506
overlaps with the indicated section is taken into account. The last indicated
507
section may be open-ended, i.e. the end point may be omitted.
510
However, if <replaceable>format</replaceable> is the nickname of a pre-defined
511
or custom format (defined by some element in the pipeline), then it is used as
512
unit for the <replaceable>tN</replaceable> numbers.
513
In this case, option <option>-s</option> below must select a seek-based method,
514
and the seek will be executed in <replaceable>format</replaceable> if it is provided
515
without matching (…), otherwise the given units will be (query) converted
516
to time format first, and these results will be used to seek in time.
521
<term><option>-s <replaceable>method</replaceable></option></term>
522
<term><option>--section <replaceable>method</replaceable></option></term>
525
Possible choices for <replaceable>method</replaceable> are:
528
<term><literal>seek</literal></term>
531
Sections are selected by means of regular &GStreamer; seeks.
532
A flushing seek is performed for the first section,
533
segment seek for the others, and a normal seek for the last section.
534
This is also the default method and is OK for most circumstances.
535
In some cases, however, the other methods may be in order,
536
e.g. when (the driving element in) the pipeline does not support
537
some type of seek that would be used.
542
<term><literal>seek-key</literal></term>
545
This is similar to the case above, but each seek is also a keyframe seek,
546
that is, the actual selection may not be exactly the one
547
that was requested but may start at the nearest keyframe
548
preceding the desired start.
549
This would typically be required when performing re-muxing
550
without fully decoding and re-encoding the material.
555
<term><literal>cut-time</literal></term>
558
In this case, the pipeline is run from the start (without any seeks)
559
and all but the desired sections are disregarded.
560
The decision whether or not to drop a piece of data is based on its timestamp.
561
This is the recommended (only possible) method to use
562
when performing A/V sync correction using data-timestamp shifting,
563
e.g. by means of the &shift; element. It can also be used
564
to end a live source(s) driven pipeline after a specified duration.
569
<term><literal>cut</literal></term>
572
This method applies in case any/all of the above fail, e.g. some element
573
does not support seek or unreliable timestamps are produced in the pipeline.
574
No seeks or anything special is done, the pipeline is run from the start and all but the
575
indicated sections is dropped. Timestamps on the datastream are disregarded,
576
and the incoming data is restamped based on framecount and framerate
577
(video), or on sample count and samplerate (audio).
578
In particular, audio cutting is performed up to sample precision.
583
Note that the last 2 methods require the desired sections to be in ascending
584
order, whereas the former methods make it possible to select sections
585
that are out-of-order with regards to the input material.
591
<term><option>-a</option></term>
594
Perform (audio) sample precision selection, that is, it is possible for only parts of
595
buffers to be passed or dropped. This is done by default
596
in the <literal>cut</literal> method above, but not for the other methods.
602
<term><option>--dam</option></term>
605
Indicate, or rather, confirm that &dam; elements are being used
606
in <emphasis>raw</emphasis> pipelines.
607
Otherwise, <quote>surrogate dam</quote> elements will be searched for and used instead.
608
These are identified as elements whose name is of the form
609
<literal>dam<replaceable><digits></replaceable></literal>.
615
<term><option>-f <replaceable>framerate</replaceable></option></term>
616
<term><option>--framerate <replaceable>framerate</replaceable></option></term>
619
The framerate that is used for framenumber to time conversion is normally
620
auto-detected (soon enough) within the pipeline. If this were not to succeed,
621
then <replaceable>framerate</replaceable>,
622
specified as <replaceable>NUM<optional>/DENOM</optional></replaceable>,
623
is used as a fallback instead of the otherwise default 25/1.
629
<term><option>-b</option></term>
630
<term><option>--block-overrun</option></term>
633
This makes &entrans; prevent automatic adjustments to queues
634
(in a <element>decodebin</element>), thereby keeping them at fixed size.
637
Despite all the automagic, the pipeline may stall in exotic cases
638
(e.g. some strange behaving element/muxer, …). A good first thing to try
639
then is to configure queues at a larger-than-default setting (see for example
640
following section) and to use this option to ensure they really remain
641
configured as intended without any other influence.
650
<refsect2 id="pipe-config-options"><title>Pipeline configuration</title>
653
Although element properties are typically set in the pipeline descriptions,
654
the following options can be useful for dynamically created elements (see for
655
instance the dvd example in §-examples;) or when it is desired to configure a property
656
syntactically separated from the pipeline on the command line.
660
<term><option>--set-prop
662
element:prop:value<optional>:time</optional>
667
Sets property <replaceable>prop</replaceable> of
668
<replaceable>element</replaceable> to <replaceable>value</replaceable>,
669
where <replaceable>element</replaceable> can either be an element-type, or the
670
name or full path-string of a specific element.
671
If <replaceable>prop</replaceable> is a <literal>GST_CONTROLLABLE</literal>
672
property (use &gst-inspect; to determine this),
673
then a (pipeline media) <replaceable>time</replaceable> at which
674
<replaceable>prop</replaceable>
675
should be set to this particular <replaceable>value</replaceable>
676
(using the controller framework) can be given as well.
679
In general, a value given for a property within the pipeline description
680
will override any value provided this way. In case of <element>queue</element>s,
681
however, both <element>decodebin</element> and &entrans; will override some
682
properties' values in order to minimize the possibility of blocking.
683
Though it is not recommended, <option>set-prop</option> can be used
684
to forcibly overwrite such aforementioned defaults.
687
The rank of an element (as a plugin feature), which (a.o.) determines whether or
688
not it is considered for auto-plugging (in dynamic mode) is considered
689
as a pseudo-property <literal>pf_rank</literal> and can therefore be set
696
<term><option>--vb <replaceable>vkbitrate</replaceable></option></term>
697
<term><option>--ab <replaceable>akbitrate</replaceable></option></term>
700
Sets the <literal>bitrate</literal> property of any video or audio element to
701
<replaceable>vkbitrate</replaceable> <optional> * 1000</optional> or
702
<replaceable>akbitrate</replaceable> <optional> * 1000</optional> respectively,
703
depending on whether the property expects to be provided with (k)bitrate.
709
<term><option>--vq <replaceable>vquality</replaceable></option></term>
710
<term><option>--aq <replaceable>aquality</replaceable></option></term>
713
Sets either the <literal>quality</literal> or <literal>quantizer</literal>
714
property of any video or audio element to <replaceable>vquality</replaceable> or
715
<replaceable>aquality</replaceable> respectively.
722
<term><option>--pass <replaceable>pass</replaceable></option></term>
725
Sets the <literal>pass</literal> property of any video element to
726
<replaceable>pass</replaceable>, which
727
must be <literal>1</literal> or <literal>2</literal>.
734
<option>-t <replaceable>tag:value</replaceable>
740
&entrans; locates a <interfacename>TagSetter</interfacename> in
741
the pipeline and sets each given <replaceable>tag</replaceable> to
742
<replaceable>value</replaceable>.
745
A list of possible tags can be found in
746
<ulink url="&url-gst-home;data/doc/gstreamer/head/gstreamer/html/gstreamer-GstTagList.html">GStreamer core documentation</ulink>.
754
<refsect2 id="reporting-options"><title>Reporting options</title>
757
By default, &entrans; reports the following items at startup:
758
<itemizedlist spacing="compact">
761
an overview of elements found in the pipeline,
762
along with the current values of properties that differ from their
763
usual (default) setting;
764
tags announced by an element are considered as a pseudo-property
765
<literal>tag</literal> of the element
770
a set of distinct caps that have been found flowing through the pipeline,
775
the (video) queues found in the pipeline (with their neighbours),
776
and their maximum capacity settings (size, buffers, time)
780
After that, it provides the following in regular intervals, if already available
782
<itemizedlist spacing="compact">
785
(time) position in input stream,
790
movie time: position in output stream, and the total expected output movie time
795
processing speed: ratio of elapsed (input) stream time to elapsed CPU time
800
ETA: expected time to completion of processing;
801
this calculation <emphasis>always</emphasis> uses elapsed system clock time,
802
regardless of options below,
807
amount of buffers presently contained in the queues reported at startup,
812
if a specific output file can be identified, (combined) bitrate so far.
819
The following options can influence some of this behaviour:
822
<term><option>-d <replaceable>delay</replaceable></option></term>
823
<term><option>--delay <replaceable>delay</replaceable></option></term>
826
Sets the interval between progress updates to <replaceable>delay</replaceable>
827
seconds. The default delay is 2 seconds.
832
<term><option>--timeout <replaceable>timeout</replaceable></option></term>
835
As an &entrans; run spins up, it transitions through a number of stages, which
836
should normally follow each other in pretty rapid succession.
837
<replaceable>timeout</replaceable>, by default 4, is the maximum interval
838
(in seconds) that will be allowed between such stages. If the interval is exceeded,
839
&entrans; may simply abort altogether or try to recover the situation
840
(depending on the stage), the success of which depends on the cause
841
(e.g. a misbehaving element, or a badly constructed pipeline, …).
842
Evidently, a high <replaceable>timeout</replaceable> value essentially renders
843
this check mute. Setting it to 0 completely disables this check as well
844
as some other mechanisms employed to support it, and is not normally advisable.
849
<term><option>--progress-fps</option></term>
852
Makes regular reports also provide processing speed in fps, which is calculated
853
using either auto-detected framerate or provided by <option>-f</option>.
858
<term><option>--progress-real</option></term>
861
Calculate processing speed based on elapsed system clock time (instead of CPU-time).
869
In the following, <replaceable>proppattern</replaceable>
870
is a regular expression that will be matched a combination of
871
an <replaceable>element</replaceable> and (optionally) one its properties
872
<replaceable>prop</replaceable>. More precisely, this combination
873
matches if the regular expression matches any of the following:
874
<itemizedlist spacing="compact">
877
<replaceable>element's factory name</replaceable>.<replaceable>prop</replaceable>
882
<replaceable>element's name</replaceable>.<replaceable>prop</replaceable>
887
<replaceable>element's path name</replaceable>.<replaceable>prop</replaceable>
891
In each case, the last part is omitted if there is no
892
<replaceable>prop</replaceable> in the context in question.
895
Similarly, <replaceable>msgpattern</replaceable> is matched against
896
expressions as above, but with <replaceable>prop</replaceable> replaced by
897
<replaceable>message type name</replaceable>.<replaceable>message structure name</replaceable>
898
Again, in each case, the last part is omitted if there is no structure for the
904
<term><option>-m</option></term>
907
Output messages posted on the pipeline's bus
912
<term><option>-v</option></term>
915
Provide output on property changes of the pipeline's elements.
916
This output can be filtered using <option>-x</option>
921
<term><option>--short-caps</option></term>
924
Do not perform complete caps to string conversion, instead replace e.g. buffers
925
with their (string) type representation.
926
This can make for more comfortable display of e.g. Vorbis and Theora related caps.
932
<option>--ignore-msg <replaceable>msgpattern<optional>,…</optional></replaceable>
936
<option>--display-msg <replaceable>msgpattern<optional>,…</optional></replaceable>
941
[multi-valued] If message reporting is enabled by <option>-m</option>,
942
only report on those that match <option>--display-msg</option>
943
or do not match <option>--ignore-msg</option>
949
<option>-x <replaceable>proppattern<optional>,…</optional></replaceable>
953
<option>--exclude <replaceable>proppattern<optional>,…</optional></replaceable>
957
<option>--include <replaceable>proppattern<optional>,…</optional></replaceable>
962
[multi-valued] If property change reporting is enabled by <option>-v</option>,
963
only report those on properties that match <option>--include</option>
964
or do not match <option>--exclude</option>
970
<option>--display-prop <replaceable>proppattern<optional>,…</optional></replaceable>
974
<option>--ignore-prop <replaceable>proppattern<optional>,…</optional></replaceable>
979
[multi-valued] An element's property (value) is reported at start-up if and only if
980
it matches an expression given in <option>--display-prop</option>
981
or its value differs from the usual and it does not match
982
<option>--ignore-prop</option>.
983
Also, in any case, an element's presence in the pipeline is at least
984
mentioned by default, unless the element (by itself) matches
985
<option>--ignore-prop</option>
993
<refsect2 id="config-options"><title>Configuration options</title>
996
Each &entrans; option —be it one affecting &entrans;'
997
run-time behaviour or affecting pipeline element (properties)—
998
can also be provided on a more permanent basis using a configuration
1001
Such a file consists of sections, led by
1002
a <quote><literal>[section]</literal></quote> header and
1003
followed by <quote><literal>name: value</literal></quote> entries,
1004
<quote><literal>name=value</literal></quote> is also accepted.
1005
Note that leading whitespace is removed from values.
1006
Lines beginning with <quote><literal>#</literal></quote> or
1007
<quote><literal>;</literal></quote> are ignored and may be used to
1012
In the special section <quote><literal>[options]</literal></quote>,
1013
each entry <quote><literal>name: value</literal></quote>
1014
is equivalent to providing <option>--<replaceable>name</replaceable>
1015
<replaceable>value</replaceable></option> on the command-line,
1016
where <replaceable>name</replaceable> must be an option's longname.
1018
The name of any other section is interpreted as an element-type
1019
or an element, with each entry providing a value for a property.
1020
Otherwise put, each <quote><literal>prop: value</literal></quote>
1022
<quote><literal>[<replaceable>element</replaceable>]</literal></quote>
1023
is equivalent to mentioning it in <option>--set-prop</option> as
1024
<replaceable>element:prop:value</replaceable>
1028
By default, the configuration file is called <filename>.gst-entrans</filename>
1029
and is searched for in the current directory and in the user's home directory
1032
Any setting provided on the command line for a single-valued option
1033
(e.g. a boolean option) overrides a similar value given in a configuration file,
1034
whereas values provided for multi-valued ones append to those already provided.
1039
<term><option>--config <replaceable>file</replaceable></option></term>
1042
Use <replaceable>file</replaceable> <emphasis>instead</emphasis> of any
1043
default configuration file.
1048
<term><option>--profile <replaceable>file</replaceable></option></term>
1051
Load <replaceable>file</replaceable> <emphasis>after</emphasis> other
1052
configuration files, either default ones or given by <option>--config</option>.
1053
This option derives its name from its use in loading certain export or
1054
encoder profiles (e.g. MPEG1, MPEG2, etc),
1055
which are mainly a collection of presets for certain properties that can
1056
be kept in corresponding profile configuration files.
1064
<refsect2 id="misc-options"><title>Miscellaneous options</title>
1068
<term><option>--save
1069
<replaceable>message:file[:append]<optional>,…</optional>
1075
Makes &entrans; save a custom element <replaceable>message</replaceable> to
1076
<replaceable>file</replaceable>,
1077
that is, the string representation of the message's structure is saved
1078
(followed by a <token>linefeed</token>).
1079
If <replaceable>append</replaceable> is true (e.g. <literal>1</literal>, <literal>t</literal>,
1080
<literal>T</literal>), then all messages are appended to <replaceable>file</replaceable>,
1081
otherwise the default is to truncate <replaceable>file</replaceable> whenever
1082
<replaceable>message</replaceable> is received, thereby saving only the
1083
most recently received <replaceable>message</replaceable>.
1085
it might be noted here there was a change in version 0.10.15 in a structure's
1086
string representation with respect to usage of a terminating <token>;</token>.
1089
<replaceable>file</replaceable> will be subject to having <literal>${n}$</literal>
1090
replaced by the name of the element sending <replaceable>message</replaceable>.
1100
<refsect1 id="examples"><title>Examples</title>
1103
More examples of pipelines can also be found in &gst-launch;;
1104
the ones below are primarily meant to illustrate some of
1105
&entrans;' features.
1108
In each case, everything could also be written on one line, without the backslash
1109
character. In some cases, some particular quoting is needed to prevent
1110
(mis)interpretation by the shell.
1114
<title>Basic transcoding</title>
1117
entrans.py -i dvd://2 -o dvd.ogm --short-caps -- \
1118
--video ! theoraenc --audio audioconvert ! vorbisenc
1120
Transcodes complete title 2 from a DVD into a mixed Ogg containing all video
1121
and audio tracks (but no subtitles) using default settings, while preventing
1122
some extensive caps display.
1127
<title>Selected stream transcoding</title>
1130
entrans.py --set-prop dvdreadsrc:device:/mnt -i dvd://2 -o dvd.mkv \
1131
--set-prop dvdsubdec:pf_rank:128 --on 6,12 --an 1,2 --vq 4 --ab 256 -- \
1132
--video ffenc_mpeg4 --audio audioconvert ! lame \
1133
--other ffmpegcolorspace ! ffenc_mpeg4 ! matroskamux ! filesink location='sub-${on}.mkv'
1135
Transcodes video and selected audio tracks from a DVD image mounted at /mnt
1136
into a Matroska file, using the indicated fixed quantization and bitrate for
1137
video and audio respectively. Some selected subtitle tracks are also encoded
1138
as separate video streams into other Matroska files. Note that the rank of
1139
the <element>dvdsubdec</element> must be increased for a subtitle stream to be
1140
considered for decoding and subsequently made available.
1145
<title>Extensive progress update transcoding</title>
1148
entrans.py -i example-in.avi -o example-out.mkv -- \
1149
--video tee name=tee ! queue ! theoraenc \
1150
tee. ! queue ! timeoverlay ! xvimagesink sync=false qos=false \
1151
--audio audioconvert ! lame
1153
Transcodes into Matroska using Theora and MP3 codecs, while providing for
1154
(excessive) live preview progress info.
1159
<title>Partial stream transcoding</title>
1162
entrans.py -i dvd://2 -o dvd.mkv -c chapter:5- --short-caps -- \
1163
--video ! identity single-segment=true ! ffenc_mpeg4 \
1164
--audio audioconvert ! identity single-segment=true ! vorbisenc
1166
Transcodes all video and audio tracks from a DVD title 2 (chapter 5 to the end)
1167
into Matroska using MPEG4 and Vorbis codecs (while catering for properly
1168
timestamped input for the container which records these faithfully for posterity).
1172
<example id="ex-pass-through">
1173
<title>Pass-through transcoding</title>
1176
entrans.py -s seek-key -c 60-180 --dam -- --raw \
1177
filesrc location=example-in.avi ! avidemux name=demux \
1178
avimux name=mux ! filesink location=example-out.avi \
1179
demux.video_00 ! queue ! dam ! queue ! mux.video_0 \
1180
demux.audio_00 ! queue ! dam ! queue ! mad ! audioconvert ! lame ! mux.audio_0
1182
Transcodes a particular section from an AVI file into another AVI file without
1183
re-encoding video (but does re-encode audio, which is
1184
recommended). The output will range from (approximately) 60 seconds into the
1185
input up to 180 seconds; actually there will be a (key)seek to the nearest
1186
keyframe just before the 60 seconds point to ensure the integrity of later
1187
decoding of the output.
1188
In addition, &entrans; will report changes on any object's properties, except
1189
for any (pad's) caps.
1192
The pipeline above uses raw mode, and as such must abide
1193
by some rules and recommendations in pipeline building (see §-muxing-pipelines;),
1194
which leads in particular to the above abundance in <element>queue</element>s.
1195
With some extra configuration, pass-through could also be performed in
1196
dynamic mode as follows (assuming that <literal>video/mpeg</literal> properly
1197
describes the encoded video content):
1199
entrans.py -s seek-key -c 60-180 --decoder decodebin2 \
1200
--set-prop 'decodebin2:caps:video/mpeg;audio/x-raw-int;audio/x-raw-float' \
1201
-i example-in.avi -o example-out.avi -- \
1202
--video capsfilter caps=video/mpeg \
1203
--audio audioconvert ! lame
1210
<title>Live recording</title>
1214
entrans.py -s cut-time -c 0-60 -v -x '.*caps' --dam -- --raw \
1215
v4l2src queue-size=16 ! video/x-raw-yuv,framerate=25/1,width=384,height=576 ! \
1216
stamp sync-margin=2 silent=false progress=0 ! queue ! \
1217
dam ! ffenc_mpeg4 name=venc \
1218
alsasrc buffer-time=1000000 ! audio/x-raw-int,rate=48000,channels=1 ! queue ! \
1219
dam ! audioconvert ! queue ! lame name=aenc \
1220
avimux name=mux ! filesink location=rec.avi aenc. ! mux. venc. ! mux.
1223
Records 1 minute of video and audio from a video4linux device and features
1224
additional synchronization and reporting on object property changes (if any),
1225
which includes reports on frame drops or duplications, although
1226
(pad's) caps changes are excluded for convenience.
1231
<title>2-pass transcoding</title>
1234
entrans.py -i example-in.avi -o /dev/null --muxer avimux --vb 1200 --pass 1 \
1235
--save astat:astat.log -- --video ffenc_mpeg4 \
1236
--audio audioconvert ! astat ! fakesink
1237
SCALE="$(cat astat.log | sed 's/astat, scale=(double)//' | sed 's/;//')"
1238
entrans.py -i example-in.avi -o example-out.avi --vb 1200 --pass 2 \
1239
--tag 'comment:2-pass demonstration' -- \
1240
--video ffenc_mpeg4 --audio audioconvert ! volume volume=$SCALE ! lame
1242
Performs 2-pass transcoding from one AVI into another. The first pass also
1243
determines and saves the maximum volume scaling that can safely be applied
1244
without having to resort to clipping. It does not bother performing audio encoding
1245
or producing an output file. Although the particular (encoder compatible) muxer
1246
is hardly relevant here, one is nevertheless indicated explicitly
1247
as a <quote>reasonable</quote>choice cannot be determined
1248
from <literal>/dev/null</literal>. After some scripting to retrieve the
1249
saved value from a file, the second pass performs volume scaling and encoding.
1250
It also sets a comment (tag) in the resulting file to note its lofty goal.
1255
<title>Configuration file</title>
1258
<xi:include href="entrans.ini" parse="text" />
1260
A basic, though adequate configuration file that filters out some
1261
(usually less interesting) information on some <quote>technical</quote>
1262
technical elements, while making sure on the other hand that some other
1263
settings get displayed in any case. In addition, an element's properties
1264
can be given defaults (other than the hardcoded ones), and the rank
1265
of <element>dvdsubdec</element> is increased so that subtitles streams will
1271
<title>Profile configuration</title>
1273
Some examples of (encoding) profiles that can be passed to
1274
<option>--profile</option> (each profile is in a separate file).
1275
Note that profiles also impose
1276
constraints on e.g. width and height which are not automagically
1277
enforced; one must still take care of this by means of e.g. proper scaling.
1278
Similarly, the elements that are to perform the required encoding
1279
must be properly (manually) specified, though their configuration
1280
is then taken care of by the examples below.
1282
<xi:include href="profile-vcd.ini" parse="text" />
1285
<xi:include href="profile-svcd.ini" parse="text" />
1288
<xi:include href="profile-xvcd.ini" parse="text" />
1291
<xi:include href="profile-dvd.ini" parse="text" />
1299
<refsect1 id="requirements">
1300
<title id="requirements_title">Requirements</title>
1303
Evidently, there must be a basic &GStreamer; framework installation,
1304
the extent of which and available plugins determine the processing scope that
1306
Beyond this, it is highly recommended for the &dam; element to be available,
1307
which is part of the plugins supplied along with &entrans;.
1308
More (technical) details and motivation can be found in the documentation for
1309
&dam;, but suffice it to say that without &dam; the following notes apply:
1313
For <option>--seek</option>, only the methods
1314
<literal>seek</literal> and <literal>seek-key</literal> are available.
1315
However, for reasons explained in &dam; documentation and in
1316
§-muxing-pipelines;, even these methods can not be considered reliable,
1317
either functional or technical.
1318
As such, only full (uninterrupted) pipeline transcoding is really available.
1321
As a technical note, this unreliability could be alleviated by
1322
having the functionality to drop out-of-segment-bound buffers not only in sinks
1323
or in some elements, but as a specific ability in
1324
e.g. <element>identity</element>.
1329
The graceful (signal initiated) termination usually
1330
also relies on &dam;, and is quite sturdy in this case.
1331
However, and fortunately, there is also an alternative fall-back implementation
1332
that will take care of this in the vast majority of circumstances.
1338
Note that in case of dynamic pipelines, the availability of the &dam; element
1339
in the system is auto-detected, and the proper pipeline-construction action is
1340
taken accordingly. In raw mode, however, it must be explictly confirmed (by
1341
<option>--dam</option>) that &dam;s are properly used, otherwise none will
1342
be assumed present and only restricted operation is then available, as indicated
1343
above. Proper usage of &dam; is subject to comments in §-muxing-pipelines;,
1344
but basically comes down to putting a &dam; as upstream as possible in each
1345
independent stream, e.g. preceding some queue. Alternatively, such a queue could
1346
be used as <quote>surrogate dam</quote> by naming it
1347
<literal>dam<replaceable><digits></replaceable></literal>.
1352
<title>GNonLin Comparison</title>
1354
On the one hand, one might compare in the sense that both GNonLin and &entrans;
1355
aim to create media files while allowing for non-linear editing/cutting.
1356
On the other hand, &entrans; is quite complementary and can actually be combined
1357
with GNonLin, for example
1360
entrans.py -- --raw gnlcomposition. '(' name=comp gnlfilesource \
1361
location=test.avi start=0 duration=20000000000 media-start=0 \
1362
media-duration=20000000000 caps=video/x-raw-yuv ')' \
1363
comp.src ! ffenc_mpeg4 ! queue ! avimux ! filesink location=test-gnonlin.avi
1368
That being the case, why this alternative and yet another program, rather than
1369
being content with e.g. GNonLin (and &gst-launch;) ?
1373
First and foremost, as a matter of style. The above example pipeline looks and
1374
feels rather contrived (and that's only the video part!), and is not much of a
1375
<emphasis>pipeline</emphasis> in that e.g. <element>gnlcomposition</element> is
1376
really (deliberately) not so much a pipeline than it is more of a bag (serving
1377
its intended purpose well). On the other hand, Un*x pipelines have a long
1378
standing beauty (and a.o. adaptability and flexibility), and a (traditional)
1379
&GStreamer; pipeline continues in that tradition. In that sense, &entrans;'
1380
(and &gst-launch;) approach is an <quote>ode to pipeline</quote> and its
1381
inherent simplicity and clarity of intent.
1382
In particular, typical &entrans; pipelines are only slightly different than
1383
playback pipelines, and the cutting/seeking mechanism is pretty identical.
1384
In that way, an &entrans; media file creation is very close to a
1385
(non-linear) playback session (and closer than a GNonLin equivalent would be).
1388
Secondly, there are some technical reasons. Particular care has been given
1389
in &entrans; to the non-linear cutting functionality to make sure it operates
1390
with great precision in a variety of circumstances. In this area;
1394
GNonLin, in particular <element>gnlcomposition</element>, may (and has been
1395
known to) experience some frame-dropping near end-of-stream due to its
1396
(asynchronous) technique of EOS-event generation
1400
GNonLin only relies on segment seek, as does &entrans; usually, which
1401
is fine when dealing with elements that support what and how they are supposed
1402
to. However (and unfortunately), elements are not always so perfect (for
1403
example, <element>dvdreadsrc</element> does not support segment seek).
1404
In such cases, &entrans; has some plain-and-simple alternative methods that can
1405
still get the (cutting) job done.
1408
So, the idea and intention basically is; if you can play it, you can &entrans;
1409
it (with a similar pipeline, and precision in various circumstances).
1414
<refsect1 id="muxing-pipelines"><title>Muxing Pipelines</title>
1416
As mentioned earlier, one might run into some pitfalls when constructing
1417
a (raw) pipeline, most of which are taken care of by &entrans; when runnning in
1421
<title>Building</title>
1422
To begin with, the pipeline must be properly built and linked,
1423
in particular to the muxer element, which typically only has request pads.
1424
For linking and subsequent negotiation to succeed, a stream must manage
1425
to get the request pad it really needs and is compatible with. That means that
1426
the element connecting to the muxer (or trying so) should provide enough
1427
(static) information to identify the corresponding muxer pad (template).
1428
As this information is typically derived from the connecting element's
1429
pad templates, it is not quite comfortable to try connecting a generic
1430
element (e.g. <element>queue</element>). If this were needed, or there is some
1431
or the other problem connecting to the muxer, then it may be helpful to use
1432
a capsfilter (aka as a filtered connection) or to specifically
1433
indicate the desired muxer pad (by a name corresponding to the intended
1434
template, as in example <xref linkend="ex-pass-through"/>),
1435
see also &gst-launch; for specific syntax in either case.
1438
<title>Muxer and Queue</title>
1439
In the particular case of a transcoding pipeline (having some media-file
1440
as source), some other care is needed to make sure it does not stall, i.e.
1441
simply block without any notification (or an application having
1442
a chance to do something about it). Specifically, a muxer will often block a
1443
thread on its incoming pad until it has enough data across all of its pads for
1444
it to make a decision as to what to mux in next.
1445
Evidently, if a single (demuxer) thread were having to provide data to several
1446
pads, then stalling would almost surely occur. As such, each of these
1447
pads/streams should have its own thread. In case of live sources, this is
1448
usually already the case, e.g. separate video and audio capturing threads.
1449
However, when transcoding, and therefore demuxing an input file, a
1450
<element>queue</element> should be inserted into each outgoing stream to act as
1451
a thread boundary and supply a required separate thread.
1452
In addition, this multi-threading will evidently also spread processing across
1453
several CPUs (if available) and improve performance. In this respect, it
1454
can also be beneficial to use more than 1 <element>queue</element>/thread per
1455
stream; one that performs filter processing (if any) and one that performs
1459
Note that similar stalling can also occur in some variations of these
1460
circumstances. For instance, <element>tee</element> could have the role of
1461
demuxer in the above story, and/or a collection of several sinks in a
1462
pipeline could act as a muxer in the above story, since they will each also
1463
block a thread in PAUSED state (when the pipeline is trying to make it to
1464
that state). Another such situation can arise (temporarily) when pads are
1465
blocked as part of the seek-mechanism. In any case, the remedy is the same;
1466
use <element>queue</element>s to prevent one thread from having to go around in
1467
too many places, and ending up stuck in one of them.
1470
<title>Muxer and Time(stamps)</title>
1471
Even if the above is taken into account, the time-sensitivity of a typical
1472
muxer may lead to (at first sight mysterious) stalling (in transcoding
1473
pipelines). That is, a muxer will usually examine the timestamps of the incoming
1474
data, select the oldest of these to be put into the outgoing stream and then
1475
wait for new data to arrive on this selected input stream (i.e. keep other
1476
streams/threads wait'ing).
1477
It follows easily that if there is a gap, <quote>imbalance</quote>,
1478
imperfection, irregularity (or however described) in timestamps between various
1479
incoming streams, a muxer will then consistently/continuously
1480
expect/want more data on 1 particular pad (for some
1481
amount proportional to the irregularity).
1482
For some time, this need could be satisfied by the <element>queue</element>s
1483
that are present in this stream. At some point, however, these may not hold
1484
enough data and will need further input from the upstream demuxer element.
1485
However, for this demuxer to provide data for 1 of its (outgoing) streams, it
1486
will also need to output data for the other streams, and this ends up
1487
into the other streams' <element>queue</element>s. Unfortunately, in
1488
this situation those queues cannot send out any data, as the muxer is
1489
holding their threads (blocked). Hence, they will (soon) fillup and then in
1490
turn block the demuxer thread trying to insert data, until there is again space
1491
available. Consequently, a deadlock circle ensues; muxer waiting for new
1492
data from queue, waiting for data from demuxer, waiting for space to put this
1493
into another stream queue, waiting to unload data into the muxer.
1494
Note that this deadlock phenomenom will not occur with live (recording) pipelines,
1495
as the various threads are then not joined to a single demuxer (thread),
1496
though it is then likely to manifest itself it by loss of (live) input data.
1499
There a number of possible causes for the irregularities mentioned above.
1503
Rarely, but not impossibly so, the problem may be inherent in the very input
1504
medium itself. Or there could be a problem with a (experimental) demuxer
1505
that might produce incorrect timestamps.
1510
If a (segment) seek is performed in a pipeline <emphasis>without</emphasis>
1511
using &dam;, it is quite likely that some stream(s) may perform proper
1512
filtering of out-of-segment-bound data, and that other(s) may not. This would
1513
then cause a typical imbalance between the various streams.
1518
If timestamps are being resequenced in some incoming streams (e.g. by
1519
&identity;), but not in the other ones, there is an obvious imbalance.
1524
Though more exotic, even if &dam; is being used, one must take care to perform
1525
this filtering <emphasis>before</emphasis> (the by now
1526
clearly essential) <element>queue</element> in the respective stream,
1527
particularly when several distinct sections are to be cut out of the input.
1528
After all, if <element>queue</element> were placed before &dam;, then the
1529
latter does not have a chance to drop unneeded buffers soon enough.
1530
As such, if a muxer tries to get the first piece of data on a
1531
particular pad following the gap between the sections, these
1532
<element>queue</element>s would fillup and be effectively as if they were not
1540
<title>Dynamic mode services</title>
1542
Dynamic mode takes care of (most of) the above as follows:
1546
Pipeline building is performed almost completely automagically.
1547
Of course, this does not mean it can fit a square into a circle, so some
1548
consideration for compatibility and negotiation is still in order.
1553
<element>queue</element>s are inserted where needed and/or useful,
1554
either by <element>decodebin</element> or by &entrans;
1559
Whenever available (recommended), &dam; is used and inserted in proper locations.
1569
<refsect1><title>See Also</title>
1572
<ulink url="&url-gst-home;">&GStreamer; homepage</ulink>,
1574
<ulink url="&url-gst-entrans-plugins;">entrans plugins</ulink>
1579
<title>Author</title>
1582
Mark Nauwelaerts <email>mnauw@users.sourceforge.net</email>
added
removed
docs/manual/entrans.xml
