Skip to content

Home

Jump to bottom
Marco edited this page Apr 19, 2023 · 4 revisions

Welcome to the yt-dlp-web-ui wiki!

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

Base Request body

{
  "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

{
  "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

string       // started process UUIDv4 (e.g. d856b872-4f7d-487f-a29e-c2ea8c71592f)

Example code

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

{
  "ID": 0  // Process identification number
}

Response Body

{
  "percentage": "29.3%", // download percentage            string
  "speed": 92374832,     // speed in bytes/s               int32
  "ETA": 300             // time to complete in seconds    int32
}

Example code

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

{}    // or null

Response Body

{
[
  {
  "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

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)
Clone this wiki locally