yueying

yueying — deja que la IA vea videos

Apunta Claude, Cursor o cualquier cliente MCP a un video y obtén una transcripción con marcas de tiempo y hojas de contacto de fotogramas clave — sin conexión, sin clave API. Primero los archivos locales; las URLs (YouTube, Bilibili, Douyin, Xiaohongshu, TikTok, Vimeo, …) son videos que tienes derecho a procesar, descargados mediante yt-dlp a ≤720p y eliminados después del procesamiento por defecto.

中文说明 ↓

Yueying (阅影) significa "leer video". Un solo paquete te ofrece un servidor MCP, una CLI y una habilidad de agente.

Lo que obtienes

Claude Desktop con yueying conectado: pega un enlace, espera unos cuarenta segundos, y recibe el video como notas con marcas de tiempo. Este video incluye subtítulos, por lo que el reconocimiento de voz nunca se ejecutó, y el modelo solo pidió la transcripción. Los fotogramas clave y las hojas de contacto vuelven a través de get_frames cuando necesita ver la pantalla. Video de demostración: GitInGifs: Git Branches de GitLab, CC BY.

Hoja de contacto de un clip de demostración de 24 segundos (cuatro capturas de pantalla de la aplicación con narración en chino). La etiqueta amarilla en cada mosaico es el número de fotograma clave y la marca de tiempo; el modelo las cita de vuelta para ti.

La transcripción del mismo clip — reconocimiento de voz local, idioma auto-detectado como chino:

[00:00] 这是阅读,一个安静的桌面小说阅读器。整本书连续滚动,按段落记住进度。
        第二个画面是桌面模式,窗口变透明,只留文字浮在桌面上。
        第三个画面是伪装皮肤,一键变成代码编辑器。
        最后是伪装成表格的样子。

(La aplicación se llama 月读; el ASR escuchó el homófono 阅读. El reconocimiento de voz hace eso con los nombres — el modelo lo corrige a partir del texto en pantalla en los fotogramas.)

Cada video se convierte en una carpeta:

report.md          index for the model: metadata, chapters, contact sheets, keyframes, transcript
transcript.txt     paragraphs with [mm:ss] timestamps
transcript.srt     subtitles for any player
grid_01.jpg …      3x3 contact sheets, 9 keyframes each, in time order
frames/            full-size keyframes, e.g. f003_00m15s.jpg
manifest.json      machine-readable result (paths, segments, chapters, options)

Por qué yueying

• Subtítulos primero, Whisper solo cuando sea necesario. Se usan los subtítulos de la plataforma cuando existen. De lo contrario, faster-whisper local: large-v3-turbo en una GPU NVIDIA, small en CPU, con respaldo automático a CPU — nada se sube, sin clave.
• ffmpeg incluido. Funciona en Windows 11 de fábrica (imageio-ffmpeg); sin ajustes de PATH.
• Eficiente en tokens. Los fotogramas clave se toman en cambios de escena, se eliminan los casi duplicados, y luego se empaquetan en hojas de contacto de 3x3 con marcas de tiempo incrustadas. Una hoja ≈ 1–2K tokens por nueve momentos; una transcripción con [mm:ss] párrafos.
• Plataformas chinas y el resto. Bilibili (multipartes, colecciones, videos de miembros con tu inicio de sesión del navegador), Douyin, Xiaohongshu — y YouTube, TikTok, Vimeo, X y cualquier otro sitio de yt-dlp.
• Cero claves API, cero telemetría. El único tráfico de red es el sitio de video que nombras y una descarga del modelo Whisper. Consulta la política de privacidad.

Punto de referencia: un video de Bilibili de 6 minutos → informe en ~90 s en una laptop RTX 5060; en CPU con model=small espera ~1–2 min por cada 10 min de habla.

Inicio rápido

1. Instala uv (Python no es necesario):

   winget install astral-sh.uv                         # Windows
   brew install uv                                     # macOS
   curl -LsSf https://astral.sh/uv/install.sh | sh     # Linux / macOS
   

