yt-dlp API - Ruuka

Core Features

The service manages the media toolchain and exposes a simple HTTP interface for downloading and streaming audio.

Automated Binary Lifecycle

On startup, the server verifies Node.js v20+ and updates local copies of yt-dlp, FFmpeg, and Deno from GitHub releases.

Node.js 20+

Audio Extraction & Validation

Downloads audio at 192 kbps MP3 quality with yt-dlp and validates the resulting file using FFprobe.

192 kbps MP3

ComputerCraft Compatibility

Converts MP3 files on-demand into 48000 Hz, single-channel DFPWM streams suitable for ComputerCraft HTTP audio.

48 kHz · Mono · DFPWM

Real-time SSE Tracking

Server-Sent Events provide live download progress, speed, ETA, and job state updates.

text/event-stream

Streaming & Seeking

MP3 routes support standard HTTP Range headers and timestamp seeking with the t query parameter.

Range · Seeking

API Endpoints Reference

All endpoints are HTTP GET routes. Replace <MEDIA_ID> with the identifier returned by the download endpoint.

GET/

Root & API Metadata

Returns metadata about the API and a list of available endpoints.

Response

JSON object containing API metadata and endpoint information.

GET/health

Health Check

Returns the current server status and uptime.

{
  "status": "ok",
  "uptime": 123.45
}

Downloads & Job Management

GET/download?url=<URL>

Triggers a background audio download job for the provided HTTP/HTTPS media URL.

Query Parameters

Parameter	Required	Description
`url`	Yes	HTTP/HTTPS media URL, such as a YouTube URL.

Example

GET /download?url=https://www.youtube.com/watch?v=...

Response

{
  "id": "MEDIA_ID",
  "status": "queued",
  "mp3": "/music/MEDIA_ID.mp3",
  "dfpwm": "/music/MEDIA_ID.dfpwm"
}

GET/status?id=<MEDIA_ID>

Retrieves the current state of a download or conversion job.

Query Parameters

Parameter	Required	Description
`id`	Yes	Media ID returned by `/download`.

Response

{
  "id": "MEDIA_ID",
  "status": "downloading",
  "progress": 42.5,
  "speed": "2.4 MiB/s",
  "eta": 18,
  "size": 12345678,
  "duration": 245,
  "completed": false
}

GET/events?id=<MEDIA_ID>

Opens a Server-Sent Events stream for live progress updates for an active download job.

Content Type

Content-Type: text/event-stream

The stream reports live progress, speed, ETA, and job state while the operation is active.

Media Streaming & Direct Audio Routes

GET/music/<MEDIA_ID>.mp3

Serves or streams the converted MP3 file.

Timestamp Seeking

Use the optional t parameter to start playback at a specific time in seconds or HH:MM:SS format.

GET /music/MEDIA_ID.mp3?t=30
GET /music/MEDIA_ID.mp3?t=01:30
GET /music/MEDIA_ID.mp3?t=00:01:30

Range Support

Standard HTTP byte ranges are supported through the Range: bytes=... header.

Range: bytes=100000-200000

GET/music/<MEDIA_ID>.dfpwm

Converts the specified MP3 into DFPWM on-the-fly and streams the result. If the MP3 is missing, it is automatically downloaded first.

Output

48000 HzSample rate

MonoSingle audio channel

DFPWMComputerCraft stream format

Direct / Auto Endpoints

GET/music/auto?url=<URL_OR_ID>

Convenience route that automatically downloads the requested media if it is not cached and immediately streams it back as an MP3.

Example

GET /music/auto?url=https://www.youtube.com/watch?v=...

GET/music/auto.dfpwm?url=<URL_OR_ID>

Automatically downloads, converts to DFPWM, and streams the result directly. Designed for ComputerCraft HTTP audio streams.

Query Parameters

Parameter	Required	Description
`url`	Yes	Media URL or media ID.

Example

GET /music/auto.dfpwm?url=https://www.youtube.com/watch?v=...

Typical Workflow

1. Start a download

GET /download?url=<URL>

2. Monitor progress

GET /status?id=<MEDIA_ID>
GET /events?id=<MEDIA_ID>

3. Stream MP3

GET /music/<MEDIA_ID>.mp3

4. Seek to a timestamp

GET /music/<MEDIA_ID>.mp3?t=60

5. Stream to ComputerCraft

GET /music/<MEDIA_ID>.dfpwm
GET /music/auto.dfpwm?url=<URL>

Quick Reference

Method	Endpoint	Purpose
GET	`/`	API metadata and endpoint list
GET	`/health`	Server health and uptime
GET	`/download?url=<URL>`	Start a download
GET	`/status?id=<ID>`	Get job status
GET	`/events?id=<ID>`	Live SSE progress
GET	`/music/<ID>.mp3`	Stream MP3
GET	`/music/<ID>.dfpwm`	Convert and stream DFPWM
GET	`/music/auto?url=<URL_OR_ID>`	Auto-download and stream MP3
GET	`/music/auto.dfpwm?url=<URL_OR_ID>`	Auto-download and stream DFPWM

Downloads are asynchronous. MP3 output is generated at 192 kbps, DFPWM conversion happens on-demand, and MP3 streaming supports HTTP range requests.