Cueprecise

Español | 한국어

CuePrecise

Encuentra el momento relevante en un video largo de YouTube—y ve la evidencia detrás de la respuesta.

Un video largo en un idioma que no hablas aún puede ser buscable. CuePrecise es un servidor MCP de código abierto para Claude Desktop, Codex, Cursor y otros clientes de IA. Convierte el habla original de un video de YouTube, los subtítulos disponibles, las etiquetas de hablantes y los fotogramas seleccionados en una referencia local buscable. El índice permanece en el idioma original del video; tu cliente de IA puede traducir una pregunta en términos de búsqueda, pero la recuperación entre idiomas no está garantizada.

En una configuración probada, CuePrecise analiza videos de más de una hora en aproximadamente tres minutos. No envía el video completo a tu cliente de IA para cada pregunta. Transcribe el audio original en fragmentos, indexa la evidencia y recupera solo los pasajes y fotogramas relacionados con tu pregunta.

La transcripción comienza con el audio original. Cuando hay una pista de subtítulos de YouTube en el idioma original disponible, CuePrecise la usa para recuperar términos y frases en escritura latina que coincidan y que la transcripción omitió. Puedes preguntar a tu cliente de IA en tu propio idioma, pero una recuperación confiable puede requerir la redacción original. Los resultados aún incluyen las palabras originales, la información del hablante, los fotogramas relevantes y una marca de tiempo que te lleva de vuelta a YouTube. El tiempo de procesamiento real depende del video, la red y el tiempo de respuesta de la API.

Véalo en acción

La demostración adjunta usa una entrevista en polaco. Pregunte de qué trata en su propio idioma; CuePrecise devuelve los momentos relevantes, la transcripción original y los fotogramas coincidentes como evidencia.

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

_{Fuente de la demostración: “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, bajo licencia CC BY.}

Descargar CuePrecise → GitHub Releases

• Salta a la respuesta. Obtén una marca de tiempo para cada elemento de un resumen.
• Mantén separados a los hablantes. Compara lo que dijo cada persona y por qué.
• Encuentra de nuevo una pantalla referenciada. Conecta un fotograma relevante con lo que se estaba explicando.
• Verifica la fuente. Abre el video original de YouTube en el momento citado.

Prueba preguntas 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?

En Claude Desktop, hacer clic en una marca de tiempo abre YouTube en ese momento. Otros clientes de IA pueden mostrar los enlaces de marca de tiempo de manera diferente.

Mantiene las respuestas vinculadas a la evidencia

CuePrecise no es solo un resumidor. Le da a tu cliente de IA el material que necesita para responder una pregunta y te permite verificar de dónde provino la respuesta:

• Transcripción palabra por palabra de Gemini del habla original.
• Subtítulos de YouTube en el idioma original, cuando están disponibles, alineados con la misma línea de tiempo.
• Fotogramas de frases de referencia de pantalla de la transcripción, términos restaurados o marcas de tiempo solicitadas.
• Etiquetas de hablante, confianza de la evidencia y procedencia de los fragmentos recuperados.

Cuando la búsqueda no encuentra un pasaje de respaldo, CuePrecise informa que no hay evidencia en el material indexado en lugar de inventar una fuente. El paquete de evidencia resultante permanece en tu computadora, por lo que una conversación posterior puede buscar el mismo video sin empezar de nuevo. Los fragmentos de audio utilizados para la transcripción se envían a Gemini; consulta PRIVACY.md para conocer el límite de red.

Recuperar un término que la transcripción omitió

Los nombres y términos técnicos son fáciles de perder en una transcripción larga. En una conferencia técnica en coreano de 23 minutos, la frase self supervised learning desapareció de las cuatro ejecuciones de transcripción solo con 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.

CuePrecise verifica los subtítulos de YouTube del mismo rango de tiempo y completa solo una brecha coincidente. No reescribe las palabras de Gemini. Las palabras proporcionadas por los subtítulos conservan su origen.

El ejemplo medido se veía así:

• Los subtítulos originales de YouTube en el idioma original contenían 91 palabras en escritura latina y la frase faltante.
• Las ejecuciones de Gemini contenían 28–29 palabras en escritura latina, pero omitieron la frase cada vez.
• El resultado combinado contenía 38 palabras en escritura latina y recuperó la frase manteniendo la calidad de la transcripción en coreano.

Este es un caso límite medido, no una afirmación general de precisión. Las reglas exactas de combinación y los criterios de validación están documentados en CONTRACT.md.

Comparar hablantes sin pretender saber sus nombres

CuePrecise transporta la información del hablante a través de los fragmentos de un video largo. Las etiquetas de hablante son identificadores, no nombres reales. Las identidades confirmadas e inferidas se mantienen separadas, y la evidencia débil permanece sin resolver en lugar de presentarse como un hecho.

