KlipKast Broadcaster MAX — Documentation

Everything a broadcaster, producer, or administrator needs to run KlipKast end-to-end. Golden Baseline v64.0.78.

1. Introduction

KlipKast Broadcaster MAX is a self-hosted streaming server that turns a single Linux box into a full broadcast network — HLS delivery, DVR, PlayBox playout, and multi-protocol output (HLS, RTMP, RTSP, SRT). This documentation is split into a User Guide for day-to-day operators and an Administrator Guide for the person running the server.

2. Signing In

Open a browser to the address your administrator gave you (typically https://ip_address/). Sign in with your operator account — the header shows your username and the server you're connected to.

3. Quick Start

1. Sign in and open the Dashboard.
2. Create your first stream from the Streams page.
3. Select the preferred output — such as HLS or RTMP.
4. Watch the preview and share the HLS URL with viewers.

4. Dashboard

The Dashboard is the single-glance view of your broadcast network. Summary cards show live streams, viewers, outbound bandwidth, and uptime. The "Currently Live" table lists every source that is on-air, and the right rail shows real-time system health for CPU, RAM, ramdisk, and service ports.

Status pills

• LIVE — source is publishing and viewers can connect.
• STANDBY — a template or PlayBox loop is filling the slot until a real source returns.
• OFFLINE — source is intentionally stopped.
• ERROR — source failed a health-check; see the Health page.

5. Streams

The Streams page lists every ingest you have configured. From here you create new streams, search by name, filter by type or status, and open any stream for its full detail view.

5.1 Creating a new stream

1. Click + New Stream in the toolbar.
2. Give the stream a URL-safe name (letters, numbers, dashes, slashes). This becomes the last segment of every output URL.
3. Pick a source type: HLS Pull, RTMP Push-In, SRT, MPEG-TS, or Icecast.
4. Paste the source URL. For push-in types, KlipKast shows you the ingest URL and key to hand to the encoder.
5. Optionally attach a Template — this pre-fills output, destinations, and overlays in one click.
6. Save. The stream starts immediately if Auto-start is enabled.

5.2 Supported source types

5.3 Stream detail

Opening any stream drops you into its detail view. The preview panel shows live output and media metadata (resolution, codec, FPS, audio, GOP, bitrate). Other panels list every publish endpoint and every push destination.

5.4 Endpoints

Every live stream is published on multiple protocols simultaneously. Share the URL that matches your viewer's player:

• HLS — browsers, iOS, Roku, most Smart TVs.
• RTSP — IP-camera clients and low-latency players.
• RTMP — legacy players and re-ingest.

When token protection is enabled, viewer URLs are automatically routed through the token proxy on port 3003 and rotated by the server. Viewers never see the underlying token.

6. Offline Streams

The Offline Streams page collects every configured stream that isn't currently live. Use it to bulk-toggle Auto-start, review the last error, or delete unused ingests. This is the fastest way to find a stream that dropped overnight and see why.

7. Templates

Templates are reusable "recipes" that pre-configure a stream: output protocols, push destinations, overlays, DVR retention, and token-refresh policy. Instead of configuring six panels for every event, pick a template and the stream is production-ready.

When to make a template

• You run more than one stream with the same push destinations.
• You use the same overlay style across multiple events.
• You rely on a token-refresh source pattern (partner CDNs, licensed feeds).
• You need a repeatable "standby" configuration for holiday coverage.

8. VOD

The VOD page hosts every clip you've saved from a recording. Each entry has its own scrubbable player and public URL. Clips are remuxed to MP4 without re-encoding, so publishing is instant. Delete removes both the file and the URL.

9. Playlists

Playlists are the source content for PlayBox. Upload MP4/MOV files, drag them into the desired order, trim in/out points, and optionally attach an overlay to each clip. A single playlist can back multiple PlayBox slots at once.

10. Cameras

The Cameras page is a purpose-built view for IP-camera and RTSP ingest. It auto-discovers ONVIF devices on the local network, shows a still-image thumbnail per camera, and lets you promote any camera to a full stream in one click.

11. Advertising

Advertising handles ad-break scheduling and mid-roll insertion. Define ad pods, assign them to stream slots, and choose a trigger — time-based, SCTE-35 marker, or manual cue. All ad state is persisted alongside the stream so schedules survive reboots.

12. PlayBox — Scheduled Playout

PlayBox turns a folder of MP4 clips into a live 24/7 channel. Drop files into the playlist, bind the playlist to a stream slot, and PlayBox handles the rest: continuous looping, in-clip overlay burn-in, cinematic push-back transitions, and atomic file swaps so the output never blinks.

12.1 Building a playlist

1. Upload MP4/MOV clips into the Playlists page.
2. Drag them into the desired order. Duration is auto-detected.
3. Optionally attach an overlay to each clip — it's burnt in during render, not composited live, which is why it looks broadcast-clean.
4. Bind the playlist to a stream slot (for example the willberightback/live standby channel).
5. Choose Continuous loop, Scheduled start, or One-shot.

12.2 Overlays

Overlays live in a small library. Each is a PNG or animated MOV with an alpha channel. Common examples: news lower-thirds, interview bugs, weather crawls, and emergency alerts. Overlays can be scheduled, recurring, or triggered live.

13. Push & Restream

Every stream can fan out to multiple RTMP/RTMPS destinations at once — YouTube, Facebook, Twitch, custom CDNs — without re-encoding. A supervisor process (push-fanout) reconciles the desired list every five seconds, reconnects on drop, and persists the destination list to disk.

Adding a destination

1. Open the stream detail and select the Push tab.
2. Click Add destination.
3. Enter a label, the RTMP/RTMPS URL, and the stream key.
4. Click Test to verify handshake, then Save & Push.
5. Toggle Reconnect on. The supervisor maintains the push automatically.

14. Archives / DVR

Every live stream can automatically record to disk. Choose retention per stream: rolling window (e.g. 6 hours), scheduled recording, or continuous archive. Recordings appear on the Archives page as scrubbable segments.

Turning a recording into VOD

1. Open Archives and scrub to the in-point.
2. Set the out-point.
3. Click Save as VOD — the clip is remuxed to MP4 without re-encoding.
4. The clip appears on the VOD page with its own playback URL.

15. Live Now / Analytics / Viewers

Live Now is a wall-view of every on-air stream — perfect for control rooms. Analytics shows historical viewer counts, bitrate stability, and drop-out heatmaps. Viewers lists active sessions and lets you kick abusive clients.

16. Config Editor

The Config Editor is the "raw" view of the server configuration for administrators. It exposes advanced knobs that are not surfaced in the standard UI — nginx snippets, custom FFmpeg flags, ramdisk sizing overrides — with schema validation and an atomic save. Changes take effect on the next service reload; the editor warns before any destructive save.

17. Health

The Health page is your first stop when something goes wrong. It shows service status for all supervisors, ramdisk usage, ghost-RAM guard state, and per-stream health scores. Most operator problems fit into three buckets:

A stream shows OFFLINE that should be on

• Check the source URL is reachable (Health → Source Probe).
• Check push credentials have not expired.
• For token-refresh streams, verify the refresh policy is still valid.

Viewers report buffering

• Look at HLS Delivery (port 3002) throughput — is bandwidth saturated?
• Check ramdisk occupancy; tmpfs full will cause segment stutter.
• Confirm the source itself is stable — Analytics shows bitrate variance.

Push destination keeps reconnecting

• Verify the platform accepts the stream key.
• Check whether the platform enforces per-key limits (YouTube, Twitch).
• Look at push-fanout logs on the Health page for the exact upstream error.

18. Block

Block manages the allow/deny lists that gate viewer access. You can block by IP, CIDR range, ASN, or country code. The Exceptions tab layers on top: a single allow rule can override a broad block, and a single deny can carve out a hole in an otherwise-open policy.

19. Alerts

Alerts define how KlipKast notifies you when something changes state — stream drop, disk pressure, push reconnect storm, license expiry. Delivery channels include email and webhook. Every alert carries a severity and can be silenced during planned maintenance.

20. Viewers

Viewers shows every active playback session in real time: IP, geolocation, player type, stream, bitrate, and session length. Click any session to kick it, block the IP, or open its full history in Analytics.

21. Analytics

Analytics is the historical companion to Viewers. Chart concurrent viewers, aggregate watch time, geographic distribution, and per-stream bitrate variance over any date range. Export to CSV for reporting.

22. Server Setup

Server Setup is the first-run wizard and ongoing infrastructure page: bind addresses, TLS certificates, ramdisk sizing tier, RTMP publish policy, and the RTMP ghost-auto-deletion window. Changes here often require a controlled service restart — the page tells you before you save.

23. Settings

Settings is the catch-all for account, license, and preferences. Rotate your license key, manage operator accounts and roles, set the default DVR retention, and toggle features such as token-refresh proxying and PlayBox global overlays.

24. Architecture Overview

KlipKast is a single-node broadcast pipeline. All state is JSON on disk under /opt/streamhub/data/ — there is no external database. Media flows through a two-stage pipeline (ingest → render → publish), buffered on a ram-backed tmpfs, and served by a hardened Node.js API alongside an FFmpeg-based delivery layer.

25. Port Map

Ports 3000 and 9090 are strictly forbidden — they clash with common third-party tooling.

26. System Requirements

27. Installation

Installation is a single script executed as root. It pins the version, installs dependencies, lays down all services, and starts the supervisors.

curl -fsSL https://ip_address/install/streamhub-installer-v6478.sh | sudo bash

1. Browse to https://ip_address/ and complete first-run setup.
2. Create the initial admin account.
3. Paste your license key on Settings → License.
4. Reboot to confirm all services come up cleanly.

28. On-Disk Layout

/opt/streamhub/
  backend/
    server.js                       ← authoritative backend
    push-fanout.js                  ← RTMP push supervisor
    hls-token-proxy-service.js      ← port 3003
  data/
    streams.json                    ← single source of truth
    push-destinations-backup.json   ← shadow safety net
    templates/
    overlays/
  tmpfs/                            ← ram-backed HLS segments

All backend files live under /opt/streamhub/backend/. Never edit server.js under any other path — patches applied elsewhere are ignored.

29. Services (systemd)

systemctl status streamhub                  # main API + control
systemctl status streamhub-push-fanout      # RTMP push supervisor
systemctl status streamhub-hls-token-proxy  # port 3003
systemctl status nginx                      # TLS front door

systemd is mandatory. Do not run the backend under pm2, forever, or a bare shell — the supervisor policies and ghost-RAM guard depend on unit-level restart semantics.

30. Persistence Model

There is no database. Every persistent value lives in JSON:

• streams.json — every stream record, including template_id, push_destinations, restream_destinations.
• push-destinations-backup.json — shadow of destinations only, used to rehydrate recreated streams.
• templates/*.json — one file per template.

The shadow file is written whenever destinations change. On stream recreation the restore path only fills keys that are entirely absent. It never overwrites live values. This behavior is frozen by v64.0.78.

31. Ghost-RAM Protection

1. Reaper — scans /proc for orphaned ffmpeg every 30 seconds and terminates the owning cgroup.
2. Guard — enforces a per-stream RAM ceiling; exceeding it triggers a graceful restart.
3. Spawn-lock — prevents duplicate ffmpeg instances for the same stream ID.

32. Token Refresh & Proxy

Partner feeds often use short-lived tokens embedded in HLS URLs. KlipKast performs zero-restart token swaps via a loopback proxy on port 3003:

• Tokens refresh at 90% of their advertised lifetime, with a 3-second minimum floor.
• New tokens are hot-swapped without dropping viewers.
• Corrupt refresh intervals on disk are auto-repaired at load time.

33. Backups

tar czf /var/backups/streamhub-$(date +%F).tgz \
    /opt/streamhub/data /opt/streamhub/backend/*.json

To restore, stop services, extract into place, and start again. Because state is JSON, restores are inspectable and diffable.

34. Upgrades & Version Policy

Versions use MAJOR.MINOR.PATCH where PATCH ranges 0–99. When PATCH hits .99 the MAJOR rolls over. Certain versions are frozen "Golden Baselines" and MUST NOT be patched in place — any fix bumps to the next version.

Currently frozen: v64.0.78 (current), v64.0.53, v64.0.52, v64.0.49, v64.0.42, v63.0.88, v63.0.85, v63.0.83, v63.0.74, v62.0.98.

35. Security

• Serve the UI and API exclusively behind nginx with TLS. HTTP-only exposure is not supported.
• Restrict port 3001 to loopback or the admin VLAN.
• Never expose port 3003 externally — it is a loopback token proxy.
• Roles are role-based: operator, admin, viewer. Store role assignments only in the dedicated table.
• License key checks happen at every startup and on every stream toggle.

36. Monitoring

• HTTP probe on https://ip_address/api/health (expect 200 + status:"ok").
• TCP probe on 1935 (RTMP ingest).
• Disk-free alarm at 1 GB (500 MB is the hard floor before ingest is paused).
• RAM alarm at 85% (primary bottleneck).

37. Troubleshooting Playbook

The UI loads but no streams start

• Check systemctl status streamhub — the API may be up while ffmpeg spawn is blocked.
• Check disk-free is above 500 MB.
• Check tmpfs is mounted (mount | grep streamhub).

RTMP push destinations disappear after reboot

Fixed for good in v64.0.78. If you observe it on v64.0.78, your shadow file was probably deleted by a rogue backup script. Restore push-destinations-backup.json from backup — the server rehydrates on next stream recreation.

High RAM and swap thrash

• Look for dead sources — the ghost-RAM guard reports them in journalctl.
• Lower ramdisk auto-size tier.
• Reduce DVR retention on high-bitrate streams.

38. Glossary

• HLS — Apple HTTP Live Streaming. Segmented video over HTTPS.
• RTMP — Real-Time Messaging Protocol. Encoder-to-server ingest and downstream push.
• RTSP — Real-Time Streaming Protocol. Low-latency, common on IP cameras.
• SRT — Secure Reliable Transport. Modern low-latency contribution over lossy internet.
• PlayBox — KlipKast's scheduled playout engine for looped and scheduled content.
• Template — Reusable stream configuration bundling output, destinations, and overlays.
• Golden Baseline — A frozen version. No in-place edits; any fix bumps the version.
• Ramdisk / tmpfs — RAM-backed filesystem used for hot HLS segments.