Halloween-Sound-Provider/README.md at 981afa113171b8938f2fa807eddb6cae1be7c9ec

Files

Meik 981afa1131 readme

2025-11-11 10:27:13 +01:00

3.5 KiB

Raw Blame History

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

3.5 KiB Raw Blame History Unescape Escape