forked from computertech/techdj
229 lines
4.3 KiB
Markdown
229 lines
4.3 KiB
Markdown
# TechDJ Pro
|
||
|
||
TechDJ Pro is a local DJ web app with a dual-port architecture:
|
||
|
||
- **DJ Panel** (mix/load tracks + start broadcast): `http://localhost:5000`
|
||
- **Listener Page** (receive the live stream): `http://localhost:5001`
|
||
|
||
It supports:
|
||
- Local library playback (files in `music/`)
|
||
- Downloading audio from URLs (via `yt-dlp` when available, with fallback)
|
||
- Live streaming from the DJ browser to listeners using Socket.IO
|
||
- Live listening via an **MP3 stream** (`/stream.mp3`) generated server-side with **ffmpeg**.
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
### System packages
|
||
|
||
- **Python**: 3.10+ recommended
|
||
- **ffmpeg**: strongly recommended (required for reliable downloads/transcoding and MP3 fallback)
|
||
|
||
Linux (Debian/Ubuntu):
|
||
|
||
```bash
|
||
sudo apt update
|
||
sudo apt install -y ffmpeg
|
||
```
|
||
|
||
macOS (Homebrew):
|
||
|
||
```bash
|
||
brew install ffmpeg
|
||
```
|
||
|
||
Windows:
|
||
- Install ffmpeg from https://ffmpeg.org/download.html
|
||
- Ensure `ffmpeg` is on your PATH
|
||
|
||
### Python dependencies
|
||
|
||
All Python dependencies are listed in `requirements.txt`:
|
||
|
||
- flask
|
||
- flask-socketio
|
||
- eventlet
|
||
- yt-dlp
|
||
- python-dotenv
|
||
- requests
|
||
|
||
---
|
||
|
||
## Install (from scratch)
|
||
|
||
```bash
|
||
git clone https://git.computertech.dev/computertech/techdj.git
|
||
cd techdj
|
||
|
||
# Create venv
|
||
python3 -m venv .venv
|
||
|
||
# Activate venv
|
||
source .venv/bin/activate
|
||
|
||
# Ensure pip exists (some environments require this)
|
||
python -m ensurepip --upgrade || true
|
||
|
||
# Upgrade tooling (recommended)
|
||
python -m pip install --upgrade pip setuptools wheel
|
||
|
||
# Install deps
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
---
|
||
|
||
## Optional configuration (.env)
|
||
|
||
Create a `.env` file in the project root if you want YouTube search results to work in the UI:
|
||
|
||
```dotenv
|
||
YOUTUBE_API_KEY=YOUR_KEY_HERE
|
||
```
|
||
|
||
Notes:
|
||
- If you don’t set `YOUTUBE_API_KEY`, you can still paste a YouTube URL directly into a deck/download box.
|
||
|
||
---
|
||
|
||
## Run
|
||
|
||
Start the server:
|
||
|
||
```bash
|
||
source .venv/bin/activate
|
||
python server.py
|
||
```
|
||
|
||
You should see output like:
|
||
|
||
- DJ panel: `http://localhost:5000`
|
||
- Listener page: `http://localhost:5001`
|
||
|
||
---
|
||
|
||
## Using the app
|
||
|
||
### DJ workflow
|
||
|
||
1. Open the DJ Panel: `http://localhost:5000`
|
||
2. Click **INITIALIZE SYSTEM**
|
||
3. Load/play music
|
||
- Upload MP3s (folder/upload button)
|
||
- Or download from URLs (paste into deck input / download controls)
|
||
4. Open the streaming panel and click **START BROADCAST**
|
||
|
||
### Listener workflow
|
||
|
||
1. Open the Listener Page:
|
||
- Same machine: `http://localhost:5001`
|
||
- Another device on your LAN/Wi‑Fi:
|
||
|
||
`http://<DJ_MACHINE_IP>:5001`
|
||
|
||
2. Click **ENABLE AUDIO** if prompted
|
||
- Browsers block autoplay by default; user interaction is required.
|
||
|
||
---
|
||
|
||
## Multi-device / LAN setup
|
||
|
||
### Find your DJ machine IP
|
||
|
||
Linux:
|
||
|
||
```bash
|
||
ip addr
|
||
```
|
||
|
||
Windows:
|
||
|
||
```bat
|
||
ipconfig
|
||
```
|
||
|
||
macOS:
|
||
|
||
```bash
|
||
ifconfig
|
||
```
|
||
|
||
Use the LAN IP (commonly `192.168.x.x` or `10.x.x.x`).
|
||
|
||
### Firewall
|
||
|
||
Make sure the DJ machine allows inbound connections on:
|
||
- TCP `5000` (DJ Panel)
|
||
- TCP `5001` (Listener)
|
||
|
||
If listeners can’t connect, this is often the cause.
|
||
|
||
---
|
||
|
||
## Streaming
|
||
|
||
TechDJ serves the listener audio as an **MP3 HTTP stream**:
|
||
|
||
- MP3 stream endpoint: `http://<DJ_MACHINE_IP>:5001/stream.mp3`
|
||
|
||
This requires `ffmpeg` installed on the DJ/server machine.
|
||
|
||
### Debug endpoint
|
||
|
||
- Stream debug JSON:
|
||
|
||
`http://<DJ_MACHINE_IP>:5001/stream_debug`
|
||
|
||
This shows whether ffmpeg is running and whether MP3 bytes are being produced.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
### Listener says “Browser blocked audio”
|
||
|
||
- Click **ENABLE AUDIO**
|
||
- Try a normal click (not keyboard-only)
|
||
- Disable strict autoplay blocking for the site, if your browser supports it
|
||
|
||
### Listener says “NotSupportedError”
|
||
|
||
- Your browser likely doesn’t support the default WebM/Opus MediaSource path
|
||
- Ensure `ffmpeg` is installed on the server
|
||
- Try opening the MP3 fallback directly:
|
||
|
||
`http://<DJ_MACHINE_IP>:5001/stream.mp3`
|
||
|
||
### DJ says broadcast is live but listeners hear nothing
|
||
|
||
- Confirm:
|
||
- A deck is actually playing
|
||
- Crossfader isn’t fully on the silent side
|
||
- Volumes aren’t at 0
|
||
- Check `http://<DJ_MACHINE_IP>:5001/stream_debug` and see if `transcoder_bytes_out` increases
|
||
|
||
### `pip` missing inside venv
|
||
|
||
Some Python installs create venvs without pip. Fix:
|
||
|
||
```bash
|
||
python -m ensurepip --upgrade
|
||
python -m pip install --upgrade pip
|
||
```
|
||
|
||
---
|
||
|
||
## Dev notes
|
||
|
||
- Main server: `server.py`
|
||
- Client UI logic: `script.js`
|
||
- Downloader: `downloader.py`
|
||
- Static assets: `index.html`, `style.css`
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
No license specified.
|