From 981afa113171b8938f2fa807eddb6cae1be7c9ec Mon Sep 17 00:00:00 2001
From: Meik <meikdre@gmx.de>
Date: Tue, 11 Nov 2025 10:27:13 +0100
Subject: [PATCH] readme

---
 README.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 94 insertions(+)

diff --git a/README.md b/README.md
index e69de29..1972ffd 100644
--- a/README.md
+++ b/README.md
@@ -0,0 +1,94 @@
+## Halloween Sound API
+
+Eine schlanke FastAPI-Anwendung, die Audiodateien (Loops & Jumpscares) indexiert, Metadaten mit `mutagen` ausliest und sie per REST sowie statisch unter `/media` verfügbar macht – ideal für ein Halloween-Setup mit unterschiedlichen Sound-Kategorien.
+
+### Highlights
+- Liefert Länge jeder Audiodatei in Sekunden, Millisekunden und als lesbare Zeichenkette.
+- Durchsucht rekursiv beliebige Unterordner unterhalb von `SOUNDS_ROOT`.
+- Stellt die Dateien zusätzlich über `/media/<path>` bereit, sodass Frontends direkt darauf zugreifen können.
+- Docker-Image inklusive, Compose-Beispiel ready-to-run.
+
+### Projektstruktur
+```
+.
+├── app/
+│   └── main.py            # FastAPI-App & Endpunkte
+├── requirements.txt       # Python-Abhängigkeiten
+├── Dockerfile             # Produktions-Image (Port 80)
+├── docker-compose.yml     # Beispiel-Deployment (host:8282 → container:80)
+└── README.md
+```
+
+### Voraussetzungen
+- Python ≥ 3.11 (nur für lokalen Start ohne Docker nötig)
+- `mutagen` wird zur Laufzeit benötigt (bereits in `requirements.txt`)
+- Ein Verzeichnis mit Audiodateien (z. B. WAV/MP3) unterhalb des `SOUNDS_ROOT`-Pfads
+
+### Lokale Entwicklung
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+export SOUNDS_ROOT=/pfad/zu/deinen/sounds  # default: /app/sounds
+uvicorn app.main:app --reload --port 8000
+```
+Die API ist anschließend unter `http://localhost:8000` erreichbar; statische Dateien liegen unter `http://localhost:8000/media/...`.
+
+### Docker & Compose
+Direkter Build & Run:
+```bash
+docker build -t halloween-sound-api .
+docker run --rm -p 8282:80 -v /pfad/zu/sounds:/app/sounds:ro \
+  -e SOUNDS_ROOT=/app/sounds \
+  halloween-sound-api
+```
+
+Oder via `docker-compose.yml` (bereitgestellt):
+```bash
+docker compose up --build
+```
+Standardmäßig wird Port `8282` des Hosts auf Port `80` des Containers gemappt und `/opt/docker/halloween/sounds` read-only eingebunden.
+
+### Konfiguration
+| Variable     | Default      | Beschreibung                                        |
+|--------------|--------------|-----------------------------------------------------|
+| `SOUNDS_ROOT`| `/app/sounds`| Wurzelverzeichnis der Audiodateien im Container.    |
+
+Erwartete Ordnerstruktur (Beispiel):
+```
+SOUNDS_ROOT
+├── loop/
+│   ├── ambience_castle.mp3
+│   └── heartbeat.wav
+└── scare/
+    ├── scream01.mp3
+    └── door_bang.wav
+```
+Weitere Unterordner sind erlaubt; alle Dateien werden rekursiv durchsucht.
+
+### API-Endpunkte
+| Methode | Pfad                | Beschreibung |
+|---------|--------------------|--------------|
+| `GET`   | `/sounds`           | Liefert beide Kategorien (`loop`, `scare`) als Objekt. |
+| `GET`   | `/sounds/{category}`| Liefert nur die angegebene Kategorie (404, falls unbekannt). |
+| `GET`   | `/media/...`        | Statische Auslieferung der Originaldateien. |
+| `GET`   | `/`                 | Absichtlich 403 mit einer ☠️-Seite. |
+
+Beispielantwort `GET /sounds/scare`:
+```json
+[
+  {
+    "path": "http://localhost:8282/media/scare/scream01.mp3",
+    "duration_seconds": 4,
+    "duration_milliseconds": 4231,
+    "duration_human": "4.231s"
+  }
+]
+```
+
+### Fehlerbehandlung & Tipps
+- Fehlende Kategorien liefern `404`, leere Verzeichnisse hingegen eine leere Liste.
+- `mutagen` ignoriert nicht unterstützte Dateitypen automatisch (sie fehlen dann einfach in der Antwort).
+- Das Root-HTML (`/`) ist nur als Schutz gedacht – baue dein Frontend direkt auf `/sounds` und `/media`.
+
+Happy haunting! 🦇