Communitygithub.com

lattifai/EdgeSpeak-Skills

Crea subtítulos ASS de karaoke con palabras resaltadas, opcionalmente bilingües con una segunda línea traducida, e incrústalos en videos locales usando una sola solicitud de transcripción EdgeSpeak con alineación forzada integrada a nivel de palabra. Úsalo cuando el usuario solicite subtítulos de karaoke, resaltado por palabra, un archivo ASS, subtítulos bilingües o de doble idioma, opciones de estilo de subtítulos o vistas previas, o un video con subtítulos fijos sin proporcionar una transcripción de referencia final.

¿Qué es EdgeSpeak-Skills?

Esta habilidad para agentes de IA (como Claude Code, Cursor, Codex) crea subtítulos ASS de karaoke con resaltado de palabras a partir de una única solicitud de transcripción de EdgeSpeak. Utiliza la alineación forzada local integrada de EdgeSpeak a nivel de palabra para generar archivos ASS con temporización precisa de palabras, lo que permite efectos de karaoke donde las palabras se resaltan sincronizadas con el audio. La habilidad admite subtítulos bilingües opcionales, con una segunda línea traducida, y puede incrustar los subtítulos de forma permanente en el video (hard sub) usando FFmpeg. Está diseñada para agentes que ejecutan scripts de Node.js sin dependencias externas, y maneja automáticamente la detección de idioma, la selección de fuentes, y la generación de vistas previas de estilo. Soporta plataformas macOS (Apple Silicon), Linux (x86_64) y Windows (x64) a través del CLI de EdgeSpeak, y requiere Node.js 18+, FFmpeg con libass, y EdgeSpeak CLI o aplicación de escritorio. La habilidad incluye lógica para elegir estilos de subtítulos (clásico, minimalista, con recuadro, alto contraste) basados en el contenido del video, y permite al usuario decidir mediante vistas previas de imágenes reales del video.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lattifai/EdgeSpeak-Skills/tree/HEAD/skills/edgespeak-karaoke

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

EdgeSpeak Karaoke

Crea subtítulos de karaoke a partir de una sola solicitud de transcripción de EdgeSpeak. Usa los scripts de Node.js integrados sin dependencias para la generación determinista de ASS, vistas previas en fotogramas reales y renderizado con FFmpeg.

Deja que el usuario elija el aspecto

Recopila la ruta del origen, la ubicación de salida y si el usuario quiere ASS, subtítulos fijos o ambos. El estilo es la única decisión que el usuario puede ver y con la que podría no estar de acuerdo, así que trátala como suya por defecto:

  • Explícito: respeta el preset nombrado o las sobrescrituras. Los presets disponibles son classic, minimal, boxed y high-contrast.
  • Automático: solo cuando el usuario realmente delega la decisión — "tú eliges", "lo que funcione", "hazlo rápido", "usa el predeterminado". Elige de la tabla siguiente y continúa sin bloquear.
  • Vista previa y luego preguntar — el valor predeterminado cuando el usuario no ha indicado preferencia de estilo. Renderiza cada preset en fotogramas reales del origen, muestra los PNG con la capacidad de visualización de imágenes del entorno, y formula una pregunta compacta. Una terminal puede listar rutas y descripciones, pero el texto ANSI no es una vista previa visual fiel.

El silencio no es delegación. Un usuario que nunca mencionó el estilo normalmente no ha visto las opciones, no ha decidido omitirlas. Preguntar cuesta un breve intercambio; adivinar mal cuesta volver a renderizar todo el video, y con subtítulos fijos ese es el camino costoso.

Para salida bilingüe, qué idioma va arriba es el mismo tipo de elección visible — intégrala en esa única pregunta en lugar de preguntar dos veces.

Nunca renderices vistas previas sin mostrarlas. --preview-media renderiza los cuatro presets en cada ejecución, por lo que en cuanto ese comando termina, la comparación completa ya existe en disco. Abrir un PNG, elegir en silencio y reportar solo el ganador oculta una compensación que el usuario tenía derecho a ver.

Para el modo automático — y para sembrar la recomendación que se ofrece junto con las vistas previas — inspecciona fotogramas representativos del origen y usa estos valores predeterminados:

MetrajePreset
Paisaje general o contenido mixtoclassic
Fondo limpio, mayormente oscurominimal
Fondo ocupado, brillante, diapositivas o grabación de pantallaboxed
Vertical/móvil o fondo consistentemente difícilhigh-contrast

