AudioApp/SUBSONIC_SETUP.md

Subsonic API Setup Guide

Your server now supports the Subsonic API! This means you can use existing music apps with CarPlay support.

Recommended Apps

iOS Apps with CarPlay Support

1. Amperfy (FREE, Open Source)

   • Download: https://apps.apple.com/app/amperfy/id1530633066
   • Best free option
   • Full CarPlay support
   • Offline caching

2. play:Sub ($4.99)

   • Download: https://apps.apple.com/app/play-sub/id955329386
   • Polished interface
   • Excellent CarPlay integration
   • Worth the price

3. Substreamer ($4.99)

   • Download: https://apps.apple.com/app/substreamer/id1012991665
   • Another solid option

Server Configuration

Default Credentials

Username: admin
Password: admin

⚠️ IMPORTANT: Change these credentials!

Edit src/routes/subsonic.js and update:

const USERS = {
  admin: { password: 'your-secure-password', salt: '' }
};

Server URL

http://your-server-ip:3000/rest

Example: http://192.168.1.100:3000/rest

Setup Instructions

1. Start Your Server

npm install
npm run scan    # Scan your audio library
npm start       # Start the server

2. Find Your Server IP

# On macOS/Linux
ifconfig | grep "inet "

# On Windows
ipconfig

Look for your local IP (usually 192.168.x.x)

3. Configure Your App

For Amperfy:

1. Open Amperfy
2. Tap "Add Server"
3. Enter:
   • Server URL: http://YOUR-IP:3000/rest
   • Username: admin
   • Password: admin
4. Tap "Connect"
5. Wait for library to sync

For play:Sub:

1. Open play:Sub
2. Tap "+" to add server
3. Enter:
   • Server Address: http://YOUR-IP:3000
   • Username: admin
   • Password: admin
   • Port: 3000
   • Path: /rest
4. Tap "Done"

4. Test CarPlay

1. Connect your iPhone to CarPlay (cable or wireless)
2. Open the music app on CarPlay display
3. Browse your library
4. Play music!

Supported Features

✅ Browse by artist, album, folder ✅ Search tracks ✅ Playlists ✅ Album artwork ✅ Audio streaming ✅ Random songs ✅ CarPlay integration (via apps)

Troubleshooting

Can't Connect

• Make sure server is running (npm start)
• Check firewall settings
• Verify IP address is correct
• Try http://localhost:3000/rest if on same machine

No Music Showing

• Run npm run scan to scan your library
• Check that audio files are in audio_library/ folder
• Look at server logs for errors

Authentication Failed

• Double-check username/password
• Make sure you're using the credentials from src/routes/subsonic.js

CarPlay Not Working

• Make sure you're using an app with CarPlay support (Amperfy, play:Sub)
• Check that CarPlay is enabled in iPhone Settings
• Try disconnecting and reconnecting CarPlay

Security Notes

For Local Network Only

Current setup is fine for home network use.

For Internet Access

If exposing to internet:

1. Change default password immediately
2. Use HTTPS (add SSL certificate)
3. Consider adding proper user authentication
4. Use a reverse proxy (nginx)
5. Set up firewall rules

API Endpoints

Your server now responds to Subsonic API calls:

• /rest/ping.view - Test connection
• /rest/getMusicFolders.view - Get folders
• /rest/getIndexes.view - Get artists
• /rest/getAlbum.view - Get album details
• /rest/stream.view - Stream audio
• /rest/getCoverArt.view - Get artwork
• /rest/getPlaylists.view - Get playlists
• /rest/search3.view - Search

All endpoints require authentication via query parameters:

• u - username
• p - password (or t + s for token auth)

Next Steps

1. Install Amperfy or play:Sub on your iPhone
2. Configure with your server details
3. Let it sync your library
4. Connect to CarPlay and enjoy!

Need Help?

Check server logs for errors:

npm start
# Watch the console output

Test the API directly:

curl "http://localhost:3000/rest/ping.view?u=admin&p=admin"

Should return XML with status="ok"