~ubuntu-branches/ubuntu/saucy/gst-libav1.0/saucy-proposed : revision 19

gst-libs/ext/libav/doc/filters.texi

A filter with no input pads is called a "source", a filter with no

output pads is called a "sink".

@anchor{Filtergraph syntax}

@section Filtergraph syntax

A filtergraph can be represented using a textual representation, which

is recognized by the @code{-vf} and @code{-af} options in @command{avconv}

and @command{avplay}, and by the @code{av_parse_graph()} function defined in

@file{libavfilter/avfiltergraph}.

A filtergraph can be represented using a textual representation, which is

recognized by the @option{-filter}/@option{-vf} and @option{-filter_complex}

options in @command{avconv} and @option{-vf} in @command{avplay}, and by the

@code{avfilter_graph_parse()}/@code{avfilter_graph_parse2()} function defined in

@file{libavfilter/avfiltergraph.h}.

A filterchain consists of a sequence of connected filters, each one

connected to the previous one in the sequence. A filterchain is

pads must be connected. A filtergraph is considered valid if all the

filter input and output pads of all the filterchains are connected.

Libavfilter will automatically insert scale filters where format

conversion is required. It is possible to specify swscale flags

for those automatically inserted scalers by prepending

@code{sws_flags=@var{flags};}

to the filtergraph description.

Follows a BNF description for the filtergraph syntax:

@example

@var{NAME} ::= sequence of alphanumeric characters and '_'

@var{FILTER_ARGUMENTS} ::= sequence of chars (eventually quoted)

@var{FILTER} ::= [@var{LINKLABELS}] @var{NAME} ["=" @var{FILTER_ARGUMENTS}] [@var{LINKLABELS}]

@var{FILTERCHAIN} ::= @var{FILTER} [,@var{FILTERCHAIN}]

@var{FILTERGRAPH} ::= @var{FILTERCHAIN} [;@var{FILTERGRAPH}]

@var{FILTERGRAPH} ::= [sws_flags=@var{flags};] @var{FILTERCHAIN} [;@var{FILTERGRAPH}]

@end example

@c man end FILTERGRAPH DESCRIPTION

107

100

108

Below is a description of the currently available audio filters.

101

109

110

@section aformat

111

112

Convert the input audio to one of the specified formats. The framework will

113

negotiate the most appropriate format to minimize conversions.

114

115

The filter accepts the following named parameters:

116

@table @option

117

118

@item sample_fmts

119

A comma-separated list of requested sample formats.

120

121

@item sample_rates

122

A comma-separated list of requested sample rates.

123

124

@item channel_layouts

125

A comma-separated list of requested channel layouts.

126

127

@end table

128

129

If a parameter is omitted, all values are allowed.

130

131

For example to force the output to either unsigned 8-bit or signed 16-bit stereo:

132

@example

133

aformat=sample_fmts\=u8\,s16:channel_layouts\=stereo

134

@end example

135

136

@section amix

137

138

Mixes multiple audio inputs into a single output.

139

140

For example

141

@example

142

avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex amix=inputs=3:duration=first:dropout_transition=3 OUTPUT

143

@end example

144

will mix 3 input audio streams to a single output with the same duration as the

145

first input and a dropout transition time of 3 seconds.

146

147

The filter accepts the following named parameters:

148

@table @option

149

150

@item inputs

151

Number of inputs. If unspecified, it defaults to 2.

152

153

@item duration

154

How to determine the end-of-stream.

155

@table @option

156

157

@item longest

158

Duration of longest input. (default)

159

160

@item shortest

161

Duration of shortest input.

162

163

@item first

164

Duration of first input.

165

166

@end table

167

168

@item dropout_transition

169

Transition time, in seconds, for volume renormalization when an input

170

stream ends. The default value is 2 seconds.

171

172

@end table

173

102

174

@section anull

103

175

104

176

Pass the audio source unchanged to the output.

105

177

178

@section ashowinfo

179

180

