Installation

MuseForge kommt als einzelnes Docker-Image. Nötig sind eine NVIDIA-GPU mit mindestens 6 GB VRAM, Docker mit dem NVIDIA Container Toolkit und Platz für die Modellgewichte — plane 150 GB ein, mehr wenn du Modelle sammelst. AMD-GPUs und macOS werden nicht unterstützt, die Pipeline ist CUDA-only.

git clone https://github.com/fgilde/MuseForge.git
cd MuseForge
docker compose up -d

Danach http://localhost:7861 öffnen.

Welches Image

Die Compose-Datei baut standardmäßig lokal. Für das fertige Image den build-Block durch image: ghcr.io/fgilde/museforge:latest in docker-compose.yml ersetzen. Das veröffentlichte Image ist das runtime-Ziel, also ohne kompilierte SageAttention-Kernel — voll funktionsfähig, es fällt auf sdpa-Attention zurück.

Andere GPUs als 30xx/40xx

Der Standard-Build zielt auf die CUDA-Compute-Fähigkeiten 8.0, 8.6 und 8.9. Für andere Karten eine eigene Liste übergeben:

docker build --build-arg CUDA_ARCHITECTURES="8.6;8.9;12.0" -t museforge .

Die erste Generierung

1. http://localhost:7861 öffnen und den Willkommensdialog schließen.
2. Rechts in der Leiste einen Modus wählen: Image zeigt am schnellsten ein Ergebnis.
3. Unten in der Leiste ein Modell wählen. Alles, was als nicht heruntergeladen markiert ist, holt beim ersten Einsatz seine Gewichte.
4. Prompt eintippen und Forge drücken.
5. Die Job-Kachel in der Galerie beobachten. Fortschritt, aktueller Schritt und etwaige Fehler stehen dort; die fertige Datei landet in der Galerie.

Ein mehrzeiliger Prompt im Bildmodus erzeugt einen Job pro Zeile — so liefert ein Blueprint mit mehreren Szenen auch mehrere Bilder statt nur eines.

Wie alles zusammenhängt

Studio

Die rechte Leiste ist die Steuerfläche: oben die Modus-Reiter (Image, Video, Audio, Edit, Tools, Text), darunter die Untermodi, dann Eingaben, Prompt und unten die Modellauswahl mit Advanced und Forge. Die Galerie links zeigt Warteschlange und alle fertigen Ausgaben, filterbar nach Typ und durchsuchbar.

Erweiterte Einstellungen

Auflösung, Schritte, Guidance, Seed, Sliding-Window-Größen, LoRAs und deren Multiplikatoren. LoRAs werden pro Architektur geführt: eine Datei, die bei einem anderen Modell geladen wurde, taucht hier nicht auf, weil dieses Modell sie tatsächlich nicht laden kann. Wie man das behebt, steht unter LoRAs.

Multi-Clip und Verlängern

Videomodi können Clips zu einer Timeline verketten oder ein vorhandenes Video verlängern. Copy prompt bietet bei einem verlängerten Video sowohl den Prompt des letzten Clips als auch den ursprünglichen an, mit dem die Kette begann.

Director

Beschreibe ein Musikvideo oder einen Kurzfilm in einem Satz. Ein lokales LLM erstellt eine Shotliste, schreibt pro Einstellung einen auf das rendernde Modell zugeschnittenen Prompt, erzeugt wo sinnvoll Startbilder und lässt anschließend die gesamte Multi-Clip-Pipeline laufen. Alles Geplante bleibt änderbar, bevor du dich aufs Rendern festlegst.

Das LLM läuft lokal (Gemma-Klasse, rund 5 GB, wird beim ersten Director-Einsatz geladen). Nichts geht in eine Cloud, solange du unter Einstellungen → Services keine externe API einrichtest.

Storywriter

Text → Story. Prämisse, Genre, Tonfall, Erzählperspektive und Länge angeben; die Pipeline plant ein Outline und schreibt dann Kapitel für Kapitel, mit einer Kontinuitätsprüfung dazwischen, damit Kapitel vier noch weiß, was in Kapitel zwei geschah.

Lange Durchläufe erscheinen unten links im Aktivitätsbereich und lassen sich dort stoppen. Ein Abbruch der Analyse lässt die Geschichte selbst unangetastet.

Hörbücher

Ein Dokument (oder eine Story) importieren; es wird in Kapitel, Blöcke und Runs zerlegt — ein Run ist ein Textstück, das von einer Stimme gesprochen wird. Erzähler zuweisen, einzelne Runs überschreiben, wo eine Figur spricht, und rendern.

