Node streaming methods
Typed stream management and retry-safe operations on an application backend.
On this page
Availability
Use a compatible API and SDK build; see installation for package availability. Management methods belong on your backend.
Import and client
Set RELAYRTC_API_URL and RELAYRTC_SECRET_KEY in your backend environment. Keep the secret key on the server.
import { RelayServer } from '@relayrtc/node'
const relay = new RelayServer({
apiUrl: process.env.RELAYRTC_API_URL!,
apiKey: process.env.RELAYRTC_SECRET_KEY!,
})Example
export async function startRoomExport(roomId: string, applicationCommandId: string) {
const stream = await relay.streams.create({
name: 'Town hall', source: { kind: 'room', roomId },
}, { idempotencyKey: applicationCommandId + ':create' })
const operation = await relay.streams.start(stream.id, {
idempotencyKey: applicationCommandId + ':start',
})
return { stream, operation }
}Methods
| Method | Result |
|---|---|
| streams.create(input, options?) | StreamResource |
streams.list({ cursor?, limit? }?, options?) | StreamPage: data, nextCursor |
| streams.get(id, options?) | StreamDetail: configuration and sessions |
streams.update(id, { version, ...changes }, options?) | StreamResource |
| streams.delete(id, options?) | StreamingOperation |
| streams.start(id, options?) | StreamingOperation, room source only |
| streams.stop(id, options?) | StreamingOperation |
| streams.listIngestCredentials(id, options?) | IngestCredentialList: data of safe summaries |
| streams.createIngestCredentials(id, input?, options?) | IngestCredential, secret returned explicitly |
| streams.rotateIngestCredentials(id, credentialId, input?, options?) | RotatedIngestCredential with handover status |
| streams.getPlayback(id, options?) | StreamPlayback |
| streams.createPlaybackGrant(id, input?, options?) | PlaybackGrant |
| streams.revokePlaybackGrants(id, options?) | { revoked: true } |
| streams.getUsage(id, options?) | StreamingUsage |
| streamingOperations.get(operationId, options?) | StreamingOperation |
All listed methods return promises. These method signatures and exported contracts require a matching Node SDK release; an older published package may not include them. Request options support AbortSignal, timeoutMs, retry:false and idempotencyKey. Create/start/stop/delete and ingest-credential issue/rotation generate a UUID idempotency key when omitted. Reuse an explicit application command ID when retrying the same command yourself. Configuration updates and live/DVR viewer-grant methods do not use that command mechanism. Mutations are not retried automatically. GET uses existing bounded transport retries.
Ingest credentials
CreateIngestCredentialInput accepts optional ttlSeconds only, from 60 to 86400, default 3600. Ingest credentials do not accept viewer mode or broadcastId options. Creation reveals the encoder secret. Rotation returns RotatedIngestCredential, which adds handover: { policy: 'disconnect-and-reconnect', status: 'ready' or 'pending', retryAfterSeconds: number }. Reconnect the publisher with the replacement credential after the indicated delay; rotation revokes the old credential.
streams.listIngestCredentials returns { data: IngestCredentialSummary[] }, at most 50 rows ordered newest first, without pagination. A summary contains id, expiresAt, revokedAt and createdAt. The history can include expired or revoked credentials, but never contains their secrets.
Playback grants and readiness
CreatePlaybackGrantInput accepts ttlSeconds (30 to 3600, default 300), optional mode: 'live' or 'dvr' (default live), and optional broadcastId. For DVR viewing, authorize the intended run and pass its broadcast ID. See DVR methods.
StreamPlayback contains sourceState and readiness alongside state. sourceState is the source lifecycle; viewer-facing state may report reconnecting while the source is live but playback is unavailable. StreamPlaybackReadiness has these fields:
| Field | Meaning |
|---|---|
| status | waiting, starting, ready, reconnecting, degraded, failed or ended. |
| publisherConnected | An eligible publisher/source connection is observed. |
| sourceProducing | A live leased source has positive program bitrate. |
| outputStarting | An active source is awaiting viewer-ready output. |
| viewerReady | Protected playback was observed ready for the current source generation. |
| code | Safe diagnostic code, or null. |
| checkedAt | ISO timestamp of the observation. |
Use viewerReady when displaying playback availability. A successful grant request or connected publisher does not establish ready media.
List pagination differs from RTC room lists: iterate page.data, then supply page.nextCursor until null. Do not assume nodes/pageInfo. Retirement/stop return durable operations, not completed RTC cleanup results. Poll until completed or failed. An operation failure includes errorCode.
StreamingOperation.sessionId is a string or null. broadcastId and outputId are optional and nullable: source-command responses can omit them, while operation reads return their nullable values. Do not assume every operation belongs to a broadcast or output.
Authenticate and authorize your own caller before returning participant tokens or viewer grants. Ordinary reads do not reveal stored secrets. Do not log credential/grant responses or raw playback URLs. REST reference documents scopes, limits, statuses and errors.