Stellarr Media
Stellarr Media (stellarr-media, in media/) is Stellarr's Rust Selective Forwarding Unit (SFU). Every voice channel and direct call goes through it: each participant opens a single RTCPeerConnection to the media server, which forwards microphone, camera, and screen-share RTP packets to everyone else in the room without transcoding or mixing. Browsers never send media directly to one another.
This page covers:
- Hub leg: SignalR methods and events between browser clients and
AppHub. - Control API: Loopback HTTP protocol between
AppHubandstellarr-media. - Media plane: ICE-lite transport, SDP negotiation, RTP forwarding, and resource limits.
See Voice and RTC protocol for bootstrap configuration, VoiceSignal state messages, VoiceState, and audio/video profiles.
Overview
| Aspect | Behavior |
|---|---|
| WebRTC engine | str0m (sans-IO ICE, DTLS, SRTP, RTP/RTCP) |
| Transport | ICE-lite on a single UDP socket (0.0.0.0:49000) |
| Forwarded media | Microphone audio, camera video, screen video, and screen audio |
| Media processing | Packet-level RTP forwarding; no decoding, mixing, or transcoding |
| Authorization | AppHub authorizes seats; stellarr-media only accepts commands on its loopback control API |
| Signaling path | Browser ↔ AppHub (SignalR) ↔ stellarr-media (127.0.0.1:5200) |
| Connections per client | Single RTCPeerConnection (bundlePolicy: "max-bundle") |
| Offer direction | Browser offers published tracks (sendonly); stellarr-media offers forwarded tracks (sendonly to the receiver) |
| Glare resolution | Browser is the impolite peer; stellarr-media is the polite peer |
| Track attribution | Server-issued directory mapping SDP mid → { userId, kind, streamId, heldBack } |
| Downlink adaptation | Per-receiver GoogCC BWE: all subscribed audio forwards; video forwards in subscription priority order while headroom allows, holding excess video back per receiver |
| Direct calls | Routed through the media server just like server voice channels |
Topology
Because all media goes through the container, any browser outside the Docker host needs the media server's public candidate: set PUBLIC_IP and forward UDP STELLARR_MEDIA_PORT (default 49000) to the host on the same external port. Without PUBLIC_IP, the media server advertises only the container's internal address, which off-host browsers can reach only through TURN (coturn). See Requirements.
GET /api/bootstrap returns:
{
"protocolVersion": 1,
"mediaServer": "udp://chat.example.com:49000"
}mediaServerisudp://{Rtc:PublicHost}:{Rtc:MediaPort}(falling back tolocalhostwhenRtc:PublicHostis unset). It is used for diagnostics; actual connection addresses come from SDP ICE candidates.
Hub leg
AppHub exposes two SignalR methods and two events for the media server:
| Type | Name | Description |
|---|---|---|
| Method | OpenMediaSession | Allocate a media session for the caller's active voice seat |
| Method | SendMediaSignal | Send an SDP offer/answer, ICE candidate, or receive subscriptions to stellarr-media |
| Event | MediaSignal | Deliver an SDP offer/answer or track directory from stellarr-media |
| Event | MediaSessionClosed | Notify the client that the media session was closed by the media server |
OpenMediaSession(channelId) → { sessionId }
- Requires the caller to hold an active seat in
channelId(viaJoinVoice). - If the connection already has a media session, the previous session is detached and closed asynchronously in the background. Because
stellarr-mediaenforces at most one session peruserId, out-of-order close requests cannot affect the new session. - Returns an opaque
sessionIdthat must accompany all subsequentSendMediaSignalcalls. Clients ignore anyMediaSignalorMediaSessionClosedevent carrying a differentsessionIdorchannelId. - Error responses:
HubException("Invalid channelId.")whenchannelIdis not a valid UUID.HubException("Not seated in this voice room.")when the caller has no seat inchannelId(including if the seat ended while the session was being created).HubException("Media server is unavailable.")whenstellarr-mediais unreachable, times out, or is undergoing a startup/event-loss reset.
Clients call OpenMediaSession after every JoinVoice (initial join, moderator move, hub reconnect, or session recovery) and create a fresh RTCPeerConnection for each session.
MediaSignal envelope
{
"protocolVersion": 1,
"channelId": "uuid",
"sessionId": "opaque",
"kind": "offer | answer | candidate | subscriptions | tracks",
"payload": "JSON string"
}| Kind | Direction | Payload schema |
|---|---|---|
offer | Browser → Media | { "type": "offer", "sdp": "…" } |
answer | Media → Browser | { "type": "answer", "sdp": "…" } |
offer | Media → Browser | { "type": "offer", "sdp": "…", "negotiationId": 7, "tracks": [Track] } |
answer | Browser → Media | { "type": "answer", "sdp": "…", "negotiationId": 7 } |
candidate | Browser → Media | RTCIceCandidateInit object, or null (end-of-candidates) |
subscriptions | Browser → Media | { "mids": ["receiving-mid", "…"] }, every receiving section to forward |
tracks | Media → Browser | { "tracks": [Track] } |
Each Track entry in the directory has the shape:
{ "mid": "fAk", "userId": "uuid", "kind": "audio | video", "streamId": "…", "heldBack": false }heldBack is true for a picture this receiver asks for that its downlink has no room for now: nothing of it is sent until it is false again (see Downlink adaptation). It is always present, and false for every sound and for every section the receiver does not ask for. A change of it sends a new tracks directory.
- Validation:
AppHubverifiesprotocolVersion == 1,kind(offer,answer,candidate, orsubscriptionsfrom browser), seat ownership,sessionIdownership, payload UTF-8 byte length ≤ 128 KiB, and payload schema. Invalid signals throwHubException("Invalid media signal.")(orHubException("Invalid ChannelId.")). - Control API forwarding:
409 stale-negotiationon a stale answer returns normally (stellarr-mediadiscards stale answers by design).422or413throwsHubException("Invalid media signal.").404 unknown-sessionreturns normally and triggersMediaSessionClosedwithreason: "media-restarted".- Other failures throw
HubException("Media server is unavailable.").
- Server-to-browser events:
MediaSignalcarries onlyoffer,answer, andtracks.stellarr-mediaincludes all ICE host candidates directly in its SDP and never trickles candidates. - Every
trackslist contains the complete track directory for the session, never a partial diff.
Receive subscriptions
subscriptions replaces the complete ordered list of receiving SDP mids that stellarr-media forwards to a session.
- Default & empty state: New sessions receive nothing until they send a list; sending
mids: []pauses all forwarding. - Priority order: Order expresses receiver priority (most important first) and determines which video tracks survive downlink adaptation. Reordering the same
mids counts as a new list. - Unsubscribed & future
mids: Unlisted sections remain negotiated in SDP and present in the track directory without carrying RTP packets (including newly negotiated sections until listed). Unknown or not-yet-negotiatedmids are harmlessly retained on that session alone, allowing the browser to pre-subscribe before answering a server offer. - Bounds & atomicity: Lists accept up to
4,096uniquemids (1–16printable ASCII characters, no spaces). Invalid lists are rejected whole without altering the active list. - No SDP renegotiation: Updating subscriptions toggles packet forwarding only. Transceivers,
mids, and the track directory stay unchanged. - Seamless resume: Resuming a paused track continues RTP sequence numbers contiguously (keeping publisher timestamps) and triggers a rate-limited PLI keyframe request for video. Receiver PLIs for unsubscribed sections are ignored.
- Client subscription policy: The browser subscribes in priority order (microphones, watched screen video and screen audio, then cameras in directory order) via
VoiceClient.setReceivePreferences({ screen, cameras }).- Updates precede the matching
answerin the serialized SignalR outbox and throttle to at most once every250 ms. - Until a publisher's
statesignal arrives, video streams default to screen-share classification. Newcomers receive occupancy/statebefore the first SFU offer, and classifications survive session replacements.
- Updates precede the matching
- Whole-track forwarding: Forwarded tracks carry the publisher's encoded stream as-is without per-receiver simulcast or SVC layer selection.
Negotiation rules
- Browser offers (publishing): The browser sends an SDP offer whenever its published tracks change (initial join, camera toggle, screen-share toggle). The initial offer after
OpenMediaSessionmust contain at least one m-line; a receive-only client offers arecvonlyaudio transceiver (answeredinactive). - Server offers (forwarding):
stellarr-mediasends an offer whenever forwarded tracks for the session change, but only after answering the browser's first offer. - Ordering: Signals from
stellarr-mediaare delivered in sequence order. The browser serializes its outgoingSendMediaSignalcalls, awaiting each hub response before sending the next. - Glare: The browser is impolite and drops any incoming media-server offer while its own offer is in flight.
stellarr-mediais polite: if a browser offer arrives while a server offer is pending, it rolls back the server offer, answers the browser's offer, and issues a new server offer with an incrementednegotiationId. - Stale answers and timeouts: Each server offer carries a monotonically increasing
negotiationId(starting at1), which the browser echoes in itsanswer. Answers with a non-matchingnegotiationIdare rejected with409 stale-negotiation. If a server offer receives no answer or competing browser offer within 10 s, it is rolled back and re-offered; after 3 consecutive unanswered offers, the session is closed witherror. - Immediate client recovery: If the browser fails to apply a remote SDP description or
SendMediaSignalis rejected by the hub, the client immediately replaces the media session rather than waiting for server timeouts.
IMPORTANT
Published tracks must be added on dedicated transceivers via addTransceiver(track, { direction: "sendonly", streams: [stream] }). Do not use addTrack: browsers may attach addTrack to an existing server-created transceiver, which stellarr-media never accepts incoming media on (answering sendonly or inactive).
Track directory
Because all remote media arrives over a single RTCPeerConnection, the client attributes incoming tracks using the server-provided directory:
mid: Matches the receiving transceiver's SDPa=midvalue, assigned bystellarr-media.userId: Lowercase UUID of the publishing user, bound from the authenticated seat.streamId: Stream identifier declared by the publisher (""if none), matched againstscreenStreamIdandcameraStreamIdin the publisher'sVoiceSignal(kind: "state") to distinguish microphone, camera, and screen tracks.- Shared microphone and camera stream: A publisher places its microphone and camera tracks into a single
MediaStream(onemsid) per call and advertises that stream ID ascameraStreamIdwhile the camera is active.stellarr-mediapreserves the publisher'smsidin forwarded offers so receiving browsers keep voice and camera synchronized. Screen shares use a separateMediaStream. - Distinguishing microphone vs. screen audio: On the receiving side, an incoming audio track is treated as the publisher's microphone if its stream is or was announced as
cameraStreamIdor if the audio track was registered on that stream before any video track. It is treated as screen-share audio if its stream matchesscreenStreamIdor if a video track was registered on that stream first. Because the track directory lists a screen share's video track before its audio track, receivers classify screen audio accurately even before the publisher'sstatesignal arrives. - Holding unattributed tracks: Tracks whose
midis not yet in the directory, or whoseuserIdis not in the currentVoiceParticipantChangedoccupancy snapshot, remain muted/unplayed until both include them. - In-place track swaps: When a publisher switches capture devices and updates its stream ID without adding a new transceiver,
stellarr-mediaemits atrackssignal without renegotiating SDP.
MediaSessionClosed
{ "channelId": "uuid", "sessionId": "opaque", "reason": "media-restarted | transport-timeout | error" }Sent only when the media server closes a session while the user's voice seat is still active:
| Reason | Cause |
|---|---|
media-restarted | stellarr-media restarted, the API reset it after an event-log gap, or a signal returned 404 unknown-session |
transport-timeout | ICE + DTLS + SRTP failed to connect within 30 s, or remained disconnected for 30 s |
error | Protocol or resource limit exceeded (e.g. 3 unanswered offers or SDP size limit) |
Sessions closed because the user left the seat or opened a replacement session do not emit MediaSessionClosed.
Seat and session lifecycle
A media session is bound to an active voice seat in PresenceTracker. AppHub and moderation endpoints close the media session whenever a seat changes:
| Trigger | Source |
|---|---|
| User leaves voice | LeaveVoice |
| SignalR connection disconnects | OnDisconnectedAsync |
| Newer browser tab takes the seat | JoinVoice (VoiceSessionReplaced) |
| User switches voice rooms | JoinVoice (from a previous room) |
| Direct call declined or user blocked | DeclineDirectCall, SocialEndpoints |
| Moderator kicks or moves user in voice | VoiceModerationEndpoints |
| Moderator kicks or bans user from server | ModerationEndpoints |
PresenceTracker detaches the session immediately in memory and enqueues a DELETE /v1/sessions/{sessionId} job in MediaSessionCloser (which retries every 2 s up to a bounded queue of 4,096 pending deletes). Calling JoinVoice again for the room the connection already occupies is a no-op and preserves the existing session.
Client state and recovery
VoiceState mapping
| State / Field | Condition |
|---|---|
peerCount | Number of other participants seated in the room |
connectedPeerCount | Number of seated participants whose microphone inbound-rtp packet counter is advancing (or who have an active transceiver while muted) |
transport.media = connecting | Peer connection is not yet connected, or outgoing audio RTP packets have not yet advanced |
transport.media = ready | Peer connection is connected, outgoing audio RTP is verified, and peerCount === 0 |
transport.media = connected | Peer connection is connected, and every other participant's microphone either arrives or is still within its arrival grace, with at least one arriving |
transport.media = degraded | A microphone is missing past its arrival grace, connection is disconnected/failed, outgoing audio is unverified after 3 stats samples (voiceClient.mediaServerStalled), or session replacement is in progress |
transport.media = failed | Automatic session replacement attempts exhausted (voiceClient.mediaServerLost) |
Session recovery
- If the peer connection stays
disconnectedfor more than 10 s, transitions tofailed/closed, receivesMediaSessionClosed, fails SDP application, or failsOpenMediaSession/SendMediaSignal, the client closes theRTCPeerConnectionand opens a replacement media session while keeping local microphone, camera, and screen tracks alive. - The client performs up to 3 automatic replacement attempts with backoff delays of
2 s,4 s, and8 s. Once outgoing audio RTP is verified (or on a freshJoinVoice), the retry counter resets. If all 3 attempts fail,transport.mediaentersfailed(voiceClient.mediaServerLost). - Clicking Reconnect in the call banner repairs the session in place: it refreshes ICE credentials, calls
JoinVoicefor the current room (keeping the seat without broadcasting a leave/join to other participants), and opens a new media session with a reset retry budget.
Proving media quickly
- Transport health is verified from cumulative RTP counters (
getStats), sampled on a 3 s interval. When the connection first reachesconnectedor a new participant joins, the client runs rapid initial checks at250 ms,500 ms,1 s, and2 suntil RTP flow is confirmed, then resumes the normal 3 s interval. - A newly joined participant's microphone is treated as pending (not missing) for a 3 s grace window starting from when the connection came up or when the participant joined, whichever is later.
- Each remote microphone transceiver is re-evaluated at most once every 500 ms; samples taken less than 500 ms apart keep the previous status so DTX silence packets (sent every 400 ms) are not mistaken for a stalled stream.
Control API (127.0.0.1:5200)
AppHub is the only client of the HTTP/1.1 JSON control API:
- Every endpoint except
GET /v1/healthrequiresAuthorization: Bearer <secret>(unless bound to loopback with an empty secret). Invalid or missing credentials return401. - Error responses have the shape
{ "error": "<code>", "detail": "<text>" }. sessionIdandepochare 32-character lowercase hex strings;roomIdanduserIdare lowercase UUIDs.
| Endpoint | Success response | Error statuses |
|---|---|---|
GET /v1/health | 200 { "status": "ok", "version": "…", "epoch": "…", "rooms": 0, "sessions": 0 } | None |
POST /v1/reset | 200 { "epoch": "…", "seq": 0 } | None |
POST /v1/sessions ({ "roomId", "userId" }) | 201 { "sessionId": "…", "epoch": "…" } | 422 invalid-request |
DELETE /v1/sessions/{sessionId} | 204 (idempotent for unknown sessions) | None |
POST /v1/sessions/{sessionId}/offer ({ "sdp" }) | 204 | 404 unknown-session, 422 invalid-sdp, 422 limit-exceeded |
POST /v1/sessions/{sessionId}/answer ({ "sdp", "negotiationId" }) | 204 | 404 unknown-session, 409 stale-negotiation, 422 invalid-sdp |
POST /v1/sessions/{sessionId}/candidate ({ "candidate" }) | 204 | 404 unknown-session, 422 invalid-candidate |
POST /v1/sessions/{sessionId}/subscriptions ({ "mids": [...] }) | 204 | 404 unknown-session, 422 invalid-request |
GET /v1/events?epoch=…&after=…&waitMs=… | 200 { "epoch": "…", "reset": false, "events": [Event] } | 422 invalid-request |
GET /v1/stats | 200 { "epoch": "…", "rooms": [...] } | None |
Additional status codes: 413 payload-too-large (request body > 256 KiB), 404 not-found, 405 method-not-allowed, 503 unavailable.
Event long-polling (GET /v1/events)
Returns immediately when events with seq > after exist, or waits up to waitMs (max 30000; the API polls with waitMs=25000 and a 30 s HTTP timeout). Returns up to 256 events per response:
{ "seq": 41, "type": "signal", "sessionId": "…", "kind": "answer | offer | tracks", "payload": { } }
{ "seq": 42, "type": "closed", "sessionId": "…", "reason": "transport-timeout | error" }epochidentifies thestellarr-mediaprocess instance. If the requestedepochdoes not match the running epoch, or ifafterfalls outside the 4,096-event ring buffer,stellarr-mediaresponds immediately with{ "epoch": "<current>", "reset": true, "events": [] }.- On
reset: true, the API closes all tracked sessions from the stale epoch (emittingMediaSessionClosedwithmedia-restarted), callsPOST /v1/resetif the epoch was unchanged but the ring buffer overflowed, and resumes polling fromafter=0.
Diagnostics (GET /v1/stats)
{
"epoch": "…",
"rooms": [
{
"roomId": "uuid",
"sessions": [
{
"sessionId": "…",
"userId": "uuid",
"state": "new | connecting | connected | disconnected",
"ageMs": 0,
"published": 2,
"forwarded": 6,
"ingress": { "packets": 0, "bytes": 0 },
"egress": { "packets": 0, "bytes": 0 },
"downlink": {
"estimateBps": 431000,
"rawEstimateBps": 512000,
"smoothedEstimateBps": 431000,
"measured": true,
"forwardedBps": 281000,
"desiredBps": 531000,
"paddingBps": 0,
"heldBack": [{ "mid": "pmQ", "userId": "uuid", "costBps": 250000 }],
"holds": 2,
"resumes": 1
}
}
]
}
]
}ingress and egress count media payload packets and bytes (excluding RTP headers, RTCP, and RTX retransmissions).
downlink is the session's downlink adaptation, in bits per second of RTP payload: estimateBps is the estimate the allocation uses (the lower of str0m's latest raw estimate and its three-second smoothing, or the initial guess while measured is false), forwardedBps what is sent, desiredBps what the estimator probes toward, paddingBps the rate padding keeps up toward the first held picture while a trial runs, heldBack every picture held back with its publisher and its current cost, and holds and resumes how often a picture was held back and came back since the session began. Every change of what is held back is also logged at debug with the estimate, what is forwarded and what is desired.
Media plane behavior
Transport
- Single UDP socket (
0.0.0.0:49000); incoming packets are demultiplexed by remote socket address (and by STUN username fragment on the initial connectivity check). - Each session accepts connectivity checks from at most 64 distinct remote addresses over its lifetime.
- ICE-lite:
stellarr-mediaresponds to STUN checks and acts as DTLS server. - Advertised host candidates (IPv4 only):
STELLARR_MEDIA_PUBLIC_IP:STELLARR_MEDIA_PUBLIC_PORT(when set) followed by the primary local IPv4 address on the bound port (used for internalcoturnrelay).
Forwarding
- Every session in a
roomIdnegotiates the tracks published by the other sessions in that room, never its own, and is forwarded those its receive subscriptions ask for. - Per connection,
stellarr-mediarewrites SSRC, payload type, RTP header extension IDs, and sequence numbers/timestamps while leaving media payloads untouched after SRTP decryption and re-encryption. - Supported codecs: Opus, VP9, VP8, H.264, AV1. Publisher codec order is preserved, and publisher Opus
a=fmtpparameters are echoed back so the browser configures its encoder according to the selected profile. - Audio level RTP header extensions are forwarded.
- NACK, RTX, transport-wide congestion control (TWCC), and keyframe requests (PLI/FIR, rate-limited to once per second per track) are handled per leg. The TWCC feedback of each receiving browser drives the media server's estimate of that receiver's downlink.
Downlink adaptation
Each receiving session runs independent GoogCC bandwidth estimation (str0m) from its own TWCC feedback. Congested receivers keep voice audio flowing while holding back excess video, without affecting the publisher or other participants. Rates below count RTP payload bits per second (smaller packets such as voice carry higher IP/UDP wire overhead).
- Bandwidth estimate: Starts at
1 Mbit/sand samplesmin(rawEstimate, smoothed3sEstimate)every200 ms, so congestion drops register immediately while increases require sustained headroom. Until feedback moves the estimate off1 Mbit/sand settles for1 s, video is neither held back nor paced (preventing initial keyframes from queuing behind an unmeasured initial guess). Once settled, unaffordable video is shed within2 s(or300 mson a steep drop). - Track cost: Measured per published track as trailing payload bitrate over
2 s(≥ 0.5 sfor new tracks). - Allocation & priority blocking: All subscribed audio is always forwarded. Subscribed video tracks are evaluated in
subscriptionsorder against remaining headroom:- A video track that fits is forwarded; one that does not is marked
heldBack: true. - If a held-back video is within reach (
cost ≤ 1.5× estimate), lower-priority videos behind it are also held back so lesser cameras cannot starve a higher-priority share waiting to recover. If it is out of reach (cost > 1.5× estimate), lower-priority videos that fit can still forward. - Allocation re-runs on estimate/subscription/directory updates and every
500 mswhile video is subscribed whenever a track cost shifts by≥ 20%(and≥ 8 kbit/s) or a hysteresis timer is active.
- A video track that fits is forwarded; one that does not is marked
- Holding back: Held-back video behaves identically to an unsubscribed track (contiguous sequence numbers on resume, rate-limited PLI on return, receiver PLIs ignored) and sets
heldBack: truein thetracksdirectory. - Hysteresis:
- Hold: Triggered once required rate exceeds
1.1×smoothed estimate for2 s, or after300 mswhen raw estimate drops below2/3of required rate. - Resume: Triggered once required rate stays within
85%of estimate for4 s. Re-holding within30 sdoubles the recovery wait up to64 s; holding steady for30 sresets the penalty. - Unproven tracks: Newly subscribed tracks start immediately if they fit; a track held back from the start only activates after a padding trial holds the required estimate for
1 s.
- Hold: Triggered once required rate exceeds
- Probing & padding:
- Target probe rate is
forwardedBps + firstHeldCost(capped at2×bystr0m), orforwardedBpswhen nothing is held back. - Held tracks within reach (
≤ 1.5×estimate) run6 spadding trials (suppressed automatically on congestion) separated by15 s,30 s, and60 srests (ending early if the estimate rises by25%). During a trial and for5 safterward, only a deep raw-estimate drop (< 2/3) can hold back active video. Out-of-reach tracks receive no padding. - If any video is held back, no padding trial is active, and the estimate stagnates for
5 s, the estimator resets at its current rate to clear loss-limited state and emit fresh probes (repeating every10 s, doubling up to2 min).
- Target probe rate is
- Audio-only fallback: When even subscribed audio exceeds the estimate, all audio continues forwarding, all video and video-probing padding stop, and only
str0m's50 kbit/sminimum padding floor applies when send rate is below it. - Pacing & isolation: Active video paces at
1.1×estimate while audio remains unpaced ahead of video queues. Receiver feedback and subscriptions affect only that session, and withdrawn transceivers stop receiving padding once the browser confirms them inactive.
Resource limits
| Limit | Value | Behavior when exceeded |
|---|---|---|
| SDP length | 128 KiB | 422 invalid-sdp on browser SDP; session closed with error if server SDP exceeds limit |
| Published tracks per session | 8 | 422 limit-exceeded |
| Control API request body | 256 KiB | 413 payload-too-large |
| Usable trickled ICE candidates per session | 64 | Subsequent candidates return 204 and are ignored |
| Remote peer addresses per session | 64 | Checks from additional addresses are dropped |
| Initial connection timeout (ICE + DTLS + SRTP) | 30 s | Closed with transport-timeout |
| Disconnected timeout | 30 s | Closed with transport-timeout |
| Consecutive unanswered server offers | 3 | Closed with error |
| Mids in one receive subscription list | 4,096 | 422 invalid-request; the previous list stays in force |
| Return of a held-back picture | after 4 s of headroom, doubling to 64 s after each return that lasts under 30 s; one that never had room, after 1 s of padding toward it that the estimate holds | The picture stays held back meanwhile |
| Padding toward a held-back picture | 6 s trials, rests of 15, 30, then 60 s | Only while the picture needs at most 1.5 times the estimate |
| Fresh looks of a still estimate | after 5 s, then every 10 s doubling to 2 min | Only while a picture is held back and no padding trial runs |
Current limitations
stellarr-media does not currently implement:
- Layer and simulcast selection per receiver: A receiver is sent a picture whole, at the publisher's quality, or not at all; nothing drops VP9 temporal layers or picks a simulcast encoding for a slow downlink, and sounds are always sent at their publisher's rate.
- SDP m-line recycling: Inactive m-lines are not reused within a session. A long session with many track toggles eventually reaches the 128 KiB SDP limit and automatically reconnects with a fresh session.
- Active-speaker filtering: Receive subscriptions and the downlink allocation select whole tracks in the order the browser gives; nothing follows who is speaking.
- Session persistence across hub reconnects or ICE restarts: The client opens a new session instead.
- IPv6 or direct ICE-TCP: The media socket uses IPv4 UDP only; clients restricted to TCP connect through
coturn.
WARNING
Call media is encrypted in transit between each browser and stellarr-media (DTLS-SRTP), not end-to-end encrypted between browsers. Because stellarr-media terminates SRTP on each leg to forward packets, audio and video are decrypted in process memory on the host running the container.
Process configuration
stellarr-media environment variables
| Variable | Default | Description |
|---|---|---|
STELLARR_MEDIA_BIND | 0.0.0.0:49000 | UDP media bind address |
STELLARR_MEDIA_PUBLIC_IP | empty | Public IPv4 address advertised in ICE host candidates |
STELLARR_MEDIA_PUBLIC_PORT | port of STELLARR_MEDIA_BIND | Public UDP port advertised with STELLARR_MEDIA_PUBLIC_IP |
STELLARR_MEDIA_ADVERTISE | empty | Comma-separated ip:port list overriding derived host candidates |
STELLARR_MEDIA_CONTROL_BIND | 127.0.0.1:5200 | HTTP control API bind address |
STELLARR_MEDIA_CONTROL_SECRET | empty | Bearer token required by the control API (required when not bound to loopback) |
STELLARR_MEDIA_LOG | info | tracing log filter (e.g. info,stellarr_media=debug) |
ASP.NET Core API settings
| Setting | Default | Description |
|---|---|---|
Rtc:MediaControlUrl | http://127.0.0.1:5200 | Base URL of the stellarr-media control API |
Rtc:MediaControlSecret | empty | Shared bearer secret |
Rtc:MediaPort | 49000 | Public UDP port advertised in GET /api/bootstrap (1–65535) |