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