Hubfly spaceDocs
Console

Transcoding

Each channel has an encoding: passthrough, which sends the stream as it arrives, or a ladder of renditions that Hubfly space encodes so viewers on slow connections get a lower quality. Encoding is the only work billed as processing; passthrough costs none.

Passthrough or a ladder

ModeWhat viewers getProcessing
passthroughThe source as received, as the rendition named source. H.265 sources are passed through as they are.None
ladderThe renditions you define, encoded in H.264. With includeSource, also the original as source, so viewers on fast connections can pick it.Each rendition while the channel runs

The HLS multivariant playlist https://acme-tv.live.hubfly.app/hls/sch_main0001/index.m3u8 lists every rendition, and players switch between them as bandwidth changes. One rendition alone is at /hls/sch_main0001/720p/index.m3u8, and WebRTC can ask for one with ?rendition=720p.

In the Dashboard, open a channel under Channels and choose the encoding. The ladder presets fill in common renditions, all at 30 fps:

PresetRenditions (video / audio kbps)
1080p ABR1080p (6,000 / 160), 720p (3,000 / 128), 480p (1,400 / 96), 360p (800 / 64)
720p ABR720p, 480p and 360p at the same bitrates
Mobile480p and 360p

Renditions

FieldRule
name1–24 characters: lowercase letters, digits, _ and -, starting with a letter or digit. Unique in the channel, and not source.
codech264
width, heightEven numbers. Height at most 2160, and not larger than the mixer's canvas when a mixer feeds the channel.
fpsFrames per second of the rendition
videoBitrateKbps64–40,000
audioBitrateKbps32–320

A ladder needs at least one rendition or one audio output, and passthrough cannot list renditions. A document that breaks a rule is refused whole with 422 STREAM_INVALID, for example invalid_rendition, out_of_range or ladder_required, and the previous configuration keeps running.

Define a ladder

The same JSON works with PUT …/stream/channels/:channelId/update and with hubfly stream channels update --file, which fills in the current revision for you:

ladder.json
{
  "encoding": {
    "mode": "ladder",
    "includeSource": true,
    "renditions": [
      {"name": "720p", "codec": "h264", "width": 1280, "height": 720, "fps": 30,
       "videoBitrateKbps": 3000, "audioBitrateKbps": 128},
      {"name": "480p", "codec": "h264", "width": 854, "height": 480, "fps": 30,
       "videoBitrateKbps": 1400, "audioBitrateKbps": 96},
      {"name": "360p", "codec": "h264", "width": 640, "height": 360, "fps": 30,
       "videoBitrateKbps": 800, "audioBitrateKbps": 64}
    ],
    "audioOutputs": []
  }
}
bash
hubfly stream channels update acme-tv Main --file ladder.json
hubfly stream channels get acme-tv Main --json   # processingMbps: what the channel bills while it runs

Audio outputs

audioOutputs adds audio-only renditions to a channel: {"name": "aac", "codec": "aac", "bitrateKbps": 128}, with the codec aac, mp3 or opus. Each one bills 0.1 processing Mbps while it runs. A channel fed only by audio cannot have video renditions or WebRTC. For listener streams in MP3, AAC and Opus, see Internet radio.

The processing cap

Each server has a processing cap: the most encoded Mbps it may run at once, from 0 to 64 (8 by default). It protects you from a runaway bill. Outputs beyond the cap are not started and not billed. Set it when you create the server or later, live:

bash
hubfly stream create acme-tv --speed 100 --processing 16
hubfly stream speed acme-tv 100 --processing 24

When the configured outputs need more than the cap, the server starts them in this order and leaves the rest rejected:

  1. mixers;
  2. channel ladders, in channel order;
  3. audio outputs.

A rejected output shows Over processing cap in the Dashboard and sends a processing.rejected event with needed_mbps and available_mbps. It starts once you raise the cap or free capacity. The media node has its own processing capacity too; when it is full, outputs are admitted in the same order, first come first served. The live status (hubfly stream live acme-tv) shows the processing in use next to the cap.

What processing costs

Processing costs $0.004 per encoded Mbps-hour, after 20 free Mbps-hours a month shared by all your servers. Each encoded video output bills its configured video bitrate or the floor for its height and frame rate, whichever is higher:

Output height up to30 fps floor60 fps floor (above 30 fps)
Audio only0.1 Mbps0.1 Mbps
3600.60.6
4801.01.0
7202.03.0
10804.06.0
14408.012.0
216012.018.0
  • A video rendition's own audio track is included.
  • Passthrough, packaging, restream copies and slates cost nothing.
  • A mixer program bills 1.5 × its billed video Mbps. See studio and graphics.
  • A playlist that must be re-encoded bills like the channel's source rendition. See playlists.

For example, the 720p, 480p and 360p ladder above bills 3.0 + 1.4 + 0.8 = 5.2 Mbps, since each bitrate is above its floor. A two-hour show uses 10.4 Mbps-hours, inside the free 20. The same ladder running all month (730 hours) uses 3,796 Mbps-hours: 3,776 billable, about $15.10. See pricing and limits.

WebRTC and B-frames

WebRTC playback needs video without B-frames (H.264 without B-frames, VP8, VP9 or AV1). Many encoders use B-frames by default.

  • If the source has B-frames and the channel has a ladder, WebRTC plays the first rendition of the ladder instead, and saving the channel returns the warning bframes_need_transcode.
  • With no ladder, WebRTC answers 409 webrtc_unavailable and players fall back to LL-HLS.
  • WebRTC audio is Opus. An AAC or MP3 source gets one shared Opus conversion per channel while at least one WebRTC viewer watches, billed as an audio output (0.1 Mbps).

Turn B-frames off for sub-second playback

Set B-frames to 0 in your encoder (in ffmpeg, -bf 0). WebRTC then plays the source directly, with no ladder and no processing. See OBS and encoders.

Warnings and rejected outputs

Some problems do not block a save. The configuration is applied and the response lists warnings in sync.warnings:

WarningMeaning
bframes_need_transcodeWebRTC is on and the live source has B-frames. WebRTC uses the first ladder rendition, or is unavailable with no ladder.
processing_over_capThe configured encodes need more processing than the server's cap. The extra outputs stay rejected until you raise it.
rendition_upscaleA rendition is taller than the live source. It is skipped until the source is large enough.
graphics_html_unavailableA mixer uses an HTML graphic, which renders transparent. See graphics.

Rendition states in the live status are running, waiting (no source yet), error and rejected (no processing capacity).

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