# audiobookshelf — /abs

<!-- toc -->

Mounts a self-hosted [audiobookshelf](https://www.audiobookshelf.org/)
server at `/abs`, so your audiobooks browse, queue, and play like any other
part of the library. Audiobooks only for now — podcast libraries on the ABS
server are not listed.

## Logging in

The provider needs two things in `abs.toml`: your server's base URL and an
**API key**. Without both, `/abs` does not mount and the rest of the server
carries on.

1. Open your audiobookshelf web UI as the user whose libraries you want.
2. Go to **Settings → Users → (your user) → API Keys** (on older versions:
   **Settings → API Keys**) and create a key.
3. Put it in `~/.config/crabidy/abs.toml`:

   ```toml
   base_url = "https://audiobookshelf.example.com"
   api_key  = "<the key you just created>"
   ```

4. Restart the server. `/abs` appears with one child per book library.

There is no interactive login and no token to refresh: the API key is a
long-lived bearer token. Revoke it in the same screen to cut access.

```admonish warning
The API key grants access to your audiobookshelf account. Crabidy redacts it
from logs and never prints it, but keep `abs.toml` private — it is stored in
cleartext, like every other provider credential.
```

## The tree

```text
/abs
└── <library>                     one node per "book" library
    ├── search                    create a term with `%`
    │   └── <term>                books matching the term
    │       └── <book>            the book's audio files as tracks
    └── <book>                    an audiobook
        └── <file>                one audio file = one track
```

- A **library** lists its books plus a creatable `search` node. Search is
  scoped per library: a term created under one library is not visible under
  another. See [Search](./search.md).
- A **book** lists its audio files as tracks, in the server's order. Queue or
  capture the whole book, or a single file.
- An item with no audio (an ebook-only entry) is listed but not queueable.

## Playback

Each file streams directly from audiobookshelf over HTTP with range
requests — no transcoding session is opened, and the audio is whatever the
server stores (commonly Opus or MP3; Opus needs the `opus` build feature, see
[Tailored builds](../build-features.md)). Captures (`W`) download the same
files into the content store.

## Configuration — `abs.toml`

```toml
# Required — without both of these the provider does not mount.
base_url = "https://audiobookshelf.example.com"
api_key  = "<your audiobookshelf API key>"

# Optional, defaults shown.
items_per_library = 200   # books listed per library
search_results    = 50    # books listed per search term
call_timeout_secs = 30    # per-request timeout
```

Listings are fetched fresh on every visit and capped by the values above.
Only your typed search terms are remembered, and only in memory until the
server restarts.