mcp-video-analyzer

mcp-video-analyzer

Transforme qualquer vídeo — YouTube, Instagram, TikTok, Loom, X, Vimeo, links diretos, arquivos locais — em transcrições, quadros-chave, texto OCR e metadados para agentes de IA.

Nenhum MCP de vídeo existente combina transcrições + quadros visuais + metadados em uma única ferramenta. Este combina — em Loom, nas principais plataformas yt-dlp (YouTube/Vimeo/TikTok/Instagram/X/Twitch/Dailymotion/Facebook), URLs de vídeo diretos e arquivos locais.

Quer um pipeline completo, não apenas uma ferramenta? social-knowledge-base é construído sobre este servidor — ele baixa contas inteiras de criadores do Instagram (reels, stories, destaques), transcreve-as e transforma o resultado em uma base de conhecimento pesquisável e consultável via RAG, com notas geradas por IA. Use este MCP quando quiser análise por vídeo dentro de um agente; use social-knowledge-base quando quiser arquivar e consultar uma conta inteira.

Instalação

Pré-requisitos

• Node.js 22.12+ — necessário para executar o servidor via npx
• yt-dlp — obrigatório para URLs do YouTube/Vimeo/TikTok/Instagram/X/Twitch/Dailymotion/Facebook; opcional para todo o resto (melhora a qualidade do download do Loom). Instale com pip install yt-dlp
• Chrome/Chromium (opcional) — alternativa para extração de quadros se o yt-dlp não estiver disponível

Sem yt-dlp ou Chrome, URLs diretos e arquivos locais ainda geram quadros — o ffmpeg-static integrado faz a extração, e o Loom usa o download do próprio CDN como alternativa. URLs de plataformas (YouTube etc.) degradam para um aviso claro de "instale o yt-dlp". Transcrições, metadados e comentários nunca exigem nenhum dos dois.

Há três formas de acesso: o plugin /video (Claude Code — comando de barra + servidor MCP configurado automaticamente), uma configuração MCP server simples (qualquer cliente MCP) ou a skill portátil + CLI (Codex, Cursor, Copilot e qualquer agente com shell — sem necessidade de MCP).

Claude Code — plugin /video (recomendado)

/plugin marketplace add guimatheus92/mcp-video-analyzer
/plugin install video@mcp-video-analyzer

Isso adiciona o comando de barra /video e registra automaticamente o servidor MCP — sem necessidade de claude mcp add:

/video https://youtu.be/jNQXAC9IVRw what happens at 0:10?
/video ~/Movies/screen-recording.mp4 when does the UI break?

Outros agentes — Codex, Cursor, Copilot, Gemini CLI, …

npx skills add guimatheus92/mcp-video-analyzer

Instala a skill video (formato Agent Skills) em todos os agentes detectados na sua máquina. Agentes sem o servidor MCP configurado usam automaticamente a CLI integrada como alternativa — zero configuração.

Claude Code (somente MCP)

claude mcp add video-analyzer -- npx mcp-video-analyzer@latest

Em seguida, reinicie o Claude Code ou inicie uma nova conversa.

VS Code / Cursor

Adicione ao seu arquivo de configurações MCP:

• VS Code: File → Preferences → Settings → search "MCP" ou edite ~/.vscode/mcp.json / %APPDATA%\Code\User\mcp.json (Windows)
• Cursor: Settings → MCP Servers → Add

{
  "servers": {
    "mcp-video-analyzer": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-video-analyzer@latest"]
    }
  }
}

Em seguida, recarregue a janela (Ctrl+Shift+P → "Developer: Reload Window").

Claude Desktop

Adicione ao seu arquivo de configuração do Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "video-analyzer": {
      "command": "npx",
      "args": ["mcp-video-analyzer@latest"]
    }
  }
}

Em seguida, reinicie o Claude Desktop.

CLI (uso único, sem cliente MCP)

O mesmo mecanismo é exposto como um comando de uso único — é isso que a skill video usa em agentes sem MCP, e funciona de forma independente em qualquer terminal:

