JoeyRedfield/videobook

VideoBook: Convierte un video en un libro electrónico ilustrado

Dado un enlace de YouTube / Bilibili, genera un libro técnico electrónico legible en línea: output/<video_id>/book.md + book.html (con tarjetas de reproductor integradas, capturas ampliables al hacer clic, diagramas Mermaid), opcionalmente transcript.corrected.txt (borrador corregido de subtítulos), y puede publicarse en GitHub Pages para que otros lo lean.

Este skill es la capa de orquestación y es autocontenido: todas las instrucciones que el agente necesita están dentro de este directorio (SKILL.md + references/), y no depende de instructions.md / README.md del repositorio (esos archivos están orientados a humanos y deben permanecer intactos, no los mantiene este skill). La única dependencia externa es el código ejecutable del pipeline src/*.py: los comandos y parámetros siempre se rigen por --help de cada script, no reescribas la lógica de los scripts. Los datos volátiles (por ejemplo, el mapa de palabras incorrectas en src/make_corrected.py) no deben copiarse en el skill, solo escribe las reglas y apunta al archivo fuente; la única excepción son las instrucciones de maquetación del paso 2, de las que este directorio tiene una copia local (references/stitcher-prompt.md, pero la versión del repositorio tiene prioridad).

Requisitos previos (lectura obligatoria para la primera ejecución)

1. Directorio de trabajo = raíz del repositorio videobook (criterio: existen src/dump_transcript.py y prompts/), todas las rutas relativas (output/<video_id>/...) se resuelven respecto a él. Si el repositorio no está en local, primero git clone https://github.com/Luke-Evan/videobook.git en el directorio donde el usuario almacena sus proyectos de código (no uses un directorio temporal, ni crees un nuevo directorio projects), luego cd.
2. Python >= 3.10 (recomendado 3.12). Instala dependencias: uv sync (con uv) o pip install -r requirements.txt. Ejecuta siempre con el intérprete del entorno del repositorio: uv run python src/xxx.py o .venv/Scripts/python.exe src/xxx.py.
3. Inicio de sesión único: python src/capture_frames.py --setup-profile abre un Chrome dedicado (directorio de datos .capture-profile/), inicia sesión en Bilibili / YouTube, cierra la ventana; el estado de inicio de sesión se reutiliza a largo plazo. El nivel de membresía de la cuenta = límite de resolución de las capturas.
4. Videos en el extranjero: proxy en la terminal (para capturar subtítulos), proxy global en el navegador (de lo contrario, el iframe de YouTube en la página generada se verá como un bloque negro).
5. Los comandos que requieren privilegios elevados o están fuera del sandbox se indican en la última columna de la tabla general; los pasos puramente locales se pueden ejecutar dentro del sandbox.

Resumen del pipeline

Paso	Qué hace	Comando	Detalles	Privilegios
1	Extraer subtítulos	python src/dump_transcript.py "<URL>"	references/transcript.md	Requiere Bilibili
1b	Respaldo ASR local si la plataforma no tiene subtítulos	python src/asr_transcript.py <video_id>	references/transcript.md	No (consume tiempo)
1.5	Materiales oficiales del curso + diapositivas 4K (se ejecuta por defecto, se omite solo si el curso no tiene página principal)	python src/course_assets.py <video_id> --course-url <URL de página del curso>	references/course-assets.md	Requiere renderizado
2	El LLM reescribe los subtítulos en book.md	Según las instrucciones de maquetación (references/stitcher-prompt.md; si existe prompts/stitcher_system.md en el repositorio, se usa esa versión)	references/writing.md	No
2b	Borrador corregido de subtítulos (opcional)	python src/make_corrected.py <video_id>	references/correction.md	No
3	Capturar fotogramas y materializar los marcadores de posición en imágenes	python src/capture_frames.py <video_id> "<URL>"	references/capture.md	Sí
4	Renderizar HTML + iniciar vista previa local	python src/post_process.py "<URL>" output/<id>/book.md luego python -m http.server 8080 --directory output/<id>	—	No
5	Informar al usuario del resultado, preguntar sobre limpieza de archivos grandes	—	Ver sección «Entrega» abajo	—
6	Publicar el resultado en la rama pages (opcional)	python src/publish.py <video_id> luego git push origin pages	references/publish.md	No (push requiere red)

Si hay errores, problemas de calidad de imagen, subtítulos no capturados, interrupción de ASR, consulta primero references/troubleshooting.md.

Reglas estrictas (no negociables)

1. Si la cobertura de subtítulos es < 50% (código de salida 3), no se puede pasar al paso 2: primero arregla el estado de inicio de sesión/proxy, o recurre al ASR de respaldo.
2. Las capturas de pantalla deben obtenerse del reproductor de la plataforma en el navegador autenticado: en el paso 3, está prohibido descargar archivos de video/audio de cualquier forma (ffmpeg para extraer fotogramas es solo el último recurso). La lista de métodos prohibidos está en references/capture.md.
3. Las cookies solo se escriben en el directorio temporal del sistema y se eliminan después de su uso: nunca se guardan en el repositorio ni se coloca manualmente un archivo cookies.txt en el espacio de trabajo.
4. output/ no se ve afectado por ninguna operación de git: el resultado final solo se publica en la rama huérfana pages; main solo contiene código.
5. Fidelidad del borrador corregido: conserva las palabras originales del instructor y el orden párrafo por párrafo; solo se reemplazan palabras mal transcritas por ASR + se eliminan muletillas; prohibido eliminar párrafos, fusionar líneas o hacer reescrituras extensas (la capa de validación lo rechazará directamente).
6. Límite de fidelidad al escribir el libro: la formalización no equivale a resumir; conserva analogías, casos de estudio y cadenas de razonamiento; las adiciones del editor deben etiquetarse como «Nota del editor».
7. Derechos de autor de los materiales del curso: los apuntes y diapositivas pertenecen al instructor (normalmente CC BY-NC); el bloque de información al inicio del libro y al final deben incluir el enlace de atribución, el nombre del autor y la licencia.
8. Regla estricta de cobertura de diapositivas: cada página de slides_text.md debe aparecer exactamente una vez en el libro; antes de la entrega, --audit debe pasar obligatoriamente.
9. Eliminar archivos grandes (audio.m4a, video_source.mp4, etc.) solo después de preguntar al usuario: una vez confirmado, se eliminan.
10. Al generar o modificar HTML, el contraste entre el texto y el fondo no debe ser inferior a 4.5:1 (WCAG AA).
11. Cada paso es idempotente y puede reejecutarse: el script hace una copia de seguridad automática book.tagged.md antes de materializar los marcadores de posición; si aún existe, se puede reejecutar el paso 3 para restaurar las capturas.

Entrega (el paso 5 debe decir todo de una vez)

1. Ubicación de output/<video_id>/book.md;
2. Dirección de vista previa http://localhost:8080/book.html; para cerrar el servidor, presiona Ctrl+C en la terminal;
3. Los videos de YouTube requieren que el navegador pueda acceder a YouTube (proxy); los videos de Bilibili se pueden ver directamente;
4. La resolución de las capturas depende del nivel de membresía de la cuenta iniciada en .capture-profile/; para obtener mayor resolución, cambia de cuenta, inicia sesión y reejecuta el paso 3;
5. Si se utilizaron materiales oficiales del curso, indica en el libro que las ilustraciones de las diapositivas son imágenes 4K oficiales renderizadas (se indica la fuente y la licencia CC al inicio del libro); los fotogramas de demostración siguen siendo fotogramas del video; el directorio course/ se puede eliminar por completo sin afectar la lectura;
6. Pregunta si se deben eliminar los archivos multimedia grandes generados durante el proceso (regla estricta 9).

Contenido de este directorio (leer según sea necesario, no leer todo de una vez)

Archivo	Cuándo leerlo
references/transcript.md	Paso 1: capturar subtítulos; si la plataforma no tiene subtítulos, pasar a ASR local
references/writing.md	Paso 2: reescribir los subtítulos en book.md
references/stitcher-prompt.md	Instrucciones de maquetación del paso 2 (si existe prompts/stitcher_system.md en el repositorio, se usa la versión del repositorio)
references/course-assets.md	Paso 1.5 cuando el curso tiene página oficial; reglas de diapositivas, actualización a 4K
references/correction.md	Generar borrador corregido de subtítulos y propuestas de corrección a nivel de línea con IA
references/capture.md	Paso 3: capturar fotogramas; prioridades, métodos explícitamente prohibidos, hábitos de QA
references/publish.md	Paso 6: publicar en la rama pages
references/troubleshooting.md	Cualquier error, anomalía de calidad de imagen, subtítulos no capturados, denegación de privilegios

Convenciones de mantenimiento

• Este skill está versionado en el mismo repositorio que el código del pipeline: si se cambian los parámetros de src/*.py, el orden de los pasos o las reglas estrictas, este directorio debe actualizarse de forma sincronizada.
• instructions.md y README.md del repositorio están orientados a humanos; deben permanecer intactos y no son mantenidos por este skill; no los modifiques para que el skill funcione; si el contenido se superpone con este directorio, el agente usa este directorio como referencia.
• Al sincronizar references/stitcher-prompt.md, actualiza el número de commit en la nota de origen al principio del archivo.
• Instalación por terceros: skill-installer usa --repo Luke-Evan/videobook --path skills/videobook; o después de clonar, copia/enlaza simbólicamente este directorio a ~/.codex/skills/ (solo Codex) o ~/.agents/skills/ (multigente).
• Este directorio no contiene cookies, estados de inicio de sesión, productos de output/ ni archivos multimedia; se puede distribuir públicamente de forma segura.