# Cubase-Steuerung im Narrava Regie Assistenten

Stand: 16. Oktober 2026. Version 0.5.1. Die Abnahme mit echtem Cubase bleibt ausstehend; siehe Grenzen unten.

## Schnellstart in der App

1. In der Cubase-Leiste **Cubase einrichten / Verbindung prüfen** öffnen. Die App
   zeigt gefundene Cubase-Installationen, Windows-Version, tatsächliche MIDI-Ports
   und den Skriptzustand. Eine gefundene Installation ist noch keine Praxisabnahme.
2. Falls die beiden Ports fehlen: eine für deinen Einsatz freigegebene virtuelle
   MIDI-Anwendung installieren und starten. Über **loopMIDI-Anbieterseite öffnen**
   erreichst du die offizielle Bezugsquelle. Bei loopMIDI unter **New port-name**
   nacheinander `Narrava To Cubase` und `Narrava From Cubase` eintragen, jeweils
   **+** drücken. Anwendung weiterlaufen lassen; optional deren Autostart nutzen.
   Installation kann Windows-Administratorbestätigung benötigen. Narrava installiert
   keinen Treiber und übernimmt keine Anbieter-Lizenzfreigabe.
3. **Erneut prüfen** wählen. Beide Namen müssen genau einmal in ihrer benötigten
   Richtung erscheinen. Falsche oder doppelte Namen in der MIDI-Anwendung korrigieren.
4. **Skript installieren / aktualisieren…** wählen und den angezeigten Dateipfad
   bestätigen. Narrava verwendet den tatsächlichen Windows-Dokumenteordner,
   sichert bestehende Bytes, tauscht nur seine eigene Datei aus und prüft SHA-256.
   Ein passendes 0.5.0-CC-Skript bleibt protokollkompatibel; alte SysEx-Skripte nicht.
5. In Cubase MIDI Remote öffnen, Skripte neu laden oder Cubase neu starten.
   **Narrava / RegieAssistent → Narrava Transport** aktivieren. Eingang =
   `Narrava To Cubase`, Ausgang = `Narrava From Cubase`. Unter Studio →
   Studio-Einstellungen → MIDI-Anschluss-Einstellungen diese Ports aus **All MIDI
   Inputs** ausschließen. Bestehendes Instrumentenrouting nicht ersetzen.
6. **Verbinden** wählen. Erst die vollständige Antwort von Cubase schaltet die
   Transporttasten frei. Bei Fehlern zeigt die Leiste den nächsten Prüfschritt.

### Update und Rückweg

Das App-Update schreibt nicht ungefragt in den Cubase-Ordner. Der Einrichtungsdialog
unterscheidet fehlende, passende, bekannte 0.5.0-, SysEx- und abweichende Skripte.
Abweichende Dateien nur nach bewusster Prüfung ersetzen. **Letzte Installation
rückgängig…** stellt die vorherigen Bytes wieder her; nach einer Erstinstallation
entfernt es nur die neu angelegte Datei. Zwischenzeitliche Änderungen blockieren
den Rückweg, damit sie nicht überschrieben werden. Danach Cubase-Skripte neu laden.
Sicherungen und Wiederherstellungsjournale liegen außerhalb des Cubase-Skriptbaums
unter `%APPDATA%/narrava-regie-assistent/cubase-script-backups/`. Auch bei einem
Schreibfehler bleiben angelegte Sicherungen erhalten. Gesperrte oder über symbolische
Verknüpfungen laufende Pfade werden nicht automatisch verändert; die App meldet dies.

### Windows-MIDI-Alternative und Lizenzgrenzen

