# Install dependencies
npm install

# Create audio library directory
mkdir -p audio_library

# Copy your audio files to audio_library/
# Organize them in folders as you like

Quick Start

1. Install & Start

npm install
npm start

2. Open Admin Panel

Open your browser to: http://localhost:3000

You'll see a web interface where you can:

View your library statistics
Manage tracks (mark as single/album)
Create and manage playlists
Upload new audio files
Get Subsonic connection details

3. Scan Your Library

# Scan default library (./audio_library)
npm run scan

# Scan custom path
node src/scripts/scanLibrary.js /path/to/your/music

This will:

Find all audio files (mp3, m4a, flac, wav, aac, ogg)
Extract metadata from ID3 tags
Detect albums vs singles
Extract and save artwork
Create database entries

2. Start the Server

# Production
npm start

# Development (with auto-reload)
npm run dev

Server runs on http://localhost:3000

API Endpoints

Tracks

GET /api/tracks - Get all tracks
- Query params: ?album=, ?artist=, ?folder=, ?single=true/false
GET /api/tracks/:id - Get single track
PATCH /api/tracks/:id - Update track metadata
GET /api/tracks/folders/list - List all folders

Albums

GET /api/albums - Get all albums
GET /api/albums/:id - Get album with tracks
GET /api/albums/singles/list - Get all singles

Playlists

GET /api/playlists - Get all playlists
POST /api/playlists - Create playlist
GET /api/playlists/:id - Get playlist with tracks
POST /api/playlists/:id/tracks - Add track to playlist
DELETE /api/playlists/:id/tracks/:trackId - Remove track
DELETE /api/playlists/:id - Delete playlist

Upload

POST /api/upload - Upload audio file
- Form data: audio (file), isSingle (boolean)

Static Files

/audio/* - Stream audio files
/artwork/* - Serve album artwork

Library Organization

The server supports flexible organization:

audio_library/
├── Artist Name/
│   ├── Album Name/
│   │   ├── 01 - Track.mp3
│   │   └── 02 - Track.mp3
│   └── Singles/
│       └── Single Track.mp3
└── Various Artists/
    └── Compilation Album/

Album vs Single Detection

Files are marked as singles if:

Located in a folder named "singles" or "single"
No album tag in metadata
You manually mark them via API

Update track classification:

curl -X PATCH http://localhost:3000/api/tracks/:id \
  -H "Content-Type: application/json" \
  -d '{"isSingle": true}'

CarPlay Client Integration

Your CarPlay client should:

Fetch tracks: GET /api/tracks
Get stream URL from response
Play using AVPlayer with the streamURL
Display artwork from artworkURL

Example response:

{
  "tracks": [
    {
      "id": "abc123",
      "title": "Song Title",
      "artist": "Artist Name",
      "album": "Album Name",
      "duration": 180,
      "streamURL": "http://localhost:3000/audio/path/to/file.mp3",
      "artworkURL": "http://localhost:3000/artwork/abc123.jpg"
    }
  ]
}

Project Structure

├── src/
│   ├── server.js              # Main server
│   ├── database/
│   │   └── db.js              # SQLite database
│   ├── routes/
│   │   ├── tracks.js          # Track endpoints
│   │   ├── albums.js          # Album endpoints
│   │   ├── playlists.js       # Playlist endpoints
│   │   └── upload.js          # Upload endpoint
│   ├── services/
│   │   └── audioScanner.js    # Library scanner
│   └── scripts/
│       └── scanLibrary.js     # CLI scanner
├── audio_library/             # Your audio files
├── artwork/                   # Extracted artwork
└── audio_server.db            # SQLite database