torrent-hls API v1

Stream anything from BitTorrent. Torrent → HTTP Live Streaming with real-time fast-start segments, optional subtitles, per-session watermarking, and an embeddable player.

API versioning

Every endpoint exists under two prefixes:

These resolve to identical handlers. Use /api/ for quick integration; pin /api/v1/ for production clients that need a frozen contract.

Session control

Session control (delete, status, heartbeat) uses three independent layers, checked in order:

Site keys

Embedding sites can register a site key with the API operator. This key is never sent to the browser — it lives on the site's backend. When the site's backend creates a session on behalf of a user, it includes its site key. The session is then associated with that site.

Later, the site can manage any session it created using the same key, regardless of which user's IP created it.

// Site backend creates a session for a user
POST /api/streams
X-Site-Key: sk_live_abc123...
Content-Type: application/json

{ "source": "magnet:?xt=...", "ipLock": false }

// Response includes policy.siteKey = "example-site"
// Site can later DELETE /api/streams/<id> with the same X-Site-Key

Create stream

curl -X POST https://your-domain/api/streams \
  -H 'content-type: application/json' \
  -H 'X-Site-Key: sk_live_...' \
  -d '{"source":"magnet:?xt=urn:btih:..."}'

{
  "id": "dd8255ec...",
  "status": "ready",
  "file": { "name": "Big Buck Bunny.mp4", "size": 276134947, "sizeHuman": "263.3 MB", "kind": "video" },
  "playlist": "/hls/dd8255ec.../index.m3u8",
  "embed": "/embed/dd8255ec...",
  "subtitles": [],
  "policy": { "ipLock": true, "transcode": false, "siteKey": null },
  "control": {
    "heartbeat": "/api/v1/streams/dd8255ec.../heartbeat",
    "delete": "/api/v1/streams/dd8255ec...",
    "interval": 10000,
    "timeout": 15000,
    "yours": true
  }
}

Upload .torrent

curl -X POST https://your-domain/api/torrents \
  -H 'content-type: application/x-bittorrent' \
  --data-binary @movie.torrent

List streams

Get stream

Delete stream

Heartbeat

{"pong": true, "streams": 3}

Health

{"ok":true,"streams":3,"maxStreams":20,"uptime":1234.5,"memory":{...},"version":"1.0.0"}

Version

{"name":"torrent-hls","version":"1.0.0","api":"v1","features":["hls","subtitles","watermark","theme","embed","heartbeat","ip-lock","site-key","rate-limit"]}

Examples

Embedding

Every session exposes an embed URL that serves a minimal player page, safe to load in an <iframe>:

<iframe src="https://your-domain/embed/dd8255ec..." 
        width="960" height="540" frameborder="0" 
        allowfullscreen></iframe>

The embed page inherits the session's watermark and theme settings, and manages its own heartbeat for the duration the iframe is open.

Watermarking

Theming

{
  "theme": {
    "primary": "#14b8a6",
    "background": "#080b10"
  }
}

Rate limits

Limits scale down dynamically only when server capacity exceeds 70%. 429 responses include Retry-After.

Error codes

Error responses use the shape:

{ "error": "Human-readable message", "code": "machine_readable_code" }

Client integration

// 1. Create stream
const r = await fetch('/api/streams', {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'X-Site-Key': SITE_KEY   // only if you're an embedding site
  },
  body: JSON.stringify({ source: 'magnet:?xt=urn:btih:...' })
});
const s = await r.json();

// 2. Start heartbeat (required every 10s)
const hb = setInterval(() => {
  fetch('/api/streams/' + s.id + '/heartbeat', { method: 'POST' })
    .catch(() => clearInterval(hb));
}, s.control.interval);

// 3. Play
const hls = new Hls();
hls.loadSource(s.playlist);
hls.attachMedia(video);

// 4. Cleanup on unmount
clearInterval(hb);
fetch('/api/streams/' + s.id, { method: 'DELETE' });

Self-hosting

See /opt/torrent-hls/.env.example for the full list with comments. Copy it to /etc/default/torrent-hls and edit, then systemctl restart torrent-hls.