No iOS/Android/Expo steps — this is a pure Node.js backend.

Project setup

1. Copy source/ into your project root (e.g. myapp/server/).
2. Set the following environment variables (.env or process environment):

NODE_ENV=production
PORT=3000
HOST=0.0.0.0
# Data and metadata paths
CONFIG_PATH=/data/config
METADATA_PATH=/data/metadata
# ffmpeg (if not on PATH)
FFMPEG_PATH=/usr/bin/ffmpeg
FFPROBE_PATH=/usr/bin/ffprobe
# JWT secret
TOKEN_SECRET=replace_with_a_long_random_string

3. In your package.json set "main": "server/Server.js" or import it explicitly.
4. If using TypeScript, add path aliases in tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@server/*": ["server/*"]
    }
  }
}

5. The entry point is server/Server.js. Instantiate and call init():

const Server = require('./server/Server')
const server = new Server()
server.init()

6. SQLite database file is created automatically at CONFIG_PATH/absdatabase.sqlite on first run.

Public API

vending (archiver factory)

// libs/archiver/index.js
function vending(format: string, options?: object): Archiver
vending.create(format: string, options?: object): Archiver
vending.registerFormat(format: string, module: Function): void

Dispenses a configured Archiver instance for a registered format (e.g. "zip", "tar"). Use vending.registerFormat once at startup to add a format module, then call vending(format, options) or vending.create(format, options) to get a streaming archiver. Throws if the format is not registered or the module is missing append/finalize prototype methods.

balanced (balanced-match utility)

// libs/archiver/archiverUtils/balancedMatch/index.js
function balanced(
  a: string | RegExp,
  b: string | RegExp,
  str: string
): { start: number; end: number; pre: string; body: string; post: string } | null

balanced.range(a: string, b: string, str: string): [number, number] | undefined

Finds the first balanced pair of delimiters a…b inside str. Returns a result object with pre, body, and post segments, or null if no match. Use it when parsing brace-expanded glob patterns or any nested delimiter structure.

realpath (fs-realpath)

// libs/archiver/archiverUtils/fsRealpath/index.js
function realpath(p: string, cache: object | null, cb: (err: Error | null, result: string) => void): void
function realpathSync(p: string, cache?: object): string

A Node.js version-aware wrapper around fs.realpath that falls back to a pure-JS implementation for ELOOP, ENOMEM, and ENAMETOOLONG errors on older runtimes. Use it anywhere you resolve symlinks inside the scanner or file-upload pipeline to avoid silent failures on path-too-long errors.

Working examples

Scenario - Boot the full server

Start Express, Socket.IO, Passport, and the SQLite database in one call using the provided Server class entry point.

// main.ts
process.env.CONFIG_PATH = '/data/config'
process.env.METADATA_PATH = '/data/metadata'
process.env.TOKEN_SECRET = 'my_secret_32_chars_minimum'
process.env.PORT = '3000'

const Server = require('./server/Server')

async function main() {
  const server = new Server()
  await server.init()
  console.log('Audiobookshelf server running on port 3000')
}

main().catch(console.error)

Scenario - Create a ZIP archive of exported metadata

Use the vendored archiver to stream a ZIP of metadata files to an HTTP response.

// routes/exportMetadata.ts
import express from 'express'
const archiver = require('./server/libs/archiver')

// Register zip format once at startup
archiver.registerFormat('zip', require('./server/libs/archiver/lib/plugins/zip'))

const router = express.Router()

router.get('/export-zip', (req, res) => {
  const archive = archiver.create('zip', { zlib: { level: 9 } })

  res.setHeader('Content-Type', 'application/zip')
  res.setHeader('Content-Disposition', 'attachment; filename="metadata.zip"')
  archive.pipe(res)

  archive.directory('/data/metadata/items', 'items')
  archive.finalize()

  archive.on('error', (err: Error) => {
    console.error('Archive error', err)
    res.status(500).end()
  })
})

export default router

Scenario - Resolve a symlinked library path safely

Use the fsRealpath wrapper to canonicalize a user-supplied library folder path before adding it to the database.

// utils/resolveLibraryPath.ts
const { realpathSync } = require('./server/libs/archiver/archiverUtils/fsRealpath')

export function resolveLibraryPath(rawPath: string): string {
  try {
    const resolved = realpathSync(rawPath, null)
    return resolved
  } catch (err: any) {
    if (err.code === 'ENOENT') {
      throw new Error(`Library path does not exist: ${rawPath}`)
    }
    throw err
  }
}

// Usage
const safePath = resolveLibraryPath('/mnt/nas/audiobooks')
console.log('Canonical path:', safePath)

Scenario - Parse a brace-expanded glob for scanner patterns

Use balanced to extract the body of a brace expression when building custom scanner include/exclude rules.

// scanner/parseGlob.ts
const balanced = require('./server/libs/archiver/archiverUtils/balancedMatch')

export function extractBraceBody(pattern: string): string | null {
  const result = balanced('{', '}', pattern)
  if (!result) return null
  console.log('pre:', result.pre)   // text before '{'
  console.log('body:', result.body) // text inside '{}'
  console.log('post:', result.post) // text after '}'
  return result.body
}

// Example: "{mp3,m4b,flac}" => "mp3,m4b,flac"
const body = extractBraceBody('{mp3,m4b,flac}')

File walkthrough

• Auth.js — Initializes Passport strategies (local + JWT + OIDC), attaches session middleware, and exposes token issuance helpers.
• Database.js — Opens the SQLite connection via Sequelize, runs pending umzug migrations, and registers all models.
• Logger.js — Exports a singleton Winston logger; imported throughout the codebase as Logger.
• Server.js — Constructs the Express app, mounts all routers, starts the HTTP server, and bootstraps Socket.IO.
• SocketAuthority.js — Wraps Socket.IO namespaces; handles per-socket authentication and event broadcasting.
• Watcher.js — Uses chokidar to watch library directories and enqueues rescan tasks when files are added, changed, or removed.
• auth/ — Passport strategy implementations: LocalAuthStrategy.js, OidcAuthStrategy.js, and TokenManager.js for JWT lifecycle.
• controllers/ — One Express controller file per API resource; each exports middleware-compatible handler functions.
• finders/ — BookFinder.js, AuthorFinder.js, PodcastFinder.js aggregate metadata from multiple providers.
• libs/ — All vendored third-party libraries pinned to specific versions to avoid external network resolution at runtime.
• managers/ — Long-lived singleton managers (CronManager, NotificationManager, BackupManager, EmailManager, etc.).
• migrations/ — Numbered Sequelize migration files executed by umzug on startup.
• models/ — Sequelize model files (Library, LibraryItem, User, Podcast, etc.).
• objects/ — Plain-JS domain objects that mirror database models for in-memory manipulation.
• providers/ — HTTP clients for Audible, Google Books, OpenLibrary, iTunes metadata APIs.
• routers/ — Express Router instances that group and mount controller handlers.
• scanner/ — Library scanner, audio-file probe, cover extraction, and metadata normalization pipeline.
• utils/ — Cross-cutting helpers: path normalization, string sanitization, date formatting, cover image utilities.

Common pitfalls and fixes

• sqlite3 native build fails — Run npm install --build-from-source sqlite3 with python3, make, and a C++ compiler present; on Alpine use apk add python3 make g++.
• ffmpeg not found at runtime — Set FFMPEG_PATH and FFPROBE_PATH env vars explicitly; do not rely on PATH inside Docker containers with minimal images.
• TOKEN_SECRET not set — Auth.js will throw or produce unverifiable JWTs; always set a 32+ character random string before starting the server.
• Archiver format not registered error — Call archiver.registerFormat(name, plugin) exactly once before any archiver.create() call; registering twice throws "format already registered".
• openid-client version mismatch — The OIDC strategy targets a specific API surface; pin openid-client to the version in the upstream package.json (^5.x) to avoid breaking issuer discovery.
• CONFIG_PATH directory must pre-exist — Database.js does not mkdirSync the config directory; create it before starting the server or the SQLite file open will fail with ENOENT.

Vibe-coding prompt template

I have dropped the audiobookshelf server source tree into `./server/` in my
Node.js project. The integration guide is in `./USAGE.md`. The upstream
package is `user@example.com`.

Please help me integrate this step by step:

1. Read `USAGE.md` fully before writing any code.
2. Set up the required environment variables listed in USAGE.md § "Project setup".
3. Wire `./server/Server.js` as the backend entry point in my project's `index.ts`.
4. Ensure all runtime dependencies from USAGE.md § "Required dependencies" are
   installed and that native modules (sqlite3, ffmpeg) are available.
5. Mount the Express routers from `./server/routers/` onto my existing Express app,
   or explain how to delegate to the audiobookshelf `Server` instance cleanly.
6. Show me how to use the archiver from `./server/libs/archiver/index.js` to ZIP
   a directory and stream it to an HTTP response, exactly as shown in USAGE.md.
7. Identify any conflicts with my existing auth middleware and suggest how to
   coexist with `./server/Auth.js` (Passport + JWT).
8. Do not invent any imports — only use symbols documented in USAGE.md § "Public API"
   and visible in the source files under `./server/`.

License and credit

The audiobookshelf server source is released under the MIT License — see source/LICENSE if present, or refer to the upstream repository. Upstream package: user@example.com by advplyr. Vendored libraries under source/libs/ retain their individual licenses as noted in each subdirectory.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.