Communitygithub.com

BuilderIO/agent-native

Cómo funciona la grabación de pantalla y cámara en Clips: ciclo de vida de MediaRecorder, subida por fragmentos, manejo de permisos, pausa/reanudación, superposición de burbuja de cámara, recuperación de errores y capturas de pantalla (grabaciones de imagen fija). Úsalo al agregar o modificar la UI del grabador, el endpoint de subida, los avisos de permiso o cualquier cosa que maneje una captura de pantalla.

¿Qué es agent-native?

Esta habilidad proporciona una guía completa y detallada sobre el sistema de grabación en Clips, cubriendo tanto la grabación de pantalla como la de cámara. Explica el ciclo de vida completo desde la intención de grabar hasta la finalización y reproducción, incluyendo el manejo de permisos, la subida por fragmentos, la transcripción en vivo y la creación de capturas de pantalla. Es esencial para cualquier desarrollador que trabaje en la interfaz de usuario del grabador, la lógica de subida, los permisos o el procesamiento posterior de grabaciones. La habilidad detalla las rutas de API personalizadas para la subida binaria, la lógica de finalización que hace que los archivos sean reproducibles de forma progresiva, y cómo manejar diferentes fuentes como la cámara, la pantalla del escritorio o la aplicación móvil. También cubre la importación desde Loom, el diagnóstico del navegador y la integración con la extensión de Chrome, asegurando que cualquier modificación al sistema de grabación esté bien informada y sea coherente.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/BuilderIO/agent-native/tree/HEAD/templates/clips/.agents/skills/recording

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Grabación

Cuándo usarlo

Recurre a esta habilidad cada vez que toques el grabador: el botón de grabar, la barra de herramientas en curso, los avisos de permiso, el flujo de subida por fragmentos o la burbuja de cámara. Si estás agregando soporte para una nueva fuente (por ejemplo, captura de pestañas, cámara de continuidad de iPhone) o cambiando cómo se finalizan los fragmentos en el servidor, este es tu mapa.

Modelo de datos afectado

  • recordings: la fila se crea tan pronto como el usuario presiona Grabar o importa una fuente. Las grabaciones nativas/de archivo hacen la transición uploading → processing → ready (o failed). videoUrl, durationMs, videoSizeBytes, width, height, hasAudio, hasCamera se completan a medida que la subida se transmite. Las importaciones de Loom usan import-loom-recording y se vuelven listas ya sea con un MP4 alojado en Clips o con un embed de Loom cuando la exportación MP4 no está disponible.
  • application_state.record-intent: el agente escribe esto cuando quiere iniciar una grabación. La UI lo lee y lo limpia, luego solicita permiso.
  • application_state.navigation: se establece en { view: "record" } mientras el grabador está activo.

Las subidas binarias usan las rutas personalizadas de la API (/api/uploads/:id/chunk y /api/uploads/:id/abort) en lugar de acciones, porque las acciones no son la herramienta adecuada para cuerpos de transmisión binaria. El fragmento final llama a finalize-recording. Las importaciones de URL de Loom son solo de metadatos y deben pasar por la acción import-loom-recording.

Algunas grabaciones están vinculadas a una reunión; cuando meeting_id no es nulo en la fila de grabación, se creó mediante start-meeting-recording y se aplican tanto la habilidad recording como meetings. Consulta la habilidad meetings para el enlace bidireccional.

