# CSV import — the universal format

media-vault can import a plain CSV covering **any** media type in one file. It's
designed to be filled in by hand, exported from a spreadsheet, **or generated by an
AI** from photos of your shelf. Import it under **Add → Import → Universal CSV**
(there's a *Download template* button in that dialog too).

## The format

One header row, then one row per item. Columns are matched **by name**, so order
doesn't matter and extra columns are ignored. Comma or semicolon delimited (Excel's
German locale uses `;` — that's auto-detected).

| Column       | Required | Notes |
|--------------|:--------:|-------|
| `title`      | ✅ | The title. The only truly required field. |
| `type`       | recommended | `movie`, `series`, `game`, `lp`, `single`, `cd`, `console`. A disc format works too: `Blu-ray`, `DVD`, `4K` → treated as a movie and used as the format (write `series` if it's a TV box set). Empty defaults to `movie`. |
| `year`       | – | Release year (any 4-digit year in the cell is picked up). |
| `format`     | – | e.g. `Blu-ray`, `4K UHD`, `DVD`; for games the platform (`PS3`, `Xbox 360`…). |
| `tmdb_id`    | – | **Movies:** the TMDB **movie** id. **Series:** the TMDB **TV** id — TMDB keeps movies and series in separate id spaces, so the row's `type` decides which endpoint is used (`/movie/{id}` vs `/tv/{id}`). Either way → exact artwork, rating & description, no guessing. |
| `season`     | – | **Series only:** which season this physical box is (a number, or `Staffel 3`). Each season box then shows **that season's own poster** instead of the shared series poster. One row per season box you own. |
| `igdb_id`    | – | **Games:** the IGDB id (same idea). |
| `discogs_id` | – | **Vinyl / CD / single:** the Discogs release id. |
| `notes`      | – | Anything (age rating, edition, condition…). |

A provider id is only used when it matches the row's type (a `tmdb_id` on a `game`
row is ignored), so a stray column can't mislabel an item.

After importing, click **Enrich collection** — rows with an id get that exact record;
rows without one are matched by title, exactly as a title search would.

## Example

```csv
type,title,year,format,tmdb_id,notes
Blu-ray,The Matrix,1999,Blu-ray,603,
DVD,Amélie,2001,DVD,194,
4K,Dune,2021,4K UHD,438631,
series,Arrow,2012,Blu-ray,1412,tmdb_id here is a TV id
series,Breaking Bad,2008,Blu-ray,1396,
game,Halo 3,2007,Xbox 360,,igdb_id also works here
```

For season box sets, add a `season` column and one row per box — each gets its own
season poster:

```csv
type,title,year,format,tmdb_id,season,notes
series,How I Met Your Mother,2005,DVD,1100,1,
series,How I Met Your Mother,2005,DVD,1100,2,
series,How I Met Your Mother,2005,DVD,1100,3,
```

> **TV series vs. movies.** A series like *Arrow* has a TMDB id, but it's a **TV**
> id (1412), unrelated to any movie id. Put it in `tmdb_id` **and** set `type` to
> `series` — media-vault then looks it up via `/tv`, so you get the series, not a
> random film that happens to share the number. Never label a series row as a movie
> format (`Blu-ray`) with a TV id; the `type` must say `series`.

## Letting an AI fill it from photos

The whole point: photograph your discs, hand the pictures to your AI of choice with
the prompt below, get a CSV back, import it.

> You are helping me catalog my physical movie and TV-series collection. I'll send
> photos of Blu-ray / DVD / 4K covers. For each disc you can identify, output a
> single CSV (comma-separated) with exactly this header:
>
> `type,title,year,format,tmdb_id,season,notes`
>
> Rules:
> - `type` = `movie` for a film, or `series` for a TV series / box set. (You may
>   instead write the disc format `Blu-ray` / `DVD` / `4K` for a film — but a series
>   MUST be `series`.)
> - `title` = the title (no "[Blu-ray]" suffixes). For a series box, the SERIES name
>   only — don't add "Season 3" to the title; use the `season` column for that.
> - `year` = release year (first air year for a series) if you're confident, else blank.
> - `format` = the disc format: `Blu-ray`, `DVD`, or `4K UHD`.
> - `tmdb_id` = the numeric themoviedb.org id, **only if you are certain** it's the
>   right title (matching title AND year). For a `movie` use the film's **movie** id;
>   for a `series` use the show's **TV** id (these are different id spaces on TMDB —
>   don't put a TV id on a movie row or vice-versa). If unsure, leave it blank — a
>   wrong id is worse than none.
> - `season` = for a series box set, the season number shown on the cover (e.g. `3`).
>   Blank for movies. One row per season box.
> - `notes` = leave blank unless there's an edition worth noting.
> - One row per disc/box. Output only the CSV, nothing else. Don't invent titles you
>   can't read.

The `tmdb_id` is optional but worth it: with it, media-vault pulls the exact poster
and details. Without it, it still matches by title — so even a `title`-only CSV works.