Cueprecise

Português | 한국어

CuePrecise

Encontre o momento relevante em um vídeo longo do YouTube—e veja as evidências por trás da resposta.

Um vídeo longo em um idioma que você não fala ainda pode se tornar pesquisável. CuePrecise é um servidor MCP de código aberto para Claude Desktop, Codex, Cursor e outros clientes de IA. Ele transforma a fala original de um vídeo do YouTube, legendas disponíveis, rótulos de falantes e quadros selecionados em uma referência local pesquisável. O índice permanece no idioma original do vídeo; seu cliente de IA pode traduzir uma pergunta em termos de busca, mas a recuperação entre idiomas não é garantida.

Em uma configuração testada, o CuePrecise analisa vídeos com mais de uma hora em cerca de três minutos. Ele não envia o vídeo inteiro para o seu cliente de IA a cada pergunta. Ele transcreve o áudio original em blocos, indexa as evidências e recupera apenas as passagens e quadros relacionados à sua pergunta.

A transcrição começa com o áudio original. Quando uma faixa de legenda do YouTube no idioma original está disponível, o CuePrecise a utiliza para recuperar termos e frases em escrita latina correspondentes que a transcrição não capturou. Você pode fazer perguntas ao seu cliente de IA no seu próprio idioma, mas a recuperação confiável pode exigir a redação original. Os resultados ainda incluem as palavras originais, informações do falante, quadros relevantes e um carimbo de data/hora que leva você de volta ao YouTube. O tempo real de processamento depende do vídeo, da rede e do tempo de resposta da API.

Veja em ação

A demonstração anexada usa uma entrevista em polonês. Pergunte sobre o que se trata no seu próprio idioma; o CuePrecise retorna momentos relevantes, a transcrição original e quadros correspondentes como evidência.

You: I do not speak Polish. What is this interview about?

Your AI + CuePrecise:
Explains the interview in your language, points to relevant moments,
and provides the original transcript and matching frames as evidence.

https://github.com/user-attachments/assets/ce7d595b-871f-469a-bcb8-798713751ffd

_{Fonte da demonstração: “Czym jest prompt injection i jak chronić firmę przed złośliwą instrukcją dla AI? Gośc. Tomasz Bartel” por Daniel Bartosiewicz | Content i Automatyzacja, licenciado sob CC BY.}

Baixar CuePrecise → GitHub Releases

• Vá direto à resposta. Obtenha um carimbo de data/hora para cada item em um resumo.
• Mantenha os falantes separados. Compare o que cada pessoa disse e por quê.
• Encontre uma tela referenciada novamente. Conecte um quadro relevante ao que estava sendo explicado.
• Verifique a fonte. Abra o vídeo original do YouTube no momento citado.

Experimente perguntas como estas:

What is the main argument of this video? Include timestamps for each point.

Find where the speaker explains self-supervised learning.
When does that phrase appear on screen?

Compare each speaker's position on basic income and include the supporting passages.

If these speakers debated a new issue, what arguments and counterarguments
would follow from what they actually said in the video?

No Claude Desktop, clicar em um carimbo de data/hora abre o YouTube naquele momento. Outros clientes de IA podem renderizar links de carimbo de data/hora de forma diferente.

Ele mantém as respostas ligadas às evidências

O CuePrecise não é apenas um resumidor. Ele dá ao seu cliente de IA o material necessário para responder a uma pergunta e permite que você verifique de onde veio a resposta:

• Transcrição palavra por palavra da fala original feita pelo Gemini.
• Legendas do YouTube no idioma original, quando disponíveis, alinhadas à mesma linha do tempo.
• Quadros de frases de referência de tela da transcrição, termos restaurados ou carimbos de data/hora solicitados.
• Rótulos de falantes, confiança das evidências e proveniência dos trechos recuperados.

Quando a busca não encontra nenhuma passagem de apoio, o CuePrecise informa que não há evidências no material indexado em vez de inventar uma fonte. O pacote de evidências resultante permanece no seu computador, para que uma conversa posterior possa pesquisar o mesmo vídeo sem recomeçar. Os blocos de áudio usados para transcrição são enviados ao Gemini; consulte PRIVACY.md para saber o limite da rede.

Recuperando um termo que a transcrição não capturou

Nomes e termos técnicos são fáceis de se perder em uma transcrição longa. Em uma palestra técnica coreana de 23 minutos, a frase self supervised learning desapareceu em todas as quatro execuções de transcrição somente com o Gemini.

