From e2f266a74a123de49bca49ce7a72067223a219b1 Mon Sep 17 00:00:00 2001
From: Marco Piovanello <35533749+marcopiovanello@users.noreply.github.com>
Date: Mon, 13 Jan 2025 13:31:36 +0100
Subject: [PATCH] Created RPC methods (markdown)

---
 RPC-methods.md | 159 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 159 insertions(+)
 create mode 100644 RPC-methods.md

diff --git a/RPC-methods.md b/RPC-methods.md
new file mode 100644
index 0000000..f0fbbe6
--- /dev/null
+++ b/RPC-methods.md
@@ -0,0 +1,159 @@
+## JSON-RPC
+
+yt-dlp-web-ui provides a **JSON-RPC 1.0** compliant **RPC interface**.
+
+The available transport protocols are: **HTTP-POST** and **WebSockets** with their respective secure extensions (HTTPS-POST and WebSocketsSecurity).
+
+This wiki is about wiring up a custom RPC client to the RPC server. (the examples will be written in **JavaScript** and **Python3**).
+
+### Exposed RPC methods
+* [Service.Exec](#serviceexec)
+* [Service.Progess](#serviceprogess)
+* [Service.Formats](#serviceformats)
+* [Service.Pending](#servicepending)
+* [Service.Running](#servicerunning)
+* [Service.Kill](#servicekill)
+* [Service.KillAll](#servicekillall)
+* [Service.Clear](#serviceclear)
+* [Service.FreeSpace](#servicefreespace)
+* [Service.DirectoryTree](#servicedirectorytree)
+* [Service.UpdateExecutable](#serviceupdateexecutable)
+
+### Base Request body
+
+```json5
+{
+  "id": 0,                 // sequence number, useful to identify requests/responses
+  "method": "service.*",   // rpc method name
+  "params": []             // method params usually a JSON object
+}
+```
+
+The following request bodies will be inside the **params** array.
+
+### Service.Exec
+Invoke a new process of `yt-dlp` and start a download with options.  
+Each request will spawn a new process. Future releases will implement a download queue with a configurable size.
+
+**Request Body**
+```json5
+{
+  "URL": "https://...",      // the url of the resource to download
+  "Params" "--no-mtime, -X", // (optional) yt-dlp cli arguments
+  "Path": "",                // (optional) path to download the file, if not specified will be the default download folder
+  "Rename" ""                // (optional) rename the download file to the specified one
+}
+```
+**Response Body**
+
+```json5
+string       // started process UUIDv4 (e.g. d856b872-4f7d-487f-a29e-c2ea8c71592f)
+```
+
+**Example code**
+
+```py
+def call(url, method, args):
+  data = {
+    'id': 0,
+    'method': method,
+    'params': [args]
+  }
+
+  res = requests.post(url=url, json=data, headers={'Content-Type': 'application/json'})
+  response = json.loads(res.text)
+  return response
+
+addr = 'ip or hostname'
+rpc = f'http://{addr}/rpc'
+args = {
+  'URL': 'some url'
+  'Params': ['--no-mtime']
+  'Rename': '👍.mp4' 
+}
+
+call(rpc, 'Service.Exec', args)
+```
+
+### Service.Progress
+Progess retrieves the Progress of a specific Process given its ID
+
+**Request Body**
+```json5
+{
+  "ID": 0  // Process identification number
+}
+```
+
+**Response Body**
+```json5
+{
+  "percentage": "29.3%", // download percentage            string
+  "speed": 92374832,     // speed in bytes/s               int32
+  "ETA": 300             // time to complete in seconds    int32
+}
+```
+**Example code**
+
+```py
+def call(url, method, args):
+  data = {
+    'id': 0,
+    'method': method,
+    'params': [args]
+  }
+
+  res = requests.post(url=url, json=data, headers={'Content-Type': 'application/json'})
+  response = json.loads(res.text)
+  return response
+
+addr = 'ip or hostname'
+rpc = f'http://{addr}/rpc'
+args = {
+  'ID': 'UUIDv4'
+}
+
+call(rpc, 'Service.Progress', args)
+```
+
+### Service.Running
+Retrieves all running processes progress
+
+**Request Body**
+```json5
+{}    // or null
+```
+
+**Response Body**
+```json5
+{
+[
+  {
+  "percentage": "29.3%", // download percentage            string
+    "speed": 92374832,     // speed in bytes/s               int32
+    "ETA": 300             // time to complete in seconds    int32
+  },
+  ...
+]
+}    // or null
+```
+**Example code**
+
+```py
+def call(url, method, args):
+  data = {
+    'id': 0,
+    'method': method,
+    'params': [args]
+  }
+
+  res = requests.post(url=url, json=data, headers={'Content-Type': 'application/json'})
+  response = json.loads(res.text)
+  return response
+
+addr = 'ip or hostname'
+rpc = f'http://{addr}/rpc'
+args = None
+
+call(rpc, 'Service.Running', args)
+```
\ No newline at end of file