~ubuntu-branches/ubuntu/natty/gst-entrans/natty

<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=us-ascii" /><title>entrans</title><link rel="stylesheet" href="manual.css" type="text/css" /><link rev="made" href="mailto:mnauw@users.sourceforge.net" /><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><link rel="start" href="index.html" title="GStreamer Transcoding" /><link rel="up" href="package.html" title="Chapter 2. Package Documentation" /><link rel="prev" href="package.html" title="Chapter 2. Package Documentation" /></head><body><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">entrans</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="package.html"><< Previous</a> </td><th width="60%" align="center">Chapter 2. Package Documentation</th><td width="20%" align="right"> </td></tr></table><hr /></div><div class="refentry" lang="en" xml:lang="en"><a id="entrans"></a><div class="titlepage"></div><div class="refnamediv"><a id="name"></a><h2>Name</h2>entrans — build and run GStreamer pipeline</div><div class="refsynopsisdiv"><a id="synopsis"></a><h2>Synopsis</h2><div class="cmdsynopsis"><code class="command">entrans</code> [OPTION...] {--} {PIPELINE-OPTION...}</div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2>

entrans builds and runs a <a class="ulink" href="http://www.gstreamer.net/" target="_top">GStreamer</a> pipeline, primarily intended for

transcoding, encoding or recording purposes.

On the one hand, it is much like

gst-launch(1) in that it has no ambitions to go beyond command-line

(or script) driven processing.

On the other hand, it has quite a few enhancements that provide application-level

functionality sufficiently comfortable and suitable for

plain-and-simple (and robust) transcoding, encoding or recording

using the <a class="ulink" href="http://www.gstreamer.net/" target="_top">GStreamer</a> framework and plugins:

Pipeline to run can be specified manually, or can be built dynamically

based on inputstream and pipeline fragments

(see <a class="xref" href="entrans.html#operation" title="Operation">“Operation”</a>), which takes

care of most of the boilerplate (and of some pitfalls to watch out for

with transcoding pipelines, see also <a class="xref" href="entrans.html#muxing-pipelines" title="Muxing Pipelines">“Muxing Pipelines”</a>).

</li><li>

Provides some typically relevant (configurable) interesting info

regarding the pipeline (elements, properties, queues, …) and

caps flowing in pipeline.

</li><li>

Regular progress updates are provided.

</li><li>

Limited support for tag setting (whenever a

<code class="interfacename">TagSetter</code> is present).

</li><li>

Property configuration support; settings can be applied from what is

stored in a config file and there is also some custom support for

setting “popular options” (e.g. bitrate).

</li><li>

Last but not least (convenient), processing can be restricted to

specific portions of the input(stream) (mind <a class="xref" href="entrans.html#requirements" title="Requirements">“Requirements”</a>).

</li><li>

Graceful shutdown of processing at any time,

and still well-formed output as result

(mind <a class="xref" href="entrans.html#requirements" title="Requirements">“Requirements”</a>).

</li></ul></div>

Another (technical) difference is that it is written

in <a class="ulink" href="http://www.python.org/" target="_top">python</a>,

using the python bindings for the <a class="ulink" href="http://www.gstreamer.net/" target="_top">GStreamer</a> framework (gst-python),

which makes many of the enhancements much more comfortable to implement

and easy to adjust (to taste).

</div><div class="refsect1" lang="en" xml:lang="en"><a id="operation"></a><h2>Operation</h2>

As already alluded to above, entrans fundamentally operates

in one of the following ways, also loosely called modes:

<div class="itemizedlist"><ul><li>Raw mode.

The pipeline to construct, run and manage is explictly given

manually (see <code class="option">--raw</code>).

On the one hand, this mode allows full freedom in

pipeline construction and can be great for diagnosing and

debugging.

On the other hand, if this freedom is not properly used, all sorts

of things can go wrong (blocking, …) see <a class="xref" href="entrans.html#muxing-pipelines" title="Muxing Pipelines">“Muxing Pipelines”</a> and

<a class="xref" href="entrans.html#requirements" title="Requirements">“Requirements”</a> [do not even try to run in this mode if what is stated

there is not fully clear and understood].

For now, this mode is also required for performing

e.g. video-passthrough transcoding (perhaps more appropriately

called re-muxing in this case).

</li><li>Dynamic mode.

decodebin

is applied to the inputstream, which will

automagically provide all the streams present in the input in

their decoded raw (video, audio or other, e.g. text) form.

Each of these streams is then connected to an instance of a pipeline

(fragment) given by <code class="option">--video</code>, <code class="option">--audio</code>

or <code class="option">--other</code>, each typically containing filters and/or

encoder. An optional subsequent step is trying to connect this to an

appropriately selected muxer for the output.

</li></ul></div>

In any case, no (advanced) error processing or sane-ness checking

is performed on either pipeline or pipeline fragments.

As such, linking, negotiation or other matters can very well fail,

e.g. if fragments do not contain encoder elements that are compatible

with the muxer in question. It is also possible for some

parts of the pipeline to simply remain disconnected and

the corresponding stream being effectively discarded (this might

also be used as a feature ;-) ).

Reporting on any of these occurrences is of course done in as much

as the pipeline provides info on what is happening.

Though this may sound ominous, in practice, this comes down to

either things working out just nicely

or finding out about something going wrong in a more or less fast and

hard way.

Having a look at <a class="xref" href="entrans.html#examples" title="Examples">“Examples”</a> should increases chances on the former

being the case, and should even provide enough for a jump-start based on some

<a class="ulink" href="http://www.gstreamer.net/" target="_top">GStreamer</a> experience.

Processing can be halted at any time by sending a <code>SIGINT</code>

or <code>SIGTERM</code> signal to entrans.

This will make entrans block the data-flow and send an end-of-stream event

through the pipeline to ensure graceful termination of streaming.

As such, it should be noted that termination may not occur instantly,

it might take a moment for things to “run out”

(particularly with some queues around).

100

If in rare cases this mechanism were to fail, sending such a signal

101

a second time will forego any attempts at graceful shutdown

102

and will make entrans end things the hard way with no

103

guarantee on the output being fully OK

104

(it will most likely not be) …

105

106

107

Due to the way the python interpreter handles signals,

108

even the above may not work if things are messed up seriously,

109

e.g. when python interpreter is caught up somewhere in <a class="ulink" href="http://www.gstreamer.net/" target="_top">GStreamer</a> backend code.

110

This, however, has only been known to happen as a prelude

111

to finding some serious application bug or <a class="ulink" href="http://www.gstreamer.net/" target="_top">GStreamer</a> plugin/core bug.

112

Regardless, e.g. <code>SIGKILL</code> is then your friend …

113

</div>

114

</div><div class="refsect1" lang="en" xml:lang="en"><a id="options"></a><h2>Options</h2>entrans accepts the options presented in the following sections,

115

most of which have shortname (one-letter) or longname forms.

116

The ordering of the options is not strict, and options can be single-valued

117

or multi-valued.

118

119

In the former case, which is the default unless otherwise

