Broadcast a library video as a live stream

A stream with the FILE protocol plays a video instead of taking an encoder. Four calls set it up: choose the library video with its playback window and loop, read the settings, and set or cancel a start at a given time. The broadcast itself starts and stops with the ordinary start and stop calls of the stream. The same steps are in the stream's settings in the dashboard.

What you need

• A FILE stream of your own. Create it in the dashboard, or with POST /streams and the protocol FILE: no source is needed at that point, you choose the library video in the next step. You may instead pass a fileSourceUrl, a public address the card plays until you choose a library video (see Streams).
• A video in your own library that has finished processing. A video that belongs to another account, or that is the source of another card, is refused.
• An API key with the streams:write permission for the settings, and streams:operate for the scheduled start, start and stop.

Choose the video

PUT /streams/:id/file-broadcast replaces the whole settings object of the card. videoId is required; a field left out takes its default.

curl -s -X PUT \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"videoId": "video_id", "loopEnabled": true, "startTime": 0, "endTime": null}' \
  https://api.dcast.pro/api/v1/streams/{streamId}/file-broadcast

The answer is the settings object, the same one every call on this page returns:

{
  "success": true,
  "data": {
    "streamId": "stream_id",
    "videoId": "video_id",
    "fileSourceUrl": null,
    "loopEnabled": true,
    "startTime": 0,
    "endTime": null,
    "scheduledStartAt": null,
    "ready": true,
    "isLive": false
  }
}

Loop: a 24/7 broadcast without recording

With loopEnabled: true the video repeats until you stop the broadcast. A looped broadcast is kept as a 24/7 broadcast without recording: a rolling live window, no recording and no video to watch afterwards, because every circle repeats a video you already hold.

This mode is taken while the stream is off air. On a stream that is on air the source cannot change (409 FILE_SOURCE_LOCKED_ON_AIR), but a loop switch is passed to the running broadcast, and loopOnAir.applied in the answer says whether it took it; false means the change applies from the next start.

# Response while the broadcast is on air (truncated)
{
  "success": true,
  "data": {
    "loopEnabled": false,
    "isLive": true,
    "loopOnAir": { "applied": true }
  }
}

Read the settings

GET /streams/:id/file-broadcast returns what the dashboard shows. ready is true once the card has a source, so Start will work; isLive is true while it is on air; scheduledStartAt is null when no start is scheduled. A card made with a fileSourceUrl shows that address in fileSourceUrl and has videoId null.

curl -s \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  https://api.dcast.pro/api/v1/streams/{streamId}/file-broadcast

Start and stop

Start the broadcast with POST /streams/:id/start and stop it with POST /streams/:id/stop. No encoder is needed: the platform plays the file.

The plan's limits are judged at start, exactly as in the dashboard: the number of broadcasts on air at once and the live-duration cap of the plan. A stream that has used its free session is refused.

curl -s -X POST \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  https://api.dcast.pro/api/v1/streams/{streamId}/start

Start at a set time

PUT /streams/:id/file-broadcast/schedule takes scheduledStartAt, an ISO 8601 date-time with a time zone, at most 5 minutes in the past. At that moment the platform presses Start for you, so the plan's limits are judged then; if Start is refused at that moment, the stream stays off air. A new call replaces the earlier time.

curl -s -X PUT \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"scheduledStartAt": "2026-12-01T18:00:00Z"}' \
  https://api.dcast.pro/api/v1/streams/{streamId}/file-broadcast/schedule

# Response (truncated)
{
  "success": true,
  "data": {
    "streamId": "stream_id",
    "videoId": "video_id",
    "scheduledStartAt": "2026-12-01T18:00:00.000Z",
    "ready": true,
    "isLive": false
  }
}

The stream needs its source first: without a library video set by PUT /streams/:id/file-broadcast the answer is 409 FILE_SOURCE_REQUIRED. A stream that is already on air answers 409 BROADCAST_ON_AIR.

DELETE /streams/:id/file-broadcast/schedule clears the time. Calling it when nothing is scheduled is not an error: the answer is 200 with cancelled: false.

curl -s -X DELETE \
  -H "Authorization: Bearer pk_YOUR_KEY_HERE" \
  https://api.dcast.pro/api/v1/streams/{streamId}/file-broadcast/schedule

# Response (truncated)
{
  "success": true,
  "data": {
    "streamId": "stream_id",
    "scheduledStartAt": null,
    "cancelled": true
  }
}

Errors

Every refusal carries error.code and error.message.

• 400 BAD_REQUEST: the stream is not a FILE stream, videoId is missing, or a number is not a valid playback window. error.field names the field.
• 400 UNSUPPORTED_FIELD: playbackSpeed, filePath or sourceUrl was sent. A file broadcast plays a library video at its original speed.
• 403 FILE_SOURCE_FORBIDDEN: the video is not yours, or it is the source of another card.
• 403 FREE_PLAN_CARD_SESSION_USED: the stream has already used its free session.
• 404 NOT_FOUND: there is no such stream in your account.
• 409 FILE_SOURCE_LOCKED_ON_AIR, FILE_SOURCE_REQUIRED and BROADCAST_ON_AIR, as described above; 409 FILE_SETTINGS_CHANGED: the card was changed or started while the settings were saved, so read it again and retry.

Step by step

The same flow in the dashboard, with common problems and their fixes, is in the help centre: Broadcast from a file: on a loop or on a schedule. Streams in general are described in Streams.