getlarge/themoltnet

Produkt-Demo-Aufzeichnung

Behandeln Sie Bildausschnitt, Privatsphäre, Erzählung und decodierte Ausgabe als separate Freigabetore. Ein erfolgreicher Produktdurchlauf beweist nicht, dass die Aufzeichnung sicher, lesbar oder sauber komponiert ist.

Informationen zu nativen macOS- oder Browser-Aufnahmemechanismen finden Sie unter references/capture-macos.md. Informationen zu Browser-Workflow-Buildern mit Polling- oder Wiederholungsschleifen finden Sie unter references/browser-workflows.md. Informationen zu Titel-/Endkarten, Einblendungen, Diagrammen, Callouts und Endkarten finden Sie unter references/infographic-style.md.

Legen Sie zuerst den Auslieferungsrahmen fest

Vor der Aufnahme:

1. Wählen Sie den Erzähltyp, bevor Sie die Shot-Liste schreiben:
   • Ein Überblick lehrt die Produktform: zeigen Sie die kleinste repräsentative Knoten- oder Bildschirmsequenz, verwenden Sie generische Kopien und verzichten Sie auf szenariospezifische Erklärungen.
   • Ein Szenario-Demo beantwortet eine konkrete Frage: nennen Sie den Fall, zeigen Sie die tatsächlichen Ausführungsschritte und schließen Sie mit dem verifizierten Ergebnis ab.
   • Bevorzugen Sie separate kurze Videos, wenn beide nützlich sind. Mischen Sie keine generische Produkterklärung und einen domänenspezifischen Fall, es sei denn, der Benutzer wünscht explizit einen kombinierten Walkthrough.
2. Erstellen Sie eine visuelle Referenz:
   • Wenn eine frühere Aufnahme existiert, prüfen Sie sie von Anfang bis Ende. Extrahieren Sie bei Bedarf ein Kontaktblatt und notieren Sie Tempo, Bildausschnitt, Anmerkungen und die stärksten erklärenden Momente.
   • Wenn es keine frühere Aufnahme gibt, verwenden Sie die @themoltnet/design-system-Bibliothek, die angrenzenden Dokumentationsmedien und die native Benutzeroberfläche des integrierten Produkts – in dieser Reihenfolge – um ein Standbild für die Titel-/Endkarte, das dichteste kommentierte UI-Standbild und ein Standbild für die Endkarte zu erstellen, bevor Sie aufnehmen. Diese genehmigten Standbilder werden zur Grundlage für spätere Videos der Serie.
3. Lesen Sie die Seite, auf der das Video erscheinen wird. Schreiben Sie eine kurze Shot-Liste, die das Benutzerergebnis, die erforderliche Einrichtung, die Hauptinteraktion, das Warte- oder Wiederholungsverhalten und das erfolgreiche Ergebnis benennt.
4. Wählen Sie das endgültige Seitenverhältnis und die Auflösung, bevor Sie die App anordnen. Bevorzugen Sie einen konventionellen 16:9-Rahmen wie 1440x810 oder 1920x1080.
5. Ordnen Sie die Anwendung so an, dass der vollständige beabsichtigte Inhaltsbereich in diesen Rahmen passt. Blenden Sie optionale Seitenleisten in der App aus, wenn nötig; entfernen Sie nicht die Hälfte einer Seitenleiste oder eines Bedienelements mit einem willkürlichen Nachbearbeitungszuschnitt.
6. Entscheiden Sie, ob der Browser-Chrome Teil der Komposition ist. Bevorzugen Sie eine saubere Browser-Viewport-Aufnahme. Wenn dies nicht verfügbar ist, behalten Sie das gesamte Browserfenster bei oder platzieren Sie es in einem bewussten Rahmen. Ein vollständiges Fenster ist sauberer als beschnittene Tabs, Ränder oder Anwendungsinhalte.
7. Überprüfen Sie die drei repräsentativen Stilrahmen in ihrer tatsächlichen Anzeigegröße. Nehmen Sie den vollständigen Walkthrough nicht auf, während das Überlagerungssystem, die Sicherheitsbereiche oder die Informationshierarchie noch erfunden werden.

Verwenden Sie einen sicheren Aufnahmebereich

• Nehmen Sie ein Anwendungsfenster oder einen Browser-Viewport auf, niemals ein Desktop-Rechteck, in das eine andere Anwendung eindringen kann.
• Identifizieren und sperren Sie die genaue Fensterkennung vor der Aufnahme. Überprüfen Sie sie nach der Navigation, Pop-Outs oder Anwendungsneustarts.
• Deaktivieren Sie Benachrichtigungen und verwenden Sie dedizierte Demo-Daten, verlassen Sie sich jedoch nicht auf diese Vorsichtsmaßnahmen als Privatsphärengrenze.
• Halten Sie Anmeldeinformationen, Token, persönliche Identifikatoren, private URLs und nicht zusammenhängende Kontodaten außerhalb der aufgenommenen Oberfläche. Passwortmaskierung ist notwendig, macht aber die Aufnahme von Anmeldeinformationen nicht wünschenswert.
• Machen Sie den Zeiger bewusst. Parken Sie ihn weg vom Text, während ein statisches Ergebnis gelesen wird.