Show a line containing various information for each input audio frame.

181

The input audio is not modified.

182

183

The shown line contains a sequence of key/value pairs of the form

184

@var{key}:@var{value}.

185

186

A description of each shown parameter follows:

187

188

@table @option

189

@item n

190

sequential number of the input frame, starting from 0

191

192

@item pts

193

Presentation timestamp of the input frame, in time base units; the time base

194

depends on the filter input pad, and is usually 1/@var{sample_rate}.

195

196

@item pts_time

197

presentation timestamp of the input frame in seconds

198

199

@item fmt

200

sample format

201

202

@item chlayout

203

channel layout

204

205

@item rate

206

sample rate for the audio frame

207

208

@item nb_samples

209

number of samples (per channel) in the frame

210

211

@item checksum

212

Adler-32 checksum (printed in hexadecimal) of the audio data. For planar audio

213

the data is treated as if all the planes were concatenated.

214

215

@item plane_checksums

216

A list of Adler-32 checksums for each data plane.

217

@end table

218

219

@section asplit

220

221

Split input audio into several identical outputs.

222

223

The filter accepts a single parameter which specifies the number of outputs. If

224

unspecified, it defaults to 2.

225

226

For example

227

@example

228

avconv -i INPUT -filter_complex asplit=5 OUTPUT

229

@end example

230

will create 5 copies of the input audio.

231

232

@section asyncts

233

Synchronize audio data with timestamps by squeezing/stretching it and/or

234

dropping samples/adding silence when needed.

235

236

The filter accepts the following named parameters:

237

@table @option

238

239

@item compensate

240

Enable stretching/squeezing the data to make it match the timestamps. Disabled

241

by default. When disabled, time gaps are covered with silence.

242

243

@item min_delta

244

Minimum difference between timestamps and audio data (in seconds) to trigger

245

adding/dropping samples. Default value is 0.1. If you get non-perfect sync with

246

this filter, try setting this parameter to 0.

247

248

@item max_comp

249

Maximum compensation in samples per second. Relevant only with compensate=1.

250

Default value 500.

251

252

@item first_pts

253

Assume the first pts should be this value. The time base is 1 / sample rate.

254

This allows for padding/trimming at the start of stream. By default, no

255

assumption is made about the first frame's expected pts, so no padding or

256

trimming is done. For example, this could be set to 0 to pad the beginning with

257

silence if an audio stream starts after the video stream or to trim any samples

258

with a negative pts due to encoder delay.

259

260

@end table

261

262

@section channelsplit

263

Split each channel in input audio stream into a separate output stream.

264

265

This filter accepts the following named parameters:

266

@table @option

267

@item channel_layout

268

Channel layout of the input stream. Default is "stereo".

269

@end table

270

271

For example, assuming a stereo input MP3 file

272

@example

273

avconv -i in.mp3 -filter_complex channelsplit out.mkv

274

@end example

275

will create an output Matroska file with two audio streams, one containing only

276

the left channel and the other the right channel.

277

278

To split a 5.1 WAV file into per-channel files

279

@example

280

avconv -i in.wav -filter_complex

281

'channelsplit=channel_layout=5.1[FL][FR][FC][LFE][SL][SR]'

282

-map '[FL]' front_left.wav -map '[FR]' front_right.wav -map '[FC]'

283

front_center.wav -map '[LFE]' lfe.wav -map '[SL]' side_left.wav -map '[SR]'

284

side_right.wav

285

@end example

286

287

@section channelmap

288

Remap input channels to new locations.

289

290

This filter accepts the following named parameters:

291

@table @option

292

@item channel_layout

293

Channel layout of the output stream.

294

295

@item map

296

Map channels from input to output. The argument is a comma-separated list of

297

mappings, each in the @code{@var{in_channel}-@var{out_channel}} or

298

@var{in_channel} form. @var{in_channel} can be either the name of the input

299

channel (e.g. FL for front left) or its index in the input channel layout.

300