Cuando la luminosidad varía en el origen — escenas oscuras y brillantes en el mismo video — ningún fotograma individual resuelve la elección. Renderiza vistas previas en dos marcas de tiempo contrastantes y compara ambas, porque un preset que funciona en un fotograma brillante puede volverse invisible en uno oscuro.

Las instrucciones de la solicitud actual tienen prioridad. Si están presentes, también lee las preferencias opcionales de .edgespeak-skills/edgespeak-karaoke/EXTEND.md, luego ~/.edgespeak-skills/edgespeak-karaoke/EXTEND.md; las preferencias del proyecto ganan sobre las del usuario. Las preferencias útiles incluyen preset, fuente, tamaño de fuente, colores ASS, margen, formato de salida y calidad.

Transcribir y alinear una vez

  1. Confirma que el origen existe e inspecciona su duración, dimensiones y contenedor con ffprobe.

  2. Llama a edgespeak_transcribe_file una vez:

    {
      "path": "/ruta/absoluta/video-origen",
      "timestamps": "word",
      "start_margin": 0,
      "end_margin": 0
    }
    

    Añade min_chars / max_chars solo cuando el usuario solicite longitudes de subtítulos diferentes. Añade model solo cuando el usuario nombre uno. Si la localidad importa, inspecciona edgespeak_list_models y no elijas un modelo remoto sin consentimiento.

  3. No llames a edgespeak_align después de una transcripción exitosa con marcas de tiempo por palabra. Esta solicitud ya ejecuta la ruta de alineación forzada local integrada de EdgeSpeak y devuelve segments[].words[].

  4. Para una respuesta MCP larga, usa artifact_json_path. Para una respuesta en línea, guarda el objeto result como JSON. El conversor acepta JSON de transcripción directa o un contenedor con result.

  5. Exige temporización de palabra no vacía en cada segmento con tiempo. Nunca inventes temporización de palabras ni recurras silenciosamente a la temporización de segmentos.

Usa edgespeak_align solo cuando el usuario haya proporcionado una transcripción final externa o haya editado sustancialmente el texto de ASR. La alineación debe usar la secuencia de palabras final; nunca mantengas marcas de tiempo obsoletas después de ediciones.

Requisitos

  • Node.js 18 o superior para los scripts incluidos.
  • FFmpeg compilado con libass, además de ffprobe — un ejecutable separado que también debe estar en PATH. Cada vista previa y cada incrustación pasa por el filtro ass, por lo que un FFmpeg sin libass falla con No such filter: 'ass' sin importar qué preset se seleccione. La incrustación a MP4/MOV/MKV/TS además necesita libx264; WebM necesita libvpx y libopus. Homebrew y los paquetes principales de las distribuciones incluyen todo esto.
  • edgespeak-cli (o la aplicación EdgeSpeak) para la transcripción, que se ejecuta en macOS Apple Silicon, Linux x86_64 y Windows x64. En Windows, instala la aplicación de escritorio EdgeSpeak, que incluye el CLI. En macOS y Linux, usa curl -fsSL https://edgespeak.com/install.sh | sh (autónomo, no necesita la aplicación de escritorio; en Linux el instalador detecta automáticamente las GPU NVIDIA e instala un entorno compatible con CUDA). El minCliVersion del frontmatter es el CLI más antiguo para el que está escrita esta habilidad — si edgespeak-cli --version es más antiguo, o falta una bandera documentada en --help, ejecuta edgespeak-cli update.

Cuando una ejecución falla por una dependencia faltante, informa qué verificación falló en lugar de reintentar:

node --version                       # v18+
ffprobe -version                     # debe existir junto a ffmpeg
ffmpeg -filters   | grep -w ass      # el renderizador ASS (libass)
ffmpeg -encoders  | grep -w libx264  # salida H.264

Generar ASS y vistas previas

Genera el preset seleccionado:

node <directorio-habilidad>/scripts/karaoke-ass.mjs /ruta/a/transcripcion.json \
  -o /salida/video.karaoke.ass \
  --style classic \
  --title "Título del video"

Para presentar la elección, renderiza cada preset en una señal activa del video real. Este es el camino predeterminado, no un caso especial — y cada PNG que produce está destinado a mostrarse:

node <directorio-habilidad>/scripts/karaoke-ass.mjs /ruta/a/transcripcion.json \
  -o /salida/video.karaoke.ass \
  --style classic \
  --preview-media /ruta/a/video-origen \
  --preview-dir /salida/video.karaoke-previews

