hadimoti/joy-media-windows-mcp

Controlando JOY Media con Windows-MCP

Esta habilidad es un método, aprendido en compilaciones de JOY Media 1.1.0 (Electron 44.3.0, Windows 11). Indica a un agente cómo ejecutar la aplicación de escritorio sin tocar la instalación real ni los datos del usuario, navegar por el editor con las herramientas de Windows-MCP y evaluar una exportación mediante hechos, no por apariencias.

Herramientas utilizadas: Snapshot, Screenshot, Click, Type, App, Wait (Windows-MCP), además de PowerShell para lanzar, comprobaciones de archivos y ffmpeg/ffprobe.

0. Reglas básicas (no omitir)

• Preguntar al propietario primero, cada ejecución. Lanzar la aplicación, importar y exportar requieren que el propietario esté frente al PC y dé un "adelante" claro para esa ejecución. Una ejecución a la vez. Nunca lanzar contra el perfil real del usuario.
• Nunca tocar la aplicación instalada (su carpeta, sus scripts de instalador, su desinstalador). Ejecutar una copia desempaquetada separada (sección 1).
• Aislar datos: pasar siempre un nuevo --user-data-dir. Para reutilizar un proyecto existente, cerrar la aplicación, luego robocopy /E el perfil antiguo a una nueva carpeta (sin /MIR, sin purgar) y lanzar sobre la copia.
• La clave de registro joy:// (HKCU\Software\Classes\joy) no debe cambiar. Exportarla a un nuevo archivo con reg export antes del lanzamiento, después del lanzamiento y después de cerrar, y comparar SHA-256. Si difiere, detenerse y notificar al propietario; restaurar solo bajo su indicación.
• No eliminar nada durante las pruebas (las copias, perfiles, exportaciones son evidencia). Chromium puede limpiar sus propios archivos temporales dentro del nuevo perfil de prueba; eso está bien.
• Detenerse ante evidencia de fallo (salida del proceso GPU, eventos de Error de Aplicación, reinicios de controlador): conservar todo, no reejecutar sobre ello, notificar al propietario.
• Nunca escribir secretos dentro de la aplicación ni poner tokens en notas.

1. Obtener una copia segura de la aplicación para ejecutar

Construir o desempaquetar el commit deseado en una ruta corta (menos de 260 caracteres), por ejemplo C:\jg\app-<sha>:

1. git archive <sha> a un tar, extraer a C:\jg\<nombre>.
2. pnpm install --offline --frozen-lockfile (necesita una caché pnpm activa).
3. Copiar la carpeta dist de Electron y path.txt desde la copia existente en node_modules\.pnpm\electron@<ver>\node_modules\electron (las instalaciones sin conexión no descargan Electron). Verificar el SHA-256 de electron.exe.
4. pnpm build, luego pnpm --filter @joy-media/desktop package:unpacked.
5. robocopy apps\desktop\dist\joy-media-unpacked C:\jg\app-<sha> /E.

Una copia desempaquetada se ejecuta con isPackaged = false, por lo que no registra el protocolo joy://. Verificar la clave de todas formas.

2. Lanzarla (PowerShell)

