Skip to content

SYSTEM Cited by 1 source

Cloudflare Streamline

Streamline is Cloudflare's open-source developer playground / reference architecture for building custom (bespoke) video pipelines on the Developer Platform. It demonstrates how to compose lower-level primitives — Containers (long-lived media processing), Durable Objects (orchestration + preview relay), and Workers (control signaling + monitoring) — around the managed Cloudflare Stream product to modify video (dynamic annotations, burned-in subtitles, overlays, filters) and immediately publish the result as a livestream or new hosted video (Source: sources/2026-10-02-cloudflare-streamline-custom-video-pipelines-with-cloudflare-stream-and-workers).

Architecture

A Streamline deployment has two components:

  • Media Engine — handles media I/O and processing, hosted in a Container. It is itself split into:
  • Controller — a control harness written in Go that implements an HTTP server, receives requests, and translates them into media-engine operations.
  • Processor — performs the actual media processing. The current implementation uses FFmpeg, treated as "an internal implementation detail rather than part of the user-facing API."
  • Application — a controlling app (full-stack browser app, agent, or embedded system) built on Workers that creates, configures, observes, and stops media sessions. Its Orchestrator is implemented by a Durable Object that coordinates the session, the Container lifecycle, and the preview relay.

The modular split is deliberate — "we've architected Streamline with modular components so that the media engine could be replaced with dedicated encoding products in the future."

Control plane / data plane shape

Streamline is a clean application of control-plane / data-plane separation at the media-pipeline tier: the Worker + Durable Object are the control plane (signaling, monitoring, Access verification, lifecycle, profile→secret resolution, preview relay) and the Container media engine is the data plane (moving RTMPS/HLS/WebSocket media bytes). The decisive property is request-independent session lifecycle: "Video streams can run for minutes or hours, so the media process needs a lifecycle independent of the request that started it." The controlling Worker can disconnect and reconnect while processing continues; "processing will continue even if the Worker disconnects."

Container lifecycle & session management

Cloudflare Containers auto-sleep after an idle interval — wrong for an in-flight pipeline. Streamline overrides the Container's onActivityExpired() callback: while a relay session is live it renews the activity timeout; once expired it destroy()s the container. A maximum session duration is also enforced so a session is always eventually closed and can't run indefinitely without external control — a TTL-bounded resource with activity-based renewal. While a session runs, the container instance is unavailable to other applications (singleton-per-session).

Session API

Streamline exports two packages over the low-level Go HTTP + DO interface:

  • @cloudflare/streamline/client — a high-level, session-based API.
  • @cloudflare/streamline/ (DO base class) — routes API requests, implements the preview relay server, and provides hooks for security + access policy. A remote deployment subclasses this DO for application-specific logic/storage; local mode uses a thin adapter that connects directly to the local Docker instance.

Client surface: createStreamline(), sessions.create(), sessions.resume(id), session.start(config), session.ingest(chunk) (webcam mode), session.annotation(png) (live overlay update), session.metrics(), session.stop().

Pipeline configuration

session.start(config) takes a JSON object { input, pipeline: [ops], output }. Supported operations (a fixed set, applied in a fixed engine-defined order regardless of array order):

Op Function
filter blur, saturation, brightness, flip, …
overlay overlay an image by URL or a binary PNG annotation (live-updatable)
subtitle burn in subtitles (incl. HLS closed captions)
encode output encode params (codec/preset/bitrate/resolution/fps/gop)
  • Inputs: rtmp/rtmps (from a Stream Live input), hls (a Stream video manifest/video.m3u8), webcam (app-ingested chunks).
  • Outputs: rtmp/rtmps (to a Stream Live input), websocket (fMP4 preview).

Preview relay

Preview output (output: { mode: 'websocket' }) uses WebSockets for low-latency delivery: the Container publishes fMP4 fragments over an outbound WebSocket to the Durable Object, which forwards them to a relay reachable at /relay/view over a client WebSocket. The client must connect before session.start() or the relay rejects the publisher. A production MediaSource player must queue fragments while SourceBuffer.updating is true — a concrete backpressure requirement at the playback edge.

Security model

  • Private owner deployment behind Workers Access integration: the Worker verifies the Access session and binds the active session to the verified principal; only one session runs at a time and a different principal cannot stop/replace it.
  • RTMPS keys as secrets: Stream Live Input keys live in Worker secrets or write-only DO storage, never returned by the settings API or placed in browser storage. The controlling app refers to inputs/outputs by a named profile; the Worker resolves the profile before contacting the container, so keys never reach the controlling application.
  • Two-credential preview auth: a Cloudflare Access service token (authenticates the container workload to the publisher endpoint, injected by the container's outbound Worker, never enters container memory) plus a random per-session capability (authorizes publishing only for the active relay). Rollout stages from a temporary path-specific Access Bypass to Service Auth after a successful smoke test.
  • The owner deployment's singleton model is explicitly not the security model for a public multi-user service; the public playground uses one container identity per user, one active session per user, and global admission control.

Limitations & roadmap

  • CPU-bound: "Streamline uses Container CPU for media processing, which introduces a bottleneck at higher qualities or frame-rates."
  • Forward work (not shipped): computer-vision pipelines, hardware-accelerated media processing, realtime next-gen protocols (WebRTC, MoQ), and native video encode/decode primitives in Workers.

Seen in

Last updated · 771 distilled / 2,233 read