Hubfly spaceDocs
Console

Playlists and schedules

A playlist plays videos from Hubfly space Storage or public https URLs, once or on a loop. A schedule runs control actions at a set time, once or repeating: switch a channel to a live show, start a restream, start recording, then stop it all again. Together they run a 24/7 channel. Both live under Schedules & playlists in the Dashboard.

Link a Storage bucket

A storage link gives the stream server access to one bucket of a Hubfly space Storage project. Creating one needs stream:admin on the stream server and storage:admin on the Storage project. A server can have up to 10.

ModeUsed for
readPlaylists
writeRecordings and clips
read_writeBoth

Link a bucket under Recordings → Storage buckets, or with the API (POST …/stream/storage-links/create) or the CLI:

bash
echo '{"storageProjectId": "<storage project id>", "bucket": "acme-videos", "mode": "read_write"}' \
  | hubfly stream storage-links create acme-tv --file -
hubfly stream storage-links assets acme-tv ssl_vod00001   # videos in the bucket, newest first

Listing a bucket's videos also needs media:read on the Storage project. Moving files between the stream server and Storage is free.

Playlists

  • Up to 50 playlists per server, each with up to 500 items.
  • loop starts again after the last item; shuffle plays the items in random order.
  • A channel plays a playlist as its source (--source playlist:spl_lofi0001), and a mixer can use one as a source.
  • The playlist.play control op (channel, playlist, item?) plays a playlist on a channel now, and playlist.next (channel) skips to the next item. Each new item sends a playlist.item event with its title.

Playlist items

An item is one of three things. Each can also have inMs and outMs to play only part of it (outMs: null plays to the end) and a title.

ItemFieldsNotes
A Storage videoassetIdThe Dashboard resolves it to the video's HLS rendition. The video must be in a linked bucket with read access and have a ready HLS rendition: encode it in Storage first.
A Storage objectstorageLinkId, objectKeyAn object in a linked bucket. Keys ending in .m3u8 play as HLS; anything else as a file.
A URLurlA public https URL. Credentials in it are kept as a secret and never returned.
lofi.json
{
  "name": "Lofi",
  "loop": true,
  "shuffle": false,
  "encoding": "auto",
  "items": [
    {"assetId": "<storage asset id>", "title": "Track 1"},
    {"storageLinkId": "ssl_vod00001", "objectKey": "uploads/intro.mp4", "inMs": 0, "outMs": 30000, "title": "Intro"},
    {"url": "https://cdn.example.com/clip.mp4", "title": "Sponsor"}
  ]
}
bash
hubfly stream playlists create acme-tv --file lofi.json
hubfly stream channels create acme-tv Lofi --source playlist:spl_lofi0001

Before saving, the Dashboard checks that each link can read and that each object or video exists.

Playing without re-encoding

With encoding: "auto", HLS renditions from Storage whose codec, resolution and frame rate match play without encoding, so they cost no processing. Items that do not match, files that are not HLS, and every item with encoding: "reencode" are re-encoded. That bills the channel's source rendition as an encoded output: its bitrate or the floor for its height and frame rate (see processing floors).

Keep 24/7 playout free of processing

Upload your videos to Hubfly space Storage, encode them to HLS there, and add them by assetId with the same resolution and frame rate. For example, Storage videos looped 24/7 to YouTube at 4.5 Mbps send 1,478.25 GB a month: about $5.71 of bandwidth after the free 50 GB, with no processing and the speed inside the free 25 Mbps.

24/7 channels

A 24/7 channel is a channel whose source is a looping playlist, plus schedules that switch it to another playlist or a live mixer at set times and back:

  • Set the channel's source to the looping playlist.
  • Add schedules whose onStart runs channel.source (to a mixer or input) or playlist.play.
  • When a schedule ends and nothing else sets a source, the channel returns to the source in its configuration.

Add destinations with Start automatically to send the channel to platforms around the clock.

Schedules

The stream server runs schedules itself, so a show starts on time even if the Dashboard cannot be reached. A server can have up to 100 schedules.

