# Building Custom Video Processing Pipelines with Cloudflare’s Developer Platform
Cloudflare Stream has long served as a go-to broadcasting platform for delivering video content with minimal overhead. However, there are scenarios where standard out-of-the-box functionality falls short — such as when developers need to render dynamic graphic overlays on a live broadcast, burn custom subtitles into a hosted video, or create entirely alternate versions of stored content in real time. For these use cases, a custom video processing pipeline is required.
A new developer tool called Streamline has been introduced to address this gap. It serves as a hands-on playground demonstrating how to construct bespoke video delivery systems entirely on Cloudflare’s Developer Platform. By leveraging Workers, Containers, and Durable Objects, Streamline shows developers how to manipulate incoming video streams and immediately publish the modified output — whether as a new livestream or a freshly hosted video asset.
## Why a Custom Pipeline Matters
Standard video platforms handle encoding, delivery, and playback efficiently, but they operate within fixed parameters. When a project demands runtime modifications — think dynamic branding overlays that change mid-broadcast, real-time subtitle generation from closed caption tracks, or applying visual filters to webcam feeds — the pipeline must be flexible and programmable.
Video streams can run continuously for minutes or even hours. This means the processing environment cannot be tied to a single HTTP request. Instead, it requires a durable, long-running runtime capable of executing compiled media code with predictable allocation of memory and CPU resources. The application should be able to launch a pipeline, feed it input data, monitor its progress, and shut it down cleanly — all without keeping a single network request open for the entire duration of the session.
## How Cloudflare’s Primitives Solve This
Cloudflare offers a set of building blocks that align naturally with the demands of media processing:
– **Containers** provide long-lived execution environments well-suited for sustained media workloads. Unlike short-lived functions, a Container can persist for the entire lifetime of a video processing session, running specialized compiled code without interruption.
– **Durable Objects** handle orchestration and session state. They act as the coordination layer, managing the lifecycle of media sessions and maintaining the connection between the controlling application and the processing backend.
– **Workers** serve as the control plane, handling signaling, monitoring, and user-facing API exposure. They can be disconnected and reconnected without affecting the ongoing media processing happening inside the Container.
## System Architecture
A Streamline deployment is composed of two primary layers: a **Media Engine** and a controlling **Application**.
### The Media Engine
The Media Engine is hosted inside a Container and is responsible for all media input, output, and transformation. It itself consists of two parts:
– A **Controller** written in Go that runs an HTTP server, accepts external commands, and translates them into operations the media engine can execute.
– A **Processor** that performs the actual frame-level manipulation. The current implementation uses FFmpeg under the hood, though this is an internal detail hidden from the user-facing API.
The Media Engine can pull RTMP streams from Cloudflare Stream Live inputs, consume HLS manifests and segments from hosted videos, accept direct video feeds such as webcam data, and publish processed output back to Stream Live inputs or deliver preview frames over WebSockets.
### The Application Layer
The application is built on Workers and can take many forms — a full-stack browser interface, an autonomous agent, or an embedded device. Its responsibilities include:
– Providing a user interface with client-side logic, identity management, and access control policies.
– An **Orchestrator**, implemented as a Durable Object, that coordinates session creation, manages the Container lifecycle, and routes preview video streams.
In a local development environment, the system simplifies significantly: the Container runs as a local Docker instance, no Durable Object is involved, there is a single user with no authorization overhead, and video preview connects directly to a WebSocket on localhost.
## Session Lifecycle and Management
When an authorized user or agent visits the Worker application, they can initiate a new processing session. If no Container is currently running for that configuration, one is automatically spun up. The system manages the Container’s lifecycle automatically, and once the pipeline is running, it continues processing even if the controlling application disconnects.
Cloudflare Containers have a built-in inactivity timeout that causes them to sleep after a period of no incoming requests. For media pipelines, this behavior must be overridden. The system does this by hooking into the activity expiry callback: if the session has a defined maximum duration and that duration has not elapsed, the activity timer is renewed; otherwise, the Container is safely destroyed. A maximum session duration is enforced to ensure pipelines do not run indefinitely in the absence of external control.
## The API: Controlling Video Processing
Streamline exposes two developer packages that abstract away the underlying complexity:
– `@cloudflare/streamline/client` provides a high-level, session-based API for interacting with processing pipelines.
– `@cloudflare/streamline/` exposes the Durable Object base class, which handles request routing, preview relay functionality, and security hooks.
With these packages, a developer can create a session, define a processing configuration, and start a pipeline with just a few lines of code. The same API supports resuming disconnected sessions, sending video chunks for webcam-mode input, updating overlay annotations dynamically, retrieving real-time session metrics, and cleanly stopping processing.
## Defining a Video Processing Pipeline
The core of Streamline is the pipeline configuration — a JSON object passed when starting a session that describes every transformation to apply. A pipeline specification includes three sections:
1. **Input**: Defines where the source video comes from — an RTMP broadcast from a Stream Live input, an HLS manifest from a hosted Cloudflare Stream video, or direct data from a webcam.
2. **Pipeline Operations**: An array of processing steps executed in a fixed order by the engine. Supported operations include applying visual filters (such as brightness adjustments or flips), overlaying PNG images with configurable positioning, burning in subtitles from closed caption tracks, and re-encoding the output with specific codec, bitrate, resolution, and frame rate settings.
3. **Output**: Determines where the processed video goes — published as an RTMP stream to a Stream Live input for broadcasting or recording, or delivered as a WebSocket feed for low-latency previewing in the browser.
### Example: Adding an Overlay to a Live Broadcast
A common use case is taking a live RTMP feed, placing a semi-transparent logo or graphic in a corner, and sending the result to a different Stream Live input for recording. The pipeline configuration for this specifies an RTMP input, an overlay operation referencing an image file, an encode operation to set compression parameters, and an RTMP output pointing to the destination.
### Example: Burning Subtitles from Hosted Video
Another powerful scenario involves ingesting a hosted video via its HLS manifest, automatically extracting embedded closed captions, rendering them as burned-in text on the video frames, and outputting the result via RTMP. This allows creators to produce alternate versions of existing content with custom subtitle styling — all without downloading or re-uploading source files.
## Sending Video Directly to the Pipeline
For testing and rapid prototyping, Streamline supports sending video data directly from the controlling application. This is especially useful when working with webcam feeds, factory camera systems, or multi-camera setups that need real-time compositing before being sent to a downstream destination. The `ingest()` method accepts binary video chunks, making it straightforward to forward MediaRecorder output from a browser or frame data from an embedded device.
## Dynamic Overlay Updates
One distinction of Streamline is the ability to update the overlay image mid-session. Using a separate API call, the controlling application can swap out the PNG used for an overlay on the fly. This opens the door to animated graphics generated from an HTML canvas, where each frame is captured and pushed to the pipeline as a new overlay image, creating the effect of dynamic, runtime-generated watermarks or interactive graphics.
## Previewing Video Over WebSocket
Streamline can deliver preview video back to the controlling application through a WebSocket connection. The Container publishes fMP4 media fragments to a Durable Object, which acts as a relay and forwards them to an output endpoint at `/relay/view`. The application connects a WebSocket to this URL, receives binary video data as it becomes available, and feeds it into a browser-based MediaSource player for real-time playback.
This preview path uses two separate credentials: a service token for authenticating the Container to the relay endpoint, and a per-session capability token that restricts publishing to only the active relay instance. This separation ensures that preview streams remain isolated and secure.
## Security by Design
Security is woven into Streamline’s architecture from the ground up. Access control is enforced through Cloudflare Workers’ built-in Access integration, meaning only verified identities can initiate or reclaim a session. Stream Live input and output keys are stored as secrets or write-only overrides in Durable Object storage — they are never returned through settings endpoints or exposed in browser-side code.
Session isolation ensures that only one active session can run per user at a time, and a different authenticated principal cannot terminate or hijack an existing session. These measures make the system suitable for deployment behind Cloudflare Access with per-user authentication, though the owner-facing deployment is intentionally kept private and is not designed as a public multi-tenant service.
## Getting Started
The Streamline system is fully open source and available on Cloudflare’s GitHub. Developers can clone the repositories and run the Container locally using Docker, or deploy it to their own Cloudflare account. An example Worker application with an Astro-powered web frontend showcases common workflows including overlays, subtitle injection, filters, and picture-in-picture compositing.
A publicly accessible playground is also available, allowing anyone to experiment with Streamline’s capabilities without setting up any infrastructure. This deployment includes its own Access configuration, one container identity per verified user, a single active session per user, global admission controls, concurrency limits, and media and session caps.
## Looking Ahead
Streamline represents the first iteration of what can be built by combining managed services like Cloudflare Stream with lower-level compute primitives. Current backends rely on Container CPU for media processing, which imposes practical limits at higher resolutions and frame rates. Future work from both Cloudflare and the developer community is expected to explore computer vision pipelines, hardware-accelerated encoding, next-generation streaming protocols such as WebRTC and MoQ, and eventually video codec primitives running natively inside Workers.
## Frequently Asked Questions
**Q: What is Streamline exactly?**
A: Streamline is an open-source developer playground and reference implementation that demonstrates how to build custom video processing pipelines on Cloudflare’s Developer Platform. It shows how to manipulate livestreams and hosted videos programmatically using Workers, Containers, and Durable Objects.
**Q: Can I use Streamline in production?**
A: The architecture and codebase are designed to be deployed to your own Cloudflare account. The open-source repositories include deployment guides, and the system is built with production considerations like session limits, resource caps, and access control. However, the public playground comes with its own usage boundaries for experimentation.
**Q: What video operations can I perform with Streamline?**
A: The current version supports visual filtering (brightness, blur, saturation, flips), image overlays with precise positioning, burning in subtitles from closed caption tracks, and re-encoding with configurable codec, bitrate, resolution, frame rate, and encoding preset parameters.
**Q: Does Streamline work with video uploads or only live streams?**
A: Both. You can process hosted videos by ingesting them via their HLS manifest URL for on-demand processing, and you can also work with live RTMP inputs and webcam feeds for real-time pipelines.
**Q: What happens if my application disconnects while a pipeline is running?**
A: The Container continues processing independently. Your application can reconnect at any time and resume control. The system also enforces a maximum session duration to ensure pipelines are eventually cleaned up even without external intervention.
**Q: Do I need to manage my own media servers or FFmpeg installations?**
A: No. The media engine runs inside a Cloudflare Container with FFmpeg pre-configured. Developers interact with the system through the high-level API packages rather than managing infrastructure directly.
**Q: Is there a limit on how long a pipeline can run?**
A: A maximum session duration is configurable, ensuring that pipelines are automatically stopped after a defined period. This prevents runaway processing and ensures fair resource usage across deployments.
**Q: What programming languages or frameworks are required?**
A: The core media engine is written in Go, but from the developer’s perspective, the control layer is JavaScript/TypeScript running in Workers. The example frontend uses Astro and standard browser APIs like MediaRecorder and WebSocket.
## Final Thoughts
Custom video processing has historically required substantial infrastructure investment — dedicated encoding servers, complex orchestration layers, and ongoing maintenance. Streamline dramatically lowers that barrier by showing how to build a fully functional, secure, and scalable video manipulation system using Cloudflare’s existing developer platform. Whether you need to add dynamic overlays to a live broadcast, generate subtitle-burned versions of archived content, or prototype real-time computer vision pipelines, the combination of Workers, Containers, and Durable Objects provides a foundation that is both powerful and accessible.
Explore the open-source repositories, try the public playground, and start experimenting with your own video processing workflows today.
Thank you for reading
