Communitygithub.com

BuilderIO/agent-native

Como a gravação de tela e câmera funciona no Clips — ciclo de vida do MediaRecorder, upload em blocos, tratamento de permissões, pausa/retomada, sobreposição da bolha da câmera, recuperação de erros e capturas de tela (gravações de imagem estática). Use ao adicionar ou modificar a IU do gravador, o endpoint de upload, os prompts de permissão ou qualquer coisa que manipule uma captura de tela.

O que é agent-native?

Este skill documenta detalhadamente o sistema de gravação do Clips (parte do ecossistema Agent-Native), cobrindo desde a captura de tela e câmera até o upload, transcrição e reprodução. Ele explica o ciclo de vida completo do MediaRecorder, a lógica de upload em blocos com fallback para IndexedDB, o tratamento de permissões, pausa/retomada, a sobreposição da bolha da câmera, capturas de tela (imagens estáticas), importação de vídeos do Loom e integração com reuniões. O skill é essencial para desenvolvedores que trabalham na IU do gravador, no fluxo de upload, na finalização de gravações e na garantia de playback seekable (através de remux MP4 e WebM). Também abrange o aplicativo móvel companion, o fluxo de diagnóstico do navegador (com extensão Chrome) e a funcionalidade de redimensionamento de pastas/bulk moves. As plataformas suportadas incluem web, desktop (com microfone e áudio do sistema) e mobile (com captura de áudio e vídeo via Expo). O diagrama de arquivos e rotas (SKILL.md) orienta o desenvolvedor a não pular etapas críticas, como a criação da linha de registro antes do upload e a navegação imediata para a página de reprodução, tornando-o um mapa indispensável para qualquer modificação no sistema de gravação.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Gravação

Quando usar

Recorra a este skill sempre que você mexer no gravador: o botão de gravação, a barra de ferramentas em andamento, os prompts de permissão, o fluxo de upload em blocos ou a bolha da câmera. Se você estiver adicionando suporte para uma nova fonte (ex.: captura de aba, câmera de continuidade do iPhone) ou alterando como os blocos são finalizados no servidor, este é o seu mapa.

Modelo de dados tocado

  • recordings — a linha é criada assim que o usuário pressiona Gravar ou importa uma fonte. Gravações nativas/de arquivo fazem a transição uploading → processing → ready (ou failed). videoUrl, durationMs, videoSizeBytes, width, height, hasAudio, hasCamera são populados à medida que o upload flui. Importações do Loom usam import-loom-recording e tornam-se ready com um MP4 hospedado no Clips ou um embed do Loom quando a exportação MP4 não está disponível.
  • application_state.record-intent — o agente escreve isso quando deseja iniciar uma gravação. A UI lê e limpa, e então solicita permissão.
  • application_state.navigation — definido como { view: "record" } enquanto o gravador está ativo.

Uploads binários atingem as rotas customizadas da API (/api/uploads/:id/chunk e /api/uploads/:id/abort) em vez de ações, porque ações não são a ferramenta certa para corpos de streaming binário. O bloco final chama finalize-recording. Importações de URL do Loom são apenas metadados e devem passar pela ação import-loom-recording.

Algumas gravações estão vinculadas a uma reunião — quando meeting_id não é nulo na linha da gravação, ela foi criada via start-meeting-recording e ambos os skills recording e meetings se aplicam. Consulte o skill meetings para o link bidirecional.