Usa --preview-at <segundos> cuando otro fotograma sea más representativo, y ejecútalo dos veces con diferentes marcas de tiempo cuando el origen mezcle escenas brillantes y oscuras. Lista los presets con --list-styles. Ajusta con --font, --font-size, --margin-v, --primary, --secondary, --outline y --back; los colores ASS usan &HAABBGGRR. El script preserva los límites de segmento de EdgeSpeak y solo asigna duraciones/espacios alineados a las etiquetas \kf / \k.

El espacio entre palabras proviene del text de la propia señal, no de un espacio por palabra. La alineación forzada adjunta la puntuación a la palabra que sigue, por lo que cada entrada de words[] es una subcadena de text y sus posiciones solo avanzan — el generador recorre text una vez y reutiliza lo que realmente hay entre dos palabras. Eso es lo que mantiene high-performance con guión (la alineación lo divide en high y performance, y el guión no pertenece a ninguna) y lo que mantiene el CJK sin espacios en lugar de renderizar 本地转录 como 本 地 转 录. Si no se puede encontrar una palabra en text, el generador recurre a espacios individuales en lugar de adivinar.

Karaoke bilingüe

Cuando la transcripción lleva una translation en cada segmento — lo que escribe edgespeak-translate — el generador emite dos líneas por señal y no necesita ninguna bandera adicional:

node <directorio-habilidad>/scripts/karaoke-ass.mjs /ruta/a/transcripcion.zh.json \
  -o /salida/video.karaoke.ass --style boxed

Ambas líneas viven en un evento de Diálogo separado por \N, por lo que ASS las apila como un solo bloque desde el margen compartido. Dos eventos separados se anclarían cada uno a ese margen y se superpondrían.

  • --layout translation-top (predeterminado) coloca la traducción arriba del origen; source-top lo invierte, para espectadores que leen junto con el idioma de origen. La línea superior se renderiza con el tamaño del preset y la inferior al 72%, para que el ojo se fije en el idioma principal de cualquier forma.
  • --layout source-only ignora las traducciones y produce el archivo de un solo idioma.
  • Solo la línea de origen tiene barrido. Las temporizaciones de palabra describen el audio de origen, por lo que la traducción no recibe etiquetas \k — mantiene un relleno plano durante toda la señal. Distribuir la duración de la señal entre los caracteres de la traducción sería una temporización inventada; no la añadas. Para temporización real de palabras en el idioma de destino, sintetiza con edgespeak-broadcast y alinea ese audio.

La fuente no es opcional — en ninguna de las dos líneas

libass no sustituye fuentes por glifo como lo hace un navegador. El texto CJK en un estilo de fuente latina se renderiza como cuadros en blanco — silenciosamente, durante toda la incrustación. Cada preset trae una fuente latina, por lo que el generador elige según el script en lugar de heredar la del preset. Esto se aplica también a la línea de origen, no solo a la traducción: una transcripción en chino sin --font de lo contrario se incrustaría como una fila de cuadros.

  • El script se detecta a partir del texto de la propia línea y se empareja mediante fc-match :lang=<etiqueta>, tomando un alias de familia ASCII único (una lista de alias rompería la fila de estilo ASS delimitada por comas).
  • --font <nombre> (origen) y --translation-font <nombre> (traducción) lo sobrescriben, y se rechazan cuando fc-list dice que esa fuente no cubre el idioma detectado. No evites el error eligiendo otra fuente latina — verifica qué cubre el script con fc-list :lang=zh-cn family.
  • El texto latino mantiene la fuente del preset sin cambios; el intercambio solo ocurre cuando el preset no cubriría el script.
  • Sin fontconfig, la selección automática falla ruidosamente; pasa la fuente explícitamente. La ejecución informa source_font_verified: false / translation_font_verified: false cuando no se pudo verificar la cobertura, así que informa esa advertencia en lugar de afirmar que la fuente está bien.
  • La ejecución informa source_font / source_script siempre que el origen no sea latino.

Una transcripción parcialmente traducida se rechaza directamente — significa que el paso de traducción se detuvo temprano, y emitir señales solo de origen para el resto pasaría un archivo incompleto como terminado.

Incrustar subtítulos fijos

Cuando el origen tiene video y el usuario quiere subtítulos fijos:

node <directorio-habilidad>/scripts/render-hardsub.mjs \
  /ruta/a/video-origen \
  /salida/video.karaoke.ass