Eso permite que tu cliente de IA:

• recopile las afirmaciones y pasajes de respaldo de un hablante;
• compare las posiciones de varios hablantes;
• simule un debate sobre un nuevo tema usando las declaraciones reales de los hablantes como evidencia.

Un debate simulado se genera a partir del video. No es una afirmación de que esas personas realmente discutieron el nuevo tema.

Inicio rápido

Claude Desktop en Windows — extensión de un solo archivo

1. Abre Releases y descarga cueprecise-windows.mcpb.
2. En Claude Desktop, abre Configuración → Extensiones → Configuración avanzada → Instalar extensión.
3. Selecciona el archivo. Claude pedirá una clave de API de Gemini y una carpeta para los datos locales de video.
4. Habilita CuePrecise y pregunta a Claude sobre un enlace de YouTube.

El paquete de aproximadamente 86 MiB incluye CuePrecise, yt-dlp, FFmpeg y FFprobe. No necesitas instalar Python, Git ni las herramientas de video por separado. La extensión está actualmente disponible para Claude Desktop en Windows.

Otros clientes de IA en Windows

1. Abre Releases y descarga cueprecise-setup.exe.
2. Ejecuta el instalador, haz clic en Crear clave de API y pega una clave de Google AI Studio.
3. Selecciona los clientes de IA encontrados en tu computadora y haz clic en Conectar.
4. Cierra y vuelve a abrir por completo los clientes conectados.

El instalador verifica FFmpeg y FFprobe e instala FFmpeg a través de WinGet cuando falta. Agrega solo la entrada de CuePrecise y hace una copia de seguridad de la configuración existente cuando puede hacerlo de manera segura; un TOML de Codex que contenga secretos puede dejarse sin copia de seguridad para evitar copiar la clave. En Windows, la clave de API se cifra con DPAPI de Windows para el usuario actual. Las claves de CuePrecise en texto plano más antiguas se mueven al almacén protegido durante una actualización.

Vista previa sin firmar: v0.2.5 no está firmada digitalmente, por lo que Windows puede mostrar una advertencia de editor desconocido. Descárgala solo desde la página de Releases de este repositorio y verifica SHA256SUMS.txt si deseas comprobar el archivo antes de instalarlo.

macOS, Linux e instalación desde la línea de comandos

Con uv:

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

El comando de configuración configura los clientes de IA compatibles detectados, incluido Claude Desktop, y crea el directorio de datos predeterminado ~/.cueprecise/data. Mantiene un archivo .bak con marca de tiempo cuando cambia una configuración existente, a menos que un formato de configuración que contenga secretos no pueda respaldarse de manera segura.

Instala ffmpeg y ffprobe, luego verifica el entorno:

cueprecise doctor

Crea una clave de API de Gemini, luego pásala a través de la entrada estándar o un archivo para que no aparezca en el comando ni en el historial del 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

Si una clave queda expuesta, elimínala en Google AI Studio y crea una nueva. Consulta PRIVACY.md para el procedimiento completo.

Solo para desarrollo de código fuente:

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 compatibles

cueprecise setup puede detectar y configurar estos clientes:

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

Las rutas de configuración de Cursor, Windsurf y Gemini CLI son objetivos de configuración automática, pero no se han probado de extremo a extremo en la máquina de desarrollo actual.

Ejecútalo para cada cliente detectado, para un cliente nombrado o para inspeccionar el resultado:

cueprecise setup
cueprecise setup --client codex
cueprecise doctor

Una aplicación se considera instalada cuando su ejecutable está en PATH. Una carpeta de configuración sobrante no se trata como prueba de que la aplicación está presente. Un cliente no detectado puede aún nombrarse explícitamente con --client <name>.

CuePrecise omite una entrada cueprecise existente si CuePrecise no la creó. No sobrescribe la configuración de otro servidor MCP, y un fallo para un cliente no detiene a los demás.

Los conectores de ChatGPT y Claude.ai en la web no son compatibles actualmente con el transporte stdio local de CuePrecise. Los clientes web que requieren un servidor MCP HTTP remoto no pueden usar esta configuración.

Conectar otro host MCP

CuePrecise acepta tanto la revisión MCP de solicitud por solicitud 2026-07-28 como el protocolo de enlace anterior initialize. Se prefiere cueprecise setup porque preserva la configuración existente y maneja las credenciales para los clientes compatibles.

El JSON a continuación es para una copia del código fuente o un host MCP no listado arriba. Almacena la clave en texto plano, así que usa el comando de configuración cuando sea posible:

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

Usa rutas absolutas. En todas las plataformas, el --api-key VALUE literal se rechaza para mantener la clave fuera de los listados de procesos y el historial del shell. El servidor puede iniciarse sin GEMINI_API_KEY: los análisis existentes permanecen buscables, mientras que las nuevas solicitudes de transcripción se detienen con un mensaje de configuración.

