Communitygithub.com

zgyk4167/karaoke-subtitles

Incrusta subtítulos de karaoke palabra por palabra en videos en inglés. Cada palabra cambia de blanco a verde y aumenta brevemente de tamaño al ser pronunciada. Opcionalmente, añade glosas cortas en chino simplificado (azul) para términos técnicos, palabras difíciles, phrasal verbs y modismos, dirigido a estudiantes de chino de nivel CET-6 (China's College English Test Band 6, intermedio-alto).

¿Qué es karaoke-subtitles?

Esta skill automatiza la creación de subtítulos de karaoke sincronizados palabra por palabra para videos en inglés. Toma un archivo de video local o una URL (YouTube, X o cualquier sitio compatible con yt-dlp) y produce un video con subtítulos incrustados donde cada palabra se ilumina en verde y escala brevemente al ser pronunciada. Además, ofrece la opción de agregar glosas en chino simplificado para términos técnicos, palabras difíciles, phrasal verbs y modismos, ideal para estudiantes de chino de nivel CET-6. Funciona mediante un pipeline no interactivo: descarga el audio, lo transcribe con DashScope ASR (que proporciona marcas de tiempo por palabra), analiza el texto para seleccionar términos que merecen glosas, y genera subtítulos en formato ASS usando ffmpeg y libass. Requiere una clave API de Alibaba Cloud Model Studio (DashScope), pero no necesita un bucket de almacenamiento. Es compatible con Claude Code, Cursor y Codex, y gestiona trabajos largos con reanudación automática si se interrumpe.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add zgyk4167/karaoke-subtitles

Preguntar en tu IA favorita

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

Documentación

Subtítulos de karaoke

Pipeline: video → audio 16 kHz → DashScope ASR con marcas de tiempo por palabra → LLM selecciona términos y escribe glosas en chino → subtítulos ASS de karaoke → incrustación con ffmpeg y libass.

Todo el trabajo se realiza a través de una CLI no interactiva, scripts/pipeline.py. Las rutas en este archivo son relativas al directorio de la skill. Ejecute cada comando desde cualquier directorio, con la ruta de la skill al frente, por ejemplo python3 /path/to/karaoke-subtitles/scripts/pipeline.py doctor.

Antes de la primera ejecución

  1. Ejecute python3 scripts/pipeline.py doctor. La salida 0 significa que está listo. Cuando se establece una clave, realiza una petición gratuita para verificar que DASHSCOPE_BASE coincide con la región de la clave. No se sube ni factura nada. Agregue --offline para omitir esa solicitud.
  2. Si la salida es 3, ejecute bash scripts/install.sh y corrija cada fila FAIL que imprima. Si el script dice que sudo necesita una contraseña, o falta la clave API, deténgase y pregunte al usuario. Nunca pida al usuario que pegue la clave en el chat; pídale que la ponga en .env (consulte .env.example).
  3. Detalles de configuración y ajustes: references/prerequisites.md.

Confirmar con el usuario

  • El video: un archivo local o una URL. El usuario debe tener el derecho de procesarlo.
  • Glosas activadas (por defecto) o desactivadas (--no-annotate).
  • Dónde va el resultado. Por defecto: devolver la ruta del archivo de salida.

Mantenga el estilo visual como está a menos que el usuario solicite un cambio. Valores de estilo: references/ass-style.md.

Ejecutar

Un comando ejecuta todo y se reanuda después de una interrupción:

python3 scripts/pipeline.py all "<url-o-archivo>" --work ./job [--no-annotate]

O ejecute los pasos uno por uno. Cada paso escribe nombres de archivo fijos en el directorio de trabajo y omite el trabajo cuya salida ya existe. Agregue --force para rehacer un paso. Cada subcomando tiene --help.

PasoEscribeAPI de pago
fetch <url-o-archivo>src.mp4no
transcribe [--audio-url URL]audio.mp3, asr_task.json, transcription.jsonsí
annotateannotations.jsonsí
ass [--no-pop] [--no-annotate]subs.assno
render [--segment 1200] [--out FILE]karaoke.mp4no

La API ASR lee el audio desde una URL. Por defecto, transcribe sube job/audio.mp3 al almacenamiento temporal gratuito de DashScope. Ese almacenamiento conserva el archivo durante 48 horas y solo el modelo ASR de esta cuenta puede leerlo. No se necesita bucket ni configuración adicional. Si el usuario prefiere su propio almacenamiento, ya sea AUDIO_URL_CMD en .env que sube el archivo e imprime una URL, o pasa --audio-url URL.

El progreso va a stderr. Cada paso imprime la ruta de su salida en stdout.

Códigos de salida

CódigoSignificadoQué hacer
0HechoContinuar.
2Error de usoLea el --help del subcomando.
3Entorno no listoSiga la línea next:, o ejecute doctor. Pida al usuario una clave o sudo, o que corrija la configuración de región.
4Servicio remoto fallóSiga la línea next:. Volver a ejecutar el mismo comando mantiene el trabajo terminado.
5Falta entrada de un paso anteriorEjecute el paso nombrado en la línea next:.
1Falla inesperadaLea la salida de la herramienta arriba del error.

Trabajos largos

La transcripción y el renderizado pueden tomar más tiempo del que permite una herramienta de shell. Ejecute el comando en segundo plano con un archivo de registro, por ejemplo nohup python3 scripts/pipeline.py all "<src>" --work ./job > job.log 2>&1 &, luego lea el registro hasta que termine. Si el proceso muere, ejecute el mismo comando nuevamente. La transcripción reanuda la tarea ASR guardada en lugar de pagar de nuevo; el renderizado reutiliza segmentos terminados.

Verificar antes de entregar

Extraiga un fotograma del medio de la salida (ffmpeg -ss <segundos> -i job/karaoke.mp4 -frames:v 1 check.jpg) y mírelo si puede ver imágenes. Si la fuente ya tiene subtítulos incrustados, dígaselo al usuario y ofrézcale dos opciones: cubrirlos con una banda de desenfoque, o mover los nuevos subtítulos a la parte superior.

Reglas

  • Nunca imprima, registre ni confirme DASHSCOPE_API_KEY. doctor solo informa si está configurada.
  • transcribe y annotate cuestan dinero en la cuenta del usuario. No use --force en ellos a menos que el usuario esté de acuerdo.
  • Las glosas son solo en chino simplificado. Para espectadores que no lean chino, use --no-annotate.
  • ASR puede malinterpretar nombres y jerga, y puede devolver texto en minúsculas. Dígale al usuario que revise los subtítulos antes de compartir el video.

Skills relacionados