@var{out_channel} is the name of the output channel or its index in the output

301

channel layout. If @var{out_channel} is not given then it is implicitly an

302

index, starting with zero and increasing by one for each mapping.

303

@end table

304

305

If no mapping is present, the filter will implicitly map input channels to

306

output channels preserving index.

307

308

For example, assuming a 5.1+downmix input MOV file

309

@example

310

avconv -i in.mov -filter 'channelmap=map=DL-FL\,DR-FR' out.wav

311

@end example

312

will create an output WAV file tagged as stereo from the downmix channels of

313

the input.

314

315

To fix a 5.1 WAV improperly encoded in AAC's native channel order

316

@example

317

avconv -i in.wav -filter 'channelmap=1\,2\,0\,5\,3\,4:channel_layout=5.1' out.wav

318

@end example

319

320

@section join

321

Join multiple input streams into one multi-channel stream.

322

323

The filter accepts the following named parameters:

324

@table @option

325

326

@item inputs

327

Number of input streams. Defaults to 2.

328

329

@item channel_layout

330

Desired output channel layout. Defaults to stereo.

331

332

@item map

333

Map channels from inputs to output. The argument is a comma-separated list of

334

mappings, each in the @code{@var{input_idx}.@var{in_channel}-@var{out_channel}}

335

form. @var{input_idx} is the 0-based index of the input stream. @var{in_channel}

336

can be either the name of the input channel (e.g. FL for front left) or its

337

index in the specified input stream. @var{out_channel} is the name of the output

338

channel.

339

@end table

340

341

The filter will attempt to guess the mappings when those are not specified

342

explicitly. It does so by first trying to find an unused matching input channel

343

and if that fails it picks the first unused input channel.

344

345

E.g. to join 3 inputs (with properly set channel layouts)

346

@example

347

avconv -i INPUT1 -i INPUT2 -i INPUT3 -filter_complex join=inputs=3 OUTPUT

348

@end example

349

350

To build a 5.1 output from 6 single-channel streams:

351

@example

352

avconv -i fl -i fr -i fc -i sl -i sr -i lfe -filter_complex

353

'join=inputs=6:channel_layout=5.1:map=0.0-FL\,1.0-FR\,2.0-FC\,3.0-SL\,4.0-SR\,5.0-LFE'

354

out

355

@end example

356

357

@section resample

358

Convert the audio sample format, sample rate and channel layout. This filter is

359

not meant to be used directly, it is inserted automatically by libavfilter

360

whenever conversion is needed. Use the @var{aformat} filter to force a specific

361

conversion.

362

363

@section volume

364

365

Adjust the input audio volume.

366

367

The filter accepts the following named parameters:

368

@table @option

369

370

@item volume

371

Expresses how the audio volume will be increased or decreased.

372

373

Output values are clipped to the maximum value.

374

375

The output audio volume is given by the relation:

376

@example

377

@var{output_volume} = @var{volume} * @var{input_volume}

378

@end example

379

380

Default value for @var{volume} is 1.0.

381

382

@item precision

383

Mathematical precision.

384

385

This determines which input sample formats will be allowed, which affects the

386

precision of the volume scaling.

387

388

@table @option

389

@item fixed

390

8-bit fixed-point; limits input sample format to U8, S16, and S32.

391

@item float

392

32-bit floating-point; limits input sample format to FLT. (default)

393

@item double

394

64-bit floating-point; limits input sample format to DBL.

395

@end table

396

@end table

397

398

@subsection Examples

399

400

@itemize

401

@item

402

Halve the input audio volume:

403

@example

404

volume=volume=0.5

405

volume=volume=1/2

406

volume=volume=-6.0206dB

407

@end example

408

409

@item

410

Increase input audio power by 6 decibels using fixed-point precision:

411

@example

412

volume=volume=6dB:precision=fixed

413

@end example

414

@end itemize

415

106

416

@c man end AUDIO FILTERS

107

417

108

418

@chapter Audio Sources

125

