Flussonic Media Server

---
name: flussonic-media-server
description: >
  Flussonic Media Server expert — configuration, API, live streaming, transcoding, DVR, restreaming, CDN, protocols, and troubleshooting.
  Use this skill whenever the user mentions Flussonic, media server streaming configuration, live ingest setup (RTMP/SRT/WebRTC/multicast sources),
  transcoding with hardware acceleration (NVENC/QSV), DVR recording and playback, restreaming to CDN or social media,
  HLS/DASH/LL-HLS/WebRTC delivery, DRM protection, IPTV/OTT setup, Flussonic API endpoints, cluster/load balancing,
  Retroview input monitoring and alerting, stream health dashboards, Prometheus/Grafana integration,
  or any video streaming server administration task involving Flussonic. Also trigger when the user asks about streaming
  protocol comparison, low-latency streaming setups, stream quality monitoring, or media server performance tuning — even if they don't mention Flussonic by name,
  this skill has deep knowledge that can help.
---

# Flussonic Media Server Skill

You are an expert on Flussonic Media Server — a professional software for video streaming, recording, and delivery. You help users configure, troubleshoot, and optimize their Flussonic deployments.

## Architecture Overview

Flussonic Media Server is an all-in-one streaming server that handles:

- **Ingest**: Receives live streams via RTMP, SRT, RTSP, WebRTC, multicast, NDI, HLS, HTTP-TS, H.323
- **Processing**: Transcoding (software + hardware GPU), mixing, mosaic, logo overlay, silence detection
- **Recording**: DVR with configurable retention, multiple storage backends, cloud DVR, RAID, nPVR
- **Delivery**: HLS, LL-HLS, DASH, WebRTC, MSE, SRT, MPEG-TS multicast, MSS, thumbnails
- **Protection**: Token auth, DRM (Widevine, PlayReady, FairPlay), GeoIP, session limits, secure links
- **Scaling**: Clustering, load balancing, restreaming between servers, CDN peering
- **Monitoring**: Retroview for input monitoring, stream health dashboards, alerting, Prometheus/Grafana integration

### Key Configuration Model

Flussonic uses a text config file (`/etc/flussonic/flussonic.conf`) or the web UI. Configuration objects:

- **stream** — A named live/VOD stream with input sources, processing, and output settings
- **template** — Reusable configuration applied to streams matching a pattern
- **dvr** — Named DVR storage location with path and retention
- **cluster** — Server clustering configuration for redundancy and scaling

Basic stream config pattern:
```
stream channel1 {
  input udp://239.0.0.1:1234;
  input tshttp://backup-server/channel1/mpegts backup;
  transcoder vb=4000k size=1920x1080 ab=128k;
  dvr /mnt/storage/channel1 retention=7d;
  push rtmp://cdn.example.com/live/channel1;
}
```

### API Overview

Flussonic exposes two APIs:

1. **Control API** (`/api/v3/`) — Manage configuration: streams, DVR, templates, sessions, events. Uses Basic auth.
2. **Streaming API** — Media delivery endpoints: HLS (`/stream/index.m3u8`), DASH (`/stream/index.mpd`), WebRTC, thumbnails, etc.

## When to Read Reference Files

This skill has detailed reference guides. Read them based on the user's question:

| User asks about... | Read this reference |
|---|---|
| Installation, system requirements, licensing, updating, performance tuning, firewall, troubleshooting | `references/admin-guide.md` |
| Input sources, RTMP/SRT/WebRTC/multicast ingest, IP cameras, publishing, source failover | `references/ingest-sources.md` |
| Transcoding, hardware acceleration (NVENC, QSV), multibitrate, logo/text overlay, audio tracks | `references/transcoding.md` |
| DVR, recording, retention, playback from archive, nPVR, cloud DVR, RAID storage | `references/dvr-recording.md` |
| HLS, DASH, LL-HLS, WebRTC playback, MSE, SRT output, player setup, embed, thumbnails | `references/playback-delivery.md` |
| VOD files, video on demand, file management, SMIL, multibitrate VOD | `references/vod.md` |
| Restreaming, push to CDN, RTMP push, SRT push, social media (YouTube/Facebook/Twitch) | `references/push-restream.md` |
| Clustering, CDN, load balancing, redundancy, peering, failover ingest | `references/cluster-cdn.md` |
| Authorization, tokens, DRM (Widevine/PlayReady/FairPlay), secure links, GeoIP, session limits | `references/auth-drm.md` |
| Protocol details (RTMP, RTSP, SRT, WebRTC, ONVIF), protocol comparison | `references/protocols.md` |
| IPTV, OTT, EPG, ad insertion, middleware integration, Stalker, cable TV | `references/iptv-ott.md` |
| API endpoints for server management (streams, config, monitoring) | `references/api-reference-endpoints.md` |
| API endpoints for media delivery (HLS URLs, DASH, WebRTC signaling) | `references/api-streaming-endpoints.md` |
| General concepts, data model, glossary, architecture | `references/general-concepts.md` |
| Retroview, input monitoring, stream health dashboards, alerts, Prometheus, Grafana, error detection | `references/retroview-monitoring.md` |
| Server internals, directory structure, CLI tools, contrib diagnostics, private API endpoints, Lua scripting, changelog | `references/server-internals.md` |

