Communitygithub.com

EdgeSpeak Karaoke

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

¿Qué es EdgeSpeak Karaoke?

EdgeSpeak Karaoke es una habilidad de agente de IA capaz de generar subtítulos estilo karaoke con resaltado de palabras a partir de una única solicitud de transcripción de EdgeSpeak, que incluye alineación forzada a nivel de palabra. La habilidad produce archivos ASS (Advanced SubStation Alpha) que permiten el resaltado sincronizado de palabras, compatible con la mayoría de los reproductores de video y herramientas de edición. Es especialmente útil para creadores de contenido, educadores y entusiastas del aprendizaje de idiomas que desean subtítulos precisos y llamativos sin transcripciones externas. Además, soporta subtítulos bilingües con una segunda línea traducida, lo que facilita la comparación visual de idiomas. La habilidad se integra con las plataformas EdgeSpeak (CLI y escritorio) en macOS Apple Silicon, Linux x86_64 y Windows x64, y requiere Node.js 18+ y FFmpeg con libass. El flujo de trabajo incluye la transcripción y alineación en un solo paso, la generación de archivos ASS con múltiples estilos predefinidos y la creación de vistas previas de estilo en cuadros reales del video. Para subtítulos quemados, utiliza FFmpeg para incrustar los subtítulos directamente en el video, manteniendo la calidad de origen al ajustar la tasa de bits. La habilidad maneja errores de alineación de manera explícita y ofrece múltiples modos de selección de estilo (explícito, automático o con vista previa).

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

Preguntar en tu IA favorita

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

Documentación

¿Qué hace EdgeSpeak Karaoke?

Crea subtítulos de karaoke a partir de una única solicitud de transcripción de EdgeSpeak. Utiliza los scripts de Node.js sin dependencias incluidos para la generación determinista de ASS, vistas previas de estilo en cuadros reales y renderizado con FFmpeg.

Deja que el usuario elija el aspecto

Recopila la ruta de origen, la ubicación de salida y si el usuario quiere ASS, subtítulos quemados 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 anulaciones. Los presets disponibles son classic, minimal, boxed y high-contrast.
  • Automático: solo cuando el usuario realmente delega la decisión — "elige tú", "lo que sea", "hazlo rápido", "usa el predeterminado". Elige de la tabla a continuación y continúa sin bloquear.
  • Vista previa y luego preguntar: el predeterminado siempre que el usuario no haya indicado preferencia de estilo. Renderiza cada preset en cuadros reales del origen, muestra los PNG con la capacidad de visualización de imágenes del runtime y haz 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 generalmente no ha visto las opciones, en lugar de haber decidido omitirlas. Preguntar cuesta un breve intercambio; adivinar mal cuesta un re-renderizado de todo el video, y con subtítulos quemados 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 el momento en que ese comando se completa, 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 modo automático — y para sembrar la recomendación ofrecida junto con las vistas previas — inspecciona cuadros de origen representativos 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 el brillo varía en el origen — escenas oscuras y brillantes en el mismo video — ningún cuadro individual resuelve la elección. Renderiza vistas previas en dos marcas de tiempo contrastantes y compara ambas, porque un preset que gana en un cuadro brillante puede volverse invisible en uno oscuro.

Las instrucciones de la solicitud actual tienen prioridad. Si está presente, 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.

Transcribe y alinea 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
    }
    

    Agrega min_chars / max_chars solo cuando el usuario solicite longitudes de subtítulos diferentes. Agrega 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 de palabra. Esta solicitud ya ejecuta la ruta de alineación forzada local en línea 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 convertidor acepta tanto JSON de transcripción directo como un envoltorio con result.

  5. Requiere marcas de tiempo de palabra no vacías en cada segmento temporizado. Nunca inventes marcas de tiempo de palabra ni recurras silenciosamente a marcas de tiempo de segmento.

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

Una alineación que no puede colocar el texto es un error, no un resultado vacío: edgespeak_align devuelve isError: true con JSON {"code": "alignment_failed" | "alignment_search_budget_exceeded", ..., "alignment": {...}} y sin palabras (el CLI sale con código no cero con el mismo código y objeto en la línea de stderr que comienza con error: alignment_failed: o error: alignment_search_budget_exceeded:). Decide solo desde el objeto alignment:

  • alignment.retry_recommended: true → llama a edgespeak_align una vez más con "search_effort": "extended" (CLI: --search-effort extended). Busca más ampliamente, se ejecuta más lento y usa memoria extra; cita alignment.estimated_extra_bytes cuando se lo digas al usuario.
  • De lo contrario, o en alignment_search_budget_exceeded, no reintentes la misma llamada. Verifica que la transcripción coincida con este medio, o alinea un clip más corto. Consulta edgespeak-align para la lista completa de códigos y campos.

Nunca construyas señales de karaoke a partir de una alineación fallida: sin palabras espaciadas uniformemente, sin recurso a marcas de tiempo de segmento, sin marcas de tiempo heredadas de la transcripción previa a la edición.

Requisitos

  • Node.js 18 o más reciente para los scripts incluidos.
  • FFmpeg compilado con libass, más ffprobe — un ejecutable separado que también debe estar en PATH. Cada vista previa y cada quema pasa a través del filtro ass, por lo que un FFmpeg sin libass falla con No such filter: 'ass' sin importar qué preset se seleccione. Quemar a MP4/MOV/MKV/TS adicionalmente necesita libx264; WebM necesita libvpx y libopus. Homebrew y los paquetes de las principales distribuciones incluyen todos estos.
  • edgespeak-cli (o la aplicación EdgeSpeak) para 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, dirige al usuario al instalador independiente en https://edgespeak.com/docs/cli#install (no se necesita aplicación de escritorio; en Linux detecta automáticamente GPU NVIDIA e instala un runtime con CUDA). El usuario ejecuta el instalador; no lo ejecutes tú mismo. 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, reporta qué verificación falló en lugar de reintentar:

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