120

indicated below, only the value given last is retained.

121

In particular, this includes boolean options.

122

If such an option is given, the corresponding setting is turned “on”.

123

The setting can also be explictly turned “off”

124

by providing the corresponding

125

<code class="option">--no-<code>longname</code></code> option.

126

</li><li>

127

Otherwise, for multi-valued options, all values given are taken into

128

consideration.

129

In these cases, it may sometimes also be possible to pass several values per

130

single option occurrence, by comma-separating these values as indicated in each

131

such case below. This will typically be the case in those instances where there

132

can be no ambiguity since the supplied value does not include

133

“free-text”.

134

</li></ul></div>

135

<div class="variablelist"><dl><dt><code class="option">-h</code>, <code class="option">--help</code></dt><dd>Show a brief help message.</dd></dl></div><div class="refsect2" lang="en" xml:lang="en"><a id="pipeline-options"></a><h3>Pipeline options</h3>

136

At least one of the following options should be provided

137

following <code class="option">--</code> (in each case, see gst-launch(1) for

138

the syntax of <code>pipeline-description</code>).

139

Clearly, as explained previously, the former option excludes

140

all of the latter ones.

141

142

<code class="option">--raw <code>pipeline-description</code></code>

143

</dt><dd>Makes entrans run in raw mode, and provides

144

the complete pipeline for this mode of operation.

145

146

Again, this should be used with expertise and being aware of comments

147

in <a class="xref" href="entrans.html#muxing-pipelines" title="Muxing Pipelines">“Muxing Pipelines”</a> and <a class="xref" href="entrans.html#requirements" title="Requirements">“Requirements”</a>.

148

</dd><dt><code class="option">--video[:<code>streamnumber</code>]

149

<code>pipeline-description</code></code></dt><dd>

150

<code>pipeline-description</code>

151

describes a pipeline fragment for video data processing,

152

typically consisting of 0 or more filters followed by an encoder.

153

</dd><dt><code class="option">--audio[:<code>streamnumber</code>]

154

<code>pipeline-description</code></code></dt><dd>Similar to <code class="option">--video</code>, except that it provides

155

a pipeline for (optionally) processing and encoding audio data.

156

</dd><dt><code class="option">--other[:<code>streamnumber</code>]

157

<code>pipeline-description</code></code></dt><dd>Similar to the above options, except that it provides

158

a pipeline for (optionally) processing and/or encoding data

159

that does not fit in the above categories, e.g. subtitles.

160

</dd><dt><code class="option">--decoder

161

<code>decoder-factory</code></code></dt><dd>Use <code>decoder-factory</code> instead of

162

the default decodebin to construct the decoding

163

part of the pipeline in dynamic mode (as mentioned earlier).

164

The given element should have compatible behaviour/signals

165

with decodebin, such as for instance the

166

new experimental decodebin2.

167

</dd></dl></div>

168

The above (partial) pipelines should typically have an encoder as last

169

element. In any case, it should best not be a generic element, as that

170

might cause confusion as to how to link to the muxer (see also

171

<a class="xref" href="entrans.html#muxing-pipelines" title="Muxing Pipelines">“Muxing Pipelines”</a>).

172

173

It is also possible to “close” any of the above

174

pipeline fragments by ending it with a sink element. In this case,

175

the resulting stream will not be muxed and each can

176

have independent output, e.g. streamed to a file.

177

As each of these would evidently need to have distinct names,

178

there is (extremely) limited support for variable substitutions.

179

Each (video and audio) stream that dynamically becomes available is

180

(independently) numbered, starting from 1, and as such

181

assigned an (audio or video) stream number.

182

Any element property of type string will be

183

subject to having <code class="literal">${vn}</code>, <code class="literal">${an}</code>

184

and <code class="literal">${on}</code> replaced by the video, audio and other

185

stream number (at that time) respectively in video, audio or other

186

pipeline fragments.

187

If any of the above have a <code>streamnumber</code> appended,

188

then that fragment will only apply to that particular stream, otherwise

189

it will be the default fragment. If no specific or default fragment

190

has been provided for a particular stream, then that stream will be discarded.

191

This effect is similar to the use of <code class="option">--vn</code>, <code class="option">--an</code>

192

or <code class="option">--on</code> (see next section).

193

194

As an additional convenience, all (partial) pipelines passed to entrans

195

will perform a simple form of glob-expansion for raw video and

196

