video-zh-dubbing: vídeo en inglés doblado al mandarín

Video a Doblaje Chino

Usa el pipeline Python incluido para producir un video completo doblado al chino. No te limites a sugerir un flujo de trabajo cuando el usuario haya proporcionado una URL y solicitado el artefacto final: ejecuta el pipeline si la terminal está disponible y el usuario ha autorizado las acciones de red/descarga requeridas.

Requiere Python 3.10+, FFmpeg/ffprobe, acceso a red para descargas de URL, y un modelo local faster-whisper. La traducción y síntesis de voz en línea son opcionales; usa el backend local CosyVoice cuando se necesite un mandarín natural sin una API de voz paga.

Resuelve <skill-root> como el directorio que contiene este SKILL.md; no asumas que el directorio de trabajo actual del llamador es el directorio de la habilidad. Prefiere <skill-root>/.venv/bin/python en macOS/Linux o <skill-root>/.venv\Scripts\python.exe en Windows cuando ese entorno virtual exista; de lo contrario, usa el intérprete de Python activo. Los comandos a continuación asumen que el directorio actual se ha cambiado a <skill-root>.

Inicio rápido

1. Verifica los requisitos previos:

   python3 scripts/check_environment.py
   

2. Instala FFmpeg y las dependencias de Python. Consulta README.md para comandos en macOS, Windows y Linux.

3. Para una traducción natural sin una API paga, usa un modelo Ollama ya instalado con --translation-provider ollama --ollama-model MODEL. El pipeline lo ejecuta localmente en dos pasos y valida cada ID de segmento; revisa los términos técnicos y la temporización antes de la entrega. Si no hay un modelo local disponible, usa --translation-provider google solo con permiso como borrador en línea y pule manualmente los segmentos con marca de tiempo, o pasa JSON revisado a través de --segments-file. Usa OPENAI_API_KEY o DEEPSEEK_API_KEY solo cuando esté explícitamente permitido; nunca cambies a una API no autorizada.

4. Convierte una URL de video (Bilibili, YouTube o cualquier sitio compatible con yt-dlp):

   python3 scripts/translate_video.py "https://www.youtube.com/watch?v=VIDEO_ID" \
     --translation-provider ollama --ollama-model MODEL --output-dir ./output
   

   Las URLs de Bilibili pueden incluir un parámetro de parte como ?p=2; pasa la URL completa de destino.

5. O procesa un video local:

   python3 scripts/translate_video.py ./input.mp4 \
     --translation-provider ollama --ollama-model MODEL --output-dir ./output
   

Valores predeterminados y opciones

• El idioma de origen predeterminado es inglés (--source-language en); usa auto para detectarlo.
• La voz china predeterminada es zh-CN-XiaoxiaoNeural; usa --voice zh-CN-YunxiNeural para una voz masculina más joven o --voice zh-CN-YunyangNeural para una voz narrativa masculina.
• Para voz natural sin costo por llamada, prefiere un Fun-CosyVoice3-0.5B instalado localmente en modo zero-shot cuando haya un clip de referencia autorizado explícitamente y una transcripción exacta. De lo contrario, usa CosyVoice-300M-SFT con un hablante incorporado (por ejemplo 中文女). Nunca clones una voz sin permiso. El modelo se carga una vez para todos los segmentos, escribe clips WAV PCM16 y guarda el progreso. Consulta README.md para las banderas.
• Si Edge TTS no está disponible, establece DASHSCOPE_API_KEY y usa --tts-provider dashscope --voice Cherry para Qwen3 TTS. El texto de la transcripción traducida se envía a DashScope.
• La traducción predeterminada es auto, que usa solo un OLLAMA_MODEL local explícitamente configurado y se detiene antes de la traducción en caso contrario. Selecciona --translation-provider openai o google explícitamente antes de que cualquier transcripción se envíe a un traductor externo. Ollama requiere su servicio local y un modelo instalado; la habilidad nunca descarga uno automáticamente. Usa --translation-context "tema del video y términos clave" cuando el nombre del archivo no identifique claramente el asunto; de lo contrario, se usa el título o nombre del archivo.
• --audio-mode replace reemplaza el audio original con voz china (predeterminado, confiable). --audio-mode mix mantiene la pista original a bajo volumen debajo de la voz china. --audio-mode background intenta separar las voces originales con Demucs opcional, luego mezcla la voz china con el fondo restante. Si Demucs no está disponible o falla, el script informa el problema y retrocede de manera segura al reemplazo de audio.
• --subtitle-mode soft incrusta subtítulos chinos seleccionables en el MP4 y también escribe un SRT externo (predeterminado). Inspecciona primero los fotogramas de origen: si los subtítulos ya están quemados en la imagen, mantén soft para evitar texto duplicado superpuesto. burn quema los subtítulos en la imagen y requiere una compilación de FFmpeg con el filtro subtitles/libass y una fuente china utilizable. none omite los subtítulos del MP4 pero aún escribe un SRT lateral para revisión.
• Ajusta el ASR con --model small (equilibrado por defecto), --model medium o --model large-v3. Los modelos más grandes necesitan más memoria y tardan más. La primera ejecución descarga el modelo seleccionado.
• Usa --cookies-from-browser chrome solo si has iniciado sesión y el sitio requiere tu propia sesión del navegador. Esto lee las cookies locales del navegador; no está habilitado por defecto.
• Usa --keep-intermediates para conservar el audio fuente descargado, archivos WAV y clips de voz generados para solución de problemas.
• Usa --segments-file path/to/translated.segments.json para reutilizar traducciones revisadas después de una falla de TTS sin repetir el reconocimiento y la traducción.
• Usa --reuse-tts-dir path/to/tts_segments con un conjunto existente de clips generados para ajustar la temporización y volver a renderizar sin llamar al servicio de voz nuevamente.

