From a57692dc39319f91d8643e4113f21a2cd126e85b Mon Sep 17 00:00:00 2001 From: NotAShelf Date: Sun, 15 Dec 2024 03:21:37 +0300 Subject: [PATCH] lib: document target --- src/lib.rs | 187 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 166 insertions(+), 21 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index 990c8762..1b83c121 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,45 @@ +//! MRC +//! A library for interacting with the MPV media player using its JSON IPC (Inter-Process Communication) protocol. +//! +//! This crate provides a set of utilities to communicate with MPV's IPC socket, enabling you to send commands +//! and retrieve responses in a structured format. +//! +//! ## Features +//! +//! - Send commands to MPV's IPC socket +//! - Retrieve responses in JSON format +//! - Supports common MPV commands like `set_property`, `seek`, and `playlist-next` +//! - Flexible socket path configuration +//! +//! ## Example Usage +//! ```rust +//! use serde_json::json; +//! use tokio; +//! use mrc::{send_ipc_command, playlist_next, set_property}; +//! +//! #[tokio::main] +//! async fn main() { +//! let result = playlist_next(None).await; +//! match result { +//! Ok(response) => println!("Playlist moved to next: {:?}", response), +//! Err(err) => eprintln!("Error: {:?}", err), +//! } +//! +//! let property_result = set_property("volume", &json!(50), None).await; +//! match property_result { +//! Ok(response) => println!("Volume set: {:?}", response), +//! Err(err) => eprintln!("Error: {:?}", err), +//! } +//! } +//! ``` +//! +//! ## Constants +//! +//! ### `SOCKET_PATH` +//! Default path for the MPV IPC socket: `/tmp/mpvsocket` +//! +//! ## Functions + use serde_json::{json, Value}; use std::io::{self}; use tokio::io::{AsyncReadExt, AsyncWriteExt}; @@ -8,7 +50,16 @@ pub const SOCKET_PATH: &str = "/tmp/mpvsocket"; /// Sends a generic IPC command to the specified socket and returns the parsed response data. /// -/// If a socket path is not provided, it will fall back to the example path of `/tmp/mpvsocket` +/// # Arguments +/// - `command`: The name of the command to send to MPV. +/// - `args`: A slice of `Value` arguments to include in the command. +/// - `socket_path`: An optional custom path to the MPV IPC socket. If `None`, the default path is used. +/// +/// # Returns +/// A `Result` containing an `Option` with the parsed response data if successful. +/// +/// # Errors +/// Returns an error if the connection to the socket fails or if the response cannot be parsed. pub async fn send_ipc_command( command: &str, args: &[Value], @@ -59,22 +110,64 @@ pub async fn send_ipc_command( } } -// Common MPV commands +/// Represents common MPV commands. +/// +/// This enum provides variants for frequently used MPV commands, which can be converted to their +/// string equivalents using the `as_str` method. #[derive(Debug)] pub enum MpvCommand { + /// Sets a property to a specified value in MPV. SetProperty, + /// Moves to the next item in the playlist. PlaylistNext, + /// Moves to the previous item in the playlist. PlaylistPrev, + /// Seeks to a specific time in the current media. Seek, + /// Quits the MPV application. Quit, + /// Moves an item in the playlist from one index to another. PlaylistMove, + /// Removes an item from the playlist. PlaylistRemove, + /// Clears all items from the playlist. PlaylistClear, + /// Retrieves the value of a property in MPV. GetProperty, + /// Loads a file into MPV. LoadFile, } -// Send any generic command to the MPV IPC socket. +impl MpvCommand { + /// Converts MPV commands to their string equivalents. + /// + /// # Returns + /// A string slice representing the command. + pub fn as_str(&self) -> &str { + match self { + MpvCommand::SetProperty => "set_property", + MpvCommand::PlaylistNext => "playlist-next", + MpvCommand::PlaylistPrev => "playlist-prev", + MpvCommand::Seek => "seek", + MpvCommand::Quit => "quit", + MpvCommand::PlaylistMove => "playlist-move", + MpvCommand::PlaylistRemove => "playlist-remove", + MpvCommand::PlaylistClear => "playlist-clear", + MpvCommand::GetProperty => "get_property", + MpvCommand::LoadFile => "loadfile", + } + } +} + +/// Sends the `set_property` command to MPV to change a property value. +/// +/// # Arguments +/// - `property`: The name of the property to set. +/// - `value`: The new value to assign to the property. +/// - `socket_path`: An optional custom socket path. +/// +/// # Returns +/// A `Result` containing the response data. pub async fn set_property( property: &str, value: &Value, @@ -88,22 +181,60 @@ pub async fn set_property( .await } +/// Sends the `playlist-next` command to move to the next playlist item. +/// +/// # Arguments +/// - `socket_path`: An optional custom socket path. +/// +/// # Returns +/// A `Result` containing the response data. pub async fn playlist_next(socket_path: Option<&str>) -> io::Result> { send_ipc_command(MpvCommand::PlaylistNext.as_str(), &[], socket_path).await } +/// Sends the `playlist-prev` command to move to the previous playlist item. +/// +/// # Arguments +/// - `socket_path`: An optional custom socket path. +/// +/// # Returns +/// A `Result` containing the response data. pub async fn playlist_prev(socket_path: Option<&str>) -> io::Result> { send_ipc_command(MpvCommand::PlaylistPrev.as_str(), &[], socket_path).await } +/// Sends the `seek` command to seek the media playback by a given number of seconds. +/// +/// # Arguments +/// - `seconds`: The number of seconds to seek. +/// - `socket_path`: An optional custom socket path. +/// +/// # Returns +/// A `Result` containing the response data. pub async fn seek(seconds: f64, socket_path: Option<&str>) -> io::Result> { send_ipc_command(MpvCommand::Seek.as_str(), &[json!(seconds)], socket_path).await } +/// Sends the `quit` command to terminate MPV. +/// +/// # Arguments +/// - `socket_path`: An optional custom socket path. +/// +/// # Returns +/// A `Result` containing the response data. pub async fn quit(socket_path: Option<&str>) -> io::Result> { send_ipc_command(MpvCommand::Quit.as_str(), &[], socket_path).await } +/// Sends the `playlist-move` command to move a playlist item from one index to another. +/// +/// # Arguments +/// - `from_index`: The index of the item to move. +/// - `to_index`: The index to move the item to. +/// - `socket_path`: An optional custom socket path. +/// +/// # Returns +/// A `Result` containing the response data. pub async fn playlist_move( from_index: usize, to_index: usize, @@ -117,6 +248,14 @@ pub async fn playlist_move( .await } +/// Sends the `playlist-remove` command to remove an item from the playlist. +/// +/// # Arguments +/// - `index`: The index of the item to remove, or `None` to remove the current item. +/// - `socket_path`: An optional custom socket path. +/// +/// # Returns +/// A `Result` containing the response data. pub async fn playlist_remove( index: Option, socket_path: Option<&str>, @@ -128,10 +267,25 @@ pub async fn playlist_remove( send_ipc_command(MpvCommand::PlaylistRemove.as_str(), &args, socket_path).await } +/// Sends the `playlist-clear` command to clear the playlist. +/// +/// # Arguments +/// - `socket_path`: An optional custom socket path. +/// +/// # Returns +/// A `Result` containing the response data. pub async fn playlist_clear(socket_path: Option<&str>) -> io::Result> { send_ipc_command(MpvCommand::PlaylistClear.as_str(), &[], socket_path).await } +/// Sends the `get_property` command to retrieve a property value from MPV. +/// +/// # Arguments +/// - `property`: The name of the property to retrieve. +/// - `socket_path`: An optional custom socket path. +/// +/// # Returns +/// A `Result` containing the response data. pub async fn get_property(property: &str, socket_path: Option<&str>) -> io::Result> { send_ipc_command( MpvCommand::GetProperty.as_str(), @@ -141,6 +295,15 @@ pub async fn get_property(property: &str, socket_path: Option<&str>) -> io::Resu .await } +/// Sends the `loadfile` command to load a file into MPV. +/// +/// # Arguments +/// - `filename`: The name of the file to load. +/// - `append`: Whether to append the file to the playlist (`true`) or replace the current file (`false`). +/// - `socket_path`: An optional custom socket path. +/// +/// # Returns +/// A `Result` containing the response data. pub async fn loadfile( filename: &str, append: bool, @@ -158,21 +321,3 @@ pub async fn loadfile( ) .await } - -impl MpvCommand { - // Convert commands to their string equivalents - pub fn as_str(&self) -> &str { - match self { - MpvCommand::SetProperty => "set_property", - MpvCommand::PlaylistNext => "playlist-next", - MpvCommand::PlaylistPrev => "playlist-prev", - MpvCommand::Seek => "seek", - MpvCommand::Quit => "quit", - MpvCommand::PlaylistMove => "playlist-move", - MpvCommand::PlaylistRemove => "playlist-remove", - MpvCommand::PlaylistClear => "playlist-clear", - MpvCommand::GetProperty => "get_property", - MpvCommand::LoadFile => "loadfile", - } - } -}