screencast-desktop

Un plugin de Claude Code que permite a un agente manejar una aplicación de Windows y convertir esa sesión en un vídeo de demostración terminado, donde la cámara empieza a acercarse hacia cada clic medio segundo antes de que el clic ocurra.

• Controla el escritorio con visión en el bucle. Cada acción devuelve una captura de pantalla nueva en la misma respuesta, de modo que el agente trabaja mirar → actuar → mirar en lugar de escribir un guion a ciegas. Los controles se buscan por nombre mediante Windows UI Automation; las aplicaciones Electron que no exponen un árbol de controles recurren a capturas de pantalla y coordenadas (o a su DOM a través de CDP, cuando hay un puerto de depuración abierto).

• Graba una ventana, no una pantalla. La captura se realiza mediante Windows Graphics Capture, asociada a un identificador de ventana, de modo que el escritorio detrás de la aplicación nunca entra en el encuadre y no importa en qué monitor o GPU se encuentre la ventana.

• El vídeo se construye a partir de un registro de eventos, no de la grabación. Cada clic, cada cadena escrita y la trayectoria completa del cursor se registran con su marca temporal en el momento en que ocurren. Los movimientos de cámara se calculan a partir de ese registro.

• Acabado de nivel Screen Studio, generado: acercamientos y paneos de cámara suavizados, un cursor dibujado con una sombra suave, ondas de clic, desenfoque de movimiento, esquinas redondeadas sobre un fondo degradado, viñeta y grano, además de eliminación de silencios que comprime el tiempo de reflexión del propio agente.

• Narración que llega en el momento justo. Locución opcional de ElevenLabs, generada antes de la ejecución para que el clic caiga dentro de la frase que la describe.

• Una capa de montaje más completa, a un script de distancia. Tarjetas de título y de cierre, subtítulos y una pasada completa de diseño de sonido — pista de clics, barridos de cámara, impactos de aterrizaje, riser de cierre, cama musical con ducking, normalización de sonoridad — viven en cinematic.py, sfx.py y sfx_bank.py. Se controlan desde server/make_showcase.py en lugar de desde la herramienta desktop_render; consulte Limitaciones conocidas.

• Re-render gratuito. El renderizado nunca toca la aplicación: cambia el tope de zoom, la narración o los efectos y reconstruye la misma toma tantas veces como quieras.

Por qué es diferente

Todo grabador de pantalla que hace «auto zoom» — Screen Studio y sus imitadores de Windows — funciona igual: primero graba y luego retrocede a través de los hooks del ratón o del propio metraje para adivinar dónde estaban los momentos interesantes. Ese orden tiene una consecuencia inevitable que ninguna ingeniería puede evitar: el zoom no puede comenzar antes del clic, porque en el momento del clic el grabador acaba de enterarse de que se acerca un clic. Lo máximo que puede hacer es empezar a moverse en el clic y llegar poco después. Los editores humanos hacen lo contrario: guían al espectador, de modo que el ojo ya está sobre el botón cuando se pulsa.

Aquí el agente genera las acciones, de modo que las coordenadas y los tiempos se conocen antes de componer un solo fotograma. Se puede dar a la cámara un margen de entrada (LEAD_IN = 0.55 s en server/camera.py), de modo que cuando se pulsa el botón el plano ya ha llegado y se ha asentado. Ese mismo conocimiento anticipado aporta tres cosas más que una herramienta a posteriori no puede tener:

• Sin bombeo. Los clics consecutivos en la misma región se fusionan en un plano estable en lugar de que la cámara haga zoom de acercamiento y alejamiento en cada elemento de la lista.

• Narración que encaja. La locución se genera antes de la ejecución (voice.plan()), su duración real se mide con ffprobe, y las pausas del agente se ajustan a partir de esos números — de modo que el clic cae dentro de la frase que lo describe, sin ajustes manuales. Grabar primero y narrar después siempre termina con la voz diciendo «Hago clic en Guardar» un segundo después de que ya se haya hecho clic en Guardar.

• Un registro legible por máquina de lo ocurrido. desktop_describe_take lee una toma como un procedimiento numerado («3. [12.4s] click Multiply by») — un artefacto mejor que un montón de capturas de pantalla, y suficiente para escribir una skill reutilizable.

Dónde se sitúa entre los vecinos

La idea no es oscura — simplemente es difícil de alcanzar en Windows. Cuatro proyectos del lado del navegador que implementan la «edición desde el registro de acciones» aparecieron en dos semanas de marzo de 2026 (argo, testreel, pagecast, playwright-recast), porque Playwright te entrega el registro de forma gratuita. En Windows, el registro debe construirse junto con el controlador de entrada, y en esos mismos cinco meses no apareció nada: los grabadores no tienen agente y los agentes no producen fotogramas.

