Bilibili / YouTube: Audio a Subtítulos
Usa el entorno conda llamado codex para transcribir el idioma original. El modelo predeterminado es Qwen/Qwen3-ASR-1.7B + Qwen/Qwen3-ForcedAligner-0.6B, invocado a través del kit oficial qwen-asr con return_time_stamps=True. El modelo ASR solo genera texto; ForcedAligner proporciona marcas de tiempo a nivel de palabra/carácter. Organiza los SRT según puntuación, pausas, aproximadamente 6 segundos y 42 caracteres, con límites provenientes de alineaciones reales, sin dividir el tiempo por igual ni descartar texto.
--engine whisper conserva el modo nativo de audio largo de openai/whisper-large-v3-turbo, el pipeline usa return_timestamps=True sin pasar chunk_length_s. Los fragmentos externos experimentales de Whisper produjeron segmentos de subtítulos de cinco minutos y repeticiones continuas, por lo que no deben activarse por defecto. El SDK oficial de Qwen procesa fragmentos de hasta 180 segundos según límites de baja energía para la alineación, restaurando automáticamente el tiempo global; esto es una implementación diferente del fragmentación experimental de 30 segundos del pipeline de Whisper.
Las marcas de tiempo de Qwen admiten chino, inglés, cantonés, francés, alemán, italiano, japonés, coreano, portugués, ruso y español; para otros idiomas, se selecciona explícitamente Whisper, sin asumir que el ASR admita la alineación solo porque admite el idioma. Por defecto, la detección es automática; cuando se conoce el idioma, se pasa --language chinese o english. También acepta códigos comunes como zh/en.
Ejecución y Salida
Primero registra la ruta absoluta del proyecto actual del usuario; no uses el directorio de instalación del skill como directorio del proyecto. Reemplaza <directorio-skill> por el directorio donde se encuentra este SKILL.md, y <directorio-proyecto> por la ruta del proyecto al invocar; pasa la URL como un solo argumento entre comillas.
conda run --no-capture-output -n codex python "<directorio-skill>/scripts/bilibili_audio_subtitles.py" \
'https://www.bilibili.com/video/BV1w88n6uE1X/' \
--project-dir '<directorio-proyecto>'
El mismo comando también acepta enlaces de YouTube, por ejemplo 'https://youtu.be/jNQXAC9IVRw'. Conserva el nombre original del skill y del script; las llamadas existentes $bilibili-audio-subtitles pueden seguir usándose.
El audio de Bilibili se descarga con yutto y se guarda en ~/Downloads/<BV o av>-p<N>.m4a; el audio de YouTube se descarga con yt-dlp y se guarda en ~/Downloads/youtube-<ID-de-video>.m4a. El directorio del proyecto solo produce un SRT con marcas de tiempo y cuerpo del subtítulo; solo se entrega este subtítulo recomendado, sin VTT, TXT, JSON ni archivos de comparación de modelos. Las advertencias de calidad necesarias se indican con un breve aviso para revisión, sin generar archivos de entrega adicionales. El text/chunks original del modelo y los diagnósticos de reproducción se guardan en JSON independientes en ~/.cache/bilibili-audio-subtitles/runs/; el registro de ejecución proporcionará la ruta. Estos son registros de diagnóstico internos, no archivos de subtítulos de entrega adicionales.
El audio existente se reutiliza. Cuando ya existe un SRT con el mismo nombre, el nuevo resultado usa automáticamente un nombre de archivo independiente que incluye el modo, la versión del script y un número de ejecución, conservando la versión anterior. No sobrescribe ni elimina subtítulos antiguos. Tras un reintento, se indica claramente al usuario la versión SRT recomendada, no solo se listan todas las rutas.
Opciones comunes:
--audio '/ruta/absoluta/audio.m4a': transcribe audio local, sin pasar URL.--language chinese: especifica explícitamente cuando se conoce el idioma; por defecto detección automática.--engine qwen|whisper: predeterminado Qwen; Whisper para comparación, prioridad de velocidad o idiomas no soportados por la alineación de Qwen.--project-dir/--download-dir: sobrescribe el directorio de salida del proyecto o de Descargas.--device auto|cpu|cuda:0: predeterminado prioriza CUDA; no cambia automáticamente los controladores del sistema.--download-only: solo descarga; luego continúa con--audio.--output-name 'nombre-archivo': personaliza el nombre del SRT, sin ruta ni extensión.--diagnostics-dir '/ruta/absoluta': sobrescribe el directorio de resultados internos y diagnósticos.--auth-file '/ruta/absoluta': solo para archivos de autenticación de Bilibili/yutto ya proporcionados por el usuario.--cookies-file '/ruta/absoluta': solo para archivos Netscape Cookie de YouTube ya proporcionados por el usuario; no escanea navegadores.--max-cue-seconds 12: umbral de advertencia para subtítulos demasiado largos; predeterminado 12 segundos.--limit-seconds 30: fragmento solicitado por el usuario o prueba de humo; el nombre de archivo se marca como sample, y en el informe se indica claramente que no es una transcripción completa.--threads 8/--batch-size 1: controla hilos y tamaño de lote de inferencia.--engine whisper --chunk-length-seconds 30: solo se activa con una razón clara y explicando el riesgo experimental; Qwen no acepta este parámetro.
Admite enlaces estándar de Bilibili /video/BV…, /video/av… y números BV/av directos. Conserva ?p=N para especificar la parte, eliminando parámetros de seguimiento. Por defecto solo procesa una parte; para múltiples partes, invoca una por una. Los enlaces cortos de Bilibili se resuelven primero en enlaces estándar.
YouTube admite youtube.com/watch?v=…, youtu.be/…, shorts/…, live/… y embed/… (incluyendo subdominios www, m, music). Unifica a enlace estándar de video único, eliminando parámetros de seguimiento, reproducción y listas de reproducción, y usa explícitamente --no-playlist; los enlaces que solo son listas de reproducción se rechazan directamente. La descarga selecciona bestaudio, se extrae a M4A mediante FFmpeg, sin descargar subtítulos de la plataforma, carátulas ni videos como archivos de entrega. No escanea navegadores, no imprime Cookies, no amplía sin autorización a colecciones completas.
Fallo de Descarga: Priorizar Actualización
Esta regla se aplica a ambas plataformas. Cuando la descarga real falla o el descargador devuelve éxito pero no hay audio válido, el script primero consulta la versión estable compatible del paquete de descarga correspondiente: Bilibili verifica yutto, YouTube verifica yt-dlp. Usa pip index versions <paquete> --json del Python de codex para comparar la versión local con la del índice de paquetes, respetando la configuración de pip existente.
Si hay una versión más reciente, el script solo actualiza ese paquete de descarga y sus dependencias necesarias en ese entorno, luego reintenta la descarga una vez. yt-dlp usa yt-dlp[default], manteniendo la compatibilidad con la dependencia EJS de YouTube. Si no hay nueva versión, la consulta falla, la actualización falla o la segunda descarga sigue fallando, guarda el error original y el evento de actualización y se detiene; no reintenta infinitamente ni cambia automáticamente a nightly/master. Después de verificar la actualización del paquete, verifica la red, inicio de sesión, si el video está eliminado, restricciones regionales y el tiempo de ejecución JS según el error real.
La actualización requiere acceso a la red y permisos de escritura en el entorno. Cuando los permisos son limitados, solicita los permisos necesarios para esta ejecución, sin cambiar el Python del sistema ni actualizar modelos de transcripción o PyTorch por problemas de descarga. Una consulta de actualización fallida no significa que ya sea la última versión. Los archivos de audio dañados existentes deben informarse claramente y conservarse, sin sobrescribir directamente; los archivos de audio no válidos generados en reintentos fallidos también conservan nombres independientes.
Verificación Estructural y de Calidad
Ambos tipos de verificación deben informarse por separado:
- Verificación estructural: coincidencia de duración de decodificación de audio completo, subtítulos no vacíos, marcas de tiempo finitas, ordenadas, con inicio y fin válidos y que no superen la duración de la transcripción. En caso de fallo, conserva el diagnóstico original y no genera SRT.
- Verificación de calidad: subtítulos que superan 12 segundos, una sola línea supera 120 caracteres de texto, densidad de texto superior a 25 caracteres/segundo, duración continua de al menos 8 segundos pero inferior a 0.5 caracteres/segundo, una sola línea con palabras/frases repetidas al menos 5 veces, al menos 3 líneas consecutivas con el mismo texto. También se marca para revisión si las marcas de tiempo necesitan corrección. Los umbrales y detalles de las advertencias se escriben en el diagnóstico.
El código de salida 0 indica que la estructura pasó y no se encontraron anomalías de calidad evidentes; el código de salida 2 indica que el SRT se generó pero necesita revisión; el código de salida 1 indica un fallo de ejecución o estructural. No declares el código de salida 2 como una verificación exitosa. Las reglas de calidad son sugerencias heurísticas, no una prueba de la corrección del contenido de voz; los falsos positivos deben juzgarse comparando con el audio, sin aumentar umbrales sin autorización, eliminar texto, recortar por igual duración o reintentar infinitamente para eliminar advertencias.
Cuando hay anomalías de calidad, proporciona la ventana de tiempo de advertencia y la ruta de diagnóstico. Si la anomalía proviene de fragmentación externa explícita de Whisper, se puede reintentar una vez con el modo nativo --engine whisper, conservando ambas salidas; si sigue siendo anómala, indica que se necesita revisión, sin cambiar automáticamente de modelo ni reintentar infinitamente. Las correcciones de terminología se manejan por separado, sin reemplazar globalmente términos como "订单流" o "鼠标" por suposición. Incluso si no hay advertencias, solo se denomina borrador de transcripción automática, no subtítulos revisados línea por línea.
El diagnóstico JSON conserva el text/chunks original, segmentos normalizados, estado estructural, estado de calidad y advertencias, registros de corrección, estado de recomendación, versión del script, modo de transcripción, parámetros de generación, GenerationConfig y revisión del modelo, versiones de bibliotecas, dispositivo, duración y tiempo de inferencia. También registra la plataforma de origen, la versión del paquete de descarga, la verificación de actualización y los eventos de reintento. Qwen conserva adicionalmente la cadena ASR original antes del posprocesamiento del SDK, unidades de alineación completas, idioma detectado, recuento de unidades de duración cero, revisión del modelo de alineación y configuración de segmentación; las repeticiones en la salida original y las cercanías al límite de longitud de generación también activan revisión, no permitiendo que el filtrado de repeticiones del SDK oculte anomalías. Las marcas de tiempo de duración cero cuantificadas se combinan con los subtítulos adyacentes y se conserva el texto, sin falsificar la duración a nivel de palabra; si no hay duración válida o el texto no coincide en una sección completa, guarda el resultado original y falla. Si la descarga o la transcripción fallan, también guarda un diagnóstico independiente para su comparación y reproducción.
Entorno
Verifica Python del entorno codex, paquetes de descarga de la plataforma correspondiente, torch, transformers, accelerate, numpy, qwen-asr, y ffmpeg y ffprobe en PATH. Solo instala las dependencias faltantes en ese entorno:
conda run --no-capture-output -n codex python -m pip install yutto 'yt-dlp[default]' 'qwen-asr==0.0.6' numpy
El kit de herramientas Qwen fija Transformers 4.57.6 y accelerate 1.12.0, evitando actualizar a Transformers 5 o instalar vLLM para esta tarea. Conserva el PyTorch CUDA existente y funcional. Entorno verificado localmente: Python 3.12, qwen-asr 0.0.6, yutto 2.3.1, Transformers 4.57.6, PyTorch 2.14.1+cu130; en CUDA, Qwen usa bfloat16 y SDPA; no requiere compilar FlashAttention. Si es necesario reconstruir el entorno GPU local:
conda run --no-capture-output -n codex python -m pip install 'torch==2.14.1+cu130' --index-url https://download.pytorch.org/whl/cu130
Si el shell no encuentra conda, localiza su ruta absoluta. Localmente se puede usar /home/leev/miniforge3/bin/conda o /home/leev/miniforge3/envs/codex/bin/python. Si la detección de GPU falla en un sandbox restringido, vuelve a detectar en un entorno con acceso permitido a dispositivos NVIDIA, sin concluir que el controlador está dañado o instalar la versión CPU. Solo en máquinas sin GPU se usa el PyTorch CPU correspondiente.
YouTube también requiere las dependencias de soporte EJS predeterminadas de yt-dlp y un tiempo de ejecución JS compatible. El script busca Deno, Node, Bun o QuickJS en PATH y los pasa explícitamente a yt-dlp; localmente se verificaron Node 24 y yt-dlp 2026.08.19. Si no encuentra un tiempo de ejecución o la versión no es compatible, lo informa claramente, sin reinstalar otros paquetes repetidamente debido a fallos de descarga.
La primera ejecución descarga el modelo en la caché estándar de Hugging Face, respetando HF_HOME / HF_HUB_CACHE; si la caché ya está completa y la red es inestable, se puede establecer HF_HUB_OFFLINE=1. Bilibili solo usa yutto para descargar, deshabilitando video, danmaku, subtítulos de la plataforma, carátulas e información de capítulos. YouTube solo usa yt-dlp para descargar audio. Si la descarga falla, primero aplica la regla de actualización y luego informa el error real; si la transcripción falla, conserva el audio. Cuando los permisos son limitados, solicita los permisos de directorio y ejecución de GPU necesarios para esta ejecución.
Validación de Regresión
Ejemplo fijo: BV1w88n6uE1X. Ejecuta la transcripción predeterminada completa con Qwen usando el mismo audio; cuando se necesite comparación, usa --engine whisper, conservando ambos diagnósticos e invocando:
python -m unittest discover -s '<directorio-skill>/scripts' -p 'test_*.py'
python '<directorio-skill>/scripts/check_regression.py' \
--candidate '<JSON diagnóstico nuevo>' --baseline '<JSON antiguo>'
Las ventanas de tiempo clave son 00:43.240–05:46.060 y 08:10–08:33. En pruebas, Qwen generó 282 segmentos con un máximo de 5.76 segundos; Whisper nativo generó 438 segmentos con un máximo de 5.18 segundos; ninguna de las dos ventanas mostró advertencias de longitud excesiva o repetición. No uses el número fijo de segmentos como condición de aprobación para otros entornos. El resultado anterior de 117 segmentos, con un subtítulo de 302.82 segundos y 23 "好" (bien) consecutivos, debería ser marcado por la verificación de calidad nueva como necesario de revisión. La aprobación de regresión solo prueba que los problemas conocidos de segmentación y repetición no se han reproducido; la semántica y la terminología aún deben compararse con el audio.
La regresión de YouTube incluye rutas de watch/enlace corto/Shorts, descarga de audio de un solo video, consulta prioritaria de actualización tras fallo, un solo reintento tras actualización, y detención si no hay actualización o la consulta falla. En pruebas, el audio de aproximadamente 19 segundos de jNQXAC9IVRw se descargó completamente; Qwen generó un SRT de 7 segmentos (Whisper: 4 segmentos). Los videos de prueba no disponibles también verificaron las rutas de verificación de actualización y diagnóstico de fallo.
La selección de modelos, los tiempos reales y las limitaciones se encuentran en references/model-evaluation.md; consúltalo al comparar modelos o reevaluar. Actualmente, el sesgo predeterminado favorece la precisión en la identificación de terminología china; no se puede afirmar que sea superior a Whisper para todos los idiomas y audios.
Implementación basada en: Proyecto oficial yutto, Proyecto oficial yt-dlp, Proyecto oficial Qwen3-ASR, Documentación del modelo Whisper.