Ciclo de vida

  1. Intenção. O usuário clica em Gravar (global Cmd+Shift+L) ou o agente chama pnpm action start-recording --mode=screen. A versão do agente escreve record-intent no estado da aplicação; a UI captura e inicia o mesmo fluxo de um clique do usuário.
  2. Permissão. Chame navigator.mediaDevices.getDisplayMedia({ video, audio }) para tela, getUserMedia({ video, audio }) para câmera. Não solicite sem um gesto do usuário. O caminho do agente depende do botão da UI — nunca ignoramos o modelo de permissão do navegador.
  3. Criar linha. Assim que o stream é concedido, chame create-recording para inserir a linha com status: "uploading" e um id pré-gerado. Esse id é usado para cada upload de bloco subsequente.
  4. Gravar. Inicie um MediaRecorder com mimeType: "video/webm;codecs=vp9,opus" (fallback para vp8, depois o padrão do navegador). Use timeslice: 2000 para que os blocos cheguem a cada 2s.
  5. Enviar cada bloco. ondataavailable envia bytes para /api/uploads/chunk com os cabeçalhos X-Recording-Id e X-Chunk-Index, enquanto espelha independentemente blocos brutos no IndexedDB como um backup de melhor esforço. Uma falha de entrega transitória pausa o upload e retoma a fonte em memória apenas enquanto a aba atual do navegador permanecer aberta; não há worker de reenvio em segundo plano ou promessa de recuperação de aba fechada. Uma falha de gravação no IndexedDB não bloqueia a captura ou o upload.
  6. Transcrição ao vivo. Junto com o MediaRecorder, useLiveTranscription executa a Web Speech API para acumular texto da transcrição em tempo real. Ao parar, o cliente chama save-browser-transcript para persistir o resultado imediatamente — nenhuma chave de API necessária. Gravações de desktop usam local Whisper/fala do macOS primeiro, quando disponível, e recorrem à Web Speech no webview em não-mac antes de depender da transcrição por upload.
  7. Finalizar. Ao parar, envie o bloco final para /api/uploads/:id/chunk?isFinal=1. A rota chama finalize-recording, que une os blocos, torna a mídia buscável (veja abaixo), faz o upload da mídia finalizada quando o armazenamento está configurado, faz a transição do status para ready, e então inicia request-transcript para saída de maior qualidade (veja ai-video-tools).
  8. Navegar imediatamente. Gravadores de desktop abrem /r/:id assim que o Stop inicia a finalização. A linha da gravação já existe, então a página pode mostrar o título, link de compartilhamento e progresso do upload enquanto faz polling de uploading ou processing para ready. Não aguarde a resposta de upload/finalização antes de abrir a página.

Ciclo de vida do aplicativo móvel companion

O aplicativo móvel Agent-Native usa as mesmas linhas de gravação e rotas de upload binário com primitivas nativas de captura:

  1. Vídeo da câmera/importação usa expo-camera / o seletor de fotos do sistema; áudio de reunião usa expo-audio com gravação em segundo plano ativada.
  2. O arquivo nativo é copiado para o diretório de documentos e um trabalho de captura de AsyncStorage tipado é escrito antes do upload começar.
  3. create-recording recebe um id estável gerado pelo cliente, sourceAppName: "Agent-Native Mobile" e o tipo MIME do contêiner.
  4. O upload lê no máximo 3 MiB através de um Expo FileHandle e persiste o índice do próximo bloco após cada POST confirmado. O limite do servidor de 4 MiB ainda se aplica.
  5. Reconciliação em primeiro plano/retomada faz polling de /api/uploads/:id/status; falhas repetíveis fazem backoff e nunca descartam o arquivo local. A conclusão pode postar uma notificação local e a gravação aparece em todos os lugares no Clips.

O áudio móvel M4A é um contêiner MP4 e usa o alias MIME MP4 da rota de gravação. Os bytes não são convertidos ou carregados inteiros na memória JavaScript.

Como o telefone persiste cada arquivo de áudio/vídeo antes de qualquer trabalho de rede e retoma uploads de blocos limitados de sua fila durável, uma falha de upload transitória nunca perde a captura. Não peça aos usuários que mantenham uma tela de captura aberta ou que regravem após um upload com falha; diga a eles para reconectar o Clips e tentar novamente o trabalho salvo na tela inicial do celular.

A captura de reunião móvel é apenas microfone; nunca afirme que ela tem a fidelidade de microfone mais áudio do sistema do desktop. Consulte o skill meetings para saber o que isso significa para a atribuição de participantes.

Reprodução buscável (não envie saída bruta do MediaRecorder)

Arquivos brutos do MediaRecorder não são amigáveis para reprodução HTTP progressiva, o que se manifesta como "o clipe leva minutos para carregar" e "rebuffers toda vez que busco" mesmo que o arquivo faça download normalmente:

  • MP4 é escrito com o átomo de metadados moov após mdat, então um player precisa buscar o arquivo inteiro antes de começar ou buscar.
  • WebM é um stream ao vivo sem Cues (índice de busca) e uma duração de Segmento desconhecida, então o Chrome não honra currentTime = X e tem que escanear/baixar.

