User guide

Everything you need to go from an encoder on your desk to viewers on any device.

Introduction

ssh101+ takes a live stream from your encoder and delivers it to viewers as HLS (and DASH on paid plans). It runs passthrough: your video is never re-encoded, so the quality your viewers see is exactly the quality you send, and latency stays low.

Quick start

1. Create an account. Sign up — the free plan includes one channel and 20 concurrent viewers.
2. Create a channel. On your dashboard, pick a slug (the public name in your URLs, e.g. gracechapel) and a display name.
3. Copy your stream key. The dashboard shows an ingest key. Append the rendition label: <key>_720p.
4. Point your encoder at the RTMP URL with that key. See OBS or ffmpeg.
5. Watch. Your channel appears at /watch/<slug> and on the portal while you are live.

Your stream key

Your ingest key identifies your channel. The suffix after the underscore is the rendition label — it tells us what quality you are sending.

copyrtmp://your-host:1935/live/a1b2c3d4e5f6a7b8_720p
                            └──── key ────┘ └label┘

Label it honestly: if you send 1080p, use _1080p. The label becomes the quality name viewers' players display.

OBS Studio

1. Open Settings → Stream.
2. Service: Custom…
3. Server: rtmp://your-host:1935/live
4. Stream Key: <your-key>_720p
5. In Settings → Output, set Keyframe Interval to 2 seconds. This matters — see below.
6. Click Start Streaming.

ffmpeg

Stream a file in real time:

copyffmpeg -re -i input.mp4 \
  -c:v libx264 -preset veryfast -pix_fmt yuv420p -g 60 \
  -c:a aac -ar 44100 -b:a 128k \
  -f flv rtmp://your-host:1935/live/<KEY>_720p

Stream a webcam (Linux):

copyffmpeg -f v4l2 -i /dev/video0 -f alsa -i default \
  -c:v libx264 -preset veryfast -tune zerolatency -g 60 \
  -c:a aac -b:a 128k \
  -f flv rtmp://your-host:1935/live/<KEY>_720p

-g 60 sets a keyframe every 2 seconds at 30 fps (60 frames). At 60 fps, use -g 120.

SRT ingest — Pro and Business

SRT survives packet loss far better than RTMP, so it is the right choice over the public internet or a bonded/cellular link.

copyffmpeg -re -i input.mp4 \
  -c:v libx264 -preset veryfast -g 60 -c:a aac \
  -f mpegts "srt://your-host:10000?streamid=<KEY>_720p&latency=200000"

latency is in microseconds — 200000 is 200 ms. Raise it on a lossy link (SRT uses that buffer to re-request lost packets); lower it on a clean one to cut delay.

Multi-bitrate (ABR)

We do not re-encode, so you build the ladder in your encoder and push each rendition with its own label. ssh101 assembles the multi-bitrate playlist automatically.

copy# three renditions from one source, three pushes
ffmpeg -re -i input.mp4 \
 -map 0:v -map 0:a -s 1920x1080 -b:v 5000k -c:v libx264 -preset veryfast -g 60 -c:a aac \
   -f flv rtmp://your-host:1935/live/<KEY>_1080p \
 -map 0:v -map 0:a -s 1280x720  -b:v 2800k -c:v libx264 -preset veryfast -g 60 -c:a aac \
   -f flv rtmp://your-host:1935/live/<KEY>_720p \
 -map 0:v -map 0:a -s 854x480   -b:v 1200k -c:v libx264 -preset veryfast -g 60 -c:a aac \
   -f flv rtmp://your-host:1935/live/<KEY>_480p

Viewers' players pick the right rendition automatically from the master playlist. Push one rendition and you simply have a single-quality stream — that is perfectly fine.

Playback URLs

Hand the master playlist to VLC, Safari, hls.js, a Roku channel, or any standard player. Nothing proprietary.

Embedding

Drop the player into any page with an iframe:

copy<iframe src="https://your-host/e/<slug>"
        width="960" height="540"
        frameborder="0" allowfullscreen
        allow="autoplay; fullscreen; picture-in-picture"></iframe>

Or use the playlist directly with your own player:

copy<video id="v" controls playsinline></video>
<script src="https://your-host/hls.min.js"></script>
<script>
  var url = "https://your-host/hls/<slug>/master.m3u8", v = document.getElementById('v');
  if (v.canPlayType('application/vnd.apple.mpegurl')) { v.src = url; }   // Safari, iOS
  else if (Hls.isSupported()) { var h = new Hls(); h.loadSource(url); h.attachMedia(v); }
</script>

DVR & recordings — Pro and Business

DVR lets viewers rewind while you are still live: 30 minutes on Pro, 240 on Business. Enable it per channel on the dashboard; the seek bar extends backwards automatically.

Recording saves each broadcast as VOD. Past recordings are listed on your channel's watch page once the stream ends.

Live to VOD

Turn Recording on for a channel (Business plan) and every broadcast is saved. When the stream ends, the recording appears on the channel's watch page and stays playable.

copy<iframe src="https://your-host/e/<slug>?vod=<id>"
        width="640" height="360" frameborder="0" allowfullscreen></iframe>

