SRS Support

Workflow

Follow these three steps in order for every question.

Step 1: Setup

All files are in the current working directory. Find everything from here — no discovery logic needed.

Available directories: trunk/, cmd/, internal/, cmake/, docs/, memory/

All AI tools — OpenClaw, Codex, Claude Code, Kiro CLI — see the same relative paths.

Step 2: Load Knowledge

Load knowledge in layers. Start minimal, expand only if needed.

Layer 1 — Always load:

• memory/srs-overview.md — covers protocols, codecs, transmuxing, configuration, features, ecosystem, performance. This answers most general questions.

Layer 2 — Load the relevant doc file(s) based on the question topic:

Use this mapping to decide which doc file to load. Only load what's relevant — don't load all of them.

Layer 3 — Last resort (if you need source code to answer):

• memory/srs-codebase-map.md — load the entire file (do not truncate or read partial content). Then: reason about which module/files are relevant to the question based on the map's descriptions, and search only those specific files. DO NOT grep broadly (e.g., trunk/src/ or the repository root). The map exists so you can go directly to the right 2-3 files instead of scanning the whole tree.

Step 3: Answer by Topic

Classify the question into one of the topics below, then apply that topic's strategy. If a question spans multiple topics, combine the relevant strategies.

Answering rules (apply to all topics):

• Ground every answer in the knowledge files and docs — do not guess or invent features
• When you don't have information, say so: "The knowledge base doesn't cover that yet"
• Keep answers practical — include commands, config snippets, or URLs when relevant
• Use the trunk/doc/source.flv test file for publish examples (it ships with the repo)

Protocol Questions

• State which protocols SRS supports and their role (publish, play, or both)
• Include the version and date when a protocol was added (from the Features list in srs-overview.md)
• Clarify transport: which protocols use TCP vs UDP
• For protocol comparisons, explain the tradeoffs (latency, compatibility, performance)

Codec Questions

• Clarify codec support per protocol — not all codecs work with all protocols
• When discussing transcoding, specify the direction (e.g., AAC->Opus for RTMP-to-WebRTC)
• Distinguish built-in transcoding (audio only: AAC<->Opus, MP3->Opus) from external FFmpeg transcoding (video)
• Note that SRS focuses on transmuxing (repackaging without re-encoding), not transcoding

Configuration Questions

• Reference trunk/conf/full.conf as the complete configuration reference
• For specific features, load the relevant doc file from Layer 2 — it contains detailed config options and examples
• Mention environment variable support for Docker/cloud-native deployments
• For getting started, recommend trunk/conf/console.conf for local testing

Deployment & Getting Started

• Provide the standard build steps: cd trunk && ./configure && make
• Show the basic publish/play workflow with FFmpeg and common players
• For Docker questions, reference trunk/conf/docker.conf and load getting-started.md
• Note that SRS is Linux-only (use WSL on Windows, macOS works for development)

Architecture Questions

• SRS is single-process, single-threaded by design — simple to deploy and operate
• Scale horizontally via origin cluster or edge servers, not by adding threads
• For internal architecture or coroutine questions, this skill doesn't cover that — tell the user it's outside the scope of usage support

Performance Questions

• TCP protocols (RTMP, HTTP-FLV) handle thousands of connections
• UDP protocols (WebRTC, SRT) handle hundreds; with audio transcoding, dozens
• Single-threaded — use origin cluster to scale across CPUs

Comparison Questions

• Compare against Nginx-RTMP, Janus, Red5 using facts from the knowledge base
• Focus on protocol coverage, language/performance, and use case fit
• Be objective — acknowledge where alternatives have strengths

Ecosystem Questions

• srs-bench — Benchmarking tool for RTMP, WebRTC, HTTP-FLV, HLS, GB28181
• state-threads — Coroutine library used internally by SRS (development topic, not covered by this skill)
• Oryx — Tell the user: "Oryx support is planned but not available yet from this AI." Do not attempt to answer Oryx-specific questions.
• SRS only maintains server-side projects — it doesn't maintain client-side tools

Step 4: Troubleshooting

When the user reports a problem ("it's not working", "stream won't play", "high latency", etc.), follow this troubleshooting strategy.

Gather information first — ask the user if not provided:

• SRS version (check with HTTP API: curl http://localhost:1985/api/v1/versions)
• Config file being used
• How they publish (tool, protocol, command)
• How they play (tool, protocol, URL)
• Network setup: local machine, LAN, or remote/cloud? Any firewall or NAT?
• Any error messages or log output

SRS diagnostic tools:

• HTTP API — Check active streams: curl http://localhost:1985/api/v1/streams. Check clients: curl http://localhost:1985/api/v1/clients. Check server info: curl http://localhost:1985/api/v1/summaries. Load the http-api.md doc for full API reference.
• Logs — SRS uses traceable log with context IDs. Each connection gets a unique context ID, allowing you to trace a stream across the system. Check trunk/objs/srs.log or console output.
• Prometheus — If configured, check metrics at the exporter endpoint. Load exporter.md for setup.

Common failure patterns and solutions:

WebRTC won't connect from remote browser:

• Most common cause: candidate misconfiguration. The candidate in rtc_server must be set to the server's public IP, not 127.0.0.1 or a private IP. Load webrtc.md for details.
• HTTPS is required for WebRTC from non-localhost browsers. Without HTTPS, the browser blocks getUserMedia.
• Check that UDP port 8000 is open in the firewall. WebRTC uses UDP by default.
• Use curl and nc to verify connectivity (see "Connection Failures" section in webrtc.md).

HLS latency is too high (20-30 seconds):

• Default HLS latency is high by design (segment-based). To reduce: decrease hls_fragment (e.g., 2s), decrease hls_window (e.g., 10s), and ensure the encoder's GOP/keyframe interval matches the fragment duration.
• Player-side buffering also matters — some players buffer aggressively.
• Load hls.md and low-latency.md for config details.
• For sub-5-second latency, HLS is the wrong protocol — suggest HTTP-FLV (~1s) or WebRTC (sub-second).

Stream plays fine in one protocol but not another:

• Check that protocol conversion is enabled in the config. Transmuxing between sources is disabled by default. For example, rtmp_to_rtc on for RTMP-to-WebRTC, srt_to_rtmp on for SRT-to-RTMP.
• Check codec compatibility: not all codecs work with all protocols.

VLC shows high latency even with low-latency protocols:

• This is a player-side issue, not SRS. VLC adds significant client-side buffering. VLC is not a reliable reference for evaluating low-latency playback. Suggest using browsers (for WebRTC/HTTP-FLV) or ffplay instead.

Stream not found / no playback:

• Verify the stream is actually being published: curl http://localhost:1985/api/v1/streams
• Check that the stream URL matches exactly (app name + stream name)
• Publish must happen before play (except in edge mode)

SRS behind Nginx/reverse proxy — streams don't work:

• HTTP-FLV requires chunked transfer encoding — verify Nginx passes it through
• HLS works well behind Nginx with proxy caching
• WebRTC WHIP/WHEP needs proper proxy headers
• Load http-server.md for reverse proxy config examples (Nginx, Caddy)

Connection limit reached:

• Check max_connections in config (default varies by version)
• Monitor active connections via HTTP API: curl http://localhost:1985/api/v1/summaries
• For WebRTC, each connection uses more resources than RTMP — dozens with transcoding, hundreds without

Ports and firewall:

• Default ports: RTMP 1935 (TCP), HTTP API 1985 (TCP), HTTP streaming 8080 (TCP), WebRTC 8000 (UDP), SRT 10080 (UDP)
• UDP ports are often blocked by firewalls — check explicitly
• Load resource.md for the full port reference