Ciclo de vida

  1. Intención. Ya sea que el usuario haga clic en Grabar (global Cmd+Shift+L) o el agente llame a pnpm action start-recording --mode=screen. La versión del agente escribe record-intent en el estado de la aplicación; la UI lo recoge e inicia el mismo flujo que un clic de usuario.
  2. Permiso. Llama a navigator.mediaDevices.getDisplayMedia({ video, audio }) para la pantalla, getUserMedia({ video, audio }) para la cámara. No solicites permiso sin un gesto del usuario. La ruta del agente depende del botón de la UI; nunca eludimos el modelo de permisos del navegador.
  3. Crear fila. Tan pronto como se concede el flujo, llama a create-recording para insertar la fila con status: "uploading" y un id pregenerado. Ese id se usa para cada subida de fragmento posterior.
  4. Grabar. Inicia un MediaRecorder con mimeType: "video/webm;codecs=vp9,opus" (recurre a vp8, luego al predeterminado del navegador). Usa timeslice: 2000 para que los fragmentos lleguen cada 2s.
  5. Subir cada fragmento. ondataavailable transmite bytes a /api/uploads/chunk con los encabezados X-Recording-Id y X-Chunk-Index, mientras que de forma independiente refleja los fragmentos sin procesar en IndexedDB como una copia de seguridad de mejor esfuerzo. Una falla de entrega transitoria pausa la subida y reanuda la fuente en memoria solo mientras la pestaña actual del navegador permanezca abierta; no hay un trabajador de reenvío en segundo plano ni una promesa de recuperación de pestaña cerrada. Una falla de escritura en IndexedDB no bloquea la captura ni la subida.
  6. Transcripción en vivo. Junto con MediaRecorder, useLiveTranscription ejecuta la API Web Speech para acumular texto de transcripción en tiempo real. Al detenerse, el cliente llama a save-browser-transcript para persistir el resultado de inmediato, sin necesidad de clave API. Las grabaciones de escritorio usan primero Whisper local/reconocimiento de voz de macOS cuando está disponible, y recurren a Web Speech en la vista web en sistemas que no son Mac antes de depender de la transcripción de subida.
  7. Finalizar. Al detenerse, envía el fragmento final a /api/uploads/:id/chunk?isFinal=1. La ruta llama a finalize-recording, que une los fragmentos, hace que el medio sea buscable (ver más abajo), sube el medio terminado cuando el almacenamiento está configurado, hace la transición de status a ready, y luego inicia request-transcript para una salida de mayor calidad (consulta ai-video-tools).
  8. Navegar inmediatamente. Los grabadores de escritorio abren /r/:id tan pronto como Stop inicia la finalización. La fila de grabación ya existe, por lo que la página puede mostrar el título, el enlace para compartir y el progreso de la subida mientras sondea desde uploading o processing hasta ready. No esperes la respuesta de subida/finalización antes de abrir la página.

Ciclo de vida del acompañante móvil

La aplicación móvil de Agent-Native usa las mismas filas de grabación y rutas de subida binaria con primitivas de captura nativas:

  1. El video/importación de cámara usa expo-camera / el selector de fotos del sistema; el audio de reunión usa expo-audio con grabación en segundo plano habilitada.
  2. El archivo nativo se copia en el directorio de documentos y se escribe un trabajo de captura de AsyncStorage con tipo antes de que comience la subida.
  3. create-recording recibe un id estable generado por el cliente, sourceAppName: "Agent-Native Mobile" y el tipo MIME del contenedor.
  4. La subida lee como máximo 3 MiB a través de un Expo FileHandle y persiste el siguiente índice de fragmento después de cada POST confirmado. El límite del servidor de 4 MiB todavía se aplica.
  5. La reconciliación de primer plano/reanudación sondea /api/uploads/:id/status; los fallos reintentables retroceden y nunca descartan el archivo local. La finalización puede publicar una notificación local y la grabación aparece en Clips en todas partes.

El audio móvil M4A es un contenedor MP4 y usa el alias MIME MP4 de la ruta de grabación. Los bytes no se convierten ni se cargan completos en la memoria de JavaScript.

Debido a que el teléfono persiste cada archivo de audio/video antes de cualquier trabajo de red y reanuda las subidas de fragmentos limitados desde su cola duradera, una falla de subida transitoria nunca pierde la captura. No pidas a los usuarios que mantengan abierta una pantalla de captura o que vuelvan a grabar después de una subida fallida; diles que reconecten Clips y reintenten el trabajo guardado desde la pantalla de inicio móvil.

La captura de reuniones móviles es solo de micrófono; nunca afirmes que tiene la fidelidad de micrófono más audio del sistema del escritorio. Consulta la habilidad meetings para saber lo que eso significa para la atribución de asistentes.

Reproducción buscable (no envíes la salida sin procesar de MediaRecorder)

Los archivos sin procesar de MediaRecorder no son amigables para la reproducción HTTP progresiva, lo que se manifiesta como "el clip tarda minutos en cargarse" y "se vuelve a almacenar en búfer cada vez que busco" aunque el archivo se descargue bien:

  • MP4 se escribe con el átomo de metadatos moov después de mdat, por lo que un reproductor debe obtener todo el archivo antes de poder comenzar o buscar.
  • WebM es una transmisión en vivo sin Cues (índice de búsqueda) y una duración de Segmento desconocida, por lo que Chrome no respetará currentTime = X y tendrá que escanear/descargar.

