AutoCliper.AI — Habilidad para Agentes
Convierte un video largo de YouTube en 5 a 15 clips cortos con empaquetado en chino y subtítulos quemados.
Este documento es la única fuente de verdad para cualquier agente de IA que ejecute el pipeline de AutoCliper. Sigue cada paso numerado en orden. No omitas pasos. No adivines nombres de archivos: inspecciona el sistema de archivos después de cada operación de escritura.
0. Verificaciones Prevuelo
Antes de hacer cualquier otra cosa, verifica el entorno. Reporta el bloqueador exacto y detente si alguna verificación falla.
| Verificación | Comando | Condición de Éxito |
|---|---|---|
| yt-dlp instalado | which yt-dlp | devuelve una ruta |
| ffmpeg instalado | which ffmpeg | devuelve una ruta; si falta, prueba python3 -c "import imageio_ffmpeg; print(imageio_ffmpeg.get_ffmpeg_exe())" |
| Python 3.9+ | python3 --version | >= 3.9 |
| Repositorio de la habilidad disponible | verifica que el directorio corekit/ exista en relación a la raíz de la habilidad | corekit/__init__.py está presente |
Configura el entorno para todos los comandos subsiguientes:
export PYTHONPATH="<ruta-al-repositorio-AutoCliper.AI>"
Todos los comandos python3 -m corekit.* a continuación asumen que este PYTHONPATH está configurado.
1. Crear Espacio de Trabajo
Crea la estructura de directorios de salida para este video. Deriva <slug> del título o ID del video: minúsculas, guiones, sin espacios, sin caracteres especiales.
mkdir -p "studio/<slug>/intake"
mkdir -p "studio/<slug>/intel"
mkdir -p "studio/<slug>/exports"
Resultado esperado:
studio/<slug>/
├── intake/ ← aquí llegan el video y subtítulos sin procesar
├── intel/ ← aquí llegan los artefactos de análisis
└── exports/ ← aquí llegan las carpetas por clip
2. Obtener Activos Fuente
Descarga el video y los subtítulos de YouTube:
python3 -m corekit.fetch_source "<URL_de_YouTube>" "studio/<slug>/intake"
Qué sucede internamente: el descargador intenta primero los subtítulos en inglés (en, en-US, en-orig), y recurre al chino (zh-Hans, zh-CN, zh). Usa --cookies-from-browser chrome para acceso autenticado.
Después de que el comando termine, lista la carpeta intake e identifica:
- El archivo de video
.mp4(puede contener el título del video y el ID en el nombre) - El archivo de subtítulos
.srt(puede tener una etiqueta de idioma como.en.srto.zh-Hans.srt) - Cualquier archivo adicional (
.ytdl,.jpg, etc.) — anótalos pero no son necesarios
Si la descarga falla:
- Error de cookies → dile al usuario que actualice su inicio de sesión de Chrome en YouTube, luego reintenta
- No se encontraron subtítulos → reporta "no hay subtítulos disponibles para este video" y detente
- Error de descarga de video → reintenta una vez con un formato diferente; si aún falla, reporta el error
Registra los nombres de archivo exactos para los siguientes pasos. No adivines ni uses nombres fijos.
3. Analizar Subtítulos a JSON
Convierte el archivo de subtítulos SRT a JSON estructurado para un análisis más fácil:
python3 -m corekit.subtitle_to_json \
"studio/<slug>/intake/<nombre-exacto-del-srt>" \
"studio/<slug>/intel/transcript.json"
Verifica que el archivo de salida exista y contenga un array de objetos de referencia. Cada objeto tiene:
{
"index": 1,
"start": "00:00:01,234",
"end": "00:00:03,456",
"start_seconds": 1.234,
"end_seconds": 3.456,
"text": "el contenido hablado"
}
Si la transcripción está vacía o tiene menos de 10 referencias, reporta "transcripción demasiado corta o corrupta" y detente.
4. Analizar Transcripción y Proponer Candidatos
Este es el paso intelectual más importante. Lee los siguientes archivos antes de comenzar el análisis:
- playbooks/clip-contract.md — define el esquema JSON exacto para
selected_clips.json - playbooks/content-analysis-playbook.md — define el método de análisis de múltiples pasadas, la rúbrica de puntuación y el formato de revisión
4a. Análisis de Múltiples Pasadas
NO intentes seleccionar clips en una sola pasada. Sigue esta secuencia:
Pasada 1 — Hojea y marca: Lee transcript.json buscando secciones que contengan contenido memorable, denso en información, con opiniones, contraintuitivo o emocionalmente afilado. Marca generosamente: es mejor marcar demasiados que muy pocos.
Pasada 2 — Refinamiento de límites: Para cada sección marcada, vuelve a leer las referencias circundantes (5–10 referencias antes y después). Elige un inicio y final limpios:
- El inicio debe caer en una línea que enganche al espectador dentro de los primeros 3 segundos del clip
- El final debe caer después de que el hablante haya terminado la idea — nunca a mitad de una oración
- Si un momento prometedor necesita unos segundos de contexto, extiende el inicio hacia atrás
- Si un pensamiento se desvanece, extiende el final hasta que se resuelva
Pasada 3 — Verificación de integridad: Para cada candidato, verifica:
- Tiene una duración de 20 a 180 segundos (puede llegar a 3 minutos si la recompensa lo justifica)
- Contiene exactamente una idea clara
- La línea de apertura es un gancho, no un relleno
- La línea de cierre resuelve la idea
- Se entiende sin ver el resto del video
- NO es un saludo, lectura de patrocinador, preámbulo de preguntas y respuestas, o una digresión larga
Pasada 4 — Puntúa y clasifica: Puntúa cada candidato en cuatro dimensiones (1–5):
hook— qué tan convincente es la apertura en los primeros 3 segundosclarity— si es una idea limpia con baja ambigüedadstandalone— si puede mantenerse por sí solo sin contexto previopayoff— si el final es útil, memorable o digno de compartir
Clasifica por total ponderado: hook × 0.35 + clarity × 0.25 + standalone × 0.2 + payoff × 0.2
4b. Guía de Cantidad de Candidatos
| Duración de la Fuente | Candidatos Objetivo |
|---|---|
| < 20 min | 5 – 8 |
| 20 – 60 min | 8 – 12 |
| > 60 min | 10 – 15 |
El modo de fallo predeterminado debe ser "demasiados pocos candidatos", no "demasiados". Ante la duda, incluye más. El usuario los podará.
4c. Manejo de Subtítulos Generados Automáticamente (Ruidosos)
Los subtítulos automáticos de YouTube a menudo contienen:
- Fragmentos repetidos (la misma frase aparece en referencias consecutivas)
- Signos de puntuación y mayúsculas faltantes
- Palabras malinterpretadas (especialmente nombres, términos técnicos)
Cuando los subtítulos de origen son generados automáticamente:
- Infiere el significado previsto de manera conservadora — no inventes afirmaciones
- Ignora fragmentos duplicados al juzgar los límites del clip
- Usa el contexto circundante para determinar dónde terminan realmente las oraciones
- Anota en el resumen del candidato si la calidad de la fuente es baja
4d. Escribir Salidas
Escribe dos archivos:
-
studio/<slug>/intel/selected_clips.json— las decisiones de clip legibles por máquina. Debe seguir el esquema enplaybooks/clip-contract.mdexactamente. -
studio/<slug>/intel/candidate-board.md— la tabla de revisión legible por humanos.
5. Presentar Candidatos para Revisión del Usuario
Muestra la lista de candidatos en un formato amigable para revisión. Para cada candidato, muestra:
| Campo | Formato | Ejemplo |
|---|---|---|
| ID | clip-XX | clip-01 |
| Rango de tiempo | HH:MM:SS → HH:MM:SS | 00:12:03 → 00:13:22 |
| Duración | legible por humanos | 1m 19s |
| Título | un título chino provocador, ≤12 caracteres | AI终将取代一切? |
| Resumen | exactamente dos oraciones en chino | 句1: En qué consiste. 句2: Por qué vale la pena verlo. |
Preséntalo como una tabla numerada para que el usuario pueda responder con los IDs.
Si el usuario dice "proceder" o "selección automática": selecciona tú mismo los candidatos mejor clasificados. Para un video de 1 hora, exporta al menos 8.
Si el usuario elige IDs específicos: exporta solo esos.
6. Exportar Cada Clip Elegido
Para cada clip que el usuario eligió (o que seleccionaste automáticamente), ejecuta los pasos 6a a 6f en orden. Completa todos los subpasos de un clip antes de pasar al siguiente.
6a. Cortar el Segmento de Video
python3 -m corekit.cut_video \
"studio/<slug>/intake/<nombre-exacto-del-mp4>" \
<start_seconds> <end_seconds> \
"studio/<slug>/exports/<carpeta-del-clip>/clip.mp4"
La convención de nombres de <carpeta-del-clip> es XX-<slug-del-titulo>, por ejemplo, 01-ai-will-replace.
Verifica que el archivo de salida exista y tenga un tamaño distinto de cero.
6b. Ventanear el Subtítulo Fuente
python3 -m corekit.window_subtitles \
"studio/<slug>/intake/<nombre-exacto-del-srt>" \
<start_seconds> <end_seconds> \
"studio/<slug>/exports/<carpeta-del-clip>/clip.src.srt"
Esto extrae solo las referencias que se superponen con la ventana del clip y desplaza todas las marcas de tiempo para que el clip comience en 00:00:00,000.
Verifica que el SRT de salida tenga al menos una referencia.
6c. Traducir a Subtítulo en Chino
Lee clip.src.srt y tradúcelo a chino simplificado. Escribe el resultado en clip.zh.srt en la misma carpeta.
Reglas de traducción (sigue estrictamente):
- Chino hablado natural — no chino escrito/formal. El espectador está viendo un video corto, no leyendo un documento.
- Preserva las marcas de tiempo exactamente — a menos que necesites fusionar dos referencias para mayor legibilidad. Nunca cambies la sincronización arbitrariamente.
- Mantén las entidades nombradas precisas — los nombres de personas, empresas, productos, números y frases entrecomilladas deben conservarse fielmente.
- Líneas concisas — prefiere frases cortas en chino que se adapten al ritmo de un video corto. Los subtítulos largos y desplazables matan la retención.
- Reequilibra entre referencias cuando sea necesario — si una oración en inglés está dividida en 3 referencias, puedes redistribuir el texto en chino en esas mismas 3 referencias. Preserva el orden de las referencias.
- NO colapses referencias — un SRT en inglés denso en referencias con 40 referencias debe producir aproximadamente 35–45 referencias en chino, no 10. El modo de fallo predeterminado es ligeramente demasiadas referencias, no demasiado pocas.
- Elimina solo los duplicados reales — los subtítulos automáticos a menudo repiten el mismo fragmento en referencias consecutivas. Puedes eliminar el duplicado, pero conserva la primera aparición.
- Si la fuente ya está en chino — no traduzcas. Solo limpia el ruido obvio de los subtítulos automáticos (fragmentos repetidos, caracteres rotos).
6d. Generar Título y Descripción
Para cada clip, crea:
Título (para la superposición del primer segundo):
- Afilado, cliqueable, con opinión
- Objetivo ≤ 12 caracteres chinos para que quepa limpiamente en pantalla con un tamaño de fuente 48
- Puede ser provocador o contraintuitivo, pero debe ser fiel al significado del hablante
- Debe crear curiosidad, tensión o una urgencia por seguir viendo
Descripción (para distribución en la plataforma):
- ≤ 140 caracteres chinos
- Debe mencionar: quién habla, de qué programa/entrevista proviene, qué tema se discute, cuál es la afirmación o conclusión clave
Escribe ambos en studio/<slug>/exports/<carpeta-del-clip>/metadata.txt:
标题:AI终将取代一切?
描述:Sam Altman 在 Lex Fridman 播客中谈到 AGI 的时间表——他认为大多数人严重低估了 AI 的发展速度,未来三年将改变一切。
6e. Quemar Subtítulos en Chino + Título en el Video
python3 -m corekit.render_hardsubs \
"studio/<slug>/exports/<carpeta-del-clip>/clip.mp4" \
"studio/<slug>/exports/<carpeta-del-clip>/clip.zh.srt" \
"studio/<slug>/exports/<carpeta-del-clip>/clip.hardsub.mp4" \
--title "<el-titulo-de-6d>"
CRÍTICO: Pasa el archivo chino clip.zh.srt, NO clip.src.srt. Este es el error más común del agente: pasar el subtítulo en el idioma de origen en lugar de la traducción.
El paso de quemado:
- Detecta automáticamente libass; si no está disponible, recurre al renderizado drawtext (no requiere acción de tu parte)
- Selecciona automáticamente el mejor codificador H.264 para la máquina actual
- Renderiza el título centrado con tamaño de fuente 48 y un contorno negro de 3px durante el primer segundo
- Renderiza las referencias de subtítulos en la parte inferior del fotograma durante el resto del clip
Verifica que el archivo de salida clip.hardsub.mp4 exista y tenga un tamaño de archivo mayor que clip.mp4 (la cadena de filtros agrega datos visuales).
6f. Anexar a la Copia de Empaquetado
Después de que cada clip sea exportado, agrega su título y descripción al archivo de empaquetado combinado:
studio/<slug>/intel/packaging-copy.md
Formato:
## clip-01: AI终将取代一切?
**标题**: AI终将取代一切?
**描述**: Sam Altman 在 Lex Fridman 播客中谈到 AGI 的时间表...
**文件**: studio/<slug>/exports/01-ai-will-replace/clip.hardsub.mp4
**时长**: 1m 19s
---
7. Salida Final
Después de que todos los clips sean exportados, devuelve al usuario:
- Carpeta de activos fuente:
studio/<slug>/intake/ - Lista de candidatos: la tabla completa del paso 5 (marcas de tiempo, duración, título, resumen)
- Archivo de empaquetado:
studio/<slug>/intel/packaging-copy.md - Clips exportados: lista cada ruta de
clip.hardsub.mp4
Referencia de Estructura del Espacio de Trabajo
studio/<video-slug>/
├── intake/ # activos sin procesar de YouTube
│ ├── <título> [<id>].mp4 # video fuente (nombre de archivo de yt-dlp)
│ └── <título> [<id>].<lang>.srt # subtítulo fuente
├── intel/ # artefactos de análisis
│ ├── transcript.json # referencias de subtítulos estructuradas (del paso 3)
│ ├── selected_clips.json # decisiones de clip (del paso 4)
│ ├── candidate-board.md # tabla de revisión (del paso 4)
│ └── packaging-copy.md # todos los títulos + descripciones (del paso 6f)
└── exports/ # una carpeta por clip exportado
└── 01-<slug>/
├── clip.mp4 # corte sin procesar (sin subtítulos)
├── clip.src.srt # subtítulo en idioma de origen ventaneado
├── clip.zh.srt # subtítulo traducido al chino
├── clip.hardsub.mp4 # entrega final (subtítulos + título quemados)
└── metadata.txt # título + descripción para este clip
Referencia de Módulos
| Módulo | Invocación | Argumentos |
|---|---|---|
corekit.fetch_source | python3 -m corekit.fetch_source <url> <dir_salida> | URL de YouTube, directorio de salida |
corekit.subtitle_to_json | python3 -m corekit.subtitle_to_json <entrada.srt> <salida.json> | Ruta del archivo SRT, ruta de salida JSON |
corekit.cut_video | python3 -m corekit.cut_video <entrada.mp4> <inicio_seg> <fin_seg> <salida.mp4> | video fuente, inicio en segundos (float), fin en segundos (float), ruta de salida |
corekit.window_subtitles | python3 -m corekit.window_subtitles <entrada.srt> <inicio_seg> <fin_seg> <salida.srt> | SRT fuente, inicio en segundos (float), fin en segundos (float), ruta de salida |
corekit.render_hardsubs | python3 -m corekit.render_hardsubs <entrada.mp4> <entrada.srt> <salida.mp4> --title "..." | video del clip, SRT en chino, ruta de salida, texto de título opcional |