# AnnexMotion – Handbuch

## 1. Überblick

AnnexMotion ist die Videoschnitt- und Motion-App der Suite AnnexCREATE: Schnitt, Keyframe-Animation, Titel, Audio und Farbe in einem Dokument, ohne Roundtrip in eine Zweit-App. Die App richtet sich an Freelancer, Selbständige und kleine Agenturen, die erklärende Videos, Social-Clips und animierte Grafiken im eigenen Branding produzieren.

Kernnutzen auf einen Blick:

- **Alles in einem Dokument**: Mehrspur-Timeline, Keyframe-Animation, Titel, Audio-Mixing und Farbkorrektur greifen ineinander – inklusive Kurven-Editor, Mixer und Scopes.
- **Was du siehst, wird exportiert**: Vorschau und Export laufen über denselben Metal-Custom-Compositor.
- **Audio-Intelligenz als Daten**: Auto-Ducking, Beat-Marker und Loudness-Angleichung (−14 LUFS, EBU R128) erzeugen editierbare Ergebnisse statt Black-Box-Effekte.
- **Branding eingebaut**: Brandkits steuern Schriften und Farben der Titel direkt im Inspector.

AnnexMotion ist Teil des „Creative OS" AnnexCREATE und teilt Design-System, Brandkits, Einstellungen und Diagnostik mit den übrigen Apps.

## 2. Installation & Aktivierung

AnnexMotion wird über **AnnexHub** installiert und verwaltet:

1. AnnexHub öffnen und im Bereich **Apps** AnnexMotion auswählen.
2. Installieren bzw. aktualisieren – Updates werden in AnnexHub mit Changelog angezeigt.
3. Die Lizenz aktivierst du in AnnexHub im Bereich **Lizenzen**: online per Lizenzschlüssel oder offline über eine signierte Aktivierungs-Datei.

**Offline-first**: AnnexMotion läuft ohne Serververbindung. Schnitt, Vorschau, Animation, Audio, Farbe und Export funktionieren vollständig offline; alle Dokumente und Medien bleiben lokal auf deinem Mac.

## 3. Grundworkflow

Der typische Ablauf von den Rohdaten bis zum fertigen Film:

1. **Projekt öffnen**: Ein `.axmotion`-Dokument über `Ablage ▸ Öffnen…` (⌘O) laden bzw. mit einem neuen Dokument starten.
2. **Medien importieren**: Video- und Audiodateien in die Medienbibliothek ziehen; die App ermittelt Dauer, Framerate und Spur-Arten automatisch, Video+Ton landet als verknüpfter A/V-Clip.
3. **Schneiden**: Clips auf die Timeline legen, mit der Blade am Playhead schneiden, an den Kanten trimmen (mit Ripple) und bei Bedarf Übergänge aus dem Übergangs-Browser einfügen.
4. **Animieren und betiteln**: Titel-Clips mit Animator-Presets anlegen, Keyframes für Position, Skalierung, Rotation und Deckkraft setzen und im Kurven-Editor feinsteuern.
5. **Audio mischen**: Pegel und Fades pro Clip einstellen, Musik per Auto-Ducking unter den Dialog legen und die Loudness auf −14 LUFS angleichen.
6. **Farbe anpassen**: Mit Lift/Gamma/Gain oder einer `.cube`-LUT graden und das Ergebnis im Scopes-Panel kontrollieren.
7. **Untertitel ergänzen**: Captions als eigene Spuren anlegen oder per SRT importieren – sie werden in Vorschau und Export eingebrannt.
8. **Exportieren**: In/Out-Bereich festlegen (Tasten I/O) und über `Ablage ▸ Exportieren…` als MP4 oder MOV rendern; Projekt mit `Ablage ▸ Speichern…` (⌘S) sichern.

## 4. Kernfunktionen

### Timeline und Edit-Operationen

Die Timeline arbeitet frame-exakt auf rationaler Zeit und kennt drei Spurarten: Video, Animation (Titel/Grafik/Vektor) und Audio. Dazu kommen eine Zeitleiste, eine Marker-Spur (Standard/Todo/Beat), Zoom und ein In/Out-Exportbereich. Schneiden geht mit der Blade am Playhead (schneidet alle Spuren inklusive verknüpfter A/V-Clips), Trimmen an den Clip-Kanten mit Ripple; magnetische Spuren schließen Lücken automatisch. Pro Spur stehen Mute, Solo und Lock zur Verfügung.

### Medien-Import und Medienbibliothek

