80 lines
3.9 KiB
Markdown
80 lines
3.9 KiB
Markdown
# 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.
|