Nehmen Sie zum Verständnis auf

• Verwenden Sie eine Idee pro Shot. Halten Sie wichtige Konfigurationen und Ergebnisse lang genug, um sie bei normaler Abspielgeschwindigkeit zu lesen.
• Zeigen Sie die Einrichtung nur, wenn sie dem Betrachter hilft, das Ergebnis zu reproduzieren. Bei Integrationsdemos bedeutet dies oft: installieren, authentifizieren ohne das Geheimnis preiszugeben, den Workflow importieren, ausführen und das Terminalergebnis inspizieren.
• Bevorzugen Sie native Anwendungszooms und Layoutänderungen gegenüber der nachträglichen Vergrößerung eines beschnittenen Rasters.
• Nehmen Sie die tatsächliche erfolgreiche Ausführung auf. Rekonstruierte Titel-/Endkarten und Anmerkungen können sie erklären, dürfen aber keine Aktion oder ein Ergebnis implizieren, das nicht beobachtet wurde.
• Eine zustandsgeführte Bearbeitung kann saubere Standbilder aus einem realen Durchlauf verwenden, wenn die Bewegung selbst nicht lehrreich ist. Behalten Sie die Zustände in der beobachteten Reihenfolge bei, bewahren Sie die sichtbaren Aufgabenbeweise und verwenden Sie Übergänge nur, um den Fortschritt zu kommunizieren.
• Schließen Sie die Erstellung von Anmeldeinformationen und Verbindungstests außerhalb des aufgenommenen Takes ab. Beginnen Sie die Erzählung aus einem sicheren, authentifizierten Zustand, es sei denn, die Einrichtung der Anmeldeinformationen ist selbst das dokumentierte Thema.
• Nehmen Sie kurze, unabhängig verwendbare Takes auf, wenn der Ablauf stabile Phasen hat. Dies begrenzt Neuaufnahmen und macht die Privatsphärenprüfung präziser.
• Bei einer langen Polling- oder Wiederholungsschleife bewahren Sie die tatsächlichen geordneten Zustände, beschleunigen oder trimmen Sie jedoch den wiederholten Leerlaufteil. Halten Sie die anfängliche Aktion, den endgültigen Workflow-Zustand und das akzeptierte Ergebnis mit lesbarer Geschwindigkeit.

Bearbeiten, ohne das Produkt zu verstecken

• Bewahren Sie jede beabsichtigte Anwendungskante. Skalieren Sie herunter und fügen Sie Abstände zum Auslieferungsrahmen hinzu, anstatt Inhalte zu beschneiden, um ein Seitenverhältnis zu erzwingen.
• Verwenden Sie Titel-/Endkarten nur, wenn sie die Orientierung oder nächsten Schritte verbessern.
• Halten Sie Einblendungen innerhalb eines vorab geplanten Sicherheitsbereichs. Sie dürfen keine Steuerelemente, Status, Ausgabe, Fehler oder Identifikatoren abdecken, die zum Verständnis des Ablaufs erforderlich sind.
• Lassen Sie bei Szenario-Demos die Anmerkungen mit der Ausführung fortschreiten. Nennen Sie die aktuelle Phase und erklären Sie ihre Konsequenz in einer kurzen Zeile, z. B. ABSICHT — Ort und Zeitrahmen extrahieren gefolgt von ABSICHT ABGESCHLOSSEN — Vorhersage abrufen. Verwenden Sie die tatsächlichen Phasennamen des Produkts und beobachtbaren Zustand; erzählen Sie keine verborgenen Überlegungen.
• Halten Sie ein Übersichtvideo visuell ruhiger als das zugehörige Szenario-Demo. Knotenbeschriftungen und native Statusindikatoren sollten die Erklärung tragen, wenn sie bereits ausreichen.
• Passen Sie die etablierte visuelle Sprache der Dokumentation an, wenn Sie ein vorhandenes Video ersetzen. Lassen Sie einen Ersatz nicht weniger bewusst wirken als das Asset, das er ersetzt.
• Für breite Browserkompatibilität: standardmäßig H.264 High, yuv420p, konstante 30 fps, kein Audio, es sei denn, eine Erzählung ist beabsichtigt, und MP4 Fast-Start.
• Bevorzugen Sie in dieser macOS-Toolchain, wenn praktikabel, die Single-Threaded-libx264 für die finale Ausgabe. Verwenden Sie das gebündelte Helfer-Skript anstelle von schneller Eingabesuche beim Extrahieren von QA-Frames mit exaktem Zeitstempel.
• Wenn ein Frame in einer Artefaktvorschau beschädigt erscheint, öffnen Sie das Prüfsummenstabile Artefakt erneut und inspizieren Sie das Video in einem nativen Player. Der Vorschaupfad hat gelegentlich identische Bildbytes unterschiedlich dargestellt; ändern Sie ein Video nicht, es sei denn, der Fehler ist unabhängig reproduzierbar.
• Wenn ein Frame bei normaler Wiedergabe und wiederholter Extraktion beschädigt bleibt, ersetzen Sie das betroffene Segment aus einer sauberen Quelle und codieren Sie den endgültigen Master mit -threads 1 neu.

