1entrans(1) entrans(1)
2
6 entrans - build and run GStreamer transcoding pipeline
7
9 entrans [OPTION]... {--} {PIPELINE-OPTION}...
10
12 entrans builds and runs a GStreamer pipeline, primarily intended for
13 transcoding, encoding or recording purposes.
14 On the one hand, it is much like gst-launch(1) in that it has no ambi‐
16 tions to go beyond command-line (or script) driven processing.
17 On the other hand, it has quite a few enhancements that provide appli‐
19 cation-level functionality sufficiently comfortable and suitable for
20 plain-and-simple (and robust) transcoding, encoding or recording using
21 the GStreamer framework and plugins:
22 · Pipeline to run can be specified manually, or can be built dynamical‐
24 ly based on inputstream and pipeline fragments (see OPERATION), which
25 takes care of most of the boilerplate (and of some pitfalls to watch
26 out for with transcoding pipelines, see also MUXING PIPELINES).
27 · Provides some typically relevant (configurable) interesting info re‐
29 garding the pipeline (elements, properties, queues, ...) and caps
30 flowing in pipeline.
31 · Regular progress updates are provided.
33 · Limited support for tag setting (whenever a TagSetter is present).
35 · Property configuration support; settings can be applied from what is
37 stored in a config file and there is also some custom support for
38 setting popular options (e.g. bitrate).
39 · Last but not least (convenient), processing can be restricted to spe‐
41 cific portions of the input(stream) (mind REQUIREMENTS).
42 · Graceful shutdown of processing at any time, and still well-formed
44 output as result (mind REQUIREMENTS).
45 Another (technical) difference is that it is written in python ⟨http://
47 www.python.org/⟩ , using the python bindings for the GStreamer frame‐
48 work (gst-python), which makes many of the enhancements much more com‐
49 fortable to implement and easy to adjust (to taste).
50
52 As already alluded to above, entrans fundamentally operates in one of
53 the following ways, also loosely called modes:
54 · Raw mode. The pipeline to construct, run and manage is explictly
56 given manually (see --raw). On the one hand, this mode allows full
57 freedom in pipeline construction and can be great for diagnosing and
58 debugging. On the other hand, if this freedom is not properly used,
59 all sorts of things can go wrong (blocking, ...) see MUXING PIPELINES
60 and REQUIREMENTS [do not even try to run in this mode if what is
61 stated there is not fully clear and understood]. For now, this mode
62 is also required for performing e.g. video-passthrough transcoding
63 (perhaps more appropriately called re-muxing in this case).
64 · Dynamic mode. decodebin is applied to the inputstream, which will
66 automagically provide all the streams present in the input in their
67 decoded raw (video, audio or other, e.g. text) form. Each of these
68 streams is then connected to an instance of a pipeline (fragment)
69 given by --video, --audio or --other, each typically containing fil‐
70 ters and/or encoder. An optional subsequent step is trying to connect
71 this to an appropriately selected muxer for the output.
72 In any case, no (advanced) error processing or sane-ness checking is
74 performed on either pipeline or pipeline fragments. As such, linking,
75 negotiation or other matters can very well fail, e.g. if fragments do
76 not contain encoder elements that are compatible with the muxer in
77 question. It is also possible for some parts of the pipeline to simply
78 remain disconnected and the corresponding stream being effectively dis‐
79 carded (this might also be used as a feature ;-) ). Reporting on any
80 of these occurrences is of course done in as much as the pipeline pro‐
81 vides info on what is happening.
82 Though this may sound ominous, in practice, this comes down to either
84 things working out just nicely or finding out about something going
85 wrong in a more or less fast and hard way. Having a look at EXAMPLES
86 should increases chances on the former being the case, and should even
87 provide enough for a jump-start based on some GStreamer experience.
88 Processing can be halted at any time by sending a SIGINT or SIGTERM
90 signal to entrans. This will make entrans block the data-flow and send
91 an end-of-stream event through the pipeline to ensure graceful termina‐
92 tion of streaming. As such, it should be noted that termination may
93 not occur instantly, it might take a moment for things to run out (par‐
94 ticularly with some queues around).
95 If in rare cases this mechanism were to fail, sending such a signal a
97 second time will forego any attempts at graceful shutdown and will make
98 entrans end things the hard way with no guarantee on the output being
99 fully OK (it will most likely not be) ...
100 Note
102 Due to the way the python interpreter handles signals, even the
104 above may not work if things are messed up seriously, e.g. when
105 python interpreter is caught up somewhere in GStreamer backend
106 code. This, however, has only been known to happen as a prelude
107 to finding some serious application bug or GStreamer plugin/core
108 bug. Regardless, e.g. SIGKILL is then your friend ...
109
111 entrans accepts the options presented in the following sections, most
112 of which have shortname (one-letter) or longname forms. The ordering
113 of the options is not strict, and options can be single-valued or mul‐
114 ti-valued.
115 · In the former case, which is the default unless otherwise indicated
117 below, only the value given last is retained. In particular, this
118 includes boolean options. If such an option is given, the corre‐
119 sponding setting is turned on. The setting can also be explictly
120 turned off by providing the corresponding --no-longname option.
121 · Otherwise, for multi-valued options, all values given are taken into
123 consideration. In these cases, it may sometimes also be possible to
124 pass several values per single option occurrence, by comma-separating
125 these values as indicated in each such case below. This will typical‐
126 ly be the case in those instances where there can be no ambiguity
127 since the supplied value does not include free-text.
128 -h, --help
130 Show a brief help message.
131 PIPELINE OPTIONS
133 At least one of the following options should be provided following --
134 (in each case, see gst-launch(1) for the syntax of pipeline-descrip‐
135 tion). Clearly, as explained previously, the former option excludes
136 all of the latter ones.
137 --raw pipeline-description
139 Makes entrans run in raw mode, and provides the complete pipe‐
140 line for this mode of operation.
141 Again, this should be used with expertise and being aware of
143 comments in MUXING PIPELINES and REQUIREMENTS.
144 --video[:streamnumber] pipeline-description
146 pipeline-description describes a pipeline fragment for video da‐
147 ta processing, typically consisting of 0 or more filters fol‐
148 lowed by an encoder.
149 --audio[:streamnumber] pipeline-description
151 Similar to --video, except that it provides a pipeline for (op‐
152 tionally) processing and encoding audio data.
153 --other[:streamnumber] pipeline-description
155 Similar to the above options, except that it provides a pipeline
156 for (optionally) processing and/or encoding data that does not
157 fit in the above categories, e.g. subtitles.
158 --decoder decoder-factory
160 Use decoder-factory instead of the default decodebin to con‐
161 struct the decoding part of the pipeline in dynamic mode (as
162 mentioned earlier). The given element should have compatible
163 behaviour/signals with decodebin, which should be the case for
164 any GstBin derived element.
165 The above (partial) pipelines should typically have an encoder as last
167 element. In any case, it should best not be a generic element, as that
168 might cause confusion as to how to link to the muxer (see also MUXING
169 PIPELINES).
170 It is also possible to close any of the above pipeline fragments by
172 ending it with a sink element. In this case, the resulting stream will
173 not be muxed and each can have independent output, e.g. streamed to a
174 file. As each of these would evidently need to have distinct names,
175 there is (extremely) limited support for variable substitutions. Each
176 (video and audio) stream that dynamically becomes available is (inde‐
177 pendently) numbered, starting from 1, and as such assigned an (audio or
178 video) stream number. Any element property of type string will be sub‐
179 ject to having ${vn}, ${an} and ${on} replaced by the video, audio and
180 other stream number (at that time) respectively in video, audio or oth‐
181 er pipeline fragments. If any of the above have a streamnumber append‐
182 ed, then that fragment will only apply to that particular stream, oth‐
183 erwise it will be the default fragment. If no specific or default frag‐
184 ment has been provided for a particular stream, then that stream will
185 be discarded. This effect is similar to the use of --vn, --an or --on
186 (see next section).
187 INPUT/OUTPUT OPTIONS
189 The option in this section are only applicable in dynamic mode, so in‐
190 compatible with --raw.
191 -i uri, --input uri
193 Indicates the input source. If uri is a valid URI, then a proper
194 source element will be selected, otherwise it is simply taken as
195 a (relative) path of an inputfile. If uri is -, then stdin will
196 be used as input.
197 -o uri, --output uri
199 Indicates the output destination. If output is a valid URI, then
200 a corresponding sink element is selected, otherwise it is taken
201 as a (relative) path of an outputfile (output to stdout is not
202 supported). The (file)suffix of uri is used to automagically
203 choose an appropriate muxer, which can be overridden with --mux‐
204 er
205 --muxer mux-element
207 Use mux-element in stead of the automatically selected one, or
208 if one fails to be auto-selected. mux-element must be of Muxer
209 class.
210 --encoding-profile targetname:profilename[:category]
212 Optionally (and incompatible with the previous option), one can
213 use the encodebin helper element to handle most of the encoding
214 details, such as selecting appropriate encoders and enforcing
215 certains constraints (e.g. resolution) as indicated by the en‐
216 coding profile selected by this option. While it is still pos‐
217 sible to provide pipeline-description fragments, this is typi‐
218 cally not necessary (and requires proper care for these to be
219 compatible on both ends).
220 As mentioned in the previous section, all streams found in the input
222 are assigned a stream number and considered for processing, unless
223 somehow restricted by the following options.
224 --vn streamnumber[,...], --an streamnumber[,...], --on streamnum‐
226 ber[,...]
227 [multi-valued] Only the video, audio or other streams with (re‐
228 spectively) listed streamnumber will be considered, others dis‐
229 regarded. Furthermore, streams of each type will be muxed into
230 the target in the order in which their streamnumbers are given
231 in these options, and in overall first video, then audio and
232 others.
233 --sync-link
235 This option is mainly meant for testing and diagnostic purposes.
236 It basically disables the stream(re)-ordering mechanism as im‐
237 plied by and explained in the above option (though still retains
238 stream selection).
239 --at tag[,...]
241 [multi-valued] Audio streams can (though need not) be accompa‐
242 nied by a language tag (typically a 2- or 3-letter language
243 code). The regular expression tag is matched against each de‐
244 tected audio stream's language tag and only streams without lan‐
245 guage tag or streams with a matching language tag are processed,
246 others disregarded. This selection method cannot be combined
247 with the above streamnumber based selection.
248 Note
250 The current (or another?) method of implementing this selection
252 may very well not work with all muxer elements. As such, this
253 option can be given a try, but if not successful, the much more
254 robust --an should be used instead. The proper number(s) to use
255 for this may be derived from (ordered) tag information that is
256 provided by some elements and reported at start-up.
257 --stamp
259 This is enabled by default, and makes entrans insert an identity
260 element (with single-segment True) before the connected pipe‐
261 line-fragment to perform timestamp re-sequencing. This is typi‐
262 cally useful when muxing into a format that records timestamps
263 (and does not hurt when the format does not).
264 BASIC OPTIONS
266 Whereas no specific dependencies exist for all other options, the RE‐
267 QUIREMENTS section applies particularly to the following options (in
268 more or less degree).
269 -c [[(]format[)]:]t1-t2[,...], --cut [[(]format[)]:]t1-t2[,...]
271 [multi-valued] Only process the indicated sections of the pipe‐
272 line (by default the complete input is processed). The option -s
273 determines the method used for selecting the desired data.
274 If no format is provided, the tN parameters can be given in
276 timecode format HH:MM:SS.FRACTION or as a (video)framenumber,
277 which is a number following f or F. Any buffer that overlaps
278 with the indicated section is taken into account. The last indi‐
279 cated section may be open-ended, i.e. the end point may be omit‐
280 ted.
281 However, if format is the nickname of a pre-defined or custom
284 format (defined by some element in the pipeline), then it is
285 used as unit for the tN numbers. In this case, option -s below
286 must select a seek-based method, and the seek will be executed
287 in format if it is provided without matching (...), otherwise
288 the given units will be (query) converted to time format first,
289 and these results will be used to seek in time.
290 -s method, --section method
292 Possible choices for method are:
293 seek Sections are selected by means of regular GStreamer
295 seeks. A flushing seek is performed for the first sec‐
296 tion, segment seek for the others, and a normal seek for
297 the last section. This is also the default method and is
298 OK for most circumstances. In some cases, however, the
299 other methods may be in order, e.g. when (the driving el‐
300 ement in) the pipeline does not support some type of seek
301 that would be used.
302 seek-key
304 This is similar to the case above, but each seek is also
305 a keyframe seek, that is, the actual selection may not be
306 exactly the one that was requested but may start at the
307 nearest keyframe preceding the desired start. This would
308 typically be required when performing re-muxing without
309 fully decoding and re-encoding the material.
310 cut-time
312 In this case, the pipeline is run from the start (without
313 any seeks) and all but the desired sections are disre‐
314 garded. The decision whether or not to drop a piece of
315 data is based on its timestamp. This is the recommended
316 (only possible) method to use when performing A/V sync
317 correction using data-timestamp shifting, e.g. by means
318 of the entransshift element. It can also be used to end a
319 live source(s) driven pipeline after a specified dura‐
320 tion.
321 cut This method applies in case any/all of the above fail,
323 e.g. some element does not support seek or unreliable
324 timestamps are produced in the pipeline. No seeks or
325 anything special is done, the pipeline is run from the
326 start and all but the indicated sections is dropped.
327 Timestamps on the datastream are disregarded, and the in‐
328 coming data is restamped based on framecount and framer‐
329 ate (video), or on sample count and samplerate (audio).
330 In particular, audio cutting is performed up to sample
331 precision.
332 Note that the last 2 methods require the desired sections to be in as‐
334 cending order, whereas the former methods make it possible to select
335 sections that are out-of-order with regards to the input material.
336 -a Perform (audio) sample precision selection, that is, it is pos‐
338 sible for only parts of buffers to be passed or dropped. This is
339 done by default in the cut method above, but not for the other
340 methods.
341 --dam Indicate, or rather, confirm that entransdam elements are being
343 used in raw pipelines. Otherwise, surrogate dam elements will
344 be searched for and used instead. These are identified as ele‐
345 ments whose name is of the form dam<digits>.
346 -f framerate, --framerate framerate
348 The framerate that is used for framenumber to time conversion is
349 normally auto-detected (soon enough) within the pipeline. If
350 this were not to succeed, then framerate, specified as NUM[/DE‐
351 NOM], is used as a fallback instead of the otherwise default
352 25/1.
353 -b, --block-overrun
355 This makes entrans prevent automatic adjustments to queues (in a
356 decodebin), thereby keeping them at fixed size.
357 Despite all the automagic, the pipeline may stall in exotic cas‐
359 es (e.g. some strange behaving element/muxer, ...). A good first
360 thing to try then is to configure queues at a larger-than-de‐
361 fault setting (see for example following section) and to use
362 this option to ensure they really remain configured as intended
363 without any other influence.
364 PIPELINE CONFIGURATION
366 Although element properties are typically set in the pipeline descrip‐
367 tions, the following options can be useful for dynamically created ele‐
368 ments (see for instance the dvd example in EXAMPLES) or when it is de‐
369 sired to configure a property syntactically separated from the pipeline
370 on the command line.
371 --set-prop element:prop:value[:time]
373 Sets property prop of element to value, where element can either
374 be a factory name, or the name or full path-string of a specific
375 element. If prop is a GST_CONTROLLABLE property (use gst-in‐
376 spect(1) to determine this), then a (pipeline media) time at
377 which prop should be set to this particular value (using the
378 controller framework) can be given as well.
379 In general, a value given for a property within the pipeline de‐
381 scription will override any value provided this way. In case of
382 queues, however, both decodebin and entrans will override some
383 properties' values in order to minimize the possibility of
384 blocking. Though it is not recommended, set-prop can be used to
385 forcibly overwrite such aforementioned defaults.
386 The rank of an element (as a plugin feature), which (a.o.) de‐
388 termines whether or not it is considered for auto-plugging (in
389 dynamic mode) is considered as a pseudo-property pf_rank and can
390 therefore be set in this way as well.
391 --vb vkbitrate, --ab akbitrate
393 Sets the bitrate property of any video or audio element to vkbi‐
394 trate [ * 1000] or akbitrate [ * 1000] respectively, depending
395 on whether the property expects to be provided with (k)bitrate.
396 --vq vquality, --aq aquality
398 Sets either the quality or quantizer property of any video or
399 audio element to vquality or aquality respectively.
400 --pass pass
402 Sets the pass property of any video element to pass, which must
403 be 1 or 2.
404 -t tag:value, --tag tag:value
406 [multi-valued] entrans locates a TagSetter in the pipeline and
407 sets each given tag to value.
408 A list of possible tags can be found in GStreamer core documen‐
410 tation ⟨http://www.gstreamer.net/data/doc/gstreamer/head/
411 gstreamer/html/gstreamer-GstTagList.html⟩ .
412 REPORTING OPTIONS
414 By default, entrans reports the following items at startup:
415 · an overview of elements found in the pipeline, along with the current
417 values of properties that differ from their usual (default) setting
418 · tags discovered on decodebin's pads (in dynamic mode); for purposes
420 of report-filtering it is considered a pseudo-property tag of the pad
421 · a set of distinct caps that have been found flowing through the pipe‐
423 line,
424 · the (video) queues found in the pipeline (with their neighbours), and
426 their maximum capacity settings (size, buffers, time)
427 After that, it provides the following in regular intervals, if already
429 available or applicable:
430 · (time) position in input stream,
432 · movie time: position in output stream, and the total expected output
434 movie time
435 · processing speed: ratio of elapsed (input) stream time to elapsed CPU
437 time
438 · ETA: expected time to completion of processing; this calculation al‐
440 ways uses elapsed system clock time, regardless of options below,
441 · amount of buffers presently contained in the queues reported at
443 startup,
444 · if a specific output file can be identified, (combined) bitrate so
446 far.
447 The following options can influence some of this behaviour:
449 -d delay, --delay delay
451 Sets the interval between progress updates to delay seconds. The
452 default delay is 2 seconds.
453 --timeout timeout
455 As an entrans run spins up, it transitions through a number of
456 stages, which should normally follow each other in pretty rapid
457 succession. timeout, by default 4, is the maximum interval (in
458 seconds) that will be allowed between such stages. If the inter‐
459 val is exceeded, entrans may simply abort altogether or try to
460 recover the situation (depending on the stage), the success of
461 which depends on the cause (e.g. a misbehaving element, or a
462 badly constructed pipeline, ...). Evidently, a high timeout
463 value essentially renders this check mute. Setting it to 0 com‐
464 pletely disables this check as well as some other mechanisms em‐
465 ployed to support it, and is not normally advisable.
466 --progress-fps
468 Makes regular reports also provide processing speed in fps,
469 which is calculated using either auto-detected framerate or pro‐
470 vided by -f.
471 --progress-real
473 Calculate processing speed based on elapsed system clock time
474 (instead of CPU-time).
475 In the following, proppattern is a regular expression that will be
477 matched against a combination of an element and (optionally) one of its
478 properties prop. More precisely, this combination matches if the regu‐
479 lar expression matches any of the following:
480 · element's factory name.prop
482 · element's name.prop
484 · element's path name.prop
486 In each case, the last part is omitted if there is no prop in the con‐
488 text in question.
489 Similarly, msgpattern is matched against expressions as above, but with
491 prop replaced by message type name.message structure name. Again, in
492 each case, the last part is omitted if there is no structure for the
493 message in question.
494 -m Output messages posted on the pipeline's bus
496 -v Provide output on property changes of the pipeline's elements.
498 This output can be filtered using -x
499 --short-caps
501 Do not perform complete caps to string conversion, instead re‐
502 place e.g. buffers with their (string) type representation.
503 This can make for more comfortable display of e.g. Vorbis and
504 Theora related caps.
505 --ignore-msg msgpattern[,...] , --display-msg msgpattern[,...]
507 [multi-valued] If message reporting is enabled by -m, only re‐
508 port on those that match --display-msg or do not match --ig‐
509 nore-msg
510 -x proppattern[,...] , --exclude proppattern[,...] , --include proppat‐
512 tern[,...]
513 [multi-valued] If property change reporting is enabled by -v,
514 only report those on properties that match --include or do not
515 match --exclude
516 --display-prop proppattern[,...] , --ignore-prop proppattern[,...]
518 [multi-valued] An element's property (value) is reported at
519 start-up if and only if it matches an expression given in --dis‐
520 play-prop or its value differs from the default value and it
521 does not match --ignore-prop. Also, in any case, an element's
522 presence in the pipeline is at least mentioned by default, un‐
523 less the element (by itself) matches --ignore-prop
524 CONFIGURATION OPTIONS
526 Each entrans option —be it one affecting entrans' run-time behaviour or
527 affecting pipeline element (properties)— can also be provided on a more
528 permanent basis using a configuration file. Such a file consists of
529 sections, led by a [section] header and followed by name: value en‐
530 tries, name=value is also accepted. Note that leading whitespace is
531 removed from values. Lines beginning with # or ; are ignored and may
532 be used to provide comments.
533 In the special section [options], each entry name: value is equivalent
535 to providing --name value on the command-line, where name must be an
536 option's longname. If the option is multi-valued and does not accept a
537 comma-separated list of values, then name may also have _0 or _1 (and
538 so forth) appended to it. The name of any other section is interpreted
539 as an element, with each entry providing a value for a property. Oth‐
540 erwise put, each prop: value in a section [element] is equivalent to
541 mentioning it in --set-prop as element:prop:value
542 By default, the current directory and the user's home directory is
544 searched for a configuration file called .gst-entrans whereas en‐
545 trans.conf is searched for in XDG_HOME_CONFIG directory (typically
546 $HOME/.config) (in that order).
547 Any setting provided on the command line for a single-valued option
549 (e.g. a boolean option) overrides a similar value given in a configura‐
550 tion file, whereas values provided for multi-valued ones append to
551 those already provided.
552 --config file
554 Use file instead of any default configuration file.
555 --profile file
557 Load file after other configuration files, either default ones
558 or given by --config. This option derives its name from its use
559 in loading certain export or encoder profiles (e.g. MPEG1,
560 MPEG2, etc), which are mainly a collection of presets for cer‐
561 tain properties that can be kept in corresponding profile con‐
562 figuration files.
563 MISCELLANEOUS OPTIONS
565 --save message:file[:append][,...]
566 [multi-valued] Makes entrans save a custom element message to
567 file, that is, the string representation of the message's struc‐
568 ture is saved (followed by a linefeed). If append is true (e.g.
569 1, t, T), then all messages are appended to file, otherwise the
570 default is to truncate file whenever message is received, there‐
571 by saving only the most recently received message. For good
572 measure, it might be noted here there was a change in version
573 0.10.15 in a structure's string representation with respect to
574 usage of a terminating ;.
575 file will be subject to having ${n}$ replaced by the name of the
577 element sending message.
578
580 More examples of pipelines can also be found in gst-launch(1); the ones
581 below are primarily meant to illustrate some of entrans' features.
582 In each case, everything could also be written on one line, without the
584 backslash character. In some cases, some particular quoting is needed
585 to prevent (mis)interpretation by the shell.
586 Basic transcoding
588 entrans.py -i dvd://2 -o dvd.ogm --short-caps -- \
590 --video ! theoraenc --audio audioconvert ! vorbisenc
591 Transcodes complete title 2 from a DVD into a mixed Ogg containing all
594 video and audio tracks (but no subtitles) using default settings, while
595 preventing some extensive caps display.
596 Selected stream transcoding
598 entrans.py --set-prop dvdreadsrc:device:/mnt -i dvd://2 -o dvd.mkv \
600 --set-prop dvdsubdec:pf_rank:128 --on 6,12 --an 1,2 --vq 4 --ab 256 -- \
601 --video avenc_mpeg4 --audio audioconvert ! lamemp3enc \
602 --other videoconvert ! avenc_mpeg4 ! matroskamux ! filesink location='sub-${on}.mkv'
603 Transcodes video and selected audio tracks from a DVD image mounted at
606 /mnt into a Matroska file, using the indicated fixed quantization and
607 bitrate for video and audio respectively. Some selected subtitle tracks
608 are also encoded as separate video streams into other Matroska files.
609 Note that the rank of the dvdsubdec must be increased for a subtitle
610 stream to be considered for decoding and subsequently made available.
611 Extensive progress update transcoding
613 entrans.py -i example-in.avi -o example-out.mkv -- \
615 --video tee name=tee ! queue ! theoraenc \
616 tee. ! queue ! timeoverlay ! xvimagesink sync=false qos=false \
617 --audio audioconvert ! lamemp3enc
618 Transcodes into Matroska using Theora and MP3 codecs, while providing
621 for (excessive) live preview progress info.
622 Partial stream transcoding
624 entrans.py -i dvd://2 -o dvd.mkv -c chapter:5- --short-caps -- \
626 --video ! identity single-segment=true ! avenc_mpeg4 \
627 --audio audioconvert ! identity single-segment=true ! vorbisenc
628 Transcodes all video and audio tracks from a DVD title 2 (chapter 5 to
631 the end) into Matroska using MPEG4 and Vorbis codecs (while catering
632 for properly timestamped input for the container which records these
633 faithfully for posterity).
634 Pass-through transcoding
636 entrans.py -s seek-key -c 60-180 --dam -- --raw \
638 filesrc location=example-in.avi ! avidemux name=demux \
639 avimux name=mux ! filesink location=example-out.avi \
640 demux.video_0 ! queue ! dam ! queue ! mux.video_0 \
641 demux.audio_0 ! queue ! dam ! queue ! mad ! audioconvert ! lamemp3enc ! mux.audio_0
642 Transcodes a particular section from an AVI file into another AVI file
645 without re-encoding video (but does re-encode audio, which is recom‐
646 mended). The output will range from (approximately) 60 seconds into the
647 input up to 180 seconds; actually there will be a (key)seek to the
648 nearest keyframe just before the 60 seconds point to ensure the in‐
649 tegrity of later decoding of the output. In addition, entrans will re‐
650 port changes on any object's properties, except for any (pad's) caps.
651 The pipeline above uses raw mode, and as such must abide by some rules
653 and recommendations in pipeline building (see MUXING PIPELINES), which
654 leads in particular to the above abundance in queues. With some extra
655 configuration, pass-through could also be performed in dynamic mode as
656 follows (assuming that video/mpeg properly describes the encoded video
657 content):
658 entrans.py -s seek-key -c 60-180 \
661 --set-prop 'decodebin:caps:video/mpeg;audio/x-raw' \
662 -i example-in.avi -o example-out.avi -- \
663 --video capsfilter caps=video/mpeg \
664 --audio audioconvert ! lamemp3enc
665 Live recording
668 entrans.py -s cut-time -c 0-60 -v -x '.*caps' --dam -- --raw \
670 v4l2src queue-size=16 ! video/x-raw,framerate=25/1,width=384,height=576 ! \
671 entransstamp sync-margin=2 silent=false progress=0 ! queue ! \
672 entransdam ! avenc_mpeg4 name=venc \
673 alsasrc buffer-time=1000000 ! audio/x-raw,rate=48000,channels=1 ! queue ! \
674 entransdam ! audioconvert ! queue ! lamemp3enc name=aenc \
675 avimux name=mux ! filesink location=rec.avi aenc. ! mux. venc. ! mux.
676 Records 1 minute of video and audio from a video4linux device and fea‐
679 tures additional synchronization and reporting on object property
680 changes (if any), which includes reports on frame drops or duplica‐
681 tions, although (pad's) caps changes are excluded for convenience.
682 2-pass transcoding
684 entrans.py -i example-in.avi -o /dev/null --muxer avimux --vb 1200 --pass 1 \
686 --save entransastat:astat.log -- --video avenc_mpeg4 \
687 --audio audioconvert ! entransastat ! fakesink
688 SCALE="$(cat astat.log | sed 's/astat, scale=(double)//' | sed 's/;//')"
689 entrans.py -i example-in.avi -o example-out.avi --vb 1200 --pass 2 \
690 --tag 'comment:2-pass demonstration' -- \
691 --video avenc_mpeg4 --audio audioconvert ! volume volume=$SCALE ! lamemp3enc
692 Performs 2-pass transcoding from one AVI into another. The first pass
695 also determines and saves the maximum volume scaling that can safely be
696 applied without having to resort to clipping. It does not bother per‐
697 forming audio encoding or producing an output file. Although the par‐
698 ticular (encoder compatible) muxer is hardly relevant here, one is nev‐
699 ertheless indicated explicitly as a reasonablechoice cannot be deter‐
700 mined from /dev/null. After some scripting to retrieve the saved value
701 from a file, the second pass performs volume scaling and encoding. It
702 also sets a comment (tag) in the resulting file to note its lofty goal.
703 Configuration file
705 [options]
707 ignore-prop=.*src.*,.*sink.*,dam.*,queue.*,identity.*,.*decodebin.*
708 display-prop=.*\.tag,.*\.bitrate$,.*bframes,.*quantizer,.*\.pass,.*\.queue-size
709 tag_0=encoder:entrans
710 tag_1=application-name:entrans
711 [dam]
713 drop-tags=bitrate,encoder,codec,container
714 [avenc_mpeg4]
716 me-method=epzs
717 max-bframes=0
718 gop-size=250
719 [dvdsubdec]
721 pf_rank = 128
722 A basic, though adequate configuration file that filters out some (usu‐
726 ally less interesting) information on some technical elements, while
727 making sure on the other hand that some other settings get displayed in
728 any case. In addition, an element's properties can be given defaults
729 (other than the hardcoded ones), and the rank of dvdsubdec is increased
730 so that subtitles streams will also be provided. Also, when transcod‐
731 ing, some original tags are filtered out and some tags are set on the
732 resulting file (where its format/type may or may not support recording
733 these particular tags).
734 Profile configuration
736 Some examples of (encoding) profiles that can be passed to --profile
738 (each profile is in a separate file). Note that profiles also impose
739 constraints on e.g. width and height which are not automagically en‐
740 forced; one must still take care of this by means of e.g. proper scal‐
741 ing. Similarly, the elements that are to perform the required encoding
742 must be properly (manually) specified, though their configuration is
743 then taken care of by the examples below.
744 # vcd:
747 # 352 x 240|288
748 # 44.1kHz, 16b, 2ch, mp2
749 [options]
751 vb = 1150
752 ab = 224
753 [avenc_mpeg1video]
755 bitrate = 1150
756 # <= 10
757 gop-size = 9
758 rc-min-rate = 1150
759 rc-max-rate = 1150
760 rc-buffer-size = 320
761 rc-buffer-aggressivity = 99
762 [mpeg2enc]
764 format = 1
765 # --------
768 # svcd:
769 # 480 x 480|576
770 # 44.1kHz, 16b, 2ch, mp2
771 [options]
773 vb = 2040
774 # >= 64, <= 384
775 ab = 224
776 [avenc_mpeg2video]
778 bitrate = 2040
779 # <= 19
780 gop-size = 15
781 # ntsc: gop-size = 18
782 rc-min-rate = 0
783 rc-max-rate = 2516
784 rc-buffer-size = 1792
785 rc-buffer-aggressivity = 99
786 flags = scanoffset
787 [mpeg2enc]
789 format = 4
790 # ---------
793 # xvcd:
794 # 480 x 480|576
795 # 32|44.1|48kHz, 16b, 2ch, mp2
796 [options]
798 vb = 5000
799 # >= 64, <= 384
800 ab = 224
801 [avenc_mpeg2video]
803 # 1000 <= bitrate <= 9000
804 bitrate = 2040
805 # <= 19
806 gop-size = 15
807 # ntsc: gop-size = 18
808 rc-min-rate = 0
809 # optional:
810 rc-max-rate = 5000
811 #
812 rc-buffer-size = 1792
813 rc-buffer-aggressivity = 99
814 flags = scanoffset
815 # ------
818 # dvd:
819 # 353|704|720 x 240|288|480|576
820 # 48kHz, 16b, 2ch, mp2|ac3
821 [options]
823 vb = 5000
824 # >= 64, <= 384
825 ab = 224
826 [avenc_mpeg2video]
828 # 1000 <= bitrate <= 9800
829 bitrate = 5000
830 # <= 19
831 gop-size = 15
832 # ntsc: gop-size = 18
833 rc-min-rate = 0
834 rc-max-rate = 9000
835 rc-buffer-size = 1792
836 rc-buffer-aggressivity = 99
837 [mpeg2enc]
839 format = 8
840 Encoding Profile Transcoding
843 entrans.py -i example-in.avi -o example-out.mp4 --encoding-profile video-encoding:mpeg4-video
845 Performs transcoding of input file to MP4 using encodebin with the
848 specified encoding profile, for instance defined as follows (and saved
849 in a file in $HOME/.gstreamer/encoding-profiles/device/video-encod‐
850 ing.gep). Note that in this case the input file may contain either
851 video or audio or both.
852 [GStreamer Encoding Target]
855 name = video-encoding
856 category = device
857 description = Video encoding profiles
858 [profile-mpeg4-video]
860 name = mpeg4-video
861 type = container
862 description[c] = Standard MPEG-4 video profile
863 format = video/quicktime, variant=(string)iso
864 [streamprofile-mpeg4-video-0]
866 parent = mpeg4-video
867 type = video
868 format = video/mpeg, mpegversion=(int)4
869 presence = 0
870 pass = 0
871 variableframerate = false
872 [streamprofile-mpeg4-video-1]
874 parent = mpeg4-video
875 type = audio
876 format = audio/mpeg, mpegversion=(int)4
877 presence = 0
878
882 Evidently, there must be a basic GStreamer framework installation, the
883 extent of which and available plugins determine the processing scope
884 that can be achieved. Beyond this, it is highly recommended for the
885 entransdam element to be available, which is part of the plugins sup‐
886 plied along with entrans. More (technical) details and motivation can
887 be found in the documentation for entransdam, but suffice it to say
888 that without entransdam the following notes apply:
889 · For --seek, only the methods seek and seek-key are available. Howev‐
891 er, for reasons explained in entransdam documentation and in MUXING
892 PIPELINES, even these methods can not be considered reliable, either
893 functional or technical. As such, only full (uninterrupted) pipeline
894 transcoding is really available.
895 As a technical note, this unreliability could be alleviated by having
897 the functionality to drop out-of-segment-bound buffers not only in
898 sinks or in some elements, but as a specific ability in e.g. identi‐
899 ty.
900 · The graceful (signal initiated) termination usually also relies on
902 entransdam, and is quite sturdy in this case. However, and fortu‐
903 nately, there is also an alternative fall-back implementation that
904 will take care of this in the vast majority of circumstances.
905 Note that in case of dynamic pipelines, the availability of the en‐
907 transdam element in the system is auto-detected, and the proper pipe‐
908 line-construction action is taken accordingly. In raw mode, however, it
909 must be explictly confirmed (by --dam) that entransdams are properly
910 used, otherwise none will be assumed present and only restricted opera‐
911 tion is then available, as indicated above. Proper usage of entransdam
912 is subject to comments in MUXING PIPELINES, but basically comes down to
913 putting a entransdam as upstream as possible in each independent
914 stream, e.g. preceding some queue. Alternatively, such a queue could be
915 used as surrogate dam by naming it dam<digits>.
916
918 On the one hand, one might compare in the sense that both GNonLin
919 (nowadays part of GStreamer Editing Services) and entrans aim to create
920 media files while allowing for non-linear editing/cutting. On the oth‐
921 er hand, entrans is quite complementary and can actually be combined
922 with GNonLin, for example
923 entrans.py -- --raw nlecomposition. '(' name=comp caps=video/x-raw \
926 nleurisource uri=file:///tmp/test.avi start=0 duration=20000000000 inpoint=0 ')' \
927 comp.src ! avenc_mpeg4 ! queue ! avimux ! filesink location=test-gnonlin.avi
928 That being the case, why this alternative and yet another program,
931 rather than being content with e.g. GNonLin (and gst-launch(1)) ?
932 On the one hand, historically, there were some technical reasons that
934 allowed entrans' approach to operate with great precision in a variety
935 of circumstances (unlike GNonLin). However, a recent GNonLin no longer
936 exhibits such drawbacks, and is aided by a GES convenience layer nowa‐
937 days.
938 On the other hand, and applicable to date, is a matter of style. The
940 above example pipeline looks and feels rather contrived (and that's on‐
941 ly the video part!), and is not much of a pipeline in that e.g. nlecom‐
942 position is really (deliberately) not so much a pipeline than it is
943 more of a bag (serving its intended purpose well). On the other hand,
944 Un*x pipelines have a long standing beauty (and a.o. adaptability and
945 flexibility), and a (traditional) GStreamer pipeline continues in that
946 tradition. In that sense, entrans' (and gst-launch(1)) approach is an
947 ode to pipeline and its inherent simplicity and clarity of intent. In
948 particular, typical entrans pipelines are only slightly different than
949 playback pipelines, and the cutting/seeking mechanism is pretty identi‐
950 cal. In that way, an entrans media file creation is very close to a
951 (non-linear) playback session (and closer than a GNonLin equivalent
952 would be). Of course, there is now also GES (along with e.g. ges-
953 launch tool), though all that somewhat surpasses the plain-and-simple
954 as intended here (and the remainder is left to a matter of taste and
955 suitable choice depending on circumstances).
956 So, the idea and intention succinctly put is; if you can play it, you
958 can entrans it (with a pretty plain-and-simple similar pipeline, and
959 precision in various circumstances).
960
962 As mentioned earlier, one might run into some pitfalls when construct‐
963 ing a (raw) pipeline, most of which are taken care of by entrans when
964 runnning in dynamic mode.
965 Building. To begin with, the pipeline must be properly built and
967 linked, in particular to the muxer element, which typically only has
968 request pads. For linking and subsequent negotiation to succeed, a
969 stream must manage to get the request pad it really needs and is com‐
970 patible with. That means that the element connecting to the muxer (or
971 trying so) should provide enough (static) information to identify the
972 corresponding muxer pad (template). As this information is typically
973 derived from the connecting element's pad templates, it is not quite
974 comfortable to try connecting a generic element (e.g. queue). If this
975 were needed, or there is some or the other problem connecting to the
976 muxer, then it may be helpful to use a capsfilter (aka as a filtered
977 connection) or to specifically indicate the desired muxer pad (by a
978 name corresponding to the intended template, as in example Pass-through
979 transcoding), see also gst-launch(1) for specific syntax in either
980 case.
981 Muxer and Queue. In the particular case of a transcoding pipeline
983 (having some media-file as source), some other care is needed to make
984 sure it does not stall, i.e. simply block without any notification (or
985 an application having a chance to do something about it). Specifically,
986 a muxer will often block a thread on its incoming pad until it has
987 enough data across all of its pads for it to make a decision as to what
988 to mux in next. Evidently, if a single (demuxer) thread were having to
989 provide data to several pads, then stalling would almost surely occur.
990 As such, each of these pads/streams should have its own thread. In case
991 of live sources, this is usually already the case, e.g. separate video
992 and audio capturing threads. However, when transcoding, and therefore
993 demuxing an input file, a queue should be inserted into each outgoing
994 stream to act as a thread boundary and supply a required separate
995 thread. In addition, this multi-threading will evidently also spread
996 processing across several CPUs (if available) and improve performance.
997 In this respect, it can also be beneficial to use more than 1
998 queue/thread per stream; one that performs filter processing (if any)
999 and one that performs encoding.
1000 Note that similar stalling can also occur in some variations of these
1002 circumstances. For instance, tee could have the role of demuxer in the
1003 above story, and/or a collection of several sinks in a pipeline could
1004 act as a muxer in the above story, since they will each also block a
1005 thread in PAUSED state (when the pipeline is trying to make it to that
1006 state). Another such situation can arise (temporarily) when pads are
1007 blocked as part of the seek-mechanism. In any case, the remedy is the
1008 same; use queues to prevent one thread from having to go around in too
1009 many places, and ending up stuck in one of them.
1010 Muxer and Time(stamps). Even if the above is taken into account, the
1012 time-sensitivity of a typical muxer may lead to (at first sight myste‐
1013 rious) stalling (in transcoding pipelines). That is, a muxer will usu‐
1014 ally examine the timestamps of the incoming data, select the oldest of
1015 these to be put into the outgoing stream and then wait for new data to
1016 arrive on this selected input stream (i.e. keep other streams/threads
1017 wait'ing). It follows easily that if there is a gap, imbalance, imper‐
1018 fection, irregularity (or however described) in timestamps between var‐
1019 ious incoming streams, a muxer will then consistently/continuously ex‐
1020 pect/want more data on 1 particular pad (for some amount proportional
1021 to the irregularity). For some time, this need could be satisfied by
1022 the queues that are present in this stream. At some point, however,
1023 these may not hold enough data and will need further input from the up‐
1024 stream demuxer element. However, for this demuxer to provide data for
1025 1 of its (outgoing) streams, it will also need to output data for the
1026 other streams, and this ends up into the other streams' queues. Unfor‐
1027 tunately, in this situation those queues cannot send out any data, as
1028 the muxer is holding their threads (blocked). Hence, they will (soon)
1029 fillup and then in turn block the demuxer thread trying to insert data,
1030 until there is again space available. Consequently, a deadlock circle
1031 ensues; muxer waiting for new data from queue, waiting for data from
1032 demuxer, waiting for space to put this into another stream queue, wait‐
1033 ing to unload data into the muxer. Note that this deadlock phenomenom
1034 will not occur with live (recording) pipelines, as the various threads
1035 are then not joined to a single demuxer (thread), though it is then
1036 likely to manifest itself it by loss of (live) input data.
1037 There a number of possible causes for the irregularities mentioned
1039 above.
1040 · Rarely, but not impossibly so, the problem may be inherent in the
1042 very input medium itself. Or there could be a problem with a (experi‐
1043 mental) demuxer that might produce incorrect timestamps.
1044 · If a (segment) seek is performed in a pipeline without using entrans‐
1046 dam, it is quite likely that some stream(s) may perform proper fil‐
1047 tering of out-of-segment-bound data, and that other(s) may not. This
1048 would then cause a typical imbalance between the various streams.
1049 · If timestamps are being resequenced in some incoming streams (e.g. by
1051 identity), but not in the other ones, there is an obvious imbalance.
1052 · Though more exotic, even if entransdam is being used, one must take
1054 care to perform this filtering before (the by now clearly essential)
1055 queue in the respective stream, particularly when several distinct
1056 sections are to be cut out of the input. After all, if queue were
1057 placed before entransdam, then the latter does not have a chance to
1058 drop unneeded buffers soon enough. As such, if a muxer tries to get
1059 the first piece of data on a particular pad following the gap between
1060 the sections, these queues would fillup and be effectively as if they
1061 were not present.
1062 Dynamic mode services. Dynamic mode takes care of (most of) the above
1064 as follows:
1065 · Pipeline building is performed almost completely automagically. Of
1067 course, this does not mean it can fit a square into a circle, so some
1068 consideration for compatibility and negotiation is still in order.
1069 · queues are inserted where needed and/or useful, either by decodebin
1071 or by entrans
1072 · Whenever available (recommended), entransdam is used and inserted in
1074 proper locations.
1075
1077 GStreamer homepage ⟨http://www.gstreamer.net/⟩ , gst-launch(1), entrans
1078 plugins ⟨http://gentrans.sourceforge.net/⟩
1079
1081 Mark Nauwelaerts <mnauw@users.sourceforge.net>
1082 1.4.0 entrans(1)