npx -y mcp-video-analyzer@latest analyze "https://youtu.be/jNQXAC9IVRw"

O stdout é um único documento JSON — metadata, transcript, ocrResults, timeline, warnings, frameCount e frames como entradas { time, filePath, mimeType } apontando para quadros-chave JPEG copiados para --out (padrão: o diretório de cache por usuário — %LOCALAPPDATA% no Windows, ~/Library/Caches no macOS, $XDG_CACHE_HOME ou ~/.cache no Linux — sob mcp-video-analyzer/<url-hash>/; defina MCP_CACHE_DIR para um caminho absoluto para realocá-lo). Diferente do diretório temporário onde costumava ficar, nada remove esse local, então os quadros persistem até você excluí-los — os diretórios são criados 0700. O progresso é transmitido no stderr, então stdout pode ser canalizado diretamente para um analisador JSON. Falhas parciais ficam em warnings com código de saída 0; apenas falhas graves saem com código 1.

Execute sem argumentos (npx mcp-video-analyzer@latest) para iniciar o servidor MCP stdio — a CLI é puramente aditiva.

Verifique se funciona

Após a instalação, pergunte ao seu assistente de IA:

Analyze this video: https://www.youtube.com/watch?v=jNQXAC9IVRw

(também funciona com um link do Instagram/TikTok/Loom, uma URL .mp4 direta ou um caminho de arquivo local). Se o servidor estiver conectado, ele chamará automaticamente a ferramenta analyze_video.

Ferramentas

Oito ferramentas — a IA escolhe a mais barata para o trabalho e a chama automaticamente. Clique em qualquer ferramenta para expandir seus parâmetros e exemplos.

> Analyze this video: https://www.youtube.com/watch?v=abc123...

> Analyze every .mp4 in this folder

> Get the transcript from this video

> What's this video about?

> Extract frames from this video with dense sampling

> Analyze what happens between 1:30 and 2:00 in this video

> Show me the frame at 1:23 in this video

> Show me 10 frames between 0:15 and 0:17 of this video

Níveis de Detalhe

Cache

Os resultados são armazenados em cache na memória por 10 minutos. Chamadas subsequentes com a mesma URL e opções retornam instantaneamente. Use forceRefresh: true para ignorar o cache. skipFrames faz parte do cache e da chave auxiliar, então uma análise apenas de transcrição e uma com quadros da mesma URL nunca respondem uma pela outra.

Arquivos auxiliares persistentes (processamento em lote retomável)

O cache em memória é perdido ao reiniciar, o que torna o reprocessamento de um grande corpus local custoso. Defina MCP_WRITE_SIDECARS=1 para também persistir resultados ao lado de cada vídeo local para que o trabalho sobreviva a reinicializações e possa ser retomado:

• <stem>.vtt — a transcrição, somente quando foi gerada pelo fallback Whisper (um <stem>.vtt existente do seu próprio pipeline nunca é sobrescrito). Uma chamada posterior o reutiliza via leitor auxiliar normal e ignora o Whisper completamente.
• <stem>.analysis.json + <stem>.frames/ — o resultado completo (quadros + OCR + linha do tempo), chaveado pelo mtime:size do vídeo e pelos parâmetros de análise. Em uma chamada posterior com carimbo + parâmetros correspondentes, o resultado é retornado diretamente do disco (sem extração, sem OCR).

Isso torna analyze_videos sobre milhares de arquivos retomável, e permite que um pipeline externo de transcrição por GPU e este MCP compartilhem resultados através do sistema de arquivos: o pipeline escreve <stem>.vtt, e o MCP o utiliza em vez de executar o Whisper.

Fontes Suportadas

