MusicOrck · Streaming Migration Guide

Interaktive Anleitung zur sauberen Umstellung auf Objekt-Storage + CDN

Diese Anleitung ist exakt für euren jetzigen Ist-Stand aufgebaut: WordPress + Theme-APIs + geschützter Stream-Endpunkt + audio_src im Frontend. Ziel ist eine spätere saubere Migration auf Cloudflare R2, alternativ Backblaze B2 oder Hetzner Object Storage, ohne das Frontend erneut zu zerlegen.

Aktueller sauberer Zwischenstand

Playernutzt bereits audio_src statt offener MP3-Datei

Backendliefert signierte Stream-URLs aus

Schutzdirekter Datei-Zugriff kann serverseitig blockiert werden

Späterer Umbaumuss dadurch hauptsächlich serverseitig erfolgen

Zielbild

Heute: PHP autorisiert und streamt

Morgen: PHP autorisiert nur noch

Später: CDN / Storage liefert private Datei performant aus

Optional: HLS/DASH als nächster Qualitäts-Schritt

Die Kernentscheidung

Euer jetziger Aufbau ist richtig, weil die entscheidende Trennung schon existiert:

Frontend spielt `audio_src`

Das Frontend muss nicht wissen, wo die Datei später physisch liegt. Es braucht nur einen gültigen Audio-Link.

API erzeugt geschützte URL

Heute zeigt audio_src auf stream_audio.php. Später kann die gleiche Logik intern an Storage/CDN weitergeben.

Physische Auslieferung wird austauschbar

Damit bleibt der spätere Umbau hauptsächlich im Server-/Storage-Layer und nicht im UI oder in der Bibliothek.

Was jetzt wichtig ist

Track-Ordner bleibt blockiert
Direkte Datei-URLs sollen künftig nicht mehr die normale Wiedergabe übernehmen.

Alle Player-Pfade lesen audio_src zuerst
Kein Fallback zurück auf offene MP3-Links, wenn eigentlich geschützt gestreamt werden soll.

stream_audio.php bleibt zentrale Autorisierungsstelle
Diese Datei ist später der Schlüssel für den sauberen Server-/CDN-Umbau.

Server-Umbau erst bei echter Infrastrukturentscheidung
Storage/CDN und Origin-Schutz erst final bauen, wenn der Zielanbieter wirklich feststeht.

Der saubere Zielpfad in einem Satz

Heute: get_* APIs → audio_src → stream_audio.php → Datei
Später: get_* APIs → audio_src → stream_audio.php → interner Redirect / Signed Storage URL / CDN

Heute funktionierende Architektur

Die Listen-APIs geben Songs aus und ergänzen audio_src additiv. Das ist richtig, weil file_url noch als Bestandsfeld existiert, aber die Wiedergabe schon auf den geschützten Pfad umgestellt werden kann.

Der PreloadManager und die Bibliothek müssen zuerst audio_src nutzen. Dann ist es egal, ob die Quelle lokal, intern umgeleitet oder später auf R2/B2/Hetzner liegt.

Diese Datei prüft aktuell Login, Token, Song-ID und liefert dann die Datei aus. Genau hier wird später der serverseitige Umbau angesetzt.

Der Track-Ordner darf nicht die normale öffentliche Wiedergabe liefern. Er bleibt künftig Schutzbereich; autorisierte Auslieferung läuft über den Stream-Pfad.

Spätere Zielarchitektur

Storage

Dateien liegen nicht mehr primär lokal im Webroot, sondern in privatem Object Storage.

Autorisierung

stream_audio.php prüft weiter Login, Rechte, Token und Song-Zugriff.

Auslieferung

Nach erfolgreicher Prüfung übernimmt entweder ein interner Server-Redirect oder ein Signed URL / CDN-Endpunkt die eigentliche Datenlieferung.

Frontend bleibt stabil

Weil das Frontend nur audio_src konsumiert, bleibt dort idealerweise fast alles unverändert.

Empfehlung

Cloudflare R2

Beste Zielrichtung für euch, wenn globale Auslieferung und Streaming-Kosten im Fokus stehen.

Stark für Streaming
besonders interessant, wenn viele Streams Egress erzeugen

S3-kompatibel
gut für späteren Standard-Umbau

Gute Skalierungsrichtung
passt zu späterem CDN-/Edge-Denken

Alternative

Backblaze B2

Stark als günstiger Storage-Backbone. Besonders interessant, wenn Kosten pro gespeichertes Volumen extrem wichtig sind.

Sehr guter Storage-Fokus
gut für große Medienmengen

S3-kompatibel
technisch gut integrierbar

Streaming nur mit sauberem Egress-/CDN-Plan
hier muss man Kosten- und Traffic-Modell bewusst mitdenken

EU / DSGVO

