## 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! 🦇