# wordarr

Request and import manager for **ebooks**, **comics/manga** and **audiobooks**, in
the style of Sonarr/Radarr. Search metadata providers, keep a list of wanted
titles, and move finished downloads into your library under a naming scheme of
your choice.

## Deployment

```bash
docker compose up -d --build
# web UI: http://localhost:8787
```

Mount `/mnt/downloads` and your library roots so that the `root_path` values
configured in wordarr exist inside the container. Keep downloads and libraries on
the same mount, otherwise moving turns into copy + delete.

| Env | Default | Description |
|---|---|---|
| `WORDARR_DOWNLOAD_DIR` | `/mnt/downloads` | scanned download folder |
| `WORDARR_CONFIG_DIR` | `/config` | location of the SQLite database |
| `WORDARR_AUDIBLE_REGIONS` | `de,com` | Audible marketplaces, first ranks first |
| `WORDARR_MUSICBRAINZ_UA` | see `metadata/musicbrainz.py` | user agent MusicBrainz requires |
| `WORDARR_EXTRA_EBOOK_EXTENSIONS` | – | extra ebook formats the scan should offer, e.g. `.kepub,.lit,.rtf` |
| `WORDARR_HARDCOVER_TOKEN` | – | Hardcover API token, the best ebook source; without it Hardcover is skipped |
| `WORDARR_GOOGLE_BOOKS_KEY` | – | optional, only needed when the keyless Google Books quota runs dry |
| `WORDARR_BUILD` | – | shown next to the version, e.g. the git sha; also a build arg of the image |

The header shows the running version and, behind it, the build stamp (the newest
source file, or `WORDARR_BUILD` when the image was built with it) - the quickest
way to see whether a redeploy actually arrived. `GET /api/version` returns the
same three values. Build with the git sha via
`WORDARR_BUILD=$(git rev-parse --short HEAD) docker compose up -d --build`.

The UI speaks German and English; the button next to the navigation switches
between them and remembers the choice. Without one, the browser language decides.

## Build

`.gitea/workflows/build.yml` runs the tests on every push to `main` and then
builds and pushes `gitea.steppencloud.de/admin/wordarr` as `:latest` and
`:<short sha>`, passing that sha as `WORDARR_BUILD`. It logs in with
`REGISTRY_TOKEN` if the secret exists, otherwise with the runner's own
`GITEA_TOKEN`. The last step pulls the fresh image on the host and recreates
just the wordarr container of the arr stack, so the version in the header is the
commit that was pushed.

## Usage

1. **Libraries** – create one per target folder with a media type, a naming
   scheme (`{Author}` `{Authors}` `{Narrator}` `{Narrators}` `{Title}` `{Year}`
   `{Series}` `{Volume}`) and optionally a language that filters the search.
2. **Search** – look up a title (ebooks: Hardcover, Google Books and Open
   Library, audiobooks: Audible plus MusicBrainz, manga: AniList) and request
   it, or add it by hand. The language filter narrows ebook and audiobook hits. For a series,
   *Ganze Serie…* requests every part at once — audiobooks from Audible's keyword
   crawl, ebooks from Hardcover's series listing (needs the token).
3. **Import** – scan the download folder. wordarr suggests file→request matches,
   which you confirm or correct; entries can be merged, split, or turned into
   requests from their folder names. Every row names its format and size, and
   the toolbar can filter by format - a Calibre export lists the same book once
   per format, and only one of them belongs in the library. Importing renames and moves the files
   according to the library's scheme and writes audio tags.

Imported titles can be edited afterwards; *Speichern & neu ablegen* re-applies
the naming scheme to files already in the library.

## Development

```bash
python3 -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
WORDARR_CONFIG_DIR=./config WORDARR_DOWNLOAD_DIR=/mnt/downloads \
  .venv/bin/uvicorn wordarr.main:app --port 8787
```

The browser tests in `tests/test_ui_dialogs.py` need `playwright` plus its
chromium build and skip themselves when either is missing.