ChaptarrNG is beta software. It is under active development, and breaking changes are possible. Keep regular backups and avoid pointing it at a library you cannot afford to lose.
ChaptarrNG is Snapetech's maintained fork of Chaptarr, which is itself an independent Readarr-derived audiobook and eBook library manager. ChaptarrNG keeps that standalone library-management experience while maintaining the request and format APIs used by SeerrNG.
We forked Chaptarr so SeerrNG can rely on a book backend with explicit ebook/audiobook routing and durable handling for imports that Chaptarr queues while preparing author metadata. Maintaining the API contract here lets SeerrNG track a request through that asynchronous work without depending on upstream changes landing first. ChaptarrNG runs on its own and does not require SeerrNG.
The application continues to identify itself as Chaptarr through its Readarr-compatible API so SeerrNG can detect it. ChaptarrNG is the name of this maintained repository, its container image, and its Unraid template.
ChaptarrNG is independently maintained and is not affiliated with the Servarr team or the Readarr, Sonarr, Radarr, Lidarr, or Prowlarr projects.
The backend is built on .NET 10 LTS. Docker images include the ASP.NET Core runtime, while source builds require the .NET 10 SDK.
- Format-scoped requests and monitoring: SeerrNG can configure one service for ebooks and another for audiobooks, both pointing to one ChaptarrNG instance. Adds, lookups, and monitoring preserve the selected format and book.
- Durable pending imports: When author metadata preparation delays an add, the API returns a pending import ID and supports reading, retrying, and cancelling that work. SeerrNG can show the request waiting and resume it after the import completes.
- Safe shared-request handling: Retry and cancellation are fenced against concurrent work, so cancelling one SeerrNG request does not cancel a pending import still used by another request.
- Discovered integration contract: SeerrNG can negotiate format routes, provider identity, paged library scans, and pending-import support through
GET /api/v1/system/capabilities, while the app keeps itsChaptarrAPI identity for compatible clients. - Restricted service access: ChaptarrNG
0.9.941and later can use a SeerrNG-only API key for book requests, searches, library status, and pending imports without granting global administration or destructive access. - Direct ebook downloads: An optional built-in indexer and download client can search configured sources, use API-key downloads, and optionally fall back to browser-assisted links. Chaptarr tracks and imports supported files without requiring a separate download-client service.
- Protected backups and maintained distributions: Full backups can use passphrase-based authenticated encryption. Fork-owned releases publish container images and maintain Unraid and YunoHost packages.
The fork feature guide maps these changes to setup, API, security, and distribution documentation. The changelog has the release-by-release record.
See the SeerrNG Bookshelf backend guide for setup and the integration contract.
- Narrator Aware - Can help recognize and organize your books with narrator info
- Format-scoped books and requests - Track ebook and audiobook records separately while one ChaptarrNG instance serves both; SeerrNG can route each request to its matching format
- Publisher Aware - Special handling for dramatized audiobooks and multi-part releases
- Audio Formats - Handles M4B, MP3 chapters, and multi-file audiobooks
- MP3 → M4B Conversion - Optionally convert MP3 audiobooks into a single chaptered M4B, with chapter preservation or insertion if missing (powered by m4b-tool)
- Dual Media Libraries - You can have separate root folders for audiobooks and eBooks or choose to have your eBooks placed alongside your audiobooks
- Matching - Match audiobook and eBook files using tags, folders, and release metadata
- Series Management - Automatically organize books by series
- Metadata Profiles - Control which languages are allowed in your library, so foreign and non-English content works the way you want
- Flexible Renaming - Customizable file naming with audiobook-specific tokens
- *Standard arr Integrations - Works with the usual *arr-family download clients and indexer protocols
- Automatic Upgrades - Replace lower quality versions automatically
- Profile Flexibility - Create custom quality profiles for different libraries
ChaptarrNG is not compatible with Readarr's metadata sources. It uses Chaptarr's modular pipeline to resolve entities across metadata providers and aggregate their data through automated refinement and consensus. Metadata work remains an ongoing effort.
Docker is currently the only supported way to run ChaptarrNG. The fork is developed and tested in Docker. Releases do not include native install packages; native support is not currently offered.
Pull the image:
docker pull ghcr.io/snapetech/chaptarrng:latestRun with Docker:
docker run -d \
--name chaptarrng \
-p 127.0.0.1:8789:8789 \
-e PUID=1000 \
-e PGID=1000 \
-v /path/to/config:/config \
-v /path/to/audiobooks:/audiobooks \
-v /path/to/ebooks:/ebooks \
-v /path/to/downloads:/downloads \
--restart unless-stopped \
ghcr.io/snapetech/chaptarrng:latestNote: if PUID/PGID are not set, the image defaults to 99:100. If /path/to/config doesn't exist, Docker will create it as root:root. Create it first (or fix ownership) so it matches PUID/PGID. Avoid setting user: in Compose; it bypasses the entrypoint permission setup. On Unraid, media folders commonly use 99:100, so use PUID=99 and PGID=100 unless your share is owned differently. If multiple containers/users share the same media group, add -e UMASK=002. When testing permissions with docker exec, test as the app user, not root, for example: docker exec -u 99:100 chaptarrng sh -c 'id; touch /audiobooks/.chaptarr-write-test && rm /audiobooks/.chaptarr-write-test'.
The host port is bound to loopback by default. To expose ChaptarrNG directly on
your LAN, change the mapping to -p 8789:8789 and restrict access with your
firewall or reverse proxy. If SeerrNG runs in another container, attach both
containers to a shared Docker network and use http://chaptarrng:8789; do not
use localhost from inside SeerrNG.
Or use Docker Compose:
wget https://raw.githubusercontent.com/snapetech/chaptarrng/main/docker-compose.yml
# Edit paths in docker-compose.yml
docker compose up -dChaptarrNG supports using an external PostgreSQL database instead of the default SQLite chaptarr.db file. To enable it, set at least Chaptarr__Postgres__Host (and credentials).
Environment variables:
Chaptarr__Postgres__HostChaptarr__Postgres__Port(default:5432)Chaptarr__Postgres__UserChaptarr__Postgres__PasswordChaptarr__Postgres__MainDb(default:chaptarr-main)Chaptarr__Postgres__LogDb(default:chaptarr-log)Chaptarr__Postgres__CacheDb(default:chaptarr-cache)
Note: ChaptarrNG does not create PostgreSQL databases automatically; create the databases and grant the configured user access.
Direct Download is an optional, built-in ebook indexer and download client. It does not provide audiobook searches, recent-item feeds, or automatic discovery of arbitrary sources. Configure it only with sources you are allowed to access and use.
- Add the Direct Download indexer.
- Enter one absolute
http://orhttps://URL per line in URLs. - Enter an API Key when the source supports fast downloads, or enable Enable Slow-Download Browser Fallback when you need browser-assisted links. At least one download method is required.
- Save the indexer and select the Direct Download client for it.
Blank lines are ignored. Duplicate URLs are removed case-insensitively, and trailing slashes are normalized. The first occurrence remains in the configured order. Chaptarr never reorders the list or stores probe health as part of the settings. The provider Test action validates the URL list and, when an API key is configured, checks it against the first source without requesting a real file. A successful Test does not search for a book or prove that a title is available.
The API Key field is masked. A saved key is preserved when the indexer is edited or included in a settings backup, while API responses, logs, and validation errors must not reveal its value. Do not put credentials in a URL. If different URLs use different credentials, create separate indexers rather than placing them in one fallback list. A key must not be copied into a fallback URL or sent to a host that was not selected for the request.
When you grab a result from a supported catalog source, Chaptarr first uses the source's fast-download API when an API key is configured. If that cannot provide a file URL, the optional slow-download browser fallback can resolve a link in a headless browser during the background transfer. Browser fallback can take longer than an API grab. Direct Download is built in; it does not require qBittorrent, Transmission, or another external download client. The official Docker image includes the Playwright Chromium runtime on AMD64 and ARM64. ARMv7 images omit Chromium, so browser fallback is unavailable on ARMv7; API-key-resolved downloads still work there. A custom image must include a matching browser runtime for browser fallback to work.
The built-in client reports transfer progress and keeps its state and staged files across restarts. Once a supported ebook file is complete, Chaptarr can send it through the normal import flow. See the fork feature guide for the behavior and safety limits.
During an ebook search, Chaptarr checks the configured URLs from top to bottom. It prefers the book ISBN when one is available, then falls back to the monitored edition title. A URL is selected only after it returns a supported response with usable ebook results. Chaptarr moves to the next URL when the current one is unsafe, unavailable, times out, returns an unsupported response, or produces no usable result. It stops after the first successful URL and does not probe later entries for that search.
Each request has a bounded timeout and response-size limit. Redirects are followed only after every destination passes the same URL safety checks, and redirect chains are bounded. Search results are limited to recognized ebook file types and carry the normalized title, format, size, ISBN when available, and a direct download URL. A search fails with an actionable error when every configured URL fails or returns no usable result.
Direct Download accepts ebook searches only. Audiobook searches and audiobook releases are rejected before a Direct download is started. Supported ebook formats are limited to the formats recognized by the importer. A source that returns a page, an empty response, an unsupported format, or a non-ebook file is not a valid Direct release.
The Direct Download client requires a configured Staging Folder. Create the folder first and make sure the Chaptarr process user can read, write, create subfolders, rename files, and delete files there. Keep the staging folder on persistent storage, not a temporary container filesystem. Do not point it at a library root or a folder shared with another downloader.
Each download gets its own state record and working directory. Data is written to a .part file and promoted to the final staged file only after a non-empty response completes. The client reports queued, downloading, completed, and failed states. Transient connection, timeout, and server failures are retried up to three attempts. An interrupted partial file is discarded before a retry, so it is not treated as a completed ebook.
On restart, Chaptarr reloads Direct state from the staging folder. Queued and in-progress items are reconciled and started again, an existing completed file is reused, and a missing completed file becomes failed. Keep the state files and staged files together until the item has been imported or deliberately removed.
Cleanup is explicit. Removing an item with delete-data enabled removes its state, partial file, completed staged file, and empty per-download directory. Removing it without delete-data removes the state but preserves downloaded data for manual inspection or recovery. After an import, use the normal completed-download cleanup action and choose whether staged data should be deleted. Do not delete staged files manually while an item is queued or being imported.
Only absolute HTTP and HTTPS URLs are accepted. URLs with embedded credentials are rejected. Chaptarr blocks localhost, loopback, private, link-local, carrier-grade NAT, and cloud metadata targets, including targets reached through redirects. TLS certificate validation remains enabled. Keep source URLs and keys private, restrict access to the Chaptarr web interface, and never paste a key into an issue, log excerpt, backup shared with others, or shell history.
The feature is not a general-purpose web downloader. It depends on a source returning a supported, bounded response and a usable direct file URL. Access controls, rate limits, expiring links, changed page formats, unavailable mirrors, and licensing restrictions can cause a previously working URL to fail. A provider Test cannot detect those runtime conditions. Monitor the queue and failed items, keep backups of the configuration and library, and remove stale staging data after confirming that no queued or import-pending item references it.
Building from source requires the .NET 10 SDK, Node.js, and Yarn. When running ChaptarrNG natively, install FFmpeg for your operating system and make sure both ffmpeg and ffprobe are available on the PATH used to start the application. Normal source builds do not bundle them automatically; the ChaptarrNG Docker image already includes them.
Linux / macOS:
# Clone the repository
git clone https://github.com/snapetech/chaptarrng.git
cd chaptarrng
# Build the backend
dotnet publish src/NzbDrone.Console/Chaptarr.Console.csproj -c Release -f net10.0 -o _output/publish
# Build the frontend
yarn install
yarn build
cp -r _output/UI _output/publish/UI
# Run ChaptarrNG
dotnet _output/publish/Chaptarr.dllWindows (Command Prompt):
:: Clone the repository
git clone https://github.com/snapetech/chaptarrng.git
cd chaptarrng
:: Build the backend
dotnet publish src/NzbDrone.Console/Chaptarr.Console.csproj -c Release -f net10.0 -o _output/publish
:: Build the frontend
yarn install
yarn build
xcopy _output\UI _output\publish\UI /E /I
:: Run ChaptarrNG
dotnet _output/publish/Chaptarr.Console.dllNote: the inherited assembly is named Chaptarr.dll on Linux/macOS and Chaptarr.Console.dll on Windows.
ChaptarrNG's Unraid template is maintained in the dedicated
ChaptarrNG Unraid package repository.
It installs the maintained fork image, maps the web interface on port 8789,
and provides separate paths for appdata, audiobooks, ebooks, and downloads.
The image uses PUID=99 and PGID=100 by default; change those values to match
the ownership of your media shares.
To make ChaptarrNG searchable in Community Applications, submit the package
repository URL https://github.com/snapetech/chaptarrng-unraid through
Unraid's Community Apps submission flow and complete its validation scan.
Stable releases from the application repository's main branch publish the
latest image to GHCR.
- Default ChaptarrNG web UI: http://localhost:8789
- Default username/password: Set on first launch
- Fork changes and capabilities: feature overview and links to detailed setup and API references
- Changelog: release-by-release changes shipped by the fork
- SeerrNG Bookshelf backend guide: setup and request lifecycle
- SeerrNG integration contract: capabilities, service-key setup, and integration smoke test
- API identity and lifecycle: compatibility details for maintainers
ChaptarrNG is a community project, and we welcome contributions! Please see CONTRIBUTING.md for guidelines.
Found a bug or have a feature request? Please open an issue on GitHub with:
- Clear description of the issue/feature
- Steps to reproduce (for bugs)
- Logs if applicable
- Your environment details
ChaptarrNG inherits the Readarr-derived operational model and security work from Chaptarr. Its current protections include:
- Constant-time API-key comparison
- Login brute-force throttling
- Inbound security headers including HSTS, CSP, X-Frame-Options, X-Content-Type-Options, and Referrer-Policy
- Image proxy target validation before fetching remote images
- API responses redact provider secrets
- No analytics or crash reporting is enabled
- Optional passphrase-encrypted Quickstart Settings Backups
- Optional authenticated encryption for full backup archives
- Update binaries are verified by SHA256 before install
CI runs CodeQL and Trivy dependency/secret scans. Published container images
include a BuildKit SBOM and provenance metadata, plus a GitHub build-provenance
attestation. The Compose example also enables no-new-privileges and binds
the published web port to loopback by default.
Use the X-Api-Key header for API clients. ChaptarrNG still accepts the legacy
apikey query parameter for compatibility, so reverse proxies should redact
that parameter from access logs.
Traditional full backups contain the database and config file, including credentials. Without the setting below they are stored as plain ZIP files; protect them as secrets.
To encrypt scheduled, update, and manual full backups, store a randomly
generated passphrase with at least 16 non-whitespace characters in a secret
file, mount it read-only in the ChaptarrNG container, and set
CHAPTARR_BACKUP_ENCRYPTION_KEY_FILE to its in-container path (for example,
/run/secrets/chaptarr_backup_passphrase). The Compose example includes a
commented Docker secret setup. Backups are then written as authenticated,
chunk-encrypted .zip.enc files; existing .zip backups remain restorable.
Mount the same secret file on a replacement instance before restoring an
encrypted backup. Keep the secret outside Config.xml and the backup archive;
losing it makes those encrypted backups unrecoverable. Enabling encryption does
not convert existing .zip backups, so protect or remove those separately.
With the file path unset, new backups retain the legacy plain ZIP format.
Protect the secret file through your container secret manager, and retain old
secret files if you need to restore archives made with them.
On POSIX systems, backup staging, temporary archives, and restore extraction
directories are restricted to the application owner while the files are in use.
The Compose example publishes its web port on 127.0.0.1 by default. Set
CHAPTARRNG_BIND_ADDRESS=0.0.0.0 in the host environment to publish it on all
host interfaces, or use a shared Docker network for container-to-container
access without publishing the port.
ChaptarrNG uses api2.chaptarr.com for metadata and matching. Metadata requests may include provider IDs, search text, media type, selected audio/eBook tags, and the file name being matched. Full file paths, user identity, and indexer or download-client credentials are not sent. Update checks send version, OS, architecture, and runtime information.
Please see SECURITY.md for reporting security vulnerabilities.
ChaptarrNG is a fork of Chaptarr, which is itself an independent fork of Readarr, from the Servarr project family. This project builds on work by Chaptarr, Readarr, and the Servarr contributors to Readarr, Sonarr, Radarr, Lidarr, and Prowlarr. Thank you.
Audiobook conversion is powered by m4b-tool (by sandreas), which builds on FFmpeg and mp4v2. These are bundled in the ChaptarrNG Docker image under their respective licenses.
See COPYRIGHT.md for full attribution and copyright details.
ChaptarrNG is independently maintained. It is not affiliated with, endorsed by, or supported by the Servarr team or the Readarr, Sonarr, Radarr, Lidarr, or Prowlarr projects — please don't send ChaptarrNG support requests their way.
ChaptarrNG is provided under the GNU GPL v3 with no warranty (see the License section below).
ChaptarrNG is developed and maintained with the assistance of AI tools.
- GNU GPL v3
- Copyright © 2026 Snapetech and SeerrNG contributors for fork-specific changes
- Portions copyright © 2010–2026 the Servarr team and contributors
See the LICENSE file for the full license text and COPYRIGHT.md for attribution details.