jp9000
/
obs-studio
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
obs-studio/libobs/obs-service.h

100 lines
2.8 KiB
C
Raw Normal View History

first commit
2013-09-30 19:37:13 -07:00
/******************************************************************************
libobs: Add services API, reduce repeated code Add API for streaming services. The services API simplifies the creation of custom service features and user interface. Custom streaming services later on will be able to do things such as: - Be able to use service-specific APIs via modules, allowing a more direct means of communicating with the service and requesting or setting service-specific information - Get URL/stream key via other means of authentication such as OAuth, or be able to build custom URLs for services that require that sort of thing. - Query information (such as viewer count, chat, follower notifications, and other information) - Set channel information (such as current game, current channel title, activating commercials) Also, I reduce some repeated code that was used for all libobs objects. This includes the name of the object, the private data, settings, as well as the signal and procedure handlers. I also switched to using linked lists for the global object lists, rather than using an array of pointers (you could say it was.. pointless.) ..Anyway, the linked list info is also stored in the shared context data structure.
2014-04-19 20:38:53 -07:00
Copyright (C) 2013-2014 by Hugh Bailey <obs.jim@gmail.com>
first commit
2013-09-30 19:37:13 -07:00
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
With the permission of my fellow contributors, I'm switching obs-studio back to GPL v2+ to prevent issues between this project and the original OBS project, and for personal reasons to avoid legal ambiguity (not political reasons, I admittedly would prefer GPL v3+)
2013-12-02 21:24:38 -08:00
the Free Software Foundation, either version 2 of the License, or
first commit
2013-09-30 19:37:13 -07:00
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
******************************************************************************/
modernize header guards to #pragma once
2013-10-14 04:21:15 -07:00
#pragma once
first commit
2013-09-30 19:37:13 -07:00
Some documentation improvements to obs-service.h
2014-10-12 11:02:23 -07:00
/**
* @file
* @brief header for modules implementing services.
*
* Services are modules that implement provider specific settings for outputs.
*/
libobs: Use extern "C" on export headers if C++ I neglected to surround some files with extern "C", so if something written with C++ used the files it would cause function exports to not be mangled by it correctly.
2014-12-18 11:50:04 -08:00
#ifdef __cplusplus
extern "C" {
#endif
libobs: Change service max res. to res. list (This commit also modifies rtmp-services and UI) Changes the maximum resolution size to a resolution list, and splits the maximum FPS to its own function. (Note: ABI has not been modified because the last changes still haven't been released yet, so it's safe to modify this as long as the changes haven't been officially released)
2020-11-13 09:15:41 -08:00
struct obs_service_resolution {
int cx;
int cy;
};
Revamp API and start using doxygen The API used to be designed in such a way to where it would expect exports for each individual source/output/encoder/etc. You would export functions for each and it would automatically load those functions based on a specific naming scheme from the module. The idea behind this was that I wanted to limit the usage of structures in the API so only functions could be used. It was an interesting idea in theory, but this idea turned out to be flawed in a number of ways: 1.) Requiring exports to create sources/outputs/encoders/etc meant that you could not create them by any other means, which meant that things like faruton's .net plugin would become difficult. 2.) Export function declarations could not be checked, therefore if you created a function with the wrong parameters and parameter types, the compiler wouldn't know how to check for that. 3.) Required overly complex load functions in libobs just to handle it. It makes much more sense to just have a load function that you call manually. Complexity is the bane of all good programs. 4.) It required that you have functions of specific names, which looked and felt somewhat unsightly. So, to fix these issues, I replaced it with a more commonly used API scheme, seen commonly in places like kernels and typical C libraries with abstraction. You simply create a structure that contains the callback definitions, and you pass it to a function to register that definition (such as obs_register_source), which you call in the obs_module_load of the module. It will also automatically check the structure size and ensure that it only loads the required values if the structure happened to add new values in an API change. The "main" source file for each module must include obs-module.h, and must use OBS_DECLARE_MODULE() within that source file. Also, started writing some doxygen documentation in to the main library headers. Will add more detailed documentation as I go.
2014-02-12 07:04:50 -08:00
struct obs_service_info {
/* required */
libobs: Add services API, reduce repeated code Add API for streaming services. The services API simplifies the creation of custom service features and user interface. Custom streaming services later on will be able to do things such as: - Be able to use service-specific APIs via modules, allowing a more direct means of communicating with the service and requesting or setting service-specific information - Get URL/stream key via other means of authentication such as OAuth, or be able to build custom URLs for services that require that sort of thing. - Query information (such as viewer count, chat, follower notifications, and other information) - Set channel information (such as current game, current channel title, activating commercials) Also, I reduce some repeated code that was used for all libobs objects. This includes the name of the object, the private data, settings, as well as the signal and procedure handlers. I also switched to using linked lists for the global object lists, rather than using an array of pointers (you could say it was.. pointless.) ..Anyway, the linked list info is also stored in the shared context data structure.
2014-04-19 20:38:53 -07:00
const char *id;
add names to sources, use 'id' for the internal source identifier names rather than 'name'
2013-12-20 16:23:19 -08:00
(API Change) libobs: Pass type data to get_name callbacks API changed from: obs_source_info::get_name(void) obs_output_info::get_name(void) obs_encoder_info::get_name(void) obs_service_info::get_name(void) API changed to: obs_source_info::get_name(void *type_data) obs_output_info::get_name(void *type_data) obs_encoder_info::get_name(void *type_data) obs_service_info::get_name(void *type_data) This allows the type data to be used when getting the name of the object (useful for plugin wrappers primarily). NOTE: Though a parameter was added, this is backward-compatible with older plugins due to calling convention. The new parameter will simply be ignored by older plugins, and the stack (if used) will be cleaned up by the caller.
2015-09-16 01:30:51 -07:00
const char *(*get_name)(void *type_data);
(API Change) Remove pointers from all typedefs Typedef pointers are unsafe. If you do: typedef struct bla *bla_t; then you cannot use it as a constant, such as: const bla_t, because that constant will be to the pointer itself rather than to the underlying data. I admit this was a fundamental mistake that must be corrected. All typedefs that were pointer types will now have their pointers removed from the type itself, and the pointers will be used when they are actually used as variables/parameters/returns instead. This does not break ABI though, which is pretty nice.
2014-09-25 17:44:05 -07:00
void *(*create)(obs_data_t *settings, obs_service_t *service);
first commit
2013-09-30 19:37:13 -07:00
void (*destroy)(void *data);
Revamp API and start using doxygen The API used to be designed in such a way to where it would expect exports for each individual source/output/encoder/etc. You would export functions for each and it would automatically load those functions based on a specific naming scheme from the module. The idea behind this was that I wanted to limit the usage of structures in the API so only functions could be used. It was an interesting idea in theory, but this idea turned out to be flawed in a number of ways: 1.) Requiring exports to create sources/outputs/encoders/etc meant that you could not create them by any other means, which meant that things like faruton's .net plugin would become difficult. 2.) Export function declarations could not be checked, therefore if you created a function with the wrong parameters and parameter types, the compiler wouldn't know how to check for that. 3.) Required overly complex load functions in libobs just to handle it. It makes much more sense to just have a load function that you call manually. Complexity is the bane of all good programs. 4.) It required that you have functions of specific names, which looked and felt somewhat unsightly. So, to fix these issues, I replaced it with a more commonly used API scheme, seen commonly in places like kernels and typical C libraries with abstraction. You simply create a structure that contains the callback definitions, and you pass it to a function to register that definition (such as obs_register_source), which you call in the obs_module_load of the module. It will also automatically check the structure size and ensure that it only loads the required values if the structure happened to add new values in an API change. The "main" source file for each module must include obs-module.h, and must use OBS_DECLARE_MODULE() within that source file. Also, started writing some doxygen documentation in to the main library headers. Will add more detailed documentation as I go.
2014-02-12 07:04:50 -08:00
/* optional */
(API Change) Remove pointers from all typedefs Typedef pointers are unsafe. If you do: typedef struct bla *bla_t; then you cannot use it as a constant, such as: const bla_t, because that constant will be to the pointer itself rather than to the underlying data. I admit this was a fundamental mistake that must be corrected. All typedefs that were pointer types will now have their pointers removed from the type itself, and the pointers will be used when they are actually used as variables/parameters/returns instead. This does not break ABI though, which is pretty nice.
2014-09-25 17:44:05 -07:00
void (*activate)(void *data, obs_data_t *settings);
obs-studio UI: Implement stream settings UI - Updated the services API so that it links up with an output and the output gets data from that service rather than via settings. This allows the service context to have control over how an output is used, and makes it so that the URL/key/etc isn't necessarily some static setting. Also, if the service is attached to an output, it will stick around until the output is destroyed. - The settings interface has been updated so that it can allow the usage of service plugins. What this means is that now you can create a service plugin that can control aspects of the stream, and it allows each service to create their own user interface if they create a service plugin module. - Testing out saving of current service information. Saves/loads from JSON in to obs_data_t, seems to be working quite nicely, and the service object information is saved/preserved on exit, and loaded again on startup. - I agonized over the settings user interface for days, and eventually I just decided that the only way that users weren't going to be fumbling over options was to split up the settings in to simple/basic output, pre-configured, and then advanced for advanced use (such as multiple outputs or services, which I'll implement later). This was particularly painful to really design right, I wanted more features and wanted to include everything in one interface but ultimately just realized from experience that users are just not technically knowledgable about it and will end up fumbling with the settings rather than getting things done. Basically, what this means is that casual users only have to enter in about 3 things to configure their stream: Stream key, audio bitrate, and video bitrate. I am really happy with this interface for those types of users, but it definitely won't be sufficient for advanced usage or for custom outputs, so that stuff will have to be separated. - Improved the JSON usage for the 'common streaming services' context, I realized that JSON arrays are there to ensure sorting, while forgetting that general items are optimized for hashing. So basically I'm just using arrays now to sort items in it.
2014-04-24 01:49:07 -07:00
void (*deactivate)(void *data);
(API Change) Remove pointers from all typedefs Typedef pointers are unsafe. If you do: typedef struct bla *bla_t; then you cannot use it as a constant, such as: const bla_t, because that constant will be to the pointer itself rather than to the underlying data. I admit this was a fundamental mistake that must be corrected. All typedefs that were pointer types will now have their pointers removed from the type itself, and the pointers will be used when they are actually used as variables/parameters/returns instead. This does not break ABI though, which is pretty nice.
2014-09-25 17:44:05 -07:00
void (*update)(void *data, obs_data_t *settings);
cleaned up main internal data structure design, changed to reference counting for sources to ensure safe destruction of source objects from all parts of the system, added some service-related stuff for testing
2013-11-20 14:00:16 -08:00
(API Change) Remove pointers from all typedefs Typedef pointers are unsafe. If you do: typedef struct bla *bla_t; then you cannot use it as a constant, such as: const bla_t, because that constant will be to the pointer itself rather than to the underlying data. I admit this was a fundamental mistake that must be corrected. All typedefs that were pointer types will now have their pointers removed from the type itself, and the pointers will be used when they are actually used as variables/parameters/returns instead. This does not break ABI though, which is pretty nice.
2014-09-25 17:44:05 -07:00
void (*get_defaults)(obs_data_t *settings);
libobs: Add services API, reduce repeated code Add API for streaming services. The services API simplifies the creation of custom service features and user interface. Custom streaming services later on will be able to do things such as: - Be able to use service-specific APIs via modules, allowing a more direct means of communicating with the service and requesting or setting service-specific information - Get URL/stream key via other means of authentication such as OAuth, or be able to build custom URLs for services that require that sort of thing. - Query information (such as viewer count, chat, follower notifications, and other information) - Set channel information (such as current game, current channel title, activating commercials) Also, I reduce some repeated code that was used for all libobs objects. This includes the name of the object, the private data, settings, as well as the signal and procedure handlers. I also switched to using linked lists for the global object lists, rather than using an array of pointers (you could say it was.. pointless.) ..Anyway, the linked list info is also stored in the shared context data structure.
2014-04-19 20:38:53 -07:00
(API Change) Pass data to get_properties when possible
2014-09-29 08:36:13 -07:00
obs_properties_t *(*get_properties)(void *data);
libobs: Add services API, reduce repeated code Add API for streaming services. The services API simplifies the creation of custom service features and user interface. Custom streaming services later on will be able to do things such as: - Be able to use service-specific APIs via modules, allowing a more direct means of communicating with the service and requesting or setting service-specific information - Get URL/stream key via other means of authentication such as OAuth, or be able to build custom URLs for services that require that sort of thing. - Query information (such as viewer count, chat, follower notifications, and other information) - Set channel information (such as current game, current channel title, activating commercials) Also, I reduce some repeated code that was used for all libobs objects. This includes the name of the object, the private data, settings, as well as the signal and procedure handlers. I also switched to using linked lists for the global object lists, rather than using an array of pointers (you could say it was.. pointless.) ..Anyway, the linked list info is also stored in the shared context data structure.
2014-04-19 20:38:53 -07:00
libobs: Add 'initialize' callback to services The 'initialize' callback is used before the encoders/output start up so it can adjust encoder settings to required values if needed. Also added the function 'obs_encoder_active' that returns true or false depending on whether that encoder is active or not.
2014-06-16 21:29:11 -07:00
/**
* Called when getting ready to start up an output, before the encoders
* and output are initialized
*
* @param data Internal service data
* @param output Output context
docs/sphinx: Fix various typos (This modifies UI, libobs, deps/obs-scripting, various cmake files) Found using: `codespell -q 3 -S *.ini,./UI/data/locale,./deps/w32-pthreads -L aci,dur,iff,mut,numer,uint`
2019-09-19 04:31:17 -07:00
* @return true to allow the output to start up,
libobs: Add 'initialize' callback to services The 'initialize' callback is used before the encoders/output start up so it can adjust encoder settings to required values if needed. Also added the function 'obs_encoder_active' that returns true or false depending on whether that encoder is active or not.
2014-06-16 21:29:11 -07:00
* false to prevent output from starting up
*/
(API Change) Remove pointers from all typedefs Typedef pointers are unsafe. If you do: typedef struct bla *bla_t; then you cannot use it as a constant, such as: const bla_t, because that constant will be to the pointer itself rather than to the underlying data. I admit this was a fundamental mistake that must be corrected. All typedefs that were pointer types will now have their pointers removed from the type itself, and the pointers will be used when they are actually used as variables/parameters/returns instead. This does not break ABI though, which is pretty nice.
2014-09-25 17:44:05 -07:00
bool (*initialize)(void *data, obs_output_t *output);
libobs: Add 'initialize' callback to services The 'initialize' callback is used before the encoders/output start up so it can adjust encoder settings to required values if needed. Also added the function 'obs_encoder_active' that returns true or false depending on whether that encoder is active or not.
2014-06-16 21:29:11 -07:00
Add preliminary FLV/RTMP output (incomplete) - obs-outputs module: Add preliminary code to send out data, and add an FLV muxer. This time we don't really need to build the packets ourselves, we can just use the FLV muxer and send it directly to RTMP_Write and it should automatically parse the entire stream for us without us having to do much manual code at all. We'll see how it goes. - libobs: Add AVC NAL packet parsing code - libobs/media-io: Add quick helper functions for audio/video to get the width/height/fps/samplerate/etc rather than having to query the info structures each time. - libobs (obs-output.c): Change 'connect' signal to 'start' and 'stop' signals. 'start' now specifies an error code rather than whether it simply failed, that way the client can actually know *why* a failure occurred. Added those error codes to obs-defs.h. - libobs: Add a few functions to duplicate/free encoder packets
2014-04-01 11:55:18 -07:00
const char *(*get_url)(void *data);
const char *(*get_key)(void *data);
obs-studio UI: Implement stream settings UI - Updated the services API so that it links up with an output and the output gets data from that service rather than via settings. This allows the service context to have control over how an output is used, and makes it so that the URL/key/etc isn't necessarily some static setting. Also, if the service is attached to an output, it will stick around until the output is destroyed. - The settings interface has been updated so that it can allow the usage of service plugins. What this means is that now you can create a service plugin that can control aspects of the stream, and it allows each service to create their own user interface if they create a service plugin module. - Testing out saving of current service information. Saves/loads from JSON in to obs_data_t, seems to be working quite nicely, and the service object information is saved/preserved on exit, and loaded again on startup. - I agonized over the settings user interface for days, and eventually I just decided that the only way that users weren't going to be fumbling over options was to split up the settings in to simple/basic output, pre-configured, and then advanced for advanced use (such as multiple outputs or services, which I'll implement later). This was particularly painful to really design right, I wanted more features and wanted to include everything in one interface but ultimately just realized from experience that users are just not technically knowledgable about it and will end up fumbling with the settings rather than getting things done. Basically, what this means is that casual users only have to enter in about 3 things to configure their stream: Stream key, audio bitrate, and video bitrate. I am really happy with this interface for those types of users, but it definitely won't be sufficient for advanced usage or for custom outputs, so that stuff will have to be separated. - Improved the JSON usage for the 'common streaming services' context, I realized that JSON arrays are there to ensure sorting, while forgetting that general items are optimized for hashing. So basically I'm just using arrays now to sort items in it.
2014-04-24 01:49:07 -07:00
const char *(*get_username)(void *data);
const char *(*get_password)(void *data);
libobs: Deprecate service multitrack check This isn't particularly needed, as a service with multiple tracks won't be using multiple tracks to begin with anyway. This might change later, but for now just mark it deprecated.
2020-09-07 13:36:25 -07:00
bool (*deprecated_1)();
libobs: Add API to apply service encoder settings Instead of having services automatically apply encoder settings on initialization (whether the output wants to or not), instead make it something that must be explicitly called by the developer. There are cases where the developer may not wish to apply the service-specific settings, or may wish to override them for whatever reason.
2015-02-10 19:23:36 -08:00
(API Change) Fix "apply service settings" functions API changed from: ------------------------ EXPORT void obs_service_apply_encoder_settings(obs_service_t *service, obs_encoder_t *video_encoder, obs_encoder_t *audio_encoder); void obs_service_info::apply_encoder_settings(void *data obs_encoder_t *video_encoder, obs_encoder_t *audio_encoder); To: ------------------------ EXPORT void obs_service_apply_encoder_settings(obs_service_t *service, obs_data_t *video_encoder_settings, obs_data_t *audio_encoder_settings); void obs_service_info::apply_encoder_settings(void *data obs_data_t *video_encoder_settings, obs_data_t *audio_encoder_settings); These changes make it so that instead of an encoder potentially being updated more than once with different settings, that these functions will be called for the specific settings being used, and the settings will be updated according to what's required by the service. This fixes that design flaw and ensures that there's no case where obs_encoder_update is called where the settings might not have service-specific settings applied.
2015-03-07 16:32:00 -08:00
void (*apply_encoder_settings)(void *data,
clang-format: Apply formatting Code submissions have continually suffered from formatting inconsistencies that constantly have to be addressed. Using clang-format simplifies this by making code formatting more consistent, and allows automation of the code formatting so that maintainers can focus more on the code itself instead of code formatting.
2019-06-22 22:13:45 -07:00
obs_data_t *video_encoder_settings,
obs_data_t *audio_encoder_settings);
libobs: Add API to apply service encoder settings Instead of having services automatically apply encoder settings on initialization (whether the output wants to or not), instead make it something that must be explicitly called by the developer. There are cases where the developer may not wish to apply the service-specific settings, or may wish to override them for whatever reason.
2015-02-10 19:23:36 -08:00
libobs: Add private data to definition structures This is useful for allowing the ability to have private data associated with the object type definition structures. This private data can be useful for things like plugin wrappers for other languages, or providing dynamically generated object types.
2015-09-15 22:39:11 -07:00
void *type_data;
void (*free_type_data)(void *type_data);
libobs: Add ability for service to specify its output type Allows the ability to change the output type in case one service requires a different output type. NOTE: This should be considered a temporarily yet simple solution to a specific problem: support for RTMP-like outputs. This will allows seamless integration of supporting different RTMP-like output types within the same service. This should probably be replaced with a more ideal solution later, such as implementing a completely different service type instead, when time permits.
2017-07-12 23:41:06 -07:00
const char *(*get_output_type)(void *data);
libobs: Change service max res. to res. list (This commit also modifies rtmp-services and UI) Changes the maximum resolution size to a resolution list, and splits the maximum FPS to its own function. (Note: ABI has not been modified because the last changes still haven't been released yet, so it's safe to modify this as long as the changes haven't been officially released)
2020-11-13 09:15:41 -08:00
void (*get_supported_resolutions)(
void *data, struct obs_service_resolution **resolutions,
size_t *count);
void (*get_max_fps)(void *data, int *fps);
libobs: Implement obs_service func to get max bitrates (This commit also modifies rtmp-services) Implements obs_service_get_max_bitrate, which allows retrieving the maximum audio/video bitrates directly rather than being forced to use the apply method. Makes it a bit easier to get the bitrate values.
2020-11-11 09:40:24 -08:00
void (*get_max_bitrate)(void *data, int *video_bitrate,
int *audio_bitrate);
first commit
2013-09-30 19:37:13 -07:00
};
libobs: Add services API, reduce repeated code Add API for streaming services. The services API simplifies the creation of custom service features and user interface. Custom streaming services later on will be able to do things such as: - Be able to use service-specific APIs via modules, allowing a more direct means of communicating with the service and requesting or setting service-specific information - Get URL/stream key via other means of authentication such as OAuth, or be able to build custom URLs for services that require that sort of thing. - Query information (such as viewer count, chat, follower notifications, and other information) - Set channel information (such as current game, current channel title, activating commercials) Also, I reduce some repeated code that was used for all libobs objects. This includes the name of the object, the private data, settings, as well as the signal and procedure handlers. I also switched to using linked lists for the global object lists, rather than using an array of pointers (you could say it was.. pointless.) ..Anyway, the linked list info is also stored in the shared context data structure.
2014-04-19 20:38:53 -07:00
EXPORT void obs_register_service_s(const struct obs_service_info *info,
clang-format: Apply formatting Code submissions have continually suffered from formatting inconsistencies that constantly have to be addressed. Using clang-format simplifies this by making code formatting more consistent, and allows automation of the code formatting so that maintainers can focus more on the code itself instead of code formatting.
2019-06-22 22:13:45 -07:00
size_t size);
libobs: Add services API, reduce repeated code Add API for streaming services. The services API simplifies the creation of custom service features and user interface. Custom streaming services later on will be able to do things such as: - Be able to use service-specific APIs via modules, allowing a more direct means of communicating with the service and requesting or setting service-specific information - Get URL/stream key via other means of authentication such as OAuth, or be able to build custom URLs for services that require that sort of thing. - Query information (such as viewer count, chat, follower notifications, and other information) - Set channel information (such as current game, current channel title, activating commercials) Also, I reduce some repeated code that was used for all libobs objects. This includes the name of the object, the private data, settings, as well as the signal and procedure handlers. I also switched to using linked lists for the global object lists, rather than using an array of pointers (you could say it was.. pointless.) ..Anyway, the linked list info is also stored in the shared context data structure.
2014-04-19 20:38:53 -07:00
#define obs_register_service(info) \
obs_register_service_s(info, sizeof(struct obs_service_info))
libobs: Use extern "C" on export headers if C++ I neglected to surround some files with extern "C", so if something written with C++ used the files it would cause function exports to not be mangled by it correctly.
2014-12-18 11:50:04 -08:00
#ifdef __cplusplus
}
#endif