2. Calienta y verifica todo una vez (instala el paquete, prueba la GPU, descarga el modelo de voz, ejecuta una prueba de humo de 2 segundos, imprime la configuración para pegar):

   uvx yueying mcp --setup
   

3. Agrega el servidor a tu cliente (abajo), luego pregunta: "Mira C:\videos\lecture3.mp4 y convierte los pasos en notas" o "¿Qué dice este video sobre docker compose: https://www.bilibili.com/video/BV…?".

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) · ~/Library/Application Support/Claude/claude_desktop_config.json (macOS). Cierra y vuelve a abrir Claude completamente después.

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

Nota de Windows: Claude Desktop no siempre ve tu PATH — si el servidor falla al iniciar ("spawn uvx ENOENT"), usa la ruta absoluta, p. ej. "command": "C:\\Users\\<you>\\.local\\bin\\uvx.exe" (where uvx la imprime). Registros: %APPDATA%\Claude\logs\mcp-server-yueying.log (~/Library/Logs/Claude/ en macOS). Mantén wait_seconds en su valor predeterminado allí; consulta la regla RUNNING.

Claude Code

claude mcp add --transport stdio --scope user yueying --env PYTHONUTF8=1 -- uvx yueying mcp

O coloca el .mcp.json de este repositorio en un proyecto (incluye "timeout": 1800000 para que una sola llamada a watch_video pueda esperar un video largo). Para aumentar el tiempo de espera de herramientas de Claude Code globalmente, establece MCP_TOOL_TIMEOUT=1800000 (ms) en tu entorno. El repositorio también es un plugin de Claude Code (.claude-plugin/plugin.json: servidor + habilidad).

Cursor

Haz clic en la insignia Add to Cursor arriba, o coloca el mismo JSON en ~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto):

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

Cline

MCP Servers → Configure (cline_mcp_settings.json). timeout está en segundos; las cinco herramientas de solo lectura son seguras para aprobación automática. Instrucciones de agente paso a paso: llms-install.md.

