Music Orchestrator

Search → preview on YouTube → download as tagged MP3, organized for PlexAmp.

Production deploy (Ubuntu server, local network)

Copy the project to your Ubuntu machine, then:

bash deploy.sh

The script installs all dependencies, builds the frontend, configures nginx and a systemd service, and starts everything. Re-run it at any time to apply updates.

Access: http://<server-ip> from any device on your local network.

After deploy

# Stream live logs
journalctl -u music-orchestrator@<your-user> -f

# Restart the API
sudo systemctl restart music-orchestrator@<your-user>

# Change music library path
nano /opt/music-orchestrator/backend/.env
sudo systemctl restart music-orchestrator@<your-user>

---

Local development

Requirements: Python 3.11+, Node 18+, ffmpeg

# Backend
cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # set MUSIC_DIR
uvicorn main:app --reload --port 8000

# Frontend (separate terminal)
cd frontend
npm install
npm run dev

Open http://localhost:5173 — Vite proxies /api to the backend automatically.

---

Music library structure

Downloads are saved as:

Music/
└── Queen/
    └── A Night at the Opera/
        └── 01 - Bohemian Rhapsody.mp3

Set MUSIC_DIR in backend/.env to your Plex library folder.

Architecture notes

• 1 uvicorn worker only — download job state is held in memory. Multiple workers would each have their own job store, breaking status polling.
• nginx serves the React build as static files and reverse-proxies /api/* to the FastAPI backend on 127.0.0.1:8000.
• Metadata (title, artist, album, artwork) comes from the iTunes Search API. The YouTube video is only used for audio.