finalize-recording soluciona esto antes de la subida: MP4 obtiene faststart de TypeScript puro (server/lib/faststart.ts), WebM obtiene un re-multiplexado sin pérdidas ffmpeg -c copy que escribe un SeekHead + Cues + duración real (server/lib/video-remux.ts). Ambos son de mejor esfuerzo; en caso de fallo, subimos el original, nunca bloqueamos la finalización. Las grabaciones por encima de CLIPS_INLINE_REMUX_MAX_BYTES (predeterminado 200 MB) omiten el paso en línea y se reparan en segundo plano.

La ruta de subida streaming/resumable reenvía los bytes sin procesar directamente al proveedor y no puede reescribirlos en línea, por lo que finalize-recording programa un pase en segundo plano ensureRecordingSeekable para esos.

Para reparar clips subidos antes de que esto existiera (o a través de streaming), llama a la acción reprocess-recording: --id, --ids='[...]', o --all --limit=N. Vuelve a buscar el medio del proveedor, lo reescribe, lo vuelve a subir y re-apunta la fila. Es idempotente (los clips ya buscables se omiten a menos que --force) y solo toca los clips alojados por el proveedor que pertenecen al que llama. Esta es la herramienta adecuada cuando un usuario reporta un clip específico lento/con almacenamiento en búfer.

El re-multiplexado de capacidad de búsqueda no puede reparar una grabación cuyo audio continúa mientras la pista de video tiene un gran espacio de marca de tiempo (común cuando un navegador móvil suspende la cámara después de que el usuario cambia de aplicación). Para un clip que se congela o parece detenerse antes de su duración declarada, llama a reprocess-recording con --normalizeTimeline=true. Ese modo explícito usa el mismo flujo de búsqueda y subida con ámbito del propietario, pero transcodifica completamente a un MP4 faststart de 30 fps constantes (H.264 + AAC). Preserva el audio y duplica el último fotograma de video decodificado en los espacios de fotogramas faltantes. La acción sube a un nuevo objeto multimedia y re-apunta la fila de forma atómica solo después de que se almacena la salida verificada; cualquier fallo de transcodificación, verificación de audio, subida o actualización concurrente deja la URL y el formato originales intactos.

Importación de Loom

Usa import-loom-recording para URLs de Loom compartidas o embebidas. La acción valida la URL de Loom, lee los metadatos de oEmbed de Loom desde el endpoint público de Loom y crea una grabación ready con la URL de embed de Loom, miniatura, título, duración y dimensiones. Cuando Loom expone una URL JSON de transcripción pública firmada en la página para compartir, la acción importa esa transcripción a Clips y almacena segmentos normalizados; nunca almacenes las URL de CDN firmadas de Loom.

Cuando Loom expone un MP4 público descargable, import-loom-recording lo descarga, vuelve a subir los bytes al almacenamiento de Clips y crea una grabación lista y reproducible alojada en Clips, importando la transcripción pública de Loom cuando la página para compartir la expone. Si Loom permite la reproducción pública pero no expone un MP4, la acción mantiene una grabación lista respaldada por embed y aún importa la transcripción cuando está disponible.

Las importaciones de Loom respaldadas por embed renderizan un iframe de Loom y ocultan el editor nativo de Clips. Las importaciones de Loom vueltas a subir admiten recorte nativo de Clips, exportaciones, extracción de fotogramas y transcripción basada en subida; pide al usuario que suba el archivo de video original cuando se necesiten esas capacidades para una importación respaldada por embed.

Diagnóstico del navegador y opciones de instalación del grabador

Las grabaciones del navegador pueden guardar diagnósticos limitados y redactados a través de createBrowserDiagnosticsCapture: mensajes de la consola más método de fetch/XHR, URL, estado, duración y errores. El grabador del navegador solo captura la actividad de la propia página del grabador. La extensión de Chrome de Clips es la ruta de pestaña activa para los registros del navegador: inicia /record con una sesión de captura de extensión y pasa developerLogs=1/0, luego guarda los diagnósticos con la fuente extension.

El listado de Chrome Web Store está activo, por lo que la opción pública de la extensión de Chrome se muestra de forma predeterminada. Los avisos de UI que de otro modo dirían "Descargar aplicación de escritorio" usan el componente compartido de elección de instalación (CaptureInstallButton / CaptureInstallInlineLink) para ofrecer dos opciones: extensión de Chrome para registros del navegador y aplicación de escritorio para la captura nativa más fluida. Establece VITE_CLIPS_CHROME_EXTENSION_ENABLED=0 para ocultar la opción de Chrome nuevamente, o VITE_CLIPS_CHROME_EXTENSION_URL para apuntar a un listado diferente.