Verificaciones de salida requeridas

El script debe verificar que el MP4 existe, no está vacío, tiene una pista de video y una pista de audio, y tiene una duración cercana a la entrada. Emite un SRT, JSON de segmentos traducidos y un informe de procesamiento junto al MP4 final. Cualquier etapa fallida debe detener el pipeline y proporcionar un error útil en lugar de pretender que la salida está completa.

Antes de la entrega, inspecciona el JSON/SRT traducido en busca de nombres y términos mal transcritos, frases palabra por palabra no naturales y segmentos que se aceleraron o recortaron. Inspecciona también un fotograma renderizado: rechaza cuadros de glifos faltantes, subtítulos fuera de pantalla y subtítulos quemados duplicados. Para CosyVoice, escucha una muestra corta antes de renderizar un video largo; verifica la pronunciación real de decimales, nombres de código y términos en inglés, no solo su texto escrito. Un segmento revisado puede agregar spoken_text para deletrear un número o nombre de archivo de forma natural mientras que zh_text sigue siendo el subtítulo exacto. Su significado debe coincidir. Evita enviar voz cortada o aceleración notable.

Flujo de trabajo

1. Resuelve URL vs archivo local. Para URLs, descarga solo el video solicitado usando yt-dlp (--no-playlist). Si una página de Bilibili devuelve 412, el script puede usar la API pública de Bilibili solo cuando el video esté explícitamente marcado como descargable; conserva la parte ?p= solicitada. Nunca evites DRM, muros de pago o restricciones de cuenta.
2. Usa ffprobe para inspeccionar las pistas y la duración. Extrae audio PCM mono de 16 kHz.
3. Transcribe con faster-whisper, conservando las marcas de tiempo de origen. Falla claramente si no se detecta voz.
4. Traduce con el tema y el contexto de voz vecino, luego púlelo a un mandarín conciso e idiomático. Conserva IDs, orden, significado, números, nombres y términos técnicos. Verifica los errores de reconocimiento de origen con respecto al tema del video.
5. Genera cada segmento de voz china a través del servicio de voz seleccionado. Ajústalo de manera conservadora a su ventana de tiempo de marca de tiempo; advierte en el informe cuando un segmento necesite aceleración o truncamiento agresivos.
6. Construye una pista de voz china de longitud completa. Aplica el modo de audio solicitado; la separación opcional de Demucs es una mejora, no una dependencia estricta.
7. Escribe SRT chino y JSON traducido. Multiplexa o quema subtítulos según lo solicitado, exporta un MP4 H.264/AAC ampliamente compatible y verifica el resultado.
8. Informa las rutas de salida exactas, la configuración seleccionada, las advertencias y cualquier necesidad de revisión restante.

Ejemplos

# URL de YouTube; traducción por API; voz femenina china; voz superpuesta sobre fondo extraído
OPENAI_API_KEY="$OPENAI_API_KEY" python3 scripts/translate_video.py "https://youtu.be/VIDEO_ID" \
  --translation-provider openai --audio-mode background --subtitle-mode soft --output-dir ./output

# Parte 2 de Bilibili; usa una clave LLM configurada para traducción natural
python3 scripts/translate_video.py "https://www.bilibili.com/video/BV1NAuq6uE8t/?p=2" \
  --translation-provider openai --translation-context "Desarrollo Guiado por Especificaciones SDD y Programación de Agentes" \
  --voice zh-CN-YunyangNeural --audio-mode mix --output-dir ./output

# Quema subtítulos chinos en la imagen
python3 scripts/translate_video.py ./input.mp4 --subtitle-mode burn --output-dir ./output

# Voz completamente local usando CosyVoice3 y una referencia autorizada; sin APIs pagas
python3 scripts/translate_video.py ./input.mp4 --segments-file ./reviewed.segments.json \
  --tts-provider cosyvoice --cosyvoice-python /path/to/cosyvoice-python \
  --cosyvoice-repo /path/to/CosyVoice --cosyvoice-model-dir /path/to/Fun-CosyVoice3-0.5B \
  --cosyvoice-mode zero-shot --cosyvoice-prompt-audio ./reference.wav \
  --cosyvoice-prompt-text-file ./reference.txt --subtitle-mode burn --output-dir ./output

# Transcripción local, traducción con Ollama y narración con CosyVoice
python3 scripts/translate_video.py ./input.mp4 --translation-provider ollama --ollama-model MODEL \
  --tts-provider cosyvoice --cosyvoice-python /path/to/cosyvoice-python \
  --cosyvoice-repo /path/to/CosyVoice --cosyvoice-model-dir /path/to/CosyVoice-300M-SFT \
  --cosyvoice-mode sft --output-dir ./output

Seguridad y derechos

Solo procesa videos que poseas, para los que tengas licencia de adaptación o que de otro modo estés autorizado a descargar y transformar. Respeta los términos de la plataforma de origen y los derechos de autor. Nunca evites DRM o controles de acceso técnico. --cookies-from-browser es opcional y solo debe usar la sesión autenticada del propio usuario. No publiques un derivado doblado sin confirmar los derechos aplicables.

El proyecto es para aprendizaje, investigación e intercambio técnico. No lo uses para actividades ilegales, clonación de voz no autorizada, fraude, suplantación de identidad o contenido engañoso. Consulta el descargo de responsabilidad en README.md; los usuarios son responsables de su uso y distribución del contenido generado según la ley aplicable.