Related MCP server: windows-gui-mcp

Requisitos

Paquetes de Python

Extraídas de las importaciones de cada módulo en server/:

pip install mcp pillow opencv-python numpy windows-capture uiautomation

No se necesita ningún paquete para el escaneo de privacidad: lee la pantalla con el OCR que viene con Windows, controlado a través de PowerShell.

Instalación

1. Obtener el plugin

git clone https://github.com/JHamidun/screencast-desktop.git

2. Registrarlo en Claude Code

El repositorio es su propio marketplace (.claude-plugin/marketplace.json), así que apunta Claude Code al clon e instala desde allí:

/plugin marketplace add <path-to-clone>
/plugin install screencast-desktop

.mcp.json registra ambos servidores con rutas relativas a ${CLAUDE_PLUGIN_ROOT}, de modo que nada necesita una instalación global y el clon puede vivir en cualquier sitio.

3. Ejecutar la configuración

/screencast-desktop:setup

Eso ejecuta server/doctor.py, que comprueba las cosas que fallan en silencio:

• Compatibilidad con DPI — a un proceso que no se ha declarado compatible con DPI se le dice que la pantalla es 2560×1440 cuando en realidad es 3840×2160, y cada clic falla por el factor de escala.

• Distribución de monitores — las coordenadas se comparten entre todas las pantallas y se vuelven negativas en los monitores secundarios.

• ffmpeg y codificadores disponibles.

• Captura de ventana, de verdad — captura ~25 fotogramas y comprueba que no sean todos idénticos.

• Narración — si una clave está presente y si el id de voz configurado sigue existiendo en la cuenta (una voz eliminada, de lo contrario, falla con un 404 escueto).

Escribe machine.json con lo que ha encontrado.

4. Descargar el binario de UI Automation

El servidor windows-ui es un binario externo — sbroenne/mcp-windows (MIT). Está deliberadamente no incluido en este repositorio: pesa ~60 MB, es un proyecto de otra persona, y fijar una copia aquí solo serviría para distribuir una versión obsoleta. Descárgalo bajo demanda:

python server/fetch_ui_binary.py          # --force to re-download

El script obtiene la última versión publicada en GitHub, verifica el archivo contra el SHA256SUMS.txt publicado con ella, y se niega a instalar nada si hay una discrepancia. Se coloca en bin/, que es donde .mcp.json lo espera.

5. Confirmar que ambos servidores están activos

claude mcp list      # expect: screencast, windows-ui

Inicio rápido

Graba una demo de la Calculadora de Windows. El comando /screencast-desktop:record guía al agente a través de este proceso, pero esto es lo que hace realmente, con los nombres reales de las herramientas.

1 — Prepara la ventana. Ponla en un monitor secundario si lo hay, para que no se sitúe encima de tu trabajo:

desktop_monitors()
desktop_place_window(window="Calculator", monitor=1, fit=0.7)

Lee la respuesta. Las aplicaciones no están obligadas a adoptar el tamaño que se les pide — una ventana UWP a la que se pidieron 2380×1490 devolvió 3967×2426 y quedó fuera de la pantalla. desktop_place_window mide el resultado, lo corrige y dice sin rodeos si la ventana cabe.

2 — Comprueba si hay algo privado en el encuadre.

desktop_screenshot(window="Calculator")
desktop_privacy_check(window="Calculator")

La comprobación informa, no bloquea: aplica OCR al encuadre y marca números de tarjeta, claves de API, direcciones de correo electrónico, números de teléfono y nombres de personas. Activa No molestar antes de grabar.

3 — Ensaya. Recorre la ruta con las herramientas reales y confirma con las capturas de pantalla devueltas que estás pulsando lo que crees estar pulsando. Todavía no se está grabando nada:

ui_snapshot(windowHandle=…)          # windows-ui: controls by name — try this first
desktop_snapshot(window="Calculator")# or the built-in UIA walk, which returns e1, e2, … refs
desktop_click(ref="e7")

4 — Reinicia la aplicación. Un cuadro de búsqueda dejado abierto desde el ensayo acaba en la toma.

5 — Graba la toma real.

desktop_record_start(window="Calculator")
desktop_click(ref="e12")                 # every click from here is logged for the camera
desktop_type("128")
desktop_click(ref="e19")
desktop_record_stop()

desktop_record_stop informa de la duración, el número de fotogramas y cuántos clics entraron en el registro, y luego te indica el out_dir para renderizar.