Beim Import prüft die App jede Datei per AVFoundation: Dauer, Framerate und enthaltene Spur-Arten werden ermittelt, Video mit Ton landet als verknüpfter A/V-Clip (gemeinsame Link-Gruppe, Audio-Rolle). Die Medienbibliothek zeigt Dauer sowie Video-/Audio-Badges pro Medium.

### Playback-Vorschau

Die Vorschau läuft über `AVPlayer` mit Custom Compositor: Play/Pause per Leertaste, Frame-Schritte vor/zurück und Sprung an den Anfang über die Transport-Leiste. Der Playhead synchronisiert in beide Richtungen; ein Frame-Cache beschleunigt Scrubbing und Scopes. Offline-Medien werden im Viewer als solche angezeigt.

### Metal-Compositing, Übergänge und Effekte

Vorschau und Export nutzen denselben Metal-Renderer: Transform (Position, Skalierung, Rotation, Deckkraft), Blend-Modes Normal/Multiply/Screen/Add und Track-Mattes (Luma/Alpha pro Videospur, wählbar im Inspector). Als Übergänge stehen Cross Dissolve, Dip to Black/White, Wipe (vier Richtungen) und Push (links/rechts) mit einstellbarer Dauer bereit; der Übergangs-Browser in der Sidebar zeigt eine Live-Vorschau beim Überfahren. Pro Clip wirken bis zu vier Effekte: Color Adjust (Helligkeit/Kontrast/Sättigung), Pixelate, Vignette und Grain – mit Slidern und Ein/Aus-Schalter im Inspector.

### Keyframes, Kurven-Editor und Motion-Paths

Animierbar sind Position X/Y, Skalierung, Rotation und Deckkraft, mit Easings (linear, easeIn/Out/InOut). Im Kurven-Editor ziehst du Keyframes, legst sie per Doppelklick an und wählst Easings übers Kontextmenü; der Inspector bietet Keyframe-Rauten mit Sprung-Buttons. Im Viewer zeigt ein Motion-Path-Overlay die Bewegung mit ziehbaren Punkten.

### Titel und Brandkits

Titel-Clips auf Animationsspuren tragen Text, Größe, Font und Farbe und werden per CoreText mit Alpha gerendert. Animator-Presets (Fade In/Out, Slide In/Out, Scale Pop, Typewriter pro Zeichen/Wort) werden als echte, editierbare Keyframes gebacken. Verknüpfst du ein Brandkit per Checkbox mit dem Dokument, steuert dessen Font-Whitelist die Titel-Schriftauswahl, und die Brandkit-Farben erscheinen als Klick-Swatches im Titel-Inspector.

### Audio, Mixer und Audio-Intelligenz

Pro Clip stellst du Pegel und Fade-In/Out ein; Volumen-Automation läuft als Hüllkurve und wird in Playback und Export übernommen. Audio-Rollen (Dialog/Musik/Ambiente/Effekte) strukturieren den Mix, das Mixer-Panel zeigt eine Zeile pro Audiospur mit Rolle, Mute/Solo, Pegel und Näherungs-Meter. Aus dem Inspector heraus stehen drei Analysen bereit: Auto-Ducking (Musik wird unter Dialog abgesenkt – als editierbare Volumen-Keyframes), Beat-Marker aus der Wellenform-Analyse und Loudness-Angleichung auf −14 LUFS mit echter EBU-R128-Messung.

### Farbe und Scopes

Die Farbkorrektur bietet das Farbrad-Trio Lift/Gamma/Gain (R/G/B-Slider pro Clip) und den Import von `.cube`-LUTs (als Metal-3D-Textur gecacht). Das Scopes-Panel zeigt Luma-Histogramm und Waveform des aktuellen Frames.

### Geschwindigkeit und Captions

Pro Clip ist ein konstantes Retime möglich (0,1–8×, in der UI 0,25–4×); verknüpfte A/V-Clips bleiben synchron. Captions laufen auf eigenen, überlappungsfähigen Spuren; SRT-Import und -Export sind integriert. Untertitel werden als Overlay (unten-mittig, sichere Zone) in Vorschau und Export eingebrannt.

### Motion-Behaviors

Der Sidebar-Tab **Behaviors** bietet vorgefertigte Animationen: Fade In/Out, Slide, Scale Pop, Orbit, Wiggle und Throw. Ziehe ein Behavior per Drag & Drop auf einen Clip oder klicke es an, während der Clip selektiert ist. Im Inspector erscheinen Parameter für Richtung, Stärke und Dauer.

