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,boxedyhigh-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:
| 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 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
-
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 }Añade
min_chars/max_charssolo cuando el usuario solicite longitudes de subtítulos diferentes. Añademodelsolo 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 por palabra. Esta solicitud ya ejecuta la ruta de alineación forzada local integrada 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 conversor acepta JSON de transcripción directa o un contenedor conresult. -
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 deffprobe— un ejecutable separado que también debe estar en PATH. Cada vista previa y cada incrustación pasa por el filtroass, por lo que un FFmpeg sin libass falla conNo such filter: 'ass'sin importar qué preset se seleccione. La incrustación a MP4/MOV/MKV/TS además necesitalibx264; WebM necesitalibvpxylibopus. 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, usacurl -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). 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, 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-toplo 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-onlyignora 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 conedgespeak-broadcasty 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 cuandofc-listdice que esa fuente no cubre el idioma detectado. No evites el error eligiendo otra fuente latina — verifica qué cubre el script 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 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: falsecuando 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_scriptsiempre 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 nonedesactiva 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...