egitim-videosu

Productor de Videos Educativos

Documento → mapa de cobertura → plan → guion → prueba de cobertura → storyboard → locución → video → control → entrega. No requiere GPU ni APIs de pago. Código: https://github.com/alpay-web/egitim-videosu

0. Preparación

Versión: cat $R/VERSION (cambios en CHANGELOG.md). En cada push, se ejecuta el trabajo Test (pruebas unitarias + video corto); si está en rojo, corrígelo primero. Los errores de guion (tipo incorrecto, desbordamiento de goster, fuera de cevap_cumle) se detectan antes del renderizado en cada comando.

Cuando realices una mejora permanente al paquete: actualiza VERSION y CHANGELOG.md, haz push y ejecuta el trabajo surum.yml.

[ -d /tmp/egitim-videosu ] || git clone --depth 1 https://github.com/alpay-web/egitim-videosu /tmp/egitim-videosu
R=/tmp/egitim-videosu
pip install -q -r $R/requirements.txt 2>/dev/null || pip install -q --break-system-packages -r $R/requirements.txt

1. Comprender el documento → mapa de cobertura

python $R/scripts/belge_oku.py belge.pdf -o belge.md     # PDF/Word/PowerPoint/Excel/HTML/EPUB → belge.md + belge_harita.md

Orden del lector: markitdown (MIT) → pandoc → pdftotext. belge_harita.md proporciona el recuento de palabras por título, el número de tablas y sugerencias de escena; advierte sobre PDFs escaneados (muy poco texto por página) — en ese caso solicita OCR, no inventes.

Enlaces de Claude Doc / artifact: lee con herramientas de docs, guarda el texto como .md y ejecuta el mismo comando.

Cada línea del mapa se asigna a una escena o se anota como "omitido: razón". Velocidad de habla ≈ 130 palabras/min; duración estimada de narración = palabras de contenido ÷ 130 × 0.6 (margen de resumen).

2. Plan y aprobación (antes de pasos costosos)

• Predeterminado: TODO EL DOCUMENTO EN UN SOLO VIDEO (el usuario lo prefiere). En un documento largo puede durar 30–40 minutos; se navega con marcas de capítulo de YouTube. Orden: gancho + hoja de ruta → estrategia → lecciones temáticas (cada lección: escena de regla + pregunta "Pruébate") → vocabulario → ejemplos de lectura/audición/conversación → simulacro → cierre. No se leen todos los ejercicios; se eligen 1–2 preguntas representativas de cada bloque, el resto se menciona como "ejercicios en la guía".
• Serie (videos de 5–8 min) solo si el usuario lo solicita. Las locuciones anteriores se reutilizan automáticamente (ver "Caché de voz" más abajo).
• Presenta al usuario un plan breve (capítulos, duración estimada, tipos de escena) y muestra que ningún título se omite sin aviso. No pases a la locución sin aprobación (si el usuario dijo "continúa", avanza directamente).

3. Escribir el guion → senaryo.json (ejemplo: $R/ornek/senaryo_b1.json)

Arte del guion (obligatorio):

• Abre con gancho (primeros 5 s): un hecho sorprendente, riesgo o pregunta; agrega "kanca": "frase impactante corta" a la primera escena — se muestra grande en la pizarra hasta que aparezca el primer elemento (la pizarra nunca queda vacía). APERTURAS PROHIBIDAS: "Hola, en este video…", "Hoy aprenderemos…". Gancho → por qué es importante → hoja de ruta.
• Estructura: gancho → configuración (por qué debería importarte) → desarrollo → clímax (momento "ajá") → cierre (resumen de una oración + llamado a la acción). Transición entre escenas con "por eso / pero", no "y luego".
• Presupuesto de palabras: ~130 palabras/min; 50–110 palabras por escena. Oraciones cortas, trato de "tú", lenguaje hablado.
• Cada 8–10 s un evento visual: nuevo elemento/línea/tarjeta/paso o pregunta.
• Rendimiento de voz: agrega a la escena "ton": "merakli" (curioso, para introducción), "canli" (animado, para tácticas), "ciddi" (serio, para advertencias), "sakin" (tranquilo, para cierre). Después de una oración importante, agrega [dur] (silencio de 0.9 s). Las oraciones interrogativas/exclamativas se alargan automáticamente.
• Fidelidad: solo la información del documento; no inventes números/reglas.

