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

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:

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):

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:

[
  {
    "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! 🦇