FFmpeg
avdevice.h
Go to the documentation of this file.
1 /*
2  * This file is part of FFmpeg.
3  *
4  * FFmpeg is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU Lesser General Public
6  * License as published by the Free Software Foundation; either
7  * version 2.1 of the License, or (at your option) any later version.
8  *
9  * FFmpeg is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  * Lesser General Public License for more details.
13  *
14  * You should have received a copy of the GNU Lesser General Public
15  * License along with FFmpeg; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17  */
18 
19 #ifndef AVDEVICE_AVDEVICE_H
20 #define AVDEVICE_AVDEVICE_H
21 
22 #include "version_major.h"
23 #ifndef HAVE_AV_CONFIG_H
24 /* When included as part of the ffmpeg build, only include the major version
25  * to avoid unnecessary rebuilds. When included externally, keep including
26  * the full version information. */
27 #include "version.h"
28 #endif
29 
30 /**
31  * @file
32  * @ingroup lavd
33  * Main libavdevice API header
34  */
35 
36 /**
37  * @defgroup lavd libavdevice
38  * Special devices muxing/demuxing library.
39  *
40  * Libavdevice is a complementary library to @ref libavf "libavformat". It
41  * provides various "special" platform-specific muxers and demuxers, e.g. for
42  * grabbing devices, audio capture and playback etc. As a consequence, the
43  * (de)muxers in libavdevice are of the AVFMT_NOFILE type (they use their own
44  * I/O functions). The filename passed to avformat_open_input() often does not
45  * refer to an actually existing file, but has some special device-specific
46  * meaning - e.g. for xcbgrab it is the display name.
47  *
48  * To use libavdevice, simply call avdevice_register_all() to register all
49  * compiled muxers and demuxers. They all use standard libavformat API.
50  *
51  * @{
52  */
53 
54 #include "libavutil/log.h"
55 #include "libavutil/opt.h"
56 #include "libavutil/dict.h"
57 #include "libavformat/avformat.h"
58 
59 /**
60  * Return the LIBAVDEVICE_VERSION_INT constant.
61  */
62 unsigned avdevice_version(void);
63 
64 /**
65  * Return the libavdevice build-time configuration.
66  */
67 const char *avdevice_configuration(void);
68 
69 /**
70  * Return the libavdevice license.
71  */
72 const char *avdevice_license(void);
73 
74 /**
75  * Initialize libavdevice and register all the input and output devices.
76  */
77 void avdevice_register_all(void);
78 
79 /**
80  * Audio input devices iterator.
81  *
82  * If d is NULL, returns the first registered input audio/video device,
83  * if d is non-NULL, returns the next registered input audio/video device after d
84  * or NULL if d is the last one.
85  */
87 
88 /**
89  * Video input devices iterator.
90  *
91  * If d is NULL, returns the first registered input audio/video device,
92  * if d is non-NULL, returns the next registered input audio/video device after d
93  * or NULL if d is the last one.
94  */
96 
97 /**
98  * Audio output devices iterator.
99  *
100  * If d is NULL, returns the first registered output audio/video device,
101  * if d is non-NULL, returns the next registered output audio/video device after d
102  * or NULL if d is the last one.
103  */
105 
106 /**
107  * Video output devices iterator.
108  *
109  * If d is NULL, returns the first registered output audio/video device,
110  * if d is non-NULL, returns the next registered output audio/video device after d
111  * or NULL if d is the last one.
112  */
114 
115 typedef struct AVDeviceRect {
116  int x; /**< x coordinate of top left corner */
117  int y; /**< y coordinate of top left corner */
118  int width; /**< width */
119  int height; /**< height */
120 } AVDeviceRect;
121 
122 /**
123  * Message types used by avdevice_app_to_dev_control_message().
124  */
126  /**
127  * Dummy message.
128  */
129  AV_APP_TO_DEV_NONE = MKBETAG('N','O','N','E'),
130 
131  /**
132  * Window size change message.
133  *
134  * Message is sent to the device every time the application changes the size
135  * of the window device renders to.
136  * Message should also be sent right after window is created.
137  *
138  * data: AVDeviceRect: new window size.
139  */
140  AV_APP_TO_DEV_WINDOW_SIZE = MKBETAG('G','E','O','M'),
141 
142  /**
143  * Repaint request message.
144  *
145  * Message is sent to the device when window has to be repainted.
146  *
147  * data: AVDeviceRect: area required to be repainted.
148  * NULL: whole area is required to be repainted.
149  */
151 
152  /**
153  * Request pause/play.
154  *
155  * Application requests pause/unpause playback.
156  * Mostly usable with devices that have internal buffer.
157  * By default devices are not paused.
158  *
159  * data: NULL
160  */
161  AV_APP_TO_DEV_PAUSE = MKBETAG('P', 'A', 'U', ' '),
162  AV_APP_TO_DEV_PLAY = MKBETAG('P', 'L', 'A', 'Y'),
163  AV_APP_TO_DEV_TOGGLE_PAUSE = MKBETAG('P', 'A', 'U', 'T'),
164 
165  /**
166  * Volume control message.
167  *
168  * Set volume level. It may be device-dependent if volume
169  * is changed per stream or system wide. Per stream volume
170  * change is expected when possible.
171  *
172  * data: double: new volume with range of 0.0 - 1.0.
173  */
174  AV_APP_TO_DEV_SET_VOLUME = MKBETAG('S', 'V', 'O', 'L'),
175 
176  /**
177  * Mute control messages.
178  *
179  * Change mute state. It may be device-dependent if mute status
180  * is changed per stream or system wide. Per stream mute status
181  * change is expected when possible.
182  *
183  * data: NULL.
184  */
185  AV_APP_TO_DEV_MUTE = MKBETAG(' ', 'M', 'U', 'T'),
186  AV_APP_TO_DEV_UNMUTE = MKBETAG('U', 'M', 'U', 'T'),
187  AV_APP_TO_DEV_TOGGLE_MUTE = MKBETAG('T', 'M', 'U', 'T'),
188 
189  /**
190  * Get volume/mute messages.
191  *
192  * Force the device to send AV_DEV_TO_APP_VOLUME_LEVEL_CHANGED or
193  * AV_DEV_TO_APP_MUTE_STATE_CHANGED command respectively.
194  *
195  * data: NULL.
196  */
197  AV_APP_TO_DEV_GET_VOLUME = MKBETAG('G', 'V', 'O', 'L'),
198  AV_APP_TO_DEV_GET_MUTE = MKBETAG('G', 'M', 'U', 'T'),
199 };
200 
201 /**
202  * Message types used by avdevice_dev_to_app_control_message().
203  */
205  /**
206  * Dummy message.
207  */
208  AV_DEV_TO_APP_NONE = MKBETAG('N','O','N','E'),
209 
210  /**
211  * Create window buffer message.
212  *
213  * Device requests to create a window buffer. Exact meaning is device-
214  * and application-dependent. Message is sent before rendering first
215  * frame and all one-shot initializations should be done here.
216  * Application is allowed to ignore preferred window buffer size.
217  *
218  * @note: Application is obligated to inform about window buffer size
219  * with AV_APP_TO_DEV_WINDOW_SIZE message.
220  *
221  * data: AVDeviceRect: preferred size of the window buffer.
222  * NULL: no preferred size of the window buffer.
223  */
225 
226  /**
227  * Prepare window buffer message.
228  *
229  * Device requests to prepare a window buffer for rendering.
230  * Exact meaning is device- and application-dependent.
231  * Message is sent before rendering of each frame.
232  *
233  * data: NULL.
234  */
236 
237  /**
238  * Display window buffer message.
239  *
240  * Device requests to display a window buffer.
241  * Message is sent when new frame is ready to be displayed.
242  * Usually buffers need to be swapped in handler of this message.
243  *
244  * data: NULL.
245  */
247 
248  /**
249  * Destroy window buffer message.
250  *
251  * Device requests to destroy a window buffer.
252  * Message is sent when device is about to be destroyed and window
253  * buffer is not required anymore.
254  *
255  * data: NULL.
256  */
258 
259  /**
260  * Buffer fullness status messages.
261  *
262  * Device signals buffer overflow/underflow.
263  *
264  * data: NULL.
265  */
268 
269  /**
270  * Buffer readable/writable.
271  *
272  * Device informs that buffer is readable/writable.
273  * When possible, device informs how many bytes can be read/write.
274  *
275  * @warning Device may not inform when number of bytes than can be read/write changes.
276  *
277  * data: int64_t: amount of bytes available to read/write.
278  * NULL: amount of bytes available to read/write is not known.
279  */
282 
283  /**
284  * Mute state change message.
285  *
286  * Device informs that mute state has changed.
287  *
288  * data: int: 0 for not muted state, non-zero for muted state.
289  */
291 
292  /**
293  * Volume level change message.
294  *
295  * Device informs that volume level has changed.
296  *
297  * data: double: new volume with range of 0.0 - 1.0.
298  */
300 };
301 
302 /**
303  * Send control message from application to device.
304  *
305  * @param s device context.
306  * @param type message type.
307  * @param data message data. Exact type depends on message type.
308  * @param data_size size of message data.
309  * @return >= 0 on success, negative on error.
310  * AVERROR(ENOSYS) when device doesn't implement handler of the message.
311  */
314  void *data, size_t data_size);
315 
316 /**
317  * Send control message from device to application.
318  *
319  * @param s device context.
320  * @param type message type.
321  * @param data message data. Can be NULL.
322  * @param data_size size of message data.
323  * @return >= 0 on success, negative on error.
324  * AVERROR(ENOSYS) when application doesn't implement handler of the message.
325  */
328  void *data, size_t data_size);
329 
330 /**
331  * Structure describes basic parameters of the device.
332  */
333 typedef struct AVDeviceInfo {
334  char *device_name; /**< device name, format depends on device */
335  char *device_description; /**< human friendly name */
336  enum AVMediaType *media_types; /**< array indicating what media types(s), if any, a device can provide. If null, cannot provide any */
337  int nb_media_types; /**< length of media_types array, 0 if device cannot provide any media types */
338 } AVDeviceInfo;
339 
340 /**
341  * List of devices.
342  */
343 typedef struct AVDeviceInfoList {
344  AVDeviceInfo **devices; /**< list of autodetected devices */
345  int nb_devices; /**< number of autodetected devices */
346  int default_device; /**< index of default device or -1 if no default */
348 
349 /**
350  * List devices.
351  *
352  * Returns available device names and their parameters.
353  *
354  * @note: Some devices may accept system-dependent device names that cannot be
355  * autodetected. The list returned by this function cannot be assumed to
356  * be always completed.
357  *
358  * @param s device context.
359  * @param[out] device_list list of autodetected devices.
360  * @return count of autodetected devices, negative on error.
361  */
362 int avdevice_list_devices(struct AVFormatContext *s, AVDeviceInfoList **device_list);
363 
364 /**
365  * Convenient function to free result of avdevice_list_devices().
366  *
367  * @param device_list device list to be freed.
368  */
369 void avdevice_free_list_devices(AVDeviceInfoList **device_list);
370 
371 /**
372  * List devices.
373  *
374  * Returns available device names and their parameters.
375  * These are convinient wrappers for avdevice_list_devices().
376  * Device context is allocated and deallocated internally.
377  *
378  * @param device device format. May be NULL if device name is set.
379  * @param device_name device name. May be NULL if device format is set.
380  * @param device_options An AVDictionary filled with device-private options. May be NULL.
381  * The same options must be passed later to avformat_write_header() for output
382  * devices or avformat_open_input() for input devices, or at any other place
383  * that affects device-private options.
384  * @param[out] device_list list of autodetected devices
385  * @return count of autodetected devices, negative on error.
386  * @note device argument takes precedence over device_name when both are set.
387  */
388 int avdevice_list_input_sources(const AVInputFormat *device, const char *device_name,
389  AVDictionary *device_options, AVDeviceInfoList **device_list);
390 int avdevice_list_output_sinks(const AVOutputFormat *device, const char *device_name,
391  AVDictionary *device_options, AVDeviceInfoList **device_list);
392 
393 /**
394  * @}
395  */
396 
397 #endif /* AVDEVICE_AVDEVICE_H */
AV_APP_TO_DEV_MUTE
@ AV_APP_TO_DEV_MUTE
Mute control messages.
Definition: avdevice.h:185
opt.h
AV_APP_TO_DEV_SET_VOLUME
@ AV_APP_TO_DEV_SET_VOLUME
Volume control message.
Definition: avdevice.h:174
AV_DEV_TO_APP_BUFFER_OVERFLOW
@ AV_DEV_TO_APP_BUFFER_OVERFLOW
Buffer fullness status messages.
Definition: avdevice.h:266
AVDeviceInfo::device_name
char * device_name
device name, format depends on device
Definition: avdevice.h:334
AVDeviceInfoList::nb_devices
int nb_devices
number of autodetected devices
Definition: avdevice.h:345
AV_DEV_TO_APP_PREPARE_WINDOW_BUFFER
@ AV_DEV_TO_APP_PREPARE_WINDOW_BUFFER
Prepare window buffer message.
Definition: avdevice.h:235
avdevice_list_devices
int avdevice_list_devices(struct AVFormatContext *s, AVDeviceInfoList **device_list)
List devices.
Definition: avdevice.c:41
AVAppToDevMessageType
AVAppToDevMessageType
Message types used by avdevice_app_to_dev_control_message().
Definition: avdevice.h:125
data
const char data[16]
Definition: mxf.c:148
avdevice_dev_to_app_control_message
int avdevice_dev_to_app_control_message(struct AVFormatContext *s, enum AVDevToAppMessageType type, void *data, size_t data_size)
Send control message from device to application.
Definition: avdevice.c:33
AV_APP_TO_DEV_PAUSE
@ AV_APP_TO_DEV_PAUSE
Request pause/play.
Definition: avdevice.h:161
AVDictionary
Definition: dict.c:34
AV_APP_TO_DEV_GET_MUTE
@ AV_APP_TO_DEV_GET_MUTE
Definition: avdevice.h:198
AV_APP_TO_DEV_WINDOW_REPAINT
@ AV_APP_TO_DEV_WINDOW_REPAINT
Repaint request message.
Definition: avdevice.h:150
AV_DEV_TO_APP_MUTE_STATE_CHANGED
@ AV_DEV_TO_APP_MUTE_STATE_CHANGED
Mute state change message.
Definition: avdevice.h:290
av_input_audio_device_next
const AVInputFormat * av_input_audio_device_next(const AVInputFormat *d)
Audio input devices iterator.
Definition: alldevices.c:127
avdevice_list_output_sinks
int avdevice_list_output_sinks(const AVOutputFormat *device, const char *device_name, AVDictionary *device_options, AVDeviceInfoList **device_list)
Definition: avdevice.c:95
type
it s the only field you need to keep assuming you have a context There is some magic you don t need to care about around this just let it vf type
Definition: writing_filters.txt:86
AV_APP_TO_DEV_UNMUTE
@ AV_APP_TO_DEV_UNMUTE
Definition: avdevice.h:186
AVDeviceInfoList::devices
AVDeviceInfo ** devices
list of autodetected devices
Definition: avdevice.h:344
AVInputFormat
Definition: avformat.h:548
avdevice_list_input_sources
int avdevice_list_input_sources(const AVInputFormat *device, const char *device_name, AVDictionary *device_options, AVDeviceInfoList **device_list)
List devices.
Definition: avdevice.c:84
AV_APP_TO_DEV_TOGGLE_PAUSE
@ AV_APP_TO_DEV_TOGGLE_PAUSE
Definition: avdevice.h:163
AV_DEV_TO_APP_DISPLAY_WINDOW_BUFFER
@ AV_DEV_TO_APP_DISPLAY_WINDOW_BUFFER
Display window buffer message.
Definition: avdevice.h:246
s
#define s(width, name)
Definition: cbs_vp9.c:198
AV_DEV_TO_APP_CREATE_WINDOW_BUFFER
@ AV_DEV_TO_APP_CREATE_WINDOW_BUFFER
Create window buffer message.
Definition: avdevice.h:224
avdevice_license
const char * avdevice_license(void)
Return the libavdevice license.
Definition: version.c:41
version_major.h
AVDeviceInfo::media_types
enum AVMediaType * media_types
array indicating what media types(s), if any, a device can provide.
Definition: avdevice.h:336
AVDeviceInfo::nb_media_types
int nb_media_types
length of media_types array, 0 if device cannot provide any media types
Definition: avdevice.h:337
AVFormatContext
Format I/O context.
Definition: avformat.h:1255
AV_APP_TO_DEV_GET_VOLUME
@ AV_APP_TO_DEV_GET_VOLUME
Get volume/mute messages.
Definition: avdevice.h:197
avdevice_configuration
const char * avdevice_configuration(void)
Return the libavdevice build-time configuration.
Definition: version.c:36
AVDeviceRect::y
int y
y coordinate of top left corner
Definition: avdevice.h:117
AV_APP_TO_DEV_NONE
@ AV_APP_TO_DEV_NONE
Dummy message.
Definition: avdevice.h:129
AVMediaType
AVMediaType
Definition: avutil.h:199
AV_DEV_TO_APP_BUFFER_READABLE
@ AV_DEV_TO_APP_BUFFER_READABLE
Buffer readable/writable.
Definition: avdevice.h:280
AV_APP_TO_DEV_PLAY
@ AV_APP_TO_DEV_PLAY
Definition: avdevice.h:162
av_output_video_device_next
const AVOutputFormat * av_output_video_device_next(const AVOutputFormat *d)
Video output devices iterator.
Definition: alldevices.c:142
MKBETAG
#define MKBETAG(a, b, c, d)
Definition: macros.h:56
AVDeviceInfo
Structure describes basic parameters of the device.
Definition: avdevice.h:333
avdevice_free_list_devices
void avdevice_free_list_devices(AVDeviceInfoList **device_list)
Convenient function to free result of avdevice_list_devices().
Definition: avdevice.c:106
AV_APP_TO_DEV_TOGGLE_MUTE
@ AV_APP_TO_DEV_TOGGLE_MUTE
Definition: avdevice.h:187
AVDevToAppMessageType
AVDevToAppMessageType
Message types used by avdevice_dev_to_app_control_message().
Definition: avdevice.h:204
AVDeviceInfo::device_description
char * device_description
human friendly name
Definition: avdevice.h:335
AVDeviceRect::x
int x
x coordinate of top left corner
Definition: avdevice.h:116
avdevice_version
unsigned avdevice_version(void)
Return the LIBAVDEVICE_VERSION_INT constant.
Definition: version.c:30
AVDeviceRect
Definition: avdevice.h:115
log.h
AVOutputFormat
Definition: avformat.h:509
AV_APP_TO_DEV_WINDOW_SIZE
@ AV_APP_TO_DEV_WINDOW_SIZE
Window size change message.
Definition: avdevice.h:140
AVDeviceInfoList
List of devices.
Definition: avdevice.h:343
avformat.h
dict.h
AVDeviceRect::height
int height
height
Definition: avdevice.h:119
AVDeviceInfoList::default_device
int default_device
index of default device or -1 if no default
Definition: avdevice.h:346
avdevice_app_to_dev_control_message
int avdevice_app_to_dev_control_message(struct AVFormatContext *s, enum AVAppToDevMessageType type, void *data, size_t data_size)
Send control message from application to device.
Definition: avdevice.c:25
av_output_audio_device_next
const AVOutputFormat * av_output_audio_device_next(const AVOutputFormat *d)
Audio output devices iterator.
Definition: alldevices.c:137
AV_DEV_TO_APP_VOLUME_LEVEL_CHANGED
@ AV_DEV_TO_APP_VOLUME_LEVEL_CHANGED
Volume level change message.
Definition: avdevice.h:299
AV_DEV_TO_APP_BUFFER_WRITABLE
@ AV_DEV_TO_APP_BUFFER_WRITABLE
Definition: avdevice.h:281
d
d
Definition: ffmpeg_filter.c:425
AV_DEV_TO_APP_NONE
@ AV_DEV_TO_APP_NONE
Dummy message.
Definition: avdevice.h:208
AV_DEV_TO_APP_DESTROY_WINDOW_BUFFER
@ AV_DEV_TO_APP_DESTROY_WINDOW_BUFFER
Destroy window buffer message.
Definition: avdevice.h:257
av_input_video_device_next
const AVInputFormat * av_input_video_device_next(const AVInputFormat *d)
Video input devices iterator.
Definition: alldevices.c:132
AV_DEV_TO_APP_BUFFER_UNDERFLOW
@ AV_DEV_TO_APP_BUFFER_UNDERFLOW
Definition: avdevice.h:267
AVDeviceRect::width
int width
width
Definition: avdevice.h:118
avdevice_register_all
void avdevice_register_all(void)
Initialize libavdevice and register all the input and output devices.
Definition: alldevices.c:70