YouTube → Documento de Transcripción Pulida
Convierte un video de YouTube (o con subtítulos) en un documento de transcripción legible, con saltos y perdurable para Feishu.
Cadena completa: Leer video → Obtener SRT → Segmentar → Limpiar + Traducir → Generar documento Feishu → (Opcional) Pizarra resumen visual.
Cuándo usarla
Un usuario envía un enlace de video y quiere: transcripción / timeline / resumen tipo acta de reunión / extracción de subtítulos / versión bilingüe / "mira este video y organízamelo".
Flujo
1. Obtener video_id e información básica
Extraer el ID de 11 caracteres de la URL. Si es posible, obtener título, duración, presentador/publicador y registrarlos en el bloque de información del encabezado del documento.
2. Obtener subtítulos (el paso más propenso a errores)
YouTube suele bloquear la descarga directa de subtítulos, no te empeñes. Sigue la cadena de degradación en references/fetch-srt.md:
Webs de subtítulos de terceros (downsub es la mejor opción, usa navegador remoto para abrir → extraer download.subtitle.to para descargar blob → curl directo)
→ Obtener texto de la página mediante navegador → Pedir al usuario que exporte manualmente. Una vez obtenido, guarda el archivo transcript.srt.
3. Segmentar en turnos de habla
python scripts/parse_srt.py transcript.srt --video-id <VIDEO_ID> --out turns.json
Divide por marcadores de hablante >> (sin marcador, vuelve a división por duración fija). Este paso soluciona el problema de "una frase partida en dos" —
antes, la división por segundos fijos cortaba frases por la mitad; ahora cada segmento es una intervención completa. El script también elimina segmentos de solo muletillas.
4. Limpiar + Traducir
Según references/clean-translate.md: eliminar muletillas, tartamudeos repetidos, corregir errores del ASR (nombres, términos, nombres de empresa),
traducir segmento por segmento. Si hay casi cien segmentos, dividir en 2-3 lotes usando subagentes paralelos, compartiendo una tabla de corrección de términos, cada uno genera un JSON {index:{en,zh}}, y se fusiona en un archivo de contenido.
Una vez listo el contenido, construye un content.json según la estructura del encabezado de scripts/build_doc.py (con meta / secciones / highlights / paras / conmutador bilingüe), luego:
python scripts/build_doc.py turns.json content.json --outdir frags/
Genera frags/intro.xml y frags/sec_0.xml … sec_N.xml.
Reglas de formato inamovibles (consolidadas a partir de comentarios de usuarios reales, ya integradas en build_doc.py, no las alteres):
- Títulos sobrios, sin etiquetas como "bilingüe";
- Diferenciar idiomas con colores (inglés gris, chino negro), sin etiquetas EN/ZH;
- No resaltar párrafos enteros; los pasajes destacados solo con ⭐, el resaltado amarillo queda para las tarjetas superiores; el negrita/resaltado de frases cortas se deja para edición manual.
5. Publicar en Feishu
Usa la skill lark-doc (docs +create para crear el documento e insertar intro, luego docs +update --command append para añadir secciones).
Detalles en references/publish-lark.md. Entrega la URL del documento al usuario.
6. (Opcional) Generar pizarra resumen visual
A menudo los usuarios, después de obtener la transcripción, quieren un gráfico visual que resuma lo esencial incrustado en el mismo documento. Usa
el enfoque de beautiful-feishu-whiteboard
para maquetar SVG manualmente (no con diseño automático de Mermaid), generando una pizarra editable en Feishu. Flujo completo y advertencias en
references/whiteboard-summary.md.
La regla más crucial y donde es más fácil fallar: Al renderizar, la pizarra de Feishu fuerza el texto a color oscuro, por lo que
todo el texto debe ir sobre fondo claro (crema/amarillo) con tinta oscura, el color solo para bordes/barritas/marcadores/insignias, nunca pongas texto sobre bloques de color saturado.
La vista previa local PNG del color del texto no es fiable; debes consultar la imagen real en línea con +query --output_as image para confirmar el contraste.
Iteración
Los usuarios suelen dejar comentarios en el documento para que los corrijas. Usa +get-comments de lark-doc para obtenerlos y atenderlos uno por uno.
Si hay errores de segmentación de frases, vuelve al paso 3 y redividelos por turno de hablante; no parchees sobre la segmentación incorrecta.
Recursos
scripts/parse_srt.py— SRT → JSON de segmentos por hablantescripts/build_doc.py— Segmentos + traducción → fragmentos XML para Feishu (formato ya integrado)references/fetch-srt.md— Cadena de degradación para obtener subtítulos (punto clave)references/clean-translate.md— Normas de limpieza, traducción y formatoreferences/publish-lark.md— Crear documento en lark-doc, añadir contenido y obtener comentariosreferences/whiteboard-summary.md— Generar pizarra resumen visual con beautiful-feishu-whiteboard (incluye la advertencia de "texto debe ir sobre fondo claro")