The watch page lists each recording with a play link, its .m3u8, and a copyable embed snippet. Recordings use the same player and the same token rules as live — a recording is just another HLS playlist. A live stream autoplays muted; a recording waits for the viewer to press play.

Privacy & security

Visibility

A public channel is listed on the portal while live. An unlisted channel never appears in the directory but plays for anyone with the link.

Secure channels — Pro and Business

Turning on Secure encrypts segments with AES-128 and requires a signed playback token. The token is HMAC-signed, expires, and can be bound to the viewer's IP.

Geo & IP rules — Pro and Business

Allow-list or deny-list countries, restrict to CIDR ranges, or require playback to originate from your own domains (referer rules).

Viewer limits

Each plan carries a ceiling on concurrent viewers, counted per account across all your channels. Beyond the cap, additional viewers receive an HTTP 503 until a slot frees up (idle sessions expire in about 30 seconds).

You may set a lower limit per channel, never a higher one. Upgrade anytime.

API

Everything the dashboard does is plain HTTP, so you can automate it. There are three kinds of endpoint, distinguished by how they authenticate.

1. Public — no authentication

copycurl -s https://your-host/api/stream-info/mychannel
# {"live":true,"width":1280,"height":720,"fps":30,"bitrate":2846000,...}

curl -s https://your-host/api/streamcheck/mychannel | jq .
# {"ok":true,"checks":[{"name":"master reachable","ok":true}, ...]}

2. Session — log in first

These are the dashboard's own endpoints. Authenticate by posting to /login and keeping the session cookie.

copy# log in, create a channel, read back the stream key
JAR=$(mktemp)
curl -s -c "$JAR" --data "email=you@example.com&password=secret" https://your-host/login
curl -s -b "$JAR" -L --data "slug=mychannel&name=My+Channel&listed=on"      https://your-host/app/channels
curl -s -b "$JAR" https://your-host/app | grep -oE '[a-f0-9]{16}' | head -1

3. Operator — HTTP basic auth

Server-level endpoints, authenticated with the operator credentials (-admin-user/-admin-pass).

copycurl -s -u admin:secret https://your-host/api/status | jq .runtime
# {"goroutines":41,"cpu_cores":8,"heap_mb":9.4,"open_streams":12,...}

curl -s -u admin:secret https://your-host/api/analytics | jq '.channels[] | {channel, concurrent, mbps}'

Webhooks (inbound)

Register these with your payment provider; they are the source of truth for subscription state. Each verifies a provider signature and rejects anything unsigned.

Status codes worth knowing

Code examples

The same four operations in three languages. Everything is ordinary HTTP — there is no SDK to install and nothing proprietary on the wire.

copy# --- 1. Is a channel live? (public, no auth)
curl -s https://your-host/api/stream-info/mychannel

# --- 2. Operator: server health + capacity headroom (basic auth)
curl -s -u admin:secret https://your-host/api/status | jq .runtime

# --- 3. Operator: who is watching right now
curl -s -u admin:secret https://your-host/api/analytics \
  | jq '.channels[] | {channel, concurrent, mbps}'

# --- 4. Broadcaster: log in, create a channel, read the stream key
JAR=$(mktemp)
curl -s -c "$JAR" --data "email=you@example.com&password=secret" \
     https://your-host/login
curl -s -b "$JAR" -L --data "slug=mychannel&name=My+Channel&listed=on" \
     https://your-host/app/channels
curl -s -b "$JAR" https://your-host/app | grep -oE '[a-f0-9]{16}' | head -1

copy<?php
$host = 'https://your-host';

function get($url, $auth = null, $jar = null) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    if ($auth) curl_setopt($ch, CURLOPT_USERPWD, $auth);   // "admin:secret"
    if ($jar)  { curl_setopt($ch, CURLOPT_COOKIEJAR, $jar); curl_setopt($ch, CURLOPT_COOKIEFILE, $jar); }
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    return [$code, $body];
}

function post($url, $fields, $jar = null, $auth = null) {
    $ch = curl_init($url);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($fields));
    curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);
    if ($auth) curl_setopt($ch, CURLOPT_USERPWD, $auth);
    if ($jar)  { curl_setopt($ch, CURLOPT_COOKIEJAR, $jar); curl_setopt($ch, CURLOPT_COOKIEFILE, $jar); }
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    return [$code, $body];
}

// --- 1. Is a channel live? (public)
list($code, $body) = get("$host/api/stream-info/mychannel");
$info = json_decode($body, true);
echo $info['live'] ? "LIVE {$info['width']}x{$info['height']}\n" : "offline\n";

// --- 2. Operator: capacity headroom (basic auth)
list($code, $body) = get("$host/api/status", 'admin:secret');
$st = json_decode($body, true);
printf("goroutines=%d streams=%d heap=%.1fMB\n",
    $st['runtime']['goroutines'], $st['runtime']['open_streams'], $st['runtime']['heap_mb']);

// --- 3. Operator: current viewers
list($code, $body) = get("$host/api/analytics", 'admin:secret');
foreach (json_decode($body, true)['channels'] as $c) {
    printf("%-20s %4d viewers  %.2f Mbps\n", $c['channel'], $c['concurrent'], $c['mbps']);
}