435

of @var{channel_layout} is 3, which corresponds to CH_LAYOUT_STEREO.

126

436

127

437

Check the channel_layout_map definition in

128

@file{libavcodec/audioconvert.c} for the mapping between strings and

438

@file{libavutil/channel_layout.c} for the mapping between strings and

129

439

channel layout values.

130

440

131

441

Follow some examples:

137

447

anullsrc=48000:mono

138

448

@end example

139

449

450

@section abuffer

451

Buffer audio frames, and make them available to the filter chain.

452

453

This source is not intended to be part of user-supplied graph descriptions but

454

for insertion by calling programs through the interface defined in

455

@file{libavfilter/buffersrc.h}.

456

457

It accepts the following named parameters:

458

@table @option

459

460

@item time_base

461

Timebase which will be used for timestamps of submitted frames. It must be

462

either a floating-point number or in @var{numerator}/@var{denominator} form.

463

464

@item sample_rate

465

Audio sample rate.

466

467

@item sample_fmt

468

Name of the sample format, as returned by @code{av_get_sample_fmt_name()}.

469

470

@item channel_layout

471

Channel layout of the audio data, in the form that can be accepted by

472

@code{av_get_channel_layout()}.

473

@end table

474

475

All the parameters need to be explicitly defined.

476

140

477

@c man end AUDIO SOURCES

141

478

142

479

@chapter Audio Sinks

150

487

mainly useful as a template and to be employed in analysis / debugging

151

488

tools.

152

489

490

@section abuffersink

491

This sink is intended for programmatic use. Frames that arrive on this sink can

492

be retrieved by the calling program using the interface defined in

493

@file{libavfilter/buffersink.h}.

494

495

This filter accepts no parameters.

496

153

497

@c man end AUDIO SINKS

154

498

155

499

@chapter Video Filters

598

942

@item tabsize

599

943

The size in number of spaces to use for rendering the tab.

600

944

Default value is 4.

945

946

@item fix_bounds

947

If true, check and fix text coords to avoid clipping.

601

948

@end table

602

949

603

950

For example the command:

718

1065

format=yuv420p:yuv444p:yuv410p

719

1066

@end example

720

1067

1068

@section fps

1069

1070

Convert the video to specified constant framerate by duplicating or dropping

1071

frames as necessary.

1072

1073

This filter accepts the following named parameters:

1074

@table @option

1075

1076

@item fps

1077

Desired output framerate.

1078

1079

@end table

1080

721

1081

@anchor{frei0r}

722

1082

@section frei0r

723

1083

853

1213

The @var{lut} filter requires either YUV or RGB pixel formats in

854

1214

input, and accepts the options:

855

1215

@table @option

856

@var{c0} (first pixel component)

857

@var{c1} (second pixel component)

858

@var{c2} (third pixel component)

859

@var{c3} (fourth pixel component, corresponds to the alpha component)

1216

@item @var{c0} (first pixel component)

1217

@item @var{c1} (second pixel component)

1218

@item @var{c2} (third pixel component)

1219

@item @var{c3} (fourth pixel component, corresponds to the alpha component)

860

1220

@end table

861

1221

862

1222

The exact component associated to each option depends on the format in

865

1225

The @var{lutrgb} filter requires RGB pixel formats in input, and

866

1226

accepts the options:

867

1227

@table @option

868

@var{r} (red component)

869

@var{g} (green component)

870

@var{b} (blue component)

871

@var{a} (alpha component)

1228

@item @var{r} (red component)

1229

@item @var{g} (green component)

1230

@item @var{b} (blue component)

1231

@item @var{a} (alpha component)

872

1232

@end table

873

1233

874

1234

The @var{lutyuv} filter requires YUV pixel formats in input, and

875

1235

accepts the options:

876

1236

@table @option

877

@var{y} (Y/luminance component)

878

@var{u} (U/Cb component)

879

@var{v} (V/Cr component)

880

@var{a} (alpha component)

1237