{
  "mcpServers": {
    "yueying": {
      "type": "stdio",
      "command": "uvx",
      "args": ["yueying", "mcp"],
      "env": { "PYTHONUTF8": "1" },
      "timeout": 1800,
      "autoApprove": ["get_transcript", "search_transcript", "get_frames", "get_frame_at", "list_videos"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

VS Code (modo agente de Copilot)

Haz clic en la insignia Install in VS Code arriba, o crea .vscode/mcp.json (nota la clave raíz servers):

{ "servers": { "yueying": { "type": "stdio", "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

Enlaces directos para hosts que aceptan esquemas de URL personalizados: cursor://anysphere.cursor-deeplink/mcp/install?name=yueying&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJ5dWV5aW5nIiwibWNwIl0sImVudiI6eyJQWVRIT05VVEY4IjoiMSJ9fQ== y vscode:mcp/install?%7B%22name%22%3A%22yueying%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22yueying%22%2C%22mcp%22%5D%2C%22env%22%3A%7B%22PYTHONUTF8%22%3A%221%22%7D%7D.

Sin uv (pip / pipx) y Windows con un clic

pip install yueying            # or: pipx install yueying
yueying mcp --setup            # prints a config with the absolute path of the yueying-mcp executable

Usa esa ruta absoluta como "command" sin args (Windows: ...\Scripts\yueying-mcp.exe; también funciona como python -m yueying mcp). Los usuarios de Windows sin herramientas de Python pueden hacer doble clic en install.cmd desde un checkout: crea %LOCALAPPDATA%\yueying\venv, instala la habilidad de Claude Code, ejecuta yueying mcp --setup e imprime el bloque JSON con la ruta correcta.

GPU

uvx --from "yueying[cuda]" yueying mcp     # NVIDIA: adds the CUDA runtime wheels (cuBLAS, cuDNN)
pip install "yueying[cuda]"

El dispositivo y el modelo se eligen automáticamente (model=auto: large-v3-turbo en CUDA, small en CPU); si la prueba de GPU falla, el reconocimiento vuelve a CPU por sí mismo.

Docker

docker build -t yueying .
docker run --rm -i -v yueying-data:/data -v "$PWD/videos:/videos:ro" yueying

La imagen es solo CPU (los contenedores no obtienen GPU por defecto), por lo que usa el modelo small por defecto. Monta tus videos como solo lectura y da a las herramientas rutas de contenedor (/videos/lesson.mp4); los resultados y los pesos de Whisper descargados viven en el volumen /data. En una configuración de cliente, el command es docker y args son ["run", "--rm", "-i", "-v", "yueying-data:/data", "-v", "/your/videos:/videos:ro", "yueying"].

Herramientas

Herramienta	Cuándo la usa el agente	Qué devuelve	Límites
watch_video(video, mode="full", language="auto", model="auto", frame_interval_seconds=None, cookies_from_browser=None, output_dir=None, refresh=False, wait_seconds=45, max_chars=12000)	Primera llamada para cualquier video: una ruta local absoluta o una URL. mode: full (transcripción + fotogramas clave), transcript, frames.	DONE resumen: título, fuente, duración, fuente de texto, carpeta, archivos, capítulos, rangos de hojas de contacto, transcripción en [mm:ss] párrafos — o RUNNING con etapa/porcentaje/ETA, o ERROR con una pista en inglés sencillo.	Bloquea hasta wait_seconds (0–1500). Transcripción truncada en max_chars con un tiempo de inicio de get_transcript. Cacheado por video; refresh=true reprocesa.
get_transcript(video, start="0", end=None, format="paragraphs", max_chars=8000)	El resumen se truncó, un rango de tiempo específico, o exportar subtítulos (format="srt").	Encabezado + [mm:ss] párrafos / [mm:ss-mm:ss] segmentos / bloques SRT; TRUNCATED — next_start="…" cuando se corta.	max_chars 1000–100000. Tiempos: segundos, mm:ss, h:mm:ss.
search_transcript(video, query, context_seconds=15, limit=10)	"¿Cuándo menciona X?"	Coincidencias con tiempo, oraciones circundantes, número de fotograma clave más cercano y número de hoja de contacto.	Términos separados por espacios, cualquier coincidencia, más términos clasifican más alto; limit ≤ 50.
get_frames(video, kind="grids", start=1, count=2, max_width=1280)	Ver qué hay en pantalla: primero hojas de contacto (grids), fotogramas clave individuales (frames) solo para detalle.	Ruta absoluta + JPEG por imagen, en orden de tiempo; Next: get_frames(start=…) cuando quedan más.	≤ 3 imágenes por llamada (predeterminado 2, mantén ≤ 2 en Claude Desktop); ~150 KB por hoja a 1280 px.
get_frame_at(video, time, max_width=960)	Leer código, una diapositiva, un gráfico o interfaz en un momento.	El fotograma exacto (extraído de la fuente si el archivo local aún existe) o el fotograma clave cacheado más cercano, más los párrafos hablados alrededor.	Una imagen, ~100 KB a 960 px.
list_videos(limit=20)	El usuario se refiere a un video anterior, o para verificar el uso de disco.	Tabla: video_id, título, duración, fuente de texto, fecha, tamaño, carpeta; trabajos en ejecución.	Instantáneo, solo lectura.

video para las herramientas de lectura acepta el video_id de watch_video/list_videos, la carpeta de resultados, o la misma ruta/URL que diste a watch_video.

La regla RUNNING

El procesamiento puede tomar minutos, y la mayoría de los hosts limitan una llamada de herramienta a aproximadamente un minuto. Entonces watch_video espera como máximo wait_seconds, luego responde RUNNING video_id=… · stage 2/4 speech recognition 40% · elapsed 46 s · est. ~1 min remaining. El agente simplemente llama a watch_video de nuevo con el mismo video — se re-adjunta al mismo trabajo (las opciones se ignoran mientras se ejecuta; refresh=true reinicia). wait_seconds recomendado:

Host	wait_seconds	Por qué
Claude Desktop	45 (predeterminado)	tiempo de espera duro del cliente ~60 s
Cursor	45 (predeterminado)	60–120 s
Claude Code	hasta 1500	con .mcp.json timeout / MCP_TOOL_TIMEOUT = 1800000 ms
Cline	hasta 1500	con "timeout": 1800 (s)

Se envían notificaciones de progreso cada 1.5 s para hosts que las muestran. Se procesa un video a la vez por servidor; las solicitudes adicionales se ponen en cola.

Primera ejecución: el primer reconocimiento de voz descarga un modelo Whisper una vez (~480 MB small en CPU, ~1.6 GB large-v3-turbo en GPU). uvx yueying mcp --setup hace esto de antemano; de lo contrario, la línea RUNNING dice "la primera ejecución descarga ~… esto puede tomar varios minutos".

Dónde van los archivos

Raíz: $YUEYING_OUT_DIR si está configurado, si no ~/yueying_out. Una entrada por video, nombrada <slug>-<video_id> (yt-<id>, bili-<BV>, o el nombre del archivo) — nunca renombrada; el título vive en manifest.json.

~/yueying_out/
└── bili-BV1xx-3f9a2c1e/
    ├── report.md  transcript.txt  transcript.srt  manifest.json
    ├── grid_01.jpg … grid_07.jpg
    ├── frames/            f001_00m02s.jpg …   (+ frames/extra/ for get_frame_at)
    ├── .job               only while a job runs
    └── _download/         only with YUEYING_KEEP_SOURCE=1

Variable de entorno	Significado	Predeterminado
YUEYING_OUT_DIR	carpeta raíz para resultados (absoluta, ~ ok)	~/yueying_out
YUEYING_MODEL	predeterminado para el parámetro model	auto
YUEYING_DEVICE	auto / cuda / cpu	auto
YUEYING_LANG	idioma de report.md escrito por el servidor (en/zh)	en
YUEYING_COOKIES_FROM_BROWSER	navegador predeterminado para cookies (chrome, edge, firefox, …)	sin configurar
YUEYING_KEEP_SOURCE	1 mantiene la fuente descargada ≤720p en _download/ (habilita fotogramas de momento exacto para URLs)	sin configurar
YUEYING_MAX_JOBS	pipelines ejecutándose a la vez por servidor	1
YUEYING_JOB_TIMEOUT	límite duro por video, segundos	7200
HF_HOME	caché de Hugging Face (los pesos de Whisper viven aquí)	predeterminado de HF
HF_ENDPOINT	espejo, p. ej. https://hf-mirror.com	huggingface.co
PYTHONUTF8	configurar a 1 en Windows para evitar mojibake	—

Presupuesto de disco: ≈ 25 MB por hora de video; 300–600 MB/h más con YUEYING_KEEP_SOURCE=1. Nada se elimina automáticamente — list_videos muestra tamaños; elimina una carpeta para liberar espacio; watch_video(refresh=true) reprocesa un video. Editar un archivo local cambia su tamaño/mtime y por lo tanto obtiene una nueva entrada.

Fuentes compatibles

• Archivos locales: cualquier cosa que ffmpeg lea — mp4, mkv, mov, webm, avi, flv, ts, y audio (mp3, m4a, wav, …). La entrada solo de audio da una transcripción sin fotogramas.
• URLs: cada sitio que yt-dlp soporta. Descargado a ≤720p y eliminado después del procesamiento a menos que YUEYING_KEEP_SOURCE=1.
• Bilibili: sin inicio de sesión, Bilibili sirve 480p — suficiente para diapositivas y código. Para HD o videos solo de miembros, pasa cookies_from_browser="chrome" (o edge, firefox, brave, chromium, safari); en Windows cierra Chrome primero, bloquea su base de datos de cookies. Videos multiparte y colecciones: los enlaces p= son entradas separadas; el --all de la CLI los procesa todos.
• No para transmisiones en vivo o imágenes. Enlaces cortos (b23.tv, v.douyin.com) se procesan pero no se deduplican contra su forma larga (el servidor nunca resuelve URLs por sí mismo).

También una CLI y una habilidad de agente

yueying video.mp4
yueying "https://www.bilibili.com/video/BVxxxx" --ui-lang en
yueying "https://www.youtube.com/watch?v=xxxx" --out ./notes/xxx
yueying lesson1.mp4 lesson2.mp4 "https://www.bilibili.com/video/BVyyyy"   # several at once, one folder each + index.md
yueying "https://www.bilibili.com/video/BVxxxx" --all                      # every part of a multi-part video / collection
yueying --install-skill                                                    # Claude Code skill -> ~/.claude/skills/yueying

Salida predeterminada: ./yueying_out/<name>/ (carpeta principal cuando hay varias entradas). Las líneas de registro de la CLI y report.md están en chino por defecto (--ui-lang en para inglés); 0.3 cambiará el predeterminado a inglés.

Indicador	Significado
--out DIR	carpeta de salida (por defecto ./yueying_out/<name>; la carpeta principal cuando hay varias entradas)
--all	cuando la URL es un video multiparte / colección / lista de reproducción de Bilibili, procesa cada entrada (por defecto: solo la primera)
--lang zh	código de idioma hablado (zh, en, ja, …); detección automática por defecto
--model auto	modelo Whisper: auto / tiny / base / small / medium / large-v3 / large-v3-turbo (predeterminado de CLI). auto = large-v3-turbo en una GPU NVIDIA, small en CPU
--device cpu	forzar CPU (auto / cuda / cpu)
--interval 3	aproximadamente un fotograma clave cada N segundos. Predeterminado según duración: 2 s bajo 1 min, 3 s bajo 3 min, 6 s bajo 10 min, 12 s bajo 30 min, 20 s más allá
--frames 30	número máximo de fotogramas clave (predeterminado según duración, tope 150; 300 con --interval)
--scene 0.2	sensibilidad de cambio de escena 0–1, menor = más sensible (predeterminado 0.3)
--no-dedupe	conservar fotogramas casi idénticos al anterior (por defecto los descarta: < 2 % de píxeles de miniatura cambiados)
--no-asr	sin reconocimiento de voz incluso sin subtítulos (solo imágenes)
--no-frames	sin fotogramas clave (solo texto)
--force-asr	ejecutar reconocimiento de voz incluso cuando existen subtítulos
--cookies-from-browser chrome	descargar con tu inicio de sesión del navegador (Bilibili HD / videos de miembros, YouTube con inicio de sesión)
--keep	conservar el video fuente descargado
--ui-lang en	idioma de los encabezados y etiquetas de report.md: zh (predeterminado) o en
--json	imprimir una línea de manifest JSON al final (para scripts)
--install-skill	instalar la habilidad del agente en ~/.claude/skills/yueying
mcp	ejecutar el servidor MCP (mcp --setup, mcp --check, mcp --version)

La habilidad (src/yueying/skill/SKILL.md) le indica a un agente de codificación que prefiera las herramientas MCP cuando estén presentes y, de lo contrario, ejecute la CLI y lea report.md más las hojas de contacto. Las herramientas que admiten el estándar Agent Skills pueden copiar ~/.claude/skills/yueying/SKILL.md en su propia carpeta de habilidades.

Comparación con proyectos similares (septiembre de 2026)

	yueying	claude-video	claude-real-video	mcp-video-analyzer
Servidor MCP	sí	no (solo habilidad)	no (habilidad)	sí (Node)
Reconocimiento de voz sin conexión	sí — subtítulos primero, faster-whisper local en caso contrario	Whisper en la nube como respaldo	ASR primero	whisper instalado por separado
Detección automática de GPU + respaldo de CPU	sí	–	–	–
ffmpeg incluido	sí	–	ffmpeg manual	–
Probado en Windows	sí (Windows 11)	–	–	–
Hojas de contacto (3x3)	sí	–	–	–
Marcas de tiempo incrustadas en fotogramas	sí	–	–	–
Bilibili / Douyin / Xiaohongshu	sí	–	–	–

"—" significa que el proyecto no anunciaba la función cuando lo consultamos; revisa sus README, es posible que hayan avanzado.

Política de privacidad

yueying no recopila nada y no tiene telemetría, análisis, informes de errores ni comprobaciones de actualizaciones. Todo el procesamiento es local. Las únicas conexiones de red son (1) al sitio de video de la URL que pasas, a través de yt-dlp, y (2) a Hugging Face (o HF_ENDPOINT) para descargar un modelo Whisper una vez. Los resultados se almacenan en tu carpeta hasta que los elimines. La transcripción y cualquier fotograma que solicites se envían solo al modelo que tu cliente MCP está configurado para usar — esa transferencia se rige por los términos de tu cliente y proveedor, no por yueying. Preguntas: Problemas de GitHub. Texto completo: docs/privacy.md.

Solución de problemas / Preguntas frecuentes

• "No se recibió ningún resultado" en Claude Desktop. Mantén wait_seconds en 45 (el agente entonces vuelve a llamar a watch_video), y ejecuta uvx yueying mcp --setup una vez para que la primera llamada no sea también la descarga del modelo.
• spawn uvx ENOENT / el servidor no se inicia. El host no puede ver tu PATH: usa la ruta absoluta a uvx (where uvx / which uvx) o a yueying-mcp como "command".
• Las ventanas de consola parpadean en Windows. Actualiza a 0.2.0+: los procesos secundarios se inician sin ventana. Si aún las ves, estás ejecutando una instalación antigua (uv cache clean yueying).
• Mojibake / ????? en títulos. Agrega "env": { "PYTHONUTF8": "1" } a la configuración del servidor (todos los fragmentos anteriores lo incluyen).
• Error 412 / "-352" de Bilibili. El sitio requiere inicio de sesión: cookies_from_browser="edge" o "chrome" (cierra Chrome primero en Windows).
• YouTube "Inicia sesión para confirmar que no eres un bot". Misma solución: cookies_from_browser. También intenta actualizar yt-dlp: uv cache clean yueying o pip install -U yt-dlp.
• Lento en CPU. model="small" ya es la opción automática sin una GPU NVIDIA; usa mode="frames" cuando solo importen las imágenes, o mode="transcript" para omitir los fotogramas clave.
• Nombres, números y código incorrectos en la transcripción. Esperado con cualquier ASR — se le indica al agente que confíe en el texto en pantalla; pídele que get_frame_at el momento.
• La descarga del modelo es lenta o está bloqueada (China continental). Establece HF_ENDPOINT=https://hf-mirror.com en el env del servidor (la CLI cambia al espejo automáticamente cuando huggingface.co es inaccesible).
• Error de GPU (CUDA / cuDNN / memoria insuficiente). model="small" o YUEYING_DEVICE=cpu; instala las ruedas CUDA con yueying[cuda].
• Quieres reprocesar con diferentes configuraciones. watch_video(video=…, refresh=true, …) — mata un trabajo en ejecución para ese video, elimina la entrada y comienza de nuevo.

Cómo funciona

video / URL ──► yt-dlp (≤720p) + platform subtitles
            ──► ffmpeg 16 kHz audio ──► faster-whisper (skipped when subtitles exist)
            ──► ffmpeg scene detection ──► keyframes (near-duplicates dropped)
            ──► Pillow: burn "#n mm:ss", pack 3x3 contact sheets
            ──► report.md · transcript.txt · transcript.srt · manifest.json

MCP client ──stdio──► mcp_server.py ──spawns──► python -m yueying.cli <video> --json --ui-lang en
                       │  parses the child's progress lines, long-polls, caches per video
                       └─► store.py (cache keys / folders) · query.py (paging, search, frames)

El proceso del servidor nunca carga yt-dlp, Whisper o CUDA por sí mismo; todo el trabajo pesado se ejecuta en un proceso secundario que se elimina con el servidor. Todo vive en src/yueying/:

Archivo	Responsabilidad
cli.py	entrada de línea de comandos; ejecuta el pipeline; despacho de subcomandos mcp; --install-skill
mcp_server.py	el servidor MCP: seis herramientas, ejecutor de trabajos, análisis de progreso, renderizado DONE/RUNNING/ERROR, --setup
store.py	raíz de salida, URLs canónicas, claves de caché y nombres de carpeta por video, marcadores .job
query.py	funciones puras sobre un manifest: paginación de transcripción, búsqueda, fotograma más cercano, rangos de hojas de contacto, reducción de imágenes
models.py	nombres de modelos Whisper, tamaños y repositorios de Hugging Face (sin importaciones pesadas)
download.py	descarga yt-dlp, elección de idioma de subtítulos, listado de listas de reproducción/colecciones
ffm.py	envoltorio ffmpeg: sonda, extracción de audio, subtítulos incrustados, tiempos de espera
subs.py	análisis de subtítulos srt / vtt / JSON de Bilibili, deduplicación de subtítulos automáticos de YouTube
asr.py	transcripción faster-whisper, selección GPU/CPU, modelo auto, respaldos
frames.py	detección de escenas, temporización de fotogramas, extracción, deduplicación, incrustación de marcas de tiempo, hojas de contacto
report.py	report.md, archivos de transcripción, manifest.json (etiquetas zh/en), carga de manifest
skill/SKILL.md	la habilidad del agente

Hoja de ruta

• siguiente — .mcpb paquete de un clic para Claude Desktop, listado en Smithery.
• 0.3 — herramientas de forget_video / poda, inglés como idioma de informe predeterminado de CLI, --all (listas de reproducción) a través de MCP.

Créditos

• faster-whisper, yt-dlp, imageio-ffmpeg, Pillow
• Las marcas de tiempo incrustadas en las hojas de contacto siguen video-vision-mcp; los intervalos de fotogramas basados en duración siguen video-analyzer-skill

Licencia

MIT — ver LICENSE.

---

中文说明

阅影（yueying）让 AI 看懂视频。 给 Claude Desktop、Claude Code、Cursor 等支持 MCP 的工具一个本地视频文件或视频链接（B站 / YouTube / 抖音 / 小红书 …），它就能拿到带时间戳的文字稿和关键帧九宫格：字幕优先，没有字幕就本地 faster-whisper 识别，全程离线，不上传、不要 API key。链接通过 yt-dlp 以 ≤720p 下载，处理完默认删除原视频。完整文档见上方英文部分。

安装

# 1. 装 uv（不需要先装 Python）
winget install astral-sh.uv          # Windows；macOS: brew install uv
# 2. 预热：安装、探测显卡、下载模型、跑 2 秒冒烟测试、打印配置
uvx yueying mcp --setup

不用 uv：pip install yueying（有 NVIDIA 显卡再加 pip install "yueying[cuda]"），然后 yueying mcp --setup 会打印 yueying-mcp 的绝对路径。Windows 也可以下载仓库后双击 install.cmd，它会建独立环境、装 Claude Code 技能、跑 --setup 并打印可粘贴的配置。

配置

Claude Desktop（%APPDATA%\Claude\claude_desktop_config.json，改完完全退出再打开；Windows 下 uvx 找不到就写绝对路径，如 C:\\Users\\<你>\\.local\\bin\\uvx.exe）、Cursor（~/.cursor/mcp.json）、Windsurf（~/.codeium/windsurf/mcp_config.json）都是同一段：

{ "mcpServers": { "yueying": { "command": "uvx", "args": ["yueying", "mcp"], "env": { "PYTHONUTF8": "1" } } } }

Claude Code 一行：

claude mcp add --transport stdio --scope user yueying --env PYTHONUTF8=1 -- uvx yueying mcp

Cline 在同一段里加 "type": "stdio"、"timeout": 1800，并把 get_transcript、search_transcript、get_frames、get_frame_at、list_videos 放进 autoApprove。VS Code 的 .vscode/mcp.json 根键是 servers 并加 "type": "stdio"。

六个工具

工具	用途
watch_video(video, mode, language, model, frame_interval_seconds, cookies_from_browser, output_dir, refresh, wait_seconds, max_chars)	看一个视频：本地绝对路径或链接。返回 DONE（概览 + 文字稿）、RUNNING（进度，用同一个 video 再调一次即可继续等）或 ERROR（英文提示）。结果按视频缓存，refresh=true 重做
get_transcript(video, start, end, format, max_chars)	按时间段读文字稿；format="srt" 导出字幕
search_transcript(video, query, context_seconds, limit)	找「哪里提到了 X」，给出时间、上下文、最近的关键帧号和九宫格号
get_frames(video, kind, start, count, max_width)	看画面：先看九宫格（grids），需要细节再看单帧（frames）；每次最多 3 张
get_frame_at(video, time, max_width)	看某一时刻：代码、PPT、图表、界面；本地文件还在就精确抽帧
list_videos(limit)	列出处理过的视频（video_id、标题、时长、文字来源、日期、大小、目录）和正在跑的任务

Claude Desktop / Cursor 里 wait_seconds 保持默认 45；Claude Code / Cline 配好 timeout 后可以给到 1500，一次调用就等到结果。第一次语音识别要下载模型（CPU 约 480 MB 的 small，显卡约 1.6 GB 的 large-v3-turbo），--setup 会提前下好。

输出目录与环境变量

结果在 ~/yueying_out/<名字>-<video_id>/（YUEYING_OUT_DIR 可改），每个视频一个文件夹：report.md、transcript.txt、transcript.srt、grid_01.jpg …、frames/、manifest.json。约每小时视频 25 MB；不会自动删，删文件夹即可。常用环境变量：YUEYING_OUT_DIR（输出根目录）、YUEYING_MODEL（默认 auto：有 NVIDIA 显卡用 large-v3-turbo，否则 small）、YUEYING_DEVICE（auto/cuda/cpu）、YUEYING_LANG（服务端 report.md 语言，默认 en，中文写 zh）、YUEYING_KEEP_SOURCE=1（保留下载的原视频）、YUEYING_JOB_TIMEOUT（单个视频上限秒数，默认 7200）、PYTHONUTF8=1（Windows 防乱码）。

B站 cookie

不登录 B站 只给 480p，看 PPT 和代码够用；高清或会员视频传 cookies_from_browser="chrome"（或 edge），Windows 下先关掉 Chrome，否则读不到 cookie 数据库。遇到 412 / -352 也是同样的处理。

国内镜像

下载模型慢或被墙：在服务器配置的 env 里加 "HF_ENDPOINT": "https://hf-mirror.com"。命令行版在 huggingface.co 连不上时会自动切到镜像。

命令行用法

yueying 视频.mp4
yueying "https://www.bilibili.com/video/BVxxxx"
yueying "https://www.youtube.com/watch?v=xxxx" --out ./notes/xxx
yueying 第1课.mp4 第2课.mp4 "https://www.bilibili.com/video/BVyyyy"   # 多个一起，各出各的文件夹 + index.md
yueying "https://www.bilibili.com/video/BVxxxx" --all                      # B站 分 P / 合集 全部处理
yueying --install-skill                                                    # 装 Claude Code 技能

默认输出 ./yueying_out/<视频名>/，日志和 report.md 默认中文（--ui-lang en 切英文）。常用参数：--lang zh 指定语言、--model small 换小模型（auto 自动选）、--device cpu、--interval 3 抽帧间隔、--frames 30 最多帧数、--scene 0.2 场景灵敏度、--no-dedupe 不去重、--no-asr 只要画面、--no-frames 只要文字、--force-asr 有字幕也识别、--cookies-from-browser chrome、--keep 保留原视频、--json 末尾打印一行 manifest。完整说明见上方英文表格。