Skip to content
StreamHub Docs

Quick start

This walks through a full loop on a fresh install: publish a stream in, play it back, and find the recording. It assumes a real domain; swap in 127.0.0.1:3020 over plain HTTP if you did a localhost test install.

  1. Install

    Section titled “Install”
    Terminal window
    curl -fsSL https://www.streamhub.studio/install.sh | sudo bash

    See Quick install for the flags. When it finishes it prints a summary: the dashboard URL, admin credentials, an sk_ API token, and a cluster token. Keep that output — the token especially only ever prints once.

  2. Log in to the dashboard

    Section titled “Log in to the dashboard”

    Open https://<your-domain>/ and sign in with the break-glass admin account printed by the installer (ADMIN_USER / ADMIN_PASS, default user admin). This is a JWT session against POST /api/v1/auth/login — fine for day-1; invite real users afterward.

  3. Set your API token

    Section titled “Set your API token”

    Everything below also works as curl against the REST API. Export the sk_ token from the install summary (or grep STREAMHUB_API_TOKEN /opt/streamhub/.env):

    Terminal window
    export STREAMHUB_TOKEN=sk_...
    export BASE=https://<your-domain>/api/v1

  4. Create an app

    Section titled “Create an app”

    A fresh install already seeds one default app, live. To create another (from the dashboard’s Apps tab, or via the API):

    Terminal window
    curl -s -X POST $BASE/apps \
      -H "Authorization: Bearer $STREAMHUB_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"name":"demo","displayName":"Demo"}'

    This scaffolds apps/demo/ on disk (config.yaml, its own app.db, recordings/, snapshots/, samples/) and generates the app’s sample pages.

  5. Get an ingest endpoint and publish

    Section titled “Get an ingest endpoint and publish”

    RTMP (OBS, ffmpeg):

    Terminal window
    curl -s -X POST $BASE/apps/demo/ingress \
      -H "Authorization: Bearer $STREAMHUB_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"inputType":"rtmp","room":"studio"}'
    # → { "data": { "ingressId": "IN_...", "url": "rtmp://<domain>:1935/demo", "streamKey": "..." } }

    Push to url/streamKey combined:

    Terminal window
    ffmpeg -re -i input.mp4 -c:v libx264 -c:a aac -f flv \
      "rtmp://<domain>:1935/demo/<streamKey>"

    WHIP: create an ingress with "inputType":"whip" instead and point a WHIP-capable encoder/browser at the returned endpoint — it hits port 8080 directly, not through the proxy.

    WebRTC from a browser: use one of the app’s generated sample pages — webrtc-publish.html to publish, webrtc-play.html to subscribe — at https://<your-domain>/samples/demo/<file>, or embed the streamhub-adaptor SDK (/sdk/streamhub-adaptor.global.js) in your own page. Every app also gets a set of turnkey vertical pages generated the same way: a CCTV grid, live-shopping, telemedicine, a radio player, and a Meet-style group call with chat at https://<your-domain>/samples/demo/conference.html.

  6. Play it back

    Section titled “Play it back”

    WebRTC (sub-second) — mint a subscribe-only viewer token and open the public player URL it returns:

    Terminal window
    curl -s -X POST $BASE/apps/demo/tokens \
      -H "Authorization: Bearer $STREAMHUB_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"room":"studio","canPublish":false}'
    # → "playUrl": "https://<your-domain>/play/demo/demo-studio", plus an embeddable "iframe"

    HLS — unlike WebRTC, live HLS isn’t running by default; start it explicitly for the active stream, then open the playlist in any HLS player (video.js, VLC, Safari):

    Terminal window
    curl -s -X POST $BASE/apps/demo/streams/<streamId>/hls/start \
      -H "Authorization: Bearer $STREAMHUB_TOKEN"
    # → "playlistUrl": "https://<your-domain>/hls/demo/demo-studio/index.m3u8"

  7. Where recordings go

    Section titled “Where recordings go”

    Start a recording for the live room:

    Terminal window
    curl -s -X POST $BASE/apps/demo/recording/start \
      -H "Authorization: Bearer $STREAMHUB_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"roomName":"demo-studio"}'
    # → { "data": { "vodId": 12, "egressId": "EG_...", "status": "recording" } }

    Egress writes an MP4 to apps/demo/recordings/ under DATA_DIR (status: recording). When you stop it (POST /apps/demo/recording/12/stop), a job uploads the file to the app’s S3 bucket — configured per app (see Configuration for config.yaml and data/secrets.json) — generates a snapshot, and flips the VOD to status: uploading then ready. Fetch it with a fresh presigned URL:

    Terminal window
    curl -s $BASE/apps/demo/vods/12 -H "Authorization: Bearer $STREAMHUB_TOKEN"

That’s the full loop: install → app → ingest → publish → play (WebRTC or HLS) → recording → VOD in S3. From here, see Directory structure for what’s on disk, or the API reference for every endpoint.