FieldRule
timezoneAn IANA name, such as Africa/Kigali
startA local date and time in that zone, without an offset: 2026-11-02T18:00:00
rruleOptional. Without it, the schedule runs once at start.
durationMinutes1–10,080 (7 days). onEnd runs at start + duration.
onStart, onEnd1–20 control ops each. clip.create and input.disconnect are not allowed.
enabledA disabled schedule does not fire.
weekly.json
{
  "name": "Weekly show",
  "enabled": true,
  "timezone": "Africa/Kigali",
  "start": "2026-11-02T18:00:00",
  "rrule": "FREQ=WEEKLY;BYDAY=MO",
  "durationMinutes": 90,
  "onStart": [
    {"op": "channel.source", "channel": "sch_main0001", "source": {"type": "mixer", "ref": "smx_show0001"}},
    {"op": "destination.start", "destination": "sds_yt000001"},
    {"op": "recording.start", "channel": "sch_main0001"}
  ],
  "onEnd": [
    {"op": "destination.stop", "destination": "sds_yt000001"},
    {"op": "recording.stop", "channel": "sch_main0001"}
  ]
}
bash
hubfly stream schedules create acme-tv --file weekly.json
hubfly stream schedules list acme-tv

Reading a schedule (GET …/stream/schedules/:scheduleId) also returns upcoming: its next 10 start times in UTC.

Repeating schedules

rrule is a subset of the iCalendar repeat rule (RFC 5545). Anything outside it is refused with invalid_rrule.

PartValues
FREQDAILY, WEEKLY or MONTHLY (required)
INTERVAL1–52
BYDAYMO … SU, comma-separated. With MONTHLY, also an ordinal: 1MO (first Monday), -1FR (last Friday).
BYMONTHDAY1–31, or −1 for the last day
BYHOUR, BYMINUTE0–23 and 0–59. Without them, the hour and minute of start are used.
COUNT or UNTILAt most one: COUNT 1–1,000, or UNTIL as UTC YYYYMMDDTHHMMSSZ
text
FREQ=DAILY                                  every day at the start time
FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR            weekdays
FREQ=WEEKLY;INTERVAL=2;BYDAY=SA             every other Saturday
FREQ=MONTHLY;BYDAY=-1FR                     the last Friday of each month
FREQ=WEEKLY;BYDAY=SU;COUNT=10               the next 10 Sundays
FREQ=DAILY;UNTIL=20261231T235959Z           every day until the end of 2026

At most 1,000 occurrences are ever expanded.

Time zones and daylight saving

  • Occurrences are computed in local time in the schedule's timezone, so a show at 18:00 stays at 18:00 local time across daylight saving changes.
  • A local time that does not exist (clocks spring forward) moves forward by the gap. A local time that happens twice (clocks fall back) uses the first one.
  • Durations are elapsed time: a 90-minute show lasts 90 real minutes, even across a change.

How schedules fire

  • Each phase runs once. The server records a start or end phase before it runs its ops, so a restart never runs a phase twice.
  • Missed fires. After a restart or an outage, a phase less than 5 minutes late still runs (schedule.fired with the real time). Older phases are skipped with schedule.missed. An end phase is never skipped while its start ran and its effects are still active.
  • Overlaps. When two phases fire in the same second, they run in schedule id order; later ops win.
  • Edits. Changing a schedule recomputes its future occurrences. An occurrence that has started keeps its end time, unless you disable or delete the schedule: then its end ops run at once.
  • Failures. Ops run in order, and a failing op does not undo the earlier ones. A failure sends schedule.failed with the error.

Preview and runs

Check a rule before you save it. The preview returns up to 20 start times, or the errors:

bash
hubfly stream schedules preview acme-tv --start 2026-11-02T18:00:00 --duration 90 \
  --rrule "FREQ=WEEKLY;BYDAY=MO" --timezone Africa/Kigali
hubfly stream schedules runs acme-tv ssc_weekly01

The API equivalent is POST …/stream/schedules/preview with {timezone, start, rrule, durationMinutes}, which answers {starts, errors}.

Runs (GET …/stream/schedules/:scheduleId/runs) list every phase the server fired, newest first: its phase (start or end), status (ok, missed or failed), firedAt and error. The live status shows each schedule's next and last fire. Receive schedule.fired, schedule.missed and schedule.failed with webhooks.

See Playlists and schedules and Recordings and storage in the API reference.

Something unclear or out of date? Emailsupport@hubfly.spaceBack to top