Gemini transcription:
So how did they learn this ability? It is a way of learning.

CuePrecise merge:
So how did they learn this ability? self supervised learning is a way of learning.

O CuePrecise verifica as legendas do YouTube do mesmo intervalo de tempo e preenche apenas uma lacuna correspondente. Ele não reescreve as palavras do Gemini. As palavras fornecidas pelas legendas mantêm sua origem.

O exemplo medido ficou assim:

• As legendas originais do YouTube continham 91 palavras em escrita latina e a frase ausente.
• As execuções do Gemini continham 28–29 palavras em escrita latina, mas perderam a frase todas as vezes.
• O resultado mesclado continha 38 palavras em escrita latina e recuperou a frase mantendo a qualidade da transcrição em coreano.

Este é um caso extremo medido, não uma afirmação geral de precisão. As regras exatas de mesclagem e os critérios de validação estão documentados em CONTRACT.md.

Compare falantes sem fingir saber seus nomes

O CuePrecise carrega informações do falante entre os blocos de um vídeo longo. Os rótulos de falantes são identificadores, não nomes reais. Identidades confirmadas e inferidas são mantidas separadas, e evidências fracas permanecem não resolvidas em vez de serem apresentadas como fato.

Isso permite que seu cliente de IA:

• colete as afirmações e passagens de apoio de um falante;
• compare as posições de vários falantes;
• simule um debate sobre um novo assunto usando as declarações reais dos falantes como evidência.

Um debate simulado é gerado a partir do vídeo. Não é uma afirmação de que essas pessoas realmente discutiram o novo assunto.

Início rápido

Claude Desktop no Windows — extensão de arquivo único

1. Abra Releases e baixe cueprecise-windows.mcpb.
2. No Claude Desktop, abra Configurações → Extensões → Configurações avançadas → Instalar extensão.
3. Selecione o arquivo. O Claude solicitará uma chave de API do Gemini e uma pasta para os dados locais de vídeo.
4. Ative o CuePrecise e pergunte ao Claude sobre um link do YouTube.

O pacote de aproximadamente 86 MiB inclui CuePrecise, yt-dlp, FFmpeg e FFprobe. Você não precisa instalar Python, Git ou as ferramentas de vídeo separadamente. A extensão está disponível atualmente para Claude Desktop no Windows.

Outros clientes de IA no Windows

1. Abra Releases e baixe cueprecise-setup.exe.
2. Execute o instalador, clique em Criar chave de API e cole uma chave do Google AI Studio.
3. Selecione os clientes de IA encontrados no seu computador e clique em Conectar.
4. Feche e reabra completamente os clientes conectados.

O instalador verifica se há FFmpeg e FFprobe e instala o FFmpeg por meio do WinGet quando ele estiver ausente. Ele adiciona apenas a entrada do CuePrecise e faz backup da configuração existente quando pode fazê-lo com segurança; um TOML do Codex com segredos pode ficar sem backup para evitar copiar a chave. No Windows, a chave de API é criptografada com DPAPI do Windows para o usuário atual. Chaves antigas do CuePrecise em texto simples são movidas para o armazenamento protegido durante uma atualização.

Prévia não assinada: v0.2.5 não é assinada digitalmente, então o Windows pode mostrar um aviso de editor desconhecido. Baixe-a somente na página de Releases deste repositório e verifique SHA256SUMS.txt se quiser conferir o arquivo antes de instalá-lo.

macOS, Linux e instalação por linha de comando

Com uv:

uv tool install git+https://github.com/Nattentia/cueprecise
cueprecise setup

O comando de configuração configura os clientes de IA suportados detectados, incluindo Claude Desktop, e cria o diretório de dados padrão ~/.cueprecise/data. Ele mantém um arquivo .bak com carimbo de data/hora quando altera uma configuração existente, a menos que um formato de configuração com segredos não possa ser copiado com segurança.

Instale ffmpeg e ffprobe e verifique o ambiente:

cueprecise doctor

Crie uma chave de API do Gemini e passe-a pela entrada padrão ou por um arquivo para que ela não apareça no comando ou no histórico do shell:

cueprecise setup --api-key -                  # paste the key, then press Enter
cueprecise setup --api-key-file ~/.gemini-key # read it from a file
pass show gemini/api-key | cueprecise setup --api-key -

cueprecise run "https://www.youtube.com/watch?v=VIDEO_ID" --language en-US
cueprecise status VIDEO_ID

