1
0

plugins.rst 20 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571
  1. Plugins
  2. =======
  3. Almost all custom functionality is added through plugin modules, which
  4. are typically dynamic libraries or scripts. The ability to capture
  5. and/or output audio/video, make a recording, output to an RTMP stream,
  6. encode in x264 are all examples of things that are accomplished via
  7. plugin modules.
  8. Plugins can implement sources, outputs, encoders, and services.
  9. Writing your first plugin? We provide `a basic template plugin <https://github.com/obsproject/obs-plugintemplate#obs-plugin-template>`_
  10. to get you started.
  11. Plugin Module Headers
  12. ---------------------
  13. These are some notable headers commonly used by plugins:
  14. - `libobs/obs-module.h`_ -- The primary header used for creating plugin
  15. modules. This file automatically includes the following files:
  16. - `libobs/obs.h`_ -- The main libobs header. This file automatically
  17. includes the following files:
  18. - `libobs/obs-source.h`_ -- Used for implementing sources in plugin
  19. modules
  20. - `libobs/obs-output.h`_ -- Used for implementing outputs in plugin
  21. modules
  22. - `libobs/obs-encoder.h`_ -- Used for implementing encoders in
  23. plugin modules
  24. - `libobs/obs-service.h`_ -- Used for implementing services in
  25. plugin modules
  26. - `libobs/obs-data.h`_ -- Used for managing settings for libobs
  27. objects
  28. - `libobs/obs-properties.h`_ -- Used for generating properties for
  29. libobs objects
  30. - `libobs/graphics/graphics.h`_ -- Used for graphics rendering
  31. Common Directory Structure and CMakeLists.txt
  32. ---------------------------------------------
  33. The common way source files are organized is to have one file for plugin
  34. initialization, and then specific files for each individual object
  35. you're implementing. For example, if you were to create a plugin called
  36. 'my-plugin', you'd have something like my-plugin.c where plugin
  37. initialization is done, my-source.c for the definition of a custom
  38. source, my-output.c for the definition of a custom output, etc. (This
  39. is not a rule of course)
  40. This is an example of a common directory structure for a native plugin
  41. module::
  42. my-plugin/data/locale/en-US.ini
  43. my-plugin/CMakeLists.txt
  44. my-plugin/my-plugin.c
  45. my-plugin/my-source.c
  46. my-plugin/my-output.c
  47. my-plugin/my-encoder.c
  48. my-plugin/my-service.c
  49. This would be an example of a common CMakeLists.txt file associated with
  50. these files::
  51. # my-plugin/CMakeLists.txt
  52. project(my-plugin)
  53. set(my-plugin_SOURCES
  54. my-plugin.c
  55. my-source.c
  56. my-output.c
  57. my-encoder.c
  58. my-service.c)
  59. add_library(my-plugin MODULE
  60. ${my-plugin_SOURCES})
  61. target_link_libraries(my-plugin
  62. libobs)
  63. install_obs_plugin_with_data(my-plugin data)
  64. Native Plugin Initialization
  65. ----------------------------
  66. To create a native plugin module, you will need to include the
  67. `libobs/obs-module.h`_ header, use :c:func:`OBS_DECLARE_MODULE()` macro,
  68. then create a definition of the function :c:func:`obs_module_load()`.
  69. In your :c:func:`obs_module_load()` function, you then register any of
  70. your custom sources, outputs, encoders, or services. See the
  71. :doc:`reference-modules` for more information.
  72. The following is an example of my-plugin.c, which would register one
  73. object of each type:
  74. .. code:: cpp
  75. /* my-plugin.c */
  76. #include <obs-module.h>
  77. /* Defines common functions (required) */
  78. OBS_DECLARE_MODULE()
  79. /* Implements common ini-based locale (optional) */
  80. OBS_MODULE_USE_DEFAULT_LOCALE("my-plugin", "en-US")
  81. extern struct obs_source_info my_source; /* Defined in my-source.c */
  82. extern struct obs_output_info my_output; /* Defined in my-output.c */
  83. extern struct obs_encoder_info my_encoder; /* Defined in my-encoder.c */
  84. extern struct obs_service_info my_service; /* Defined in my-service.c */
  85. bool obs_module_load(void)
  86. {
  87. obs_register_source(&my_source);
  88. obs_register_output(&my_output);
  89. obs_register_encoder(&my_encoder);
  90. obs_register_service(&my_service);
  91. return true;
  92. }
  93. .. _plugins_sources:
  94. Sources
  95. -------
  96. Sources are used to render video and/or audio on stream. Things such as
  97. capturing displays/games/audio, playing a video, showing an image, or
  98. playing audio. Sources can also be used to implement audio and video
  99. filters as well as transitions. The `libobs/obs-source.h`_ file is the
  100. dedicated header for implementing sources. See the
  101. :doc:`reference-sources` for more information.
  102. For example, to implement a source object, you need to define an
  103. :c:type:`obs_source_info` structure and fill it out with information and
  104. callbacks related to your source:
  105. .. code:: cpp
  106. /* my-source.c */
  107. [...]
  108. struct obs_source_info my_source {
  109. .id = "my_source",
  110. .type = OBS_SOURCE_TYPE_INPUT,
  111. .output_flags = OBS_SOURCE_VIDEO,
  112. .get_name = my_source_name,
  113. .create = my_source_create,
  114. .destroy = my_source_destroy,
  115. .update = my_source_update,
  116. .video_render = my_source_render,
  117. .get_width = my_source_width,
  118. .get_height = my_source_height
  119. };
  120. Then, in my-plugin.c, you would call :c:func:`obs_register_source()` in
  121. :c:func:`obs_module_load()` to register the source with libobs.
  122. .. code:: cpp
  123. /* my-plugin.c */
  124. [...]
  125. extern struct obs_source_info my_source; /* Defined in my-source.c */
  126. bool obs_module_load(void)
  127. {
  128. obs_register_source(&my_source);
  129. [...]
  130. return true;
  131. }
  132. Some simple examples of sources:
  133. - Synchronous video source: The `image source <https://github.com/obsproject/obs-studio/blob/master/plugins/image-source/image-source.c>`_
  134. - Asynchronous video source: The `random texture test source <https://github.com/obsproject/obs-studio/blob/master/test/test-input/test-random.c>`_
  135. - Audio source: The `sine wave test source <https://github.com/obsproject/obs-studio/blob/master/test/test-input/test-sinewave.c>`_
  136. - Video filter: The `test video filter <https://github.com/obsproject/obs-studio/blob/master/test/test-input/test-filter.c>`_
  137. - Audio filter: The `gain audio filter <https://github.com/obsproject/obs-studio/blob/master/plugins/obs-filters/gain-filter.c>`_
  138. .. _plugins_outputs:
  139. Outputs
  140. -------
  141. Outputs allow the ability to output the currently rendering audio/video.
  142. Streaming and recording are two common examples of outputs, but not the
  143. only types of outputs. Outputs can receive the raw data or receive
  144. encoded data. The `libobs/obs-output.h`_ file is the dedicated header
  145. for implementing outputs. See the :doc:`reference-outputs` for more
  146. information.
  147. For example, to implement an output object, you need to define an
  148. :c:type:`obs_output_info` structure and fill it out with information and
  149. callbacks related to your output:
  150. .. code:: cpp
  151. /* my-output.c */
  152. [...]
  153. struct obs_output_info my_output {
  154. .id = "my_output",
  155. .flags = OBS_OUTPUT_AV | OBS_OUTPUT_ENCODED,
  156. .get_name = my_output_name,
  157. .create = my_output_create,
  158. .destroy = my_output_destroy,
  159. .start = my_output_start,
  160. .stop = my_output_stop,
  161. .encoded_packet = my_output_data,
  162. .get_total_bytes = my_output_total_bytes,
  163. .encoded_video_codecs = "h264",
  164. .encoded_audio_codecs = "aac"
  165. };
  166. Then, in my-plugin.c, you would call :c:func:`obs_register_output()` in
  167. :c:func:`obs_module_load()` to register the output with libobs.
  168. .. code:: cpp
  169. /* my-plugin.c */
  170. [...]
  171. extern struct obs_output_info my_output; /* Defined in my-output.c */
  172. bool obs_module_load(void)
  173. {
  174. obs_register_output(&my_output);
  175. [...]
  176. return true;
  177. }
  178. Some examples of outputs:
  179. - Encoded video/audio outputs:
  180. - The `FLV output <https://github.com/obsproject/obs-studio/blob/master/plugins/obs-outputs/flv-output.c>`_
  181. - The `FFmpeg muxer output <https://github.com/obsproject/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-mux.c>`_
  182. - The `RTMP stream output <https://github.com/obsproject/obs-studio/blob/master/plugins/obs-outputs/rtmp-stream.c>`_
  183. - Raw video/audio outputs:
  184. - The `FFmpeg output <https://github.com/obsproject/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-output.c>`_
  185. .. _plugins_encoders:
  186. Encoders
  187. --------
  188. Encoders are OBS-specific implementations of video/audio encoders, which
  189. are used with outputs that use encoders. x264, NVENC, Quicksync are
  190. examples of encoder implementations. The `libobs/obs-encoder.h`_ file
  191. is the dedicated header for implementing encoders. See the
  192. :doc:`reference-encoders` for more information.
  193. For example, to implement an encoder object, you need to define an
  194. :c:type:`obs_encoder_info` structure and fill it out with information
  195. and callbacks related to your encoder:
  196. .. code:: cpp
  197. /* my-encoder.c */
  198. [...]
  199. struct obs_encoder_info my_encoder_encoder = {
  200. .id = "my_encoder",
  201. .type = OBS_ENCODER_VIDEO,
  202. .codec = "h264",
  203. .get_name = my_encoder_name,
  204. .create = my_encoder_create,
  205. .destroy = my_encoder_destroy,
  206. .encode = my_encoder_encode,
  207. .update = my_encoder_update,
  208. .get_extra_data = my_encoder_extra_data,
  209. .get_sei_data = my_encoder_sei,
  210. .get_video_info = my_encoder_video_info
  211. };
  212. Then, in my-plugin.c, you would call :c:func:`obs_register_encoder()`
  213. in :c:func:`obs_module_load()` to register the encoder with libobs.
  214. .. code:: cpp
  215. /* my-plugin.c */
  216. [...]
  217. extern struct obs_encoder_info my_encoder; /* Defined in my-encoder.c */
  218. bool obs_module_load(void)
  219. {
  220. obs_register_encoder(&my_encoder);
  221. [...]
  222. return true;
  223. }
  224. **IMPORTANT NOTE:** Encoder settings currently have a few expected
  225. common setting values that should have a specific naming convention:
  226. - **"bitrate"** - This value should be used for both video and audio
  227. encoders: bitrate, in kilobits.
  228. - **"rate_control"** - This is a setting used for video encoders.
  229. It's generally expected to have at least a "CBR" rate control.
  230. Other common rate controls are "VBR", "CQP".
  231. - **"keyint_sec"** - For video encoders, sets the keyframe interval
  232. value, in seconds, or closest possible approximation. *(Author's
  233. note: This should have have been "keyint", in frames.)*
  234. Examples of encoders:
  235. - Video encoders:
  236. - The `x264 encoder <https://github.com/obsproject/obs-studio/tree/master/plugins/obs-x264>`_
  237. - The `FFmpeg NVENC encoder <https://github.com/obsproject/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-nvenc.c>`_
  238. - The `Quicksync encoder <https://github.com/obsproject/obs-studio/tree/master/plugins/obs-qsv11>`_
  239. - Audio encoders:
  240. - The `FFmpeg AAC/Opus encoder <https://github.com/obsproject/obs-studio/blob/master/plugins/obs-ffmpeg/obs-ffmpeg-audio-encoders.c>`_
  241. .. _plugins_services:
  242. Services
  243. --------
  244. Services are custom implementations of streaming services, which are
  245. used with outputs that stream. For example, you could have a custom
  246. implementation for streaming to Twitch, and another for YouTube to allow
  247. the ability to log in and use their APIs to do things such as get the
  248. RTMP servers or control the channel. The `libobs/obs-service.h`_ file
  249. is the dedicated header for implementing services. See the
  250. :doc:`reference-services` for more information.
  251. *(Author's note: the service API is incomplete as of this writing)*
  252. For example, to implement a service object, you need to define an
  253. :c:type:`obs_service_info` structure and fill it out with information
  254. and callbacks related to your service:
  255. .. code:: cpp
  256. /* my-service.c */
  257. [...]
  258. struct obs_service_info my_service_service = {
  259. .id = "my_service",
  260. .get_name = my_service_name,
  261. .create = my_service_create,
  262. .destroy = my_service_destroy,
  263. .encode = my_service_encode,
  264. .update = my_service_update,
  265. .get_url = my_service_url,
  266. .get_key = my_service_key
  267. };
  268. Then, in my-plugin.c, you would call :c:func:`obs_register_service()` in
  269. :c:func:`obs_module_load()` to register the service with libobs.
  270. .. code:: cpp
  271. /* my-plugin.c */
  272. [...]
  273. extern struct obs_service_info my_service; /* Defined in my-service.c */
  274. bool obs_module_load(void)
  275. {
  276. obs_register_service(&my_service);
  277. [...]
  278. return true;
  279. }
  280. The only two existing services objects are the "common RTMP services"
  281. and "custom RTMP service" objects in `plugins/rtmp-services
  282. <https://github.com/obsproject/obs-studio/tree/master/plugins/rtmp-services>`_
  283. Settings
  284. --------
  285. Settings (see `libobs/obs-data.h`_) are used to get or set settings data
  286. typically associated with libobs objects, and can then be saved and
  287. loaded via Json text. See the :doc:`reference-settings` for more
  288. information.
  289. The *obs_data_t* is the equivalent of a Json object, where it's a string
  290. table of sub-objects, and the *obs_data_array_t* is similarly used to
  291. store an array of *obs_data_t* objects, similar to Json arrays (though
  292. not quite identical).
  293. To create an *obs_data_t* or *obs_data_array_t* object, you'd call the
  294. :c:func:`obs_data_create()` or :c:func:`obs_data_array_create()`
  295. functions. *obs_data_t* and *obs_data_array_t* objects are reference
  296. counted, so when you are finished with the object, call
  297. :c:func:`obs_data_release()` or :c:func:`obs_data_array_release()` to
  298. release those references. Any time an *obs_data_t* or
  299. *obs_data_array_t* object is returned by a function, their references
  300. are incremented, so you must release those references each time.
  301. To set values for an *obs_data_t* object, you'd use one of the following
  302. functions:
  303. .. code:: cpp
  304. /* Set functions */
  305. EXPORT void obs_data_set_string(obs_data_t *data, const char *name, const char *val);
  306. EXPORT void obs_data_set_int(obs_data_t *data, const char *name, long long val);
  307. EXPORT void obs_data_set_double(obs_data_t *data, const char *name, double val);
  308. EXPORT void obs_data_set_bool(obs_data_t *data, const char *name, bool val);
  309. EXPORT void obs_data_set_obj(obs_data_t *data, const char *name, obs_data_t *obj);
  310. EXPORT void obs_data_set_array(obs_data_t *data, const char *name, obs_data_array_t *array);
  311. Similarly, to get a value from an *obs_data_t* object, you'd use one of
  312. the following functions:
  313. .. code:: cpp
  314. /* Get functions */
  315. EXPORT const char *obs_data_get_string(obs_data_t *data, const char *name);
  316. EXPORT long long obs_data_get_int(obs_data_t *data, const char *name);
  317. EXPORT double obs_data_get_double(obs_data_t *data, const char *name);
  318. EXPORT bool obs_data_get_bool(obs_data_t *data, const char *name);
  319. EXPORT obs_data_t *obs_data_get_obj(obs_data_t *data, const char *name);
  320. EXPORT obs_data_array_t *obs_data_get_array(obs_data_t *data, const char *name);
  321. Unlike typical Json data objects, the *obs_data_t* object can also set
  322. default values. This allows the ability to control what is returned if
  323. there is no value assigned to a specific string in an *obs_data_t*
  324. object when that data is loaded from a Json string or Json file. Each
  325. libobs object also has a *get_defaults* callback which allows setting
  326. the default settings for the object on creation.
  327. These functions control the default values are as follows:
  328. .. code:: cpp
  329. /* Default value functions. */
  330. EXPORT void obs_data_set_default_string(obs_data_t *data, const char *name, const char *val);
  331. EXPORT void obs_data_set_default_int(obs_data_t *data, const char *name, long long val);
  332. EXPORT void obs_data_set_default_double(obs_data_t *data, const char *name, double val);
  333. EXPORT void obs_data_set_default_bool(obs_data_t *data, const char *name, bool val);
  334. EXPORT void obs_data_set_default_obj(obs_data_t *data, const char *name, obs_data_t *obj);
  335. Properties
  336. ----------
  337. Properties (see `libobs/obs-properties.h`_) are used to automatically
  338. generate user interface to modify settings for a libobs object (if
  339. desired). Each libobs object has a *get_properties* callback which is
  340. used to generate properties. The properties API defines specific
  341. properties that are linked to the object's settings, and the front-end
  342. uses those properties to generate widgets in order to allow the user to
  343. modify the settings. For example, if you had a boolean setting, you
  344. would use :c:func:`obs_properties_add_bool()` to allow the user to be
  345. able to change that setting. See the :doc:`reference-properties` for
  346. more information.
  347. An example of this:
  348. .. code:: cpp
  349. static obs_properties_t *my_source_properties(void *data)
  350. {
  351. obs_properties_t *ppts = obs_properties_create();
  352. obs_properties_add_bool(ppts, "my_bool",
  353. obs_module_text("MyBool"));
  354. UNUSED_PARAMETER(data);
  355. return ppts;
  356. }
  357. [...]
  358. struct obs_source_info my_source {
  359. .get_properties = my_source_properties,
  360. [...]
  361. };
  362. The *data* parameter is the object's data if the object is present.
  363. Typically this is unused and probably shouldn't be used if possible. It
  364. can be null if the properties are retrieved without an object associated
  365. with it.
  366. Properties can also be modified depending on what settings are shown.
  367. For example, you can mark certain properties as disabled or invisible
  368. depending on what a particular setting is set to using the
  369. :c:func:`obs_property_set_modified_callback()` function.
  370. For example, if you wanted boolean property A to hide text property B:
  371. .. code:: cpp
  372. static bool setting_a_modified(obs_properties_t *ppts,
  373. obs_property_t *p, obs_data_t *settings)
  374. {
  375. bool enabled = obs_data_get_bool(settings, "setting_a");
  376. p = obs_properties_get(ppts, "setting_b");
  377. obs_property_set_enabled(p, enabled);
  378. /* return true to update property widgets, false
  379. otherwise */
  380. return true;
  381. }
  382. [...]
  383. static obs_properties_t *my_source_properties(void *data)
  384. {
  385. obs_properties_t *ppts = obs_properties_create();
  386. obs_property_t *p;
  387. p = obs_properties_add_bool(ppts, "setting_a",
  388. obs_module_text("SettingA"));
  389. obs_property_set_modified_callback(p, setting_a_modified);
  390. obs_properties_add_text(ppts, "setting_b",
  391. obs_module_text("SettingB"),
  392. OBS_TEXT_DEFAULT);
  393. return ppts;
  394. }
  395. Localization
  396. ------------
  397. Typically, most plugins bundled with OBS Studio will use a simple
  398. ini-file localization method, where each file is a different language.
  399. When using this method, the :c:func:`OBS_MODULE_USE_DEFAULT_LOCALE()`
  400. macro is used which will automatically load/destroy the locale data with
  401. no extra effort on part of the plugin. Then the
  402. :c:func:`obs_module_text()` function (which is automatically declared as
  403. an extern by `libobs/obs-module.h`_) is used when text lookup is needed.
  404. There are two exports the module used to load/destroy locale: the
  405. :c:func:`obs_module_set_locale()` export, and the
  406. :c:func:`obs_module_free_locale()` export. The
  407. :c:func:`obs_module_set_locale()` export is called by libobs to set the
  408. current language, and then the :c:func:`obs_module_free_locale()` export
  409. is called by libobs on destruction of the module. If you wish to
  410. implement a custom locale implementation for your plugin, you'd want to
  411. define these exports along with the :c:func:`obs_module_text()` extern
  412. yourself instead of relying on the
  413. :c:func:`OBS_MODULE_USE_DEFAULT_LOCALE()` macro.
  414. .. ---------------------------------------------------------------------------
  415. .. _libobs/obs-module.h: https://github.com/obsproject/obs-studio/blob/master/libobs/obs-module.h
  416. .. _libobs/obs.h: https://github.com/obsproject/obs-studio/blob/master/libobs/obs.h
  417. .. _libobs/obs-source.h: https://github.com/obsproject/obs-studio/blob/master/libobs/obs-source.h
  418. .. _libobs/obs-output.h: https://github.com/obsproject/obs-studio/blob/master/libobs/obs-output.h
  419. .. _libobs/obs-encoder.h: https://github.com/obsproject/obs-studio/blob/master/libobs/obs-encoder.h
  420. .. _libobs/obs-service.h: https://github.com/obsproject/obs-studio/blob/master/libobs/obs-service.h
  421. .. _libobs/obs-data.h: https://github.com/obsproject/obs-studio/blob/master/libobs/obs-data.h
  422. .. _libobs/obs-properties.h: https://github.com/obsproject/obs-studio/blob/master/libobs/obs-properties.h
  423. .. _libobs/graphics/graphics.h: https://github.com/obsproject/obs-studio/blob/master/libobs/graphics/graphics.h