Behaviors werden als echte Keyframes gebacken, bleiben aber als `MotionBehavior`-Objekt editierbar. Du kannst ein Behavior jederzeit neu backen oder entfernen; dabei werden die zuvor erzeugten Keyframes ersetzt bzw. gelöscht.

**Grenzen:** Behaviors wirken auf die transformierbaren Eigenschaften eines Clips (Position, Skalierung, Rotation, Deckkraft). Sind auf denselben Eigenschaften bereits Keyframes vorhanden, werden sie durch das Backen überschrieben – der Inspector warnt vor dem Überschreiben.

### Verknüpfte Objekte

Beim Medien-Import bietet der Dialog die Optionen **Kopieren in Projekt** oder **Verknüpfen**. Verknüpfte Medien und `.axdesign`-Dateien bleiben außerhalb des `.axmotion`-Containers und tragen einen `LinkedObject`-Eintrag. In der Medienbibliothek erkennst du sie an einem Status-Badge.

Ein File-Watcher erkennt externe Änderungen an verknüpften `.axdesign`-Dateien und löst einen Composition-Rebuild aus. Über das Menü oder einen Alert erreichst du die Befehle **Aktualisieren** und **Einbetten**. Der Status (`ok`, `modified`, `missing`, `embedded`) wird pro Medium bzw. Clip abgefragt.

**Grenzen:** Verknüpfte Medien, die beim Öffnen des Projekts fehlen, werden als offline markiert; der Export bricht mit einer Liste der fehlenden Dateien ab, bis du sie neu verknüpfst oder einbettet.

### Proxy-Workflow (Grundlage)

Die App erzeugt auf Wunsch reduzierte H.264/MP4-Arbeitskopien (längste Kante ≤ 960 px, kein Upscale) im Caches-Verzeichnis. Die Vorschau kann zwischen Original und Proxy umschalten; der Export nutzt immer das Original. Eine eigene Proxy-Bedienoberfläche existiert noch nicht.

### Menüleiste und Tastaturkürzel

- `Ablage ▸ Öffnen…` – `.axmotion`-Dokument öffnen (⌘O)
- `Ablage ▸ Speichern…` – speichern über Panel (⌘S)
- `Ablage ▸ Exportieren…` – Video-Export (kein Tastaturkürzel)
- `AnnexMotion ▸ Einstellungen…` (⌘,)
- Transport-Leiste: Play/Pause (Leertaste), In-Punkt setzen (I), Out-Punkt setzen (O)

### Einstellungen und Mehrsprachigkeit

Die Einstellungen bündeln die Suite-Optionen (Theme/Farbschema, Diagnostik, Datenschutz). Die Oberfläche ist auf Deutsch, Englisch, Spanisch, Französisch und Italienisch lokalisiert.

## 5. Formate & Interoperabilität

**Eigenes Format `.axmotion`** (Formatversion 6, seit 01.08.2026): ein ZIP-Container wie bei den übrigen Apps der Suite — `meta.json` mit der Formatversion, `document.json` mit Spuren, Clips, Keyframes, Effekten, Grading, Captions, Markern, Proxies und Brandkit-Verknüpfungen, dazu `assets/` mit den **eingebetteten Mediendateien**. Damit ist ein Projekt in sich geschlossen: Verschickst du die Datei, kommt sie beim Empfänger vollständig an — vorher lagen die Medien als Ordner daneben und fehlten unterwegs.

Ältere Dateien öffnen weiter. Der Weg nach oben läuft in Einerschritten vom Prototyp bis zum Container; die frühere Eigenzählung `schemaVersion` ist darin aufgegangen. Eine Datei aus einer **neueren** Programmfassung wird nicht halb geladen, sondern mit Angabe der Formatversion abgelehnt — sie bleibt unangetastet.

**Fehlende Medien**: Zeigt ein Projekt auf Dateien, die nicht mehr da sind, sagt die App beim Export, **welche** fehlen, und bietet „Medien suchen…" an: Du wählst den Ordner, in dem sie jetzt liegen, und die Verweise werden neu verknüpft.

**Import**: Video und Audio über AVFoundation (u. a. QuickTime, MP4, MP3, WAV), AnnexDesign-Dokumente `.axdesign` als Vektor-Ebenen, SRT-Untertitel und `.cube`-LUTs (je Clip).