Tipos de escena — elige según la forma del contenido (no uses el mismo tipo 3 veces seguidas):

{"baslik": "...", "maddeler": ["≤40 caracteres", "..."], "anlatim": "...", "goster": [0, 2, 3]}
{"baslik": "...", "tur": "tablo", "tablo": {"basliklar": ["Ves", "Respuesta"], "satirlar": [["since", "have + V3"]], "stil": "yanlis-dogru"}}
{"baslik": "...", "tur": "rakam", "kartlar": [{"deger": "30", "birim": "minutos", "etiket": "Duración del examen"}]}
{"baslik": "...", "tur": "karsilastirma", "sol": {"baslik": "En audición", "renk": "mavi"}, "sag": {"baslik": "En lectura", "renk": "yesil"}, "satirlar": [["izquierda", "derecha"]]}
{"baslik": "...", "tur": "zaman", "adimlar": [{"baslik": "Día 1", "metin": "Gramática"}]}
{"baslik": "...", "tur": "ipucu", "ipucu": {"tip": "ipucu|uyari|not", "metin": "Mensaje único impactante"}}
{"baslik": "Pruébate 1/3", "tur": "soru", "soru": {"metin": "Yes, ___.", "secenekler": ["I'm", "I am", "I do"], "dogru": 1, "cevap_cumle": 2, "bekle": 4}}

