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
- 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 queDASHSCOPE_BASEcoincide con la región de la clave. No se sube ni factura nada. Agregue--offlinepara omitir esa solicitud. - Si la salida es 3, ejecute
bash scripts/install.shy corrija cada filaFAILque 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). - 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.
| Paso | Escribe | API de pago |
|---|---|---|
fetch <url-o-archivo> | src.mp4 | no |
transcribe [--audio-url URL] | audio.mp3, asr_task.json, transcription.json | sí |
annotate | annotations.json | sí |
ass [--no-pop] [--no-annotate] | subs.ass | no |
render [--segment 1200] [--out FILE] | karaoke.mp4 | no |
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ódigo | Significado | Qué hacer |
|---|---|---|
| 0 | Hecho | Continuar. |
| 2 | Error de uso | Lea el --help del subcomando. |
| 3 | Entorno no listo | Siga la línea next:, o ejecute doctor. Pida al usuario una clave o sudo, o que corrija la configuración de región. |
| 4 | Servicio remoto falló | Siga la línea next:. Volver a ejecutar el mismo comando mantiene el trabajo terminado. |
| 5 | Falta entrada de un paso anterior | Ejecute el paso nombrado en la línea next:. |
| 1 | Falla inesperada | Lea 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.doctorsolo informa si está configurada. transcribeyannotatecuestan dinero en la cuenta del usuario. No use--forceen 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.