Merge pull request #186 from WizardCM/api-enhancements

JS API Enhancements

Author: jp9000

README.md

@@ -4,103 +4,171 @@ CEF Based obs-studio browser plugin
 
 ## JS Bindings
 
-obs-browser provides a global object that allows access to some obs specific functionality from javascript.
+obs-browser provides a global object that allows access to some OBS-specific functionality from JavaScript.
 
-### Get OBS Studio Browser Plugin Version
-```
-window.obsstudio.pluginVersion
-// => 1.24.0
-```
+### Get Browser Plugin Version
 
-### Register for visibility callbacks
-```
+```js
 /**
- * onVisibilityChange gets callbacks when the visibility of the browser source changes in OBS
- *
- * @param {bool} visibility - True -> visible, False -> hidden
+ * @returns {number} OBS Browser plugin version
  */
-window.obsstudio.onVisibilityChange = function(visibility) {
-	
-};
+window.obsstudio.pluginVersion
+// => 1.24.0
 ```
 
-### Register for active/inactive callbacks
-```
+### Register for event callbacks
+
+```js
 /**
- * onActiveChange gets callbacks when the active/inactive state of the browser source changes in OBS
- *
- * @param {bool} True -> active, False -> inactive
+ * @typedef {Object} OBSEvent
+ * @property {object} detail - data from event
  */
-window.obsstudio.onActiveChange = function(active) {
-	
-};
-```
 
-### Register for scene change callbacks
-```
-window.addEventListener('obsSceneChanged', function(evt) {
-	var t = document.createTextNode(evt.detail.name);
-    document.body.appendChild(t);
-});
+window.addEventListener('obsSceneChanged', function(event) {
+	var t = document.createTextNode(event.detail.name)
+	document.body.appendChild(t)
+})
 ```
