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