audio mimetypes in capsfilters. That is, e.g. <code class="literal">video/*</code>

197

will be expanded to raw video mimetypes

198

(also distributing properties if any, of course).

199

This allows e.g. for scaling without particular attention for what colorspace

200

may be in use at a particular stage.

201

</div><div class="refsect2" lang="en" xml:lang="en"><a id="io-options"></a><h3>Input/output options</h3>

202

The option in this section are only applicable

203

in dynamic mode, so incompatible with <code class="option">--raw</code>.

204

205

<div class="variablelist"><dl><dt><code class="option">-i <code>uri</code></code>, <code class="option">--input <code>uri</code></code></dt><dd>

206

Indicates the input source. If <code>uri</code> is a

207

valid URI, then a proper source element will be selected, otherwise it is simply

208

taken as a (relative) path of an inputfile. If <code>uri</code> is

209

<code class="literal">-</code>, then stdin will be used as input.

210

</dd><dt><code class="option">-o <code>uri</code></code>, <code class="option">--output <code>uri</code></code></dt><dd>

211

Indicates the output destination. If <code>output</code> is a

212

valid URI, then a corresponding sink element is selected, otherwise

213

it is taken as a (relative) path of an outputfile

214

(output to stdout is not supported).

215

The (file)suffix of <code>uri</code> is used to automagically

216

choose an appropriate muxer, which can be overridden with

217

<code class="option">--muxer</code>

218

</dd><dt><code class="option">--muxer <code>mux-element</code></code></dt><dd>

219

Use <code>mux-element</code> in stead of the automatically

220

selected one, or if one fails to be auto-selected.

221

<code>mux-element</code> must be of <code class="literal">Muxer</code> class.

222

</dd></dl></div>

223

224

As mentioned in the previous section, all streams found in the input are

225

assigned a stream number and considered for processing, unless somehow

226

restricted by the following options.

227

228

<div class="variablelist"><dl><dt><code class="option">--vn <code>streamnumber[,…]</code></code>, <code class="option">--an <code>streamnumber[,…]</code></code>, <code class="option">--on <code>streamnumber[,…]</code></code></dt><dd>

229

[multi-valued] Only the video, audio or other streams with (respectively) listed

230

<code>streamnumber</code> will be considered, others disregarded.

231

Furthermore, streams of each type will be muxed into the target in the order

232

in which their <code>streamnumber</code>s are given in these options,

233

and in overall first video, then audio and others.

234

</dd><dt><code class="option">--sync-link</code></dt><dd>

235

This option is mainly meant for testing and diagnostic purposes.

236

It basically disables the stream(re)-ordering mechanism as implied by and

237

explained in the above option (though still retains stream selection).

238

</dd><dt><code class="option">--at <code>tag[,…]</code></code></dt><dd>

239

[multi-valued] Audio streams can (though need not) be accompanied by a language tag

240

(typically a 2- or 3-letter language code). The regular expression

241

242

is matched against each detected audio stream's language tag and only

243

streams without language tag or streams with a matching language tag are

244

processed, others disregarded. This selection method cannot

245

be combined with the above streamnumber based selection.

246

247

<div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> The current (or another?) method of

248

implementing this selection may very well not work with all muxer elements. As

249

such, this option can be given a try, but if not successful, the much more

250

robust <code class="option">--an</code> should be used instead. The proper

251

number(s) to use for this may be derived from (ordered) tag information that is

252

provided by some elements and reported at start-up.

253

</div>

254

</dd><dt><code class="option">--stamp</code></dt><dd>

255

This is enabled by default, and makes entrans insert an <a class="ulink" href="http://www.gstreamer.net/data/doc/gstreamer/head/gstreamer-plugins/html/gstreamer-plugins-identity.html" target="_top">identity</a> element

256

(with single-segment True) before the connected pipeline-fragment

257

to perform timestamp re-sequencing. This is typically useful when

258

muxing into a format that records timestamps (and does not hurt

259

when the format does not).

260

</dd></dl></div>

261

</div><div class="refsect2" lang="en" xml:lang="en"><a id="basic-options"></a><h3>Basic options</h3>

262

Whereas no specific dependencies exist for all other options,

263

the <a class="xref" href="entrans.html#requirements" title="Requirements">“Requirements”</a> section applies particularly

264

to the following options (in more or less degree).

265

<div class="variablelist"><dl><dt><code class="option">-c

266

<code>[[(]<code>format</code>[)]:]t1-t2[,…]</code></code>, <code class="option">--cut

267

268

[multi-valued]

269

Only process the indicated sections of the pipeline (by default the complete

270

input is processed). The option <code class="option">-s</code> determines the method used

271

for selecting the desired data.

272

273

If no <code>format</code> is provided,

274

the <code>tN</code> parameters can be given in timecode format

275

HH:MM:SS.FRACTION or as a (video)framenumber, which is a number following

276

<code class="literal">f</code> or <code class="literal">F</code>. Any buffer that

277

overlaps with the indicated section is taken into account. The last indicated

278

section may be open-ended, i.e. the end point may be omitted.

279

280

281

However, if <code>format</code> is the nickname of a pre-defined

282

or custom format (defined by some element in the pipeline), then it is used as

283

unit for the <code>tN</code> numbers.

284

In this case, option <code class="option">-s</code> below must select a seek-based method,

285

and the seek will be executed in <code>format</code> if it is provided

286

without matching (…), otherwise the given units will be (query) converted

287

to time format first, and these results will be used to seek in time.

288

</dd><dt><code class="option">-s <code>method</code></code>, <code class="option">--section <code>method</code></code></dt><dd>

289

Possible choices for <code>method</code> are:

290

291

Sections are selected by means of regular <a class="ulink" href="http://www.gstreamer.net/" target="_top">GStreamer</a> seeks.

292

A flushing seek is performed for the first section,

293

segment seek for the others, and a normal seek for the last section.

294

This is also the default method and is OK for most circumstances.

295

In some cases, however, the other methods may be in order,

296

e.g. when (the driving element in) the pipeline does not support

297

some type of seek that would be used.

298

</dd><dt><code class="literal">seek-key</code></dt><dd>

299

This is similar to the case above, but each seek is also a keyframe seek,

300

that is, the actual selection may not be exactly the one

301

that was requested but may start at the nearest keyframe

302

preceding the desired start.

303

This would typically be required when performing re-muxing

304

without fully decoding and re-encoding the material.

305

</dd><dt><code class="literal">cut-time</code></dt><dd>

306

In this case, the pipeline is run from the start (without any seeks)

307

and all but the desired sections are disregarded.

308

The decision whether or not to drop a piece of data is based on its timestamp.

309

This is the recommended (only possible) method to use

310

when performing A/V sync correction using data-timestamp shifting,

311

e.g. by means of the <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-shift.html" target="_top">shift</a> element. It can also be used

312

to end a live source(s) driven pipeline after a specified duration.

313

</dd><dt><code class="literal">cut</code></dt><dd>

314

This method applies in case any/all of the above fail, e.g. some element

315

does not support seek or unreliable timestamps are produced in the pipeline.

316

No seeks or anything special is done, the pipeline is run from the start and all but the

317

indicated sections is dropped. Timestamps on the datastream are disregarded,

318

and the incoming data is restamped based on framecount and framerate

319

(video), or on sample count and samplerate (audio).

320

In particular, audio cutting is performed up to sample precision.

321

</dd></dl></div>

322

Note that the last 2 methods require the desired sections to be in ascending

323

order, whereas the former methods make it possible to select sections

324

that are out-of-order with regards to the input material.

325

</dd><dt><code class="option">-a</code></dt><dd>

326

Perform (audio) sample precision selection, that is, it is possible for only parts of

327

buffers to be passed or dropped. This is done by default

328

in the <code class="literal">cut</code> method above, but not for the other methods.

329

</dd><dt><code class="option">--dam</code></dt><dd>

330

Indicate, or rather, confirm that <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a> elements are being used

331

in raw pipelines.

332

Otherwise, “surrogate dam” elements will be searched for and used instead.

333

These are identified as elements whose name is of the form

334

<code class="literal">dam<code><digits></code></code>.

335

</dd><dt><code class="option">-f <code>framerate</code></code>, <code class="option">--framerate <code>framerate</code></code></dt><dd>

336

The framerate that is used for framenumber to time conversion is normally

337

auto-detected (soon enough) within the pipeline. If this were not to succeed,

338

then <code>framerate</code>,

339

specified as <code>NUM[/DENOM]</code>,

340

is used as a fallback instead of the otherwise default 25/1.

341

</dd><dt><code class="option">-b</code>, <code class="option">--block-overrun</code></dt><dd>

342

This makes entrans prevent automatic adjustments to queues

343

(in a decodebin), thereby keeping them at fixed size.

344

345

Despite all the automagic, the pipeline may stall in exotic cases

346

(e.g. some strange behaving element/muxer, …). A good first thing to try

347

then is to configure queues at a larger-than-default setting (see for example

348

following section) and to use this option to ensure they really remain

349

configured as intended without any other influence.

350

</dd></dl></div>

351

</div><div class="refsect2" lang="en" xml:lang="en"><a id="pipe-config-options"></a><h3>Pipeline configuration</h3>

352

Although element properties are typically set in the pipeline descriptions,

353

the following options can be useful for dynamically created elements (see for

354

instance the dvd example in <a class="xref" href="entrans.html#examples" title="Examples">“Examples”</a>) or when it is desired to configure a property

355

syntactically separated from the pipeline on the command line.

356

357

<div class="variablelist"><dl><dt><code class="option">--set-prop

358

<code>

359

element:prop:value[:time]

360

</code>

361

</code></dt><dd>

362

Sets property <code>prop</code> of

363

<code>element</code> to <code>value</code>,

364

where <code>element</code> can either be an element-type, or the

365

name or full path-string of a specific element.

366

If <code>prop</code> is a <code class="literal">GST_CONTROLLABLE</code>

367

property (use gst-inspect(1) to determine this),

368

then a (pipeline media) <code>time</code> at which

369

370

should be set to this particular <code>value</code>

371

(using the controller framework) can be given as well.

372

373

In general, a value given for a property within the pipeline description

374

will override any value provided this way. In case of queues,

375

however, both decodebin and entrans will override some

376

properties' values in order to minimize the possibility of blocking.

377

Though it is not recommended, <code class="option">set-prop</code> can be used

378

to forcibly overwrite such aforementioned defaults.

379

380

The rank of an element (as a plugin feature), which (a.o.) determines whether or

381

not it is considered for auto-plugging (in dynamic mode) is considered

382

as a pseudo-property <code class="literal">pf_rank</code> and can therefore be set

383

in this way as well.

384

</dd><dt><code class="option">--vb <code>vkbitrate</code></code>, <code class="option">--ab <code>akbitrate</code></code></dt><dd>

385

Sets the <code class="literal">bitrate</code> property of any video or audio element to

386

<code>vkbitrate</code> [ * 1000] or

387

<code>akbitrate</code> [ * 1000] respectively,

388

depending on whether the property expects to be provided with (k)bitrate.

389

</dd><dt><code class="option">--vq <code>vquality</code></code>, <code class="option">--aq <code>aquality</code></code></dt><dd>

390

Sets either the <code class="literal">quality</code> or <code class="literal">quantizer</code>

391

property of any video or audio element to <code>vquality</code> or

392

<code>aquality</code> respectively.

393

394

</dd><dt><code class="option">--pass <code>pass</code></code></dt><dd>

395

Sets the <code class="literal">pass</code> property of any video element to

396

<code>pass</code>, which

397

must be <code class="literal">1</code> or <code class="literal">2</code>.

398

</dd><dt>

399

<code class="option">-t <code>tag:value</code>

400

</code>

401

</dt><dd>

402

[multi-valued]

403

entrans locates a <code class="interfacename">TagSetter</code> in

404

the pipeline and sets each given <code>tag</code> to

405

<code>value</code>.

406

407

A list of possible tags can be found in

408

<a class="ulink" href="http://www.gstreamer.net/data/doc/gstreamer/head/gstreamer/html/gstreamer-GstTagList.html" target="_top">GStreamer core documentation</a>.

409

</dd></dl></div>

410

</div><div class="refsect2" lang="en" xml:lang="en"><a id="reporting-options"></a><h3>Reporting options</h3>

411

By default, entrans reports the following items at startup:

412

413

an overview of elements found in the pipeline,

414

along with the current values of properties that differ from their

415

usual (default) setting;

416

tags announced by an element are considered as a pseudo-property

417

<code class="literal">tag</code> of the element

418

</li><li>

419

a set of distinct caps that have been found flowing through the pipeline,

420

</li><li>

421

the (video) queues found in the pipeline (with their neighbours),

422

and their maximum capacity settings (size, buffers, time)

423

</li></ul></div>

424

After that, it provides the following in regular intervals, if already available

425

or applicable:

426

427

(time) position in input stream,

428

</li><li>

429

movie time: position in output stream, and the total expected output movie time

430

</li><li>

431

processing speed: ratio of elapsed (input) stream time to elapsed CPU time

432

</li><li>

433

ETA: expected time to completion of processing;

434

this calculation always uses elapsed system clock time,

435

regardless of options below,

436

</li><li>

437

amount of buffers presently contained in the queues reported at startup,

438

</li><li>

439

if a specific output file can be identified, (combined) bitrate so far.

440

</li></ul></div>

441

442

The following options can influence some of this behaviour:

443

<div class="variablelist"><dl><dt><code class="option">-d <code>delay</code></code>, <code class="option">--delay <code>delay</code></code></dt><dd>

444

Sets the interval between progress updates to <code>delay</code>

445

seconds. The default delay is 2 seconds.

446

</dd><dt><code class="option">--timeout <code>timeout</code></code></dt><dd>

447

As an entrans run spins up, it transitions through a number of stages, which

448

should normally follow each other in pretty rapid succession.

449

<code>timeout</code>, by default 4, is the maximum interval

450

(in seconds) that will be allowed between such stages. If the interval is exceeded,

451

entrans may simply abort altogether or try to recover the situation

452

(depending on the stage), the success of which depends on the cause

453

(e.g. a misbehaving element, or a badly constructed pipeline, …).

454

Evidently, a high <code>timeout</code> value essentially renders

455

this check mute. Setting it to 0 completely disables this check as well

456

as some other mechanisms employed to support it, and is not normally advisable.

457

</dd><dt><code class="option">--progress-fps</code></dt><dd>

458

Makes regular reports also provide processing speed in fps, which is calculated

459

using either auto-detected framerate or provided by <code class="option">-f</code>.

460

</dd><dt><code class="option">--progress-real</code></dt><dd>

461

Calculate processing speed based on elapsed system clock time (instead of CPU-time).

462

</dd></dl></div>

463

464

In the following, <code>proppattern</code>

465

is a regular expression that will be matched a combination of

466

an <code>element</code> and (optionally) one its properties

467

<code>prop</code>. More precisely, this combination

468

matches if the regular expression matches any of the following:

469

470

<code>element's factory name</code>.<code>prop</code>

471

</li><li>

472

<code>element's name</code>.<code>prop</code>

473

</li><li>

474

<code>element's path name</code>.<code>prop</code>

475

</li></ul></div>

476

In each case, the last part is omitted if there is no

477

<code>prop</code> in the context in question.

478

479

Similarly, <code>msgpattern</code> is matched against

480

expressions as above, but with <code>prop</code> replaced by

481

<code>message type name</code>.<code>message structure name</code>

482

Again, in each case, the last part is omitted if there is no structure for the

483

message in question.

484

485

Output messages posted on the pipeline's bus

486

</dd><dt><code class="option">-v</code></dt><dd>

487

Provide output on property changes of the pipeline's elements.

488

This output can be filtered using <code class="option">-x</code>

489

</dd><dt><code class="option">--short-caps</code></dt><dd>

490

Do not perform complete caps to string conversion, instead replace e.g. buffers

491

with their (string) type representation.

492

This can make for more comfortable display of e.g. Vorbis and Theora related caps.

493

</dd><dt>

494

<code class="option">--ignore-msg <code>msgpattern[,…]</code>

495

</code>

496

,

497

<code class="option">--display-msg <code>msgpattern[,…]</code>

498

</code>

499

</dt><dd>

500

[multi-valued] If message reporting is enabled by <code class="option">-m</code>,

501

only report on those that match <code class="option">--display-msg</code>

502

or do not match <code class="option">--ignore-msg</code>

503

</dd><dt>

504

<code class="option">-x <code>proppattern[,…]</code>

505

</code>

506

,

507

<code class="option">--exclude <code>proppattern[,…]</code>

508

</code>

509

,

510

<code class="option">--include <code>proppattern[,…]</code>

511

</code>

512

</dt><dd>

513

[multi-valued] If property change reporting is enabled by <code class="option">-v</code>,

514

only report those on properties that match <code class="option">--include</code>

515

or do not match <code class="option">--exclude</code>

516

</dd><dt>

517

<code class="option">--display-prop <code>proppattern[,…]</code>

518

</code>

519

,

520

<code class="option">--ignore-prop <code>proppattern[,…]</code>

521

</code>

522

</dt><dd>

523

[multi-valued] An element's property (value) is reported at start-up if and only if

524

it matches an expression given in <code class="option">--display-prop</code>

525

or its value differs from the usual and it does not match

526

<code class="option">--ignore-prop</code>.

527

Also, in any case, an element's presence in the pipeline is at least

528

mentioned by default, unless the element (by itself) matches

529

<code class="option">--ignore-prop</code>

530

</dd></dl></div></div><div class="refsect2" lang="en" xml:lang="en"><a id="config-options"></a><h3>Configuration options</h3>

531

Each entrans option —be it one affecting entrans'

532

run-time behaviour or affecting pipeline element (properties)—

533

can also be provided on a more permanent basis using a configuration

534

file.

535

536

Such a file consists of sections, led by

537

a “<code class="literal">[section]</code>” header and

538

followed by “<code class="literal">name: value</code>” entries,

539

“<code class="literal">name=value</code>” is also accepted.

540

Note that leading whitespace is removed from values.

541

Lines beginning with “<code class="literal">#</code>” or

542

“<code class="literal">;</code>” are ignored and may be used to

543

provide comments.

544

545

In the special section “<code class="literal">[options]</code>”,

546

each entry “<code class="literal">name: value</code>”

547

is equivalent to providing <code class="option">--<code>name</code>

548

<code>value</code></code> on the command-line,

549

where <code>name</code> must be an option's longname.

550

551

The name of any other section is interpreted as an element-type

552

or an element, with each entry providing a value for a property.

553

Otherwise put, each “<code class="literal">prop: value</code>”

554

in a section

555

“<code class="literal">[<code>element</code>]</code>”

556

is equivalent to mentioning it in <code class="option">--set-prop</code> as

557

<code>element:prop:value</code>

558

559

By default, the configuration file is called <code class="filename">.gst-entrans</code>

560

and is searched for in the current directory and in the user's home directory

561

(in that order).

562

563

Any setting provided on the command line for a single-valued option

564

(e.g. a boolean option) overrides a similar value given in a configuration file,

565

whereas values provided for multi-valued ones append to those already provided.

566

<div class="variablelist"><dl><dt><code class="option">--config <code>file</code></code></dt><dd>

567

Use <code>file</code> instead of any

568

default configuration file.

569

</dd><dt><code class="option">--profile <code>file</code></code></dt><dd>

570

Load <code>file</code> after other

571

configuration files, either default ones or given by <code class="option">--config</code>.

572

This option derives its name from its use in loading certain export or

573

encoder profiles (e.g. MPEG1, MPEG2, etc),

574

which are mainly a collection of presets for certain properties that can

575

be kept in corresponding profile configuration files.

576

</dd></dl></div></div><div class="refsect2" lang="en" xml:lang="en"><a id="misc-options"></a><h3>Miscellaneous options</h3><div class="variablelist"><dl><dt><code class="option">--save

577

<code>message:file[:append][,…]

578

</code>

579

</code></dt><dd>

580

[multi-valued]

581

Makes entrans save a custom element <code>message</code> to

582

<code>file</code>,

583

that is, the string representation of the message's structure is saved

584

(followed by a linefeed).

585

If <code>append</code> is true (e.g. <code class="literal">1</code>, <code class="literal">t</code>,

586

<code class="literal">T</code>), then all messages are appended to <code>file</code>,

587

otherwise the default is to truncate <code>file</code> whenever

588

<code>message</code> is received, thereby saving only the

589

most recently received <code>message</code>.

590

For good measure,

591

it might be noted here there was a change in version 0.10.15 in a structure's

592

string representation with respect to usage of a terminating ;.

593

594

<code>file</code> will be subject to having <code class="literal">${n}$</code>

595

replaced by the name of the element sending <code>message</code>.

596

</dd></dl></div></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="examples"></a><h2>Examples</h2>

597

More examples of pipelines can also be found in gst-launch(1);

598

the ones below are primarily meant to illustrate some of

599

entrans' features.

600

601

In each case, everything could also be written on one line, without the backslash

602

character. In some cases, some particular quoting is needed to prevent

603

(mis)interpretation by the shell.

604

<div class="example"><a id="id527789"></a>Example 2.1. Basic transcoding<div class="example-contents">

605

606

entrans.py -i dvd://2 -o dvd.ogm --short-caps -- \

607

--video ! theoraenc --audio audioconvert ! vorbisenc

608

</pre>

609

Transcodes complete title 2 from a DVD into a mixed Ogg containing all video

610

and audio tracks (but no subtitles) using default settings, while preventing

611

some extensive caps display.

612

</div></div> <div class="example"><a id="id527807"></a>Example 2.2. Selected stream transcoding<div class="example-contents">

613

614

entrans.py --set-prop dvdreadsrc:device:/mnt -i dvd://2 -o dvd.mkv \

615

--set-prop dvdsubdec:pf_rank:128 --on 6,12 --an 1,2 --vq 4 --ab 256 -- \

616

--video ffenc_mpeg4 --audio audioconvert ! lame \

617

--other ffmpegcolorspace ! ffenc_mpeg4 ! matroskamux ! filesink location='sub-${on}.mkv'

618

</pre>

619

Transcodes video and selected audio tracks from a DVD image mounted at /mnt

620

into a Matroska file, using the indicated fixed quantization and bitrate for

621

video and audio respectively. Some selected subtitle tracks are also encoded

622

as separate video streams into other Matroska files. Note that the rank of

623

the dvdsubdec must be increased for a subtitle stream to be

624

considered for decoding and subsequently made available.

625

</div></div> <div class="example"><a id="id527833"></a>Example 2.3. Extensive progress update transcoding<div class="example-contents">

626

627

entrans.py -i example-in.avi -o example-out.mkv -- \

628

--video tee name=tee ! queue ! theoraenc \

629

tee. ! queue ! timeoverlay ! xvimagesink sync=false qos=false \

630

--audio audioconvert ! lame

631

</pre>

632

Transcodes into Matroska using Theora and MP3 codecs, while providing for

633

(excessive) live preview progress info.

634

</div></div> <div class="example"><a id="id527851"></a>Example 2.4. Partial stream transcoding<div class="example-contents">

635

636

entrans.py -i dvd://2 -o dvd.mkv -c chapter:5- --short-caps -- \

637

--video ! identity single-segment=true ! ffenc_mpeg4 \

638

--audio audioconvert ! identity single-segment=true ! vorbisenc

639

</pre>

640

Transcodes all video and audio tracks from a DVD title 2 (chapter 5 to the end)

641

into Matroska using MPEG4 and Vorbis codecs (while catering for properly

642

timestamped input for the container which records these faithfully for posterity).

643

</div></div> <div class="example"><a id="ex-pass-through"></a>Example 2.5. Pass-through transcoding<div class="example-contents">

644

645

entrans.py -s seek-key -c 60-180 --dam -- --raw \

646

filesrc location=example-in.avi ! avidemux name=demux \

647

avimux name=mux ! filesink location=example-out.avi \

648

demux.video_00 ! queue ! dam ! queue ! mux.video_0 \

649

demux.audio_00 ! queue ! dam ! queue ! mad ! audioconvert ! lame ! mux.audio_0

650

</pre>

651

Transcodes a particular section from an AVI file into another AVI file without

652

re-encoding video (but does re-encode audio, which is

653

recommended). The output will range from (approximately) 60 seconds into the

654

input up to 180 seconds; actually there will be a (key)seek to the nearest

655

keyframe just before the 60 seconds point to ensure the integrity of later

656

decoding of the output.

657

In addition, entrans will report changes on any object's properties, except

658

for any (pad's) caps.

659

660

The pipeline above uses raw mode, and as such must abide

661

by some rules and recommendations in pipeline building (see <a class="xref" href="entrans.html#muxing-pipelines" title="Muxing Pipelines">“Muxing Pipelines”</a>),

662

which leads in particular to the above abundance in queues.

663

With some extra configuration, pass-through could also be performed in

664

dynamic mode as follows (assuming that <code class="literal">video/mpeg</code> properly

665

describes the encoded video content):

666

667

entrans.py -s seek-key -c 60-180 --decoder decodebin2 \

668

--set-prop 'decodebin2:caps:video/mpeg;audio/x-raw-int;audio/x-raw-float' \

669

-i example-in.avi -o example-out.avi -- \

670

--video capsfilter caps=video/mpeg \

671

--audio audioconvert ! lame

672

</pre>

673

</div></div> <div class="example"><a id="id527928"></a>Example 2.6. Live recording<div class="example-contents">

674

675

entrans.py -s cut-time -c 0-60 -v -x '.*caps' --dam -- --raw \

676

v4l2src queue-size=16 ! video/x-raw-yuv,framerate=25/1,width=384,height=576 ! \

677

stamp sync-margin=2 silent=false progress=0 ! queue ! \

678

dam ! ffenc_mpeg4 name=venc \

679

alsasrc buffer-time=1000000 ! audio/x-raw-int,rate=48000,channels=1 ! queue ! \

680

dam ! audioconvert ! queue ! lame name=aenc \

681

avimux name=mux ! filesink location=rec.avi aenc. ! mux. venc. ! mux.

682

</pre></div>

683

Records 1 minute of video and audio from a video4linux device and features

684

additional synchronization and reporting on object property changes (if any),

685

which includes reports on frame drops or duplications, although

686

(pad's) caps changes are excluded for convenience.

687

</div></div> <div class="example"><a id="id527953"></a>Example 2.7. 2-pass transcoding<div class="example-contents">

688

689

entrans.py -i example-in.avi -o /dev/null --muxer avimux --vb 1200 --pass 1 \

690

--save astat:astat.log -- --video ffenc_mpeg4 \

691

--audio audioconvert ! astat ! fakesink

692

SCALE="$(cat astat.log | sed 's/astat, scale=(double)//' | sed 's/;//')"

693

entrans.py -i example-in.avi -o example-out.avi --vb 1200 --pass 2 \

694

--tag 'comment:2-pass demonstration' -- \

695

--video ffenc_mpeg4 --audio audioconvert ! volume volume=$SCALE ! lame

696

</pre>

697

Performs 2-pass transcoding from one AVI into another. The first pass also

698

determines and saves the maximum volume scaling that can safely be applied

699

without having to resort to clipping. It does not bother performing audio encoding

700

or producing an output file. Although the particular (encoder compatible) muxer

701

is hardly relevant here, one is nevertheless indicated explicitly

702

as a “reasonable”choice cannot be determined

703

from <code class="literal">/dev/null</code>. After some scripting to retrieve the

704

saved value from a file, the second pass performs volume scaling and encoding.

705

It also sets a comment (tag) in the resulting file to note its lofty goal.

706

</div></div> <div class="example"><a id="id527986"></a>Example 2.8. Configuration file<div class="example-contents">

707

708

[options]

709

ignore-prop=.*src.*,.*sink.*,dam.*,queue.*,identity.*,.*decodebin.*

710

display-prop=.*\.tag,.*\.bitrate$,.*bframes,.*quantizer,.*\.pass,.*\.queue-size

711

712

[ffenc_mpeg4]

713

me-method=epzs

714

max-bframes=0

715

gop-size=250

716

717

[dvdsubdec]

718

pf_rank = 128

719

</pre>

720

A basic, though adequate configuration file that filters out some

721

(usually less interesting) information on some “technical”

722

technical elements, while making sure on the other hand that some other

723

settings get displayed in any case. In addition, an element's properties

724

can be given defaults (other than the hardcoded ones), and the rank

725

of dvdsubdec is increased so that subtitles streams will

726

also be provided.

727

</div></div> <div class="example"><a id="id528015"></a>Example 2.9. Profile configuration<div class="example-contents">

728

Some examples of (encoding) profiles that can be passed to

729

<code class="option">--profile</code> (each profile is in a separate file).

730

Note that profiles also impose

731

constraints on e.g. width and height which are not automagically

732

enforced; one must still take care of this by means of e.g. proper scaling.

733

Similarly, the elements that are to perform the required encoding

734

must be properly (manually) specified, though their configuration

735

is then taken care of by the examples below.

736

737

# vcd:

738

# 352 x 240|288

739

# 44.1kHz, 16b, 2ch, mp2

740

741

[options]

742

vb = 1150

743

ab = 224

744

745

[ffenc_mpeg1video]

746

bitrate = 1150

747

# <= 10

748

gop-size = 9

749

rc-min-rate = 1150

750

rc-max-rate = 1150

751

rc-buffer-size = 320

752

rc-buffer-aggressivity = 99

753

754

[mpeg2enc]

755

format = 1

756

</pre>

757

758

# --------

759

# svcd:

760

# 480 x 480|576

761

# 44.1kHz, 16b, 2ch, mp2

762

763

[options]

764

vb = 2040

765

# >= 64, <= 384

766

ab = 224

767

768

[ffenc_mpeg2video]

769

bitrate = 2040

770

# <= 19

771

gop-size = 15

772

# ntsc: gop-size = 18

773

rc-min-rate = 0

774

rc-max-rate = 2516

775

rc-buffer-size = 1792

776

rc-buffer-aggressivity = 99

777

flags = scanoffset

778

779

[mpeg2enc]

780

format = 4

781

</pre>

782

783

# ---------

784

# xvcd:

785

# 480 x 480|576

786

# 32|44.1|48kHz, 16b, 2ch, mp2

787

788

[options]

789

vb = 5000

790

# >= 64, <= 384

791

ab = 224

792

793

[ffenc_mpeg2video]

794

# 1000 <= bitrate <= 9000

795

bitrate = 2040

796

# <= 19

797

gop-size = 15

798

# ntsc: gop-size = 18

799

rc-min-rate = 0

800

# optional:

801

rc-max-rate = 5000

802

803

rc-buffer-size = 1792

804

rc-buffer-aggressivity = 99

805

flags = scanoffset

806

</pre>

807

808

# ------

809

# dvd:

810

# 353|704|720 x 240|288|480|576

811

# 48kHz, 16b, 2ch, mp2|ac3

812

813

[options]

814

vb = 5000

815

# >= 64, <= 384

816

ab = 224

817

818

[ffenc_mpeg2video]

819

# 1000 <= bitrate <= 9800

820

bitrate = 5000

821

# <= 19

822

gop-size = 15

823

# ntsc: gop-size = 18

824

rc-min-rate = 0

825

rc-max-rate = 9000

826

rc-buffer-size = 1792

827

rc-buffer-aggressivity = 99

828

829

[mpeg2enc]

830

format = 8

831

</pre>

832

</div></div> </div><div class="refsect1" lang="en" xml:lang="en"><a id="requirements"></a><h2>Requirements</h2>

833

Evidently, there must be a basic <a class="ulink" href="http://www.gstreamer.net/" target="_top">GStreamer</a> framework installation,

834

the extent of which and available plugins determine the processing scope that

835

can be achieved.

836

Beyond this, it is highly recommended for the <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a> element to be available,

837

which is part of the plugins supplied along with entrans.

838

More (technical) details and motivation can be found in the documentation for

839

<a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a>, but suffice it to say that without <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a> the following notes apply:

840

841

For <code class="option">--seek</code>, only the methods

842

<code class="literal">seek</code> and <code class="literal">seek-key</code> are available.

843

However, for reasons explained in <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a> documentation and in

844

<a class="xref" href="entrans.html#muxing-pipelines" title="Muxing Pipelines">“Muxing Pipelines”</a>, even these methods can not be considered reliable,

845

either functional or technical.

846

As such, only full (uninterrupted) pipeline transcoding is really available.

847

848

As a technical note, this unreliability could be alleviated by

849

having the functionality to drop out-of-segment-bound buffers not only in sinks

850

or in some elements, but as a specific ability in

851

e.g. identity.

852

</li><li>

853

The graceful (signal initiated) termination usually

854

also relies on <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a>, and is quite sturdy in this case.

855

However, and fortunately, there is also an alternative fall-back implementation

856

that will take care of this in the vast majority of circumstances.

857

</li></ul></div>

858

859

Note that in case of dynamic pipelines, the availability of the <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a> element

860

in the system is auto-detected, and the proper pipeline-construction action is

861

taken accordingly. In raw mode, however, it must be explictly confirmed (by

862

<code class="option">--dam</code>) that <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a>s are properly used, otherwise none will

863

be assumed present and only restricted operation is then available, as indicated

864

above. Proper usage of <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a> is subject to comments in <a class="xref" href="entrans.html#muxing-pipelines" title="Muxing Pipelines">“Muxing Pipelines”</a>,

865

but basically comes down to putting a <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a> as upstream as possible in each

866

independent stream, e.g. preceding some queue. Alternatively, such a queue could

867

be used as “surrogate dam” by naming it

868

<code class="literal">dam<code><digits></code></code>.

869

</div><div class="refsect1" lang="en" xml:lang="en"><a id="id528275"></a><h2>GNonLin Comparison</h2>

870

On the one hand, one might compare in the sense that both GNonLin and entrans

871

aim to create media files while allowing for non-linear editing/cutting.

872

On the other hand, entrans is quite complementary and can actually be combined

873

with GNonLin, for example

874

875

entrans.py -- --raw gnlcomposition. '(' name=comp gnlfilesource \

876

location=test.avi start=0 duration=20000000000 media-start=0 \

877

media-duration=20000000000 caps=video/x-raw-yuv ')' \

878

comp.src ! ffenc_mpeg4 ! queue ! avimux ! filesink location=test-gnonlin.avi

879

</pre></div>

880

881

That being the case, why this alternative and yet another program, rather than

882

being content with e.g. GNonLin (and gst-launch(1)) ?

883

884

First and foremost, as a matter of style. The above example pipeline looks and

885

feels rather contrived (and that's only the video part!), and is not much of a

886

pipeline in that e.g. gnlcomposition is

887

really (deliberately) not so much a pipeline than it is more of a bag (serving

888

its intended purpose well). On the other hand, Un*x pipelines have a long

889

standing beauty (and a.o. adaptability and flexibility), and a (traditional)

890

<a class="ulink" href="http://www.gstreamer.net/" target="_top">GStreamer</a> pipeline continues in that tradition. In that sense, entrans'

891

(and gst-launch(1)) approach is an “ode to pipeline” and its

892

inherent simplicity and clarity of intent.

893

In particular, typical entrans pipelines are only slightly different than

894

playback pipelines, and the cutting/seeking mechanism is pretty identical.

895

In that way, an entrans media file creation is very close to a

896

(non-linear) playback session (and closer than a GNonLin equivalent would be).

897

898

Secondly, there are some technical reasons. Particular care has been given

899

in entrans to the non-linear cutting functionality to make sure it operates

900

with great precision in a variety of circumstances. In this area;

901

902

GNonLin, in particular gnlcomposition, may (and has been

903

known to) experience some frame-dropping near end-of-stream due to its

904

(asynchronous) technique of EOS-event generation

905

</li><li>

906

GNonLin only relies on segment seek, as does entrans usually, which

907

is fine when dealing with elements that support what and how they are supposed

908

to. However (and unfortunately), elements are not always so perfect (for

909

example, dvdreadsrc does not support segment seek).

910

In such cases, entrans has some plain-and-simple alternative methods that can

911

still get the (cutting) job done.

912

</li></ul></div>

913

So, the idea and intention basically is; if you can play it, you can entrans

914

it (with a similar pipeline, and precision in various circumstances).

915

</div><div class="refsect1" lang="en" xml:lang="en"><a id="muxing-pipelines"></a><h2>Muxing Pipelines</h2>

916

As mentioned earlier, one might run into some pitfalls when constructing

917

a (raw) pipeline, most of which are taken care of by entrans when runnning in

918

dynamic mode.

919

Building.

920

To begin with, the pipeline must be properly built and linked,

921

in particular to the muxer element, which typically only has request pads.

922

For linking and subsequent negotiation to succeed, a stream must manage

923

to get the request pad it really needs and is compatible with. That means that

924

the element connecting to the muxer (or trying so) should provide enough

925

(static) information to identify the corresponding muxer pad (template).

926

As this information is typically derived from the connecting element's

927

pad templates, it is not quite comfortable to try connecting a generic

928

element (e.g. queue). If this were needed, or there is some

929

or the other problem connecting to the muxer, then it may be helpful to use

930

a capsfilter (aka as a filtered connection) or to specifically

931

indicate the desired muxer pad (by a name corresponding to the intended

932

template, as in example <a class="xref" href="entrans.html#ex-pass-through" title="Example 2.5. Pass-through transcoding">Example 2.5, “Pass-through transcoding”</a>),

933

see also gst-launch(1) for specific syntax in either case.

934

Muxer and Queue.

935

In the particular case of a transcoding pipeline (having some media-file

936

as source), some other care is needed to make sure it does not stall, i.e.

937

simply block without any notification (or an application having

938

a chance to do something about it). Specifically, a muxer will often block a

939

thread on its incoming pad until it has enough data across all of its pads for

940

it to make a decision as to what to mux in next.

941

Evidently, if a single (demuxer) thread were having to provide data to several

942

pads, then stalling would almost surely occur. As such, each of these

943

pads/streams should have its own thread. In case of live sources, this is

944

usually already the case, e.g. separate video and audio capturing threads.

945

However, when transcoding, and therefore demuxing an input file, a

946

queue should be inserted into each outgoing stream to act as

947

a thread boundary and supply a required separate thread.

948

In addition, this multi-threading will evidently also spread processing across

949

several CPUs (if available) and improve performance. In this respect, it

950

can also be beneficial to use more than 1 queue/thread per

951

stream; one that performs filter processing (if any) and one that performs

952

encoding.

953

954

Note that similar stalling can also occur in some variations of these

955

circumstances. For instance, tee could have the role of

956

demuxer in the above story, and/or a collection of several sinks in a

957

pipeline could act as a muxer in the above story, since they will each also

958

block a thread in PAUSED state (when the pipeline is trying to make it to

959

that state). Another such situation can arise (temporarily) when pads are

960

blocked as part of the seek-mechanism. In any case, the remedy is the same;

961

use queues to prevent one thread from having to go around in

962

too many places, and ending up stuck in one of them.

963

Muxer and Time(stamps).

964

Even if the above is taken into account, the time-sensitivity of a typical

965

muxer may lead to (at first sight mysterious) stalling (in transcoding

966

pipelines). That is, a muxer will usually examine the timestamps of the incoming

967

data, select the oldest of these to be put into the outgoing stream and then

968

wait for new data to arrive on this selected input stream (i.e. keep other

969

streams/threads wait'ing).

970

It follows easily that if there is a gap, “imbalance”,

971

imperfection, irregularity (or however described) in timestamps between various

972

incoming streams, a muxer will then consistently/continuously

973

expect/want more data on 1 particular pad (for some

974

amount proportional to the irregularity).

975

For some time, this need could be satisfied by the queues

976

that are present in this stream. At some point, however, these may not hold

977

enough data and will need further input from the upstream demuxer element.

978

However, for this demuxer to provide data for 1 of its (outgoing) streams, it

979

will also need to output data for the other streams, and this ends up

980

into the other streams' queues. Unfortunately, in

981

this situation those queues cannot send out any data, as the muxer is

982

holding their threads (blocked). Hence, they will (soon) fillup and then in

983

turn block the demuxer thread trying to insert data, until there is again space

984

available. Consequently, a deadlock circle ensues; muxer waiting for new

985

data from queue, waiting for data from demuxer, waiting for space to put this

986

into another stream queue, waiting to unload data into the muxer.

987

Note that this deadlock phenomenom will not occur with live (recording) pipelines,

988

as the various threads are then not joined to a single demuxer (thread),

989

though it is then likely to manifest itself it by loss of (live) input data.

990

991

There a number of possible causes for the irregularities mentioned above.

992

993

Rarely, but not impossibly so, the problem may be inherent in the very input

994

medium itself. Or there could be a problem with a (experimental) demuxer

995

that might produce incorrect timestamps.

996

</li><li>

997

If a (segment) seek is performed in a pipeline without

998

using <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a>, it is quite likely that some stream(s) may perform proper

999

filtering of out-of-segment-bound data, and that other(s) may not. This would

1000

then cause a typical imbalance between the various streams.

1001

</li><li>

1002

If timestamps are being resequenced in some incoming streams (e.g. by

1003

<a class="ulink" href="http://www.gstreamer.net/data/doc/gstreamer/head/gstreamer-plugins/html/gstreamer-plugins-identity.html" target="_top">identity</a>), but not in the other ones, there is an obvious imbalance.

1004

</li><li>

1005

Though more exotic, even if <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a> is being used, one must take care to perform

1006

this filtering before (the by now

1007

clearly essential) queue in the respective stream,

1008

particularly when several distinct sections are to be cut out of the input.

1009

After all, if queue were placed before <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a>, then the

1010

latter does not have a chance to drop unneeded buffers soon enough.

1011

As such, if a muxer tries to get the first piece of data on a

1012

particular pad following the gap between the sections, these

1013

queues would fillup and be effectively as if they were not

1014

present.

1015

</li></ul></div>

1016

Dynamic mode services.

1017

Dynamic mode takes care of (most of) the above as follows:

1018

1019

Pipeline building is performed almost completely automagically.

1020

Of course, this does not mean it can fit a square into a circle, so some

1021

consideration for compatibility and negotiation is still in order.

1022

</li><li>

1023

queues are inserted where needed and/or useful,

1024

either by decodebin or by entrans

1025

</li><li>

1026

Whenever available (recommended), <a class="ulink" href="../../gst-entrans-plugins/html/gst-entrans-plugins-dam.html" target="_top">dam</a> is used and inserted in proper locations.

1027

</li></ul></div>

1028

</div><div class="refsect1" lang="en" xml:lang="en"><a id="id528790"></a><h2>See Also</h2>

1029

<a class="ulink" href="http://www.gstreamer.net/" target="_top"><a class="ulink" href="http://www.gstreamer.net/" target="_top">GStreamer</a> homepage</a>,

1030

gst-launch(1),

1031

<a class="ulink" href="http://gentrans.sourceforge.net/" target="_top">entrans plugins</a>

1032

</div><div class="refsect1" lang="en" xml:lang="en"><a id="id528832"></a><h2>Author</h2>

1033

Mark Nauwelaerts <code class="email"><<a class="email" href="mailto:mnauw@users.sourceforge.net">mnauw@users.sourceforge.net</a>></code>

1034

</div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="package.html"><< Previous</a> </td><td width="20%" align="center"><a accesskey="u" href="package.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. Package Documentation </td><td width="20%" align="center"><a accesskey="h" href="index.html">Table of Contents</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div><div class="footer-homepage"><table width="100%"><tr><td width="40%" align="left">Last created:

1035

2010-03-03 22:13:23+01:00</td><td width="20%" align="center"><a href="http://gentrans.sourceforge.net/" title="GEntrans: Home page">GEntrans home page</a></td><td width="40%" align="right"></td></tr></table></div></body></html>

Older »