Audiobookshelf Provider - Audiobook Guild

Custom metadata provider for Audiobookshelf that scrapes https://audiobookguild.com through Shopify's public JSON search endpoint.

Usage and third-party services

This is an independent demonstration and educational project. It is not affiliated with, endorsed by, sponsored by, or authorized by Audiobook Guild, Audiobookshelf, Shopify, or any other third-party service.

The project license applies to this software, not to third-party websites, services, APIs, data, or content. Do not use the software unless you are authorized to access the services involved. You are responsible for obtaining any required permission and for complying with applicable terms, policies, technical restrictions, and laws. Stop using it if a service operator asks you to stop or if you are uncertain whether your use is permitted.

Use the software and returned metadata at your own risk. See the Third-Party Services Notice for the complete notice and LICENSE for the software license.

What it populates

• cover art
• author
• series
• number in series
• overview
• narrator
• genres
• tags
• published year

Why this layout

• Cross-platform: plain Node.js + TypeScript, no Docker or native modules required
• Maintainable: small modules for HTTP fetch, HTML cleanup, series parsing, and response mapping
• Stable scraping surface: uses Shopify JSON endpoints instead of brittle page DOM selectors

Requirements

• Node.js 20 or newer

Install

npm install

Run

npm run dev

Production:

npm run build
npm start

The provider listens on http://localhost:8787 by default.

The container always listens on port 8787 internally. Docker and Unraid may map that to any available host port; 8787 is the default.

Docker

Build the image:

docker build -t audiobookguild-provider .

Run the container:

docker run -d \
  --name audiobookguild-provider \
  -p 8787:8787 \
  -e PORT=8787 \
  audiobookguild-provider

Or with Compose:

docker compose up -d --build

Published releases are available from GitHub Container Registry:

docker pull ghcr.io/kazrans-vibes/audiobookshelf-provider-audiobookguild:latest

If you want auth enabled:

docker run -d \
  --name audiobookguild-provider \
  -p 8787:8787 \
  -e PORT=8787 \
  -e AUTHORIZATION_TOKEN=change-me \
  audiobookguild-provider

Configuration

• PORT: HTTP port, default 8787
• AUTHORIZATION_TOKEN: optional token Audiobookshelf must send in the AUTHORIZATION header
• SEARCH_RESULT_LIMIT: default max result count, default 10
• COVER_PROXY_BASE_URL: optional public base URL for provider-hosted cover caching, for example https://abs-meta.example.com

Audiobookshelf setup

In Audiobookshelf:

1. Open Settings
2. Open Item Metadata Tools
3. Add a custom metadata provider
4. Set the provider URL to http://<host>:8787
5. If you set AUTHORIZATION_TOKEN, enter the same value as the auth token

If Audiobookshelf is also in Docker on the same machine, use the Docker host IP or a shared compose network hostname instead of localhost.

Audiobookshelf will call:

GET /search?query=<title>&author=<author>

This service responds with the format defined by the Audiobookshelf custom metadata provider spec.

Notes on field mapping

• author: Shopify vendor, with Author_... tag support as fallback/override
• narrator: all Narrator_... tags joined with ,
• series: first tag matching Series_... or series_..., else product type
• number in series: extracted from the book title when it ends in a number
• overview: cleaned from product HTML and stripped of ebook promo text
• cover art: Shopify featured image URL
• genres: all Genre_... tags
• tags: Trope_..., Harem_..., and Sexy Time_... tags
• publishedYear: extracted from Shopify published_at

Cover proxy note

The provider supports a short-lived /cover cache, but Audiobookshelf may block cover downloads from private or LAN IPs as SSRF protection.

For that reason:

• local/LAN installs should leave COVER_PROXY_BASE_URL unset
• this makes the provider return direct Shopify cover URLs
• only set COVER_PROXY_BASE_URL when this provider is reachable on a public or trusted reverse-proxied URL that Audiobookshelf can fetch

Test

npm test

Unraid Community Apps

The Community Apps metadata is kept alongside the application:

• templates/audiobookguild-provider.xml: Unraid Docker installation template
• ca_profile.xml: Community Apps maintainer profile
• icon.svg: listing artwork
• .github/workflows/docker-publish.yml: multi-architecture GHCR publishing

The Unraid template displays HTTP Host Port as an always-visible, modifiable field. The default is 8787. After installation, the container menu's WebUI action opens its /health endpoint using the selected host port.

Before the first public release, push the repository to GitHub and make the published GHCR package public. Then validate and scan the repository at https://ca.unraid.net/submit.