Architecture
One runtime, pluggable adapters, and a pipeline every file passes through.
Better Media is a server-side media pipeline framework. You configure it once — wiring storage, a database, and plugins — and get back a single media runtime your handlers call into. The framework owns the pipeline; it does not own your HTTP layer, your queue, or your schema beyond what it needs.
The three layers
| Layer | What it is |
|---|---|
| Factory | createBetterMedia() — assembles storage, DB, plugins, and jobs into a runtime |
| Runtime | The media object — upload, files, system, and runBackgroundJob |
| Adapters | Storage and database are swappable; plugins extend the pipeline |
Server-side ingest
Every file that enters the system through your server follows the same path:
- Your handler calls
media.upload.ingestwith a file source (buffer, stream, path, or URL) and metadata - The plugin pipeline runs — validation, transformation, and any side effects you've registered
- Bytes land in the storage adapter; a media record is written to the database adapter
- Background work (transcoding, post-processing) is enqueued via the jobs adapter if configured
- A
MediaResult— id, key, status — comes back to your handler
Direct uploads
For client-to-storage uploads, your server issues a presigned token and steps out of the data path:
The browser uploads directly to storage; media.upload.complete picks up after and runs the same plugin pipeline as server-side ingest. See Client for the browser-side SDK.
What's in this section
- API — the
createBetterMediafactory, runtime namespaces, and all method signatures - CLI — schema bootstrap, migration generation, and applying migrations
- Database — adapter interface, schema, and migration patterns
- Hooks & Webhooks — reacting to pipeline events in-process and over HTTP
- Plugins — the plugin lifecycle, context shape, and writing your own
- Rate Limiting — per-user and per-tenant upload throttling
- Background Jobs — the jobs adapter interface and worker wiring