Emotion

Jeder Run kann eine Emotion tragen. Wie sie beim Modell ankommt, hängt von der Engine ab: IndexTTS2 bekommt seine nativen Tags pro Zeile ([sad] vor jeder Zeile, weil es Emotion pro Satz anwendet), Qwen3-Stimmen bekommen sie in ihre gesprochene Anweisung eingearbeitet, und Engines ohne Emotionskanal bekommen einen Temperatur-Anstupser — das ist keine Emotionssteuerung, sondern der einzige verfügbare Hebel.

Effekte

Passagen können Hintergrundbetten und einzelne Effekte tragen. Der Mixer senkt das Bett unter der Sprache ab und gleicht die Lautheit an, damit ein Kapitel zwischen Passagen nicht in der Lautstärke springt.

Rendern und der Cache

Beim Rendern wird jeder Run vertont und anschließend das Kapitel gemischt. Vertonte Runs werden zwischengespeichert: ein unverändertes Kapitel erneut zu rendern dauert kaum, und wer eine Passage ändert, vertont nur diese neu. Ausgabe ist MP3 oder WAV pro Kapitel oder ein M4B mit Kapitelmarken fürs ganze Buch.

Stimmen

Audio → Voices. Eine Stimme ist eine Engine samt Einstellungen, unter einem Namen gespeichert und von jedem Hörbuch nutzbar.

Eine Stimme behalten

Eine beschreibungsgetriebene Engine erfindet bei jedem Render einen neuen Sprecher — dieselbe Beschreibung liefert nicht zweimal dieselbe Person. Also so lange probehören, bis eine gefällt, dann Keep this take: dieser Render wird zum Referenzclip der Stimme, und jede Passage wird damit gesprochen. Einen Seed festzunageln reicht dafür nicht; gemessen ergaben drei Renders mit demselben festen Seed drei verschiedene Stimmen.

Die eigene Stimme

Voice from a recording macht aus beliebigem Audio — im Browser aufgenommen, hochgeladen oder eine vorhandene Ausgabe — eine Klon-Stimme. Der Clip wird in den eigenen Speicher der Bibliothek kopiert, sodass das spätere Löschen der ursprünglichen Ausgabe die Stimme nicht kaputt macht.

Blueprints

Ein Blueprint ist ein gespeichertes Rezept. Dreiunddreißig sind dabei, beschriftet nach Art:

Erreichbar über die Schaltfläche Blueprints in der Kopfzeile der Galerie; eigene lassen sich aus jeder Ausgabe oder aus der Mehrfachauswahl speichern.

LoRAs

Die Schaltfläche LoRAs öffnet einen eingebauten CivitAI-Browser. Bereits vorhandene Einträge sind markiert, und Use now trägt eine LoRA in ein passendes Modell ein und wechselt dorthin.

Warum eine LoRA manchmal nicht nutzbar ist

LoRAs liegen pro Architektur unter loras/<arch>. Eine Datei, die bei einem anderen ausgewählten Modell geladen wurde, landet in dessen Ordner, wo sonst niemand nachsieht — installiert und unsichtbar zugleich. Zwei Dinge schützen vor der Verwirrung, die das früher stiftete:

• Eine LoRA, deren angegebenes Basismodell hier überhaupt kein Zuhause hat (ein SDXL-Adapter in einem Videostudio), wird vor dem Download markiert.
• Eine falsch abgelegte Datei lässt sich in den Ordner ihres Basismodells verschieben — im Browser oder über die API mit POST /loras/relocate.

Eine Generierung mit einer LoRA, die für das gewählte Modell nicht installiert ist, wird sofort abgelehnt, mitsamt Liste dessen, was tatsächlich installiert ist — statt dass die Generierung stillschweigend nichts produziert.

REST-API

Alles, was die Oberfläche tut, läuft über /api/v1. Die interaktive Dokumentation mit vollständigem Schema für alle 184 Endpunkte liefert die App selbst unter http://localhost:7861/docs; die kuratierte Referenz steht in docs/API.md.

# Generierung abschicken
curl -X POST http://localhost:7861/api/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"model_type":"t2v","prompt":"a lighthouse at dusk","video_length":81}'

# Status abfragen
curl http://localhost:7861/api/v1/status/<job_id>

# Ergebnis herunterladen
curl -O http://localhost:7861/api/v1/file/<dateiname>