El --format source predeterminado preserva el contenedor de origen cuando es práctico:

  • MP4/M4V/MOV -> misma extensión con H.264/AAC.
  • MKV -> MKV con H.264 y audio copiado.
  • WebM -> WebM con VP9/Opus.
  • TS/M2TS -> misma extensión con H.264/AAC.
  • Extensiones de origen no soportadas/ambiguas -> recurre a MKV, informado como container_fallback: true.

Los subtítulos fijos siempre requieren recodificación de video; preservar el contenedor no significa copiar el códec de video de origen. Usa --format mp4|mov|mkv|webm o un -o explícito solo cuando el usuario solicite un formato de entrega diferente. Usa --overwrite solo con autorización.

Igualar la tasa de bits de origen

Recodificar a una calidad fija ignora la tasa de bits del origen, y la diferencia puede ser grande: incrustar CRF 21 en un archivo AV1 magro de 1.5 Mbps produce una copia H.264 de 4.2 Mbps — 2.8 veces la tasa de bits del origen, casi 3 veces el tamaño del archivo, sin ganancia visible. Por lo tanto, el script analiza el origen y deriva un límite -maxrate / -bufsize de su tasa de bits, escalado por cuánto menos eficiente es el códec de salida (H.264 necesita aproximadamente 1.6 veces la tasa de bits de AV1 para una calidad comparable). La calidad aún proviene de CRF; el límite solo evita que supere el origen.

Esto es automático para objetivos x264. VP9/WebM se deja intacto porque el perfil .webm fija -b:v 0 para el modo de calidad constante. El informe incluye source_video_bitrate, video_bitrate y la decisión bitrate_cap — compara los dos primeros al informar el resultado.

Sobrescribe solo cuando el usuario solicita una tasa de bits o nivel de calidad específicos:

  • --crf <n> establece el objetivo de calidad (menor es mejor, 21 predeterminado para H.264).
  • --maxrate <tasa> reemplaza el límite derivado, p. ej. --maxrate 4M.
  • --maxrate none desactiva el límite por completo y restaura el comportamiento CRF simple.

La tasa de bits también es la palanca para el tamaño del archivo. Cuando un usuario objeta al tamaño de salida, cita la tasa de bits del origen junto con la tasa de bits de salida antes de proponer un cambio, y recuerda que el metraje plano ilustrado o grabado de pantalla se comprime mucho más que la acción en vivo — el texto de los subtítulos en sí se mantiene nítido incluso a CRF 28, por lo que nunca es la restricción.

Recurso a CLI

Recurre a edgespeak-cli siempre que MCP no pueda hacer el trabajo — incluso cuando el servidor MCP en sí está activo pero sus herramientas fallan. El caso más común: la aplicación de escritorio no se está ejecutando, por lo que cada herramienta MCP de EdgeSpeak devuelve runtime_error: could not reach gateway. Eso no es una instalación rota ni algo para reintentar; el servidor MCP de larga duración deliberadamente nunca inicia un motor propio (un servidor residente que mantenga el motor chocaría con la aplicación que el usuario abra después). El CLI no tiene esa restricción — inicia el motor en el dispositivo él mismo. Así que trata could not reach gateway de cualquier herramienta MCP de EdgeSpeak como "usa el CLI ahora", no como un fallo que informar.

Si no se encuentra el comando edgespeak-cli, instala la aplicación de escritorio EdgeSpeak en Windows x64, o usa curl -fsSL https://edgespeak.com/install.sh | sh en macOS Apple Silicon y Linux x86_64 (autónomo, no necesita la aplicación de escritorio; CUDA se detecta automáticamente en Linux).

edgespeak-cli transcribe /ruta/a/video-origen -o /salida/transcripcion.json \
  --start-margin 0 --end-margin 0

El JSON de transcripción del CLI ya contiene segments[].words[]. No ejecutes edgespeak-cli align en texto que el mismo comando transcribe acaba de producir. A diferencia de los scripts incluidos (que se niegan a reemplazar salidas existentes sin --overwrite), edgespeak-cli -o sobrescribe un archivo existente silenciosamente — si la ruta de la transcripción ya existe, confirma con el usuario antes de sobrescribir o elige una nueva ruta.

Validación y reporte

  • Dale a MCP y FFmpeg presupuestos de tiempo realistas; no interrumpas el procesamiento silencioso saludable.
  • Mantén start...

Skills relacionados