95 lines
3.5 KiB
Markdown
95 lines
3.5 KiB
Markdown
## 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! 🦇
|