Quadros do Loom: transcrição, metadados e comentários vêm diretamente da API do Loom sem ferramentas extras. A extração de quadros é diferente — o Loom serve a maioria dos vídeos como streams DASH separados de vídeo+áudio, que apenas yt-dlp (pip install yt-dlp) busca e mescla. A mesclagem usa o ffmpeg-static incluído, então nenhum ffmpeg do sistema é necessário. Sem yt-dlp, um fallback direto de CDN ainda cobre alguns vídeos; quando não consegue, você recebe transcrição + metadados + comentários além de um aviso explicando por que os quadros estão ausentes.

Arquivos locais: passe um caminho absoluto (ex.: /Users/you/clip.mp4) ou uma URI file:// como argumento url para qualquer ferramenta. Caminhos relativos são rejeitados — o diretório de trabalho do servidor é imprevisível a partir do cliente MCP. Observe que qualquer chamador do servidor MCP pode pedir que ele leia qualquer arquivo ao qual o processo do servidor tenha acesso. Caminhos UNC / compartilhamentos de rede (\\host\share\clip.mp4) são a exceção: eles alcançam a rede em vez do disco local, então seguem as regras de destino de rede e precisam de MCP_ALLOW_PRIVATE_URLS=1.

Transcrições auxiliares: se um clip.vtt, clip.srt, clip.en.vtt, etc. existir ao lado de clip.mp4, ele é usado como transcrição automaticamente — sem ida ao Whisper. SRT é convertido para VTT em memória.

Legendas incorporadas: se nenhum auxiliar for encontrado e o contêiner tiver um stream de legenda incorporado (comum em .mkv / .mov / .mp4 de gravadores de tela), ele é transmuxado para VTT via ffmpeg e usado como transcrição.

Extensões reconhecidas (arquivos locais e URLs diretas): .mp4 .mov .mkv .webm .avi .m4v .wmv .flv .mpeg .mpg .m2ts .mts .3gp .ogv. A extensão apenas controla o roteamento — o ffmpeg faz a demuxagem real, então a maioria dos contêineres comuns funciona. .ts é excluído para evitar colisão com arquivos-fonte TypeScript.

Destinos de rede

Apenas URLs http:// e https:// são buscadas, e somente para endereços públicos. Requisições para loopback (localhost, 127.0.0.1, ::1), faixas privadas/LAN, link-local, CGNAT, nomes mDNS .local e caminhos UNC do Windows são recusadas, assim como esquemas não-HTTP como ftp:// e data:.

Isso importa porque o argumento url é alcançável por atacantes no caso normal: um agente que dirige este servidor pode ser conduzido pelo conteúdo que lê, então uma URL que ele passa não é necessariamente uma que o usuário escolheu. Sem a restrição, o servidor é um proxy para qualquer rede em que esteja.

A verificação ocorre no endereço resolvido, não apenas no texto, então um hostname público que resolve para 10.0.0.5 também é recusado — e cada salto de uma cadeia de redirecionamento é reverificado, já que uma URL pública respondendo 302 Location: http://127.0.0.1/ passaria direto por uma verificação apenas no primeiro salto.

# Serving videos from a NAS or a local dev server? Opt back in:
MCP_ALLOW_PRIVATE_URLS=1

Endpoints de metadados de instância de nuvem (169.254.169.254, Azure 168.63.129.16 e similares) permanecem bloqueados mesmo com isso definido — não há vídeo legítimo lá, e são o que um SSRF geralmente procura.

Limitação conhecida: o endereço é verificado no momento da resolução, não no momento da conexão, então rebinding de DNS — um domínio respondendo um endereço público à verificação e um privado à conexão — não é coberto. Execute o servidor atrás de um proxy de saída se isso estiver no seu modelo de ameaça.

URLs de plataformas via yt-dlp (YouTube, Instagram, TikTok, …)

Páginas de vídeo único em grandes plataformas passam por yt-dlp (pip install yt-dlp — necessário para essas URLs). Playlists, canais e páginas de perfil são rejeitados por design; passe URLs de vídeos individuais (agrupe-os com analyze_videos).