Hetzner Object Storage

Starke EU-Variante für Deutschland-/DSGVO-orientierte Projekte mit S3-kompatibler Struktur.

EU-Orientierung
gut für DSGVO- und Standort-Fokus

S3-kompatibel
gute technische Basis

Weniger „weltweites Streaming-Ökosystem“ als R2
aber sehr stark als europäische Lösung

Interaktive Entscheidungshilfe

Wähle deinen Hauptfokus. Die Empfehlung passt sich an.

Ich will die beste Streaming-Richtung

globale Auslieferung, saubere Zukunftsskalierung, Egress sehr wichtig

Ich will EU/Deutschland/DSGVO priorisieren

europäische Struktur und Compliance-Fokus stehen höher

Ich will maximal günstig speichern

Storage-Kosten stehen im Vordergrund, CDN-Modell wird bewusst separat geplant

Empfehlung: Cloudflare R2.
Für MusicOrck ist das die stärkste Hauptlinie, weil euer Projekt langfristig vom Streaming-Pattern und von einer sauberen Standard-Migration profitiert.

Datei-Matrix: Was bleibt, was wird später angepasst?

Datei	Heutige Rolle	Späterer Status	Änderungsgrad	Bemerkung
/wp-content/themes/musicorck/assets/api/get_songs_v2.php	liefert Songliste + `audio_src`	bleibt sehr wahrscheinlich bestehen	gering bis mittel	Nur die Generierung von `audio_src` kann später auf neue Signatur-/Storage-Logik umgestellt werden.
/wp-content/themes/musicorck/assets/api/get_playlist_songs.php	liefert Playlist-Songs + `audio_src`	bleibt sehr wahrscheinlich bestehen	gering bis mittel	Gleiche Logik wie bei der Hauptsongliste.
/wp-content/themes/musicorck/assets/api/get_user_favorites.php	liefert Favoriten + `audio_src`	bleibt sehr wahrscheinlich bestehen	gering bis mittel	Ebenfalls nur bei URL-/Signaturmodell betroffen.
/wp-content/themes/musicorck/assets/api/stream_audio.php	prüft Zugriff und streamt Datei selbst aus	wird sicher angepasst	hoch	Diese Datei wird später vom "Streamer" zum "Autorisierer + Weiterleiter".
/app/wp-content/themes/musicorck/js/app_library.js	Player/Bibliothek nutzt `audio_src`	soll idealerweise bleiben	kein bis gering	Wenn `audio_src` stabil bleibt, sollte hier später fast nichts mehr nötig sein.
/js/core/preloadManager.js	preloaded Audio aus `audio_src` / `file_url`	soll idealerweise bleiben	kein bis gering	Wichtig ist nur, dass `audio_src` weiter die Primärquelle bleibt.
/musikseite/Track/.htaccess	blockiert Direktzugriff auf lokale Audiodateien	wird evtl. ersetzt	mittel	Kann später wegfallen oder durch Server-/Origin-Regeln ersetzt werden, wenn Dateien nicht mehr lokal im Webroot liegen.
Server-Konfiguration / CDN-Regeln	heute begrenzt / lokal	wird neu aufgebaut	hoch	Der eigentliche große spätere Umbau findet hier statt, nicht in eurem UI.

Migrationspfad in Phasen

Ist-Stand einfrieren

Aktuellen funktionierenden Stream-Stand dokumentieren: audio_src, stream_audio.php, Track-Schutz, Preload-Verhalten.

Storage-Anbieter final festlegen

R2, B2 oder Hetzner nicht nur theoretisch benennen, sondern wirklich als Ziel-Storage mit Zugangsdaten, Bucket-Strategie und Domain-Plan festmachen.

Test-Bucket + Testobjekte

Einige echte Songs in einem privaten Testbereich hochladen. Noch ohne Produktivumschaltung.

stream_audio.php als Adapter umbauen

Die Datei liefert nicht mehr lokal aus, sondern gibt nach Prüfung an Storage/CDN/Server-intern weiter.

Songlisten-APIs nur bei Bedarf anpassen

Nur wenn die Generierung von audio_src geändert werden muss. Ideal: gleiche Felder, nur andere Zielquelle.

Track-Dateien schrittweise migrieren

Zuerst Testalbum, dann größere Mengen. Erst nach sauberer Verifikation den lokalen alten Pfad zurückbauen.

Warum dieser Pfad für euch sauber ist

Eure Bibliothek, euer Preload und der Player müssen nicht erneut komplett angefasst werden, wenn audio_src derselbe Vertrag bleibt.

Ihr baut keinen zweiten Playerweg. Ihr tauscht nur die physische Auslieferungsebene unter einem vorhandenen Schutzpfad aus.

Wenn der neue Storage scheitert, kann stream_audio.php wieder lokal ausliefern, solange die alte Struktur noch vorhanden ist.

