pithy add media --with-prerequisites--with-prerequisites composes secrets, which media requires — two credential secrets are read through the registry.
Add auth too. An upload belongs to somebody, and without an identity composed every write is refused and only a public record can be read.
What lands in your repo
apps/<worker>/pithy.config.ts gains the registration:
media({
// Who may read a media record: `default` is the level an upload gets when it names none, ...
visibility: { default: "private", allowed: ["private", "organization", "public"] },
}),apps/<worker>/wrangler.jsonc gains two bindings it can write, in every environment stanza:
| Binding | Type | What it is |
|---|---|---|
DB | d1 | The media records — with their owners, organizations and visibility — and the transcriptions and extracted text |
MEDIA_BUCKET | r2 | Where audio and documents live |
Three Workflow bindings are not written here — MEDIA_IMAGE_TO_TEXT, MEDIA_AUDIO_TRANSCRIBE and the video one. They are optional, and wrangler requires both a name and a class_name on every entry with the deployed name being per project and environment. They arrive with provision.
Two migrations run, and a third when you extend the record. 0001_init creates the media record tables, pithy_media_assets and pithy_media_hashes. 0003_ownership adds each record’s owner, organization, visibility and signed delivery, and the indexes the per-owner and per-organization reads use; records that existed before it become private and system-owned. 0002_extend is the slot between them: it is generated from the schema you pass as extend, one column per field, and is not registered at all when you pass none.
visibility is the one decision to make now
| Level | Who reads the record, and learns it exists |
|---|---|
private (default) | The owner, acting for the organization the record was written under |
organization | Any member of the record’s organization, acting for it |
public | Anyone holding the id or the URL, signed in or not |
allowed is a set, not a mode. All three by default. Drop public from it and nothing can ever be published, even by mistake. A write naming a level outside it is refused, never coerced, and default must be one of them. Records always live in D1: the kv record store was removed, and a config that still names it is refused at boot.
The choice also changes what provision does. While some record could be private, it writes the Images and Stream signing keys a private file is delivered through, and it refuses an Images variant that serves unsigned.
Then provision
pithy media provision --r2-access-key-id "$R2_KEY" --r2-secret-access-key "$R2_SECRET"That creates the bucket, writes the two credential secrets and the two signing keys, and deploys the media worker that hosts the enrichment Workflows.
Two credentials, because there are two owners. One is media’s own, and holds the account id and nothing else. The other belongs to storage’s object store, which media presigns through and whose key pair media never sees.
No Images or Stream token is asked for. Media calls Cloudflare with the application’s one runtime token, which pithy secrets provision mints per environment, and the run refuses before it writes anything while an environment has none. The R2 pair is not minted: Cloudflare exposes no API for creating one. You make it by hand and hand it over — on the flags, or as R2_CREDENTIALS in the account config.
Each environment’s deploy needs the app DB id from that environment’s stanza and the environment’s secrets database, so pithy secrets provision has to have run. Both are refused rather than deployed around.
pithy media is the whole command surface, including what --storage deletes.
Turning enrichment on
Enrichment is off unless you ask for it, and it runs on your Workers AI binding — so the inference lands on your bill and your users’ files never leave your infrastructure to be processed.
Each of the three is independent. Turning on transcription does not turn on alt text, and neither costs anything until a file of that type is uploaded.
What to compose beside it
vector, if the extracted text is worth searching. Transcripts and document text are the obvious thing to embed, and a spoken sentence becoming a search result needs no glue code between the two.
storage, if your users also upload files you do not intend to process. The two do not share a bucket, a quota or a set of tables, which is what keeps an avatar and a data export from competing for the same allowance.
organization, if records belong to teams. Each record then carries the organization in force when it was written, and some role in your catalog has to hold media:manage, so an organization can clean up after somebody who left. A catalog where none does is refused at compose.
Check it worked
pithy doctor reports media under the Worker’s health. Before provision, the MEDIA_BUCKET binding reads as declared with no resource behind it — the correct state, not a fault.