Events, Docs: Refactor media events and improve docs

Move duplicated functionality to a helper function and added some docs
clarifying the behavior of the events, and fixed a few typos in
the request handlers.

src/WSEvents.cpp

@@ -425,6 +425,16 @@ QString WSEvents::getRecordingTimecode() {
 	return Utils::nsToTimestamp(getRecordingTime());
 }
 
+OBSDataAutoRelease getMediaSourceData(calldata_t* data) {
+	OBSDataAutoRelease fields = obs_data_create();
+	OBSSource source = calldata_get_pointer<obs_source_t>(data, "source");
+
+	obs_data_set_string(fields, "sourceName", obs_source_get_name(source));
+	obs_data_set_string(fields, "sourceTypeId", obs_source_get_id(source));
+
+	return fields;
+}
+
  /**
  * Indicates a scene change.
  *
@@ -1359,7 +1369,10 @@ void WSEvents::OnSourceFilterOrderChanged(void* param, calldata_t* data) {
 /**
  * A media source has started playing.
  *
+ * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.
+ *
  * @return {String} `sourceName` Source name
+ * @return {String} `sourceTypeId` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)
  *
  * @api events
  * @name MediaPlaying
@@ -1369,20 +1382,18 @@ void WSEvents::OnSourceFilterOrderChanged(void* param, calldata_t* data) {
 void WSEvents::OnMediaPlaying(void* param, calldata_t* data) {
 	auto self = reinterpret_cast<WSEvents*>(param);
 
-	OBSSource source = calldata_get_pointer<obs_source_t>(data, "source");
+	OBSDataAutoRelease fields = getMediaSourceData(data);
-	if (!source) {
-		return;
-	}
 
-	OBSDataAutoRelease fields = obs_data_create();
-	obs_data_set_string(fields, "sourceName", obs_source_get_name(source));
 	self->broadcastUpdate("MediaPlaying", fields);
 }
 
 /**
  * A media source has been paused.
  *
+ * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.
+ *
  * @return {String} `sourceName` Source name
+ * @return {String} `sourceTypeId` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)
  *
  * @api events
  * @name MediaPaused
@@ -1392,20 +1403,18 @@ void WSEvents::OnMediaPlaying(void* param, calldata_t* data) {
 void WSEvents::OnMediaPaused(void* param, calldata_t* data) {
 	auto self = reinterpret_cast<WSEvents*>(param);
 
-	OBSSource source = calldata_get_pointer<obs_source_t>(data, "source");
+	OBSDataAutoRelease fields = getMediaSourceData(data);
-	if (!source) {
-		return;
-	}
 
-	OBSDataAutoRelease fields = obs_data_create();
-	obs_data_set_string(fields, "sourceName", obs_source_get_name(source));
 	self->broadcastUpdate("MediaPaused", fields);
 }
 
 /**
  * A media source has been restarted.
  *
+ * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.
+ *
  * @return {String} `sourceName` Source name
+ * @return {String} `sourceTypeId` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)
  *
  * @api events
  * @name MediaRestarted
@@ -1415,20 +1424,18 @@ void WSEvents::OnMediaPaused(void* param, calldata_t* data) {
 void WSEvents::OnMediaRestarted(void* param, calldata_t* data) {
 	auto self = reinterpret_cast<WSEvents*>(param);
 
-	OBSSource source = calldata_get_pointer<obs_source_t>(data, "source");
+	OBSDataAutoRelease fields = getMediaSourceData(data);
-	if (!source) {
-		return;
-	}
 
-	OBSDataAutoRelease fields = obs_data_create();
-	obs_data_set_string(fields, "sourceName", obs_source_get_name(source));
 	self->broadcastUpdate("MediaRestarted", fields);
 }
 
 /**
  * A media source has been stopped.
  *
+ * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.
+ *
  * @return {String} `sourceName` Source name
+ * @return {String} `sourceTypeId` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)
  *
  * @api events
  * @name MediaStopped
@@ -1438,20 +1445,18 @@ void WSEvents::OnMediaRestarted(void* param, calldata_t* data) {
 void WSEvents::OnMediaStopped(void* param, calldata_t* data) {
 	auto self = reinterpret_cast<WSEvents*>(param);
 
-	OBSSource source = calldata_get_pointer<obs_source_t>(data, "source");
+	OBSDataAutoRelease fields = getMediaSourceData(data);
-	if (!source) {
-		return;
-	}
 
-	OBSDataAutoRelease fields = obs_data_create();
-	obs_data_set_string(fields, "sourceName", obs_source_get_name(source));
 	self->broadcastUpdate("MediaStopped", fields);
 }
 
 /**
  * A media source has gone to the next item in the playlist.
  *
+ * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.
+ *
  * @return {String} `sourceName` Source name
+ * @return {String} `sourceTypeId` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)
  *
  * @api events
  * @name MediaNext
@@ -1461,20 +1466,18 @@ void WSEvents::OnMediaStopped(void* param, calldata_t* data) {
 void WSEvents::OnMediaNext(void* param, calldata_t* data) {
 	auto self = reinterpret_cast<WSEvents*>(param);
 
-	OBSSource source = calldata_get_pointer<obs_source_t>(data, "source");
+	OBSDataAutoRelease fields = getMediaSourceData(data);
-	if (!source) {
-		return;
-	}
 
-	OBSDataAutoRelease fields = obs_data_create();
-	obs_data_set_string(fields, "sourceName", obs_source_get_name(source));
 	self->broadcastUpdate("MediaNext", fields);
 }
 
 /**
  * A media source has gone to the previous item in the playlist.
  *
+ * Note: This event is only emitted when something actively controls the media/VLC source. In other words, the source will never emit this on its own naturally.
+ *
  * @return {String} `sourceName` Source name
+ * @return {String} `sourceTypeId` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)
  *
  * @api events
  * @name MediaPrevious
@@ -1484,23 +1487,18 @@ void WSEvents::OnMediaNext(void* param, calldata_t* data) {
 void WSEvents::OnMediaPrevious(void* param, calldata_t* data) {
 	auto self = reinterpret_cast<WSEvents*>(param);
 
-	OBSSource source = calldata_get_pointer<obs_source_t>(data, "source");
+	OBSDataAutoRelease fields = getMediaSourceData(data);
-	if (!source) {
-		return;
-	}
 
-	OBSDataAutoRelease fields = obs_data_create();
-	obs_data_set_string(fields, "sourceName", obs_source_get_name(source));
 	self->broadcastUpdate("MediaPrevious", fields);
 }
 
 /**
- * A media source has been started. (Does not mean that it is playing. See [`MediaPlaying`](#mediaplaying))
+ * A media source has been started.
- * 
+ *
- * Note: For VLC, this means that the source and therefore playlist has started.
+ * Note: These events are emitted by the OBS sources themselves. For example when the media file starts playing. The behavior depends on the type of media source being used.
- * For the normal Media Source, this just means that the source has been started. 
  *
  * @return {String} `sourceName` Source name
+ * @return {String} `sourceTypeId` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)
  *
  * @api events
  * @name MediaStarted
@@ -1510,23 +1508,18 @@ void WSEvents::OnMediaPrevious(void* param, calldata_t* data) {
 void WSEvents::OnMediaStarted(void* param, calldata_t* data) {
 	auto self = reinterpret_cast<WSEvents*>(param);
 
-	OBSSource source = calldata_get_pointer<obs_source_t>(data, "source");
+	OBSDataAutoRelease fields = getMediaSourceData(data);
-	if (!source) {
-		return;
-	}
 
-	OBSDataAutoRelease fields = obs_data_create();
-	obs_data_set_string(fields, "sourceName", obs_source_get_name(source));
 	self->broadcastUpdate("MediaStarted", fields);
 }
 
 /**
  * A media source has ended.
  *
- * Note: For VLC, this means that the source and therefore playlist has ended.
+ * Note: These events are emitted by the OBS sources themselves. For example when the media file ends. The behavior depends on the type of media source being used.
- * For the normal Media Source, this just means that the source has been stopped/ended. 
  *
  * @return {String} `sourceName` Source name
+ * @return {String} `sourceTypeId` The ID type of the source (Eg. `vlc_source` or `ffmpeg_source`)
  *
  * @api events
  * @name MediaEnded
@@ -1536,13 +1529,8 @@ void WSEvents::OnMediaStarted(void* param, calldata_t* data) {
 void WSEvents::OnMediaEnded(void* param, calldata_t* data) {
 	auto self = reinterpret_cast<WSEvents*>(param);
 
-	OBSSource source = calldata_get_pointer<obs_source_t>(data, "source");
+	OBSDataAutoRelease fields = getMediaSourceData(data);
-	if (!source) {
-		return;
-	}
 
-	OBSDataAutoRelease fields = obs_data_create();
-	obs_data_set_string(fields, "sourceName", obs_source_get_name(source));
 	self->broadcastUpdate("MediaEnded", fields);
 }
 

src/WSRequestHandler_MediaControl.cpp

@@ -218,7 +218,7 @@ RpcResponse WSRequestHandler::GetMediaDuration(const RpcRequest& request) {
 	}
 
 	OBSDataAutoRelease response = obs_data_create();
-	obs_data_set_int(response, "timeStamp", obs_source_media_get_duration(source));
+	obs_data_set_int(response, "mediaDuration", obs_source_media_get_duration(source));
 	return request.success(response);
 }
 
@@ -227,7 +227,7 @@ RpcResponse WSRequestHandler::GetMediaDuration(const RpcRequest& request) {
 *
 * @param {String} `sourceName` Source name.
 *
-* @return {int} `timeStamp` The time in milliseconds since the start of the media.
+* @return {int} `timestamp` The time in milliseconds since the start of the media.
 *
 * @api requests
 * @name GetMediaTime
@@ -250,7 +250,7 @@ RpcResponse WSRequestHandler::GetMediaTime(const RpcRequest& request) {
 	}
 
 	OBSDataAutoRelease response = obs_data_create();
-	obs_data_set_int(response, "timeStamp", obs_source_media_get_time(source));
+	obs_data_set_int(response, "timestamp", obs_source_media_get_time(source));
 	return request.success(response);
 }
 
@@ -258,7 +258,7 @@ RpcResponse WSRequestHandler::GetMediaTime(const RpcRequest& request) {
 * Set the timestamp of a media source. Supports ffmpeg and vlc media sources (as of OBS v25.0.8)
 *
 * @param {String} `sourceName` Source name.
-* @param {int} `timeStamp` Milliseconds to set the timestamp to.
+* @param {int} `timestamp` Milliseconds to set the timestamp to.
 *
 * @api requests
 * @name SetMediaTime
@@ -266,12 +266,12 @@ RpcResponse WSRequestHandler::GetMediaTime(const RpcRequest& request) {
 * @since 4.9.0
 */
 RpcResponse WSRequestHandler::SetMediaTime(const RpcRequest& request) {
-	if (!request.hasField("sourceName") || !request.hasField("timeStamp")) {
+	if (!request.hasField("sourceName") || !request.hasField("timestamp")) {
 		return request.failed("missing request parameters");
 	}
 
 	QString sourceName = obs_data_get_string(request.parameters(), "sourceName");
-	int64_t timeStamp = (int64_t)obs_data_get_int(request.parameters(), "timeStamp");
+	int64_t timestamp = (int64_t)obs_data_get_int(request.parameters(), "timestamp");
 	if (sourceName.isEmpty()) {
 		return request.failed("invalid request parameters");
 	}
@@ -281,7 +281,7 @@ RpcResponse WSRequestHandler::SetMediaTime(const RpcRequest& request) {
 		return request.failed("specified source doesn't exist");
 	}
 
-	obs_source_media_set_time(source, timeStamp);
+	obs_source_media_set_time(source, timestamp);
 	return request.success();
 }
 
@@ -374,7 +374,7 @@ RpcResponse WSRequestHandler::GetMediaSourcesList(const RpcRequest& request)
 
 	auto sourceEnumProc = [](void* privateData, obs_source_t* source) -> bool {
 		obs_data_array_t* sourcesArray = (obs_data_array_t*)privateData;
-		
+
 		QString sourceTypeId = obs_source_get_id(source);
 		if (isMediaSource(sourceTypeId)) {
 			OBSDataAutoRelease sourceData = obs_data_create();
@@ -393,4 +393,4 @@ RpcResponse WSRequestHandler::GetMediaSourcesList(const RpcRequest& request)
 	OBSDataAutoRelease response = obs_data_create();
 	obs_data_set_array(response, "mediaSources", sourcesArray);
 	return request.success(response);
-}
+}