Se uma chave for exposta, exclua-a no Google AI Studio e crie uma nova. Consulte PRIVACY.md para o procedimento completo.

Somente para desenvolvimento de código-fonte:

git clone https://github.com/Nattentia/cueprecise.git
cd cueprecise
python -m pip install -r requirements.txt
python src/pipeline.py --help

Clientes de IA suportados

cueprecise setup pode detectar e configurar estes clientes:

• Claude Desktop
• Codex
• Claude Code
• VS Code
• Cursor
• Windsurf
• Gemini CLI

Os caminhos de configuração do Cursor, Windsurf e Gemini CLI são alvos de configuração automática, mas não foram testados de ponta a ponta na máquina de desenvolvimento atual.

Execute para cada cliente detectado, para um cliente nomeado ou para inspecionar o resultado:

cueprecise setup
cueprecise setup --client codex
cueprecise doctor

Um aplicativo é considerado instalado quando seu executável está em PATH. Uma pasta de configuração restante não é tratada como prova de que o aplicativo está presente. Um cliente não detectado pode ainda ser nomeado explicitamente com --client <name>.

O CuePrecise ignora uma entrada cueprecise existente se o CuePrecise não a criou. Ele não sobrescreve as configurações de outro servidor MCP, e uma falha para um cliente não interrompe os outros.

Conectores do ChatGPT e Claude.ai na web não são suportados atualmente pelo transporte stdio local do CuePrecise. Clientes web que exigem um servidor MCP HTTP remoto não podem usar esta configuração.

Conecte outro host MCP

O CuePrecise aceita tanto a revisão MCP de solicitação por solicitação 2026-07-28 quanto o handshake anterior initialize. cueprecise setup é preferido porque preserva a configuração existente e lida com credenciais para clientes suportados.

O JSON abaixo é para um checkout do código-fonte ou um host MCP não listado acima. Ele armazena a chave em texto simples, então use o comando de configuração quando possível:

{
  "mcpServers": {
    "cueprecise": {
      "command": "python",
      "args": [
        "C:/path/to/cueprecise/src/mcp_server.py",
        "--bundle-root",
        "C:/path/to/cueprecise/data"
      ],
      "env": {
        "GEMINI_API_KEY": "..."
      }
    }
  }
}

Use caminhos absolutos. Em todas as plataformas, o literal --api-key VALUE é rejeitado para manter a chave fora das listagens de processos e do histórico do shell. O servidor pode iniciar sem GEMINI_API_KEY: as análises existentes permanecem pesquisáveis, enquanto novas solicitações de transcrição param com uma mensagem de configuração.

Ferramentas MCP

As ferramentas são divididas em quatro grupos.

Análise e status:

• cueprecise_register — registrar e analisar um vídeo do YouTube. Você pode escolher as etapas a serem executadas.
• cueprecise_status — relatar progresso, artefatos gerados e uso local estimado.

Busca e evidências:

• cueprecise_outline — retornar um esboço com carimbos de data/hora, termos recuperados e estado do falante.
• cueprecise_query — pesquisar evidências de transcrição e quadros relacionados.
• cueprecise_excerpt — retornar transcrição e quadros para um intervalo de tempo específico.
• cueprecise_frames — extrair quadros em torno de momentos de referência de tela ou carimbos de data/hora solicitados.

Resultados salvos:

• cueprecise_summary — criar ou recuperar um resumo.
• cueprecise_set_summary — validar e salvar um resumo melhorado pelo host.
• cueprecise_set_chapter_titles — validar e salvar títulos de capítulos escritos pelo host.

Limpeza:

• cueprecise_purge — remover explicitamente blocos, vídeo de origem, resultados derivados, dados brutos ou todos os dados.

Após a busca no YouTube e a transcrição do Gemini, a montagem, a mesclagem de legendas, os capítulos, a renderização, a extração visual e a indexação são executadas localmente. Os títulos dos capítulos e os resumos são escritos pelo host de IA a partir das evidências recuperadas; o CuePrecise não cria outra chamada de transcrição do Gemini.

Pacote de evidências local

O instalador e cueprecise setup usam ~/.cueprecise/data. Um checkout do código-fonte pode usar data a menos que você defina --bundle-root.