• maddeler: lista/resumen. tablo: tablas del documento, "ves → respuesta", listas de verdadero/falso. rakam: 1–3 números impactantes (duración, puntuación, cantidad). karsilastirma: dos lados (primero se abre la columna izquierda, luego la derecha; goster = filas izquierdas + filas derechas respectivamente). zaman: pasos/plan/proceso (vertical para ≥4 pasos). ipucu: mensaje único impactante. soru: de los ejercicios; LEE EN VOZ ALTA la pregunta y las opciones ("{El museo} espacio {en 1890}. Opciones: A, {construido}; B, {fue construido}; C, {ha construido}."), cevap_cumle = índice de la oración "Respuesta correcta…"; antes cuenta regresiva, luego la opción correcta en verde + "ding".
• TODO LO QUE SE ESCRIBE EN PANTALLA SE LEE (obligatorio): ambas columnas de la tabla, ambos lados de la comparación, la etiqueta de la tarjeta numérica, la pregunta y las opciones deben aparecer en la narración. Dedica una oración separada a cada elemento (ritmo de elemento). Si --kontrol advierte "no se lee", corrige la narración. Escritura de goster: el video abre cada elemento en la oración que lo lee, mientras se dice esa palabra (oto_goster); entre dos elementos consecutivos hay al menos 1,2 s.
• Inglés entre {llaves} (obligatorio): "{had better}", "{I'm late, aren't I?}". Dentro de las llaves se genera en inglés (en) en Chatterbox, fuera en turco; la misma voz de referencia y niveles igualados (Chatterbox no puede cambiar de idioma en una sola llamada: resemble-ai/chatterbox#346). No agregues sufijos turcos a palabras en inglés ("{had better}'dan" no, sino "la estructura {had better}"). Para marcar automáticamente el borrador, usa --ingilizce-isaretle (wordfreq), luego revisa: palabras turcas como "not", "on" pueden marcarse incorrectamente; agrega manualmente frases cortas como "{at}", "{I am}".
• goster: en qué oración (desde 0) se abre cada elemento; en ese momento el puntero se desliza al elemento (si se da --tik, se reproduce un ligero clic). Sincronización de palabras (predeterminado): el elemento no se abre al inicio de la oración, sino cuando se dice la primera palabra significativa del elemento (si existe SS_CC.json con tiempos de palabra de Whisper, exacto al segundo; si no, según su posición en la oración). Anclaje manual: "3:enough" (en la palabra "enough" de la 3.ª oración) o 2.5 (mitad de la 2.ª oración). Para desactivar: --kelime-senkron-yok.
• La pantalla va por delante de la voz (regla de video explicativo): que la voz no comience en una pizarra vacía; que no haya más de 14 s sin algo nuevo en la pizarra. Si el primer elemento llega tarde, el video muestra la primera oración como texto de introducción grande en la pizarra (proporciona el texto con el campo "giris"; para desactivar: --giris-yok).
• bolum: en la escena que inicia un capítulo, escribe "bolum": "Gramática 5: Passive". Aparece en la parte inferior de la pizarra, cae una línea de capítulo en la barra de progreso y se genera automáticamente la lista de capítulos de YouTube. También agrega youtube_baslik (≤100 caracteres) y etiketler al guion.
• telaffuz: escribe nombres de abreviaturas/niveles con letras turcas ("B1": "be bir", "C1": "se bir", "IELTS": "ay elts", "A": "a", "B": "be"). NO escribas pronunciación para palabras en inglés, usa {…}. telaffuz_kok: {"fiil": "fiyil"}. Escribe "seçenek" en lugar de "şık" (que Chatterbox pronuncia mal).

4. Prueba de cobertura (idea de PresentQuiz)

A partir de la fuente, extrae 8–10 preguntas críticas de las secciones cubiertas por el video (solo basadas en el documento). Marca una por una si la respuesta a cada una aparece en el guion. Si hay algún tema crítico sin respuesta, agrégalo al guion o declara explícitamente en la entrega que lo omitiste conscientemente.

5. Storyboard + control (puerta de aprobación)

python $R/scripts/video_uret.py senaryo.json --kontrol [--ses-dizini sesler]  # informe de uniformidad + DISEÑO + SINCRONIZACIÓN
python $R/scripts/video_uret.py senaryo.json --storyboard storyboard.png  # estado final de cada escena, imagen única

Informes de --kontrol: diseño (texto desbordado/cortado, letra menor de 30 px, opciones/tarjetas que no caben) y sincronización (aire muerto: la voz comenzó pero la pizarra está vacía; pantalla estática: sin nuevo elemento durante 14 s+). Después de generar la voz, vuelve a ejecutar con --ses-dizini para duraciones reales. No dejes advertencias de diseño. Mira el storyboard: desbordamiento, superposición, pizarra vacía, tipo incorrecto. Corrige, muestra al usuario, obtén aprobación.

6. Locución (Chatterbox, MIT) — --kalite 3 con puerta Whisper que verifica cada oración

A) GitHub Actions (rápido, paralelo; requiere acceso de escritura al repositorio): haz commit del guion como senaryolar/<ad>.json, luego:

curl -X POST -H "Accept: application/vnd.github+json" -H "Content-Type: application/json" \
  https://api.github.com/repos/alpay-web/egitim-videosu/actions/workflows/ses_uret.yml/dispatches \
  -d '{"ref":"main","inputs":{"senaryo":"senaryolar/<ad>.json","etiket":"ses-<ad>","parcalar":"[\"1-3\",\"4-6\",\"7-9\",\"10-12\",\"13-15\"]"}}'
curl -fsSL -o sesler.zip https://github.com/alpay-web/egitim-videosu/releases/download/ses-<ad>/sesler.zip && unzip -q sesler.zip -d sesler

Caché de voz (direccionado por contenido, idea de manim-voiceover): cada carpeta de voz mantiene un dizin.json con el mapeo oración → resumen del texto. Agregar/eliminar/cambiar el orden de las escenas no invalida las voces antiguas; si el texto de una oración cambia, nunca se reproduce con la voz antigua. Flujo:

python $R/scripts/video_uret.py senaryo.json --eksik --ses-dizini eski1,eski2   # ¿qué oraciones faltan? devuelve partes + --cumleler

