¿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,boxedyhigh-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:
| Metraje | Preset |
|---|---|
| Paisaje general o contenido mixto | classic |
| Fondo limpio, mayormente oscuro | minimal |
| Fondo ocupado, brillante, diapositivas o grabación de pantalla | boxed |
| Vertical/móvil o fondo consistentemente difícil | high-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
-
Confirma que el origen existe e inspecciona su duración, dimensiones y contenedor con
ffprobe. -
Llama a
edgespeak_transcribe_fileuna vez:{ "path": "/ruta/absoluta/video-origen", "timestamps": "word", "start_margin": 0, "end_margin": 0 }Agrega
min_chars/max_charssolo cuando el usuario solicite longitudes de subtítulos diferentes. Agregamodelsolo cuando el usuario nombre uno. Si la localidad importa, inspeccionaedgespeak_list_modelsy no elijas un modelo remoto sin consentimiento. -
No llames a
edgespeak_aligndespué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 devuelvesegments[].words[]. -
Para una respuesta MCP larga, usa
artifact_json_path. Para una respuesta en línea, guarda el objetoresultcomo JSON. El convertidor acepta tanto JSON de transcripción directo como un envoltorio conresult. -
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 aedgespeak_alignuna vez más con"search_effort": "extended"(CLI:--search-effort extended). Busca más ampliamente, se ejecuta más lento y usa memoria extra; citaalignment.estimated_extra_bytescuando 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. Consultaedgespeak-alignpara 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ásffprobe— un ejecutable separado que también debe estar en PATH. Cada vista previa y cada quema pasa a través del filtroass, por lo que un FFmpeg sin libass falla conNo such filter: 'ass'sin importar qué preset se seleccione. Quemar a MP4/MOV/MKV/TS adicionalmente necesitalibx264; WebM necesitalibvpxylibopus. 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. ElminCliVersiondel frontmatter es el CLI más antiguo para el que está escrita esta habilidad — siedgespeak-cli --versiones más antiguo, o falta una bandera documentada en--help, ejecutaedgespeak-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-toplo 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-onlyignora 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 cuandofc-listdice que esa fuente no reclama el idioma detectado. No trabajes alrededor del error eligiendo otra fuente latina — verifica qué cubre la escritura confc-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: falsecuando 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_scriptsiempre 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 nonedeshabilita 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]