$env:NODE_ENV = 'production'
$app = 'C:\jg\app-<sha>'
Start-Process -FilePath '<ruta a>\electron.exe' `
  -ArgumentList @($app, '--user-data-dir=C:\jgp\<nuevo-perfil>', '--enable-logging=stderr') `
  -WorkingDirectory $app `
  -RedirectStandardOutput 'C:\jgp\run\stdout.log' -RedirectStandardError 'C:\jgp\run\stderr.log' -PassThru

--enable-logging=stderr pone las líneas console.* del renderizador en el archivo de stderr (útil para diagnósticos temporales). Verificar que ninguna línea de comando de proceso contenga --joy-media-gpu-encode-fallback (eso sería un reinicio de respaldo, no un lanzamiento predeterminado). El título de la ventana es JOY Studio. En un perfil nuevo, la aplicación abre la página de Proyectos; en un perfil copiado, restaura el último proyecto.

3. Controlar la ventana con Windows-MCP

Escala: las capturas de pantalla son aproximadamente 2,56 veces más pequeñas que la pantalla real. Hacer clic siempre en las coordenadas reales de Snapshot, nunca en píxeles de captura de pantalla. Tomar una Screenshot pequeña (scale 0,4) después de cada cambio de página.

Orden: ejecutar las acciones de ventana una a la vez. Un lote enviado justo después de una exportación una vez hizo que los clics y la escritura cayeran en el proyecto incorrecto. App switch "JOY Studio" a veces falla con "Invalid window handle"; si la ventana ya está al frente, continuar.

Las coordenadas a continuación son de una pantalla de 4920x2160 con la ventana de JOY en su tamaño y posición predeterminados. Son un mapa inicial, no una promesa: tomar un Snapshot y usar la lista de elementos cuando algo se vea diferente.

Acción	Dónde (coordenadas reales)
Menú Archivo	(910, 288)
Archivo > Biblioteca de Proyectos	(1077, 358)
Botón Nuevo proyecto	(3023, 311), luego hacer clic en el campo de nombre (1165, 727), Type el nombre con press_enter
Primera tarjeta de proyecto	(1680, 873)
Línea de tiempo "Importar medios" (línea de tiempo vacía)	(2199, 1312)
Diálogo de abrir archivo: cuadro de nombre / Abrir	(1587, 1208) / (2268, 1264)
Exportar MP4	(2672, 288)
Seleccionar el clip, verificar Escala	hacer clic en la barra del clip (1762, 1349); el inspector muestra Escala X/Y
Cerrar la ventana de la aplicación	(3143, 288)
Diálogo Guardar: cuadro de nombre / Guardar	aproximadamente (1717, 1058) / (2283, 1266)

Receta para un caso: Biblioteca de Proyectos > Nuevo proyecto > nombre > Importar medios > escribir la ruta completa del archivo > Abrir (el clip cae en la línea de tiempo) > verificar la vista previa > Exportar MP4 > esperar > guardar el diálogo > verificar.

El diálogo Guardar. La exportación termina en un diálogo Guardar normal de Windows (carpeta predeterminada Descargas, un nombre sugerido sin extensión). El archivo llega al Escritorio solo después de que alguien lo guarda, por lo que un retraso entre "trabajador terminado" y "archivo en el Escritorio" es simplemente ese diálogo esperando. Tomar una captura de pantalla cuando el trabajador debería haber terminado; o el propietario guarda, o (con su aprobación) escribir la ruta de destino completa ...\Desktop\<nombre-sugerido>.mp4 en el cuadro de nombre y hacer clic en Guardar. Los tiempos de trabajo en la base de datos de la aplicación no se ven afectados por la espera.

4. Antes, durante y después de una ejecución

Antes: reg export la clave joy:// y calcular su hash; listar la carpeta del perfil real del usuario y cualquier carpeta de evidencia (scripts/list-tree.ps1) para poder demostrar que nada cambió.

Durante (exportaciones largas): iniciar scripts/sampler.ps1 -Pattern '*<perfil>*' -Out <csv> -Stop <archivo-stop> en segundo plano. Registra, una vez por segundo, el conjunto de trabajo, los bytes privados, los segundos de CPU, las sesiones NVENC y el uso de GPU por proceso Electron. Crear el archivo stop para finalizarlo.

Después: cerrar la aplicación (el botón Cerrar ventana), confirmar que no queda ningún proceso electron, exportar la clave nuevamente, listar las carpetas nuevamente y comparar, verificar que no haya restos *.upload en el perfil, y buscar eventos de Error de Aplicación/WER y Display/nvlddmkm (ignorar ruido no relacionado como Docker).

5. Evaluar la exportación mediante hechos

• ffprobe -show_streams: códec, tamaño, fotogramas, duración, etiquetas de color (color_space, color_primaries, color_transfer, color_range).
• La decodificación completa debe ser limpia: ffmpeg -v error -i out.mp4 -f null - y código de salida 0.
• Hash del archivo (Get-FileHash); diseños idénticos de diferentes compilaciones deberían dar hashes idénticos cuando la ruta de código es la misma.
• Tiempos de fase desde la base de datos de la propia aplicación (una copia de joy-media.sqlite3 más sus -wal/-shm, abierta en solo lectura): scripts/export-times.py <copia> imprime, por exportación, la fase del navegador (marca de tiempo del clic hasta el original preparado), los bytes preparados y el tiempo del trabajador. La marca de tiempo del clic es el número de 13 dígitos en el nombre del archivo.
• Precisión del color: construir fixtures con scripts/fxgen.py <carpeta> (parches de color plano con valores sRGB conocidos más un contador de fotogramas binario; BT.709, BT.601, SD sin etiquetar, rango completo, rotado, VFR, 10 bits, HEVC, VP9, AV1, entrelazado, un par de transición y un par de tasa de audio), verificarlos con scripts/fxcheck.py <carpeta>, luego puntuar una exportación con JOY_FX_DIR=<carpeta> python -I scripts/fxplace.py <exportación.mp4> <nombre-archivo-fixture> [fotograma]. Encuentra dónde cayó el clip (clips más pequeños que el lienzo se colocan 1:1 en la esquina superior izquierda, sin escalar) e imprime la desviación máxima/promedio bajo cuatro lecturas de matriz/rango; la lectura correcta debe estar dentro de aproximadamente 3 niveles.
• Audio: tono a través de la tasa de cruce por cero de astats, nivel a través de RMS; las fuentes mono se convierten a estéreo (aproximadamente 3 dB más bajo por canal).

6. Comportamiento conocido que vale la pena recordar (compilaciones de JOY Media 1.1.0)

• Ejecutar cada prueba de color en una sesión nueva de la aplicación. En la máquina probada (RTX 5070 Ti, Electron 44.3.0) la primera exportación después del lanzamiento se codifica como BT.709 (etiqueta bt709); las exportaciones posteriores en la misma sesión se codifican como BT.601 (etiqueta smpte170m), salen más grandes y más lentas en un diseño largo, y tienen bytes diferentes. Una compilación de diagnóstico mostró que el fotograma del lienzo de captura es RGBA (respaldado por GPU) la primera vez y BGRA (respaldado por CPU) después; la aplicación no establece ningún espacio de color por sí misma. Convertir a NV12 BT.709 dentro de la aplicación hizo que todas las exportaciones fueran idénticas.
• El video SD sin etiquetar se lee como BT.709 (los colores se desplazan hasta aproximadamente 20 niveles).
• Una fuente sin pista de audio exporta una pista AAC estéreo silenciosa.
• Comparar compilaciones solo en igualdad de condiciones: mismo diseño, misma posición en la sesión (primera exportación vs primera exportación), ventana al frente y enfocada (una ventana desenfocada puede ser aproximadamente un 30 % más lenta), una copia del mismo perfil.
• Otros agentes o ventanas de chat en el mismo escritorio pueden robar el foco: tomar una captura de pantalla antes de hacer clic.
• El primer clic en una ventana puede solo enfocarla.

7. Informar de la siguiente manera

Indicar qué se ejecutó (compilación, copia de perfil, diseño), los números (tiempos de fase, pico de memoria, tamaños, etiquetas), las comprobaciones que pasaron (clave joy:// sin cambios, diferencias de carpetas vacías, decodificación limpia), qué no se verificó, y la única decisión que se necesita del propietario. Decir "una ejecución por compilación" cuando eso es todo lo que se tiene.