Proporciona la entrada "taban":"ses-b1-tam-kurs,ses-<ad>" al workflow: si el mismo texto existe en esos releases, se copia; solo se sintetizan las oraciones nuevas/cambiadas. En el render se pueden proporcionar varias carpetas: --ses-dizini sesler,eski_sesler. Para etiquetar una carpeta antigua (sin dizin.json): --dizin-olustur KLASOR (si estás seguro de que la carpeta pertenece a este guion). Borrador: para control de tiempos/visuales sin esperar la locución, genera un video borrador en 720p con --ses sessiz. B) En este entorno (lento, ~10 min por 1 min de video): python $R/scripts/video_uret.py senaryo.json --sadece-ses sesler --ses chatterbox --kalite 3 (ejecutar en segundo plano). En kalite_raporu.txt, para las oraciones con puntuación < 0.8, corrige la pronunciación y regenérelas solo con --cumleler 04_05,06_07.

7. Video

python $R/scripts/video_uret.py senaryo.json -o video.mp4 --ses-dizini sesler     # 1080p + video_kapak.jpg

Predeterminado: profesor de dibujo sencillo (en el atril), cámara lenta, puntero, "ding" solo en respuesta correcta, sin música. Audio limpio (sin roce de micrófono/clics): los clips de oraciones se combinan con fundidos suaves de entrada/salida; la cadena incluye adeclick, afftdn (reducción ligera de ruido) y deesser; el efecto de "clic" sobre la voz está desactivado por defecto. Ruido (solución general, en capas): (1) el trabajo de locución limpia cada oración con DeepFilterNet3 (scripts/ses_temizle.py, supresión máxima de 30 dB; para voces antiguas, ses_temizle.yml), (2) klip_temizle corta colas de inicio/fin de oración y regiones de respiración largas, (3) la cadena de render suprime el residuo entre palabras con agate. Limpieza de respiración/susurro (predeterminado): Chatterbox a veces agrega una cola de respiración/roce de baja amplitud y aguda (4–7 kHz) de 0.5–2 s al final de algunas oraciones; klip_temizle corta las colas no sonoras por debajo de 24 dB del pico de voz, y reduce en 24 dB las respiraciones de ≥150 ms dentro de la oración. Sonidos como "s/ş" al final se conservan porque son más fuertes. Para desactivar: --temizleme-yok. Sincronización de labios: la boca del profesor de dibujo no solo se abre y cierra; se elige una forma entre 'a' (abierta), 'o' (redondeada) e 'i' (ancha, dientes visibles) para cada fotograma según las bandas de formantes del audio. No requiere modelo y no afecta el tiempo de render. (Caras parlantes realistas como SadTalker/Wav2Lip/LivePortrait requieren GPU y ralentizan mucho la producción). Opciones: --tik, --muzik, --efekt-yok, --kamera-yok, --altyazi-yok, --karakter yol.json (personaje fotográfico), --sahne 2-3 --cozunurluk 720 (prueba rápida).

8. Control (obligatorio antes de la entrega, máximo 2 rondas de corrección)

python $R/scripts/kalite_raporu.py video.mp4      # duración, LUFS/pico, silencio, fotogramas negros/congelados + tabla de fotogramas

Revisa la tabla de fotogramas. Escribe los hallazgos con seriedad (críticos / sugerencias) y para cada uno propón una corrección concreta ("Encabezados de tabla de la escena 6 superpuestos → acortar encabezados"); no escribas hallazgos vagos como "podría ser un poco largo". Puntúa la tabla de fotogramas con 5 criterios de TheoremExplainAgent en escala 1–5: precisión (¿es fiel al documento?), interés visual (¿la pizarra muestra lo que se explica?), flujo (¿los temas están en orden lógico?), diseño (¿hay desbordamiento/superposición?), consistencia (¿mismo color, fuente, estilo?). Realiza correcciones concretas para cada criterio por debajo de 4. Corrige los críticos, regenera; después de 2 rondas, declara explícitamente los restantes en la entrega.

9. Entrega

El video también escribe el paquete de publicación en cada render: video.srt (subtítulos de YouTube; ≤2 líneas × 42 caracteres) y video_youtube.txt (título, descripción con capítulos, etiquetas, nota de IA). Envía MP4 + portada + .srt + youtube.txt; menciona la duración, el número de escenas y las secciones cubiertas. Recuerda que el SRT se cargará en YouTube Studio > Subtítulos y que se marcará la casilla "contenido modificado/generado por IA".