RelayrtcDocs
Get started
Documentation
Streaming

Restreaming

Monitor upstream sources, handle recovery and rotate source credentials.

On this page

After registering a source, use its status and session history to manage recovery. Source state is independent of the broadcast outputs that consume its program.

Follow the source lifecycle

HLS sources progress through created, probing, ready, connecting and live. A lost source may enter recovering; stopped and failed end that session. Only observed canonical media establishes a live source.

restreamSources.get(sourceId) returns the current session, recent health transitions, a safe lastError and observed usage. After a terminal failure, repair the input and start a new session. Avoid retry loops that ignore capacity or policy errors.

Configure recovery and limits

Sources default to a reconnect budget of three, four hours of duration and 2 GB of fetched bytes. The API permits zero to five reconnect retries and durations from one minute to 24 hours, bounded by the attached stream. Probes and retries count toward observed fetch usage.

The deployment admits four source jobs globally by default. Probes also consume capacity. Increasing STREAMING_MAX_SOURCE_JOBS changes admission; it does not add source-worker resources.

The fetcher bounds request time, redirects, manifest size, object size, discovered resources and concurrent requests. A source that exceeds a safety bound fails visibly. Do not bypass those checks by replacing the guarded worker binaries or disabling TLS verification.

Change credentials or configuration

Stop the source and wait for its active session to end before editing or probing it again. Updates require its current version. Its stream and protocol cannot be changed; register a replacement source instead.

Upstream URLs and authorization are encrypted using the deployment's destination encryption key. Update endpoint or authorization to rotate them; an empty authorization value removes that header. Preserve the encryption key across restarts and backups. Replacing it without re-encryption makes stored credentials unreadable.

Deleting a source stops ingest and dependent broadcasts, clears its saved authentication material, and preserves history and usage. It does not delete an already finalized recording.

Diagnose failures

CodeNext step
SOURCE_ADDRESS_REJECTEDCheck all hostnames, redirects, public DNS answers and permitted ports
SOURCE_BUSYWait for the active probe/session to stop before changing configuration
SOURCE_CAPACITYCheck active jobs and provisioned source-worker capacity
SOURCE_CONNECTION_TIMEOUTCheck that the push encoder connects with a valid credential
SOURCE_PROFILE_UNSUPPORTEDCheck codecs and supported HLS playlist features
SOURCE_BYTE_LIMITReview the source byte budget
SOURCE_FETCH_FAILEDCheck upstream availability, authentication and TLS
SOURCE_CANONICAL_FAILEDInspect source-worker health and the attached stream's readiness

Raw encoder diagnostics may contain upstream secrets and are intentionally excluded from public errors. Correlate source/session IDs with private operator logs instead of displaying those logs to viewers.

Events and usage

Subscribe to restream.probing, restream.source_connected, restream.source_lost, restream.recovering, restream.stopped and restream.failed. Verify signatures, deduplicate IDs and reload state after notifications.

Fetched bytes include probes, manifests, initialization data and retries. Processing seconds are observed process elapsed time, not CPU-seconds. Push traffic belongs to normal stream usage; registry monitoring does not create another copy of that traffic. Keep these measurements separate from destination egress.

See Node methods, React status and streaming self-hosting.