• Transcrição: legendas nativas são preferidas e gratuitas — legendas enviadas primeiro, legendas geradas automaticamente como fallback (duplicação de janela deslizante é colapsada). WHISPER_LANGUAGE (ex.: pt) também é usado para escolher o idioma das legendas. Vídeos sem legendas caem na cadeia normal do Whisper.
• Metadados: título, duração, uploader/canal, contagem de visualizações, data de upload e capítulos — sem necessidade de download.
• Download: limitado a 1080p (quadros/OCR não precisam de mais), streams ao vivo são ignorados, e áudio+vídeo DASH é mesclado com o ffmpeg-static incluído (nenhum ffmpeg do sistema necessário).
• Cookies — Instagram e vídeos restritos por idade geralmente exigem uma sessão logada:

A extração de cookies do navegador exige que o navegador esteja fechado no Windows (o banco de dados de cookies fica bloqueado enquanto ele executa). Se isso for inconveniente, exporte um cookies.txt uma vez (ex.: com uma extensão de navegador "Get cookies.txt") e aponte YTDLP_COOKIES para ele. Vídeos privados/restritos por idade sem cookies válidos não travam a ferramenta — a linha ERROR: do yt-dlp aparece em warnings[].

TwelveLabs Pegasus (opcional)

Defina a variável de ambiente TWELVELABS_API_KEY para analisar URLs de vídeo diretas com TwelveLabs Pegasus. O Pegasus analisa o vídeo no lado do servidor (visuais e seu próprio áudio) e retorna uma transcrição com carimbo de tempo gerada por IA além de um resumo de IA como texto — capacidades que o DirectAdapter não pode fornecer (uma URL .mp4 bruta não tem transcrição ou resumo por conta própria), e sem necessidade de chave Whisper.

A transcrição é saída de LLM de melhor esforço, não um despejo ASR determinístico: o Pegasus é instruído a emitir linhas [MM:SS] line, e linhas que não correspondem a esse formato são descartadas, então a redação e os carimbos de tempo exatos dependem da adesão do modelo às instruções. Falhas (chave inválida, timeout, erro de API) aparecem no warnings[] da ferramenta em vez de retornar silenciosamente uma transcrição vazia.

O maior ganho está nos caminhos somente texto: get_transcript e get_metadata retornam uma transcrição e resumo Pegasus para URLs diretas — alguns KB de texto, sem imagens de quadros, sem custo de token por quadro. analyze_video em detail: "standard"/"detailed" ainda extrai quadros adicionalmente (use detail: "brief" para permanecer somente texto).

Vídeos longos: o resumo e a transcrição completa compartilham uma única conclusão limitada (max_tokens = 16384), então para vídeos muito longos a transcrição pode ser truncada. Para conteúdo de várias horas, dividir por janelas de tempo é a melhor abordagem.

É totalmente opt-in e não quebra nada: quando TWELVELABS_API_KEY está definido, o TwelveLabsAdapter lida com URLs de vídeo diretas (ele registra a URL pública com o TwelveLabs — sem upload); quando não está definido, o DirectAdapter lida com elas exatamente como antes. URLs do Loom não são afetadas. Obtenha uma chave em playground.twelvelabs.io.

Transcrição (fallback Whisper)

Quando uma fonte não tem transcrição nativa (sem auxiliar .vtt/.srt, sem legendas incorporadas, sem legendas de plataforma), a faixa de áudio é transcrita com Whisper via uma cadeia de fallback graciosa (em ordem de execução):

Faixas silenciosas: antes de qualquer execução do Whisper, o áudio é sondado com ffmpeg volumedetect (primeiros 2 minutos). Uma faixa presente mas muda — comum em Reels/Stories silenciados — pula a transcrição completamente e emite um aviso de que a transcrição vazia é conteúdo esperado, não um erro, economizando uma execução inútil do Whisper.