finalize-recording conserta isso antes do upload: MP4 recebe faststart puro-TS (server/lib/faststart.ts), WebM recebe um remux ffmpeg -c copy sem perdas que escreve um SeekHead + Cues + duração real (server/lib/video-remux.ts). Ambos são de melhor esforço — em caso de falha, fazemos upload do original, nunca bloqueamos a finalização. Gravações acima de CLIPS_INLINE_REMUX_MAX_BYTES (padrão 200 MB) pulam a passagem inline e são reparadas em segundo plano.

O caminho de upload streaming/resumable encaminha bytes brutos diretamente para o provedor e não pode reescrevê-los inline, então finalize-recording agenda uma passagem de ensureRecordingSeekable em segundo plano para esses.

Para reparar clipes enviados antes disso (ou via streaming), chame a ação reprocess-recording: --id, --ids='[...]' ou --all --limit=N. Ela busca novamente a mídia do provedor, reescreve, faz novo upload e redireciona a linha. É idempotente (clipes já buscáveis são pulados, a menos que --force) e toca apenas clipes hospedados pelo provedor de propriedade do chamador. Esta é a ferramenta certa quando um usuário relata um clipe específico lento/com buffering.

O remux para buscabilidade não pode reparar uma gravação cujo áudio continua enquanto a faixa de vídeo tem uma grande lacuna de timestamp (comum quando um navegador móvel suspende a câmera após o usuário trocar de aplicativo). Para um clipe que congela ou parece parar antes de sua duração declarada, chame reprocess-recording com --normalizeTimeline=true. Esse modo explícito usa o mesmo fluxo de busca e upload com escopo de proprietário, mas transcodifica completamente para um faststart MP4 (H.264 + AAC) de 30 fps constantes. Ele preserva o áudio e duplica o último quadro de vídeo decodificado através das lacunas de quadros ausentes. A ação faz upload para um novo objeto de mídia e redireciona atomicamente a linha somente após a saída verificada ser armazenada; qualquer falha de transcodificação, verificação de áudio, upload ou atualização concorrente deixa a URL e o formato originais intactos.

Importação do Loom

Use import-loom-recording para URLs de compartilhamento ou embed do Loom. A ação valida a URL do Loom, lê os metadados oEmbed do Loom do endpoint público do Loom e cria uma gravação ready com a URL de embed do Loom, miniatura, título, duração e dimensões. Quando o Loom expõe uma URL JSON pública de transcrição assinada na página de compartilhamento, a ação importa essa transcrição para o Clips e armazena segmentos normalizados; nunca armazene URLs CDN assinados do Loom.

Quando o Loom expõe um MP4 público baixável, import-loom-recording faz o download, envia novamente os bytes para o armazenamento do Clips e cria uma gravação pronta e reproduzível hospedada no Clips, importando a transcrição pública do Loom quando a página de compartilhamento expõe uma. Se o Loom permite reprodução pública, mas não expõe um MP4, a ação mantém uma gravação pronta baseada em embed e ainda importa a transcrição quando disponível.

Importações do Loom baseadas em embed renderizam um iframe do Loom e ocultam o editor nativo do Clips. Importações do Loom reenviadas suportam corte, exportações, extração de quadros e transcrição baseada em upload nativos do Clips; peça ao usuário para enviar o arquivo de vídeo original quando essas capacidades forem necessárias para uma importação baseada em embed.

Diagnósticos do navegador e opções de instalação do gravador

Gravações do navegador podem salvar diagnósticos limitados e redigidos através de createBrowserDiagnosticsCapture: mensagens do console mais método, URL, status, duração e erros de fetch/XHR. O gravador do navegador captura apenas atividade da própria página do gravador. A extensão Chrome do Clips é o caminho da aba ativa para logs do navegador: ela inicia /record com uma sessão de captura de extensão e passa developerLogs=1/0, então salva diagnósticos com origem extension.

A listagem da Web Store está ativa, então a opção pública da extensão Chrome é mostrada por padrão. Prompts de UI que, de outra forma, dizem "Baixar aplicativo de desktop" usam o componente de escolha de instalação compartilhado (CaptureInstallButton / CaptureInstallInlineLink) para oferecer duas opções: extensão Chrome para logs do navegador e aplicativo de desktop para a captura nativa mais perfeita. Defina VITE_CLIPS_CHROME_EXTENSION_ENABLED=0 para ocultar a opção Chrome novamente, ou VITE_CLIPS_CHROME_EXTENSION_URL para apontar para uma listagem diferente.