6 — Renderiza y luego míralo.

desktop_render(out_dir="%USERPROFILE%/screencasts/take-143502", max_zoom=2.0)
desktop_render_status(out_dir="…")       # rendering runs in a child process

Abre el archivo y compruébalo con tus propios ojos: ¿ha llegado la cámara a donde debía?, ¿hay barras negras en algún borde?, ¿es visible el cursor? Una coordenada incorrecta produce un archivo técnicamente válido en el que la cámara no mira a nada. Si está desviado, vuelve a ejecutar desktop_render con otros ajustes: la aplicación no se vuelve a lanzar y la pantalla no se vuelve a grabar.

Referencia de herramientas

Servidor screencast — desktop_monitors, desktop_windows, desktop_screenshot, desktop_snapshot, desktop_dom, desktop_dom_launch, desktop_click, desktop_type, desktop_key, desktop_move_mouse, desktop_scroll, desktop_focus, desktop_launch, desktop_place_window, desktop_privacy_check, desktop_record_start, desktop_record_stop, desktop_render, desktop_render_status, desktop_describe_take.

desktop_click, desktop_type, desktop_key, desktop_scroll, desktop_focus y desktop_launch aceptan todos see="shot" (por defecto) o see="none" — el segundo ahorra contexto cuando ya sabes cómo se ve la pantalla.

Servidor windows-ui (subconjunto expuesto) — ui_snapshot, ui_find, ui_click, ui_type, ui_select, ui_read, ui_wait, window_management, app.

Cómo funciona

Lo mismo en texto, para quien lo lea en una terminal:

  AGENT                                                   server/
  ─────                                                   ───────
  desktop_click / desktop_type / …                        desktop_server.py
        │                                                 (MCP, FastMCP)
        ├──► real SendInput: cursor eased to the target,  driver.py
        │    clicked, keys sent                           ── moves + clicks
        │                                                    the real desktop
        │
        ├──► EVENT LOG  t, kind, x, y, label, dur         driver.py → events.json
        │    + the sampled cursor path (track)               ◄── the ground truth
        │
        └──► screenshot back to the agent in the same reply

  desktop_record_start                                    recorder_proc.py (child process)
        └──► Windows Graphics Capture, bound to the HWND  wgc.py
             ├─ frames arrive only when the picture       ── writer thread re-sends
             │  changes …                                    the last frame on a
             └─ … so a writer thread feeds ffmpeg at a       fixed clock
                constant rate, logging the true
                wall-clock time of every frame
                                                          → raw.mp4 + frame_times.json

  desktop_render                                          render_proc.py (child process)
        │
        ├─ 1. TIMELINE   collapse the dead air            timeline.py
        │      keep 1.1 s before and 1.5 s after every
        │      action, squeeze the gaps to 0.55 s
        │
        ├─ 2. CAMERA     event log → keyframes            camera.py
        │      lead-in 0.55 s BEFORE each click,
        │      nearby clicks merged into one shot,
        │      pan instead of pumping in and out
        │
        ├─ 3. COMPOSITOR one affine matrix per frame      composer.py
        │      recording on a gradient backdrop, rounded     + cinematic.py
        │      corners, drop shadow, drawn cursor, click     (vignette, grain;
        │      ripples, motion blur, breathing idle,          title cards and
        │      vignette, grain                                captions available)
        │                                                 → silent.mp4
        │
        └─ 4. SOUND      optional narration               voice.py
               ElevenLabs TTS mixed onto the cut          → demo.mp4

  make_showcase.py — the fuller montage, run as a script rather than a tool:
        the same four stages plus title/outro cards, captions, and the whole
        sound design pass (clicks, whooshes, impacts, riser, ducked music bed,
        loudness normalisation)                           sfx.py + sfx_bank.py

Dos decisiones de diseño explican la mayor parte de la estructura de archivos:

La captura y el renderizado se ejecutan en procesos hijos. Importar la librería de captura u OpenCV dentro del proceso del servidor MCP lo atasca, y un renderizado tarda minutos, algo que ninguna llamada de herramienta debería mantener abierto. recorder_proc.py y render_proc.py existen solo por esa razón. Se comunican mediante archivos (started.json, stop, render.log), y ambos se inician con stdin=DEVNULL — un hijo que hereda el stdin del servidor empieza a consumir las peticiones JSON-RPC destinadas al servidor.

Los fotogramas se emparejan por marca de tiempo, no por índice. Si la máquina se queda atrás, el fotograma fuente N no está en N/fps. frame_times.json contiene el tiempo de captura real de cada fotograma, y el compositor los busca a través de él — que es lo que mantiene la cámara sobre los clics cuando la máquina tartamudea.

