CarPlay Audio Server

A Node.js server application for managing and streaming audio files to CarPlay-compatible clients.

Features

Audio Management

• 🎵 Automatic library scanning with metadata extraction
• 📁 Folder-based organization
• 🎼 Album vs Single classification
• 🎨 Artwork extraction and serving
• 📝 ID3 tag parsing (title, artist, album, year, genre, etc.)
• 📤 File upload support

Organization

• 📀 Album management with track grouping
• 🎯 Singles collection
• 📋 Custom playlists
• 🗂️ Folder browsing

Streaming

• 🚗 CarPlay-compatible REST API
• 🎧 Direct audio file streaming
• 🖼️ Album artwork delivery
• ⚡ Efficient file serving

Requirements

• Node.js 16+
• npm or yarn

Installation

# 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

Usage

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

1. Fetch tracks: GET /api/tracks
2. Get stream URL from response
3. Play using AVPlayer with the streamURL
4. 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