// --- 4. Broadcaster: log in and create a channel (session cookie)
$jar = tempnam(sys_get_temp_dir(), 'ssh101');
post("$host/login", ['email' => 'you@example.com', 'password' => 'secret'], $jar);
post("$host/app/channels", ['slug' => 'mychannel', 'name' => 'My Channel', 'listed' => 'on'], $jar);
list($code, $dash) = get("$host/app", null, $jar);
preg_match('/[a-f0-9]{16}/', $dash, $m);
echo "stream key: {$m[0]}\n";
echo "push to:    rtmp://your-host:1935/live/{$m[0]}_720p\n";

copy#!/usr/bin/env python3
"""ssh101+ API examples. Only needs `requests`."""
import re
import requests

HOST = "https://your-host"
OPERATOR = ("admin", "secret")

# --- 1. Is a channel live? (public, no auth)
info = requests.get(f"{HOST}/api/stream-info/mychannel", timeout=10).json()
print(f"live={info['live']} {info.get('width')}x{info.get('height')} @ {info.get('fps')}fps")

# --- 2. Operator: server health + capacity headroom (basic auth)
st = requests.get(f"{HOST}/api/status", auth=OPERATOR, timeout=10).json()
rt = st["runtime"]
print(f"goroutines={rt['goroutines']} cores={rt['cpu_cores']} "
      f"heap={rt['heap_mb']:.1f}MB streams={rt['open_streams']}")
print("features:", st["features"])   # posters / http3 / ffmpeg availability

# --- 3. Operator: who is watching right now
an = requests.get(f"{HOST}/api/analytics", auth=OPERATOR, timeout=10).json()
for c in an.get("channels", []):
    print(f"{c['channel']:20s} {c['concurrent']:4d} viewers  {c['mbps']:.2f} Mbps")

# --- 4. Broadcaster: log in, create a channel, read the stream key
s = requests.Session()   # the session cookie is the credential
s.post(f"{HOST}/login", data={"email": "you@example.com", "password": "secret"}, timeout=10)
s.post(f"{HOST}/app/channels",
       data={"slug": "mychannel", "name": "My Channel", "listed": "on"}, timeout=10)
dash = s.get(f"{HOST}/app", timeout=10).text
key = re.search(r"[a-f0-9]{16}", dash).group(0)
print("stream key:", key)
print("push to:   ", f"rtmp://your-host:1935/live/{key}_720p")
print("watch at:  ", f"{HOST}/hls/mychannel/master.m3u8")

# --- 5. Health check for monitoring (Nagios/Icinga style exit codes)
import sys
try:
    r = requests.get(f"{HOST}/healthz", timeout=5)
    sys.exit(0 if r.status_code == 200 and r.text.strip() == "ok" else 2)
except Exception as e:
    print("CRITICAL:", e)
    sys.exit(2)

API test script

Ships with every install: ssh101-api-check.sh exercises the API surface from any machine, local or remote — no ffmpeg needed, so you can run it from a laptop or a monitoring box.

copy# public endpoints only
./ssh101-api-check.sh https://your-host

# include the operator API
./ssh101-api-check.sh https://your-host admin secret

It checks liveness, the public read API, signup and login, channel create/edit/delete, stream-key retrieval, plan entitlement enforcement, the viewer-limit gate, admin gating, 404 and 403 behaviour, and — with operator credentials — status, analytics, ingest and audit. Exit code 0 means the whole API surface behaves. Use ssh101-check.sh instead when you also want to push real video and measure stream quality.

Troubleshooting

curl -s -u admin:secret https://your-host/api/postercheck/<slug> | jq .

One-line stream test

The fastest way to prove a server accepts a push and plays it back — one command, no scripts, no files:

copy# push a 30-second test pattern with tone
ffmpeg -re -f lavfi -i testsrc2=size=1280x720:rate=30 \
       -f lavfi -i sine=frequency=1000 \
       -c:v libx264 -preset veryfast -g 60 -pix_fmt yuv420p \
       -c:a aac -ar 44100 -b:a 128k -t 30 \
       -f flv rtmp://your-host:1935/live/<KEY>_720p

Then, in another terminal, confirm it plays back and measure it:

copyffplay https://your-host/hls/<slug>/master.m3u8

# or, without a window — prints resolution, fps and bitrate
ffprobe -v error -show_entries stream=width,height,r_frame_rate,bit_rate \
        -of default=noprint_wrappers=1 https://your-host/hls/<slug>/master.m3u8

Self-check script

Every install ships with ssh101-check.sh. Run it from your own machine against any ssh101 server: it creates a throwaway channel, pushes a test stream, and verifies the whole playback path plus stream quality.

copy./ssh101-check.sh https://your-host rtmp://your-host:1935/live

It checks reachability, signup, channel creation, master and variant playlists, content types, CODECS, PROGRAM-DATE-TIME, TARGETDURATION, segment fetch and the TS sync byte — then measures resolution, frame rate, bitrate, audio presence, corrupt packets and continuous playback duration. Exit code 0 means everything passed. Paste the output to support and we can usually pinpoint the fault immediately.