abs-agg

A metadata provider server for Audiobookshelf. Aggregates audiobook metadata from multiple sources through a unified API.

This currently does not mean it connects them between providers. This might be added in the future.

abs-agg named after "aggregate" and the German "AGG", because each provider should be usable as the others.

Supported metadata providers

• ARD Audiothek
• Audioteka
• Big Finish
• BookBeat
• Goodreads
• Graphic Audio
• Hardcover
• LibriVox
• Libro
• Storytel
• The StoryGraph
• Die drei ???
• Soundbooth

Added in this fork (German audio dramas / Hörspiele, all scraped on demand):

• ARD Hörspieldatenbank (dra) – radio drama productions of the German public broadcasters
• hoerspiele.de (hoerspielede) – commercial releases (Europa, Kiddinx, Maritim, ...)
• Hörspiel-Request (hoerspielrequest) – episode guides of classic series
• Hoerspielprojekt.de (hoerspielprojekt) – free community productions
• Lady Bedfort (ladybedfort) – the official site of the series
• Maritim Hörspiele (maritim) – the label catalog, series level only (cover + blurb)
• HolyShop (holysoft) – Holysoft's shop: episodes with runtime, blurb, cast with roles, 1000 px covers
• Audible (audible) – the catalog API Audiobookshelf itself uses, per region

Aggregate providers for Audiobookshelf's Quick Match (one provider per library):

• hoerspiel – asks all German audio drama sources above plus Audible.de, Die drei ??? and ARD Audiothek in parallel, merges equal hits and returns one ranked list
• hoerbuch – Audible.de, Storytel (de), BookBeat (germany), Audioteka (de)

Both are strict by default (/strict:false to see everything): a result must match the title words and, if given, the author, because Quick Match takes the first hit without asking. Audiobookshelf gives a custom provider 10 s, so every source is cut off after 8 s.

For detailed documentation on each provider, see Providers.md. The "Add to Audiobookshelf" URLs in Providers.md point to the upstream public instance; for this fork use your own host, e.g. http://<host>:3001/dra.

This unifies many existing audiobook metadata providers into a single server:

Other provider attribution

• https://github.com/ahobsonsayers/abs-tract
• https://github.com/lakafior/audioteka-abs
• https://github.com/vito0912/abs-bigfinish
• https://github.com/Revisor01/abs-storytel-provider
• https://github.com/Vito0912/hardcover-provider
• https://github.com/h43lb1t0/ARD_Audiothek_provider
• https://github.com/binyaminyblatt/graphicaudio_scraper

Quick Start

Using Docker (recommended)

docker run -d \
  -p 3000:3000 \
  -v ./data:/app/data \
  ghcr.io/vito0912/abs-agg:latest

Or with docker-compose:

See docker-compose.yml.

API Usage

List available providers

GET /providers

Search for audiobooks

GET /:provider/search?title=<title>&author=<author>

Required parameters:

• title - Book title to search for

Optional parameters:

• author - Author name
• cache - Set to false to bypass cache

Example:

curl "http://localhost:3000/librivox/search?title=sherlock+holmes&author=doyle"

Important

Parameters (especially optional ones, as they are not in the examples of the providers) must be in the following format: <host>/provider/<parameter1>/../<parameter2>/search?title=<title>&author=<author>

Example: http://localhost:3000/librivox/limit:10/search?title=sherlock+holmes&author=doyle

For ABS! do not add /search at the end. Just use:
`http://localhost:3000/librivox/limit:10

Configuration

Environment variables:

Variable	Required	Description
PORT	No	Server port (default: 3000)
HARDCOVER_TOKEN	No	API token for Hardcover provider
GOODREADS_KEY	No	API key for Goodreads provider
DEEZER_ACCESS_TOKEN	No	Token for higher rate limits

Contributing

See CONTRIBUTING.md