swei99386-alt/video-to-text-skill

Convierte el "habla" de vídeos/audio en texto. Aquí hay un flujo fijo con lecciones aprendidas a base de errores; síguelo estrictamente y no te saltes el paso 0 por tu cuenta.

Regla de hierro (esta es la más importante, recuérdala primero)

Siempre busca primero los "subtítulos ya existentes", y solo si no los hay, recurre a la "transcripción por voz". La gran mayoría de charlas formales, conferencias y podcasts se suben a YouTube, y YouTube casi siempre tiene subtítulos integrados — con un solo comando los obtienes en segundos, gratis, sin descargar el vídeo completo y sin consumir GPU.

Hoy mismo caí en no seguir este atajo: descargué tontamente un vídeo de 450 MB, ejecuté la transcripción por CPU durante media hora y además obtuve un texto lleno de errores. Esta trampa no debe repetirse.

Paso 0: Al obtener un enlace, primero distingue dos cosas, luego decide el orden

Convertir a texto (obtener la transcripción de lo que se dice) y averiguar el origen (quién lo dijo, cuándo se grabó originalmente, si es la versión completa) son dos tareas diferentes, no las mezcles. La versión antigua que "al ver X, correr a YouTube" es incorrecta — X también suele tener sus propios subtítulos, así que esa ida a YouTube es en vano.

Convertir a texto: Siempre explora primero el enlace actual, no asumas que debes ir a YouTube.

1. Ejecuta directamente grab.py — el script primero intenta obtener los subtítulos del propio enlace (X suele tener subtítulos en inglés/español, etc.). Si los encuentra, termina; este es el camino más rápido.
2. Solo vale la pena ir a YouTube a buscar la versión original en estos dos casos:
   • El enlace de X no tiene subtítulos (probablemente YouTube sí los tenga).
   • El enlace de X es un clip editado — el texto habla de un vídeo más largo, pero el clip de X solo dura un par de minutos (obtendrías solo un fragmento; si necesitas el vídeo completo, busca la versión original). Método: Busca "orador + tema/título + nombre del evento" para encontrar la versión original en YouTube y luego úsala en el paso 1.

La duración es el revelador: Primero ejecuta yt-dlp --no-download --print "%(duration_string)s" para verla. Si el clip de X dura aproximadamente lo que dice el texto (por ejemplo, dice "28 minutos" y dura 27 minutos) = es una copia completa; procésalo directamente. Si es mucho más corto = es un clip editado; hay que buscar la versión original.

Averiguar el origen (quién/cuándo/se trata de la versión completa) es otra tarea, solo se hace si el usuario lo pide explícitamente, no es un paso obligatorio para la conversión a texto. Y sé suficiente: obtén la información que responda la pregunta del usuario, no persigas precisiones como la fecha exacta o la versión oficial que el usuario no ha solicitado (experiencia del 2026-07-22, donde se perdió tiempo en esto).

Paso 1: Ejecuta el script con un solo comando (él decide si usar subtítulos o transcripción por voz)

python "C:/Users/Administrator/.claude/skills/视频转文字/scripts/grab.py" "<enlace o archivo local>" "nombre de la carpeta de salida" [idioma]

El tercer parámetro [idioma] es opcional: para vídeos en chino usa zh (forzará salida en chino simplificado), para inglés usa en, si no se especifica, se detecta automáticamente. Lógica interna del script (ya fijada en el código):

• Primero busca subtítulos existentes → si los encuentra, genera 完整文字稿.txt en segundos, terminado.
• Si no encuentra subtítulos → entonces extrae el audio automáticamente y usa la GPU para la transcripción por voz (no la CPU).
• Los resultados se guardan en el escritorio dentro de la carpeta <nombre de carpeta de salida>: 完整文字稿.txt (texto limpio) + archivos de subtítulos originales.

Al terminar, informa al usuario la ubicación de 完整文字稿.txt y el número de palabras.

Bilibili / Sitios nacionales (diferente de YouTube, apunta esto por separado)

• Se puede descargar: La herramienta de descarga soporta Bilibili (B站) y varios sitios nacionales; la extracción de vídeo/audio funciona.
• Pero "obtener subtítulos ya existentes" como atajo gratuito no es confiable: Bilibili no tiene subtítulos automáticos para todos los vídeos como YouTube; solo unos pocos creadores suben subtítulos CC. Los danmaku (bullet comments) no son subtítulos (son comentarios del público que flotan, no el diálogo), no intentes extraerlos.
• Por lo tanto, la mayoría de los vídeos de Bilibili van directamente a "transcripción por voz con GPU". Para vídeos en chino, recuerda pasar zh como tercer parámetro:

  python ".../grab.py" "<enlace de Bilibili>" "nombre de la carpeta de salida" zh
  

