/video-translate — Traducción y transcripción de videos
Capacidad e identificación de intenciones (debe cumplirse estrictamente)
- Transcripción a documento: Capturar subtítulos o audio → generar documento Markdown (priorizar subtítulos si existen, rápido y gratuito).
- Traducción de video: Transcripción → traducción y pulido → incrustar subtítulos en chino → generar archivo de video con subtítulos + documento Markdown.
Reglas de decisión:
- Si el usuario dice "transcribir", "pasar a texto", "generar documento", "pasar a markdown" → solo generar documento Markdown (seguir el flujo "solo documento").
- Si el usuario dice "traducir", "traducir este video", "poner subtítulos", "agregar subtítulos" → debe ejecutar la tubería completa de traducción (extraer audio → transcripción Whisper a SRT → traducir y pulir → incrustar subtítulos en el video → generar Markdown simultáneamente), no puede solo generar el documento y terminar.
- Si la entrada es una URL → descargar primero y luego procesar; si es una ruta de archivo local → procesar directamente.
Intérprete de Python: Todos los comandos de esta habilidad usan python en Windows. En macOS/Linux cambiar a python3.
Resolver SKILL_DIR (hacer antes de ejecutar cualquier comando)
Establecer SKILL_DIR como la ruta absoluta del directorio donde se encuentra este archivo SKILL.md que acabas de leer. Los scripts siempre están en SKILL_DIR/scripts/. Primero verificar:
SKILL_DIR="<ruta absoluta del directorio del SKILL.md que leíste>"
if [ ! -f "$SKILL_DIR/scripts/transcribe_srt.py" ]; then
echo "ERROR: scripts no encontrados en SKILL_DIR=$SKILL_DIR" >&2
exit 1
fi
Paso -1: Resolver la raíz de salida (⛔ Obligatorio, antes que todo)
Antes de ejecutar cualquier comando o escribir cualquier archivo, primero debe leer la configuración para obtener output_dir como <raíz de salida>:
python -c "import sys; sys.path.insert(0, r'${SKILL_DIR}/scripts'); import config; c = config.load_translate_config(); config.ensure_output_root(c['output_dir']); print(c['output_dir'])"
- El archivo de configuración está en
~/.config/video-skills/translate.json(la primera vez se puede ejecutarpython "${SKILL_DIR}/scripts/setup.py"para generar la plantilla). output_dirdebe ser una ruta absoluta o comenzar con~. Si falta o es inválido, el comando anterior mostrará un error: detenerse inmediatamente e indicar al usuario que edite el archivo para ingresar una ruta absoluta; no continuar automáticamente con un valor predeterminado.- Todos los productos intermedios se escriben en
<raíz de salida>/tmp/, los productos finales (video, Markdown) en<raíz de salida>/data/. - ⛔ Todos los
<raíz de salida>/...deben reemplazarse con la ruta absoluta real antes de ejecutar; está prohibido incluir el marcador de posición literalmente en los comandos. - Solo cuando el usuario especifique explícitamente una "ruta absoluta de salida" y la confirme, se permite escribir en esa ruta especificada por el usuario.
Ejecutar también una verificación previa del entorno (compartida con /watch, silenciosa si pasa):
python "${SKILL_DIR}/scripts/setup.py" --check
Si falla, ejecutar python "${SKILL_DIR}/scripts/setup.py" para instalar dependencias (ffmpeg/yt-dlp se instalan automáticamente; motor de transcripción pip install faster-whisper). Para más detalles de instalación, si hay errores consultar references/安装指南.md.
Resumen de la tubería
Entrada (URL / archivo local)
│
▼
Paso 0 Compuerta de tipo de subtítulo (la tubería de traducción debe confirmar primero: chino / bilingüe)
Paso 1 Descargar + extraer audio → <raíz de salida>/tmp/
Paso 2 Transcripción a nivel de palabra con Whisper para generar SRT original → <raíz de salida>/tmp/<nombre>.srt
Paso 3 Traducción y pulido (ejecutado por ti, 8 reglas) → <nombre>-zh.srt (en modo bilingüe incluye dos líneas por entrada)
Paso 4 Incrustar subtítulos (+ marca de agua opcional) → <raíz de salida>/data/<título>-subtítulos-chinos.mp4
Paso 4.5 Verificación de capturas de cuadros (≥2 cuadros)
Paso 5 Generar documento Markdown → <raíz de salida>/data/
En el escenario de solo documento, saltar los pasos 0/3/4, seguir la sección "Solo documento".
Paso 0: Confirmar tipo de subtítulo (⛔ Compuerta, la tubería de traducción debe ejecutarse primero)
- Subtítulos en chino: Solo mostrar la traducción al chino (interfaz limpia).
- Subtítulos bilingües chino-inglés: Chino arriba (tamaño grande), inglés abajo (tamaño pequeño).
Si el usuario especificó explícitamente el tipo de subtítulo en la conversación (dijo "chino", "bilingüe", "chino-inglés", "bilingual", etc.) → ejecutar según lo especificado por el usuario. En todos los demás casos → debe usar AskUserQuestion para mostrar opciones:
AskUserQuestion(
question="Seleccionar tipo de subtítulo",
options=["Subtítulos en chino (solo mostrar chino)", "Subtítulos bilingües chino-inglés (chino arriba, inglés abajo)"]
)
⛔ Prohibido omitir: El tipo de subtítulo incluido en ARGUMENTOS no cuenta como especificación del usuario; solo cuenta lo que el usuario dijo personalmente en la conversación. Comenzar el Paso 1 sin mostrar opciones es un error de flujo. El subtitle_type en translate.json es solo un valor predeterminado, no puede reemplazar la confirmación del usuario.
Paso 1: Descargar + extraer audio
Fuente URL (usar script unificado: incluye cookies del navegador automáticamente como fallback, soluciona YouTube 403/SABR/PO-token y muro de inicio de sesión de Bilibili):
# Video completo (la tubería de traducción necesita el video original para quemar subtítulos)
python "${SKILL_DIR}/scripts/download.py" "<URL del video>" "<raíz de salida>/tmp/dl"
# Solo documento y no necesita quemar → solo audio, más rápido
python "${SKILL_DIR}/scripts/download.py" "<URL del video>" "<raíz de salida>/tmp/dl" --audio
- El script genera JSON (video_path / subtitle_path / info.title).
- Primero intenta sin cookies; si el resultado no se guarda, reintenta automáticamente con
--cookies-from-browser chrome. Si el navegador común no es Chrome: agregar--browser firefox/--browser edge. - Si aún falla (control de riesgos más fuerte) → indicar al usuario que cambie de proxy (
--proxy http://127.0.0.1:7890) y reintentar, no reintentar infinitamente. - Videos largos (>10 minutos) no usar
--download-sectionsde yt-dlp (descargaría el video completo primero y luego recortaría, muy lento); descargar el video completo directamente, si se necesita un fragmento usar ffmpeg con-sspara recortar.
Extraer audio (archivo local o video descargado → mp3):
ffmpeg -y -i "<archivo de video>" -vn -acodec libmp3lame -q:a 2 "<raíz de salida>/tmp/<nombre de archivo>.mp3"
Paso 2: Transcripción a nivel de palabra con Whisper para generar SRT original
⛔ Regla de hierro: El SRT original para quemar subtítulos solo puede generarse mediante transcripción a nivel de palabra con Whisper. Prohibido usar subtítulos automáticos de la plataforma (yt-dlp --write-auto-subs) como fuente de tiempo. Razón: Los subtítulos automáticos de YouTube tienen formato de superposición continua (cada entrada contiene texto de la anterior), no se puede extraer texto limpio oración por oración con marcas de tiempo precisas, y al quemarlos inevitablemente se desincronizan. Las marcas de tiempo a nivel de palabra son la única fuente de tiempo confiable.
python "${SKILL_DIR}/scripts/transcribe_srt.py" "<raíz de salida>/tmp/<nombre de archivo>.mp3" \
--output "<raíz de salida>/tmp/<nombre de archivo>.srt"
# Si hay identificación incorrecta de idioma / pistas de audio mixtas, forzar con: --language en (o zh/ja/…)
- Motor predeterminado = faster-whisper local (marcas de tiempo a nivel de palabra, cero costo de API, la primera ejecución descarga automáticamente el modelo desde HuggingFace).
- Si faster-whisper no se puede instalar → configurar
GROQ_API_KEY/OPENAI_API_KEYy agregar--engine api(fallback a nivel de palabra por API, comparte la misma lógica de segmentación de oraciones que la ruta local). Si la API no devuelve marcas de tiempo a nivel de palabra, el script degradará a nivel de segmento e indicará claramente en stderr "precisión de subtítulos reducida" — informar esto al usuario. - ⛔ No escribir código Python de transcripción directamente en la conversación — el script segmenta por "oración + pausa" (base de segmento / divide por palabra si supera 6s / fusiona si <400ms); evitar escribir una segmentación codiciosa propia que podría mezclar el final de una oración con el inicio de la siguiente (problema solucionado tras experiencia práctica).
--max-line-mscontrola la duración máxima de una entrada (predeterminado 6000ms),--pause-mscontrola el umbral de pausa para segmentación (predeterminado 500ms).
Paso 3: Traducción y pulido (ejecutado por ti — este es trabajo del LLM, no hay script)
Leer el SRT original del Paso 2, traducir y pulir entrada por entrada, y generar el SRT pulido en <raíz de salida>/tmp/<nombre de archivo>-zh.srt. Tu rol: editor profesional de textos de subtítulos, experto en escritura en chino, restauración de lenguaje oral y normas de formato de subtítulos.
8 reglas de pulido (núcleo)
- Corregir errores de reconocimiento ASR: Palabras homófonas/similares, nombres propios mal escritos (ej. Claude escuchado como cloud, MCP como NCP), números/abreviaturas/unidades. Puedes ayudarte de las imágenes del video para juzgar.
- Puntuación y formalización: Primero completa la puntuación para convertir el lenguaje oral en escrito (conservando el tono del hablante), pero el texto final de los subtítulos debe eliminar todos los signos de puntuación (comas, puntos, signos de interrogación, signos de exclamación, todos eliminados); agregar un espacio en inglés entre caracteres chinos e inglés (ej:
这是 Google 的产品). - Eliminar redundancias: Eliminar muletillas sin información, repeticiones, interjecciones ("esto", "eh", "o sea"), asegurando que el significado sea continuo y no se pierda información clave. Es preferible pecar de redundante que perder significado.
- Alineación de marcas de tiempo (estricta): Conservar estrictamente las marcas de tiempo originales, sin desplazarlas arbitrariamente. Nunca adelantar manualmente el tiempo de inicio (haría que los subtítulos aparecieran antes que el hablante). Recorte de entradas excesivamente largas: Si una entrada tiene una duración >6 segundos y el texto es corto = Whisper incluyó silencio/música de fondo después del habla en el mismo segmento, usar ffmpeg con detección de silencio para ubicar con precisión el punto final del habla, no usar estimaciones de fórmula:
Tomar el primerffmpeg -i <audio> -ss <inicio> -to <fin> -af silencedetect=n=-30dB:d=0.5 -f null - 2>&1 | grep silence_startsilence_start(sumando el desplazamiento de inicio) como el fin recortado; si todo el segmento tiene sonido, no recortar. Si una entrada tiene >8 segundos y texto largo, se puede dividir en varias entradas, distribuyendo las marcas de tiempo de manera razonable dentro del rango original. Prohibido fusionar entradas adyacentes, solo se permite dividir; después de dividir, renumerar secuencialmente; prohibido superposición de marcas de tiempo. - Segmentación y división en párrafos: Principio central: se puede dividir, no se puede fusionar. Una entrada original corresponde a una entrada traducida; si supera 12 caracteres, dividir en dos entradas en puntos de ruptura semánticos (distribuir marcas de tiempo proporcionalmente). Priorizar una sola línea, cada línea ≤12 caracteres chinos (incluyendo espacios e inglés), romper en pausas de tono, no dividir una frase completa en dos entradas. Es preferible dividir en entradas cortas que apilar múltiples líneas en la pantalla.
- Nombres propios: Nombres de personas/lugares/empresas/productos conservar el original (primera letra mayúscula); términos técnicos conservar en inglés (API, GPU, AI, ASR); marcas ampliamente conocidas no traducir (Google, iPhone, YouTube); términos especializados poco comunes pueden incluir una breve explicación en chino la primera vez que aparecen.
- Estilo de lenguaje: Adecuado al uso lingüístico de los jóvenes contemporáneos, traducir jerga de internet/modismos de manera natural y cercana, evitar tono de traducción literal ("esto es muy emocionante" → "esto es realmente genial"). La narración usar lenguaje escrito conciso, el diálogo/letras conservar el tono oral.
- Letras de canciones: Rodear con ♪ (
♪ letra ♪), priorizar la atmósfera y la rima sobre la traducción palabra por palabra; al alternar con la narración, asegurar que el público pueda distinguir.
Formato de salida (SRT estricto)
1
00:00:00,000 --> 00:00:03,500
Este es el contenido del primer subtítulo
2
00:00:03,500 --> 00:00:07,200
Este es el contenido del segundo subtítulo
Los números de secuencia comienzan en 1 y son consecutivos; marcas de tiempo HH:MM:SS,mmm (coma separa milisegundos); texto sin puntuación; espacio entre chino e inglés; línea en blanco entre entradas; línea en blanco al final del archivo.
Modo bilingüe (cuando el usuario seleccionó bilingüe en el paso 0)
Generar "SRT bilingüe": cada entrada dos líneas — chino arriba, inglés (original) abajo, marcas de tiempo completamente alineadas una a una con el SRT original (no re-segmentar, no fusionar; el original corta como sea, el chino lo sigue igual). La línea en chino elimina puntuación y normaliza términos; la línea en inglés conserva el original (solo corregir errores de reconocimiento ASR):
1
00:00:19,239 --> 00:00:21,239
¿Cómo están todos?
Hello everyone, how are you?
Videos largos (>10 minutos): segmentación y paralelización
Cuando hay muchas entradas de subtítulos, segmentar y traducir en paralelo: cada segmento de aproximadamente 500 entradas, el developer ejecuta subtareas en paralelo para traducir, luego fusionar y renumerar. Después de fusionar, verificar globalmente: marcas de tiempo sin superposición ni saltos, números de secuencia consecutivos, coherencia semántica, formato conforme.
⛔ La tubería no se detiene: después de completar el pulido, ejecutar inmediatamente el Paso 4 (quemar), sin generar informes intermedios ni esperar confirmación del usuario. Toda la tubería solo informa una vez cuando todos los productos finales (video + Markdown) están completos.
Paso 4: Incrustar subtítulos (+ marca de agua opcional)
Usar burn.py exclusivamente — no armar comandos ffmpeg manualmente. El script maneja de manera centralizada: escape de rutas de Windows en el filtro (C:\a.srt → 'C\:/a.srt', hacerlo manualmente suele fallar), conversión forzada de audio a AAC (la pista de audio Opus de yt-dlp haría que la subida a X/WeChat/Weibo falle, ⛔ prohibido -c:a copy), análisis de fontfile para marcas de agua y distribución de puntos en el tiempo, y subtítulos+marca de agua en un solo -vf para una sola codificación (evitando pérdida de calidad por segunda codificación).
Chino monolingüe (SRT directo):
python "${SKILL_DIR}/scripts/burn.py" "<archivo de video>" \
--subs "<raíz de salida>/tmp/<nombre de archivo>-zh.srt" \
--output "<raíz de salida>/data/<título del video>-subtítulos-chinos.mp4"
Bilingüe chino-inglés (primero convertir a ASS y luego quemar — ⛔ debe usar ASS):
python "${SKILL_DIR}/scripts/bilingual_ass.py" "<raíz de salida>/tmp/<nombre de archivo>-zh.srt" \
--output "<raíz de salida>/tmp/<nombre de archivo>-zh.ass" [--cn-size N] [--height altura del video]
python "${SKILL_DIR}/scripts/burn.py" "<archivo de video>" \
--subs "<raíz de salida>/tmp/<nombre de archivo>-zh.ass" \
--output "<raíz de salida>/data/<título del video>-subtítulos-chinos.mp4"
- ⛔ Por qué el bilingüe debe usar ASS: El filtro
subtitlescon force_style FontSize se aplica a toda la entrada, no puede tener chino grande e inglés pequeño dentro de una misma entrada; el inline{\fsN}en SRT es eliminado por el decodificador srt de ffmpeg (probado con tres tamaños de letra y todos dieron el mismo md5). Solo el ASS real alimentado a libass puede tener salto de línea\Ny cambio de tamaño inline dentro de una misma entrada.bilingual_ass.pyexiste para esto, no escribir ASS manualmente. - Tamaño de letra: Si el usuario dio explícitamente un tamaño de letra chino en la conversación (ej. "tamaño 24") → pasar
--cn-size 24, el inglés se calcula automáticamente como chino/1.7; si no se da → el script elige el predeterminado según la resolución. La proporción chino:inglés ≈ 1.7 es la relación de contraste limpia probada en la práctica. - ⛔ ASS FontSize/MarginV son valores relativos a PlayResY=288, no píxeles. libass los escala automáticamente según la resolución del video; no aumentar linealmente el tamaño de letra según la resolución (17 en 1080p multiplicado por 2 para 4K ocuparía media pantalla); en 1080p, MarginV=N equivale aproximadamente a N×3.75px desde la parte inferior (MarginV=110 ≈ centro de la pantalla, no 110px), no ajustar por intuición de píxeles.
Marca de agua (desactivada por defecto; activar cuando translate.json tiene settings.watermark_enabled: true o el usuario lo solicita):
python "${SKILL_DIR}/scripts/burn.py" "<archivo de video>" --subs <subtítulos> \
--watermark-text "<texto de la marca de agua>" --output <salida>
Los puntos de tiempo se distribuyen automáticamente según la duración (<30min 3 veces 4s / 30-60min 5 veces 5s / >60min cada 15 minutos una vez 10s; fijo al inicio y final), opacidad 0.28, desvanecimiento de 0.5s, esquina superior izquierda. Se pueden sobrescribir parámetros con --watermark-opacity/--watermark-fontsize; los parámetros especificados en la conversación tienen prioridad sobre los del archivo de configuración.
Evitar superposición con subtítulos duros existentes en la parte inferior del video original: Los nuevos subtítulos deben moverse hacia arriba, sin cubrir los originales:
# Subtítulos duros de una línea
python "${SKILL_DIR}/scripts/burn.py" <video> --subs <subtítulos> --avoid-hardsub single ...
# Dos líneas o dinámicas (una línea en una entrada, dos en otra) → evitar como dos líneas; las entradas de una línea con chino ligeramente más arriba es un costo aceptable
python "${SKILL_DIR}/scripts/burn.py" <video> --subs <subtítulos> --avoid-hardsub double ...
Los niveles de evitación (single=MarginV 42/FontSize 19, double=MarginV 60/FontSize 19) son valores empíricos; si la verificación de capturas de cuadros falla, usar --margin-v para ajustar ±3-5 y volver a quemar.
Si no estás seguro del comando final, primero usar --dry-run para imprimir el comando para revisión antes de ejecutar realmente.
Paso 4.5: Verificación de capturas de cuadros (⛔ Obligatorio, ≥2 cuadros)
Después de quemar, se deben extraer cuadros y usar Read para verificar y confirmar: los subtítulos se muestran completos, no cubren subtítulos duros existentes, la diferencia de tamaño en modo bilingüe es evidente, el chino no aparece como cuadrados (falta de fuente):
ffmpeg -y -i "<video de salida>" -ss <punto de tiempo 1> -vframes 1 "<raíz de salida>/tmp/check1.jpg"
ffmpeg -y -i "<video de salida>" -ss <punto de tiempo 2> -vframes 1 "<raíz de salida>/tmp/check2.jpg"
Cuando hay necesidad de evitar subtítulos duros, los dos cuadros deben seleccionar momentos donde el subtítulo original tenga 1 línea y 2 líneas respectivamente; la verificación se considera aprobada solo si ambos cuadros no muestran superposición. Ver solo un cuadro antes de entregar = error ya cometido. Si hay problemas, ajustar --margin-v/--font-size y volver a quemar y verificar.
Paso 5: Generar documento Markdown
Reglas generales (todos los escenarios):
- Leer el texto transcrito (SRT sin números de secuencia ni marcas de tiempo, o texto limpiado por
vtt_to_text.py), está prohibido añadir, eliminar o modificar el texto original, solo hacer puntuación, fusión de oraciones y segmentación por párrafos. Debe cubrir todo el contenido, sin omisiones. - Contenido en chino: Fusionar oraciones cortas, normalizar puntuación, segmentar por párrafos semánticamente → generar 1 archivo
<raíz de salida>/data/<título del video>-中文.md. ⛔ Está prohibido usar reglas de traducción para contenido en chino. - Contenido que no es en chino: Primero generar
<raíz de salida>/data/<título del video>-原文.mden el idioma original (también sin añadir, eliminar o modificar), luego leerreferences/深度文稿规则.mdy seguir sus reglas para crear<raíz de salida>/data/<título del video>-中文.md(estilo de artículo profundo, no traducción oración por oración). - El front matter solo contiene
title,source_url.
Escenario de solo documento (el usuario solo quiere transcripción/texto, no quemar subtítulos)
- Priorizar la captura de subtítulos si el video los tiene (gratuito y más rápido; ⛔ solo para generar documentos — para quemar subtítulos está prohibida esta ruta, ver regla de hierro del Paso 2):
El texto limpio ahorra aproximadamente la mitad de tokens. Leerpython "${SKILL_DIR}/scripts/download.py" "<URL del video>" "<raíz de salida>/tmp/dl" --captions-only python "${SKILL_DIR}/scripts/vtt_to_text.py" "<raíz de salida>/tmp/dl/<subtítulos>.vtt" --output "<raíz de salida>/tmp/cleaned.txt"cleaned.txty generar documento según el Paso 5. - Sin subtítulos → descargar audio (
--audio) → transcribir contranscribe_srt.py→ SRT sin números de secuencia ni marcas de tiempo para obtener texto limpio → generar documento según el Paso 5.
Archivos temporales y limpieza
- Los productos intermedios (audio, SRT, ASS, capturas de cuadros) están todos en
<raíz de salida>/tmp/; se pueden limpiar después del procesamiento; los productos finales en<raíz de salida>/data/no se ven afectados. - Los SRT de transcripción se pueden conservar para depuración; el usuario puede vaciar tmp/ manualmente en cualquier momento.
Manejo de errores
| Síntoma | Manejo |
|---|---|
| Fallo de descarga (403/control de riesgos/muro de inicio de sesión) | El script ya reintenta automáticamente con cookies; si aún falla, cambiar --browser firefox/edge, o sugerir al usuario configurar un proxy; si es bloqueo regional/contenido de pago, decirlo directamente |
| faster-whisper no instalado | pip install faster-whisper; si no se puede instalar, usar --engine api (requiere clave API) |
| Identificación incorrecta de idioma en la transcripción | Agregar --language en (o el idioma correspondiente) para forzar la retranscripción |
| Los caracteres chinos aparecen como cuadrados después de quemar | Falta de fuente — burn.py elige por plataforma predeterminada (Windows Microsoft YaHei/macOS PingFang/Linux Noto CJK), en Linux se necesita sudo apt install fonts-noto-cjk; también se puede especificar con --font-name |
| Los subtítulos cubren los subtítulos duros originales | Usar `--avoid-hardsub single |
| Espacio en disco insuficiente | Limpiar <raíz de salida>/tmp/ |
| Errores de dependencias | Leer references/安装指南.md y seguir las instrucciones para instalar, luego volver al flujo principal |
Principio de verificación de dependencias: Ejecutar directamente el flujo principal, verificar solo si hay errores — no verificar todas las dependencias por adelantado perdiendo tiempo; se asume que el entorno ya está configurado (la verificación --check del Paso -1 ya cubre los elementos básicos).