agens-no/app-promo

App-Werbevideo (Remotion + echtes iPhone + echte UI)

Diese Methode wurde an vier kleinen iOS-Apps (Unblock, Talljakt, Georama und Quiz) entwickelt und ist so geschrieben, dass sie für jede App wiederholt werden kann. Alles App-spezifische befindet sich in examples/. Wiederverwendbare Teile in templates/. Detaillierte Techniken, Fallstricke und einstellbare Variablen finden sich in references/techniques.md. Lies es, bevor du loslegst.

Sprache: Sprich mit dem Benutzer in der Sprache, die er verwendet. Wenn er auf Norwegisch beginnt, antworte auf Norwegisch. Die Sprache des Texts im Video ist eine separate Wahl (Frage 3 unten).

0. Zuerst das Interview (kurz)

Stelle diese Fragen zusammen (AskUserQuestion oder eine Nachricht). Schlage Standardwerte vor, sodass der Benutzer einfach „Standard“ antworten kann:

1. Länge: 20–60 s. Standard ~30 s.
2. Format: 9:16 vertikal 1080×1920. Standard 60 fps. Auch 1:1 oder 16:9?
3. Sprache des On-Screen-Texts.
4. Verwendung: privates Teilen, Social Media (Reels/TikTok, Sicherheitszonen) oder App-Store-Vorschau. App-Store-Vorschauen müssen echte Aufnahmen sein, max. 30 s, ohne erfundene 3D-Effekte, daher ist diese Methode dafür schlecht geeignet.
5. Wie viel UI hebt sich vom Bildschirm ab: keine (dezent: echte Aufnahmen, nur Fokus-Zooms und die eigenen Übergänge der App, siehe examples/kjop), dezent (ein oder zwei Heldenmomente), mittel oder voll (alles hebt sich ab). Standard ist dezent bis mittel; keine eignet sich für schlichte Alltags-Apps (Listen, Formulare, Einstellungen). Voll eignet sich für Apps, deren Teile natürlicherweise physische Objekte sind (Spielsteine); für gewöhnliche Apps (Listen, Formulare, Karten) hebe nur 1–3 Schlüsselelemente hervor und lasse den Rest auf dem Bildschirm.
6. Kreative Freiheit: Soll der Agent das Konzept entwickeln?
7. Musik: im Code generiert (Standard, keine Lizenz erforderlich) oder eigener Track? Gib jeder App ihre eigene Klangpalette, damit zwei Videos nie gleich klingen (siehe references/techniques.md#sound).
8. Welche Funktionen sollen gezeigt werden (3–5), und was ist das „Helden“-Element oder der Höhepunkt der App?
9. Ende: zwei bewährte Optionen; wähle je nach App und frage, falls unklar. (a) Ein Logo-Lock-up aus den eigenen Elementen der App (Unblock: Das Logo setzt sich aus 3D-Kacheln zusammen, die letzte Messing-Kachel setzt auf). (b) Der Home-Bildschirm auf dem Telefon mit einem Slogan darüber, wobei Symbol + Name die letzte Zeile sind (Talljakt: „Sechs Zahlen. / Ein Ziel. / [Icon] Talljakt.“).
10. Telefonfarbe: cosmic-orange, deep-blue oder silver. Wähle die Farbe, die zur Akzentfarbe der App passt.

Die Antworten steuern hauptsächlich das Konzept, wie viel sich vom Bildschirm abhebt, das Tempo (bpm) und die Farben.

0a. Preflight: Überprüfe die Toolchain

Überprüfe vor dem Bauen, was installiert ist, und melde es in einer kurzen Liste. Biete an, Fehlendes zu installieren, und installiere nur, nachdem der Benutzer zugestimmt hat (dies sind Systemänderungen). Überspringe alles, was bereits vorhanden ist.

Tool	Prüfung	Installation
Xcode + Kommandozeilen-Tools	xcodebuild -version, xcode-select -p	App Store (Xcode), dann xcode-select --install
iOS Simulator Laufzeit mit einem iPhone 17 Pro Gerätetyp	xcrun simctl list runtimes, `xcrun simctl list devicetypes	grep "iPhone 17 Pro"`
baguette	baguette --version	brew install baguette
Blender	ls /Applications/Blender.app	brew install --cask blender
Node 22	node --version	nvm install 22 (oder brew install node@22)
ffmpeg	ffmpeg -version	brew install ffmpeg
Python 3 + Pillow	python3 -c "import PIL"	python3 -m pip install --user pillow
Homebrew (für die obigen)	brew --version	Das offizielle Installationsskript von brew.sh, vom Benutzer ausgeführt

Richte dann das Remotion-Projekt ein (references/techniques.md#setup) und konvertiere das iPhone-Modell einmal (Schritt 6 unten). Beides ist projektlokal und benötigt keine zusätzliche Berechtigung über die Arbeit im Repo hinaus.

0b. Lieferordner (einmal pro Mac)

Fertige Videos werden in einem festgelegten Ordner auf dem Rechner abgelegt, nicht nur im out/ des Projekts. Die Wahl wird pro Mac in ~/.config/app-promo/destination gespeichert (eine Zeile, vollständiger Pfad).

• Lies die Datei zu Beginn. Wenn sie existiert, verwende den Ordner ohne Nachfragen.
• Wenn sie fehlt, frage einmal (AskUserQuestion): ~/Movies/App Promos (empfohlen), den out/-Ordner des Projekts, den Desktop oder einen benutzerdefinierten Pfad. Erstelle den Ordner und schreibe den Pfad in ~/.config/app-promo/destination.
• Der Benutzer kann es jederzeit ändern, indem er es anfragt; aktualisiere die Datei.

1. Arbeitsablauf

1. Lies die App. README, Farb-Tokens (suche Color(, hex, Theme-Strukturen), Schriftarten, Copy. Verwende den eigenen Copy der App im Video, wo er gut ist.
2. Finde Debug-Einstiegspunkte, um Zustände ohne Abspielen zu zeigen: Launch-Argumente (--design-*), URL-Schemata (myapp://design-home?state=…) oder Fixtures. Wenn es keine gibt, frage, bevor du DEBUG-only-Hooks zur App hinzufügst.
3. Baue und installiere auf einem dedizierten iPhone 17 Pro Simulator. Screenshots müssen 1206×2622 sein, sonst passen sie nicht auf den Bildschirm des Telefonmodells. Siehe references/techniques.md#simulator. 3b. Für echte Screen-Recordings: lies references/recording.md. Bereite die Szene und Tipppunkte zuerst vor, nimm kurze Takes ohne UI-Inspektion, Builds oder Videoanalyse während der Aufnahme auf und überprüfe das Roh-Timing vor Remotion. Ein einzelner kontinuierlicher Take eines gesamten Ablaufs (wie in examples/quiz) hält jede Zahl, jeden Fortschrittsbalken und jeden Verlauf konsistent.
4. Mache Screenshots von jedem Zustand. Für Standbild-/Ausschnitt-Sequenzen spiele sie mit echten Taps ab und mache nach jedem Tap einen Screenshot (siehe references/consistency.md). Für Video führe diese Inspektion in einer separaten Probe durch, niemals während des endgültigen Takes. Sperre die Statusleiste (9:41, 100 %, entladen, oder ein grüner Ladeindikator wird angezeigt). Erhalte Elementrahmen mit baguette describe-ui.
5. Schneide UI-Elemente aus mit einem app-spezifischen tools/prep_<app>.py, das templates/tools/prep_helpers.py verwendet: Sprites, leere Hintergründe und ein JSON mit Rechtecken. Überprüfe jede Menge visuell (Composite auf Magenta).
6. Konvertiere das iPhone-Modell von baguette (USDZ) in GLB mit Blender (templates/tools/convert_model.py).
7. Richte das Remotion-Projekt ein oder verwende eines wieder: kopiere templates/src/three/*, Title.tsx, brand.ts, remotion.config.ts, tools/sheet.sh und tools/prep_helpers.py.
8. Schreibe ein Beat-Sheet (timeline.json) in Frames auf einem bpm-Raster (120 bpm bei 60 fps = 30 Frames pro Beat). Bild und Ton lesen beide diese Datei.
9. Baue die Szenen als eine kontinuierliche „One-Take“-Aufnahme: Die Kamera bleibt still und das Telefon-Rig bewegt sich. Bildschirmwechsel werden durch einen Übergang verdeckt: eine Drehung, die eigene Navigation der App, ein Zoom oder Wipe von einem Element, ein Push, Flip, Whip Pan, Match Cut oder Vorspulen. Variiere sie, maximal zwei Drehungen pro Video. Siehe references/techniques.md#transitions.
10. Iteriere mit Kontaktbögen (tools/sheet.sh f1 f2 …) von Schlüsselbildern. Sieh sie dir an. Rendere das vollständige Video (schnell: ~1–2 min für 30 s).
11. Checkpoint: Zeige dem Benutzer die ersten ~12 s, bevor du den Rest baust.
12. Generiere den Soundtrack (tools/<app>_audio.mjs, kopiert von einem Beispiel) aus derselben Timeline. Rendere, messe die Lautstärke (ffmpeg -af ebur128, Ziel −14 bis −16 LUFS) und öffne die Datei für den Benutzer.

12b. Konsistenzprüfung (vor der Auslieferung erforderlich). Eine Diskrepanz zwischen dem, was auf dem Telefonbildschirm zu sehen ist, und dem, was außerhalb hervorgehoben wird, sieht wie ein KI-Artefakt aus. Gehe references/consistency.md durch und rendere Kontaktbögen ±2 Frames um jeden Übergang, Bildschirmwechsel und Anhebung. 13. Teile-Text: Schreibe einen kurzen Text zum Einfügen, wo immer das Video geteilt wird (Format unten). Kopiere ihn in die Zwischenablage (pbcopy) und zeige ihn in der Antwort in einem Code-Block an. Speichere ihn nicht als Datei. 14. Liefern: Kopiere den neuesten genehmigten Render in den Lieferordner (0b) als <App> promo.mp4. Überschreibe die vorherige Lieferung für dieselbe App; die Versionshistorie (-v2, -v3 …) bleibt in out/. Gib den Pfad der gelieferten Datei in der Antwort an.

Format des Teilen-Textes

Der Text wird normalerweise in Slack gepostet, also verwende Slack-Formatierung (mrkdwn): einen fetten Titel mit einzelnen Sternchen und Aufzählungspunkten mit „• “ (ein eingefügtes „- “ wird keine Liste). Schreibe ihn in der Sprache des Videos.

*<App> – <Tagline in 2–4 kurzen Sätzen/Wörtern, idealerweise die aus dem Video>.*
<Ein Satz: Was die App ist, für wen oder was.>

• <Punkt: Die Kernaktion, konkret und aktiv>
• <Punkt: Die Wahlmöglichkeiten, die die App gibt (Themen, Modi, Bereich, Tempo …)>
• <Punkt: …>
• <Punkt: Belohnung/Teilen/Was sie besonders macht>

Regeln: 4–5 Punkte, kein Punkt am Ende der Punkte, sprich den Leser direkt an, konkrete Verben, keine Marketing-Klischees. Beginne damit, wie die App tatsächlich verwendet wird: Die ersten 2–3 Punkte erklären die Mechanik konkret, bevor Optionen und Extras kommen. Beschreibe dann, was die App dir ermöglicht, nicht nur, was das Video zeigt: gruppiere die Optionen pro Punkt („Übe Länder, Hauptstädte oder Flaggen“), damit der Leser die Bandbreite sieht. Verwende die eigenen Namen der App für Dinge und überprüfe im Code, was jeder Modus wirklich tut (READMEs werden alt). Siehe examples/*/share.txt.

2. Eine Konzeptvorlage, die funktioniert hat

Ein Held, eine Bewegung, die alles zusammenhält, der eigene Copy der App:

Teil	Unblock	Allgemein
Aufhänger 0–2,5 s	Kacheln fallen auf ein im Dunkeln schwebendes Brett, kein Telefon. „Festgefahren.“	Das Problem, das die App löst, gezeigt mit den eigenen Elementen der App, ohne das Telefon
Enthüllung	Das Telefon baut sich um das Brett herum auf, während die Kamera zurückzieht	Dasselbe Element entpuppt sich als in der App
Kernschleife	4 Züge im Takt, ein Zähler außerhalb des Bildschirms	Die Hauptaktion in 3–4 Takten
Heldenmoment	Der Held hebt sich vom Bildschirm ab und fliegt in die Kamera, Messingblitz	EIN großer Moment (ein Bildschirm-Effekt oder die eigene beste Animation der App in Zeitlupe)
Belohnung	Ergebnisbildschirm, 3D-Sterne hüpfen heraus	Die Belohnung oder das Ergebnis
Funktionen (variierte Übergänge dazwischen)	Level-Auswahl, tägliche Karte, Punktzahl	2–3 Funktionen, jede mit einem hervorgehobenen Element
Outro	Logo aus 3D-Kacheln gebaut, Tagline	Logo-Lock-up aus den Elementen der App, oder der Home-Bildschirm mit Slogan + Name

Wenn die App eine wirklich gute eigene Animation hat (Quiz: der „Antwort anzeigen“-Button, der sich in Falsch/Richtig aufreißt), mache diese zum Helden: zoome nah heran, verlangsame sie mit einer Geschwindigkeitsrampe, gib ihr einen eigenen Sound und beschrifte sie nicht.

2b. Visuelle Mittel aus guten App-Werbungen

Gute Referenzen nutzen den Bildschirm und den Inhalt, nicht nur das Layout. Plane mindestens 3–4 davon pro Video ein:

• Schneide den Bildschirm zu: Gehe nah genug heran, dass nur ein Teil sichtbar ist (ein Timer, eine Schaltflächenreihe, eine Gleichung). Das Telefon wird vom Bildschirmrand abgeschnitten. Verwende focus-Posen.
• Inhaltskarten neben oder vor dem Telefon: Echte Karten oder Poster aus der App (Teilen-Karte, Ergebnis-Karte, Vorschlag) als flache, leicht gedrehte Ebenen hinter oder vor dem Telefon.
• Mehrere Inhaltskarten auf einmal: Fächere 3–5 Varianten auf (Seiten, Lösungen, Poster).
• Mehrere Geräte: Zwei Telefone nebeneinander, wenn die Geschichte vom Teilen oder „das Gleiche für alle“ handelt, mit Namensschildchen darüber. Telefon + Watch/iPad, wenn die App es unterstützt (baguette hat iPad- und Watch-Modelle).
• Die Elemente der App als Dekoration: Echte Kacheln, Schaltflächen, Chips oder Symbole, die im Hintergrund treiben (unscharf = weit weg), oder vergrößert zur Typografie über dem Telefon. Ein thematisches Motiv (Pulslinie, Kreidestrich, Millimeterpapier).
• Was die App produziert, als Objekt: der Druck, das Poster, die Karte, idealerweise ohne das Telefon.
• Sprech- oder Denkblasen für Dinge, die außerhalb des Telefons passieren (Quiz: Die gesprochene Antwort erscheint neben der Karte und fällt dann auf die Richtig/Falsch-Schaltfläche, um sie zu „drücken“).

2c. Text und Rahmung

• Große zentrierte Titel oben tragen die Botschaft: 2–4 Wörter pro Zeile, maximal zwei Zeilen, die zweite Zeile oder das Schlüsselwort in der Akzentfarbe.
• Kleine Beschriftungen unten, sparsam, nur wenn der Titel einer Klärung bedarf (2–3 Mal in einem 30-Sekunden-Video). Sie müssen lesbar sein: mindestens ~50 px, in einem Chip mit hellem Hintergrund und Schatten (kein freistehender Text), tief platziert, sodass sie nie den Rahmen des Telefons kreuzen, mindestens 2 s sichtbar.
• Behaupte nur, was die App tatsächlich tut. Überprüfe, was eine Funktion wirklich ist, bevor du darüber schreibst.
• Ganzseitige Textkarten werden unterstützt: eine farbige Fläche (die Primärfarbe der App) mit einem großen zentrierten zweizeiligen Titel, eingewischt aus dem zuletzt fokussierten Element und weggerutscht zur nächsten Szene. Verwende eine als Verschnaufpause oder Brücke vor dem Ende, idealerweise eine Frage, die den Betrachter herausfordert („Kannst du es rechtzeitig finden?“). Springe nicht direkt von intensiver Aktion zum Endbildschirm. Siehe QuestionCard in examples/talljakt und examples/quiz.
• Kein festes App-Symbol und Name in einer Ecke. Zeige den Namen nur am Ende, im Logo oder als letzte Zeile des Slogans.
• Halte den Rahmen sauber: eine Idee pro Szene. Wenn eine Funktion wenig zu zeigen hat (eine Einstellung), arbeite sie als Beschriftung oder kurzen Fokus in einer anderen Szene ein, anstatt ihr eine eigene Szene zu geben. Vermeide Titel + gezoomtes Telefon + eine Reihe von Elementen + Beschriftung gleichzeitig.
• Tempo: keine tote Zeit. Jede Szene hat innerhalb von ~1 s nach Beginn ein Ereignis, und kein Titel sitzt länger als ~1,5 s über einem statischen Bildschirm. Wiederholende Schritte (Fragen 2–13 eines Quiz) können vorgespult werden.
• Zeige Wahlmöglichkeiten als Aktion, nicht als Text. Wenn die App Modi oder Einstellungen hat, zeige die Auswahl des Standards (die Karte hebt sich ein wenig), ein Tippen auf die Alternative (sie hebt sich, der Bildschirm wechselt den Zustand), dann ein Tippen auf Start, der in diesen Modus führt.
• Interaktionen, die sonst unklar wären (Menü öffnen, Option auswählen), erhalten einen Tipp-Indikator (ein Kreis, der eindrückt und nach außen wellt) auf das, worauf die App tatsächlich reagiert.

3. Prinzipien

• Echte UI besser als nachgebaute UI. Verwende Screenshots, Aufnahmen und Ausschnitte, keine HTML-Kopien der App. Text, der sich ändern muss (Zähler, Punktzahlen), wird in der Schriftart der App mit PIL gezeichnet und mit dem Original abgeglichen.
• Dosieren von „aus dem Bildschirm heraus“. Es ist eine Würze. Der Standard ist ein Heldenmoment und 1–2 hervorgehobene Funktionen.
• Zoom und Fokus sind das Hauptwerkzeug zur Betonung. Bewege die Kamera auf den Teil des Bildschirms, der wichtig ist. Ein enger Fokus (z. B. nur ein Timer) sagt mehr als ein Pfeil oder eine Hervorhebung.
• Sound tut die schwere Interpretationsarbeit. Eine tiefe Note für ein Gewicht, ein Glockenspiel für eine Belohnung, ein Rauschen für einen Wisch. Generiere ihn aus dem Beat-Sheet, nicht getrennt.
• Überprüfe deine Arbeit, bevor du sie zeigst. Ein konsistent falscher Bildschirm (Screenshot eines anderen Zustands, eine Kachel, die auf dem Bildschirm, aber nicht außerhalb zu sehen ist) zerstört die Illusion vollständig.

4. Technische Referenzen

Siehe references/techniques.md für:

• Einrichtung des Remotion-Projekts
• Simulator-Konfiguration und Statusleiste
• Übergangstechniken
• Sounddesign (Generierung von Soundtracks aus der Timeline, Loudness-Ziele)
• Umgang mit verschiedenen Telefonmodellen (baguette hat iPhone 17 Pro, iPad, Watch)

Siehe references/consistency.md für Konsistenzprüfungen vor der Auslieferung.

Siehe references/recording.md für die Aufnahme von Screen-Recordings.

5. Beispiele

Jedes Beispiel in examples/ enthält:

• prep_<app>.py: App-spezifisches Python-Skript zum Ausschneiden von UI-Elementen
• timeline.json: Das Beat-Sheet für das Video
• share.txt: Der Teilen-Text (siehe Format oben)
• out/: Fertige Renderings

Aktuelle Beispiele:

• unblock – Ein Puzzlespiel mit Kacheln
• talljakt – Eine Zahlenratespiel-App
• georama – Eine Karten-/Erkundungs-App
• quiz – Eine Quiz-App

6. Beitragen

Siehe CONTRIBUTING.md für Richtlinien zum Hinzufügen neuer App-Vorlagen und zur Verbesserung der Werkzeuge.