audiobookshelf/AGENTS.md

Audiobookshelf Development Project

Overview

This is a local development deployment of Audiobookshelf - a self-hosted audiobook and podcast server. The project is cloned from the original repository and configured for personal enhancements and development.

Repository Configuration

• Original Remote: origin (git@github.com:advplyr/audiobookshelf.git)
• Personal Remote: tibi (git@github.com:tiberiuichim/audiobookshelf.git)
• Default Branch: Typically master or main
• Development Scope: Personal enhancements only - no contributions back to original repo

Technology Stack

Backend

• Runtime: Node.js (v20)
• Framework: Express.js with Socket.IO
• Database: SQLite3 with Sequelize ORM
• Key Libraries:
  • axios - HTTP client
  • passport - Authentication
  • socket.io - WebSocket support
  • sequelize - ORM
  • nodemailer - Email notifications

Frontend

• Framework: Nuxt.js (Vue.js)
• State Management: Vuex
• CSS: Custom styles with PostCSS
• Internationalization: i18n support (36+ languages)

Project Structure

audiobookshelf/
├── client/                 # Nuxt.js frontend application
│   ├── assets/            # Static assets (CSS, images)
│   ├── components/        # Vue components
│   ├── layouts/           # Page layouts
│   ├── middleware/        # Route middleware
│   ├── mixins/            # Reusable Vue mixins
│   ├── pages/             # Application pages
│   ├── plugins/           # Vue plugins
│   ├── static/            # Static files
│   ├── store/             # Vuex stores
│   └── strings/           # i18n translations
├── server/                # Node.js backend
│   ├── auth/             # Authentication strategies
│   ├── controllers/      # API controllers
│   ├── finders/          # Metadata finders
│   ├── libs/             # Utility libraries
│   ├── managers/         # Business logic managers
│   ├── migrations/       # Database migrations
│   ├── models/           # Sequelize models
│   ├── objects/          # Domain objects
│   ├── providers/        # External service providers
│   ├── routers/          # Express routers
│   ├── scanner/          # Library scanning logic
│   └── utils/            # Utility functions
├── data/                 # Local test data (ignored by git)
├── docs/                 # API documentation (OpenAPI)
├── images/               # Project images
├── index.js             # Application entry point
├── prod.js              # Production entry point
└── package.json         # Dependencies and scripts

Key Features

• Self-hosted audiobook and podcast server
• Multi-user support with custom permissions
• Progress syncing across devices
• Automatic library detection and scanning
• Chromecast support
• RSS feeds for podcasts and audiobooks
• Chapter editing and lookup
• Audio file merging (m4b)
• Metadata embedding
• Ebook support (EPUB, PDF, CBR, CBZ)
• Backup and restore functionality

Development Commands

# Install dependencies
npm ci                    # Root dependencies
cd client && npm ci       # Client dependencies

# Build client
npm run client           # Build production client
cd client && npm run generate  # Generate static files

# Run development server
npm run dev              # Nodemon with file watching on port 3333
cd client && npm run dev # Live reload client on port 3000

# Run production
npm start               # Start production server
npm run prod            # Build client and start production

# Testing
npm run test            # Run unit tests with Mocha
npm run coverage        # Run tests with code coverage

# Docker
docker buildx build --platform linux/amd64,linux/arm64 -t advplyr/audiobookshelf

Local Development Setup

1. Node.js v20 and FFmpeg are required
2. Create dev.js in root directory for local configuration (see .devcontainer/dev.js for example)
3. Default development ports:

• Server: 3333
• Client (dev): 3000

4. Access the running instance directly on localhost:3333

Important Notes

• This is a local deployment - no reverse proxy or deployment configuration is needed
• All changes are committed to the tibi remote: git push tibi <branch>
• The data/ directory contains test audiobooks and is git-ignored
• Database is SQLite-based, stored in config location (not in repo)
• Client must be regenerated after frontend changes: (cd client; npm run generate)

API Documentation

OpenAPI documentation available at docs/openapi.json

Code Style

• JavaScript (ES6+)
• Vue.js components with Composition API where applicable
• Sequelize models for database operations
• No comments in code unless explicitly requested

Database Migrations

Located in server/migrations/. Key migrations include:

• v2.15.0+ - Schema improvements
• v2.17.x - Foreign key constraints and indices
• v2.19.x - Library item improvements
• v2.26.0 - Authentication tables

Run migrations automatically on server startup.

Portable Database Setup

The database uses relative paths for portability. When moving the entire project folder:

Path Structure

Data Type	Database Path	Actual Location
Audiobooks	audiobooks/	./data/audiobooks/
Cover images	metadata/metadata/items/	./metadata/metadata/items/
Backups	metadata/metadata/backups/	./metadata/metadata/backups/

Migration Script

Run the migration script to convert absolute Docker paths to relative paths:

./scripts/migrate_to_relative_paths.sh

This script:

1. Creates a backup at config/absdatabase.sqlite.backup
2. Converts libraryFolders.path to relative paths
3. Converts libraryItems.path and relPath to relative paths
4. Converts books.coverPath to relative paths
5. Updates settings.backupPath in JSON configuration
6. Creates necessary directory structure

Directory Structure (Created by Migration)

data/
  audiobooks/
metadata/
  metadata/
    items/
    backups/
    cache/
    logs/
    streams/
config/
  absdatabase.sqlite
  absdatabase.sqlite.backup

Starting the Server

cd /mnt/docker/work/books/audiobookshelf
npm run dev

The server will resolve all paths relative to the current working directory.

Artifact Specifications

Each new feature or major change should be documented in an artifact specification file. These files serve as the planning and record of implementation for the feature.

Organization

• Location: All artifact specifications are stored in the artifacts/ directory.
• Dated Folders: Specifications should be placed in a subfolder named by the current date (e.g., artifacts/YYYY-MM-DD/).
• Filename: Use descriptive names for the specification files (e.g., move-to-library-specification.md).

Managing Folders

A Makefile is provided in the artifacts/ directory to quickly set up the folder for the current day:

cd artifacts
make  # Runs the 'today' target to create the dated folder

Purpose

Artifact specifications should serve as a source of truth for the feature's lifecycle. A high-quality specification includes:

1. Detailed Overview: Clear summary of the user-facing functionality.
2. API & Data Contracts: Explicit documentation of new endpoints (methods, paths, payloads) and schema changes.
3. Traceability (Files Modified): A table of all files touched in the implementation, categorized (e.g., Backend, Frontend, Docs).
4. Architectural Decisions: Explanation of why certain patterns were used (e.g., shared utility functions, state management choices).
5. Localization: Tracking of new string keys or translation updates.
6. Verification Plan: Concrete testing steps (manual or automated) to verify the implementation.
7. Limitations & Future Work: Explicitly stating what is not supported or known edge cases that weren't addressed.

Best Practices

• Update as you go: The artifact should be updated during implementation if the plan changes.
• Be Specific: Avoid vague descriptions. If a function is moved to a controller, name the function and the controller.
• Use Tables: Tables are great for listing files or comparing before/after states.
• Include Code Snippets: For API definitions or complex logic flows, short code/JSON snippets are highly encouraged.

Related Documentation

• Main Documentation
• User Guides
• API Documentation
• Discord Community