audiobookshelf

Audiobookshelf API

Configuration

All settings are loaded from the .env file in the workspace root.

AUDIOBOOKSHELF_HOST=http://localhost/audiobookshelf
AUDIOBOOKSHELF_USERNAME=your_username
AUDIOBOOKSHELF_PASSWORD=your_password

Reference

• API documentation: https://api.audiobookshelf.org/
• Code Snippets: scripts/

Python API Packages

• aioaudiobookshelf: Async Python library for Audiobookshelf

Available Scripts

Script	Purpose
api_client.py	Common client setup patterns (async and sync)
list_libraries.py	List all libraries from the server
get_library_items.py	Get books with filtering by author/series
search_authors.py	Search and manage authors
update_book_metadata.py	Update book metadata via PATCH API
scan_libraries.py	Trigger library rescans
update_audio_metadata.py	Update local audio file metadata using mutagen
scan_audiobook_directory.py	Scan local directories for audiobook info

Key Patterns

Async API with aioaudiobookshelf

from aioaudiobookshelf import SessionConfiguration, get_admin_client_by_token

async with aiohttp.ClientSession() as session:
    session_config = SessionConfiguration(session=session, url=SERVER_URL, token=API_KEY)
    abs_client = await get_admin_client_by_token(session_config=session_config)
    libraries = await abs_client.get_all_libraries()

Sync API with requests

headers = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}
response = requests.patch(url, headers=headers, json=payload, timeout=10)

Local Audio Metadata with mutagen

from mutagen.mp4 import MP4
audio = MP4(file_path)
audio.tags['\xa9ART'] = [author]
audio.save()

Instructions

• Review code snippets in scripts/ for reusable patterns before creating new scripts
• Use api_client.py as starting point for new API scripts
• Use update_audio_metadata.py patterns for local file metadata updates
• Put generated scripts under $WORKSPACE_PATH/temp/