data/<video_id>/
  job.json                  chunk plan and progress
  raw/
    captions.json           YouTube caption track (original preferred)
    metadata.json            metadata used for language checks
    audio/                  audio chunks used for transcription
    transcripts/             per-chunk transcripts and raw responses
    frames/                  extracted frames
  derived/
    transcript.json          assembled Gemini transcription
    merged.json              transcription plus caption evidence
    chapters.json            timestamped outline
    frames.json              frame index
    output.srt, output.txt   optional render output
  index.sqlite3              transcript, chapter, frame index, and summary

Cada trecho de evidência indexado mantém seu carimbo de data/hora, status do falante, confiança das evidências e origem. Os dados de palavras mesclados também mantêm carimbos de data/hora por palavra e origem:

{
  "text": "supervised",
  "start": 208.93,
  "end": 209.87,
  "speaker": "speaker:0",
  "speaker_status": "confirmed",
  "origin": "youtube"
}

Um resultado de consulta inclui o intervalo de tempo, texto, fonte, confiança e qualquer quadro relacionado:

{
  "start": 1728.4,
  "end": 1740.2,
  "timecode": "00:28:48",
  "text": "The experiment was stopped after eight participants had seizures.",
  "source_path": "derived/merged.json",
  "source_kind": "transcript",
  "speaker": "speaker:3",
  "speaker_status": "inferred",
  "speaker_confidence": 0.75,
  "confidence": 1.0
}

Os quadros não são amostrados uniformemente em todo o vídeo. O CuePrecise prioriza frases de referência de tela na transcrição, termos restaurados das legendas e carimbos de data/hora solicitados pelo usuário. Ele não classifica semanticamente todos os quadros de código, tabela ou diagrama. Se o OCR estiver instalado, o texto reconhecido é armazenado como proveniência separada em vez de substituir silenciosamente a transcrição.

Como funciona

O CuePrecise não tenta fazer seu cliente de IA assistir ao vídeo inteiro de uma vez. Ele constrói um pacote de conhecimento que pode ser pesquisado novamente:

1. Busque áudio, legendas no idioma original quando disponíveis, metadados e um stream de vídeo de baixa resolução para a etapa visual do YouTube. Com --skip-video, o download do vídeo é adiado até que os quadros sejam solicitados.
2. Divida o áudio em blocos e solicite transcrição em nível de palavra e informações do falante ao Gemini.
3. Monte os blocos concluídos e, quando houver uma faixa de legenda no idioma original, use termos correspondentes em escrita latina para preencher lacunas na transcrição.
4. Extraia quadros nos momentos de referência de tela da transcrição, nos momentos de termos restaurados e nos timestamps solicitados pelo usuário.
5. Indexe transcrição, capítulos, falantes e quadros no SQLite.
6. Deixe o cliente de IA recuperar as evidências relevantes e escrever a resposta com timestamps.

As etapas se comunicam por meio de arquivos JSON e podem ser reexecutadas de forma independente. Blocos concluídos são reutilizados quando a entrada e as configurações coincidem. Respostas brutas de transcrição são salvas antes da validação, então uma falha de análise não gasta automaticamente outra chamada ao Gemini na mesma resposta.

A etapa opcional render cria arquivos SRT e TXT. Texto que excede o limite é transferido para a próxima legenda em vez de ser descartado silenciosamente, preservando 100% das palavras na saída renderizada.

Seleção de idioma e proteção contra tradução

Informe o idioma original do vídeo quando possível, por exemplo --language en-US, --language ko-KR, ou outro código BCP-47. Sem isso, o Gemini pode ocasionalmente retornar uma tradução em vez de uma transcrição literal.

O CuePrecise verifica cada bloco contra o que estiver disponível entre legendas no idioma original, idioma solicitado e metadados do vídeo. Se detectar uma tradução, ele para antes de gastar chamadas nos blocos restantes. Se não houver uma base utilizável, a proteção é ignorada e registrada como tal. A verificação usa material já obtido e não faz uma chamada extra à API.

Referência da linha de comando

python src/pipeline.py run <url> [options]
python src/pipeline.py status <video_id>
python src/pipeline.py purge <video_id> --scope <scope>

Opções comuns do run:

• --language — códigos de idioma BCP-47 separados por vírgula; especificar o idioma original é recomendado
• --stages — etapas a executar; all inclui etapas opcionais
• --bundle-root — diretório para pacotes de vídeo
• --force — ignorar resultados em cache e reconstruir
• --skip-video — pular o download do vídeo
• --keep-video — manter o vídeo após a extração de quadros
• --at — timestamps, em segundos, nos quais extrair quadros
• --max-frames — número máximo de quadros; padrão 40
• --chunk-max-secs — comprimento máximo do bloco; padrão 1790 segundos
• --overlap-secs — sobreposição entre blocos; padrão 10 segundos
• --daily-limit, --rpm-limit — limites locais de uso do Gemini
• --width — largura da linha da legenda; padrão 20. Use 42 ao renderizar legendas em inglês.

