avdevice.h 17 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514
  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. #ifndef AVDEVICE_AVDEVICE_H
  19. #define AVDEVICE_AVDEVICE_H
  20. #include "version.h"
  21. /**
  22. * @file
  23. * @ingroup lavd
  24. * Main libavdevice API header
  25. */
  26. /**
  27. * @defgroup lavd libavdevice
  28. * Special devices muxing/demuxing library.
  29. *
  30. * Libavdevice is a complementary library to @ref libavf "libavformat". It
  31. * provides various "special" platform-specific muxers and demuxers, e.g. for
  32. * grabbing devices, audio capture and playback etc. As a consequence, the
  33. * (de)muxers in libavdevice are of the AVFMT_NOFILE type (they use their own
  34. * I/O functions). The filename passed to avformat_open_input() often does not
  35. * refer to an actually existing file, but has some special device-specific
  36. * meaning - e.g. for xcbgrab it is the display name.
  37. *
  38. * To use libavdevice, simply call avdevice_register_all() to register all
  39. * compiled muxers and demuxers. They all use standard libavformat API.
  40. *
  41. * @{
  42. */
  43. #include "libavutil/log.h"
  44. #include "libavutil/opt.h"
  45. #include "libavutil/dict.h"
  46. #include "libavformat/avformat.h"
  47. /**
  48. * Return the LIBAVDEVICE_VERSION_INT constant.
  49. */
  50. unsigned avdevice_version(void);
  51. /**
  52. * Return the libavdevice build-time configuration.
  53. */
  54. const char *avdevice_configuration(void);
  55. /**
  56. * Return the libavdevice license.
  57. */
  58. const char *avdevice_license(void);
  59. /**
  60. * Initialize libavdevice and register all the input and output devices.
  61. */
  62. void avdevice_register_all(void);
  63. /**
  64. * Audio input devices iterator.
  65. *
  66. * If d is NULL, returns the first registered input audio/video device,
  67. * if d is non-NULL, returns the next registered input audio/video device after d
  68. * or NULL if d is the last one.
  69. */
  70. AVInputFormat *av_input_audio_device_next(AVInputFormat *d);
  71. /**
  72. * Video input devices iterator.
  73. *
  74. * If d is NULL, returns the first registered input audio/video device,
  75. * if d is non-NULL, returns the next registered input audio/video device after d
  76. * or NULL if d is the last one.
  77. */
  78. AVInputFormat *av_input_video_device_next(AVInputFormat *d);
  79. /**
  80. * Audio output devices iterator.
  81. *
  82. * If d is NULL, returns the first registered output audio/video device,
  83. * if d is non-NULL, returns the next registered output audio/video device after d
  84. * or NULL if d is the last one.
  85. */
  86. AVOutputFormat *av_output_audio_device_next(AVOutputFormat *d);
  87. /**
  88. * Video output devices iterator.
  89. *
  90. * If d is NULL, returns the first registered output audio/video device,
  91. * if d is non-NULL, returns the next registered output audio/video device after d
  92. * or NULL if d is the last one.
  93. */
  94. AVOutputFormat *av_output_video_device_next(AVOutputFormat *d);
  95. typedef struct AVDeviceRect {
  96. int x; /**< x coordinate of top left corner */
  97. int y; /**< y coordinate of top left corner */
  98. int width; /**< width */
  99. int height; /**< height */
  100. } AVDeviceRect;
  101. /**
  102. * Message types used by avdevice_app_to_dev_control_message().
  103. */
  104. enum AVAppToDevMessageType {
  105. /**
  106. * Dummy message.
  107. */
  108. AV_APP_TO_DEV_NONE = MKBETAG('N','O','N','E'),
  109. /**
  110. * Window size change message.
  111. *
  112. * Message is sent to the device every time the application changes the size
  113. * of the window device renders to.
  114. * Message should also be sent right after window is created.
  115. *
  116. * data: AVDeviceRect: new window size.
  117. */
  118. AV_APP_TO_DEV_WINDOW_SIZE = MKBETAG('G','E','O','M'),
  119. /**
  120. * Repaint request message.
  121. *
  122. * Message is sent to the device when window has to be repainted.
  123. *
  124. * data: AVDeviceRect: area required to be repainted.
  125. * NULL: whole area is required to be repainted.
  126. */
  127. AV_APP_TO_DEV_WINDOW_REPAINT = MKBETAG('R','E','P','A'),
  128. /**
  129. * Request pause/play.
  130. *
  131. * Application requests pause/unpause playback.
  132. * Mostly usable with devices that have internal buffer.
  133. * By default devices are not paused.
  134. *
  135. * data: NULL
  136. */
  137. AV_APP_TO_DEV_PAUSE = MKBETAG('P', 'A', 'U', ' '),
  138. AV_APP_TO_DEV_PLAY = MKBETAG('P', 'L', 'A', 'Y'),
  139. AV_APP_TO_DEV_TOGGLE_PAUSE = MKBETAG('P', 'A', 'U', 'T'),
  140. /**
  141. * Volume control message.
  142. *
  143. * Set volume level. It may be device-dependent if volume
  144. * is changed per stream or system wide. Per stream volume
  145. * change is expected when possible.
  146. *
  147. * data: double: new volume with range of 0.0 - 1.0.
  148. */
  149. AV_APP_TO_DEV_SET_VOLUME = MKBETAG('S', 'V', 'O', 'L'),
  150. /**
  151. * Mute control messages.
  152. *
  153. * Change mute state. It may be device-dependent if mute status
  154. * is changed per stream or system wide. Per stream mute status
  155. * change is expected when possible.
  156. *
  157. * data: NULL.
  158. */
  159. AV_APP_TO_DEV_MUTE = MKBETAG(' ', 'M', 'U', 'T'),
  160. AV_APP_TO_DEV_UNMUTE = MKBETAG('U', 'M', 'U', 'T'),
  161. AV_APP_TO_DEV_TOGGLE_MUTE = MKBETAG('T', 'M', 'U', 'T'),
  162. /**
  163. * Get volume/mute messages.
  164. *
  165. * Force the device to send AV_DEV_TO_APP_VOLUME_LEVEL_CHANGED or
  166. * AV_DEV_TO_APP_MUTE_STATE_CHANGED command respectively.
  167. *
  168. * data: NULL.
  169. */
  170. AV_APP_TO_DEV_GET_VOLUME = MKBETAG('G', 'V', 'O', 'L'),
  171. AV_APP_TO_DEV_GET_MUTE = MKBETAG('G', 'M', 'U', 'T'),
  172. };
  173. /**
  174. * Message types used by avdevice_dev_to_app_control_message().
  175. */
  176. enum AVDevToAppMessageType {
  177. /**
  178. * Dummy message.
  179. */
  180. AV_DEV_TO_APP_NONE = MKBETAG('N','O','N','E'),
  181. /**
  182. * Create window buffer message.
  183. *
  184. * Device requests to create a window buffer. Exact meaning is device-
  185. * and application-dependent. Message is sent before rendering first
  186. * frame and all one-shot initializations should be done here.
  187. * Application is allowed to ignore preferred window buffer size.
  188. *
  189. * @note: Application is obligated to inform about window buffer size
  190. * with AV_APP_TO_DEV_WINDOW_SIZE message.
  191. *
  192. * data: AVDeviceRect: preferred size of the window buffer.
  193. * NULL: no preferred size of the window buffer.
  194. */
  195. AV_DEV_TO_APP_CREATE_WINDOW_BUFFER = MKBETAG('B','C','R','E'),
  196. /**
  197. * Prepare window buffer message.
  198. *
  199. * Device requests to prepare a window buffer for rendering.
  200. * Exact meaning is device- and application-dependent.
  201. * Message is sent before rendering of each frame.
  202. *
  203. * data: NULL.
  204. */
  205. AV_DEV_TO_APP_PREPARE_WINDOW_BUFFER = MKBETAG('B','P','R','E'),
  206. /**
  207. * Display window buffer message.
  208. *
  209. * Device requests to display a window buffer.
  210. * Message is sent when new frame is ready to be displayed.
  211. * Usually buffers need to be swapped in handler of this message.
  212. *
  213. * data: NULL.
  214. */
  215. AV_DEV_TO_APP_DISPLAY_WINDOW_BUFFER = MKBETAG('B','D','I','S'),
  216. /**
  217. * Destroy window buffer message.
  218. *
  219. * Device requests to destroy a window buffer.
  220. * Message is sent when device is about to be destroyed and window
  221. * buffer is not required anymore.
  222. *
  223. * data: NULL.
  224. */
  225. AV_DEV_TO_APP_DESTROY_WINDOW_BUFFER = MKBETAG('B','D','E','S'),
  226. /**
  227. * Buffer fullness status messages.
  228. *
  229. * Device signals buffer overflow/underflow.
  230. *
  231. * data: NULL.
  232. */
  233. AV_DEV_TO_APP_BUFFER_OVERFLOW = MKBETAG('B','O','F','L'),
  234. AV_DEV_TO_APP_BUFFER_UNDERFLOW = MKBETAG('B','U','F','L'),
  235. /**
  236. * Buffer readable/writable.
  237. *
  238. * Device informs that buffer is readable/writable.
  239. * When possible, device informs how many bytes can be read/write.
  240. *
  241. * @warning Device may not inform when number of bytes than can be read/write changes.
  242. *
  243. * data: int64_t: amount of bytes available to read/write.
  244. * NULL: amount of bytes available to read/write is not known.
  245. */
  246. AV_DEV_TO_APP_BUFFER_READABLE = MKBETAG('B','R','D',' '),
  247. AV_DEV_TO_APP_BUFFER_WRITABLE = MKBETAG('B','W','R',' '),
  248. /**
  249. * Mute state change message.
  250. *
  251. * Device informs that mute state has changed.
  252. *
  253. * data: int: 0 for not muted state, non-zero for muted state.
  254. */
  255. AV_DEV_TO_APP_MUTE_STATE_CHANGED = MKBETAG('C','M','U','T'),
  256. /**
  257. * Volume level change message.
  258. *
  259. * Device informs that volume level has changed.
  260. *
  261. * data: double: new volume with range of 0.0 - 1.0.
  262. */
  263. AV_DEV_TO_APP_VOLUME_LEVEL_CHANGED = MKBETAG('C','V','O','L'),
  264. };
  265. /**
  266. * Send control message from application to device.
  267. *
  268. * @param s device context.
  269. * @param type message type.
  270. * @param data message data. Exact type depends on message type.
  271. * @param data_size size of message data.
  272. * @return >= 0 on success, negative on error.
  273. * AVERROR(ENOSYS) when device doesn't implement handler of the message.
  274. */
  275. int avdevice_app_to_dev_control_message(struct AVFormatContext *s,
  276. enum AVAppToDevMessageType type,
  277. void *data, size_t data_size);
  278. /**
  279. * Send control message from device to application.
  280. *
  281. * @param s device context.
  282. * @param type message type.
  283. * @param data message data. Can be NULL.
  284. * @param data_size size of message data.
  285. * @return >= 0 on success, negative on error.
  286. * AVERROR(ENOSYS) when application doesn't implement handler of the message.
  287. */
  288. int avdevice_dev_to_app_control_message(struct AVFormatContext *s,
  289. enum AVDevToAppMessageType type,
  290. void *data, size_t data_size);
  291. /**
  292. * Following API allows user to probe device capabilities (supported codecs,
  293. * pixel formats, sample formats, resolutions, channel counts, etc).
  294. * It is build on top op AVOption API.
  295. * Queried capabilities make it possible to set up converters of video or audio
  296. * parameters that fit to the device.
  297. *
  298. * List of capabilities that can be queried:
  299. * - Capabilities valid for both audio and video devices:
  300. * - codec: supported audio/video codecs.
  301. * type: AV_OPT_TYPE_INT (AVCodecID value)
  302. * - Capabilities valid for audio devices:
  303. * - sample_format: supported sample formats.
  304. * type: AV_OPT_TYPE_INT (AVSampleFormat value)
  305. * - sample_rate: supported sample rates.
  306. * type: AV_OPT_TYPE_INT
  307. * - channels: supported number of channels.
  308. * type: AV_OPT_TYPE_INT
  309. * - channel_layout: supported channel layouts.
  310. * type: AV_OPT_TYPE_INT64
  311. * - Capabilities valid for video devices:
  312. * - pixel_format: supported pixel formats.
  313. * type: AV_OPT_TYPE_INT (AVPixelFormat value)
  314. * - window_size: supported window sizes (describes size of the window size presented to the user).
  315. * type: AV_OPT_TYPE_IMAGE_SIZE
  316. * - frame_size: supported frame sizes (describes size of provided video frames).
  317. * type: AV_OPT_TYPE_IMAGE_SIZE
  318. * - fps: supported fps values
  319. * type: AV_OPT_TYPE_RATIONAL
  320. *
  321. * Value of the capability may be set by user using av_opt_set() function
  322. * and AVDeviceCapabilitiesQuery object. Following queries will
  323. * limit results to the values matching already set capabilities.
  324. * For example, setting a codec may impact number of formats or fps values
  325. * returned during next query. Setting invalid value may limit results to zero.
  326. *
  327. * Example of the usage basing on opengl output device:
  328. *
  329. * @code
  330. * AVFormatContext *oc = NULL;
  331. * AVDeviceCapabilitiesQuery *caps = NULL;
  332. * AVOptionRanges *ranges;
  333. * int ret;
  334. *
  335. * if ((ret = avformat_alloc_output_context2(&oc, NULL, "opengl", NULL)) < 0)
  336. * goto fail;
  337. * if (avdevice_capabilities_create(&caps, oc, NULL) < 0)
  338. * goto fail;
  339. *
  340. * //query codecs
  341. * if (av_opt_query_ranges(&ranges, caps, "codec", AV_OPT_MULTI_COMPONENT_RANGE)) < 0)
  342. * goto fail;
  343. * //pick codec here and set it
  344. * av_opt_set(caps, "codec", AV_CODEC_ID_RAWVIDEO, 0);
  345. *
  346. * //query format
  347. * if (av_opt_query_ranges(&ranges, caps, "pixel_format", AV_OPT_MULTI_COMPONENT_RANGE)) < 0)
  348. * goto fail;
  349. * //pick format here and set it
  350. * av_opt_set(caps, "pixel_format", AV_PIX_FMT_YUV420P, 0);
  351. *
  352. * //query and set more capabilities
  353. *
  354. * fail:
  355. * //clean up code
  356. * avdevice_capabilities_free(&query, oc);
  357. * avformat_free_context(oc);
  358. * @endcode
  359. */
  360. /**
  361. * Structure describes device capabilities.
  362. *
  363. * It is used by devices in conjunction with av_device_capabilities AVOption table
  364. * to implement capabilities probing API based on AVOption API. Should not be used directly.
  365. */
  366. typedef struct AVDeviceCapabilitiesQuery {
  367. const AVClass *av_class;
  368. AVFormatContext *device_context;
  369. enum AVCodecID codec;
  370. enum AVSampleFormat sample_format;
  371. enum AVPixelFormat pixel_format;
  372. int sample_rate;
  373. int channels;
  374. int64_t channel_layout;
  375. int window_width;
  376. int window_height;
  377. int frame_width;
  378. int frame_height;
  379. AVRational fps;
  380. } AVDeviceCapabilitiesQuery;
  381. /**
  382. * AVOption table used by devices to implement device capabilities API. Should not be used by a user.
  383. */
  384. extern const AVOption av_device_capabilities[];
  385. /**
  386. * Initialize capabilities probing API based on AVOption API.
  387. *
  388. * avdevice_capabilities_free() must be called when query capabilities API is
  389. * not used anymore.
  390. *
  391. * @param[out] caps Device capabilities data. Pointer to a NULL pointer must be passed.
  392. * @param s Context of the device.
  393. * @param device_options An AVDictionary filled with device-private options.
  394. * On return this parameter will be destroyed and replaced with a dict
  395. * containing options that were not found. May be NULL.
  396. * The same options must be passed later to avformat_write_header() for output
  397. * devices or avformat_open_input() for input devices, or at any other place
  398. * that affects device-private options.
  399. *
  400. * @return >= 0 on success, negative otherwise.
  401. */
  402. int avdevice_capabilities_create(AVDeviceCapabilitiesQuery **caps, AVFormatContext *s,
  403. AVDictionary **device_options);
  404. /**
  405. * Free resources created by avdevice_capabilities_create()
  406. *
  407. * @param caps Device capabilities data to be freed.
  408. * @param s Context of the device.
  409. */
  410. void avdevice_capabilities_free(AVDeviceCapabilitiesQuery **caps, AVFormatContext *s);
  411. /**
  412. * Structure describes basic parameters of the device.
  413. */
  414. typedef struct AVDeviceInfo {
  415. char *device_name; /**< device name, format depends on device */
  416. char *device_description; /**< human friendly name */
  417. } AVDeviceInfo;
  418. /**
  419. * List of devices.
  420. */
  421. typedef struct AVDeviceInfoList {
  422. AVDeviceInfo **devices; /**< list of autodetected devices */
  423. int nb_devices; /**< number of autodetected devices */
  424. int default_device; /**< index of default device or -1 if no default */
  425. } AVDeviceInfoList;
  426. /**
  427. * List devices.
  428. *
  429. * Returns available device names and their parameters.
  430. *
  431. * @note: Some devices may accept system-dependent device names that cannot be
  432. * autodetected. The list returned by this function cannot be assumed to
  433. * be always completed.
  434. *
  435. * @param s device context.
  436. * @param[out] device_list list of autodetected devices.
  437. * @return count of autodetected devices, negative on error.
  438. */
  439. int avdevice_list_devices(struct AVFormatContext *s, AVDeviceInfoList **device_list);
  440. /**
  441. * Convenient function to free result of avdevice_list_devices().
  442. *
  443. * @param devices device list to be freed.
  444. */
  445. void avdevice_free_list_devices(AVDeviceInfoList **device_list);
  446. /**
  447. * List devices.
  448. *
  449. * Returns available device names and their parameters.
  450. * These are convinient wrappers for avdevice_list_devices().
  451. * Device context is allocated and deallocated internally.
  452. *
  453. * @param device device format. May be NULL if device name is set.
  454. * @param device_name device name. May be NULL if device format is set.
  455. * @param device_options An AVDictionary filled with device-private options. May be NULL.
  456. * The same options must be passed later to avformat_write_header() for output
  457. * devices or avformat_open_input() for input devices, or at any other place
  458. * that affects device-private options.
  459. * @param[out] device_list list of autodetected devices
  460. * @return count of autodetected devices, negative on error.
  461. * @note device argument takes precedence over device_name when both are set.
  462. */
  463. int avdevice_list_input_sources(struct AVInputFormat *device, const char *device_name,
  464. AVDictionary *device_options, AVDeviceInfoList **device_list);
  465. int avdevice_list_output_sinks(struct AVOutputFormat *device, const char *device_name,
  466. AVDictionary *device_options, AVDeviceInfoList **device_list);
  467. /**
  468. * @}
  469. */
  470. #endif /* AVDEVICE_AVDEVICE_H */