From fdcba2734d12a45bf690c00938f6ddc9a8eb53ab Mon Sep 17 00:00:00 2001 From: tt2468 Date: Sun, 28 Jun 2020 17:02:37 -0700 Subject: [PATCH] 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 | 96 ++++++++++++--------------- src/WSRequestHandler_MediaControl.cpp | 18 ++--- 2 files changed, 51 insertions(+), 63 deletions(-) diff --git a/src/WSEvents.cpp b/src/WSEvents.cpp index 92e1e1d2..0e20d989 100644 --- a/src/WSEvents.cpp +++ b/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(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(param); - OBSSource source = calldata_get_pointer(data, "source"); - if (!source) { - return; - } + OBSDataAutoRelease fields = getMediaSourceData(data); - 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(param); - OBSSource source = calldata_get_pointer(data, "source"); - if (!source) { - return; - } + OBSDataAutoRelease fields = getMediaSourceData(data); - 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(param); - OBSSource source = calldata_get_pointer(data, "source"); - if (!source) { - return; - } + OBSDataAutoRelease fields = getMediaSourceData(data); - 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(param); - OBSSource source = calldata_get_pointer(data, "source"); - if (!source) { - return; - } + OBSDataAutoRelease fields = getMediaSourceData(data); - 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(param); - OBSSource source = calldata_get_pointer(data, "source"); - if (!source) { - return; - } + OBSDataAutoRelease fields = getMediaSourceData(data); - 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(param); - OBSSource source = calldata_get_pointer(data, "source"); - if (!source) { - return; - } + OBSDataAutoRelease fields = getMediaSourceData(data); - 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)) - * - * Note: For VLC, this means that the source and therefore playlist has started. - * For the normal Media Source, this just means that the source has been started. + * A media source has been 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. * * @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(param); - OBSSource source = calldata_get_pointer(data, "source"); - if (!source) { - return; - } + OBSDataAutoRelease fields = getMediaSourceData(data); - 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. - * For the normal Media Source, this just means that the source has been stopped/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. * * @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(param); - OBSSource source = calldata_get_pointer(data, "source"); - if (!source) { - return; - } + OBSDataAutoRelease fields = getMediaSourceData(data); - OBSDataAutoRelease fields = obs_data_create(); - obs_data_set_string(fields, "sourceName", obs_source_get_name(source)); self->broadcastUpdate("MediaEnded", fields); } diff --git a/src/WSRequestHandler_MediaControl.cpp b/src/WSRequestHandler_MediaControl.cpp index ea754c6a..ba61c17f 100644 --- a/src/WSRequestHandler_MediaControl.cpp +++ b/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); -} \ No newline at end of file +}