MCP für Agenten

MuseForge spricht das Model Context Protocol über streamable HTTP unter /mcp, im selben Prozess wie die Oberfläche — kein zweiter Dienst. Sechsundsiebzig Werkzeuge decken Generierung, Jobs, Ausgaben, Geschichten, Hörbücher, Stimmen, LoRAs und Blueprints ab.

claude mcp add --transport http museforge http://localhost:7861/mcp

Oder in einer Konfiguration im mcp.json-Stil:

{
  "mcpServers": {
    "museforge": { "type": "http", "url": "http://localhost:7861/mcp" }
  }
}

MUSEFORGE_API_TOKEN setzen, um Authorization: Bearer <token> auf /mcp zu verlangen. Die REST-Aufrufe der Oberfläche bleiben tokenfrei.

Durchgespielte Beispiele

Dokument rein, Hörbuch raus

Vollständig über MCP, ohne Oberfläche:

1. upload_document — Datei übergeben.
2. audiobook_create, dann audiobook_import — Projekt und Text.
3. list_voices und audiobook_import_voice — Erzähler wählen.
4. audiobook_plan — prüfen, dass jeder Run eine Stimme hat.
5. audiobook_render — danach job_status abfragen.

Erst die Geschichte, dann vorlesen

story_start → story_status abfragen → audiobook_from_story, was die ersten beiden Schritte ersetzt.

Alles ohne eigenes Werkzeug

api_request("GET", "/openapi.json") liefert das vollständige Schema, und api_request kann jeden Endpunkt direkt aufrufen.

Speicher & Workspaces

Aller Zustand liegt in benannten Docker-Volumes, ein Neubau des Images rührt die Daten also nicht an:

Workspaces unterteilen outputs pro Projekt und werden in der Kopfzeile der Galerie gewechselt. default ist der Ausgabeordner selbst und nicht löschbar.

Aktualisieren

git pull
docker compose up -d --build

Ein Upstream-Release von Maestro holt man per Merge — MuseForge hat echte Git-Abstammung mit upstream, das ist also ein gewöhnlicher Drei-Wege-Merge:

git remote add upstream https://github.com/Blizaine/Maestro.git   # einmalig
git fetch upstream && git merge upstream/main

Die Datei VERSION hält fest, auf welchem Upstream-Release die Engine steht.

Erreichbarkeit & Sicherheit

• Nur auf Loopback binden, indem das Port-Mapping auf 127.0.0.1:7861:7860 geändert wird.
• MUSEFORGE_API_TOKEN setzen, wenn Agenten /mcp von außerhalb erreichen.
• Einen Reverse Proxy mit echter Authentifizierung davorsetzen, bevor die Instanz in einem nicht kontrollierten Netz erreichbar wird.

Fehlerbehebung

Eine Generierung endet ohne Datei

Die Meldung auf der Job-Kachel lesen — Fehlschläge nennen inzwischen den Grund. Häufigste Ursache war früher eine LoRA, die sich nicht laden ließ; das wird jetzt vorab abgelehnt, unter Nennung der Datei und dessen, was stattdessen installiert ist.

Meine geladene LoRA erscheint nicht unter Advanced

Sie liegt im Ordner einer anderen Architektur. Im LoRA-Browser unter den installierten Einträgen suchen und verschieben. Siehe LoRAs.

Ein MCP-Aufruf läuft in einen Timeout

Zuerst die Adresse prüfen: Sie muss die sein, unter der die Oberfläche antwortet, plus /mcp. Die Instanz selbst fragen mit GET /api/v1/mcp/info.

Eine Geschichte steht auf „crashed"

Der Prozess ist mitten im Lauf verschwunden — ein Neustart oder ein Speicher-Abbruch. Die Meldung nennt die Phase, aus der er nicht zurückkam. Fertige Kapitel bleiben erhalten, Extend setzt beim letzten fort.

Etwas läuft und soll aufhören

Der Aktivitätsbereich unten links listet jeden laufenden Vorgang — Generierungen, Story-Durchläufe und Modell-Downloads — jeweils mit Stopp-Schaltfläche.

VRAM reicht nicht

Auflösung oder Sliding-Window-Größe senken oder eine kleinere Modellvariante wählen. Die Auto-Tune-Funktion vermisst die GPU beim ersten Start und wählt Offload- und Quantisierungseinstellungen; Karten mit wenig VRAM funktionieren, nur langsam.