1. @huggingface/transformers (nativo JS, zero dependências externas) — somente opt-in: esta estratégia executa primeiro, mas apenas quando WHISPER_HF_MODEL está explicitamente definido. Quando não está definido (o padrão), a estratégia é ignorada completamente, então a CLI abaixo vence e suas configurações WHISPER_MODEL/WHISPER_LANGUAGE nunca são silenciosamente sobrescritas.
2. CLI whisper — usada quando um executável whisper é encontrado (pip install -U openai-whisper). Aponte WHISPER_BIN para o executável se ele não estiver em PATH. Modelo via WHISPER_MODEL, idioma via WHISPER_LANGUAGE. O ffmpeg-static incluído é colocado no PATH da CLI automaticamente, então nenhum ffmpeg do sistema é necessário.
3. API OpenAI Whisper — usada quando OPENAI_API_KEY está definido.

Nenhum backend configurado? Se nenhum dos três estiver disponível (sem whisper em PATH/WHISPER_BIN, sem OPENAI_API_KEY, sem WHISPER_HF_MODEL), as ferramentas de transcrição retornam uma transcrição vazia com um aviso dizendo como habilitar uma — em vez de um "sem transcrição" silencioso. Instale openai-whisper ou defina uma das chaves acima. (A CLI é iniciada com PYTHONUTF8=1 para que transcrições não-inglesas/CJK não travem o processo Python no Windows.) | Variável de ambiente | Aplica-se a | Padrão | Exemplo | |---------|-----------|---------|---------| | WHISPER_MODEL | whisper CLI | tiny | small, medium | | WHISPER_LANGUAGE | whisper CLI / API OpenAI | detecção automática | pt, en, es | | WHISPER_PROMPT | whisper CLI / API OpenAI | — | Doha, Smiles, Livelo, Latam, milheiro | | WHISPER_BIN | whisper CLI | whisper (no PATH) | C:/.../Scripts/whisper.exe | | WHISPER_DEVICE | whisper CLI (enviado apenas se definido) | — | cuda, cpu | | WHISPER_COMPUTE | apenas whisper-ctranslate2 | — | float16, int8_float16, int8 | | WHISPER_BEAM_SIZE | whisper CLI (enviado apenas se definido) | — | 5 | | WHISPER_WORD_TIMESTAMPS | whisper CLI (enviado apenas se definido) | desligado | 1 | | WHISPER_HF_MODEL | HF transformers (opt-in) | — (estratégia desligada) | Xenova/whisper-small | | OPENAI_API_KEY | API OpenAI | — | sk-… |

O modelo padrão tiny é rápido, mas fraco para áudio não-inglês. Para fontes em português (ou outros idiomas não-inglês), instale o CLI e defina WHISPER_MODEL=small (ou medium) + WHISPER_LANGUAGE=pt para obter precisão muito melhor. Adicione WHISPER_PROMPT com um glossário de domínio (nomes de marcas/lugares) para corrigir nomes próprios. Você também pode substituir model/language/initialPrompt por chamada em analyze_video / get_transcript / analyze_videos — sem necessidade de reiniciar.

GPU (faster-whisper): whisper-ctranslate2 (pip install -U whisper-ctranslate2) é um CLI substituto com as mesmas flags, além de --device cuda / --compute_type / --beam_size. Aponte WHISPER_BIN para ele e defina WHISPER_DEVICE=cuda (+ opcionalmente WHISPER_COMPUTE=float16). Essas flags de GPU são controladas por variável de ambiente — elas só são passadas quando definidas, então o openai-whisper simples (que rejeita --compute_type) continua funcionando quando elas não estão definidas.

Nota para Windows: o pip instala whisper.exe no diretório Scripts/ do Python, que muitas vezes não está no PATH que os MCP clients iniciados por GUI herdam. Se as transcrições voltarem vazias, defina WHISPER_BIN para o caminho completo de whisper.exe.

Estratégias de Extração de Quadros

A extração de quadros usa uma cadeia de fallback de duas estratégias — nenhuma dependência única é necessária:

O fallback é automático — se o yt-dlp não estiver disponível, o servidor tenta a extração baseada em navegador via puppeteer-core. Se nenhum estiver disponível, a análise ainda retorna transcrição + metadados + comentários, apenas sem quadros.