Reconstruir saída derivada selecionada ou limpar material de origem:

python src/pipeline.py run <url> --stages render
python src/pipeline.py run <url> --stages visual
python src/pipeline.py purge <id> --scope chunks

--scope aceita chunks, video, derived, raw ou all. A exclusão é explícita.

Desempenho e uso

O pipeline foi projetado para retomar. Blocos concluídos são reutilizados quando a entrada e as configurações não mudam, e o pós-processamento local, como mesclagem, extração visual e indexação, não chama o Gemini.

O tamanho do pacote depende do áudio, da transcrição e dos quadros selecionados do vídeo. O vídeo de origem é normalmente removido após a extração de quadros; use --keep-video para mantê-lo. O áudio da transcrição pode ser removido com purge --scope chunks.

Um registro de uso local registra tentativas por um hash da chave de API e data do Pacífico, nunca a chave original. O CuePrecise mostra as chamadas esperadas antes de um trabalho começar e para se um limite configurado for excedido. O Google AI Studio continua sendo a autoridade para uso no lado do servidor.

Requisitos

• Python 3.11+
• ffmpeg e ffprobe para divisão de áudio e extração de quadros
• Pacotes Python opcionais pytesseract e Pillow, além do binário tesseract, para OCR de quadros

python -m pip install -r requirements.txt
python -m pip install -r requirements-optional.txt  # optional OCR and timezone support

A distribuição instalável é cueprecise-mcp, com cueprecise e cueprecise-mcp como seus pontos de entrada de linha de comando. Ela ainda não foi publicada no PyPI, então instale a partir da URL do GitHub acima.

Testes

python -m unittest discover -s tests

A suíte usa o executor unittest da biblioteca padrão. Os testes não acessam a rede nem chamam a API do Gemini. Testes que exigem google-genai são ignorados quando o SDK não está instalado.

Limitações conhecidas

• Erros de ortografia nas legendas do YouTube podem permanecer nos termos recuperados, e as legendas podem não estar disponíveis.
• O OCR exige os pacotes opcionais pytesseract e Pillow e o binário Tesseract.
• O limite de mesclagem de legendas foi ajustado em um conjunto limitado de vídeos reais e precisa de validação mais ampla.
• Em três ou mais blocos, um falante ausente da sobreposição pode permanecer unresolved. O CuePrecise evita atribuir uma identidade potencialmente incorreta.
• O caminho de interrupção/retomada para um trabalho de longa duração na API real ainda precisa de validação de ponta a ponta.
• A correspondência de frases de referência visual atualmente se concentra em coreano e inglês.
• A busca visual é baseada em candidatos: ela prioriza referências de tela da transcrição e timestamps solicitados em vez de inspecionar cada quadro semanticamente.
• A recuperação entre idiomas é lexical, em vez de baseada em tradução ou embeddings; termos originais podem ser necessários quando a IA do host não traduz a consulta.
• Timestamps atribuídos a palavras recuperadas de legendas são colocados dentro da lacuna de transcrição ausente e devem ser tratados como aproximados dentro desse intervalo.

Documentação

• README.ko.md — README em coreano
• CODE_SIGNING_POLICY.md — política de revisão e assinatura de lançamentos para Windows
• PRIVACY.md — chaves de API, dados locais, serviços externos e comportamento de desinstalação
• CONTRACT.md — contratos de dados autoritativos e regras de validação
• DECISIONS/ — decisões de design e alternativas rejeitadas
• CONTRIBUTING.md — ambiente de desenvolvimento e processo de pull request
• SECURITY.md — relato privado de vulnerabilidades

Roteiro

• Links de timestamp específicos do host
• Transcrição de blocos em pipeline
• Pesquisa multi-vídeo com evidências específicas da fonte

Agradecimentos

O fluxo inicial de transcrição foi informado pelo gemini-transcribe-wrapper licenciado sob MIT. O CuePrecise é um projeto escrito de forma independente.

Licença

MIT. Consulte LICENSE.

O CuePrecise não é afiliado ou endossado pelo YouTube ou Google. O YouTube é um serviço suportado, não parte do nome do produto.