geograsim/App/sims/heli/docs/konzept-audio-schnitt-tool.md

Audio-Schnitt-Tool — Konzept

Stand: 2026-06-01 · Atlas · Status: zum Review · KEIN CODE BIS THOMAS-OK

Zweck

Tool-Seite (eigene URL, nicht Spiel) zum Schneiden, Anordnen und Speichern der Audio-Timeline pro Mission. Wie Cubase/DaVinci, aber speziell für unsere Heli-Missionen. Was im Tool definiert ist, spielt das Spiel deterministisch ab (Tool = Wahrheit, Engine folgt).

Grundprinzipien

1. Eine Timeline pro Mission — horizontale Zeitachse, links→rechts, scrollbar, zoombar
2. Pro Audio = ein Balken auf der Timeline. Balken-Länge = echte MP3-Dauer (gemessen, gecacht). Verschieben per Drag&Drop.
3. Niemals zwei Audios gleichzeitig — Tool verhindert visuell und logisch Überlappungen
4. Strecken sind variabel — die Karten-Animations-Dauer im Spiel passt sich der Audio-Inhalts-Länge an, nicht umgekehrt. Lange Inhalte = langsamerer Flug zwischen den Wegpunkten.
5. Phase-Gating im Spiel: der nächste Wegpunkt wird erst sichtbar, wenn das aktuelle Audio fertig ist. Klick vorab erlaubt, Audio läuft trotzdem.

Tool-UI

┌──────────────────────────────────────────────────────────────────────┐
│ ← M1 Damüls      M2 ▶          [M1] [M2] [M3] ... [M25]              │  ← Mission-Switcher
├──────────────────────────────────────────────────────────────────────┤
│  PLAN ▏              FLUG                ▏ Abflug | Landung | Ende   │  ← Phasen-Track
│  ─────────────────────────────────────────────────────────────────   │
│ 0:00         0:30         1:00         1:30         2:00         2:30│  ← Zeitachse (sec)
│  ╿                                                                   │
│  ▌▌r_mission_intro_m1 (12s)     ▌▌r_wp_geo_thueringen (7s)           │  ← Audio-Track
│                              ▌▌r_wp_geo_zwischenwasser (8s)          │
│                                                  ▌▌r_wp_geo_damuels  │
│  ─────────────────────────────────────────────────────────────────   │
│ 🚩Plan-Start  🟢WP1 thueringen  🟢WP2 zwischenwasser  🟢WP3 damuels  │  ← Event-Marker
│                                                                      │
│  ┌─ Audio-Pool ────────────────────────────────────────────────┐    │  ← Audio-Pool unten,
│  │ 🔊 r_mission_intro_m1   12s  Sarah/Tower                    │    │     Drag→Timeline
│  │ 🔊 r_wp_geo_thueringen   7s  Briefing                       │    │
│  │ 🔊 r_wp_geo_zwischenwasser  ... [Filter: alle / verwendet] │    │
│  └────────────────────────────────────────────────────────────┘    │
│                                                                      │
│ [💾 Speichern] [▶ Vorschau abspielen] [↩ Reset auf Default]          │  ← Aktionen
└──────────────────────────────────────────────────────────────────────┘

UI-Details