Pipeline de Pós-Processamento

Após a extração de quadros, o pipeline aplica automaticamente:

A etapa de OCR requer tesseract.js (incluído como dependência). Se falhar ao carregar, a análise continua sem OCR — nenhum quadro ou transcrição é perdido. O pré-processamento de OCR está ativado por padrão; defina MCP_OCR_PREPROCESS=0 para fazer OCR nos quadros brutos.

O OCR sempre lê o quadro em resolução total, não a cópia emitida para o cliente. Os dois têm funções diferentes: o quadro emitido é limitado para custo de tokens, enquanto o reconhecimento precisa de cada pixel que puder obter.

Tamanho do quadro (capturas de UI densas)

Os quadros emitidos são limitados a 800 px de largura, o que atende ao caso comum — clipes de pessoa falando, Reels, reprodução de bugs — onde o assunto preenche o quadro.

É o tamanho errado para uma captura de UI densa: um terminal, dashboard, IDE ou gravação de planilha, onde o significado está em texto pequeno. Uma gravação de tela 1920×1080 sem escala chega a 800×450, e uma fonte de UI de 15 px cai abaixo do que um modelo de visão consegue resolver.

Passe maxWidth por chamada para manter mais (ou toda) a resolução da fonte — 0 desativa o limite:

get_frames(url, { maxFrames: 8, maxWidth: 0 })   // source resolution
get_frame_at(url, "2:14", { maxWidth: 1920 })
analyze_video(url, { detail: "standard", maxWidth: 1568 })

Suportado em analyze_video, analyze_videos, analyze_moment, get_frames, get_frame_at e get_frame_burst, e no CLI como --max-width <px>.

Quadros nativos custam várias vezes mais contexto que o padrão, então aumente o limite deliberadamente — get_frames retorna até 20 quadros e analyze_video em detailed até 60.

Um valor que qualquer variável não possa usar — 1e3, 1920px, uma qualidade de 150 — é rejeitado com um aviso único no stderr e o padrão se aplica. Não é aceito silenciosamente: o objetivo da configuração é escapar de um downscale que de outra forma parece um resultado normal.

Prefira o parâmetro por chamada: o servidor inicia uma vez por sessão, então uma variável de ambiente não pode diferir entre uma visão geral de um clipe do YouTube e uma leitura detalhada de uma gravação de tela. A largura que uma chamada realmente usa faz parte da chave de cache e sidecar, então analisar o mesmo vídeo a 800 px e depois a maxWidth: 0 reexecuta o pipeline em vez de retornar o primeiro resultado duas vezes.

Ferramentas Complementares

Chrome DevTools MCP

Para depuração web ao vivo junto com análise de vídeo, combine este servidor com o Chrome DevTools MCP:

claude mcp add chrome-devtools npx @anthropic-ai/mcp-devtools@latest

Quando usar cada um:

Os dois MCPs se complementam: o analisador de vídeo entende conteúdo gravado, o DevTools interage com páginas ao vivo.

Exemplo de Saída

A pasta examples/loom-demo/ contém saídas reais da análise de um vídeo Loom público (Boost In-App Demo Video, 2:55).

Imagens de quadros (19 no total em examples/loom-demo/frames/):

• scene_*.jpg — detecção de mudança de cena (transições visuais principais)
• dense_*.jpg — amostragem densa de 1fps (cada 10º quadro salvo como amostra)
• burst_*.jpg — extração em rajada para análise de momento (0:30–0:45)

Regenerar após alterações: npx tsx examples/generate.ts — requer yt-dlp + acesso à rede.

Desenvolvimento

# Install dependencies
npm install

# Run all checks (format, lint, typecheck, knip, tests)
npm run check

# Audit dependencies. `security` covers what the published package ships and
# is a blocking CI job; `security:all` adds devDependencies. Both also run on
# a weekly cron, because npm audit reads a live advisory database.
npm run security

# Build
npm run build

