Enregistrement
Quand l'utiliser
Consultez cette compétence chaque fois que vous touchez à l'enregistreur : le bouton d'enregistrement, la barre d'outils en cours, les invites d'autorisation, le flux de téléchargement par segments ou la bulle caméra. Si vous ajoutez le support d'une nouvelle source (par ex., capture d'onglet, caméra de continuité iPhone) ou modifiez la façon dont les segments sont finalisés côté serveur, ceci est votre feuille de route.
Modèle de données concerné
recordings— la ligne est créée dès que l'utilisateur appuie sur Enregistrer ou importe une source. Les enregistrements natifs/fichiers transitent paruploading→processing→ready(oufailed).videoUrl,durationMs,videoSizeBytes,width,height,hasAudio,hasCamerasont renseignés au fur et à mesure du flux de téléchargement. Les importations Loom utilisentimport-loom-recordinget deviennent prêtes soit avec un MP4 hébergé par Clips, soit avec une intégration Loom lorsque l'export MP4 n'est pas disponible.application_state.record-intent— l'agent écrit ceci lorsqu'il veut démarrer un enregistrement. L'interface utilisateur le lit et l'efface, puis demande l'autorisation.application_state.navigation— défini à{ view: "record" }pendant que l'enregistreur est actif.
Les téléchargements binaires utilisent les routes API personnalisées (/api/uploads/:id/chunk et /api/uploads/:id/abort) plutôt que les actions, car les actions ne sont pas l'outil approprié pour les corps de flux binaires. Le dernier segment appelle finalize-recording. Les importations d'URL Loom sont uniquement des métadonnées et doivent passer par l'action import-loom-recording.
Certains enregistrements sont liés à une réunion — lorsque meeting_id n'est pas nul sur la ligne d'enregistrement, il a été créé via start-meeting-recording et les compétences recording et meetings s'appliquent toutes les deux. Voir la compétence meetings pour le lien bidirectionnel.
Cycle de vie
- Intention. Soit l'utilisateur clique sur Enregistrer (
Cmd+Maj+Lglobal), soit l'agent appellepnpm action start-recording --mode=screen. La version agent écritrecord-intentdans l'état de l'application ; l'interface utilisateur le détecte et lance le même flux qu'un clic utilisateur. - Autorisation. Appeler
navigator.mediaDevices.getDisplayMedia({ video, audio })pour l'écran,getUserMedia({ video, audio })pour la caméra. Ne pas demander sans un geste de l'utilisateur. Le chemin agent repose sur le bouton de l'interface utilisateur — nous ne contournons jamais le modèle d'autorisation du navigateur. - Créer la ligne. Dès que le flux est accordé, appeler
create-recordingpour insérer la ligne avecstatus: "uploading"et un identifiant pré-généré. Cet identifiant est utilisé pour chaque téléchargement de segment suivant. - Enregistrer. Démarrer un
MediaRecorderavecmimeType: "video/webm;codecs=vp9,opus"(repli sur vp8, puis sur la valeur par défaut du navigateur). Utilisertimeslice: 2000pour que les segments arrivent toutes les 2s. - Télécharger chaque segment.
ondataavailableenvoie les octets vers/api/uploads/chunkavec les en-têtesX-Recording-IdetX-Chunk-Index, tout en reflétant indépendamment les segments bruts versIndexedDBcomme sauvegarde au mieux. Un échec de livraison transitoire met en pause le téléchargement et reprend la source en mémoire uniquement pendant que l'onglet du navigateur actuel reste ouvert ; il n'y a pas de travailleur de renvoi en arrière-plan ni de promesse de récupération après fermeture d'onglet. Un échec d'écriture dansIndexedDBne bloque pas la capture ni le téléchargement. - Transcription en direct. Parallèlement au MediaRecorder,
useLiveTranscriptionexécute l'API Web Speech pour accumuler le texte de la transcription en temps réel. À l'arrêt, le client appellesave-browser-transcriptpour persister le résultat immédiatement — aucune clé API nécessaire. Les enregistrements de bureau utilisent d'abord Whisper local / la reconnaissance vocale macOS lorsque disponible, et se replient sur Web Speech dans la webview sur les non-Mac avant de dépendre de la transcription par téléchargement. - Finaliser. À l'arrêt, envoyer le segment final vers
/api/uploads/:id/chunk?isFinal=1. La route appellefinalize-recording, qui assemble les segments, rend le média accessible par défilement temporel (voir ci-dessous), télécharge le média terminé lorsque le stockage est configuré, fait passerstatusàready, puis lancerequest-transcriptpour une sortie de meilleure qualité (voirai-video-tools). - Naviguer immédiatement. Les enregistreurs de bureau ouvrent
/r/:iddès que l'arrêt commence la finalisation. La ligne d'enregistrement existe déjà, donc la page peut afficher le titre, le lien de partage et la progression du téléchargement pendant qu'elle interroge l'étatuploadingouprocessingjusqu'àready. N'attendez pas la réponse de téléchargement/finalisation avant d'ouvrir la page.
Cycle de vie du compagnon mobile
L'application mobile Agent-Native utilise les mêmes lignes d'enregistrement et routes de téléchargement binaire avec des primitives de capture natives :
- La vidéo/importation de la caméra utilise
expo-camera/ le sélecteur de photos système ; l'audio de réunion utiliseexpo-audioavec enregistrement en arrière-plan activé. - Le fichier natif est copié dans le répertoire de documents et un travail de capture AsyncStorage typé est écrit avant le début du téléchargement.
create-recordingreçoit un identifiant stable généré par le client,sourceAppName: "Agent-Native Mobile", et le type MIME du conteneur.- Le téléchargement lit au maximum 3 Mio via un FileHandle Expo et persiste l'index du segment suivant après chaque POST accusé réception. La limite serveur de 4 Mio s'applique toujours.
- La réconciliation au premier plan/reprise interroge
/api/uploads/:id/status; les échecs réessayables patientent et ne suppriment jamais le fichier local. La fin peut publier une notification locale et l'enregistrement apparaît partout dans Clips.
Le M4A audio mobile est un conteneur MP4 et utilise l'alias MIME MP4 de la route d'enregistrement. Les octets ne sont pas convertis ni chargés en mémoire JavaScript.
Comme le téléphone persiste chaque fichier audio/vidéo avant tout travail réseau et reprend les téléchargements de segments limités depuis sa file d'attente durable, une panne de téléchargement transitoire ne perd jamais la capture. Ne demandez pas aux utilisateurs de garder un écran de capture ouvert ou de ré-enregistrer après un échec de téléchargement ; dites-leur de reconnecter Clips et de réessayer le travail sauvegardé depuis l'accueil mobile.
La capture de réunion mobile est uniquement microphone ; ne prétendez jamais qu'elle a la fidélité microphone-plus-audio-système du bureau. Voir la compétence meetings pour ce que cela signifie pour l'attribution des participants.
Lecture accessible par défilement temporel (ne livrez pas la sortie brute de MediaRecorder)
Les fichiers bruts MediaRecorder ne sont pas adaptés à la lecture HTTP progressive, ce qui se manifeste par "le clip met des minutes à se charger" et "re-bufferise chaque fois que je cherche une position" même si le fichier se télécharge correctement :
- MP4 est écrit avec l'atome de métadonnées
moovaprèsmdat, donc un lecteur doit télécharger tout le fichier avant de pouvoir commencer ou chercher. - WebM est un flux en direct sans Cues (index de recherche) et avec une durée de Segment inconnue, donc Chrome n'honorera pas
currentTime = Xet devra analyser/télécharger.
finalize-recording corrige cela avant le téléchargement : MP4 obtient un faststart pur-TS (server/lib/faststart.ts), WebM obtient un remux ffmpeg -c copy sans perte qui écrit un SeekHead + Cues + une durée réelle (server/lib/video-remux.ts). Les deux sont au mieux — en cas d'échec, nous téléchargeons l'original, ne bloquons jamais la finalisation. Les enregistrements au-dessus de CLIPS_INLINE_REMUX_MAX_BYTES (défaut 200 Mo) sautent le passage en ligne et sont réparés en arrière-plan.
Le chemin de téléchargement streaming/resumable transmet les octets bruts directement au fournisseur et ne peut pas les réécrire en ligne, donc finalize-recording planifie un passage en arrière-plan ensureRecordingSeekable pour ceux-ci.
Pour réparer les clips téléchargés avant cela (ou via streaming), appelez l'action reprocess-recording : --id, --ids='[...]', ou --all --limit=N. Elle récupère le média du fournisseur, le réécrit, le retélécharge et repointe la ligne. Elle est idempotente (les clips déjà accessibles par défilement sont ignorés sauf --force) et ne touche que les clips hébergés par le fournisseur appartenant à l'appelant. C'est l'outil approprié lorsqu'un utilisateur signale un clip lent/un buffering spécifique.
Le remux d'accessibilité par défilement temporel ne peut pas réparer un enregistrement dont l'audio continue tandis que la piste vidéo a un grand écart temporel (courant lorsqu'un navigateur mobile suspend la caméra après que l'utilisateur change d'application). Pour un clip qui se fige ou semble s'arrêter avant sa durée déclarée, appelez reprocess-recording avec --normalizeTimeline=true. Ce mode explicite utilise le même flux de récupération et téléchargement limité au propriétaire mais transcode entièrement en un MP4 faststart à 30 images par seconde constantes (H.264 + AAC). Il préserve l'audio et duplique la dernière image vidéo décodée à travers les lacunes d'images manquantes. L'action télécharge vers un nouvel objet média et repointe atomiquement la ligne seulement après que la sortie vérifiée est stockée ; tout échec de transcodage, vérification audio, téléchargement ou mise à jour concurrente laisse l'URL et le format d'origine intacts.
Importation Loom
Utilisez import-loom-recording pour les URLs de partage ou d'intégration Loom. L'action valide l'URL Loom, lit les métadonnées Loom oEmbed depuis le point de terminaison public de Loom, et crée un enregistrement ready avec l'URL d'intégration Loom, la vignette, le titre, la durée et les dimensions. Lorsque Loom expose une URL de transcription publique signée au format JSON sur la page de partage, l'action importe cette transcription dans Clips et stocke des segments normalisés ; ne stockez jamais les URLs CDN signées de Loom.
Lorsque Loom expose un MP4 public téléchargeable, import-loom-recording le télécharge, retélécharge les octets vers le stockage Clips, et crée un enregistrement prêt et lisible hébergé par Clips, important la transcription publique de Loom lorsque la page de partage en expose une. Si Loom permet la lecture publique mais n'expose pas de MP4, l'action conserve un enregistrement prêt avec intégration et importe toujours la transcription lorsque disponible.
Les importations Loom avec intégration rendent un iframe Loom et masquent l'éditeur natif Clips. Les importations Loom retéléchargées supportent le rognage natif Clips, les exports, l'extraction d'images et la transcription par téléchargement ; demandez à l'utilisateur de télécharger le fichier vidéo original lorsque ces capacités sont nécessaires pour une importation avec intégration.
Diagnostics navigateur et options d'installation de l'enregistreur
Les enregistrements navigateur peuvent sauvegarder des diagnostics limités et expurgés via createBrowserDiagnosticsCapture : messages console plus méthode fetch/XHR, URL, statut, durée et erreurs. L'enregistreur navigateur ne capture que l'activité de la page d'enregistrement elle-même. L'extension Chrome Clips est le chemin pour les logs d'onglet actif : elle lance /record avec une session de capture d'extension et passe developerLogs=1/0, puis sauvegarde les diagnostics avec la source extension.
La fiche du Chrome Web Store est active, donc l'option publique de l'extension Chrome s'affiche par défaut. Les invites UI qui disent sinon "Télécharger l'application de bureau" utilisent le composant de choix d'installation partagé (CaptureInstallButton / CaptureInstallInlineLink) pour offrir deux options : extension Chrome pour les logs navigateur, et application de bureau pour la capture native la plus fluide. Définissez VITE_CLIPS_CHROME_EXTENSION_ENABLED=0 pour masquer à nouveau l'option Chrome, ou VITE_CLIPS_CHROME_EXTENSION_URL pour pointer vers une autre fiche.
save-browser-diagnostics est UI/interne. Il stocke les logs console limités plus la méthode fetch/XHR, le chemin URL/clés de requête, le statut et la durée. Il ne capture jamais les en-têtes, corps, cookies ou valeurs de requête URL réseau. Le texte console conserve les valeurs utiles non secrètes tout en expurgeant les clés et en-têtes ressemblant à des identifiants. Utilisez get-recording-player-data pour la charge utile de diagnostic complète lorsque vous avez un accès éditeur ; voir la compétence video-sharing pour le flux expurgé plus restreint que le contexte public de l'agent expose.
Extension Chrome
L'extension se trouve dans chrome-extension/. Elle lance /record avec clipsExtensionId et clipsCaptureSessionId, et l'enregistreur renvoie CLIPS_CAPTURE_START / CLIPS_CAPTURE_STOP / CLIPS_CAPTURE_CANCEL à l'extension. Elle utilise l'API debugger de Chrome uniquement sur l'onglet depuis lequel l'utilisateur a lancé, uniquement pendant qu'un enregistrement est actif, et renvoie la même forme de diagnostics expurgés sauvegardés par save-browser-diagnostics.
L'extension améliore également le markdown des issues et PR GitHub : un script de contenu restreint github.com détecte les liens Clips /r/, /share/ et /embed/, puis affiche le lecteur existant /embed/:id dans un iframe d'aperçu appartenant à l'extension afin que la vidéo soit lisible sans quitter GitHub. Maintenez cela limité à GitHub sauf en cas de révision de permission délibérée.
Dossiers, espaces et déplacements en masse
Utilisez move-recording pour les déplacements de dossiers uniques et en masse. Passez id pour un clip ou ids pour les clips sélectionnés, et folderId: null pour les déplacer vers la bibliothèque ou la racine de l'espace.
Captures d'écran
Une capture d'écran est une ligne recordings avec kind = "image" (isImageRecording dans shared/recording-kind.ts). Elle partage les dossiers, espaces, partage, commentaires et recherche avec les clips, et n'a aucune des parties vidéo : pas de transcription, chapitres, filmstrip, chronologie ou audio. list-recordings --kind=image les liste.
- La capture, l'annotation et l'expurgation sont des travaux du navigateur (
create-screenshot,save-screenshot-edits, tous UI-uniquement). L'agent lit une capture d'écran viaget-recording-player-dataou/api/agent-frame.jpg, qui renvoie l'image elle-même pour toutatMs. imageUrlest l'image servie ;baseImageUrlest la base non marquée sur laquelle un éditeur dessine. Les deux sont servis via/api/thumbnail/:id, qui applique le mot de passe, l'expiration et la restriction d'expurgation. Ne distribuez jamais les URLs de stockage.- L'expurgation est en deux étapes, comme pour la vidéo : les boîtes sont sauvegardées comme superpositions en attente (retenues des spectateurs), puis intégrées. Une intégration écrit
editsJson.burnInProgressavant de supprimer l'original et l'efface après ;unreclaimedUrlsliste les copies plus anciennes pas encore supprimées. Les deux sont serveur-uniquement (server/lib/screenshot-edits.ts) et ne doivent jamais atteindre un spectateur. - Les actions d'édition vidéo refusent les captures d'écran à
assertNativeRecordingMedia; seulsave-screenshot-editsécrit leeditsJsond'une capture d'écran.
Pause / Reprise
MediaRecorder.pause() / .resume() sont supportés dans tous les navigateurs modernes. Gardez une seule instance MediaRecorder à travers les pauses — ne détruisez pas le flux, sinon l'invite d'autorisation se déclenchera à nouveau. Pendant la pause, le travailleur de téléchargement continue de vider son tampon afin de rattraper avant que l'utilisateur n'arrête.
Bulle caméra
Lorsque le mode est screen+camera, "la bulle" est deux choses différentes :
- Auto-vue à l'écran.
CameraBubbleaffiche un élément<video>simple non enregistré que l'utilisateur fait glisser pour se cadrer pendant le compte à rebours/l'enregistrement. Il n'est jamais capturé — c'est juste une UI de cadrage local. - Composite enregistré. La capture d'écran ne peut pas inclure cet élément DOM une fois que l'utilisateur enregistre une autre fenêtre/application, donc la vidéo sauvegardée doit incorporer le cercle de la caméra avant que le MediaRecorder...