Media overview

storage stores bytes and takes no position on what they are. This one does.

@pithy-sh/media handles images, video, audio and documents: direct-upload URLs to the right backend per type, a record of what was uploaded, and opt-in enrichment — AI alt text, transcription, text extraction — running as Workflows on your own AI binding.

The backend follows the type

An image is not a video, and pretending otherwise costs you either quality or money. So config picks the backend per media type and the package does the rest:

TypeTypically
ImageCloudflare Images, for variants and transformation
VideoCloudflare Stream, for adaptive playback
Audio, documentsR2, through storage’s object-store seam

Direct upload means the bytes go from the browser to Cloudflare, not through your Worker. The Worker mints a URL and records a row.

Enrichment is opt-in, and it runs on your bill

Three Workflows, each optional and each off unless you ask for it:

Alt text for images. Generated on your own Workers AI binding. Useful for accessibility, and useful for search.

Transcription for audio. The text lands in your own D1 and is queryable.

Text extraction for documents. Same.

The inference runs on your binding, which means it lands on your bill and your customers’ files never leave your infrastructure to be processed. That is the same principle as the rest of the kit, applied to the one place where it is easy to quietly use somebody else’s API instead.

What that text is for

Transcripts and extracted text are the obvious thing to embed. vector is the capability that turns them into semantic search — a spoken sentence in a video becoming a search result needs no glue code between the two.

Records live in D1, so transcriptions and extracted text can be searched with SQL and joined against your own tables. There used to be a kv record store. It could not group, sum or scope a read, so it was removed.

It presigns through storage, and inherits nothing else

Media does not reimplement object storage. It uses storage’s ObjectStore seam — against its own bucket and its own credential name — and inherits none of storage’s tables, routes, quotas or share links for doing so.

That separation matters if you compose both: a user’s uploaded document and a user’s uploaded avatar are different products with different lifecycles, and they do not share a quota by accident.

Every record knows whose it is

Each record carries its owner, the organization in force when it was written, and a visibility: private, organization or public. Private is the default. The project decides which levels exist with visibility.allowed, and ["private", "organization"] means nothing can ever be published.

A record the caller may not read is not found, never forbidden, so an id cannot be probed. A public record needs no session at all. Editing and deleting belong to the owner, and to a role holding media:manage in the record’s organization.

The pixels are private too. A non-public Images or Stream asset is uploaded to require signed URLs, and the Worker signs a short-lived one for a caller who may read it. A visibility that governed the row and not the bytes would be a claim, not a protection.

Duplicate detection stays inside the tenant. It looks within the organization in force, or the caller’s own records when none is. Do you have this file is not a question one tenant may ask about another.

It reports what was served

What an account holds is one question. What its users actually looked at is another, and Cloudflare already counts it. Media reads minutes of video watched from Stream and image requests from Images, per asset, in a window, and joins each one to the record it belongs to. Cloudflare’s datasets are account-wide, so media asks only about the assets this environment’s own database holds, and never reports an account total.

It is a management read, behind its own control-plane scope, media:delivery:read, and it calls Cloudflare with the application’s one runtime token. A type you store in R2 is named as unreported, and why, never shown as zero.

What it deliberately does not do

No editing. No cropping, no trimming, no filters, no watermarks. Cloudflare Images does variants and transformations at serve time, which covers most of what people mean by this.

No moderation. Whether an image should be on your platform is a policy question with a human at the end of it. The enrichment Workflows describe content; they do not judge it.

No live streaming. Stream handles video-on-demand here. Live is a different product with different economics.

No DRM. Signed, expiring playback URLs are what you get.

When you would reach for it

When your users upload something you intend to do something with: display an image at three sizes, play a video at whatever bitrate the connection allows, search what somebody said in a recording.

If you only need to hold files and hand them back — an attachment, an export, a document — storage alone is smaller, simpler and cheaper.

What it needs

It requires secrets: two credential secrets and two signing keys are read through the registry. One credential is media’s own, the account id and nothing else. The other is the R2 key pair belonging to storage’s object store. The signing keys sign delivery URLs for private images and video. Every call media makes to Cloudflare — an upload, a signing change, a delete, a delivery read — uses the application’s one runtime token, and no token of media’s own.

auth is optional and effectively required — an upload belongs to somebody, and without it only a public record can be read. organization is optional too, and scopes records to teams.

pithy add media writes bindings and touches no Cloudflare account. The bucket, the credentials, the signing keys and the enrichment host arrive with pithy media provision, which needs an R2 S3 key pair you make by hand and the runtime token pithy secrets provision mints.

ESC