lavdevice: Add AudioToolbox output device.
[ffmpeg.git] / doc / outdevs.texi
1 @chapter Output Devices
2 @c man begin OUTPUT DEVICES
3
4 Output devices are configured elements in FFmpeg that can write
5 multimedia data to an output device attached to your system.
6
7 When you configure your FFmpeg build, all the supported output devices
8 are enabled by default. You can list all available ones using the
9 configure option "--list-outdevs".
10
11 You can disable all the output devices using the configure option
12 "--disable-outdevs", and selectively enable an output device using the
13 option "--enable-outdev=@var{OUTDEV}", or you can disable a particular
14 input device using the option "--disable-outdev=@var{OUTDEV}".
15
16 The option "-devices" of the ff* tools will display the list of
17 enabled output devices.
18
19 A description of the currently available output devices follows.
20
21 @section alsa
22
23 ALSA (Advanced Linux Sound Architecture) output device.
24
25 @subsection Examples
26
27 @itemize
28 @item
29 Play a file on default ALSA device:
30 @example
31 ffmpeg -i INPUT -f alsa default
32 @end example
33
34 @item
35 Play a file on soundcard 1, audio device 7:
36 @example
37 ffmpeg -i INPUT -f alsa hw:1,7
38 @end example
39 @end itemize
40
41 @section AudioToolbox
42
43 AudioToolbox output device.
44
45 Allows native output to CoreAudio devices on OSX.
46
47 The output filename can be empty (or @code{-}) to refer to the default system output device or a number that refers to the device index as shown using: @code{-list_devices true}.
48
49 Alternatively, the audio input device can be chosen by index using the
50 @option{
51     -audio_device_index <INDEX>
52 }
53 , overriding any device name or index given in the input filename.
54
55 All available devices can be enumerated by using @option{-list_devices true}, listing
56 all device names, UIDs and corresponding indices.
57
58 @subsection Options
59
60 AudioToolbox supports the following options:
61
62 @table @option
63
64 @item -audio_device_index <INDEX>
65 Specify the audio device by its index. Overrides anything given in the output filename.
66
67 @end table
68
69 @subsection Examples
70
71 @itemize
72
73 @item
74 Print the list of supported devices and output a sine wave to the default device:
75 @example
76 $ ffmpeg -f lavfi -i sine=r=44100 -f audiotoolbox -list_devices true -
77 @end example
78
79 @item
80 Output a sine wave to the device with the index 2, overriding any output filename:
81 @example
82 $ ffmpeg -f lavfi -i sine=r=44100 -f audiotoolbox -audio_device_index 2 -
83 @end example
84
85 @end itemize
86
87 @section caca
88
89 CACA output device.
90
91 This output device allows one to show a video stream in CACA window.
92 Only one CACA window is allowed per application, so you can
93 have only one instance of this output device in an application.
94
95 To enable this output device you need to configure FFmpeg with
96 @code{--enable-libcaca}.
97 libcaca is a graphics library that outputs text instead of pixels.
98
99 For more information about libcaca, check:
100 @url{http://caca.zoy.org/wiki/libcaca}
101
102 @subsection Options
103
104 @table @option
105
106 @item window_title
107 Set the CACA window title, if not specified default to the filename
108 specified for the output device.
109
110 @item window_size
111 Set the CACA window size, can be a string of the form
112 @var{width}x@var{height} or a video size abbreviation.
113 If not specified it defaults to the size of the input video.
114
115 @item driver
116 Set display driver.
117
118 @item algorithm
119 Set dithering algorithm. Dithering is necessary
120 because the picture being rendered has usually far more colours than
121 the available palette.
122 The accepted values are listed with @code{-list_dither algorithms}.
123
124 @item antialias
125 Set antialias method. Antialiasing smoothens the rendered
126 image and avoids the commonly seen staircase effect.
127 The accepted values are listed with @code{-list_dither antialiases}.
128
129 @item charset
130 Set which characters are going to be used when rendering text.
131 The accepted values are listed with @code{-list_dither charsets}.
132
133 @item color
134 Set color to be used when rendering text.
135 The accepted values are listed with @code{-list_dither colors}.
136
137 @item list_drivers
138 If set to @option{true}, print a list of available drivers and exit.
139
140 @item list_dither
141 List available dither options related to the argument.
142 The argument must be one of @code{algorithms}, @code{antialiases},
143 @code{charsets}, @code{colors}.
144 @end table
145
146 @subsection Examples
147
148 @itemize
149 @item
150 The following command shows the @command{ffmpeg} output is an
151 CACA window, forcing its size to 80x25:
152 @example
153 ffmpeg -i INPUT -c:v rawvideo -pix_fmt rgb24 -window_size 80x25 -f caca -
154 @end example
155
156 @item
157 Show the list of available drivers and exit:
158 @example
159 ffmpeg -i INPUT -pix_fmt rgb24 -f caca -list_drivers true -
160 @end example
161
162 @item
163 Show the list of available dither colors and exit:
164 @example
165 ffmpeg -i INPUT -pix_fmt rgb24 -f caca -list_dither colors -
166 @end example
167 @end itemize
168
169 @section decklink
170
171 The decklink output device provides playback capabilities for Blackmagic
172 DeckLink devices.
173
174 To enable this output device, you need the Blackmagic DeckLink SDK and you
175 need to configure with the appropriate @code{--extra-cflags}
176 and @code{--extra-ldflags}.
177 On Windows, you need to run the IDL files through @command{widl}.
178
179 DeckLink is very picky about the formats it supports. Pixel format is always
180 uyvy422, framerate, field order and video size must be determined for your
181 device with @command{-list_formats 1}. Audio sample rate is always 48 kHz.
182
183 @subsection Options
184
185 @table @option
186
187 @item list_devices
188 If set to @option{true}, print a list of devices and exit.
189 Defaults to @option{false}. This option is deprecated, please use the
190 @code{-sinks} option of ffmpeg to list the available output devices.
191
192 @item list_formats
193 If set to @option{true}, print a list of supported formats and exit.
194 Defaults to @option{false}.
195
196 @item preroll
197 Amount of time to preroll video in seconds.
198 Defaults to @option{0.5}.
199
200 @item duplex_mode
201 Sets the decklink device duplex mode. Must be @samp{unset}, @samp{half} or @samp{full}.
202 Defaults to @samp{unset}.
203
204 @item timing_offset
205 Sets the genlock timing pixel offset on the used output.
206 Defaults to @samp{unset}.
207
208 @end table
209
210 @subsection Examples
211
212 @itemize
213
214 @item
215 List output devices:
216 @example
217 ffmpeg -sinks decklink
218 @end example
219
220 @item
221 List supported formats:
222 @example
223 ffmpeg -i test.avi -f decklink -list_formats 1 'DeckLink Mini Monitor'
224 @end example
225
226 @item
227 Play video clip:
228 @example
229 ffmpeg -i test.avi -f decklink -pix_fmt uyvy422 'DeckLink Mini Monitor'
230 @end example
231
232 @item
233 Play video clip with non-standard framerate or video size:
234 @example
235 ffmpeg -i test.avi -f decklink -pix_fmt uyvy422 -s 720x486 -r 24000/1001 'DeckLink Mini Monitor'
236 @end example
237
238 @end itemize
239
240 @section fbdev
241
242 Linux framebuffer output device.
243
244 The Linux framebuffer is a graphic hardware-independent abstraction
245 layer to show graphics on a computer monitor, typically on the
246 console. It is accessed through a file device node, usually
247 @file{/dev/fb0}.
248
249 For more detailed information read the file
250 @file{Documentation/fb/framebuffer.txt} included in the Linux source tree.
251
252 @subsection Options
253 @table @option
254
255 @item xoffset
256 @item yoffset
257 Set x/y coordinate of top left corner. Default is 0.
258 @end table
259
260 @subsection Examples
261 Play a file on framebuffer device @file{/dev/fb0}.
262 Required pixel format depends on current framebuffer settings.
263 @example
264 ffmpeg -re -i INPUT -c:v rawvideo -pix_fmt bgra -f fbdev /dev/fb0
265 @end example
266
267 See also @url{http://linux-fbdev.sourceforge.net/}, and fbset(1).
268
269 @section opengl
270 OpenGL output device.
271
272 To enable this output device you need to configure FFmpeg with @code{--enable-opengl}.
273
274 This output device allows one to render to OpenGL context.
275 Context may be provided by application or default SDL window is created.
276
277 When device renders to external context, application must implement handlers for following messages:
278 @code{AV_DEV_TO_APP_CREATE_WINDOW_BUFFER} - create OpenGL context on current thread.
279 @code{AV_DEV_TO_APP_PREPARE_WINDOW_BUFFER} - make OpenGL context current.
280 @code{AV_DEV_TO_APP_DISPLAY_WINDOW_BUFFER} - swap buffers.
281 @code{AV_DEV_TO_APP_DESTROY_WINDOW_BUFFER} - destroy OpenGL context.
282 Application is also required to inform a device about current resolution by sending @code{AV_APP_TO_DEV_WINDOW_SIZE} message.
283
284 @subsection Options
285 @table @option
286
287 @item background
288 Set background color. Black is a default.
289 @item no_window
290 Disables default SDL window when set to non-zero value.
291 Application must provide OpenGL context and both @code{window_size_cb} and @code{window_swap_buffers_cb} callbacks when set.
292 @item window_title
293 Set the SDL window title, if not specified default to the filename specified for the output device.
294 Ignored when @option{no_window} is set.
295 @item window_size
296 Set preferred window size, can be a string of the form widthxheight or a video size abbreviation.
297 If not specified it defaults to the size of the input video, downscaled according to the aspect ratio.
298 Mostly usable when @option{no_window} is not set.
299
300 @end table
301
302 @subsection Examples
303 Play a file on SDL window using OpenGL rendering:
304 @example
305 ffmpeg  -i INPUT -f opengl "window title"
306 @end example
307
308 @section oss
309
310 OSS (Open Sound System) output device.
311
312 @section pulse
313
314 PulseAudio output device.
315
316 To enable this output device you need to configure FFmpeg with @code{--enable-libpulse}.
317
318 More information about PulseAudio can be found on @url{http://www.pulseaudio.org}
319
320 @subsection Options
321 @table @option
322
323 @item server
324 Connect to a specific PulseAudio server, specified by an IP address.
325 Default server is used when not provided.
326
327 @item name
328 Specify the application name PulseAudio will use when showing active clients,
329 by default it is the @code{LIBAVFORMAT_IDENT} string.
330
331 @item stream_name
332 Specify the stream name PulseAudio will use when showing active streams,
333 by default it is set to the specified output name.
334
335 @item device
336 Specify the device to use. Default device is used when not provided.
337 List of output devices can be obtained with command @command{pactl list sinks}.
338
339 @item buffer_size
340 @item buffer_duration
341 Control the size and duration of the PulseAudio buffer. A small buffer
342 gives more control, but requires more frequent updates.
343
344 @option{buffer_size} specifies size in bytes while
345 @option{buffer_duration} specifies duration in milliseconds.
346
347 When both options are provided then the highest value is used
348 (duration is recalculated to bytes using stream parameters). If they
349 are set to 0 (which is default), the device will use the default
350 PulseAudio duration value. By default PulseAudio set buffer duration
351 to around 2 seconds.
352
353 @item prebuf
354 Specify pre-buffering size in bytes. The server does not start with
355 playback before at least @option{prebuf} bytes are available in the
356 buffer. By default this option is initialized to the same value as
357 @option{buffer_size} or @option{buffer_duration} (whichever is bigger).
358
359 @item minreq
360 Specify minimum request size in bytes. The server does not request less
361 than @option{minreq} bytes from the client, instead waits until the buffer
362 is free enough to request more bytes at once. It is recommended to not set
363 this option, which will initialize this to a value that is deemed sensible
364 by the server.
365
366 @end table
367
368 @subsection Examples
369 Play a file on default device on default server:
370 @example
371 ffmpeg  -i INPUT -f pulse "stream name"
372 @end example
373
374 @section sdl
375
376 SDL (Simple DirectMedia Layer) output device.
377
378 "sdl2" can be used as alias for "sdl".
379
380 This output device allows one to show a video stream in an SDL
381 window. Only one SDL window is allowed per application, so you can
382 have only one instance of this output device in an application.
383
384 To enable this output device you need libsdl installed on your system
385 when configuring your build.
386
387 For more information about SDL, check:
388 @url{http://www.libsdl.org/}
389
390 @subsection Options
391
392 @table @option
393
394 @item window_title
395 Set the SDL window title, if not specified default to the filename
396 specified for the output device.
397
398 @item icon_title
399 Set the name of the iconified SDL window, if not specified it is set
400 to the same value of @var{window_title}.
401
402 @item window_size
403 Set the SDL window size, can be a string of the form
404 @var{width}x@var{height} or a video size abbreviation.
405 If not specified it defaults to the size of the input video,
406 downscaled according to the aspect ratio.
407
408 @item window_x
409 @item window_y
410 Set the position of the window on the screen.
411
412 @item window_fullscreen
413 Set fullscreen mode when non-zero value is provided.
414 Default value is zero.
415
416 @item window_enable_quit
417 Enable quit action (using window button or keyboard key)
418 when non-zero value is provided.
419 Default value is 1 (enable quit action)
420 @end table
421
422 @subsection Interactive commands
423
424 The window created by the device can be controlled through the
425 following interactive commands.
426
427 @table @key
428 @item q, ESC
429 Quit the device immediately.
430 @end table
431
432 @subsection Examples
433
434 The following command shows the @command{ffmpeg} output is an
435 SDL window, forcing its size to the qcif format:
436 @example
437 ffmpeg -i INPUT -c:v rawvideo -pix_fmt yuv420p -window_size qcif -f sdl "SDL output"
438 @end example
439
440 @section sndio
441
442 sndio audio output device.
443
444 @section v4l2
445
446 Video4Linux2 output device.
447
448 @section xv
449
450 XV (XVideo) output device.
451
452 This output device allows one to show a video stream in a X Window System
453 window.
454
455 @subsection Options
456
457 @table @option
458 @item display_name
459 Specify the hardware display name, which determines the display and
460 communications domain to be used.
461
462 The display name or DISPLAY environment variable can be a string in
463 the format @var{hostname}[:@var{number}[.@var{screen_number}]].
464
465 @var{hostname} specifies the name of the host machine on which the
466 display is physically attached. @var{number} specifies the number of
467 the display server on that host machine. @var{screen_number} specifies
468 the screen to be used on that server.
469
470 If unspecified, it defaults to the value of the DISPLAY environment
471 variable.
472
473 For example, @code{dual-headed:0.1} would specify screen 1 of display
474 0 on the machine named ``dual-headed''.
475
476 Check the X11 specification for more detailed information about the
477 display name format.
478
479 @item window_id
480 When set to non-zero value then device doesn't create new window,
481 but uses existing one with provided @var{window_id}. By default
482 this options is set to zero and device creates its own window.
483
484 @item window_size
485 Set the created window size, can be a string of the form
486 @var{width}x@var{height} or a video size abbreviation. If not
487 specified it defaults to the size of the input video.
488 Ignored when @var{window_id} is set.
489
490 @item window_x
491 @item window_y
492 Set the X and Y window offsets for the created window. They are both
493 set to 0 by default. The values may be ignored by the window manager.
494 Ignored when @var{window_id} is set.
495
496 @item window_title
497 Set the window title, if not specified default to the filename
498 specified for the output device. Ignored when @var{window_id} is set.
499 @end table
500
501 For more information about XVideo see @url{http://www.x.org/}.
502
503 @subsection Examples
504
505 @itemize
506 @item
507 Decode, display and encode video input with @command{ffmpeg} at the
508 same time:
509 @example
510 ffmpeg -i INPUT OUTPUT -f xv display
511 @end example
512
513 @item
514 Decode and display the input video to multiple X11 windows:
515 @example
516 ffmpeg -i INPUT -f xv normal -vf negate -f xv negated
517 @end example
518 @end itemize
519
520 @c man end OUTPUT DEVICES