Configuración

Renderizado

desktop_render(out_dir, name="demo.mp4", max_zoom=2.0, narration="") — narration toma una lista JSON de {"text": …, "at": seconds}.

Todo lo demás es una constante de módulo, que se edita in situ:

desktop_record_start(window, out_dir="", fps=30) usa por defecto ~/screencasts/take-HHMMSS.

Si no se indica max_zoom, camera.build() elige un límite por sí mismo para que al menos el 70 % de la altura de la ventana permanezca en el encuadre: una ventana alta y estrecha encajada en un fotograma 16:9 ya es pequeña, y forzar 2× allí recorta la parte que da sentido a la acción. (En la Calculadora cortó la pantalla que mostraba el resultado).

Narración

Establece ELEVENLABS_API_KEY en el entorno o en un archivo .env en la raíz del plugin (KEY=value, una por línea; el archivo está ignorado por git). Opcionalmente fija una voz con ELEVENLABS_VOICE_ID; si no se establece ninguna, se usa la primera voz de la cuenta. Modelo: eleven_multilingual_v2. Apunta SCREENCAST_ENV_FILE a otra ubicación si guardas tus claves en otro sitio.

voice.resolve_voice() comprueba los ids configurados contra el listado real de voces de la cuenta antes de usar una, porque una voz eliminada fallaría de otro modo con un 404 sin explicación.

Sin clave no se rompe nada. doctor.py lo informa como advertencia, no como error, y desktop_render produce un vídeo sin sonido — que es también lo que produce con clave cuando no se pasa el argumento narration.

La capa de diseño de sonido se degrada en lugar de morir sin clave: sfx_bank.build() necesita ElevenLabs para generar la paleta, pero sfx_bank.build_synthetic() sintetiza las mismas familias sin conexión con numpy (los archivos *_syn1.wav / *_syn2.wav), y sfx.click_samples() recurre a synth_click() cuando no encuentra activos de muestra. Así que una máquina sin conexión sigue teniendo clics, silbidos e impactos; solo pierde la voz.

Limitaciones conocidas

Lista honesta. Son reales, ciertas a día de hoy, y en su mayoría cosas con las que nos topamos durante el desarrollo. Lo que se planea hacer al respecto, en orden de prioridad y con las mediciones que respaldan cada elemento, está en ROADMAP.md.

• La herramienta desktop_render renderiza menos de lo que el código puede. Llama a composer.compose() sin intro, outro ni captions, y mezcla solo la narración: sin pista de clics, sin silbidos, sin cama musical. Todo lo demás está implementado y funciona, pero actualmente solo es accesible a través de server/make_showcase.py, que es un script con su propia ruta de toma y lista de tiempos fijadas en código. Conectar esos parámetros a través de la herramienta es la tarea abierta más evidente de este repositorio.

• Sin arrastre. No existe ninguna herramienta de arrastre ni de arrastrar y soltar. El ratón se pulsa y se suelta siempre en la misma posición, así que cualquier cosa que requiera un gesto de presionar-mover-soltar — deslizadores, reordenar, dibujar en un lienzo, redimensionar con el asidero — queda fuera de alcance.

• Las pulsaciones de teclas no se escriben en el registro de eventos. desktop_key envía la pulsación, pero no la registra, por lo que la cámara nunca reacciona a pasos solo de teclado y estos no aparecen en desktop_describe_take. Los clics y el texto tecleado (desktop_type) se registran; las pulsaciones individuales de teclas no.

• Las ventanas UWP deben abordarse por su ventana de marco. Windows Graphics Capture toma un identificador de ventana de nivel superior. Para una aplicación UWP/Store esa es la ApplicationFrameWindow visible — la CoreWindow interna no es un objetivo de captura utilizable. En la práctica: resuelve la aplicación por su título de ventana visible (que es lo que hacen las herramientas) y no intentes ir más allá.

• desktop_screenshot es un recorte de la pantalla, no una captura de ventana. Toma la región de la pantalla que ocupa la ventana. Cualquier cosa que se superponga a la ventana — otra ventana, un aviso de notificación, un tooltip — aparece en la captura. (La grabación no tiene este problema: WGC captura la propia ventana). Asegúrate de que la ventana objetivo esté encima antes de fiarte de una captura.

• Las aplicaciones Electron exponen casi nada a la Automatización de la Interfaz de Usuario. Medido en Windows 11: una aplicación Electron típica devuelve de 2 a 6 elementos con nombre — contenedores de ventana, no interfaces. Recurre a capturas de pantalla y coordenadas, o usa desktop_dom cuando haya un puerto de depuración disponible. desktop_dom_launch abre una segunda copia de la aplicación con un perfil separado, que no tiene la sesión iniciada.