• Advertencia de precisión en chino: Actualmente se usa el modelo pequeño (small), que para chino solo da "una aproximación" y propenso a errores de caracteres. Para mayor precisión, se necesita el modelo mediano (medium, ~1.5 GB, descarga única, aún no instalado). El usuario el 2026-07-21 optó por "usar el pequeño por ahora"; si se necesita más precisión, instala el modelo medium y cambia --model small a medium en el script.
• Inicio de sesión: Para vídeos exclusivos para miembros de Bilibili, en alta definición o que requieran inicio de sesión, la descarga necesita las cookies de la cuenta. Pregunta primero al usuario, no accedas a la cuenta por tu cuenta.

Vídeos cuyo enlace no se puede capturar (WeChat Video / páginas encriptadas de pago / cualquier contenido que solo se pueda reproducir en pantalla) → Graba el audio de la pantalla

La herramienta de descarga no puede alcanzar este tipo de vídeos (WeChat Video está encerrado en la aplicación, las páginas de pago están encriptadas). La única solución universal: reproducir y grabar el audio que está sonando en el ordenador, y luego convertirlo a texto. Este equipo ya tiene capacidad de grabación interna (librería soundcard, sin necesidad de controladores ni configuración).

Tres pasos:

1. Inicia la grabación (se ejecuta en segundo plano, graba hasta que la detengas):

   python "C:/Users/Administrator/.claude/skills/视频转文字/scripts/record.py" "nombre de la carpeta de salida"
   

2. Reproduce el vídeo de principio a fin (grabación en tiempo real; un vídeo de 3 horas requerirá 3 horas de grabación, no se puede acelerar).
3. Detén el proceso de grabación (detener una tarea en segundo plano del agente es un corte forzado, no importa), y luego pasa directamente el archivo 录音.pcm a grab.py para la transcripción (reconoce PCM, para chino añade zh):

   python "C:/Users/Administrator/.claude/skills/视频转文字/scripts/grab.py" "<ruta del escritorio>/<carpeta>/录音.pcm" "<carpeta>" zh
   

• La grabación se escribe en disco mientras se realiza; si se interrumpe a la fuerza, no se pierde todo el fragmento (el PCM siempre está ahí, no depende de ningún paso de "finalización").
• Si puedes obtener el enlace, no uses la grabación: la descarga toma minutos, mientras que la grabación requiere esperar el tiempo real completo. La grabación de pantalla solo se usa para aquellos que realmente no se pueden capturar mediante enlace.

Paso 2: Solo debes preocuparte por lo siguiente cuando se usa transcripción por voz

• Debe usar la GPU: Esta máquina tiene una NVIDIA GTX 1060 (5 GB de VRAM), el script la usará automáticamente si está disponible. Si algún día los registros muestran "CPU", significa que la versión de torch con soporte CUDA ha sido reemplazada por la versión solo CPU; sigue la sección [Base de GPU] más abajo para repararlo.
• Si la duración es muy larga (>20 minutos), es normal que tarde; pero con GPU debería ser cuestión de minutos; si parece que va a tardar media hora, seguro que está usando CPU.
• La transcripción por voz inevitablemente tiene errores de caracteres o palabras omitidas; es "una aproximación", no tan precisa como los subtítulos nativos. Si puedes obtener subtítulos, no uses la transcripción por voz.

Base de GPU (la transcripción por voz depende de esto; si falla, repáralo así)

El requisito para usar la GPU en la transcripción por voz es tener instalada la versión de torch con soporte CUDA. Autodiagnóstico:

C:/Users/Administrator/portable-python311/runtime/python.exe -c "import torch;print(torch.__version__, torch.cuda.is_available())"

• Si muestra ...+cu126 True = todo correcto, GPU disponible.
• Si muestra ...+cpu False = se ha vuelto a usar solo CPU; reinstala:

C:/Users/Administrator/portable-python311/runtime/python.exe -m pip install --force-reinstall torch==2.11.0 --index-url https://download.pytorch.org/whl/cu126

(driver CUDA 12.6 → usa la fuente cu126. Esta GPU de 5 GB es suficiente para reconocimiento de voz, OCR y modelos medianos; no puede ejecutar modelos grandes que requieran 8 GB de VRAM o más.)

Comandos manuales comunes (fuera del script, para consulta)

• Ver qué idiomas de subtítulos están disponibles: yt-dlp --no-download --list-subs "<url>"
• Descargar solo subtítulos en inglés sin el vídeo: yt-dlp --skip-download --write-auto-subs --sub-langs "en-orig,en.*" --convert-subs srt -o "%(title)s.%(ext)s" "<url>"
• Verificar duración/fecha de publicación: yt-dlp --no-download --print "%(title)s | %(duration_string)s | %(upload_date)s" "<url>"