# Run E2E tests (requires network; add WHISPER_E2E=1 to include the
# transcription outcome test — needs a whisper CLI installed)
npm run test:e2e

# Just the video-format matrix: a real clip per container/codec
# (mp4/h264+hevc+av1, webm, mkv, mov, avi, m4v, mpeg, mpg, m2ts, mts,
# 3gp, ogv, flv, wmv) decoded end to end. ~15s on a warm cache; the
# first run fetches ~7MB of tesseract traineddata.
npm run test:formats

# Build + boot the real MCP server/CLI (seconds)
npm run test:smoke

# Everything: check → e2e → smoke → verify-package
npm run verify-all

# Open MCP Inspector for manual testing
npm run inspect

Arquitetura

src/
├── index.ts                    # Entry point (shebang + stdio)
├── server.ts                   # FastMCP server + tool registration
├── tools/                      # MCP tool definitions (7 tools)
│   ├── analyze-video.ts        # Full analysis with detail levels + caching
│   ├── analyze-moment.ts       # Deep-dive on a time range
│   ├── get-transcript.ts       # Transcript-only with Whisper fallback
│   ├── get-metadata.ts         # Metadata + comments + chapters
│   ├── get-frames.ts           # Frames-only (scene-change or dense)
│   ├── get-frame-at.ts         # Single frame at timestamp
│   └── get-frame-burst.ts      # N frames in a time range
├── adapters/                   # Source-specific logic
│   ├── adapter.interface.ts    # IVideoAdapter interface + registry
│   ├── loom.adapter.ts         # Loom: authless GraphQL
│   ├── local-file.adapter.ts   # Local files: absolute path or file:// URI
│   ├── twelvelabs.adapter.ts   # TwelveLabs Pegasus: transcript + AI summary (opt-in)
│   └── direct.adapter.ts       # Direct URL: any mp4/webm link
├── processors/                 # Shared processing
│   ├── frame-extractor.ts      # ffmpeg scene detection + dense + burst extraction
│   ├── browser-frame-extractor.ts # Headless Chrome fallback for frames
│   ├── audio-transcriber.ts    # Whisper fallback (HF transformers → CLI → OpenAI)
│   ├── image-optimizer.ts      # sharp resize/compress
│   ├── frame-dedup.ts          # Perceptual dedup (dHash + Hamming distance)
│   ├── frame-ocr.ts            # OCR text extraction (tesseract.js)
│   └── annotated-timeline.ts   # Unified timeline (transcript + frames + OCR)
├── config/
│   └── detail-levels.ts        # brief / standard / detailed config
├── utils/
│   ├── cache.ts                # In-memory TTL cache with LRU eviction
│   ├── field-filter.ts         # Selective field filtering for responses
│   ├── url-detector.ts         # Platform detection from URL
│   ├── vtt-parser.ts           # WebVTT → transcript entries
│   └── temp-files.ts           # Temp directory management
└── types.ts                    # Shared TypeScript interfaces

Temporização de rajada

A extração em rajada aceita timestamps fracionários (por exemplo, 0:01.1). O caminho FFmpeg seleciona até a quantidade solicitada de quadros de origem existentes dentro de [from, to), sem duplicar quadros para satisfazer uma taxa de amostragem excessiva. Os resultados do processador retêm o tempo de apresentação relativo ao vídeo de cada quadro selecionado, incluindo segundos fracionários. O fallback do navegador preserva alvos de busca fracionários e arquivos de screenshot separados; seus tempos são buscas solicitadas, não PTS de quadros de origem medidos. A busca no navegador não é um substituto preciso de quadro para decodificação local.

get_frame_burst retorna um bloco de texto JSON contendo { frameCount, from, to, warnings, frames: [{ time, timingOrigin }] }, seguido por imagens exatamente na mesma ordem que frames. timingOrigin: "source-pts" significa tempo de apresentação FFmpeg medido relativo ao vídeo; "seek-target" significa tempo de busca solicitado no navegador. Resultados vazios/degradados contêm frames: [].

Licença

MIT