Microsoft Windows MIDI Services unterstützt Loopbacks. Die aktuell dokumentierte
komfortable [Windows MIDI Loopback Setup](https://microsoft.github.io/MIDI/tools/midiloopbacksetup/)
Oberfläche ist jedoch als Entwicklerangebot mit Consumer-Veröffentlichung Q1 2027
gekennzeichnet. Ein laufender Dienst allein beweist weder verfügbare Einrichtungstools
noch passende WinMM-Ports. Narrava installiert keine Vorschaukomponenten. Vorhandene
freigegebene MIDI-1.0-Basic-Loopbacks können mit den beiden exakten Namen geprüft
werden; MIDI-2.0-A/B-Paare sind wegen anderer Richtungssemantik kein ungeprüfter Ersatz.

Der [loopMIDI-Anbieter](https://www.tobias-erichsen.de/software.html) nennt kostenlose
private, nicht kommerzielle Nutzung; berufliche Nutzung muss mit dem Anbieter geklärt
sein. Sein [virtualMIDI-SDK](https://www.tobias-erichsen.de/software/virtualmidi/virtualmidi-sdk.html)
darf ohne vorherige Freigabe nicht verteilt werden und enthält selbst keinen Treiber.
Deshalb liegt kein solcher Treiber/SDK in Narrava und es wird keiner still installiert.

English: Open **Set up Cubase / check connection** in the toolbar. Its four steps
are fully translated: check Cubase, create the two named virtual cables, install
the script with a backup, then assign the input/output in Cubase and connect.
The installer does not install a MIDI driver. Script rollback is available in the
same panel. Recording status is host transport feedback, not proof of an audio file.

## Bedienung

Die Desktop-App zeigt die Cubase-Leiste im Arbeitsbereich und im Teleprompter. Mit **Verbinden** werden ausschließlich die unten genannten MIDI-Ports geöffnet. **Wiedergabe**, **Stopp** und **Aufnahme** steuern Cubases Transport. Aufnahme ist ein Startbefehl, kein Umschalter; zum Beenden **Stopp** verwenden. Die Anzeige zeigt Cubases Transport-Aufnahmestatus, keine Bestätigung, dass auf einer bestimmten Spur eine Audiodatei geschrieben wird. Spuren, Eingänge, Aufnahmebereitschaft und Projekt müssen in Cubase eingerichtet sein.

Die Tasten ändern den angezeigten Transportzustand nicht selbst. Erst die Rückmeldung von Cubase setzt „Aufnahme“, „Wiedergabe“ oder „Gestoppt“. Ein offener MIDI-Port genügt nicht. Ohne vollständige Rückmeldung bleibt der Zustand unbekannt und die Transporttasten sind gesperrt.

Nach ungefähr drei Sekunden ohne gültige vollständige Antwort (Prüfraster 750 ms, maximal etwa 3,75 s) werden die Ports geschlossen, der bisherige Status gelöscht und „Verbindung verloren“ angezeigt. Ports oder Cubase wiederherstellen und **Neu verbinden** wählen. Es gibt keine automatische Wiederholung oder Warteschlange für Transportbefehle. **Trennen**, Leser schließen oder die App beenden sendet keinen Stopp an Cubase. Die Verbindung gehört der App und bleibt beim Wechsel ihrer Arbeitsbereiche erhalten.

Der Teleprompter läuft bei Fokusverlust weiter. Seine Start-/Pause-Taste, Leertaste, Anfang/Home, manuelles Blättern und das Textende behalten ihre Funktion. Vollbild- und bewusste Layoutwechsel pausieren weiterhin; danach bewusst wieder starten. Beim Schließen werden Animations- und Speichertimer bereinigt. Die Desktop-App deaktiviert Chromium-Hintergrunddrosselung für das Leserfenster. Browser-Tabs außerhalb der Desktop-App können weiterhin vom Browser gedrosselt werden.

## Voraussetzungen und Versionsgrenzen

Steinberg führt MIDI Remote API 1.0 ab Cubase/Nuendo 12.0.0, 1.1 ab 13.0.0, 1.2 ab 13.0.50 und 1.3 ab 15.0.20 auf. Dieses Skript verwendet die Basis-API `midiremote_api_v1`, Transport-Value-Bindings und CC-Anfragen. Es braucht keine Idle-Callbacks (erst API 1.1), kein DirectAccess und keine API-1.3-Funktionen. Die optionale Versionsabfrage aus API 1.2 wird auf Vorhandensein geprüft.

**API-Kompatibilitätsziel ist Cubase 12 oder neuer mit MIDI-Remote-Scripting. Keine konkrete Cubase-Version/Edition ist hier praktisch zertifiziert.** Die genaue Kundenversion und Edition sind noch unbekannt. Auf älteren Hosts ohne Versionsabfrage die Version unter „Über Cubase“ erfassen. Es gibt keine VST3-Komponente und keine Einbettung des Cubase-Fensters.

Unter Windows wird ein bereits eingerichteter virtueller MIDI-Transport benötigt. Ein praktischer Kandidat ist **loopMIDI**: zwei getrennte virtuelle Loopback-Kabel. Der Anbieter beschreibt Windows 7–10; die Eignung auf dem konkreten Kundenbetriebssystem, insbesondere Windows 11, muss geprüft werden. Installation, Lizenzbedingungen und Betrieb bleiben eine separate Entscheidung. Diese Änderung installiert oder startet keinen Systemtreiber. RtMidi kann unter Windows selbst keine virtuellen Ports anlegen.

## Einmalige Einrichtung durch den Betreiber

1. Cubase-Version/Edition feststellen und MIDI Remote öffnen. In einer bereits freigegebenen virtuellen MIDI-Anwendung zwei Ports mit exakt diesen Namen anlegen und die Anwendung laufen lassen:
   - `Narrava To Cubase`
   - `Narrava From Cubase`
2. Das mitgelieferte Verzeichnis `desktop/midi-remote/Narrava` unter den Cubase-Benutzerordner kopieren. Die vollständige Skriptdatei muss unter folgendem Pfad liegen (bei umgeleitetem Dokumente-Ordner den tatsächlichen Pfad verwenden):

   ```text
   <Dokumente>\Steinberg\Cubase\MIDI Remote\Driver Scripts\Local\Narrava\RegieAssistent\Narrava_RegieAssistent.js
   ```

3. In Cubase die MIDI-Remote-Skripte neu laden beziehungsweise Cubase neu starten. Das Gerät **Narrava / RegieAssistent** und die Seite **Narrava Transport** verwenden. Portzuordnung:

   | Richtung | Regie Assistent | Cubase |
   |---|---|---|
   | Befehle/Statusanfrage | Ausgang `Narrava To Cubase` | Eingang `Narrava To Cubase` |
   | Statusantwort | Eingang `Narrava From Cubase` | Ausgang `Narrava From Cubase` |

4. Die virtuellen Ports aus Cubases „All MIDI Inputs“ ausschließen und keiner Instrumentenspur oder weiteren Remote-Zuordnung zuweisen. Keine Verbindung zwischen den beiden virtuellen Kabeln zusätzlich routen. Jede Richtung braucht genau einen eindeutig benannten Port.
5. Im Regie Assistenten **Verbinden** anklicken. Erst wenn Cubase den vollständigen Transportstatus zurückmeldet, werden die Tasten bedienbar. Die Verbindungshilfe zeigt eine vom Host gelieferte Versionsnummer, sofern verfügbar.
6. Den folgenden Abnahmetest in einem ausdrücklich dafür vorgesehenen Cubase-Testprojekt ausführen. Keine laufende Produktion dafür verwenden.

## Offene Abnahme mit echtem Cubase

- Exakte Version, Edition, Windows-Version, virtuellen MIDI-Treiber und dessen Version festhalten.
- App vor/nach Cubase starten: korrekter Anfangsstatus ohne vorherigen Transport-Tastendruck. Auch verbinden, während Cubase bereits aufnimmt.
- In Narrava Wiedergabe, Aufnahme und Stopp betätigen; Cubase muss die Aktion ausführen. Wiederholtes Play darf nicht stoppen, wiederholtes Record nicht umschalten.
- In **Cubase selbst** per Maus/Tastatur Wiedergabe/Aufnahme/Stopp auslösen; Narrava muss unabhängig von seinen Tasten folgen. Abgelehnte Aufnahme, fehlende Aufnahmebereitschaft, Vorzähler, Punch-in/out und Projektwechsel prüfen. Die UI ist eine Transportanzeige, kein Audiosignalnachweis.
- Cubase beenden, Skript deaktivieren und jeweils ein virtuelles Kabel unterbrechen. Nach dem Timeout muss jede alte Aufnahme-Anzeige verschwinden. Nach Wiederherstellung neu verbinden: nur aktueller Status, kein nachgeholter Befehl.
- Bei laufendem Teleprompter tatsächlich zu Cubase und einer anderen Windows-App wechseln. Scrollen muss kontinuierlich fortschreiten; explizite Pause muss pausiert bleiben. Vollbild hinein/heraus, minimiert/wiederhergestellt und mehrere Leser-/Kapitelwechsel prüfen.

## Technischer Vertrag und Prüfungen

Renderer → isolierter Preload → geprüfte Electron-IPC-Aufrufe → Main-Prozess → `@julusian/midi` 3.8.1 (RtMidi/WinMM) → virtuelle Kabel → Cubase MIDI Remote. Sandbox und Context Isolation bleiben eingeschaltet; Node-Integration bleibt aus. Es gibt keine generischen IPC-, Dateisystem-, MIDI-Byte- oder Portauswahlfunktionen im Renderer. Der Main-Prozess prüft WebContents, Hauptframe, exakten lokalen Origin, erlaubte Befehle und Argumentanzahl. Maximale Befehlsrate: ein Befehl je 150 ms. Keine neuen HTTP-Steuerendpunkte.

Kanal 16: CC80 = Play, CC81 = Stop, CC82 = Record, jeweils 127/0. Das Cubase-Value-Binding filtert auf den gedrückten Wert 1; Release setzt den Hostwert nicht auf 0. Status kommt ausschließlich aus `mTransport.mValue.mStart/mStop/mRecord.mOnProcessValueChange`, nicht aus Surface- oder Button-Callbacks. Werte liegen pro aktivem Gerät vor und werden bei Deaktivierung ungültig.

Alle 750 ms sendet Narrava auf Kanal 16 vier 7-Bit-Zufallswerte auf CC90–93; ein wechselnder Wert 127/0 auf CC94 fordert die Antwort an. Diese fünf Custom-Surface-Werte steuern keine Hostfunktion. Die Antwort ist eine geordnete CC-Folge: CC100=2 (Protokollversion), CC101–104=Nonce, CC105=Gültigkeitsmaske, CC106/107/108=Play/Stop/Record, CC109=Versionsstringlänge, wiederholtes CC110=ASCII-Zeichen, CC111=2 (Ende). Eine Antwort muss binnen 500 ms vollständig sein und zu einer höchstens zwei Sekunden alten offenen Anfrage passen. Nur Maske 7 und drei bekannte Hostwerte verbinden. Fremde, falsche, wiederholte oder alte Antworten und Kabel-Echos werden verworfen. Es werden keine SysEx-Nachrichten oder MIDI-Herstellerkennungen verwendet. Dies ist keine kryptografische Authentisierung gegen lokale Software, die dieselben MIDI-Kabel kontrolliert.

**App und MIDI-Remote-Skript aus Version 0.5.1 verwenden; das veröffentlichte 0.5.0-CC-Skript bleibt kompatibel.** Das frühere interne Entwicklungsskript mit SysEx ist nicht kompatibel. Installationspfad des Skripts: resources/app/desktop/midi-remote/Narrava/RegieAssistent/Narrava_RegieAssistent.js. Diese Anleitung liegt unter resources/app/docs/CUBASE.md.

```powershell
npm ci
npm test
npm run test:cubase
npm run build
npm run test:desktop
npm run test:focus
```

`test:focus` benötigt die bereits vorhandene Playwright-Laufzeit am in den bisherigen QA-Skripten verwendeten Codex-Pfad und installiertes Edge. Es arbeitet ausschließlich headless mit synthetischem Text. Der native Windows-Wechsel zu Cubase wird dadurch nicht behauptet. `test:desktop` benutzt ein temporäres Profil und ein verstecktes Electron-Fenster. Die Cubase-Skripttests emulieren den API-Vertrag; sie ersetzen keinen Cubase-Test. Die oben dokumentierten Tests ersetzen keine Abnahme mit echtem Cubase.

## Primärquellen

- [Steinberg API-Referenz](https://steinbergmedia.github.io/midiremote_api_doc/codedoc_api_reference/) – Transportwerte, Host-Callbacks, ValueBinding und MIDI-SysEx.
- [Steinberg Versionen](https://steinbergmedia.github.io/midiremote_api_doc/versions/) und [API 1.2](https://steinbergmedia.github.io/midiremote_api_doc/new_in_v1.2/) – Versionsgrenzen und optionale Hostversionsabfrage.
- [Steinberg Einrichtung](https://steinbergmedia.github.io/midiremote_api_doc/getting-started/) – Benutzerpfad und Skripte neu laden.
- [loopMIDI-Anbieter](https://www.tobias-erichsen.de/software/loopmidi.html) – virtuelle Kabel und Lebensdauer der Ports.
- [RtMidi-Node-Adapter](https://github.com/Julusian/node-midi) – Windows-Backend, vorkompilierte Module und virtuelle Portgrenzen.
- [Electron BrowserWindow](https://www.electronjs.org/docs/latest/api/browser-window#page-visibility) – Hintergrunddrosselung und Sichtbarkeit.
