Ocyss/srs-auth / .agents/skills/internal-docs-for-srs
internal-docs-for-srs
FlaggedRoute SRS and Oryx tasks to the smallest relevant set of trusted project documentation and maintain the project documentation bundled with this skill. Use whenever support or development work requires locating, choosing, reading, creating, updating, or reviewing SRS documentation, or whenever Oryx work requires project documentation for deployment, streaming, authentication, recording to local or S3-compatible storage, restreaming, virtual live, camera, transcoding, HTTPS, APIs, callbacks, AI features, or development. Includes the C++ media server documentation, Oryx project documentation, website pages, changelog, executable API examples, and next-generation Go server and performance documentation.
references/proxy/proxy-protocol.md
View on GitHub# Protocol
## Backend Server Registration
The origin server can register itself to the proxy server, so the proxy server can load balance
the backend servers.
### Default Backend Server (For Debugging)
The proxy can automatically register a default backend server for testing and debugging purposes, controlled by environment variables:
```bash
# Enable default backend server
PROXY_DEFAULT_BACKEND_ENABLED=on
# Default backend server configuration
PROXY_DEFAULT_BACKEND_IP=127.0.0.1
PROXY_DEFAULT_BACKEND_RTMP=1935
PROXY_DEFAULT_BACKEND_HTTP=8080 # Optional
PROXY_DEFAULT_BACKEND_API=1985 # Optional
PROXY_DEFAULT_BACKEND_RTC=8000 # Optional (UDP)
PROXY_DEFAULT_BACKEND_SRT=10080 # Optional (UDP)
```
When enabled, the proxy automatically registers this default backend server at startup and sends heartbeats every 30 seconds to keep it alive. This is useful for:
- Quick testing without setting up backend server registration
- Development and debugging scenarios
- Single-server deployments
### Automatic Registration
SRS 5.0+ has built-in support for automatic registration to the proxy server using the heartbeat feature. Configure SRS to send heartbeats to the proxy's System API:
```nginx
# For example, conf/origin1-for-proxy.conf in SRS.
heartbeat {
enabled on;
interval 9;
url http://127.0.0.1:12025/api/v1/srs/register;
device_id origin1;
ports on;
}
```
When heartbeat is enabled:
- SRS automatically registers itself on startup
- Sends periodic heartbeats (default: every 30 seconds) to keep the registration alive
- Proxy marks servers as unavailable if heartbeats stop (after
`PROXY_ORIGIN_SERVER_TTL`, default 300 seconds)
- No manual intervention required - fully automatic
For multi-proxy deployments, configure every proxy to use the same shared Redis instance. An
origin only needs to send each heartbeat to one proxy because that proxy writes the registration
to shared Redis, where all proxies can read it. However, SRS accepts only one `heartbeat.url`, so
the URL should point to a highly available frontend such as an NLB or VIP that routes the System
API to a healthy proxy. If it points directly to one proxy and that proxy fails, SRS does not try
another proxy and the registration expires after `PROXY_ORIGIN_SERVER_TTL` (default 300 seconds).
This is the **recommended approach** for production deployments with SRS backend servers.
### Manual Registration API
For non-SRS backend servers or custom integrations, use the HTTP API directly:
```bash
curl -X POST http://127.0.0.1:12025/api/v1/srs/register \
-H "Connection: Close" \
-H "Content-Type: application/json" \
-H "User-Agent: curl" \
-d '{
"device_id": "origin2",
"ip": "10.78.122.184",
"server": "vid-46p14mm",
"service": "z2s3w865",
"pid": "42583",
"rtmp": ["19352"],
"http": ["8082"],
"api": ["19853"],
"srt": ["10082"],
"rtc": ["udp://0.0.0.0:8001"]
}'
#{"code":0,"pid":"53783"}
```
A single request only registers the backend until its configured TTL expires. Custom integrations
must repeat the request periodically to maintain the heartbeat. Configure the lifetime with
`PROXY_ORIGIN_SERVER_TTL` using a positive Go duration such as `45s` or `2m`; it must remain longer
than the heartbeat interval. The default is `300s`.
### Registration Fields
* `ip`: Mandatory, the IP of the backend server. Make sure the proxy server can access the backend server via this IP.
* `server`: Mandatory, the server id of backend server. For SRS, it stores in file, may not change.
* `service`: Mandatory, the service id of backend server. For SRS, it always changes when restarted.
* `pid`: Mandatory, the process id of backend server. Used to identify whether process restarted.
* `rtmp`: Mandatory, the RTMP listen endpoints of backend server. Proxy server will connect backend server via this port for RTMP protocol.
* `http`: Optional, the HTTP listen endpoints of backend server. Proxy server will connect backend server via this port for HTTP-FLV or HTTP-TS protocol.
* `api`: Optional, the HTTP API listen endpoints of backend server. Proxy server will connect backend server via this port for HTTP-API, such as WHIP and WHEP.
* `srt`: Optional, the SRT listen endpoints of backend server. Proxy server will connect backend server via this port for SRT protocol.
* `rtc`: Optional, the WebRTC listen endpoints of backend server. Proxy server will connect backend server via this port for WebRTC protocol.
* `device_id`: Optional, the device id of backend server. Used as a label for the backend server.
### Listen Endpoint Format
The listen endpoint format is `port`, or `protocol://ip:port`, or `protocol://:port`, for example:
* `1935`: Listen on port 1935 and any IP for TCP protocol.
* `tcp://:1935`: Listen on port 1935 and any IP for TCP protocol.
* `tcp://0.0.0.0:1935`: Listen on port 1935 and any IP for TCP protocol.
* `tcp://192.168.3.10:1935`: Listen on port 1935 and specified IP for TCP protocol.
### Integration Options Summary
There are three ways to register backend servers to the proxy:
1. **Automatic Registration (Recommended for Production)**
- Use SRS 5.0+ with heartbeat feature
- Fully automatic, no manual scripts needed
- Self-healing: automatically re-registers if proxy restarts
- See "Automatic Registration (SRS 5.0+ Heartbeat)" section above
2. **Manual Registration API**
- For non-SRS media servers (nginx-rtmp, Node-Media-Server, etc.)
- Requires custom registration script or service
- More flexible for heterogeneous environments
- See "Manual Registration API" section above
3. **Default Backend (Development/Testing Only)**
- Quick setup via environment variables
- No backend server configuration needed
- Use for development, testing, and debugging
- See "Default Backend Server (For Debugging)" section above
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |