intial Readme

README.md

@@ -1,2 +1,75 @@
-# vinyl-streamer
+# Vinyl Streamer
 
+A lightweight, local-network streaming service that captures analog audio from a turntable and broadcasts it over the network using Icecast. Listen to your vinyl records in real-time from any device in your home.
+
+## 🎛️ Hardware Prerequisites
+
+To build this streaming node, you will need the following physical components:
+
+*   **Raspberry Pi:** A Raspberry Pi 3B, 4, or Zero 2 W is recommended, along with a reliable power supply and MicroSD card.
+*   **USB Audio Interface (ADC):** A device to convert the analog audio to a digital signal for the Pi. (e.g., Behringer UCA202, ART USB Phono Plus, or a HiFiBerry DAC+ ADC hat).
+*   **Turntable:** Your vinyl record player.
+*   **Phono Preamplifier:** Required to boost the turntable's low-level phono signal to a standard line-level signal. *Note: You can skip this if your turntable has a built-in preamp or if your USB audio interface includes a dedicated phono stage.*
+*   **RCA Cables:** To connect the turntable/preamp to the audio interface.
+
+## 💻 Software Prerequisites
+
+The streamer relies on two core pieces of software: a capture/encoding client and a broadcast server.
+
+*   **Linux OS:** A headless Linux distribution like Raspberry Pi OS Lite or a customized container environment. 
+*   **ALSA (Advanced Linux Sound Architecture):** Standard Linux sound drivers to detect and manage the USB audio interface (`alsa-utils`).
+*   **Darkice:** The streaming client. It captures the live audio from the ALSA device, encodes it (to MP3, Ogg Vorbis, etc.), and sends it to the server. *(Note: **Liquidsoap** is a powerful alternative to Darkice if you want to implement advanced scripting, like silence detection).*
+*   **Icecast2:** The streaming media server. It receives the encoded stream from Darkice and serves it to network clients (browsers, media players, smart speakers) via a local HTTP URL.
+
+---
+
+## 🚀 Installation & Setup
+
+### Option A: Bare-Metal Package Installation
+
+1. Update your system and install the required packages:
+   ```bash
+   sudo apt update
+   sudo apt install alsa-utils darkice icecast2
+   ```
+2. Configure Icecast by following the prompts to set your broadcast passwords.
+3. Identify your USB audio device using `arecord -l` to find the correct ALSA card number.
+4. Edit the `/etc/darkice.cfg` file to link your hardware capture device to the Icecast server.
+
+### Option B: Docker Compose Deployment
+
+If you prefer a containerized homelab setup, you can deploy the stack using Docker Compose. 
+
+**`docker-compose.yml`**
+```yaml
+services:
+  icecast:
+    image: infiniteproject/icecast
+    container_name: vinyl-icecast
+    ports:
+      - "8000:8000"
+    environment:
+      - ICECAST_SOURCE_PASSWORD=hackme
+      - ICECAST_ADMIN_PASSWORD=admin
+      - ICECAST_PASSWORD=hackme
+      - ICECAST_RELAY_PASSWORD=hackme
+    restart: unless-stopped
+
+  darkice:
+    image: pltnk/darkice
+    container_name: vinyl-darkice
+    devices:
+      - /dev/snd:/dev/snd  # Pass through the ALSA audio device
+    volumes:
+      - ./darkice.cfg:/etc/darkice.cfg:ro
+    depends_on:
+      - icecast
+    restart: unless-stopped
+```
+*(Ensure your ALSA device is mapped correctly and your `darkice.cfg` points to the `icecast` container hostname).*
+
+## 🎧 Listening to the Stream
+
+Once the services are running and a record is spinning, you can access the stream from any device on your local network by pointing your browser or a network media player to:
+
+`http://<RASPBERRY_PI_IP>:8000/vinyl`