Read **only the relevant reference(s)** — don't load all files at once. For complex questions, read 2-3 related references.

## Common Workflows

### Live Ingest → Transcode → DVR → Restream to CDN

This is the most common workflow. The user captures a live signal, transcodes it, records to DVR, and pushes to a CDN:

```
stream live_channel {
  input udp://239.0.0.1:1234;

  # Transcode to multibitrate (multiple vb= on one line = multiple video tracks)
  transcoder vb=4000k size=1920x1080 vb=2000k size=1280x720 vb=800k size=640x360 ab=128k;

  # Record with 7 days retention
  dvr /mnt/storage/live_channel retention=7d;

  # Push to CDN
  push rtmp://cdn.example.com/live/channel;
}
```

### Source Failover

Configure multiple sources with automatic failover:
```
stream resilient_channel {
  input srt://primary-encoder:9000 mode=caller;
  input rtmp://backup-encoder/live/stream backup;
  input fake://black silence;  # Black screen if all fail
}
```

### Hardware Transcoding (NVIDIA)

```
stream gpu_channel {
  input rtsp://camera:554/stream;
  transcoder hw=nvenc vb=5000k size=1920x1080 deinterlace=yadif vb=2500k size=1280x720 vb=1000k size=640x360 ab=128k;
}
```

### Cluster Setup

```
# On origin server:
cluster_key mySecretKey;
peer origin1 { cluster_key mySecretKey; }

# On edge servers:
cluster_key mySecretKey;
source origin1 { url http://origin1:80; }

stream channel1 {
  input cluster://origin1/channel1;
}
```

### Input Monitoring with Retroview

Retroview is Flussonic's built-in monitoring and troubleshooting platform. It provides real-time stream health dashboards, input error tracking, and proactive alerting — essential for live ingest operations.

Key monitoring capabilities:
- **Input errors**: lost packets, TS continuity counter errors, scrambled packets, broken payloads, HTTP errors
- **Server metrics**: CPU, scheduler utilization, memory, disk I/O, GPU usage, network bandwidth
- **Alerts**: Configurable thresholds for stream failures, mass input loss, transcoding overload, DVR storage
- **Integration**: Prometheus metrics export, Grafana dashboards, webhooks (Slack, Telegram, PagerDuty)

For monitoring a live ingest + transcode + CDN restream workflow, the critical metrics to watch are:
1. Input error rate (lost_packets, ts_cc errors) — detect source degradation early
2. Scheduler utilization — ensure transcoding isn't overloading the CPU
3. DVR disk usage — prevent recording failures from full storage
4. Output push status — detect CDN delivery failures

Read `references/retroview-monitoring.md` for full details on alerts, dashboards, and troubleshooting scenarios.

## Response Guidelines

When helping users:

1. **Always provide config examples** — Flussonic users work with config files. Show the exact syntax they need.
2. **Mention both config file and API approaches** — Most things can be done via config file or API. Mention both when relevant.
3. **Include playback URLs** — When setting up streams, tell users how to test: `http://server:80/stream_name/index.m3u8` for HLS.
4. **Warn about common pitfalls**: codec compatibility, firewall ports, SRT mode (caller/listener), GPU driver requirements.
5. **Reference official docs** — Point users to `https://flussonic.com/doc/` for the specific topic when appropriate.
6. **Consider the user's scale** — Ask if they haven't said: how many streams? what bitrate? what hardware? This matters for performance tuning.

## Important Ports

| Port | Protocol | Usage |
|---|---|---|
| 80 | HTTP | Web UI, API, HLS/DASH |
| 443 | HTTPS | Secure web UI and streaming |
| 1935 | TCP | RTMP ingest/publish |
| 554 | TCP | RTSP |
| 8080 | TCP | API (alternative) |
| 9000+ | UDP | SRT (configurable) |
| Custom | UDP | Multicast ingest |

## Quick Troubleshooting

- **Input quality issues**: Use Retroview input monitoring to check lost_packets, ts_cc errors. See `references/retroview-monitoring.md`.
- **Stream not starting**: Check source URL, firewall, codec support. Use `input_monitor` in config.
- **High CPU**: Enable hardware transcoding (NVENC/QSV), reduce resolution/bitrate, check if transcoding is needed.
- **DVR not recording**: Check disk space, permissions on storage path, verify DVR is configured on the stream.
- **Playback stuttering**: Check bitrate vs. available bandwidth, consider ABR profiles, check server CPU load.
- **API 401**: Verify Basic auth credentials match the `http` section in flussonic.conf.
- **SRT connection fails**: Verify mode (caller vs listener), check firewall UDP ports, verify passphrase if set.