save-browser-diagnostics es de UI/interno. Almacena registros de consola limitados más método de fetch/XHR, ruta URL/claves de consulta, estado y duración. Nunca captura encabezados, cuerpos, cookies o valores de URL de consulta de red. El texto de la consola mantiene valores no secretos útiles mientras redacta claves y encabezados de apariencia credencial. Usa get-recording-player-data para la carga útil de diagnóstico completa cuando tengas acceso de editor; consulta la habilidad video-sharing para la transmisión redactada más estrecha que expone el contexto público del agente.

Extensión de Chrome

La extensión se encuentra en chrome-extension/. Inicia /record con clipsExtensionId y clipsCaptureSessionId, y el grabador envía CLIPS_CAPTURE_START / CLIPS_CAPTURE_STOP / CLIPS_CAPTURE_CANCEL de vuelta a la extensión. Usa la API de depuración de Chrome solo en la pestaña desde la que el usuario inició, solo mientras una grabación está activa y devuelve la misma forma de diagnóstico redactada guardada por save-browser-diagnostics.

La extensión también mejora el markdown de issues y PRs de GitHub: un script de contenido estrecho de github.com detecta enlaces de Clips /r/, /share/ y /embed/, luego renderiza el reproductor existente de /embed/:id en un iframe de vista previa propiedad de la extensión para que el video se pueda reproducir sin salir de GitHub. Mantén esto limitado a GitHub a menos que haya una revisión de permisos deliberada.

Carpetas, espacios y movimientos masivos

Usa move-recording tanto para movimientos de carpeta individuales como masivos. Pasa id para un clip o ids para los clips seleccionados, y folderId: null para moverlos a la biblioteca o raíz del espacio.

Capturas de pantalla

Una captura de pantalla es una fila de recordings con kind = "image" (isImageRecording en shared/recording-kind.ts). Comparte carpetas, espacios, uso compartido, comentarios y búsqueda con los clips, y no tiene ninguna de las partes de video: sin transcripción, capítulos, tira de película, línea de tiempo ni audio. list-recordings --kind=image las lista.

  • La captura, anotación y redacción son trabajo del navegador (create-screenshot, save-screenshot-edits, ambas solo de UI). El agente lee una captura de pantalla a través de get-recording-player-data o /api/agent-frame.jpg, que devuelve la imagen en sí para cualquier atMs.
  • imageUrl es la imagen servida; baseImageUrl es la base sin marcas sobre la que dibuja un editor. Ambos se sirven a través de /api/thumbnail/:id, que aplica la contraseña, caducidad y retención de redacción. Nunca entregues las URLs de almacenamiento.
  • La redacción es de dos pasos, como para video: los cuadros se guardan como superposiciones pendientes (retenidas de los espectadores), luego se queman. Una quema escribe editsJson.burnInProgress antes de eliminar el original y lo limpia después; unreclaimedUrls enumera copias más antiguas aún no eliminadas. Ambos son solo del servidor (server/lib/screenshot-edits.ts) y nunca deben llegar a un espectador.
  • Las acciones de edición de video rechazan capturas de pantalla en assertNativeRecordingMedia; solo save-screenshot-edits escribe el editsJson de una captura de pantalla.

Pausa / reanudar

MediaRecorder.pause() / .resume() son compatibles en todos los navegadores modernos. Mantén una única instancia de MediaRecorder durante las pausas; no destruyas el flujo, o el aviso de permiso se activará de nuevo. Mientras está en pausa, el trabajador de subida sigue drenando su búfer para que nos pongamos al día antes de que el usuario se detenga.

Burbuja de cámara

Cuando el modo es screen+camera, "la burbuja" son dos cosas diferentes:

  • Vista propia en pantalla. CameraBubble renderiza un elemento <video> simple, no grabado, que el usuario arrastra para encuadrarse durante la cuenta atrás/grabación. Nunca se captura, es solo UI de encuadre local.
  • Compuesto grabado. La captura de pantalla no puede incluir ese elemento DOM una vez que el usuario graba otra ventana/aplicación, por lo que el video guardado debe incrustar el círculo de cámara antes de que MediaRecorder lo capture. La implementación renderiza la vista propia de cámara en un <canvas> separado fuera de la pantalla usando drawImage en un intervalo (cada 100 ms) y combina ese canvas con la captura de pantalla usando un segundo canvas. Eso es costoso de procesador, pero es la única forma de obtener un círculo de cámara limpio sin instalar software de sistema. En macOS, la aplicación de escritorio usa la API de ReplayKit createsOutputContextWithPixelBufferAttributes, que puede incrustar la cámara sin la sobrecarga del canvas.

Skills relacionados