You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

avdevice.h 16KB

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