diff --git a/.gitignore b/.gitignore
index 59dd477..4f001c3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,27 @@
-music
-.venv
+music/
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyd
+.Python
+
+# Virtual envs
+.venv/
+venv/
+ENV/
+
+# Env files
 .env
+.env.*
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS / editor
+.DS_Store
+.vscode/
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ba82c2d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,237 @@
+# 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
+- **Compatibility fallback**: if a listener browser can’t play the WebM/Opus stream, it can fall back to 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 formats & fallback
+
+### Default stream
+
+- DJ browser encodes live audio using `MediaRecorder` (usually WebM/Opus)
+- Listeners receive chunks over Socket.IO and play them via MediaSource
+
+### MP3 fallback (compatibility)
+
+Some browsers/environments don’t support WebM/Opus + MediaSource well.
+In that case TechDJ can fall back to:
+
+- 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.