• NVENC es prácticamente obligatorio. Tanto wgc.WindowRecorder como composer.compose() usan h264_nvenc por defecto. Las rutas con libx264 están implementadas y doctor.py detecta el codificador adecuado en machine.json, pero nada conecta esa elección automáticamente todavía. En una máquina sin NVENC tienes que pasar el codificador tú mismo.

• Archivos grandes. El grano de película se aplica por fotograma, lo que anula la compresión entre fotogramas: una demo corta pesa más que el mismo metraje sin grano. Establece grain_amount=0 si el tamaño importa más que el aspecto.

• Una toma tiene un límite de 15 minutos. recorder_proc.py se detiene solo, así que una grabación olvidada no puede ejecutarse para siempre.

• Solo Windows, y solo el escritorio interactivo. SendInput, la Automatización de la Interfaz de Usuario, WGC y el OCR de WinRT son todas APIs de Windows; nada de esto funciona en una sesión desatendida, en un servicio ni en una pantalla bloqueada.

• La ventana es una aplicación viva. El estado perdura entre tomas: una caja de búsqueda que quedó abierta de un ensayo convirtió una palabra tecleada en "githubgithub". Reinicia la aplicación antes de la toma definitiva.

• La comprobación de privacidad informa, no bloquea. La coincidencia es literal; un nombre en un menú no es una fuga, y el OCR pasa por alto cosas. Mira el fotograma tú mismo antes de publicar.

Créditos y licencias

• sbroenne/mcp-windows (MIT) — el servidor MCP windows-ui que hace la Automatización de la Interfaz de Usuario. No se incluye aquí; lo descarga bajo demanda server/fetch_ui_binary.py, verificado por suma de comprobación contra el SHA256SUMS.txt propio del lanzamiento.

• ffmpeg — codificación de la captura, la mezcla de audio y la medición de duración con ffprobe. Se invoca como binario externo; no se incluye. La licencia depende de la compilación que instales (LGPL o GPL).

• Banco de sonidos. Los archivos .wav en server/sfx_bank/ están generados, no muestreados: server/sfx_bank.py los construye una sola vez a partir de recetas de prompt mediante la API de generación de sonidos de ElevenLabs y los guarda en caché, y cada candidato se examina con mediciones (se rechaza un "clic" cuyo pico aparezca a los 200 ms por muy bien que suene). Una segunda familia de archivos — *_syn1.wav, *_syn2.wav — se sintetiza completamente sin conexión en sfx_bank.build_synthetic() con numpy, de modo que una máquina sin clave de API sigue teniendo diseño de sonido. Aquí no se redistribuye ninguna librería de muestras de terceros. Apunta SCREENCAST_SFX_DIR a tu propia carpeta de muestras y sfx.py preferirá esos clics y camas musicales al banco incluido; si no está configurado, usa server/sfx_bank/, y si no encuentra nada, sintetiza. En cualquier caso, no hay dependencia obligatoria.

• ElevenLabs — opcional, para la narración y para construir el banco de sonidos. Trae tu propia clave; el plugin no incluye ningún audio generado con la voz de nadie.

• Fuentes — los títulos y los subtítulos usan Segoe UI, que viene con Windows, con Arial como alternativa. No se redistribuye ningún archivo de fuentes.

• Model Context Protocol Python SDK (MIT) — el framework del servidor.

El código propio del plugin se publica bajo la Licencia MIT. Consulta LICENSE.

Contribuir

Las issues y las pull requests son bienvenidas. Algunas cosas que agilizan la revisión:

• Solo Windows. Prueba en un escritorio real; no hay CI que pueda hacer clic por ti.

• Ejecuta primero el doctor (python server/doctor.py) y pega su salida en un informe de error — la mayoría de los problemas aquí son ambientales (escalado de DPI, disposición de monitores, codificador faltante) y el doctor los nombra directamente.

• Si se rompió en silencio, dilo en un comentario. Este código está lleno de notas que explican por qué una línea es como es, porque casi todas ellas son un fallo que parecía un éxito: fotogramas idénticos que pasan por una grabación, una cámara que se desvía del borde, un registro de eventos vacío que produce un video sin zoom alguno. Mantener esas notas es deliberado.

• Los cambios en las constantes de cámara o de línea de tiempo necesitan un clip de antes/después. Son decisiones subjetivas sobre cómo se ve el resultado, y ninguna prueba puede resolverlas.