Herramientas MCP

Las herramientas se dividen en cuatro grupos.

Análisis y estado:

• cueprecise_register — registrar y analizar un video de YouTube. Puedes elegir las etapas a ejecutar.
• cueprecise_status — informar el progreso, los artefactos generados y el uso local estimado.

Búsqueda y evidencia:

• cueprecise_outline — devolver un esquema con marcas de tiempo, términos recuperados y estado del hablante.
• cueprecise_query — buscar evidencia de transcripción y fotogramas relacionados.
• cueprecise_excerpt — devolver transcripción y fotogramas para un rango de tiempo específico.
• cueprecise_frames — extraer fotogramas alrededor de momentos de referencia de pantalla o marcas de tiempo solicitadas.

Resultados guardados:

• cueprecise_summary — crear o recuperar un resumen.
• cueprecise_set_summary — validar y guardar un resumen mejorado por el host.
• cueprecise_set_chapter_titles — validar y guardar títulos de capítulos escritos por el host.

Limpieza:

• cueprecise_purge — eliminar explícitamente fragmentos, video fuente, resultados derivados, datos sin procesar o todos los datos.

Después de la obtención de YouTube y la transcripción de Gemini, el ensamblaje, la combinación de subtítulos, los capítulos, el renderizado, la extracción visual y la indexación se ejecutan localmente. Los títulos de capítulos y los resúmenes son escritos por el IA del host a partir de la evidencia recuperada; CuePrecise no crea otra llamada de transcripción de Gemini.

Paquete de evidencia local

El instalador y cueprecise setup usan ~/.cueprecise/data. Una copia del código fuente puede usar data a menos que establezcas --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 fragmento de evidencia indexado mantiene su marca de tiempo, estado del hablante, confianza de la evidencia y origen. Los datos de palabras combinados también mantienen marcas de tiempo por palabra y origen:

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

Un resultado de consulta incluye el rango de tiempo, el texto, la fuente, la confianza y cualquier fotograma 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
}

Los fotogramas no se muestrean de manera uniforme en todo el video. CuePrecise prioriza las frases de referencia de pantalla en la transcripción, los términos restaurados de los subtítulos y las marcas de tiempo solicitadas por el usuario. No clasifica semánticamente cada código, tabla o fotograma de diagrama. Si OCR está instalado, el texto reconocido se almacena como procedencia separada en lugar de reemplazar silenciosamente la transcripción.

Cómo funciona

CuePrecise no intenta hacer que tu cliente de IA vea el video completo en una sola pasada. Construye un paquete de conocimiento que se puede buscar nuevamente:

1. Obtén el audio, los subtítulos en el idioma original cuando estén disponibles, los metadatos y un flujo de video de baja resolución para la etapa visual desde YouTube. Con --skip-video, la descarga del video se difiere hasta que se soliciten los fotogramas.
2. Divide el audio en fragmentos y solicita transcripción a nivel de palabra e información del hablante a Gemini.
3. Ensambla los fragmentos completados y, cuando exista una pista de subtítulos en el idioma original, usa términos coincidentes en escritura latina para llenar los vacíos en la transcripción.
4. Extrae fotogramas en los momentos de referencia de pantalla de la transcripción, en los momentos de términos restaurados y en las marcas de tiempo solicitadas por el usuario.
5. Indexa transcripción, capítulos, hablantes y fotogramas en SQLite.
6. Permite que el cliente de IA recupere la evidencia relevante y redacte la respuesta con marcas de tiempo.

Las etapas se comunican mediante archivos JSON y pueden volver a ejecutarse de forma independiente. Los fragmentos completados se reutilizan cuando la entrada y la configuración coinciden. Las respuestas de transcripción sin procesar se guardan antes de la validación, por lo que un fallo de análisis no gasta automáticamente otra llamada a Gemini en la misma respuesta.

La etapa opcional render crea archivos SRT y TXT. El texto que se desborda se traslada a la siguiente pista en lugar de descartarse silenciosamente, preservando el 100% de las palabras en la salida renderizada.

Selección de idioma y protección contra traducción

Pasa el idioma original del video cuando sea posible, por ejemplo --language en-US, --language ko-KR, u otro código BCP-47. Sin esto, Gemini ocasionalmente puede devolver una traducción en lugar de una transcripción literal.

CuePrecise verifica cada fragmento contra cualquiera de los subtítulos en el idioma original, el idioma solicitado y los metadatos del video que estén disponibles. Si detecta una traducción, se detiene antes de gastar llamadas en los fragmentos restantes. Si no hay una base utilizable, la protección se omite y se registra como tal. La verificación usa material ya obtenido y no realiza una llamada API adicional.

Referencia de línea de comandos

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

Opciones comunes de run:

• --language — códigos de idioma BCP-47 separados por comas; se recomienda especificar el idioma original
• --stages — etapas a ejecutar; all incluye etapas opcionales
• --bundle-root — directorio para paquetes de video
• --force — ignorar resultados en caché y reconstruir
• --skip-video — omitir la descarga del video
• --keep-video — conservar el video después de la extracción de fotogramas
• --at — marcas de tiempo, en segundos, en las que extraer fotogramas
• --max-frames — número máximo de fotogramas; predeterminado 40
• --chunk-max-secs — longitud máxima de fragmento; predeterminado 1790 segundos
• --overlap-secs — superposición entre fragmentos; predeterminado 10 segundos
• --daily-limit, --rpm-limit — límites de uso local de Gemini
• --width — ancho de línea de subtítulos; predeterminado 20. Usa 42 al renderizar subtítulos en inglés.

Reconstruye la salida derivada seleccionada o limpia el material fuente:

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 acepta chunks, video, derived, raw o all. La eliminación es explícita.

Rendimiento y uso

El pipeline está diseñado para reanudarse. Los fragmentos completados se reutilizan cuando la entrada y la configuración no cambian, y el postprocesamiento local como la fusión, la extracción visual y la indexación no llama a Gemini.

El tamaño del paquete depende del audio del video, la transcripción y los fotogramas seleccionados. El video fuente normalmente se elimina después de la extracción de fotogramas; usa --keep-video para conservarlo. El audio de transcripción se puede eliminar con purge --scope chunks.

Un registro de uso local registra los intentos mediante un hash de la clave API y la fecha del Pacífico, nunca la clave original. CuePrecise muestra las llamadas esperadas antes de que comience un trabajo y se detiene si se excedería un límite configurado. Google AI Studio sigue siendo la autoridad para el uso del lado del servidor.

Requisitos

• Python 3.11+
• ffmpeg y ffprobe para la división de audio y la extracción de fotogramas
• Paquetes Python opcionales pytesseract y Pillow, además del binario tesseract, para OCR de fotogramas

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

La distribución instalable es cueprecise-mcp, con cueprecise y cueprecise-mcp como sus puntos de entrada de línea de comandos. Aún no se ha publicado en PyPI, así que instala desde la URL de GitHub anterior.

Pruebas

python -m unittest discover -s tests

El conjunto usa el ejecutor unittest de la biblioteca estándar. Las pruebas no acceden a la red ni llaman a la API de Gemini. Las pruebas que requieren google-genai se omiten cuando el SDK no está instalado.

Limitaciones conocidas

• Los errores ortográficos de los subtítulos de YouTube pueden permanecer en los términos recuperados, y los subtítulos pueden no estar disponibles.
• El OCR requiere los paquetes opcionales pytesseract y Pillow y el binario de Tesseract.
• El umbral de fusión de subtítulos se ajustó en un conjunto limitado de videos reales y necesita una validación más amplia.
• En tres o más fragmentos, un hablante ausente de la superposición puede permanecer unresolved. CuePrecise evita asignar una identidad potencialmente incorrecta.
• La ruta de interrupción/reanudación para un trabajo de larga duración en la API real aún necesita validación de extremo a extremo.
• La coincidencia de frases de referencia visual se centra actualmente en coreano e inglés.
• La búsqueda visual está basada en candidatos: prioriza las referencias de pantalla de la transcripción y las marcas de tiempo solicitadas en lugar de inspeccionar cada fotograma semánticamente.
• La recuperación entre idiomas es léxica en lugar de basada en traducción o incrustaciones; los términos originales pueden ser necesarios cuando la IA anfitriona no traduce la consulta.
• Las marcas de tiempo asignadas a las palabras recuperadas de subtítulos se colocan dentro del vacío de transcripción faltante y deben tratarse como aproximadas dentro de ese intervalo.

Documentación

• README.ko.md — README en coreano
• CODE_SIGNING_POLICY.md — Política de revisión y firma de versiones de Windows
• PRIVACY.md — Claves API, datos locales, servicios externos y comportamiento de desinstalación
• CONTRACT.md — Contratos de datos autoritativos y reglas de validación
• DECISIONS/ — Decisiones de diseño y alternativas rechazadas
• CONTRIBUTING.md — Entorno de desarrollo y proceso de solicitudes de extracción
• SECURITY.md — Reporte privado de vulnerabilidades

Hoja de ruta

• Enlaces de marca de tiempo específicos del host
• Transcripción de fragmentos en pipeline
• Investigación de múltiples videos con evidencia específica de la fuente

Agradecimientos

El flujo de transcripción inicial se basó en el gemini-transcribe-wrapper con licencia MIT. CuePrecise es un proyecto escrito de forma independiente.

Licencia

MIT. Ver LICENSE.

CuePrecise no está afiliado ni respaldado por YouTube o Google. YouTube es un servicio compatible, no parte del nombre del producto.