Erstellen eines Runtime-Add-ons mit WASM für einen Musikplayer

# # Einen Musikplayer-Theme in ein Laufzeit-Add-on mit WASM und audio-reaktiven Effekten verwandeln

Das Projekt begann als Versuch, ein defektes Theme für einen beliebten Electron-Musikplayer zu reparieren, entwickelte sich aber zu einem vollwertigen Laufzeit-Add-on namens ChromaSync – komplett mit dynamischer Farbanpassung, audio-reaktivem Pulsieren, Zen-Modus und einem WebAssembly-Rechenkernen. All das läuft auf PulseSync auf – einer Plattform zur Anpassung der Oberfläche via JS/CSS –, wo der Autor an die Grenzen des Frameworks stieß und die Logik über CSS hinaus skalieren musste.

Architektur: Vom Theme zum Orchestrator

ChromaSync wurde ursprünglich als visueller Patch erdacht, wuchs aber schnell zu einem mehrschichtigen System heran. Wichtige Komponenten:

• metadata.json — Einstiegspunkt für PulseSync;
• handleEvents.json — deklarative Beschreibung der Einstellungen;
• script.js — zentrale Steuerzentrale für Zustände und Effekte;
• style.css — Basisstile und Animationen;
• WASM-Modul — Kern für rechenintensive Aufgaben (Pulsieren, Glättung);
• Backend-Schicht — optionale Netzwerkfunktionen.

Der PulseSync → handleEvents → script.js → DOM/CSS/WASM-Pipeline ermöglicht dynamische Änderungen ohne Neuladen. Beispiel: Beim Wechseln von Tracks extrahiert das Skript dominante Farben aus dem Albumcover, übergibt sie an CSS-Variablen und startet gleichzeitig audio-reaktives Pulsieren über den WASM-Kern. Alles in Echtzeit, ohne merkliche Verzögerung.

Einstellungssystem: 70 Parameter unter Kontrolle

PulseSync erlaubt Nutzern, Add-ons anzupassen, ohne Code anzurühren. Jede Einstellung ist in einer JSON-Struktur mit einer erforderlichen id definiert, die sie mit der Laufzeitlogik verknüpft. Beispielkonfiguration für den Hintergrundübergangsmodus:

{
  "id": "backgroundTrackTransitionMode",
  "name": "Withmena fona (trek)",
  "description": "Effekt switching fonovoy oblozhki when smene treka: fade (plavnaya podmena) or slide (staraya uezzhaet vlevo, novaya vezzhaet right).",
  "type": "selector",
  "selected": "1",
  "options": [
      {
          "name": "Fade (by umolchaniyu)",
          "id": "fade"
      },
      {
          "name": "Slide (left/right)",
          "id": "slide-horizontal"
      }
  ],
  "defaultParameter": "fade"
}

Mit 70 solcher Parameter wird die Normalisierung des Zustands essenziell. script.js übernimmt das: Es sammelt Werte, validiert sie, wandelt sie in ein einheitliches Zustandsobjekt um und wendet es auf die UI an. Ohne diese Schicht wäre das System unhandhabbar – besonders bei voneinander abhängigen Einstellungen, wie dem automatischen Deaktivieren von Partikeln im Zen-Modus und der Abschwächung der Pulsierungsintensität.

Evolution von script.js: Von 700 Zeilen zum Monolith

script.js begann als einfache 700-Zeilen-Datei. Heute umfasst es über 8.000 Zeilen – kein Bloat, sondern Koordination stetig wachsender Untersysteme. Es agiert als Orchestrator:

• Holt und normalisiert Einstellungen aus PulseSync;
• Verfolgt Player-Zustände (Track, Fortschritt, Vollbild);
• Verwaltet DOM-Elemente und CSS-Variablen;
• Startet/stoppt audio-reaktive Effekte;
• Ruft WASM-Funktionen für rechenintensive Berechnungen auf;
• Behandelt Maus-/Tastaturevents für Parallaxen und Interaktivität.

Frühes Beispiel: Hintergrund-Parallaxe basierend auf Mausbewegung:

const handleParallax = (event) => {
    const offsetX = event.clientX / window.innerWidth - 0.5;
    const offsetY = event.clientY / window.innerHeight - 0.5;
    const posX = `calc(50% + ${offsetX * 25}px)`;
    const posY = `calc(50% + ${offsetY * 25}px)`;

    requestAnimationFrame(() => {
        bgLayer1.style.backgroundPosition = `${posX} ${posY}`;
        bgLayer2.style.backgroundPosition = `${posX} ${posY}`;
    });
};

Später entstanden fortgeschrittenere Features – wie die dynamische Extraktion von Farbpaletten aus Track-Covern:

const applyChameleonStyles = (palette, sourceChoice) => {
    if (settings.useCustomAccentColor?.value) {
        document.documentElement.style.setProperty(
            '--accent-color',
            settings.customAccentColor?.value || '#8a63b3'
        );
        return;
    }

    const swatch = palette?.[sourceChoice] || palette?.Vibrant;
    if (!swatch) return;
    document.documentElement.style.setProperty('--accent-color', swatch.getHex());
};

WASM: Wenn JavaScript nicht mithalten kann

Der Wendepunkt kam, als das Pulsieren von simpler Animation zu einem rechenintensiven System mit mehreren Modi, Glättung und Auslösern evolvierte. JavaScript konnte die Leistungsanforderungen nicht bewältigen – besonders auf schwachen Geräten. Lösung: Den Kern nach Rust/WASM verlagern.

Modulladen:

async function loadPulseWasm() {
    const res = await fetch('/api/chromasync/rust', { cache: 'no-store' });
    const buf = await res.arrayBuffer();
    const { instance } = await WebAssembly.instantiate(buf);
    return instance.exports;
}

Beispiel für exportierte Rust-Funktion:

#[no_mangle]
pub extern "C" fn c2(prev: f32, current: f32, weight: f32) -> f32 {
    prev * weight + current * (1.0 - weight)
}

WASM übernimmt:

• Echtzeit-Berechnung der Track-Amplitude;
• Sanfte Übergänge von Frame zu Frame;
• Optimierung der Animationsbildrate;
• Isolierung schwerer Logik vom Haupt-UI-Thread.

Ergebnis: Stetige 60 FPS selbst mit aktiven Effekten und komplexen Filtern wie Pixelierung oder Rauschen.

Wichtige Erkenntnisse

• PulseSync — Plattform, um Themes in vollwertige Laufzeit-Add-ons umzuwandeln, ohne Zugriff auf den Player-Quellcode.
• WASM ist entscheidend für audio-reaktive Effekte: Liefert Leistung, die reines JavaScript nicht erreichen kann.
• script.js — mehr als ein Skript; es ist der Orchestrator, der Einstellungen, DOM, CSS und Rechenkerns verknüpft.
• Dynamische Farbanpassung aus Track-Covern nutzt Laufzeit-Bildanalyse und CSS-Variablen.
• Die Architektur skaliert: Neue Effekte als unabhängige Module hinzufügen, ohne bestehende Logik zu brechen.

Optimierung: Schönheit darf keine FPS kosten

Jeder neue Effekt birgt Risiken für Leistungsabstürze. Der Autor legt großen Wert auf Profiling und Optimierung:

• requestAnimationFrame statt setTimeout für Animationen;
• Debouncing von Maus- und Scroll-Events;
• Lazy-Loading schwerer Module (z. B. WASM nur bei Puls-Aktivierung);
• Deaktivieren ungenutzter Effekte im Hintergrund;
• Caching von Albumcover-Analyseergebnissen.

Tests zeigen: CPU-Nutzung bleibt unter 8–12 % auf durchschnittlichen Laptops, selbst mit allen Effekten (Pulsieren, Partikel, Parallaxe, Filter). So bleibt die UI reaktionsschnell und Animationen butterweich.

Die Zukunft: Wohin als Nächstes?

Der Autor plant mehrere Entwicklungsrichtungen:

• Integration von System-APIs für Lautstärke- und Medientastensteuerung;
• Nutzer-Shader-Support via WebGL;
• Cloud-Export/Sync für Einstellungen über Geräte hinweg;
• Auto-anpassende Effekte an Musikgenre (z. B. aggressives Pulsieren für EDM, sanfte Übergänge für Jazz).

Grundsatz: Keine Features um der Features willen. Jede Ergänzung muss ein echtes Nutzerproblem lösen oder das Erlebnis steigern, ohne Leistung zu opfern.

— Editorial Team