• Mission-Switcher oben: vor/zurück (Pfeile) + alle 25 Missionen als Tabs/Dropdown
• Phasen-Track zeigt Phasen-Sektionen (Plan, Flug, Abflug, Landung, Ende) in unterschiedlichen Farben/Schraffuren
• Zeitachse in Sekunden, zoombar via Mausrad/Buttons (z. B. 1 px = 0,1 s, 0,2 s, 0,5 s, 1 s …)
• Audio-Track zeigt Audio-Balken — Länge proportional zur Dauer. Klick auf Balken → markiert + zeigt Audio-ID + Text + Aktionen (löschen, verschieben, „Inhalt prüfen"). Drag verschiebt.
• Event-Marker als vertikale Linien mit kleinem Label (Wegpunkt erreicht, Phase-Wechsel, etc.). Werden teils automatisch gesetzt (z. B. pro Wegpunkt aus mission.waypoints), teils manuell.
• Audio-Pool unten als Liste/Tabelle mit Such-/Filterfunktion. Drag auf Timeline → fügt Balken hinzu. Audios die schon platziert sind, sind im Pool ausgegraut.
• Speichern → POST an PHP-Endpoint → schreibt audio-timeline-m1.json ins Verzeichnis
• Vorschau → spielt die Timeline im Browser ab (sequenziell, mit Events als Subtitel-Anzeige)
• Reset → lädt Default-Timeline aus dem Regelwerk (für leere Missionen)

Sequenz-Garantie (Tool-Verhalten)

Wenn der User einen Balken so verschiebt, dass er einen anderen überlappt:

• Tool springt automatisch hinter den vorherigen Balken (+ konfigurierbarer Gap, z. B. 0,5 s)
• Visuelles Feedback (rote Outline beim Drag wenn Überlappung droht, snappt dann ein)

Datenmodell

Pro Mission: App/sims/heli/data/audio-timeline-<mid>.json

{
  "_doc": "Audio-Timeline fuer M1 Damüls. Wird von /heli-audio-editor gespeichert + vom Spiel deterministisch abgespielt.",
  "missionId": "m1",
  "version": 1,
  "lastSaved": "2026-06-01T10:30:00",
  "gap": 0.5,
  "phases": [
    {
      "id": "plan",
      "label": "Routenplanung",
      "color": "#4a7c8a",
      "events": [
        { "id": "ev-plan-start", "t": 0, "label": "Plan-Start" },
        { "id": "ev-wp1", "t": 14, "label": "Wegpunkt sichtbar: thueringen", "waypoint": "thueringen" },
        { "id": "ev-wp2", "t": 22, "label": "Wegpunkt sichtbar: zwischenwasser", "waypoint": "zwischenwasser" },
        ...
        { "id": "ev-plan-end", "t": 65, "label": "Plan fertig" }
      ],
      "audios": [
        { "id": "a1", "audioId": "r_mission_intro_m1", "t": 0,  "dur": 12.3 },
        { "id": "a2", "audioId": "r_wp_geo_thueringen", "t": 14, "dur": 7.1 },
        { "id": "a3", "audioId": "r_nav_plan_correct", "t": 22, "dur": 3.2 },
        { "id": "a4", "audioId": "r_wp_geo_zwischenwasser", "t": 26, "dur": 8.5 },
        ...
        { "id": "aN", "audioId": "r_nav_plan_done", "t": 60, "dur": 5.0 }
      ]
    },
    {
      "id": "flug",
      "label": "Kartenflug",
      "color": "#5a8a5e",
      "events": [ ... ],
      "audios": [ ... ]
    }
  ],
  "_notes": "Editor erlaubt nur Plan + Flug. Abflug + Landung werden vom alten Engine-Pfad gespielt (separate Phase-Markierung im Tool als grauer Block, nicht editierbar)."
}

Audio-Dauer-Cache: App/sims/heli/data/audio-durations.json

{
  "_doc": "Audio-Dauern in Sekunden. Tool laedt MP3s clientseitig und liest <audio>.duration. Bei neuen Files automatisch nachpflegen.",
  "lastUpdated": "2026-06-01T10:30:00",
  "durations": {
    "r_mission_intro_m1": 12.3,
    "r_nachtrag_a": 2.1,
    "r_wp_geo_thueringen": 7.1,
    ...
  }
}

Beim ersten Tool-Aufruf: für jeden Audio-Eintrag in audio-texts.json, der noch nicht im Cache ist, MP3 via <audio>-Element laden + duration abfragen + cachen. Cache wird beim Save aktualisiert.

PHP-Save-Endpoint

App/php/api/heli-timeline.php:

• POST /api/heli-timeline?mission=m1 → body JSON → schreibt in data/audio-timeline-m1.json (+Backup)
• GET /api/heli-timeline?mission=m1 → liest Datei zurück
• POST /api/heli-audio-durations → schreibt/updated data/audio-durations.json

Sicherheit: nur internes Tool, kein Auth. (Wenn Production: hinter Lehrer-Login.)

Spiel-Integration (Engine-Refactor)

Heute (chaotisch)

• Plan-Audios werden in 4-5 verschiedenen Code-Stellen getriggert (initPlanPhase, showPlanInstruction, onPlanClick, …)
• Race-Conditions möglich (Mission-Intro + WP-Geo gleichzeitig)
• V1-Whitelist filtert teilweise

Neu (Timeline-getrieben)

audio-engine.js (neue zentrale Datei):

• Lädt beim Mission-Start audio-timeline-<mid>.json
• Pro Phase eine State-Machine:
  • phaseStart(phaseId) → spielt das erste Audio der Phase
  • audioEnded() → fires event bei t = ende-des-Audios, schaltet nächsten Wegpunkt frei, spielt nächstes Audio
• Game wartet auf Audio-Ende bevor nächster Wegpunkt sichtbar wird
• Klick-vor-Audio-Ende → Klick wird angenommen, aber als „Pre-Click" markiert. Audio läuft trotzdem fertig.
• Strecken-Animation passt sich an Audio-Dauer an (Flugzeit-Berechnung wird dynamisch)

Konkrete Code-Stellen die verschwinden

• game.html:1056 (Mission-Intro setTimeout) → ersetzt durch Timeline-Trigger
• game.html:1365 (r_wp_geo in showPlanInstruction) → ersetzt durch Timeline
• game.html:1400 (r_nav_plan_correct/done in onPlanClick) → ersetzt durch Timeline
• game.html:1552 (r_mission_geo in initFlightPhase) → ersetzt durch Timeline

Plan + Flug = Engine-driven, Abflug + Landung = wie heute

Phase 3 + 5 (iframe-basiert) bleiben unangetastet. Wenn das später auch in die Timeline soll, müssen wir die iframes auf das gleiche Schema umbauen — aber das ist Phase 2 dieses Projekts.

Implementierungs-Reihenfolge

Schritt	Was	Aufwand
1	Konzept-Doc OK von Thomas	—
2	PHP-Endpoint heli-timeline.php (GET/POST + Datei-Backup)	1 h
3	Audio-Dauer-Cache: Skript das alle MP3s clientseitig misst und in audio-durations.json schreibt (einmaliger Setup)	2 h
4	Tool-UI Grundgerüst: Mission-Switch, Phasen-Track, Zeitachse, Audio-Track (read-only)	3 h
5	Tool-UI Editor: Drag&Drop, Audio-Pool, Speichern	3 h
6	Default-Timeline-Generator: Atlas befüllt ALLE 25 Missionen vor (siehe Sektion „Default-Befüllung")	3 h
7	M1 als erste Mission gemeinsam durchgehen + tunen (Atlas lernt)	gemeinsam
8	Engine-Refactor: audio-engine.js lädt Timeline + spielt deterministisch (nur Plan + Flug)	4 h
9	Test M1: Tool → Spiel → läuft korrekt + sequenziell + Klick-vorab funktioniert	gemeinsam
10	Restliche 24 Missionen im Tool durchschneiden	gemeinsam
Total Atlas-Code	ca. 15 h
Total Thomas-Review	ca. 3-4 h gemeinsam

Default-Befüllung (Atlas macht die Hauptarbeit)

Thomas-Direktive: „Du füllst das Tool gleich mit deinem Vorschlag … hoffentlich muss ich nicht alle selbst machen."

→ Atlas erzeugt pro Mission eine komplette Default-Timeline. Thomas reviewt + tunet, was nicht passt. Atlas lernt aus den Korrekturen für die nächsten Missionen.

Generator-Regeln (Atlas befüllt automatisch)

Pro Mission liest der Generator:

• Mission-Daten aus ALL_MISSIONS (waypoints, base, theme, scenario, heliKey)
• Audio-Drehbuch-Regelwerk (welche Audios in welcher Phase, in welcher Reihenfolge)
• Audio-Dauern aus audio-durations.json
• Briefings aus briefings.json (Wetter-Trigger ja/nein)

Daraus baut er die Default-Timeline:

PLAN-Phase:
  T=0.0   r_mission_intro_<mid>             (dur aus Cache)
  T=+gap  r_wp_geo_<wp1>                    (erster Wegpunkt-Hint, Trigger für Wegpunkt-Sichtbar-Event)
  T=+dur  EVENT: WP1 sichtbar
  T=+gap  r_nav_plan_correct                (wenn Schüler klickt, Audio spielt zu Ende)
  T=+dur  EVENT: WP1 erreicht
  T=+gap  r_wp_geo_<wp2>
  ...
  T=...   r_nav_plan_done                   (letzter Wegpunkt)

FLUG-Phase:
  T=0.0   r_mission_geo_<mid>               (das lange Region-Briefing)
  T=+gap  r_nav_heli_intro_<helikey>        (Crew-Vorstellung)
  T=+gap  r_nav_altitude_mountain ODER _valley (je Theme)
  T=+gap  r_nav_fuel_half
  T=+gap  r_nav_weather_enter               (NUR wenn briefings.wetter gesetzt)
  T=+gap  r_im_zielgebiet                   (kurz vor Landung)

Mit gap = 0.5 s (Default-Pause zwischen Audios, im Tool änderbar).

Tool zeigt Generator-Status

Im UI-Header pro Mission:

• 🤖 „Default von Atlas, ungeändert" — du musst nichts tun, kannst direkt zur nächsten
• ✏️ „Von dir bearbeitet" — Diff-Anzeige (gelb markiert), zeigt was du verändert hast
• 💾 „Gespeichert" — letztes Save-Datum

Atlas lernt (Memory)

Wenn du an einer Mission etwas änderst — z. B. r_nav_fuel_half rausnimmst weil es nicht passt — schreibt Atlas das in ein Lern-Memo:

docs/audio-tool-lernkurve.md:

2026-06-01: Thomas hat aus M1 r_nav_fuel_half entfernt (Begründung: zu früh, störender Hinweis)
  → Default-Generator: r_nav_fuel_half künftig nur bei Missionen mit >5 Wegpunkten einreihen.
2026-06-01: Thomas hat in M6 das Wetter-Audio vorgezogen (vor Mission-Geo)
  → Default-Generator: wenn briefings.wetter gesetzt, r_nav_weather_enter VOR r_mission_geo platzieren.

Bei der nächsten Mission-Befüllung berücksichtigt Atlas diese Lerneinträge. So musst du nicht für 25 Missionen das gleiche tunen — die Lern-Regel reicht.

Workflow

[Atlas startet Tool] → 25 Default-Timelines werden vorgeneriert
       ↓
[Thomas öffnet M1]   → sieht 🤖-Default, hört Vorschau im Spiel
       ↓
[Thomas tunet M1]    → verschiebt 2 Audios, löscht 1
[Atlas merkt sich Begründung] → Memory-Eintrag
       ↓
[Thomas M2]          → Default ist schon besser dank gelernter Regel
       ↓
[...iterativ M3...M25 — Aufwand sinkt pro Mission]

Realistische Schätzung pro Mission (nach Default):

• Erste 5 Missionen: ~10 min Review/Tunen (viel zu lernen)
• Mittlere 10 Missionen: ~3 min (kleine Anpassungen)
• Letzte 10 Missionen: ~1 min (meist nur Bestätigen)

Total: ~1.5 h gemeinsame Review-Zeit für alle 25 Missionen.

Was ich beim Bauen NICHT mache (wichtig)

• Keine weiteren Bug-Fixes an der alten Engine
• Keine neuen TTS-Runs bis das Tool steht (sonst Inhalts-Murks bevor Struktur sauber ist)
• Kein V3-Whitelist-Geraffel — die V1-Whitelist bleibt aktiv, nur die neue Engine umgeht sie sauber
• Kein Code-Anfassen ohne Konzept-OK

Offene Frage(n)

Nur eine — alles andere ist konkret genug:

Q1: Vorschau-Knopf im Tool — wirklich nötig? „▶ Vorschau abspielen" würde die ganze Timeline sequenziell durchspielen mit Subtitel-Anzeige. Kostet ~2 h Tool-Entwicklung. Alternative: du speicherst, öffnest /heli-game?mission=m1 in neuem Tab und hörst dort die echte Engine. Spart Aufwand, ist authentischer.

Mein Tipp: Vorschau weglassen. Echtes Spiel ist der wahre Test.

---

Wenn das Konzept passt, fange ich mit Schritt 2 (PHP-Endpoint) an. Sag „los".