Fügen Sie Audio nur hinzu, wenn es seinen Platz verdient

• Behalten Sie die stille Wiedergabe als Standard für eingebettete Dokumentationsvideos bei. Fügen Sie eine Erzählung hinzu, wenn sie material Timing, Kausalität oder Kontext erklärt, den prägnante visuelle Anmerkungen nicht leisten können.
• Schreiben und timen Sie die Erzählung gegen das gesperrte Bild. Untertitel oder ein Text-Transkript müssen dieselben Informationen bewahren, und das Video muss verständlich bleiben, wenn es stummgeschaltet ist.
• Verwenden Sie eine geklonte oder synthetische Stimme, die auf einer identifizierbaren Person modelliert ist, nur mit der ausdrücklichen Genehmigung dieser Person. Geben Sie an, dass die Stimme synthetisch ist, auf der umgebenden Seite oder im Abspann; präsentieren Sie sie nicht als authentische Live-Aufnahme.
• Halten Sie Sprachproben, Modelldateien und generierte Zwischenprodukte außerhalb des Repositorys, es sei denn, der Benutzer entscheidet sich ausdrücklich dafür, sie zu veröffentlichen. Behandeln Sie die Autorisierung zur Erstellung eines gesprochenen Demos als auf dieses Arbeitsergebnis beschränkt, nicht als fortlaufende Zustimmung für zukünftige Spracherzeugung.
• Führen Sie die Lieferungs-QA nach dem Multiplexen von Audio erneut durch. Überprüfen Sie Verständlichkeit, Pegel, Synchronisation, Untertitel, Kanalanordnung und dass der endgültige Container weiterhin der Videolieferungsspezifikation entspricht.

Überprüfen Sie das decodierte Auslieferungsergebnis

Führen Sie das gebündelte Helfer-Skript gegen die endgültige Datei aus, nicht gegen ein Zwischenprodukt:

.agents/skills/product-demo-recording/scripts/qa-video.sh \
  pfad/zum/endgueltigen.mp4 /private/tmp/demo-video-qa --interval 2 4 5 6

Das Hilfsskript schreibt Stream-Metadaten, ein sequentiell decodiertes Kontaktblatt und Start-/Mitte-/Ende- sowie angeforderte Zeitstempel-Frames als JPEGs. Verwenden Sie ein neues Ausgabeverzeichnis.

Führen Sie dann alle diese Prüfungen durch:

1. Sehen Sie sich das gesamte endgültige Video bei normaler Geschwindigkeit an.
2. Überprüfen Sie das Kontaktblatt auf jede Änderung der Anwendung, des Modals, des Shots, der Anmerkung und des Ergebniszustands.
3. Überprüfen Sie genaue Frames unmittelbar vor, an und nach jeder Schnittgrenze. Fügen Sie immer Zeitstempel hinzu, die im Überprüfungsfeedback genannt wurden; nehmen Sie nicht an, dass benachbarte Frames repräsentativ sind.
4. Bestätigen Sie, dass keine anderen Apps, Desktop-Bereiche, Benachrichtigungen, Anmeldeinformationen, private Daten, beschnittene Kanten, teilweiser Browser-Chrome, seltsame schwarze Ränder oder blockierte Steuerelemente vorhanden sind.
5. Bestätigen Sie, dass Text lesbar ist, die Cursorplatzierung ruhig ist, Übergänge sauber sind und das sichtbare Ergebnis mit der umgebenden Dokumentation übereinstimmt.
6. Überprüfen Sie Codec, Pixelformat, Abmessungen, Bildrate, Dauer, Audioauswahl und die Anforderung des schnellen Starts (Fast-Start) anhand der Auslieferungsspezifikation.

Beschreiben Sie die Aufnahme erst dann als überprüft, wenn diese Prüfungen an der genauen Datei durchgeführt wurden, die übertragen wird.

Bewusst ausliefern und aufbewahren

• Stufen Sie nur das endgültige Asset und die beabsichtigten Dokumentationsänderungen ein. Fügen Sie keine Roh-Takes, Anmeldeinformationen, Browserprofile oder QA-Exporte hinzu.
• Bewahren Sie Roh-Takes auf, bis die endgültige Datei überprüft und sicher übertragen oder hochgeladen wurde. Befolgen Sie dann die Aufbewahrungspräferenz des Betreibers; entfernen Sie sensible temporäre Aufnahmen explizit und nicht mit breiten Löschmustern.
• Geben Sie in der Übergabe an, was gezeigt wurde, die endgültigen technischen Eigenschaften, welche Zeitstempel geprüft wurden und wo sich das endgültige Asset befindet.