@item @var{y} (Y/luminance component)

1238

@item @var{u} (U/Cb component)

1239

@item @var{v} (V/Cr component)

1240

@item @var{a} (alpha component)

881

1241

@end table

882

1242

883

1243

The expressions can contain the following constants and functions:

1115

1475

overlay=main_w-overlay_w-10:main_h-overlay_h-10

1116

1476

1117

1477

# insert a transparent PNG logo in the bottom left corner of the input

1118

movie=logo.png [logo];

1119

[in][logo] overlay=10:main_h-overlay_h-10 [out]

1478

avconv -i input -i logo -filter_complex 'overlay=10:main_h-overlay_h-10' output

1120

1479

1121

1480

# insert 2 different transparent PNG logos (second logo on bottom

1122

1481

# right corner):

1123

movie=logo1.png [logo1];

1124

movie=logo2.png [logo2];

1125

[in][logo1] overlay=10:H-h-10 [in+logo1];

1126

[in+logo1][logo2] overlay=W-w-10:H-h-10 [out]

1482

avconv -i input -i logo1 -i logo2 -filter_complex

1483

'overlay=10:H-h-10,overlay=W-w-10:H-h-10' output

1127

1484

1128

1485

# add a transparent color layer on top of the main video,

1129

1486

# WxH specifies the size of the main input to the overlay filter

1643

2000

"[@var{c0} @var{c1} @var{c2} @var{c3}]"

1644

2001

@end table

1645

2002

1646

@section slicify

1647

1648

Pass the images of input video on to next video filter as multiple

1649

slices.

1650

2003

@section split

2004

2005

Split input video into several identical outputs.

2006

2007

The filter accepts a single parameter which specifies the number of outputs. If

2008

unspecified, it defaults to 2.

2009

2010

For example

1651

2011

@example

1652

./avconv -i in.avi -vf "slicify=32" out.avi

2012

avconv -i INPUT -filter_complex split=5 OUTPUT

1653

2013

@end example

1654

1655

The filter accepts the slice height as parameter. If the parameter is

1656

not specified it will use the default value of 16.

1657

1658

Adding this in the beginning of filter chains should make filtering

1659

faster due to better use of the memory cache.

2014

will create 5 copies of the input video.

1660

2015

1661

2016

@section transpose

1662

2017

1857

2212

with format "yuv410p", assuming 1/24 as the timestamps timebase and

1858

2213

square pixels (1:1 sample aspect ratio).

1859

2214

Since the pixel format with name "yuv410p" corresponds to the number 6

1860

(check the enum PixelFormat definition in @file{libavutil/pixfmt.h}),

2215

(check the enum AVPixelFormat definition in @file{libavutil/pixfmt.h}),

1861

2216

this example corresponds to:

1862

2217

@example

1863

2218

buffer=320:240:6:1:24

1906

2261

1907

2262

Read a video stream from a movie container.

1908

2263

2264

Note that this source is a hack that bypasses the standard input path. It can be

2265

useful in applications that do not support arbitrary filter graphs, but its use

2266

is discouraged in those that do. Specifically in @command{avconv} this filter

2267

should never be used, the @option{-filter_complex} option fully replaces it.

2268

1909

2269

It accepts the syntax: @var{movie_name}[:@var{options}] where

1910

2270

@var{movie_name} is the name of the resource to read (not necessarily

1911

2271

a file but also a device or a stream accessed through some protocol),

2057

2417

2058

2418

Below is a description of the currently available video sinks.

2059

2419

2420

@section buffersink

2421

2422

Buffer video frames, and make them available to the end of the filter

2423

graph.

2424

2425

This sink is intended for a programmatic use through the interface defined in

2426

@file{libavfilter/buffersink.h}.

2427

2060

2428

@section nullsink

2061

2429

2062

2430

Null video sink, do absolutely nothing with the input video. It is

2064

2432

tools.

2065

2433

2066

2434

@c man end VIDEO SINKS

2067

Older »