181 lines
4.3 KiB
Markdown
181 lines
4.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
```bash
|
|
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:
|
|
```json
|
|
{
|
|
"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
|
|
```
|