# Time4Midi

<p align="center">
  <img src="./time4midi.png" alt="Time4Midi Logo" width="220">
</p>

<p align="center">
  Desktop-Timeline fuer Show-Control, MIDI, DMX, Audio und technische Automationen.
</p>

<p align="center">
  <img src="./JHArtworks2023_wh.png" alt="J.H. Artworks" width="180">
</p>

## Was ist Time4Midi?

Time4Midi ist eine Electron-Desktop-App fuer zeitbasierte Show-Automation. Du legst Punkte auf einer Timeline an und steuerst damit je nach Track-Typ zum Beispiel:

- MIDI Notes und MIDI CC
- Art-Net und sACN / E1.31
- OSC
- MQTT
- Serial
- Modbus TCP / RTU
- KNX
- Audio-Tracks mit Waveform, Beat-Raster und Fade-Automation

Die App ist darauf ausgelegt, waehrend einer Show schnell lesbar zu bleiben: links Projekt und Tracks, in der Mitte die Timeline, rechts der Inspector fuer den aktuell gewaehlten Track oder Punkt.

## Auf einen Blick

- Mehrere Timelines pro Projekt
- Freie Timeline-Laenge bis 24 Stunden
- Zoomen mit `Strg + Mausrad`
- Horizontal scrollen mit dem Mausrad
- Auto-Follow des Timecursors beim Abspielen
- Audio-Waveform mit Beat-, Takt- und Drop-Markern
- Beat-Snap fuer Punkte auf anderen Tracks
- gelbe Snap-Linien ueber alle Tracks mit einstellbarer Staerke
- Diagnosefenster fuer Art-Net, sACN, MQTT und KNX
- Mapping-Bibliotheken fuer wiederverwendbare Zieldefinitionen
- Splashscreen beim Start mit Logo und Ladebalken
- Speichern und Laden als JSON-Projektdatei

## Bedienkonzept

```mermaid
flowchart LR
  A["Projekt anlegen"] --> B["Timeline waehlen"]
  B --> C["Tracks hinzufuegen"]
  C --> D["Punkte setzen oder Audio laden"]
  D --> E["Ausgaenge konfigurieren"]
  E --> F["Play / Timecode / Diagnose"]
```

## Aufbau der Oberflaeche

```mermaid
flowchart TB
  A["Sidebar<br/>Projekt, Timelines, Tracks"] --> B["Editor<br/>Timeline, Zoom, Scroll, Playhead"]
  B --> C["Inspector<br/>Track- und Punktparameter"]
  B --> D["Transportleiste<br/>Play, Sync, Timeline-Laenge, Beat-Snap"]
  D --> E["Diagnosefenster<br/>Live-Werte fuer Netzwerk-Outputs"]
```

## Wichtige Features im Detail

### 1. Timeline und Keyframes

- Punkte lassen sich per Doppelklick setzen.
- Punkte koennen mit der Maus verschoben werden.
- Je nach Track-Typ stehen `Hold` oder `Linear` als Interpolation zur Verfuegung.
- Die Timeline-Laenge kann direkt oben in der Transportleiste eingestellt werden.

### 2. Audio-Analyse

Audio-Tracks koennen mehr als nur abspielen:

- Waveform wird direkt in der Timeline angezeigt
- erkannte Beats werden als feine Marker eingezeichnet
- erkannte Taktanfange werden hervorgehoben
- erkannte Drops werden markiert
- Audio-Clips koennen auf der Timeline nach links und rechts verschoben werden
- Fade-Punkte im Audiotrack steuern den Gain ueber die Zeit
- das aktuell gewaehlte Snap-Muster wird als gelbes Raster sichtbar

Hinweis:
Wenn ein geladenes Audio laenger ist als die aktuelle Timeline, wird die Timeline automatisch verlaengert. Ist die Timeline schon laenger als das Audio, bleibt sie unveraendert.

### 3. Beat-Snap

Wenn ein Audiotrack analysiert wurde, kann dessen Beat-Raster als Fangnetz fuer andere Tracks dienen.

- `Beat Snap` aktivieren
- `Snap Raster` waehlen
- Punkte auf MIDI-, DMX-, OSC-, MQTT- oder anderen Tracks setzen oder ziehen
- Punkte rasten auf das Audio-Raster ein

Verfuegbare Raster:

- `1/4 Beat`
- `1/2 Beat`
- `1 Beat`
- `2 Beats`
- `1 Takt`
- `2 Takte`

Damit kannst du z. B. in einem 4/4-Track nur jeden zweiten Takt oder eben halbe Beats als Raster verwenden.

Zusaetzlich:

- das aktive Snap-Muster wird als gelbe Linien in der Timeline gespiegelt
- die Linienstaerke kann direkt oben in der Transportleiste eingestellt werden
- Punkte lassen sich trotz Snap weiter sauber ziehen und springen stabil Raster fuer Raster

### 4. Diagnosefenster

Das Diagnosefenster ist gedacht, damit du waehrend einer laufenden Show sehen kannst, was wirklich rausgeht.

Aktuell enthalten:

- Art-Net Universe + aktive Kanaele
- sACN Universe + aktive Kanaele
- MQTT Topics + letzter gesendeter Wert
- KNX Gruppenadresse + letzter gesendeter Wert
- Verlauf der letzten Events

### 5. Mapping-Bibliotheken

Mappings koennen projektunabhaengig gespeichert werden. Damit kannst du technische Ziele mit sprechenden Namen versehen, zum Beispiel:

- `MIDI Note 1 = Strobe`
- `Art-Net Universe 4 / Channel 7 = Shutter`
- `KNX 1/2/20 = Preset Licht`

Diese Bibliotheken lassen sich in den Einstellungen pro Treiber pflegen, speichern und laden.

## Unterstuetzte Sync-Quellen

- Internal
- MIDI Timecode `MTC`
- Art-Net Timecode

## Unterstuetzte Track-Typen

| Bereich | Track-Typen |
| --- | --- |
| MIDI | Note, CC |
| DMX | Art-Net Channel, sACN Channel |
| Netzwerk | OSC, MQTT |
| Feldbus / Technik | KNX, Modbus TCP, Modbus RTU |
| Serielle Ausgaben | Serial |
| Media | Audio File |

## Quick Start

### Voraussetzungen

- Node.js
- npm
- Windows fuer den Portable-Build

### Entwicklung starten

```bash
npm install
npm start
```

Unter Windows kannst du alternativ auch `start-time4midi.cmd` benutzen.

### Windows Portable Build

```bash
npm run dist:win
```

## Schritt-fuer-Schritt Anleitung

### Ein erstes Projekt anlegen

1. App starten.
2. Ein neues Projekt anlegen.
3. Eine Timeline waehlen oder eine neue erzeugen.
4. Oben die gewuenschte Timeline-Laenge eintragen.
5. Die benoetigten Tracks links hinzufuegen.

### MIDI oder DMX programmieren

1. Einen passenden Track hinzufuegen.
2. Rechts im Inspector Ziel, Kanal, Universe oder Adresse setzen.
3. Punkte per Doppelklick in die Timeline setzen.
4. Werte und Interpolation im Inspector feinjustieren.

### Audio laden und als Raster nutzen

1. Einen `Audio`-Track anlegen.
2. Eine Datei waehlen.
3. Warten, bis Waveform und Analyse erscheinen.
4. Falls gewuenscht `Beat Snap` aktivieren.
5. Das `Snap Raster` waehlen.
6. Optional die Staerke der gelben Snap-Linien einstellen.
7. Punkte auf anderen Tracks setzen oder verschieben.

### Audio-Fades zeichnen

1. Den Audio-Track auswaehlen.
2. Per Doppelklick direkt im Audiotrack Fade-Punkte setzen.
3. Punkte ziehen, um Zeit und Gain zu aendern.
4. Im Inspector `Zeit im Clip`, `Gain` und Interpolation anpassen.

### Tastatursteuerung fuer Snap

Wenn ein Punkt markiert ist:

1. `Pfeil links` springt zum vorherigen Beat bzw. Takt des aktiven Snap-Rasters.
2. `Pfeil rechts` springt zum naechsten Beat bzw. Takt.
3. `Strg + Pfeil links/rechts` springt um 4 Takte zurueck oder vor.
4. `Bild auf / Bild ab` scrollt horizontal durch die Timeline.

### Netzwerk-Ausgaenge pruefen

1. Transport starten.
2. `Diagnose` oeffnen.
3. Live beobachten, welche Werte auf welchen Universes, Kanaelen oder Topics ankommen.

## Projektdateien

Time4Midi speichert Projekte als JSON. Darin enthalten sind unter anderem:

- Projektname
- Timelines
- Tracks
- Punkte / Automation
- Routing
- ausgewaehlte Sync-Quelle

Mapping-Bibliotheken werden getrennt vom Projekt gespeichert und koennen in mehreren Projekten wiederverwendet werden.

## Dateien im Projekt

| Datei / Ordner | Bedeutung |
| --- | --- |
| `main.js` | Electron Main Process |
| `preload.js` | Bridge zwischen Renderer und Node / Treibern |
| `src/app.js` | Hauptlogik der App |
| `src/index.html` | Hauptfenster |
| `src/diagnostics.html` | Diagnosefenster |
| `src/splash.html` | Start-Splashscreen |
| `time4midi.png` | App-Logo |
| `JHArtworks2023_wh.png` | Brand-Logo |

## Status

Aktueller Paketstand laut `package.json`:

- Version `0.3.3`

Bereits integriert:

- Art-Net
- sACN
- KNX
- MQTT
- OSC
- Audio-Waveform und Beat-Snap
- gelbe Snap-Linien mit einstellbarer Staerke
- Tastatursteuerung fuer Snap-Punkte
- Diagnosefenster
- Splashscreen

## Roadmap / Ideen

- noch praezisere Beat- und Drop-Erkennung
- manuelle Wahl der Snap-Quelle bei mehreren Audio-Tracks
- mehr Audio-Effekte direkt in der Timeline
- Undo / Redo
- Copy / Paste fuer Punkte und Tracks
- Loop-Bereiche und Cue-Strukturen
- bessere Paketierung fuer Release-Builds

## Credits

Entwickelt von `J.H. Artworks`.