Genera ASS y vistas previas

Genera el preset seleccionado:

bash node /scripts/karaoke-ass.mjs /ruta/a/transcripcion.json
-o /salida/origen.karaoke.ass
--style classic
--title "Título del origen"

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

bash node /scripts/karaoke-ass.mjs /ruta/a/transcripcion.json
-o /salida/origen.karaoke.ass
--style classic
--preview-media /ruta/a/video-origen
--preview-dir /salida/origen.karaoke-previews

Usa --preview-at <segundos> cuando otro cuadro sea más representativo, y ejecútalo dos veces con marcas de tiempo diferentes cuando el origen mezcle escenas brillantes y oscuras. Lista los presets con --list-styles. Ajusta fino 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 mapea duraciones/brechas alineadas a etiquetas \kf / \k.

El espaciado entre palabras proviene del text de la 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 words[] es una subcadena de text y sus posiciones solo avanzan — el generador recorre text una vez y reutiliza lo que realmente está entre dos palabras. Eso mantiene high-performance con guión (la alineación lo divide en high y performance, y el guión no pertenece a ninguna) y mantiene el CJK sin espacios en lugar de renderizar 本地转录 como 本 地 转 录. Si una palabra no se encuentra en text, el generador recurre a espacios simples en lugar de adivinar.

Karaoke bilingüe

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

bash node /scripts/karaoke-ass.mjs /ruta/a/transcripcion.zh.json
-o /salida/origen.karaoke.ass --style boxed

Ambas líneas viven en un evento Dialogue separadas 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 encima del origen; source-top lo invierte, para espectadores que leen en el idioma de origen. La línea superior se renderiza al tamaño del preset y la inferior al 72%, por lo que la vista se centra en el idioma principal de cualquier manera.
  • --layout source-only ignora las traducciones y produce el archivo de un solo idioma.
  • Solo la línea de origen barre. Las marcas de tiempo de palabra describen el audio de origen, por lo que la traducción no recibe etiquetas \k — mantiene un relleno plano para toda la señal. Distribuir la duración de la señal entre los caracteres de la traducción sería una marca de tiempo inventada; no la agregues. Para marcas de tiempo de palabra real en el idioma de destino, vocaliza la traducción con una habilidad de síntesis de voz (si está instalada) 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 una fuente de estilo latino se renderiza como cajas en blanco — silenciosamente, a lo largo de toda una quema. Cada preset incluye una fuente latina, por lo que el generador elige por escritura en lugar de heredar la del preset. Esto aplica también a la línea de origen, no solo a la traducción: una transcripción en chino sin --font se quemaría como una fila de cajas.

  • La escritura se detecta del texto de la línea y se empareja a través de fc-match :lang=<etiqueta>, tomando un único alias de familia ASCII (una lista de alias rompería la fila de estilo ASS delimitada por comas).
  • --font <nombre> (origen) y --translation-font <nombre> (traducción) lo anulan, y son rechazados cuando fc-list dice que esa fuente no reclama el idioma detectado. No trabajes alrededor del error eligiendo otra fuente latina — verifica qué cubre la escritura 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 la escritura.
  • Sin fontconfig la selección automática falla ruidosamente; pasa la fuente explícitamente. La ejecución reporta source_font_verified: false / translation_font_verified: false cuando no se pudo verificar la cobertura, así que reporta esa advertencia en lugar de afirmar que la fuente está bien.
  • La ejecución reporta source_font / source_script siempre que el origen no sea latino.

Una transcripción parcialmente traducida es rechazada de plano — 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.

Quema subtítulos duros

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

bash node /scripts/render-hardsub.mjs
/ruta/a/video-origen
/salida/origen.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 -> recurso a MKV, reportado como container_fallback: true.

Los subtítulos duros siempre requieren re-codificació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.

Iguala la tasa de bits de origen

Re-codificar a una calidad fija ignora lo que el origen traía, y la brecha puede ser grande: quemar CRF 21 en un archivo AV1 de 1.5 Mbps produce una copia H.264 de 4.2 Mbps — 2.8x la tasa de bits de origen, casi 3x el tamaño de archivo, sin ganancia visible. El script por lo tanto sondea el origen y deriva un techo -maxrate / -bufsize de su tasa de bits, escalado por cuánto menos eficiente es el códec de salida (H.264 necesita aproximadamente 1.6x la tasa de bits de AV1 para 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 solo porque el perfil .webm fija -b:v 0 para modo de calidad constante. El informe incluye source_video_bitrate, video_bitrate y la decisión bitrate_cap — compara los dos primeros al reportar el resultado.

Anula solo cuando el usuario solicite una tasa de bits o nivel de calidad específico:

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

La tasa de bits es también la palanca para el tamaño de archivo. Cuando un usuario objeta el tamaño de salida, cita la tasa de bits de 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 subtítulos en sí mismo se mantiene nítido incluso en 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 — incluyendo cuando el servidor MCP en sí mismo 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 ejecución deliberadamente nunca inicia un motor propio (un servidor residente mantiene...

[truncado para traducción]

Skills relacionados