groove/audiobookshelf
1
0
Fork 0
mirror of https://github.com/advplyr/audiobookshelf.git synced 2026-02-28 21:19:42 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 5
audiobookshelf/AGENTS.md

11 KiB
Raw Blame History

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
  1. 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

UI Components & Modals

  • Modals: Do NOT use <ui-modal>. The correct component for creating modals in this project is <modals-modal>.
    • When creating a new modal, it must be imported/registered in client/layouts/default.vue (e.g., <modals-my-new-modal />).
    • The modal title should be placed inside a <template #outer> slot, following the design pattern of other modals.
    • State for whether the modal is open or closed should be managed in client/store/globals.js and toggled via a Vuex mutation.

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

CRITICAL: If you execute or create a new database migration, you MUST bump the version in package.json to match the migration version (e.g., if you create v2.32.9-my-migration.js, you must update package.json version to "2.32.9").

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.
  • Index: You can look up previous artifact specification files in artifacts/index.md.
  • Dated Folders: Specifications MUST be placed in a subfolder named by the current date (e.g., artifacts/YYYY-MM-DD/).
  • CRITICAL: Do NOT create specification files directly in the artifacts/ root. Always use the dated folder.
  • 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. AI Assistants should always run this command first if the today folder does not exist:

cd artifacts
make  # Runs the 'today' target to create the dated folder (e.g. artifacts/2026-02-17)

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

  • Use for Every Feature: For every new feature or significant development, start by creating a specification file in today's dated folder. You MUST produce an artifact specification file for ALL development work.
  • Index Management: It is CRITICAL that you update artifacts/index.md whenever you create a new artifact specification file. The index must always be kept up to date.
  • Initialization: Always run make (or make today) in the artifacts/ directory before starting work on a new specification to ensure the correct dated folder exists.
  • Relevant Naming: Name the specification file according to the task/feature (e.g., feature_name_specification.md).
  • 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