1entrans(1) entrans(1)
2
6 entrans - build and run GStreamer 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, such as for instance the new
164 experimental decodebin2.
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 As an additional convenience, all (partial) pipelines passed to entrans
189 will perform a simple form of glob-expansion for raw video and audio
190 mimetypes in capsfilters. That is, e.g. video/* will be expanded to raw
191 video mimetypes (also distributing properties if any, of course). This
192 allows e.g. for scaling without particular attention for what col‐
193 orspace may be in use at a particular stage.
194 INPUT/OUTPUT OPTIONS
196 The option in this section are only applicable in dynamic mode, so in‐
197 compatible with --raw.
198 -i uri, --input uri
200 Indicates the input source. If uri is a valid URI, then a proper
201 source element will be selected, otherwise it is simply taken as
202 a (relative) path of an inputfile. If uri is -, then stdin will
203 be used as input.
204 -o uri, --output uri
206 Indicates the output destination. If output is a valid URI, then
207 a corresponding sink element is selected, otherwise it is taken
208 as a (relative) path of an outputfile (output to stdout is not
209 supported). The (file)suffix of uri is used to automagically
210 choose an appropriate muxer, which can be overridden with --mux‐
211 er
212 --muxer mux-element
214 Use mux-element in stead of the automatically selected one, or
215 if one fails to be auto-selected. mux-element must be of Muxer
216 class.
217 As mentioned in the previous section, all streams found in the input
219 are assigned a stream number and considered for processing, unless
220 somehow restricted by the following options.
221 --vn streamnumber[,...], --an streamnumber[,...], --on streamnum‐
223 ber[,...]
224 [multi-valued] Only the video, audio or other streams with (re‐
225 spectively) listed streamnumber will be considered, others dis‐
226 regarded. Furthermore, streams of each type will be muxed into
227 the target in the order in which their streamnumbers are given
228 in these options, and in overall first video, then audio and
229 others.
230 --sync-link
232 This option is mainly meant for testing and diagnostic purposes.
233 It basically disables the stream(re)-ordering mechanism as im‐
234 plied by and explained in the above option (though still retains
235 stream selection).
236 --at tag[,...]
238 [multi-valued] Audio streams can (though need not) be accompa‐
239 nied by a language tag (typically a 2- or 3-letter language
240 code). The regular expression tag is matched against each de‐
241 tected audio stream's language tag and only streams without lan‐
242 guage tag or streams with a matching language tag are processed,
243 others disregarded. This selection method cannot be combined
244 with the above streamnumber based selection.
245 Note
247 The current (or another?) method of implementing this selection
249 may very well not work with all muxer elements. As such, this
250 option can be given a try, but if not successful, the much more
251 robust --an should be used instead. The proper number(s) to use
252 for this may be derived from (ordered) tag information that is
253 provided by some elements and reported at start-up.
254 --stamp
256 This is enabled by default, and makes entrans insert an identity
257 element (with single-segment True) before the connected pipe‐
258 line-fragment to perform timestamp re-sequencing. This is typi‐
259 cally useful when muxing into a format that records timestamps
260 (and does not hurt when the format does not).
261 BASIC OPTIONS
263 Whereas no specific dependencies exist for all other options, the RE‐
264 QUIREMENTS section applies particularly to the following options (in
265 more or less degree).
266 -c [[(]format[)]:]t1-t2[,...], --cut [[(]format[)]:]t1-t2[,...]
268 [multi-valued] Only process the indicated sections of the pipe‐
269 line (by default the complete input is processed). The option -s
270 determines the method used for selecting the desired data.
271 If no format is provided, the tN parameters can be given in
273 timecode format HH:MM:SS.FRACTION or as a (video)framenumber,
274 which is a number following f or F. Any buffer that overlaps
275 with the indicated section is taken into account. The last indi‐
276 cated section may be open-ended, i.e. the end point may be omit‐
277 ted.
278 However, if format is the nickname of a pre-defined or custom
281 format (defined by some element in the pipeline), then it is
282 used as unit for the tN numbers. In this case, option -s below
283 must select a seek-based method, and the seek will be executed
284 in format if it is provided without matching (...), otherwise
285 the given units will be (query) converted to time format first,
286 and these results will be used to seek in time.
287 -s method, --section method
289 Possible choices for method are:
290 seek Sections are selected by means of regular GStreamer
292 seeks. A flushing seek is performed for the first sec‐
293 tion, segment seek for the others, and a normal seek for
294 the last section. This is also the default method and is
295 OK for most circumstances. In some cases, however, the
296 other methods may be in order, e.g. when (the driving el‐
297 ement in) the pipeline does not support some type of seek
298 that would be used.
299 seek-key
301 This is similar to the case above, but each seek is also
302 a keyframe seek, that is, the actual selection may not be
303 exactly the one that was requested but may start at the
304 nearest keyframe preceding the desired start. This would
305 typically be required when performing re-muxing without
306 fully decoding and re-encoding the material.
307 cut-time
309 In this case, the pipeline is run from the start (without
310 any seeks) and all but the desired sections are disre‐
311 garded. The decision whether or not to drop a piece of
312 data is based on its timestamp. This is the recommended
313 (only possible) method to use when performing A/V sync
314 correction using data-timestamp shifting, e.g. by means
315 of the shift element. It can also be used to end a live
316 source(s) driven pipeline after a specified duration.
317 cut This method applies in case any/all of the above fail,
319 e.g. some element does not support seek or unreliable
320 timestamps are produced in the pipeline. No seeks or
321 anything special is done, the pipeline is run from the
322 start and all but the indicated sections is dropped.
323 Timestamps on the datastream are disregarded, and the in‐
324 coming data is restamped based on framecount and framer‐
325 ate (video), or on sample count and samplerate (audio).
326 In particular, audio cutting is performed up to sample
327 precision.
328 Note that the last 2 methods require the desired sections to be in as‐
330 cending order, whereas the former methods make it possible to select
331 sections that are out-of-order with regards to the input material.
332 -a Perform (audio) sample precision selection, that is, it is pos‐
334 sible for only parts of buffers to be passed or dropped. This is
335 done by default in the cut method above, but not for the other
336 methods.
337 --dam Indicate, or rather, confirm that dam elements are being used in
339 raw pipelines. Otherwise, surrogate dam elements will be
340 searched for and used instead. These are identified as elements
341 whose name is of the form dam<digits>.
342 -f framerate, --framerate framerate
344 The framerate that is used for framenumber to time conversion is
345 normally auto-detected (soon enough) within the pipeline. If
346 this were not to succeed, then framerate, specified as NUM[/DE‐
347 NOM], is used as a fallback instead of the otherwise default
348 25/1.
349 -b, --block-overrun
351 This makes entrans prevent automatic adjustments to queues (in a
352 decodebin), thereby keeping them at fixed size.
353 Despite all the automagic, the pipeline may stall in exotic cas‐
355 es (e.g. some strange behaving element/muxer, ...). A good first
356 thing to try then is to configure queues at a larger-than-de‐
357 fault setting (see for example following section) and to use
358 this option to ensure they really remain configured as intended
359 without any other influence.
360 PIPELINE CONFIGURATION
362 Although element properties are typically set in the pipeline descrip‐
363 tions, the following options can be useful for dynamically created ele‐
364 ments (see for instance the dvd example in EXAMPLES) or when it is de‐
365 sired to configure a property syntactically separated from the pipeline
366 on the command line.
367 --set-prop element:prop:value[:time]
369 Sets property prop of element to value, where element can either
370 be an element-type, or the name or full path-string of a specif‐
371 ic element. If prop is a GST_CONTROLLABLE property (use gst-in‐
372 spect(1) to determine this), then a (pipeline media) time at
373 which prop should be set to this particular value (using the
374 controller framework) can be given as well.
375 In general, a value given for a property within the pipeline de‐
377 scription will override any value provided this way. In case of
378 queues, however, both decodebin and entrans will override some
379 properties' values in order to minimize the possibility of
380 blocking. Though it is not recommended, set-prop can be used to
381 forcibly overwrite such aforementioned defaults.
382 The rank of an element (as a plugin feature), which (a.o.) de‐
384 termines whether or not it is considered for auto-plugging (in
385 dynamic mode) is considered as a pseudo-property pf_rank and can
386 therefore be set in this way as well.
387 --vb vkbitrate, --ab akbitrate
389 Sets the bitrate property of any video or audio element to vkbi‐
390 trate [ * 1000] or akbitrate [ * 1000] respectively, depending
391 on whether the property expects to be provided with (k)bitrate.
392 --vq vquality, --aq aquality
394 Sets either the quality or quantizer property of any video or
395 audio element to vquality or aquality respectively.
396 --pass pass
398 Sets the pass property of any video element to pass, which must
399 be 1 or 2.
400 -t tag:value
402 [multi-valued] entrans locates a TagSetter in the pipeline and
403 sets each given tag to value.
404 A list of possible tags can be found in GStreamer core documen‐
406 tation ⟨http://www.gstreamer.net/data/doc/gstreamer/head/
407 gstreamer/html/gstreamer-GstTagList.html⟩ .
408 REPORTING OPTIONS
410 By default, entrans reports the following items at startup:
411 · an overview of elements found in the pipeline, along with the current
413 values of properties that differ from their usual (default) setting;
414 tags announced by an element are considered as a pseudo-property tag
415 of the element
416 · a set of distinct caps that have been found flowing through the pipe‐
418 line,
419 · the (video) queues found in the pipeline (with their neighbours), and
421 their maximum capacity settings (size, buffers, time)
422 After that, it provides the following in regular intervals, if already
424 available or applicable:
425 · (time) position in input stream,
427 · movie time: position in output stream, and the total expected output
429 movie time
430 · processing speed: ratio of elapsed (input) stream time to elapsed CPU
432 time
433 · ETA: expected time to completion of processing; this calculation al‐
435 ways uses elapsed system clock time, regardless of options below,
436 · amount of buffers presently contained in the queues reported at
438 startup,
439 · if a specific output file can be identified, (combined) bitrate so
441 far.
442 The following options can influence some of this behaviour:
444 -d delay, --delay delay
446 Sets the interval between progress updates to delay seconds. The
447 default delay is 2 seconds.
448 --timeout timeout
450 As an entrans run spins up, it transitions through a number of
451 stages, which should normally follow each other in pretty rapid
452 succession. timeout, by default 4, is the maximum interval (in
453 seconds) that will be allowed between such stages. If the inter‐
454 val is exceeded, entrans may simply abort altogether or try to
455 recover the situation (depending on the stage), the success of
456 which depends on the cause (e.g. a misbehaving element, or a
457 badly constructed pipeline, ...). Evidently, a high timeout
458 value essentially renders this check mute. Setting it to 0 com‐
459 pletely disables this check as well as some other mechanisms em‐
460 ployed to support it, and is not normally advisable.
461 --progress-fps
463 Makes regular reports also provide processing speed in fps,
464 which is calculated using either auto-detected framerate or pro‐
465 vided by -f.
466 --progress-real
468 Calculate processing speed based on elapsed system clock time
469 (instead of CPU-time).
470 In the following, proppattern is a regular expression that will be
472 matched a combination of an element and (optionally) one its properties
473 prop. More precisely, this combination matches if the regular expres‐
474 sion matches any of the following:
475 · element's factory name.prop
477 · element's name.prop
479 · element's path name.prop
481 In each case, the last part is omitted if there is no prop in the con‐
483 text in question.
484 Similarly, msgpattern is matched against expressions as above, but with
486 prop replaced by message type name.message structure name Again, in
487 each case, the last part is omitted if there is no structure for the
488 message in question.
489 -m Output messages posted on the pipeline's bus
491 -v Provide output on property changes of the pipeline's elements.
493 This output can be filtered using -x
494 --short-caps
496 Do not perform complete caps to string conversion, instead re‐
497 place e.g. buffers with their (string) type representation.
498 This can make for more comfortable display of e.g. Vorbis and
499 Theora related caps.
500 --ignore-msg msgpattern[,...] , --display-msg msgpattern[,...]
502 [multi-valued] If message reporting is enabled by -m, only re‐
503 port on those that match --display-msg or do not match --ig‐
504 nore-msg
505 -x proppattern[,...] , --exclude proppattern[,...] , --include proppat‐
507 tern[,...]
508 [multi-valued] If property change reporting is enabled by -v,
509 only report those on properties that match --include or do not
510 match --exclude
511 --display-prop proppattern[,...] , --ignore-prop proppattern[,...]
513 [multi-valued] An element's property (value) is reported at
514 start-up if and only if it matches an expression given in --dis‐
515 play-prop or its value differs from the usual and it does not
516 match --ignore-prop. Also, in any case, an element's presence
517 in the pipeline is at least mentioned by default, unless the el‐
518 ement (by itself) matches --ignore-prop
519 CONFIGURATION OPTIONS
521 Each entrans option —be it one affecting entrans' run-time behaviour or
522 affecting pipeline element (properties)— can also be provided on a more
523 permanent basis using a configuration file. Such a file consists of
524 sections, led by a [section] header and followed by name: value en‐
525 tries, name=value is also accepted. Note that leading whitespace is
526 removed from values. Lines beginning with # or ; are ignored and may
527 be used to provide comments.
528 In the special section [options], each entry name: value is equivalent
530 to providing --name value on the command-line, where name must be an
531 option's longname. The name of any other section is interpreted as an
532 element-type or an element, with each entry providing a value for a
533 property. Otherwise put, each prop: value in a section [element] is
534 equivalent to mentioning it in --set-prop as element:prop:value
535 By default, the configuration file is called .gst-entrans and is
537 searched for in the current directory and in the user's home directory
538 (in that order). Any setting provided on the command line for a sin‐
539 gle-valued option (e.g. a boolean option) overrides a similar value
540 given in a configuration file, whereas values provided for multi-valued
541 ones append to those already provided.
542 --config file
544 Use file instead of any default configuration file.
545 --profile file
547 Load file after other configuration files, either default ones
548 or given by --config. This option derives its name from its use
549 in loading certain export or encoder profiles (e.g. MPEG1,
550 MPEG2, etc), which are mainly a collection of presets for cer‐
551 tain properties that can be kept in corresponding profile con‐
552 figuration files.
553 MISCELLANEOUS OPTIONS
555 --save message:file[:append][,...]
556 [multi-valued] Makes entrans save a custom element message to
557 file, that is, the string representation of the message's struc‐
558 ture is saved (followed by a linefeed). If append is true (e.g.
559 1, t, T), then all messages are appended to file, otherwise the
560 default is to truncate file whenever message is received, there‐
561 by saving only the most recently received message. For good
562 measure, it might be noted here there was a change in version
563 0.10.15 in a structure's string representation with respect to
564 usage of a terminating ;.
565 file will be subject to having ${n}$ replaced by the name of the
567 element sending message.
568
570 More examples of pipelines can also be found in gst-launch(1); the ones
571 below are primarily meant to illustrate some of entrans' features.
572 In each case, everything could also be written on one line, without the
574 backslash character. In some cases, some particular quoting is needed
575 to prevent (mis)interpretation by the shell.
576 Basic transcoding
578 entrans.py -i dvd://2 -o dvd.ogm --short-caps -- \
580 --video ! theoraenc --audio audioconvert ! vorbisenc
581 .fi
582 Transcodes complete title 2 from a DVD into a mixed Ogg containing all video
584 and audio tracks (but no subtitles) using default settings, while preventing
585 some extensive caps display.
586 Selected stream transcoding
588 entrans.py --set-prop dvdreadsrc:device:/mnt -i dvd://2 -o dvd.mkv \
590 --set-prop dvdsubdec:pf_rank:128 --on 6,12 --an 1,2 --vq 4 --ab 256 -- \
591 --video ffenc_mpeg4 --audio audioconvert ! lame \
592 --other ffmpegcolorspace ! ffenc_mpeg4 ! matroskamux ! filesink location='sub-${on}.mkv'
593 .fi
594 Transcodes video and selected audio tracks from a DVD image mounted at /mnt
596 into a Matroska file, using the indicated fixed quantization and bitrate for
597 video and audio respectively. Some selected subtitle tracks are also encoded
598 as separate video streams into other Matroska files. Note that the rank of
599 the dvdsubdec must be increased for a subtitle stream to be
600 considered for decoding and subsequently made available.
601 Extensive progress update transcoding
603 entrans.py -i example-in.avi -o example-out.mkv -- \
605 --video tee name=tee ! queue ! theoraenc \
606 tee. ! queue ! timeoverlay ! xvimagesink sync=false qos=false \
607 --audio audioconvert ! lame
608 .fi
609 Transcodes into Matroska using Theora and MP3 codecs, while providing for
611 (excessive) live preview progress info.
612 Partial stream transcoding
614 entrans.py -i dvd://2 -o dvd.mkv -c chapter:5- --short-caps -- \
616 --video ! identity single-segment=true ! ffenc_mpeg4 \
617 --audio audioconvert ! identity single-segment=true ! vorbisenc
618 .fi
619 Transcodes all video and audio tracks from a DVD title 2 (chapter 5 to the end)
621 into Matroska using MPEG4 and Vorbis codecs (while catering for properly
622 timestamped input for the container which records these faithfully for posterity).
623 Pass-through transcoding
625 entrans.py -s seek-key -c 60-180 --dam -- --raw \
627 filesrc location=example-in.avi ! avidemux name=demux \
628 avimux name=mux ! filesink location=example-out.avi \
629 demux.video_00 ! queue ! dam ! queue ! mux.video_0 \
630 demux.audio_00 ! queue ! dam ! queue ! mad ! audioconvert ! lame ! mux.audio_0
631 .fi
632 Transcodes a particular section from an AVI file into another AVI file without
634 re-encoding video (but does re-encode audio, which is
635 recommended). The output will range from (approximately) 60 seconds into the
636 input up to 180 seconds; actually there will be a (key)seek to the nearest
637 keyframe just before the 60 seconds point to ensure the integrity of later
638 decoding of the output.
639 In addition, entrans will report changes on any object's properties, except
640 for any (pad's) caps.
641 The pipeline above uses raw mode, and as such must abide
643 by some rules and recommendations in pipeline building (see MUXING PIPELINES),
644 which leads in particular to the above abundance in queues.
645 With some extra configuration, pass-through could also be performed in
646 dynamic mode as follows (assuming that video/mpeg properly
647 describes the encoded video content):
648 entrans.py -s seek-key -c 60-180 --decoder decodebin2 \
650 --set-prop 'decodebin2:caps:video/mpeg;audio/x-raw-int;audio/x-raw-float' \
651 -i example-in.avi -o example-out.avi -- \
652 --video capsfilter caps=video/mpeg \
653 --audio audioconvert ! lame
654 .fi
655 Live recording
657 entrans.py -s cut-time -c 0-60 -v -x '.*caps' --dam -- --raw \
659 v4l2src queue-size=16 ! video/x-raw-yuv,framerate=25/1,width=384,height=576 ! \
660 stamp sync-margin=2 silent=false progress=0 ! queue ! \
661 dam ! ffenc_mpeg4 name=venc \
662 alsasrc buffer-time=1000000 ! audio/x-raw-int,rate=48000,channels=1 ! queue ! \
663 dam ! audioconvert ! queue ! lame name=aenc \
664 avimux name=mux ! filesink location=rec.avi aenc. ! mux. venc. ! mux.
665 .fi
666 Records 1 minute of video and audio from a video4linux device and features
668 additional synchronization and reporting on object property changes (if any),
669 which includes reports on frame drops or duplications, although
670 (pad's) caps changes are excluded for convenience.
671 2-pass transcoding
673 entrans.py -i example-in.avi -o /dev/null --muxer avimux --vb 1200 --pass 1 \
675 --save astat:astat.log -- --video ffenc_mpeg4 \
676 --audio audioconvert ! astat ! fakesink
677 SCALE="$(cat astat.log | sed 's/astat, scale=(double)//' | sed 's/;//')"
678 entrans.py -i example-in.avi -o example-out.avi --vb 1200 --pass 2 \
679 --tag 'comment:2-pass demonstration' -- \
680 --video ffenc_mpeg4 --audio audioconvert ! volume volume=$SCALE ! lame
681 .fi
682 Performs 2-pass transcoding from one AVI into another. The first pass also
684 determines and saves the maximum volume scaling that can safely be applied
685 without having to resort to clipping. It does not bother performing audio encoding
686 or producing an output file. Although the particular (encoder compatible) muxer
687 is hardly relevant here, one is nevertheless indicated explicitly
688 as a reasonablechoice cannot be determined
689 from /dev/null. After some scripting to retrieve the
690 saved value from a file, the second pass performs volume scaling and encoding.
691 It also sets a comment (tag) in the resulting file to note its lofty goal.
692 Configuration file
694 [options]
696 ignore-prop=.*src.*,.*sink.*,dam.*,queue.*,identity.*,.*decodebin.*
697 display-prop=.*\.tag,.*\.bitrate$,.*bframes,.*quantizer,.*\.pass,.*\.queue-size
698 [ffenc_mpeg4]
700 me-method=epzs
701 max-bframes=0
702 gop-size=250
703 [dvdsubdec]
705 pf_rank = 128
706 .fi
707 A basic, though adequate configuration file that filters out some
709 (usually less interesting) information on some technical
710 technical elements, while making sure on the other hand that some other
711 settings get displayed in any case. In addition, an element's properties
712 can be given defaults (other than the hardcoded ones), and the rank
713 of dvdsubdec is increased so that subtitles streams will
714 also be provided.
715 Profile configuration
717 Some examples of (encoding) profiles that can be passed to
719 --profile (each profile is in a separate file).
720 Note that profiles also impose
721 constraints on e.g. width and height which are not automagically
722 enforced; one must still take care of this by means of e.g. proper scaling.
723 Similarly, the elements that are to perform the required encoding
724 must be properly (manually) specified, though their configuration
725 is then taken care of by the examples below.
726 # vcd:
728 # 352 x 240|288
729 # 44.1kHz, 16b, 2ch, mp2
730 [options]
732 vb = 1150
733 ab = 224
734 [ffenc_mpeg1video]
736 bitrate = 1150
737 # <= 10
738 gop-size = 9
739 rc-min-rate = 1150
740 rc-max-rate = 1150
741 rc-buffer-size = 320
742 rc-buffer-aggressivity = 99
743 [mpeg2enc]
745 format = 1
746 .fi
747 # --------
749 # svcd:
750 # 480 x 480|576
751 # 44.1kHz, 16b, 2ch, mp2
752 [options]
754 vb = 2040
755 # >= 64, <= 384
756 ab = 224
757 [ffenc_mpeg2video]
759 bitrate = 2040
760 # <= 19
761 gop-size = 15
762 # ntsc: gop-size = 18
763 rc-min-rate = 0
764 rc-max-rate = 2516
765 rc-buffer-size = 1792
766 rc-buffer-aggressivity = 99
767 flags = scanoffset
768 [mpeg2enc]
770 format = 4
771 .fi
772 # ---------
774 # xvcd:
775 # 480 x 480|576
776 # 32|44.1|48kHz, 16b, 2ch, mp2
777 [options]
779 vb = 5000
780 # >= 64, <= 384
781 ab = 224
782 [ffenc_mpeg2video]
784 # 1000 <= bitrate <= 9000
785 bitrate = 2040
786 # <= 19
787 gop-size = 15
788 # ntsc: gop-size = 18
789 rc-min-rate = 0
790 # optional:
791 rc-max-rate = 5000
792 #
793 rc-buffer-size = 1792
794 rc-buffer-aggressivity = 99
795 flags = scanoffset
796 .fi
797 # ------
799 # dvd:
800 # 353|704|720 x 240|288|480|576
801 # 48kHz, 16b, 2ch, mp2|ac3
802 [options]
804 vb = 5000
805 # >= 64, <= 384
806 ab = 224
807 [ffenc_mpeg2video]
809 # 1000 <= bitrate <= 9800
810 bitrate = 5000
811 # <= 19
812 gop-size = 15
813 # ntsc: gop-size = 18
814 rc-min-rate = 0
815 rc-max-rate = 9000
816 rc-buffer-size = 1792
817 rc-buffer-aggressivity = 99
818 [mpeg2enc]
820 format = 8
821 .fi
822
824 Evidently, there must be a basic GStreamer framework installation, the
825 extent of which and available plugins determine the processing scope
826 that can be achieved. Beyond this, it is highly recommended for the
827 dam element to be available, which is part of the plugins supplied
828 along with entrans. More (technical) details and motivation can be
829 found in the documentation for dam, but suffice it to say that without
830 dam the following notes apply:
831 · For --seek, only the methods seek and seek-key are available. Howev‐
833 er, for reasons explained in dam documentation and in MUXING PIPE‐
834 LINES, even these methods can not be considered reliable, either
835 functional or technical. As such, only full (uninterrupted) pipeline
836 transcoding is really available.
837 As a technical note, this unreliability could be alleviated by having
839 the functionality to drop out-of-segment-bound buffers not only in
840 sinks or in some elements, but as a specific ability in e.g. identi‐
841 ty.
842 · The graceful (signal initiated) termination usually also relies on
844 dam, and is quite sturdy in this case. However, and fortunately,
845 there is also an alternative fall-back implementation that will take
846 care of this in the vast majority of circumstances.
847 Note that in case of dynamic pipelines, the availability of the dam el‐
849 ement in the system is auto-detected, and the proper pipeline-construc‐
850 tion action is taken accordingly. In raw mode, however, it must be ex‐
851 plictly confirmed (by --dam) that dams are properly used, otherwise
852 none will be assumed present and only restricted operation is then
853 available, as indicated above. Proper usage of dam is subject to com‐
854 ments in MUXING PIPELINES, but basically comes down to putting a dam as
855 upstream as possible in each independent stream, e.g. preceding some
856 queue. Alternatively, such a queue could be used as surrogate dam by
857 naming it dam<digits>.
858
860 On the one hand, one might compare in the sense that both GNonLin and
861 entrans aim to create media files while allowing for non-linear edit‐
862 ing/cutting. On the other hand, entrans is quite complementary and can
863 actually be combined with GNonLin, for example
864 entrans.py -- --raw gnlcomposition. '(' name=comp gnlfilesource \
866 location=test.avi start=0 duration=20000000000 media-start=0 \
867 media-duration=20000000000 caps=video/x-raw-yuv ')' \
868 comp.src ! ffenc_mpeg4 ! queue ! avimux ! filesink location=test-gnonlin.avi
869 .fi
870 That being the case, why this alternative and yet another program, rather than
872 being content with e.g. GNonLin (and gst-launch(1)) ?
873 On the one hand, historically, there were some technical reasons that allowed
875 entrans' approach to operate with great precision in a variety of circumstances
876 (unlike GNonLin). However, a recent GNonLin no longer exhibits
877 such drawbacks.
878 On the other hand, and applicable to date, is a matter of style.
880 The above example pipeline looks and
881 feels rather contrived (and that's only the video part!), and is not much of a
882 pipeline in that e.g. gnlcomposition is
883 really (deliberately) not so much a pipeline than it is more of a bag (serving
884 its intended purpose well). On the other hand, Un*x pipelines have a long
885 standing beauty (and a.o. adaptability and flexibility), and a (traditional)
886 GStreamer pipeline continues in that tradition. In that sense, entrans'
887 (and gst-launch(1)) approach is an ode to pipeline and its
888 inherent simplicity and clarity of intent.
889 In particular, typical entrans pipelines are only slightly different than
890 playback pipelines, and the cutting/seeking mechanism is pretty identical.
891 In that way, an entrans media file creation is very close to a
892 (non-linear) playback session (and closer than a GNonLin equivalent would be).
893 So, the idea and intention succinctly put is; if you can play it, you can entrans
895 it (with a pretty plain-and-simple similar pipeline, and precision in various
896 circumstances).
897
899 As mentioned earlier, one might run into some pitfalls when construct‐
900 ing a (raw) pipeline, most of which are taken care of by entrans when
901 runnning in dynamic mode.
902 Building. To begin with, the pipeline must be properly built and
904 linked, in particular to the muxer element, which typically only has
905 request pads. For linking and subsequent negotiation to succeed, a
906 stream must manage to get the request pad it really needs and is com‐
907 patible with. That means that the element connecting to the muxer (or
908 trying so) should provide enough (static) information to identify the
909 corresponding muxer pad (template). As this information is typically
910 derived from the connecting element's pad templates, it is not quite
911 comfortable to try connecting a generic element (e.g. queue). If this
912 were needed, or there is some or the other problem connecting to the
913 muxer, then it may be helpful to use a capsfilter (aka as a filtered
914 connection) or to specifically indicate the desired muxer pad (by a
915 name corresponding to the intended template, as in example Pass-through
916 transcoding), see also gst-launch(1) for specific syntax in either
917 case.
918 Muxer and Queue. In the particular case of a transcoding pipeline
920 (having some media-file as source), some other care is needed to make
921 sure it does not stall, i.e. simply block without any notification (or
922 an application having a chance to do something about it). Specifically,
923 a muxer will often block a thread on its incoming pad until it has
924 enough data across all of its pads for it to make a decision as to what
925 to mux in next. Evidently, if a single (demuxer) thread were having to
926 provide data to several pads, then stalling would almost surely occur.
927 As such, each of these pads/streams should have its own thread. In case
928 of live sources, this is usually already the case, e.g. separate video
929 and audio capturing threads. However, when transcoding, and therefore
930 demuxing an input file, a queue should be inserted into each outgoing
931 stream to act as a thread boundary and supply a required separate
932 thread. In addition, this multi-threading will evidently also spread
933 processing across several CPUs (if available) and improve performance.
934 In this respect, it can also be beneficial to use more than 1
935 queue/thread per stream; one that performs filter processing (if any)
936 and one that performs encoding.
937 Note that similar stalling can also occur in some variations of these
939 circumstances. For instance, tee could have the role of demuxer in the
940 above story, and/or a collection of several sinks in a pipeline could
941 act as a muxer in the above story, since they will each also block a
942 thread in PAUSED state (when the pipeline is trying to make it to that
943 state). Another such situation can arise (temporarily) when pads are
944 blocked as part of the seek-mechanism. In any case, the remedy is the
945 same; use queues to prevent one thread from having to go around in too
946 many places, and ending up stuck in one of them.
947 Muxer and Time(stamps). Even if the above is taken into account, the
949 time-sensitivity of a typical muxer may lead to (at first sight myste‐
950 rious) stalling (in transcoding pipelines). That is, a muxer will usu‐
951 ally examine the timestamps of the incoming data, select the oldest of
952 these to be put into the outgoing stream and then wait for new data to
953 arrive on this selected input stream (i.e. keep other streams/threads
954 wait'ing). It follows easily that if there is a gap, imbalance, imper‐
955 fection, irregularity (or however described) in timestamps between var‐
956 ious incoming streams, a muxer will then consistently/continuously ex‐
957 pect/want more data on 1 particular pad (for some amount proportional
958 to the irregularity). For some time, this need could be satisfied by
959 the queues that are present in this stream. At some point, however,
960 these may not hold enough data and will need further input from the up‐
961 stream demuxer element. However, for this demuxer to provide data for
962 1 of its (outgoing) streams, it will also need to output data for the
963 other streams, and this ends up into the other streams' queues. Unfor‐
964 tunately, in this situation those queues cannot send out any data, as
965 the muxer is holding their threads (blocked). Hence, they will (soon)
966 fillup and then in turn block the demuxer thread trying to insert data,
967 until there is again space available. Consequently, a deadlock circle
968 ensues; muxer waiting for new data from queue, waiting for data from
969 demuxer, waiting for space to put this into another stream queue, wait‐
970 ing to unload data into the muxer. Note that this deadlock phenomenom
971 will not occur with live (recording) pipelines, as the various threads
972 are then not joined to a single demuxer (thread), though it is then
973 likely to manifest itself it by loss of (live) input data.
974 There a number of possible causes for the irregularities mentioned
976 above.
977 · Rarely, but not impossibly so, the problem may be inherent in the
979 very input medium itself. Or there could be a problem with a (experi‐
980 mental) demuxer that might produce incorrect timestamps.
981 · If a (segment) seek is performed in a pipeline without using dam, it
983 is quite likely that some stream(s) may perform proper filtering of
984 out-of-segment-bound data, and that other(s) may not. This would then
985 cause a typical imbalance between the various streams.
986 · If timestamps are being resequenced in some incoming streams (e.g. by
988 identity), but not in the other ones, there is an obvious imbalance.
989 · Though more exotic, even if dam is being used, one must take care to
991 perform this filtering before (the by now clearly essential) queue in
992 the respective stream, particularly when several distinct sections
993 are to be cut out of the input. After all, if queue were placed be‐
994 fore dam, then the latter does not have a chance to drop unneeded
995 buffers soon enough. As such, if a muxer tries to get the first
996 piece of data on a particular pad following the gap between the sec‐
997 tions, these queues would fillup and be effectively as if they were
998 not present.
999 Dynamic mode services. Dynamic mode takes care of (most of) the above
1001 as follows:
1002 · Pipeline building is performed almost completely automagically. Of
1004 course, this does not mean it can fit a square into a circle, so some
1005 consideration for compatibility and negotiation is still in order.
1006 · queues are inserted where needed and/or useful, either by decodebin
1008 or by entrans
1009 · Whenever available (recommended), dam is used and inserted in proper
1011 locations.
1012
1014 GStreamer homepage ⟨http://www.gstreamer.net/⟩ , gst-launch(1), entrans
1015 plugins ⟨http://gentrans.sourceforge.net/⟩
1016
1018 Mark Nauwelaerts <mnauw@users.sourceforge.net>
1019 0.10.2.1 entrans(1)