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çãouploading→processing→ready(oufailed).videoUrl,durationMs,videoSizeBytes,width,height,hasAudio,hasCamerasão populados à medida que o upload flui. Importações do Loom usamimport-loom-recordinge tornam-sereadycom 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
- Intenção. O usuário clica em Gravar (global
Cmd+Shift+L) ou o agente chamapnpm action start-recording --mode=screen. A versão do agente escreverecord-intentno estado da aplicação; a UI captura e inicia o mesmo fluxo de um clique do usuário. - 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. - Criar linha. Assim que o stream é concedido, chame
create-recordingpara inserir a linha comstatus: "uploading"e um id pré-gerado. Esse id é usado para cada upload de bloco subsequente. - Gravar. Inicie um
MediaRecordercommimeType: "video/webm;codecs=vp9,opus"(fallback para vp8, depois o padrão do navegador). Usetimeslice: 2000para que os blocos cheguem a cada 2s. - Enviar cada bloco.
ondataavailableenvia bytes para/api/uploads/chunkcom os cabeçalhosX-Recording-IdeX-Chunk-Index, enquanto espelha independentemente blocos brutos noIndexedDBcomo 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 noIndexedDBnão bloqueia a captura ou o upload. - Transcrição ao vivo. Junto com o MediaRecorder,
useLiveTranscriptionexecuta a Web Speech API para acumular texto da transcrição em tempo real. Ao parar, o cliente chamasave-browser-transcriptpara 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. - Finalizar. Ao parar, envie o bloco final para
/api/uploads/:id/chunk?isFinal=1. A rota chamafinalize-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 dostatusparaready, e então iniciarequest-transcriptpara saída de maior qualidade (vejaai-video-tools). - Navegar imediatamente. Gravadores de desktop abrem
/r/:idassim 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 deuploadingouprocessingparaready. 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:
- Vídeo da câmera/importação usa
expo-camera/ o seletor de fotos do sistema; áudio de reunião usaexpo-audiocom gravação em segundo plano ativada. - O arquivo nativo é copiado para o diretório de documentos e um trabalho de captura de AsyncStorage tipado é escrito antes do upload começar.
create-recordingrecebe um id estável gerado pelo cliente,sourceAppName: "Agent-Native Mobile"e o tipo MIME do contêiner.- 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.
- 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
moovapósmdat, 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 = Xe 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 deget-recording-player-dataou/api/agent-frame.jpg, que retorna a imagem propriamente dita para qualqueratMs. 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.burnInProgressantes de deletar o original e a limpa depois;unreclaimedUrlslista 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; apenassave-screenshot-editsescreve oeditsJsonde 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.
CameraBubblerenderiza 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
MediaRecordercomeç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 oMediaRecorderviacaptureStream(). O canvas garante que o círculo da câmera apareça na gravação final, independentemente da janela/alvo da captura de tela.