3.9 KiB
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
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
- 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. - 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).
- 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
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.