save-browser-diagnostics é UI/interno. Armazena logs de console limitados mais método, URL/caminho/chaves de query, status e duração de fetch/XHR. Nunca captura cabeçalhos, corpos, cookies ou valores de query de URL de rede. O texto do console mantém valores úteis não secretos enquanto redige chaves e cabeçalhos com aparência de credenciais. Use get-recording-player-data para o payload completo de diagnósticos quando você tiver acesso de editor; consulte o skill video-sharing para o stream redigido mais restrito que o contexto público do agente expõe.

Extensão Chrome

A extensão reside em chrome-extension/. Ela inicia /record com clipsExtensionId e clipsCaptureSessionId, e o gravador envia CLIPS_CAPTURE_START / CLIPS_CAPTURE_STOP / CLIPS_CAPTURE_CANCEL de volta para a extensão. Ela usa a API de depuração do Chrome apenas na aba da qual o usuário iniciou, apenas enquanto uma gravação está ativa e retorna a mesma forma de diagnósticos redigidos salva por save-browser-diagnostics.

A extensão também melhora o markdown de problemas e PRs do GitHub: um script de conteúdo estreito github.com detecta links Clips /r/, /share/ e /embed/, então renderiza o player existente /embed/:id em um iframe de visualização de propriedade da extensão para que o vídeo seja reproduzível sem sair do GitHub. Mantenha isso restrito ao GitHub, a menos que haja uma revisão de permissão deliberada.

Pastas, espaços e movimentações em massa

Use move-recording para movimentações de pasta única e em massa. Passe id para um clipe ou ids para os clipes selecionados e folderId: null para movê-los para a biblioteca ou raiz do espaço.

Capturas de tela

Uma captura de tela é uma linha recordings com kind = "image" (isImageRecording em shared/recording-kind.ts). Ela compartilha pastas, espaços, compartilhamento, comentários e pesquisa com clipes e não tem nenhuma das partes de vídeo: sem transcrição, capítulos, tira de filme, linha do tempo ou áudio. list-recordings --kind=image as lista.

  • Captura, anotação e redação são trabalho do navegador (create-screenshot, save-screenshot-edits, ambos apenas na UI). O agente lê uma captura de tela através de get-recording-player-data ou /api/agent-frame.jpg, que retorna a imagem propriamente dita para qualquer atMs.
  • imageUrl é a imagem servida; baseImageUrl é a base sem marcações na qual um editor desenha. Ambos são servidos através de /api/thumbnail/:id, que aplica a senha, expiração e retenção de redação. Nunca forneça as URLs de armazenamento.
  • A redação é em duas etapas, como para vídeo: as caixas são salvas como sobreposições pendentes (retidas dos visualizadores), depois queimadas. Uma queima escreve editsJson.burnInProgress antes de deletar o original e a limpa depois; unreclaimedUrls lista cópias mais antigas ainda não deletadas. Ambos são apenas do servidor (server/lib/screenshot-edits.ts) e nunca devem chegar a um visualizador.
  • Ações de edição de vídeo recusam capturas de tela em assertNativeRecordingMedia; apenas save-screenshot-edits escreve o editsJson de uma captura de tela.

Pausar / Retomar

MediaRecorder.pause() / .resume() são suportados em todos os navegadores modernos. Mantenha uma única instância de MediaRecorder entre as pausas — não derrube o stream, ou o prompt de permissão será exibido novamente. Enquanto pausado, o worker de upload continua drenando seu buffer para que possamos recuperar antes que o usuário pare.

Bolha da câmera

Quando o modo é screen+camera, "a bolha" são duas coisas diferentes:

  • Visualização de si mesmo na tela. CameraBubble renderiza um elemento <video> simples e não gravado que o usuário arrasta para se enquadrar durante a contagem regressiva/gravação. Nunca é capturado — é apenas UI de enquadramento local.
  • Composição gravada. A captura de tela não pode incluir esse elemento DOM quando o usuário grava outra janela/aplicativo, então o vídeo salvo precisa assar o círculo da câmera antes de o MediaRecorder começar. Isso é feito através de um <canvas> que combina o stream de captura de tela e o stream da câmera em quadros compositados, que são então alimentados para o MediaRecorder via captureStream(). O canvas garante que o círculo da câmera apareça na gravação final, independentemente da janela/alvo da captura de tela.

Habilidades Relacionadas