From 30ea6c26ca8d2f1878dfb5a0bbff37fc642484c5 Mon Sep 17 00:00:00 2001 From: Dominik Nakamura Date: Tue, 21 Dec 2021 22:03:53 +0900 Subject: [PATCH] More docs and smaller tweaks from obs-websocket --- src/client/general.rs | 2 ++ src/client/scene_items.rs | 43 ++++++++++++++++++++++++++++++++++++++- src/client/streaming.rs | 4 ++++ src/common.rs | 2 ++ src/requests/mod.rs | 42 ++++++++++++++++++++++++++++++++++++++ src/responses/mod.rs | 22 ++++++++++++++++++-- 6 files changed, 112 insertions(+), 3 deletions(-) diff --git a/src/client/general.rs b/src/client/general.rs index 73c7cde..1a42f12 100644 --- a/src/client/general.rs +++ b/src/client/general.rs @@ -107,6 +107,8 @@ impl<'a> General<'a> { } /// Enables or disables studio mode. + /// + /// - `studio_mode_enabled`: Enable or disable the studio mode. pub async fn set_studio_mode_enabled(&self, studio_mode_enabled: bool) -> Result<()> { self.client .send_message(RequestType::SetStudioModeEnabled { diff --git a/src/client/scene_items.rs b/src/client/scene_items.rs index e514c7e..1b1dba9 100644 --- a/src/client/scene_items.rs +++ b/src/client/scene_items.rs @@ -13,6 +13,9 @@ pub struct SceneItems<'a> { } impl<'a> SceneItems<'a> { + /// Gets a list of all scene items in a scene. + /// + /// - `scene_name`: Name of the scene to get the items of. pub async fn get_scene_item_list(&self, scene_name: &str) -> Result> { self.client .send_message::(RequestType::GetSceneItemList { scene_name }) @@ -20,6 +23,11 @@ impl<'a> SceneItems<'a> { .map(|sil| sil.scene_items) } + /// Basically GetSceneItemList, but for groups. + /// + /// Using groups at all in OBS is discouraged, as they are very broken under the hood. + /// + /// - `scene_name`: Name of the group to get the items of. pub async fn get_group_scene_item_list( &self, scene_name: &str, @@ -32,6 +40,10 @@ impl<'a> SceneItems<'a> { .map(|sil| sil.scene_items) } + /// Searches a scene for a source, and returns its id. + /// + /// - `scene_name`: Name of the scene or group to search in. + /// - `source_name`: Name of the source to find. pub async fn get_scene_item_id(&self, scene_name: &str, source_name: &str) -> Result { self.client .send_message::(RequestType::GetSceneItemId { @@ -42,6 +54,7 @@ impl<'a> SceneItems<'a> { .map(|sii| sii.scene_item_id) } + /// Creates a new scene item using a source. pub async fn create_scene_item(&self, create: CreateSceneItem<'_>) -> Result { self.client .send_message::(RequestType::CreateSceneItem(create)) @@ -49,6 +62,10 @@ impl<'a> SceneItems<'a> { .map(|sii| sii.scene_item_id) } + /// Removes a scene item from a scene. + /// + /// - `scene_name`: Name of the scene the item is in. + /// - `scene_item_id`: Numeric ID of the scene item. pub async fn remove_scene_item(&self, scene_name: &str, scene_item_id: i64) -> Result<()> { self.client .send_message(RequestType::RemoveSceneItem { @@ -58,6 +75,7 @@ impl<'a> SceneItems<'a> { .await } + /// Duplicates a scene item, copying all transform and crop info. pub async fn duplicate_scene_item(&self, duplicate: DuplicateSceneItem<'_>) -> Result { self.client .send_message::(RequestType::DuplicateSceneItem(duplicate)) @@ -65,19 +83,25 @@ impl<'a> SceneItems<'a> { .map(|sii| sii.scene_item_id) } + /// Gets the transform and crop info of a scene item. + /// + /// - `scene_name`: Name of the scene the item is in. + /// - `scene_item_id`: Numeric ID of the scene item. pub async fn get_scene_item_transform( &self, scene_name: &str, scene_item_id: i64, ) -> Result { self.client - .send_message(RequestType::GetSceneItemTransform { + .send_message::(RequestType::GetSceneItemTransform { scene_name, scene_item_id, }) .await + .map(|gsit| gsit.scene_item_transform) } + /// Sets the transform and crop info of a scene item. pub async fn set_scene_item_transform( &self, transform: SetSceneItemTransform<'_>, @@ -87,6 +111,10 @@ impl<'a> SceneItems<'a> { .await } + /// Gets the enable state of a scene item. + /// + /// - `scene_name`: Name of the scene the item is in. + /// - `scene_item_id`: Numeric ID of the scene item. pub async fn get_scene_item_enabled( &self, scene_name: &str, @@ -101,12 +129,17 @@ impl<'a> SceneItems<'a> { .map(|sie| sie.scene_item_enabled) } + /// Sets the enable state of a scene item. pub async fn set_scene_item_enabled(&self, enabled: SetSceneItemEnabled<'a>) -> Result<()> { self.client .send_message(RequestType::SetSceneItemEnabled(enabled)) .await } + /// Gets the lock state of a scene item. + /// + /// - `scene_name`: Name of the scene the item is in. + /// - `scene_item_id`: Numeric ID of the scene item. pub async fn get_scene_item_locked( &self, scene_name: &str, @@ -121,12 +154,19 @@ impl<'a> SceneItems<'a> { .map(|sil| sil.scene_item_locked) } + /// Sets the lock state of a scene item. pub async fn set_scene_item_locked(&self, locked: SetSceneItemLocked<'a>) -> Result<()> { self.client .send_message(RequestType::SetSceneItemLocked(locked)) .await } + /// Gets the index position of a scene item in a scene. + /// + /// An index of 0 is at the bottom of the source list in the UI. + /// + /// - `scene_name`: Name of the scene the item is in. + /// - `scene_item_id`: Numeric ID of the scene item. pub async fn get_scene_item_index(&self, scene_name: &str, scene_item_id: i64) -> Result { self.client .send_message::(RequestType::GetSceneItemIndex { @@ -137,6 +177,7 @@ impl<'a> SceneItems<'a> { .map(|sii| sii.scene_item_index) } + /// Sets the index position of a scene item in a scene. pub async fn set_scene_item_index(&self, index: SetSceneItemIndex<'a>) -> Result<()> { self.client .send_message(RequestType::SetSceneItemIndex(index)) diff --git a/src/client/streaming.rs b/src/client/streaming.rs index 55ac70a..cfdd1f6 100644 --- a/src/client/streaming.rs +++ b/src/client/streaming.rs @@ -7,10 +7,12 @@ pub struct Streaming<'a> { } impl<'a> Streaming<'a> { + /// Gets the status of the stream output.. pub async fn get_stream_status(&self) -> Result { self.client.send_message(RequestType::GetStreamStatus).await } + /// Toggles the status of the stream output. pub async fn toggle_stream(&self) -> Result { self.client .send_message::(RequestType::ToggleStream) @@ -18,10 +20,12 @@ impl<'a> Streaming<'a> { .map(|ts| ts.output_active) } + /// Starts the stream output. pub async fn start_stream(&self) -> Result<()> { self.client.send_message(RequestType::StartStream).await } + /// Stops the stream output. pub async fn stop_stream(&self) -> Result<()> { self.client.send_message(RequestType::StopStream).await } diff --git a/src/common.rs b/src/common.rs index 1cad021..56c4eaf 100644 --- a/src/common.rs +++ b/src/common.rs @@ -33,6 +33,8 @@ pub enum BoundsType { #[derive(Clone, Copy, Debug, Serialize, Deserialize)] pub enum MediaAction { + #[serde(rename = "OBS_WEBSOCKET_MEDIA_INPUT_ACTION_NONE")] + None, #[serde(rename = "OBS_WEBSOCKET_MEDIA_INPUT_ACTION_PLAY")] Play, #[serde(rename = "OBS_WEBSOCKET_MEDIA_INPUT_ACTION_PAUSE")] diff --git a/src/requests/mod.rs b/src/requests/mod.rs index a960d77..4109fc5 100644 --- a/src/requests/mod.rs +++ b/src/requests/mod.rs @@ -257,6 +257,7 @@ pub(crate) enum RequestType<'a> { GetVersion, #[serde(rename_all = "camelCase")] BroadcastCustomEvent { + /// Data payload to emit to all receivers. event_data: serde_json::Value, }, CallVendorRequest(CallVendorRequestInternal<'a>), @@ -264,16 +265,20 @@ pub(crate) enum RequestType<'a> { GetHotkeyList, #[serde(rename_all = "camelCase")] TriggerHotkeyByName { + /// Name of the hotkey to trigger. hotkey_name: &'a str, }, #[serde(rename_all = "camelCase")] TriggerHotkeyByKeySequence { + /// The OBS key ID to use. key_id: &'a str, + /// Object containing key modifiers to apply. key_modifiers: KeyModifiers, }, GetStudioModeEnabled, #[serde(rename_all = "camelCase")] SetStudioModeEnabled { + /// Enable or disable the studio mode. studio_mode_enabled: bool, }, // TODO: Sleep @@ -324,7 +329,9 @@ pub(crate) enum RequestType<'a> { }, #[serde(rename_all = "camelCase")] SetInputVolume { + /// Name of the input to set the volume of. input_name: &'a str, + /// Volume settings in either mul or dB. #[serde(flatten)] input_volume: Volume, }, @@ -420,45 +427,59 @@ pub(crate) enum RequestType<'a> { // -------------------------------- #[serde(rename_all = "camelCase")] GetSceneItemList { + /// Name of the scene to get the items of. scene_name: &'a str, }, #[serde(rename_all = "camelCase")] GetGroupSceneItemList { + /// Name of the group to get the items of. scene_name: &'a str, }, #[serde(rename_all = "camelCase")] GetSceneItemId { + /// Name of the scene or group to search in. scene_name: &'a str, + /// Name of the source to find. source_name: &'a str, }, CreateSceneItem(CreateSceneItem<'a>), #[serde(rename_all = "camelCase")] RemoveSceneItem { + /// Name of the scene the item is in. scene_name: &'a str, + /// Numeric ID of the scene item. scene_item_id: i64, }, DuplicateSceneItem(DuplicateSceneItem<'a>), #[serde(rename_all = "camelCase")] GetSceneItemTransform { + /// Name of the scene the item is in. scene_name: &'a str, + /// Numeric ID of the scene item. scene_item_id: i64, }, SetSceneItemTransform(SetSceneItemTransform<'a>), #[serde(rename_all = "camelCase")] GetSceneItemEnabled { + /// Name of the scene the item is in. scene_name: &'a str, + /// Numeric ID of the scene item. scene_item_id: i64, }, SetSceneItemEnabled(SetSceneItemEnabled<'a>), #[serde(rename_all = "camelCase")] GetSceneItemLocked { + /// Name of the scene the item is in. scene_name: &'a str, + /// Numeric ID of the scene item. scene_item_id: i64, }, SetSceneItemLocked(SetSceneItemLocked<'a>), #[serde(rename_all = "camelCase")] GetSceneItemIndex { + /// Name of the scene the item is in. scene_name: &'a str, + /// Numeric ID of the scene item. scene_item_id: i64, }, #[serde(rename_all = "camelCase")] @@ -587,8 +608,11 @@ pub struct CallVendorRequest<'a, T> { #[derive(Default, Serialize)] #[serde(rename_all = "camelCase")] pub(crate) struct CallVendorRequestInternal<'a> { + /// Name of the vendor to use. pub vendor_name: &'a str, + /// The request type to call. pub request_type: &'a str, + /// Object containing appropriate request data. pub request_data: serde_json::Value, } @@ -662,24 +686,33 @@ pub(crate) struct CreateInputInternal<'a> { #[derive(Default, Serialize)] #[serde(rename_all = "camelCase")] pub struct CreateSceneItem<'a> { + /// Name of the scene to create the new item in. pub scene_name: &'a str, + /// Name of the source to add to the scene. pub source_name: &'a str, + /// Enable state to apply to the scene item on creation. pub scene_item_enabled: Option, } #[derive(Default, Serialize)] #[serde(rename_all = "camelCase")] pub struct DuplicateSceneItem<'a> { + /// Name of the scene the item is in. pub scene_name: &'a str, + /// Numeric ID of the scene item. pub scene_item_id: i64, + /// Name of the scene to create the duplicated item in. pub destination_scene_name: Option<&'a str>, } #[derive(Default, Serialize)] #[serde(rename_all = "camelCase")] pub struct SetSceneItemTransform<'a> { + /// Name of the scene the item is in. pub scene_name: &'a str, + /// Numeric ID of the scene item. pub scene_item_id: i64, + /// Object containing scene item transform info to update. pub scene_item_transform: SceneItemTransform, } @@ -705,24 +738,33 @@ pub struct SceneItemTransform { #[derive(Default, Serialize)] #[serde(rename_all = "camelCase")] pub struct SetSceneItemEnabled<'a> { + /// Name of the scene the item is in. pub scene_name: &'a str, + /// Numeric ID of the scene item. pub scene_item_id: i64, + /// New enable state of the scene item. pub scene_item_enabled: bool, } #[derive(Default, Serialize)] #[serde(rename_all = "camelCase")] pub struct SetSceneItemLocked<'a> { + /// Name of the scene the item is in. pub scene_name: &'a str, + /// Numeric ID of the scene item. pub scene_item_id: i64, + /// New lock state of the scene item. pub scene_item_locked: bool, } #[derive(Default, Serialize)] #[serde(rename_all = "camelCase")] pub struct SetSceneItemIndex<'a> { + /// Name of the scene the item is in. pub scene_name: &'a str, + /// Numeric ID of the scene item. pub scene_item_id: i64, + /// New index position of the scene item. pub scene_item_index: u32, } diff --git a/src/responses/mod.rs b/src/responses/mod.rs index 87834e1..f097d0a 100644 --- a/src/responses/mod.rs +++ b/src/responses/mod.rs @@ -438,6 +438,7 @@ pub struct RecordStatus { #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub(crate) struct OutputActive { + /// New state of the stream output. pub output_active: bool, } @@ -456,10 +457,16 @@ pub(crate) struct RecordDirectory { #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub(crate) struct SceneItemId { - /// ID of the newly created scene item. + /// Numeric ID of the scene item. pub scene_item_id: i64, } +#[derive(Debug, Deserialize)] +#[serde(rename_all = "camelCase")] +pub(crate) struct GetSceneItemTransform { + pub scene_item_transform: SceneItemTransform, +} + #[derive(Clone, Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub struct SceneItemTransform { @@ -486,18 +493,21 @@ pub struct SceneItemTransform { #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub(crate) struct SceneItemEnabled { + /// Whether the scene item is enabled. pub scene_item_enabled: bool, } #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub(crate) struct SceneItemLocked { + /// Whether the scene item is locked. pub scene_item_locked: bool, } #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub(crate) struct SceneItemIndex { + /// Index position of the scene item. pub scene_item_index: u32, } @@ -534,6 +544,7 @@ pub struct ListPropertyItem { #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub(crate) struct SceneItemList { + /// Array of scene items in the scene or group. pub scene_items: Vec, } @@ -611,13 +622,20 @@ pub(crate) struct ImageData { #[derive(Debug, Deserialize)] #[serde(rename_all = "camelCase")] pub struct StreamStatus { + /// Whether the output is active. pub output_active: bool, + /// Whether the output is currently reconnecting. pub output_reconnecting: bool, + /// Current timecode for the output. #[serde(deserialize_with = "crate::de::duration_timecode")] pub output_timecode: Duration, - #[serde(deserialize_with = "crate::de::duration_nanos")] + /// Current duration for the output. + #[serde(deserialize_with = "crate::de::duration_millis")] pub output_duration: Duration, + /// Number of bytes sent by the output. pub output_bytes: u64, + /// Number of frames skipped by the output's process. pub output_skipped_frames: u32, + /// Total number of frames delivered by the output's process. pub output_total_frames: u32, }