reference-services.rst 9.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291
  1. Service API Reference (obs_service_t)
  2. =====================================
  3. Services are custom implementations of streaming services, which are
  4. used with outputs that stream. For example, you could have a custom
  5. implementation for streaming to Twitch, and another for YouTube to allow
  6. the ability to log in and use their APIs to do things such as get the
  7. RTMP servers or control the channel. The `libobs/obs-service.h`_ file
  8. is the dedicated header for implementing services.
  9. *(Author's note: the service API is incomplete as of this writing)*
  10. .. type:: obs_service_t
  11. A reference-counted service object.
  12. .. type:: obs_weak_service_t
  13. A weak reference to a service object.
  14. .. code:: cpp
  15. #include <obs.h>
  16. Service Definition Structure
  17. ----------------------------
  18. .. type:: struct obs_service_info
  19. Service definition structure.
  20. .. member:: const char *obs_service_info.id
  21. Unique string identifier for the service (required).
  22. .. member:: const char *(*obs_service_info.get_name)(void *type_data)
  23. Get the translated name of the service type.
  24. :param type_data: The type_data variable of this structure
  25. :return: The translated name of the service type
  26. .. member:: void *(*obs_service_info.create)(obs_data_t *settings, obs_service_t *service)
  27. Creates the implementation data for the service.
  28. :param settings: Settings to initialize the service with
  29. :param service: Source that this data is associated with
  30. :return: The implementation data associated with this service
  31. .. member:: void (*obs_service_info.destroy)(void *data)
  32. Destroys the implementation data for the service.
  33. .. member:: void (*obs_service_info.get_defaults)(obs_data_t *settings)
  34. void (*obs_service_info.get_defaults2)(void *type_data, obs_data_t *settings)
  35. Sets the default settings for this service.
  36. :param settings: Default settings. Call obs_data_set_default*
  37. functions on this object to set default setting
  38. values
  39. .. member:: obs_properties_t *(*obs_service_info.get_properties)(void *data)
  40. obs_properties_t *(*obs_service_info.get_properties2)(void *data, void *type_data)
  41. Gets the property information of this service.
  42. (Optional)
  43. :return: The properties of the service
  44. .. member:: void (*obs_service_info.update)(void *data, obs_data_t *settings)
  45. Updates the settings for this service.
  46. (Optional)
  47. :param settings: New settings for this service
  48. .. member:: bool (*obs_service_info.initialize)(void *data, obs_output_t *output)
  49. Called when getting ready to start up an output, before the encoders
  50. and output are initialized.
  51. (Optional)
  52. :param output: Output context to use this service with
  53. :return: *true* to allow the output to start up,
  54. *false* to prevent output from starting up
  55. .. member:: const char *(*obs_service_info.get_url)(void *data)
  56. :return: The stream URL
  57. .. member:: const char *(*obs_service_info.get_key)(void *data)
  58. :return: The stream key
  59. .. member:: const char *(*obs_service_info.get_username)(void *data)
  60. (Optional)
  61. :return: The username
  62. .. member:: const char *(*obs_service_info.get_password)(void *data)
  63. (Optional)
  64. :return: The password
  65. .. member:: void (*obs_service_info.apply_encoder_settings)(void *data, obs_data_t *video_encoder_settings, obs_data_t *audio_encoder_settings)
  66. This function is called to apply custom encoder settings specific to
  67. this service. For example, if a service requires a specific keyframe
  68. interval, or has a bitrate limit, the settings for the video and
  69. audio encoders can be optionally modified if the front-end optionally
  70. calls :c:func:`obs_service_apply_encoder_settings()`.
  71. (Optional)
  72. :param video_encoder_settings: The audio encoder settings to change
  73. :param audio_encoder_settings: The video encoder settings to change
  74. .. member:: void *obs_service_info.type_data
  75. void (*obs_service_info.free_type_data)(void *type_data)
  76. Private data associated with this entry. Note that this is not the
  77. same as the implementation data; this is used to differentiate
  78. between two different types if the same callbacks are used for more
  79. than one different type.
  80. (Optional)
  81. .. member:: const char *(*obs_service_info.get_output_type)(void *data)
  82. (Optional)
  83. :return: The output type that should be used with this service
  84. General Service Functions
  85. -------------------------
  86. .. function:: void obs_register_service(struct obs_service_info *info)
  87. Registers a service type. Typically used in
  88. :c:func:`obs_module_load()` or in the program's initialization phase.
  89. ---------------------
  90. .. function:: const char *obs_service_get_display_name(const char *id)
  91. Calls the :c:member:`obs_service_info.get_name` callback to get the
  92. translated display name of a service type.
  93. :param id: The service type string identifier
  94. :return: The translated display name of a service type
  95. ---------------------
  96. .. function:: obs_service_t *obs_service_create(const char *id, const char *name, obs_data_t *settings, obs_data_t *hotkey_data)
  97. Creates a service with the specified settings.
  98. The "service" context is used for encoding video/audio data. Use
  99. obs_service_release to release it.
  100. :param id: The service type string identifier
  101. :param name: The desired name of the service. If this is
  102. not unique, it will be made to be unique
  103. :param settings: The settings for the service, or *NULL* if
  104. none
  105. :param hotkey_data: Saved hotkey data for the service, or *NULL*
  106. if none
  107. :return: A reference to the newly created service, or
  108. *NULL* if failed
  109. ---------------------
  110. .. function:: void obs_service_addref(obs_service_t *service)
  111. Adds a reference to a service.
  112. .. deprecated:: 27.2.0
  113. Use :c:func:`obs_service_get_ref()` instead.
  114. ---------------------
  115. .. function:: obs_service_t *obs_service_get_ref(obs_service_t *service)
  116. Returns an incremented reference if still valid, otherwise returns
  117. *NULL*.
  118. ---------------------
  119. .. function:: void obs_service_release(obs_service_t *service)
  120. Releases a reference to a service. When the last reference is
  121. released, the service is destroyed.
  122. ---------------------
  123. .. function:: obs_weak_service_t *obs_service_get_weak_service(obs_service_t *service)
  124. obs_service_t *obs_weak_service_get_service(obs_weak_service_t *weak)
  125. These functions are used to get a weak reference from a strong service
  126. reference, or a strong service reference from a weak reference. If
  127. the service is destroyed, *obs_weak_service_get_service* will return
  128. *NULL*.
  129. ---------------------
  130. .. function:: void obs_weak_service_addref(obs_weak_service_t *weak)
  131. void obs_weak_service_release(obs_weak_service_t *weak)
  132. Adds/releases a weak reference to a service.
  133. ---------------------
  134. .. function:: const char *obs_service_get_name(const obs_service_t *service)
  135. :return: The name of the service
  136. ---------------------
  137. .. function:: obs_data_t *obs_service_defaults(const char *id)
  138. :return: An incremented reference to the service's default settings
  139. ---------------------
  140. .. function:: obs_properties_t *obs_service_properties(const obs_service_t *service)
  141. obs_properties_t *obs_get_service_properties(const char *id)
  142. Use these functions to get the properties of a service or service
  143. type. Properties are optionally used (if desired) to automatically
  144. generate user interface widgets to allow users to update settings.
  145. :return: The properties list for a specific existing service. Free
  146. with :c:func:`obs_properties_destroy()`
  147. ---------------------
  148. .. function:: obs_data_t *obs_service_get_settings(const obs_service_t *service)
  149. :return: An incremented reference to the service's settings
  150. ---------------------
  151. .. function:: void obs_service_update(obs_service_t *service, obs_data_t *settings)
  152. Updates the settings for this service context.
  153. ---------------------
  154. .. function:: const char *obs_service_get_url(const obs_service_t *service)
  155. :return: The URL currently used for this service
  156. ---------------------
  157. .. function:: const char *obs_service_get_key(const obs_service_t *service)
  158. :return: Stream key (if any) currently used for this service
  159. ---------------------
  160. .. function:: const char *obs_service_get_username(const obs_service_t *service)
  161. :return: User name (if any) currently used for this service
  162. ---------------------
  163. .. function:: const char *obs_service_get_password(const obs_service_t *service)
  164. :return: Password (if any) currently used for this service
  165. ---------------------
  166. .. function:: void obs_service_apply_encoder_settings(obs_service_t *service, obs_data_t *video_encoder_settings, obs_data_t *audio_encoder_settings)
  167. Applies service-specific video encoder settings.
  168. :param video_encoder_settings: Video encoder settings. Can be *NULL*
  169. :param audio_encoder_settings: Audio encoder settings. Can be *NULL*
  170. .. ---------------------------------------------------------------------------
  171. .. _libobs/obs-service.h: https://github.com/jp9000/obs-studio/blob/master/libobs/obs-service.h