**Export**: MP4 (H.264), MOV (H.264) und MOV (Apple ProRes 422) über denselben Metal-Compositor wie die Vorschau; Bereichs-Export über die In/Out-Punkte; Captions werden eingebrannt; SRT-Export der Caption-Spuren.

**Zusammenspiel mit der Suite**:

- **AnnexDesign**: `.axdesign`-Dateien liegen als Live-Vektor-Ebenen auf Animationsspuren – gerastert über die echte Design-Export-Pipeline und gecacht. Ändert sich die Datei extern, baut die Vorschau neu auf; per Kontextmenü „In AnnexDesign bearbeiten" öffnest du die Datei direkt.
- **Brandkits**: Schriften und Farben für Titel aus der gemeinsamen Bibliothek.
- Beim Speichern wird das Dokument in den geteilten Versions-Index geschrieben und taucht dadurch in der zentralen Suche von AnnexHub auf.

iCloud- bzw. Cloud-Sync ist nicht verdrahtet.

## 6. MCP-Bedienung

AnnexMotion ist über den MCP-Host steuerbar, der in **AnnexHub** läuft (JSON-RPC 2.0 via STDIO) und von dort gestartet wird. Damit lassen sich Aktionen der App durch KI-Agenten automatisieren.

Suite-Tools (für alle Apps):

- `list_apps` – listet alle verfügbaren Annex-Apps mit Installationsstatus und Version.
- `open_app` – öffnet eine Annex-App anhand ihrer ID.
- `open_document` – öffnet eine Datei in der angegebenen Annex-App.
- `get_active_document` – gibt Informationen zum aktiven Dokument einer App zurück.
- `get_license_status` – gibt den Lizenzstatus eines Annex-Produkts zurück.
- `search_assets` – durchsucht die zentrale Asset-Bibliothek nach Name oder Tags.

App-spezifisches Tool:

- `motion.open_document` – öffnet ein AnnexMotion-Projekt (`.axmotion`) in AnnexMotion.

Skills (suite-weit): `suite.discover`, `brandkit.apply`.

## 7. Diagnostik & Privatsphäre

AnnexMotion protokolliert Fehler und Aktionen lokal über `AnnexLog` in rotierende JSON-Log-Dateien unter `~/Library/Logs/AnnexCREATE/AnnexMotion/`, gespiegelt nach `os_log` (Subsystem `com.annexcreative.annexmotion`). Die Protokolle werden mit einem PII-Filter geschrieben. Die Diagnostik ist in der Entwicklungsphase standardmäßig aktiv und in den Einstellungen (Datenschutz) abschaltbar; es findet keine Übertragung statt.

Telemetrie läuft ausschließlich per Opt-in (Standard: aus) und kann zur Laufzeit in den Einstellungen umgeschaltet werden. Alle Medien und Dokumente bleiben lokal auf deinem Mac.

## 8. FAQ

**Brauche ich eine Internetverbindung zum Schneiden?**
Nein. Schnitt, Vorschau, Animation, Audio, Farbe und Export laufen vollständig offline.

**Sehe ich in der Vorschau exakt das, was exportiert wird?**
Ja. Vorschau und Export nutzen denselben Metal-Custom-Compositor.

**Gibt es automatische Untertitel per Spracherkennung?**
Noch nicht. Die Schnittstelle ist vorbereitet, die Spracherkennungs-Engine aber noch nicht angebunden. Bis dahin stehen SRT-Import und -Export zur Verfügung.

**Kann ich Änderungen rückgängig machen?**
Undo und Autosave sind noch nicht implementiert. Speichere dein Projekt regelmäßig über `Ablage ▸ Speichern…` (⌘S).

**Nutzt der Export die Proxy-Dateien?**
Nein. Proxies beschleunigen nur die Vorschau; der Export rendert immer aus dem Originalmaterial.

**Kann ich Vektorgrafiken animieren?**
Ja. AnnexDesign-Dokumente (`.axdesign`) liegen als Live-Vektor-Ebenen auf Animationsspuren und werden pro Frame gerastert. Änderungen in AnnexDesign aktualisieren die Ebene.

**Werden Untertitel als separate Datei ausgegeben?**
Captions werden in Vorschau und Export ins Bild eingebrannt. Zusätzlich kannst du die Caption-Spuren als SRT-Datei exportieren.

**Welche Exportformate stehen zur Verfügung?**
MP4 (H.264), MOV (H.264) und MOV (Apple ProRes 422), jeweils über denselben Renderpfad wie die Vorschau; der Exportbereich wird über die In/Out-Punkte festgelegt.