# av-club

Turning whatever someone uploads into assets a website can actually serve.

People upload photos and videos straight off a phone or a camera: a 12 MB HEIC, a 4K clip in a codec
Safari refuses to play, a JPEG carrying the GPS coordinates of the room it was shot in. None of that
belongs on a page as-is. This is the thing in between.

## Status

**Early.** Right now this repo contains the tooling requirements, an installer, and the
documentation of what the pipeline is meant to become. The processing code is not written yet.

| | |
|---|---|
| `scripts/install.sh` | Brings a machine to the state this needs, then verifies it |
| `scripts/verify.sh` | Checks the tooling by running it — usable standalone |
| `docs/TOOLING.md` | What each tool is for, and the two things that bite |
| `docs/PIPELINE.md` | What the pipeline is supposed to do, and what is still undecided |

## Quick start

```bash
./scripts/install.sh      # system packages + bun deps, then verifies
./scripts/verify.sh       # verification on its own
```

Verified on Ubuntu 24.04. The installer says so rather than guessing if it finds something else.

## Why this is its own repo

**It has system dependencies a web app should not have to assume.** ffmpeg, ImageMagick, libvips and
exiftool are a real installation, not an `npm install`. Keeping them here means a consuming project
can state that it needs this, rather than quietly failing on a machine that happens not to have
`ffprobe` on its `PATH`.

**It changes on a different clock.** Encoder settings, derivative sizes and format choices get
revisited as browser support moves. Page templates and database schemas do not.

**Nothing about it is specific to one site.** Resizing an image and extracting a poster frame are the
same problem everywhere, which is why this is not buried inside the project that first needed it.

## Its first consumer

`fofos/platform` — a website with a public site, an admin, and a database. Admins upload media
through the admin; this processes it; the platform stores what comes back.

**How that handoff works is not decided yet.** The honest options are a library the platform imports,
a CLI it shells out to, or a service it talks to. Each has real consequences for deployment and for
whether processing blocks an admin's upload while they wait. That question is written down in
`docs/PIPELINE.md` as open, rather than being answered by whatever happens to get built first.

## Working agreements

- **Commit and push every turn that changes anything** — working, broken, or half-finished. The
  history is the artifact; it is how decisions stay traceable and mistakes stay learnable.
- **Docs are live documents, and the code is the source of truth.** Docs move with the code in the
  same commit. A doc contradicting the code is a bug in the doc.
- **Direction changes fast, and that is expected.** Nothing written here is frozen.