-#### Other events that are available
+
+#### Available events
+
+Descriptions for these events can be [found here](https://obsproject.com/docs/reference-frontend-api.html?highlight=paused#c.obs_frontend_event).
+
+* obsSceneChanged
+* obsSourceVisibleChanged
+* obsSourceActiveChanged
 * obsStreamingStarting
 * obsStreamingStarted
 * obsStreamingStopping
 * obsStreamingStopped
 * obsRecordingStarting
 * obsRecordingStarted
+* obsRecordingPaused
+* obsRecordingUnpaused
 * obsRecordingStopping
 * obsRecordingStopped
+* obsReplaybufferStarting
+* obsReplaybufferStarted
+* obsReplaybufferStopping
+* obsReplaybufferStopped
 
 ### Get the current scene
-```
-window.obsstudio.getCurrentScene(function(data) { console.log(data); });
 
-data is a Javascript object containing the following properties:
-* width
-* height
-* name
+```js
+/**
+ * @typedef {Object} Scene
+ * @property {string} name - name of the scene
+ * @property {number} width - width of the scene
+ * @property {number} height - height of the scene
+ */
+
+/**
+ * @param {function} callback
+ * @returns {Scene}
+ */
+window.obsstudio.getCurrentScene(function(scene) {
+	console.log(scene)
+})
 ```
 
 ### Get OBS output status
+
+```js
+/**
+ * @typedef {Object} Status
+ * @property {boolean} recording - not affected by pause state
+ * @property {boolean} recordingPaused
+ * @property {boolean} streaming
+ * @property {boolean} replaybuffer
+ */
+
+/**
+ * @param {function} callback
+ * @returns {Status}
+ */
+window.obsstudio.getStatus(function (status) {
+	console.log(status)
+})
+```
+
+### Save OBS Replay Buffer
+
+```js
+/**
+ * Does not accept any parameters and does not return anything
+ */
+window.obsstudio.saveReplayBuffer()
 ```
-window.obsstudio.getStatus(function data) { console.log(data); });
 
-data is a Javascript object containing the following properties:
-* recording (true/false)
-* streaming (true/false)
-* replaybuffer (true/false)
+### Register for visibility callbacks
+
+**This method is legacy. Register an event listener instead.**
+
+```js
+/**
+ * onVisibilityChange gets callbacks when the visibility of the browser source changes in OBS
+ *
+ * @deprecated
+ * @see obsSourceVisibleChanged
+ * @param {boolean} visibility - True -> visible, False -> hidden
+ */
+window.obsstudio.onVisibilityChange = function(visibility) {
+	
+};
+```
+
+### Register for active/inactive callbacks
+
+**This method is legacy. Register an event listener instead.**
+
+```js
+/**
+ * onActiveChange gets callbacks when the active/inactive state of the browser source changes in OBS
+ *
+ * @deprecated
+ * @see obsSourceActiveChanged
+ * @param {bool} True -> active, False -> inactive
+ */
+window.obsstudio.onActiveChange = function(active) {
+	
+};
 ```
 
 ## Building on OSX
 
 ### Building CEF
+
 #### Getting
+
 *  Download CEF Mac 64 from [http://opensource.spotify.com/cefbuilds/index.html](http://opensource.spotify.com/cefbuilds/index.html)
-  *  Use CEF branch 3112
+    *  Use CEF branch 3770
 *  Extract and cd into the folder
 
 #### Setting Up Project
-```
+
+```shell
 mkdir build
 cmake -D CMAKE_XCODE_ATTRIBUTE_CLANG_CXX_LIBRARY=libc++ -G Xcode ..
 open cef.xcodeproj/
 ```
 
 #### Building
+
 Build in Xcode (⌘+B)
 
 TODO: tell user to move stuff, or update FindCEF.cmake
 
 ### Building OBS and obs-browser
+
 #### Installing Dependencies
-```
+
+```shell
 brew install ffmpeg x264 qt5 cmake
 ```
 
 #### Setting Up Project
-```
+
+```shell
 git clone --recursive https://github.com/jp9000/obs-studio.git
 cd ./obs-studio
 git clone [email protected]:kc5nra/obs-browser.git ./plugins/obs-browser
@@ -112,17 +180,21 @@ open obs-studio.xcodeproj/
 ```
 
 #### Building
+
 Build in Xcode (⌘+B)
 
 ## Building on Windows
 
 ### Building CEF
+
 #### Getting
+
 *  Download CEF Windows 64bit from [http://opensource.spotify.com/cefbuilds/index.html](http://opensource.spotify.com/cefbuilds/index.html)
   *  Use CEF branch 3440 or newer (3579 if you want shared texture support)
 *  Extract and cd into the folder
 
 #### Setting Up the Project
+
 * Run cmake-gui
   * In "where is the source code", enter in the repo directory (example: C:/Users/User/Desktop/cef_binary_3.2743.1445.gdad7c0a_windows64).
   * In "where to build the binaries", enter the repo directory path with the 'build' subdirectory (example: C:/Users/User/Desktop/cef_binary_3.2743.1445.gdad7c0a_windows64/build).
@@ -132,16 +204,21 @@ Visual Studio 12 2013 Win64, Visual Studio 14 2015 Win64 or Visual Studio 15 201
 * Open cef.sln from the 'build' subdirectory
 
 #### Building
+
 * Build at least libcef_dll_wrapper (as Release), the rest is optional and are just clients to test with
 
 ### Building OBS and obs-browser
+
 #### Follow the OBS build instructions
+
 [https://github.com/jp9000/obs-studio/wiki/Install-Instructions#windows](https://github.com/jp9000/obs-studio/wiki/Install-Instructions#windows)
 
 #### Setting Up Project
+
 * Enable BUILD_BROWSER and set the CEF_ROOT_DIR path in cmake-gui for obs-studio (example: C:/Users/User/Desktop/cef_binary_3.2743.1445.gdad7c0a_windows64)
 * * Press 'Generate' to generate Visual Studio project files in the 'build' subdirectory.
 * Open obs-studio.sln from the 'build' subdirectory
 
 #### Building
+
 Build in Visual Studio

browser-app.cpp

@@ -120,16 +120,21 @@ void BrowserApp::OnContextCreated(CefRefPtr<CefBrowser> browser,
 	obsStudioObj->SetValue("pluginVersion", pluginVersion,
 			       V8_PROPERTY_ATTRIBUTE_NONE);
 
-	CefRefPtr<CefV8Value> func =
+	CefRefPtr<CefV8Value> getCurrentScene =
 		CefV8Value::CreateFunction("getCurrentScene", this);
-	obsStudioObj->SetValue("getCurrentScene", func,
+	obsStudioObj->SetValue("getCurrentScene", getCurrentScene,
 			       V8_PROPERTY_ATTRIBUTE_NONE);
 
 	CefRefPtr<CefV8Value> getStatus =
 		CefV8Value::CreateFunction("getStatus", this);
 	obsStudioObj->SetValue("getStatus", getStatus,
 			       V8_PROPERTY_ATTRIBUTE_NONE);
 
+	CefRefPtr<CefV8Value> saveReplayBuffer =
+		CefV8Value::CreateFunction("saveReplayBuffer", this);
+	obsStudioObj->SetValue("saveReplayBuffer", saveReplayBuffer,
+			       V8_PROPERTY_ATTRIBUTE_NONE);
+
 #if !ENABLE_WASHIDDEN
 	int id = browser->GetIdentifier();
 	if (browserVis.find(id) != browserVis.end()) {
@@ -352,29 +357,14 @@ bool BrowserApp::Execute(const CefString &name, CefRefPtr<CefV8Value>,
 			 const CefV8ValueList &arguments,
 			 CefRefPtr<CefV8Value> &, CefString &)
 {
-	if (name == "getCurrentScene") {
-		if (arguments.size() == 1 && arguments[0]->IsFunction()) {
-			callbackId++;
-			callbackMap[callbackId] = arguments[0];
-		}
-
-		CefRefPtr<CefProcessMessage> msg =
-			CefProcessMessage::Create("getCurrentScene");
-		CefRefPtr<CefListValue> args = msg->GetArgumentList();
-		args->SetInt(0, callbackId);
-
-		CefRefPtr<CefBrowser> browser =
-			CefV8Context::GetCurrentContext()->GetBrowser();
-		SendBrowserProcessMessage(browser, PID_BROWSER, msg);
-
-	} else if (name == "getStatus") {
+	if (name == "getCurrentScene" || name == "getStatus" || name == "saveReplayBuffer") {
 		if (arguments.size() == 1 && arguments[0]->IsFunction()) {
 			callbackId++;
 			callbackMap[callbackId] = arguments[0];
 		}
 
 		CefRefPtr<CefProcessMessage> msg =
-			CefProcessMessage::Create("getStatus");
+			CefProcessMessage::Create(name);
 		CefRefPtr<CefListValue> args = msg->GetArgumentList();
 		args->SetInt(0, callbackId);
 

browser-client.cpp

@@ -126,8 +126,11 @@ bool BrowserClient::OnProcessMessageReceived(
 		json = Json::object{
 			{"recording", obs_frontend_recording_active()},
 			{"streaming", obs_frontend_streaming_active()},
+			{"recordingPaused", obs_frontend_recording_paused()},
 			{"replaybuffer", obs_frontend_replay_buffer_active()}};
 
+	} else if (name == "saveReplayBuffer") {
+		obs_frontend_replay_buffer_save();
 	} else {
 		return false;
 	}

obs-browser-plugin.cpp

@@ -409,7 +409,8 @@ void RegisterBrowserSource()
 
 /* ========================================================================= */
 
-extern void DispatchJSEvent(std::string eventName, std::string jsonString);
+extern void DispatchJSEvent(std::string eventName, std::string jsonString,
+			    BrowserSource *browser = nullptr);
 
 static void handle_obs_frontend_event(enum obs_frontend_event event, void *)
 {
@@ -432,12 +433,30 @@ static void handle_obs_frontend_event(enum obs_frontend_event event, void *)
 	case OBS_FRONTEND_EVENT_RECORDING_STARTED:
 		DispatchJSEvent("obsRecordingStarted", "");
 		break;
+	case OBS_FRONTEND_EVENT_RECORDING_PAUSED:
+		DispatchJSEvent("obsRecordingPaused", "");
+		break;
+	case OBS_FRONTEND_EVENT_RECORDING_UNPAUSED:
+		DispatchJSEvent("obsRecordingUnpaused", "");
+		break;
 	case OBS_FRONTEND_EVENT_RECORDING_STOPPING:
 		DispatchJSEvent("obsRecordingStopping", "");
 		break;
 	case OBS_FRONTEND_EVENT_RECORDING_STOPPED:
 		DispatchJSEvent("obsRecordingStopped", "");
 		break;
+	case OBS_FRONTEND_EVENT_REPLAY_BUFFER_STARTING:
+		DispatchJSEvent("obsReplaybufferStarting", nullptr);
+		break;
+	case OBS_FRONTEND_EVENT_REPLAY_BUFFER_STARTED:
+		DispatchJSEvent("obsReplaybufferStarted", nullptr);
+		break;
+	case OBS_FRONTEND_EVENT_REPLAY_BUFFER_STOPPING:
+		DispatchJSEvent("obsReplaybufferStopping", nullptr);
+		break;
+	case OBS_FRONTEND_EVENT_REPLAY_BUFFER_STOPPED:
+		DispatchJSEvent("obsReplaybufferStopped", nullptr);
+		break;
 	case OBS_FRONTEND_EVENT_SCENE_CHANGED: {
 		OBSSource source = obs_frontend_get_current_scene();
 		obs_source_release(source);