Späteres Server-/Storage-Setup

Privaten Bucket anlegen

Keine öffentliche Standardauslieferung. Songs liegen in einem Bereich, der nur über signierte oder intern freigegebene Zugriffe ausgeliefert wird.

Pfadkonvention festlegen

Zum Beispiel nach Artist / Release / Song-ID strukturieren. Wichtiger als „schön“ ist: dauerhaft eindeutig, migrationsfreundlich und automatisierbar.

Mapping zwischen Song und Objektpfad

Entweder in DB als neues Storage-Feld oder über saubere Ableitung. Nicht raten, sondern deterministisch auflösen.

stream_audio.php umbauen

Nach Login-/Token-Prüfung entweder internen Redirect setzen oder Signed URL / Origin-Zugriff freigeben.

Origin-Schutz aktivieren

Der Storage darf nicht offen die komplette Bibliothek preisgeben. Nur kontrollierte Pfade dürfen echte Daten liefern.

Variante A – spätere Adapter-Logik

Das ist für euch der bevorzugte Weg.

Songlisten-API
  -> audio_src = /wp-content/themes/musicorck/assets/api/stream_audio.php?song_id=...

stream_audio.php
  -> prüft Login
  -> prüft Song-Recht
  -> prüft Token / Signatur
  -> löst Storage-Objektpfad auf
  -> gibt intern weiter an:
     a) NGINX internal path / X-Accel-Redirect
     oder
     b) signierte Storage-/CDN-URL

Browser
  -> erhält Audio-Daten weiterhin über audio_src

Variante B – direkte Signed URL in der Songliste

Technisch möglich, für euch aber erst zweite Wahl.

get_songs_v2.php / get_playlist_songs.php / get_user_favorites.php
  -> erzeugen audio_src direkt als signierte Storage-/CDN-URL

Vorteil:
  -> stream_audio.php wird kleiner oder kann entfallen

Nachteil:
  -> mehr Signatur-Logik verteilt sich auf mehrere APIs
  -> spätere Änderungen müssen an mehreren Stellen nachgezogen werden
  -> zentraler Zugriffsschutz wird schwächer gebündelt

Pflicht-Testplan vor späterer Migration

Direktlink auf Objekt darf nicht offen funktionieren
Kein freier Downloadpfad ohne Autorisierung.

audio_src spielt im eingeloggten Browser
ohne Unterbrechung und mit Preload-Verhalten.

Bibliothek spielt mehrere Songs nacheinander
inklusive Next/Skip/Playlist/Favoriten.

Preload lädt richtige Folge-Songs
keine Rückfälle auf alte offene file_url-Pfadnutzung.

Abgelaufene Tokens werden sauber abgewiesen
keine falschen Hänger ohne erkennbare Ursache.

Rollback bleibt möglich
Vor vollständiger Migration muss der alte Stand technisch reversibel sein.

Abnahmekriterien

Songlisten liefern korrekt, audio_src funktioniert, Player und Preload verhalten sich stabil, und der direkte Datei-Bypass ist geschlossen.

Keine spürbaren Verzögerungen beim Wechsel, keine „kein Ton“-Momente, keine zufälligen Token-Fehler bei normalem Hören.

Die eigentliche Medienquelle ist nicht mehr als normale offene Bibliothek erreichbar. Autorisierung läuft kontrolliert über euren vorgesehenen Pfad.

Go-Live-Checkliste für die spätere Storage-Migration

Zielanbieter final entschieden
R2 / B2 / Hetzner nicht mehr nur Plan, sondern echte Zielplattform.

Private Bucket-Struktur steht
inklusive Pfad- und Rechtekonzept.

Testalbum vollständig migriert
inklusive realer Wiedergabe- und Preload-Tests.

stream_audio.php als Adapter verifiziert
nicht nur im Browser, sondern auch im echten App-Flow.

Lokaler Altpfad bleibt vorerst als Rückfalloption
erst entfernen, wenn der neue Weg sauber stabil läuft.

Monitoring/Logs aktiv
Fehler auf Token-, Pfad- und Auslieferungsebene schnell sichtbar machen.

Die wichtigste strategische Regel

Nicht zuerst das Frontend neu bauen.
Nicht zuerst zehn APIs umbauen.

Zuerst Storage/Origin/CDN sauber aufsetzen und dann stream_audio.php als zentrale Adapter-Schicht austauschen.

Saubere MusicOrck-Regel für später:

1. audio_src bleibt der Frontend-Vertrag.
2. stream_audio.php bleibt der zentrale Schutzpfad.
3. Die physische Datei-Auslieferung wird darunter ausgetauscht.
4. Erst danach werden optionale Optimierungen wie HLS/CDN-Feintuning ergänzt.