Scheduled broadcasts
Plan an event with explicit publisher and viewer access windows.
On this page
A schedule creates one broadcast and starts it at a UTC instant. Scheduling does not launch OBS, activate devices or publish RTC tracks. Prepare the publisher separately and allow enough staging time before the event.
Create a schedule
Call this helper with UTC timestamps chosen by an authorized event operator. End must follow start within 24 hours.
import { relay } from './relay.js'
export async function scheduleEvent(streamId: string, startsAt: string, endsAt: string) {
return relay.schedules.create({
broadcast: { streamId, name: 'Town hall', waitTimeoutSeconds: 120 },
timing: {
startsAt,
endsAt,
timeZone: 'UTC',
sourceWaitSeconds: 120,
catchUpSeconds: 300,
publisherEarlySeconds: 900,
viewerEarlySeconds: 900,
viewerAfterSeconds: 0,
notifyBeforeSeconds: null,
},
})
}REST accepts UTC timestamps ending in Z. timeZone is an IANA display zone, not permission to submit an ambiguous local timestamp. Convert local wall times on the backend; resolveScheduleLocalTime rejects nonexistent DST times and requires an explicit offset for repeated times.
The schedule snapshots the stream configuration, selected destinations and automatic recording policy. A later stream-version change prevents execution; create a replacement schedule for the new configuration.
Prepare publishers and viewers
For WHIP/RTMP, use schedules.createIngestCredentials(scheduleId). These credentials open at startsAt - publisherEarlySeconds and expire at event end. Editing, cancelling or completing the event revokes event credentials. For ROOM, issue room tokens through your application and enforce the event window there.
Use schedules.getPlayback(scheduleId) for countdown and state, and schedules.createPlaybackGrant(scheduleId) after viewer authorization. Schedule grants only authorize the live scheduled run and cannot outlast its end. A generic stream grant bypasses this event-specific audience flow and should remain an operator capability.
viewerAfterSeconds extends ended-event metadata access; it does not extend live media or grant recording access. Authorize recorded playback or DVR separately.
Follow execution
The scheduler runs in the API; it does not require an open browser tab or your own cron job. States progress through scheduled, starting, running, ending, then completed, missed, failed or cancelled.
catchUpSeconds bounds late admission after downtime. Once admitted, the source must become ready within sourceWaitSeconds and before event end. An absent publisher can make an event missed. The scheduler also rechecks the original creator's current authority and resource capacity; revoked access can prevent automatic start.
Read the schedule, its operation and associated broadcast when diagnosing failures. A successful command response is not confirmation that media is playing.
Edit, start now or cancel
Pending schedule updates, startNow and cancel require the current schedule version. Reload after conflicts. Start-now shifts the start/end while preserving duration. These changes can revoke earlier event credentials, so issue replacements when needed.
At event end the scheduler stops broadcast outputs. It preserves independently managed source sessions and participants' devices. Source duration limits include staging time; configure them to cover staging plus the event. Cancellation revokes event access immediately while worker cleanup completes asynchronously.
Reminders
Reminders use signed webhooks, not built-in email or SMS. Enable schedule notifications on the deployment, subscribe a webhook endpoint to schedule.reminder, then set notifyBeforeSeconds. Your application can deliver its own email after accepting the webhook.
Deduplicate webhook IDs and reload current state before acting on a reminder. Rescheduling invalidates obsolete reminders. See schedule REST contracts, Node methods and webhooks.