Module

Media

Store, track, and enrich media on your own Cloudflare account. Images, video, audio, documents. Config picks the backend; the package does the rest.

@pithy-sh/media

terminal
pithy add media

What it is for

Media that knows what it is. Upload images, video, audio and documents; get back records you can query, with optional AI enrichment on your own Workers AI binding.

What it sits on

R2, Cloudflare Images, Stream, Workers AI and Workflows.

Config picks the backend per media type: images to R2 or Cloudflare Images, video to R2 or Stream, audio and documents always R2. Bytes never proxy through your Worker — the client uploads straight to Cloudflare.

Enrichment runs as a Workflow, so a slow model never blocks an upload.

  • R2
  • Images
  • Stream
  • Workers AI
  • Workflows

The honest bit

Choosing the backend is a decision you should make once, deliberately.

Cloudflare Images and Stream buy you a delivery pipeline — variants, adaptive bitrate, a player. R2 buys you the bytes and nothing else, more cheaply. This package makes the choice config rather than architecture, but it is still a choice, and moving later means moving files.

If you build it yourself

Four media types, four sets of rules.

An image pipeline is a project. A video pipeline is a department.

Direct upload without proxying

Bytes should never pass through your Worker. Minting the upload URL correctly for each backend is the price of that.

Backend per media type

Images to R2 or Cloudflare Images, video to R2 or Stream — a decision that changes the record model and cannot be swapped later without moving files.

Transcoding and variants

Sizes, formats, and the fact that the browser asking has opinions about all three.

Enrichment that cannot block an upload

Captioning, labeling and transcription are slow and fail; they belong in a Workflow, not a request.

Ownership down to the pixels

An owner, a team and a visibility on every record, and signed delivery URLs, because a private flag on the row means nothing if the image URL works for anyone.

Deduplication that stays inside the tenant

Content hashing that finds a file already uploaded, without letting one customer ask whether another holds it.

What was actually served

Minutes watched and images delivered, per asset, from Cloudflare's own analytics, joined to your records and to this environment alone. Read with the application's one Cloudflare token, never a second.

terminal
pithy add media

In the dashboard

Administer it from a browser, without building the screen.

What your media holds, in records and bytes per organization and per owner within one, and what your images and video were served, per asset over 7, 30 or 90 days. Where your Worker does not report a type, its own sentence, never a zero.

The dashboard is the admin interface for your own application: whatever this capability writes, your team can look up, check and act on from a browser. Reading is free, forever, with no time limit. Connect the project when you deploy.

Add it, and get on with the feature.

One command installs the package, wires its bindings into every environment your project declares, and runs its migrations.