clipnote

¿Qué hace clipnote?

<Propósito> Convierte un video instructivo de YouTube en un documento que se puede seguir paso a paso, donde cada instrucción verbal vaga ("del tamaño de un bocado", "hasta que la salsa se reduzca", "dobla aquí") se respalda con el fotograma exacto del video que la muestra. Funciona en múltiples dominios (cocina, bricolaje/reparación, manualidades, belleza, fitness, tutoriales de software) mediante perfiles intercambiables. La salida es un documento portátil que se exporta a Notion, Obsidian o Goodnotes. </Propósito>

<Cuándo_Usar>

• El usuario comparte una URL de YouTube de un instructivo y desea una guía limpia y legible en texto e imágenes.
• El usuario se queja de que las instrucciones habladas de un tutorial son ambiguas y quiere el fotograma "que me muestre cómo".
• El usuario quiere guardar una receta o procedimiento en una aplicación de notas. </Cuándo_Usar>

<Cuándo_No_Usar>

• El video es una charla, vlog, reseña o podcast sin acciones visualmente resolubles.
• El contenido es crítico para la seguridad (médico, electricidad de red, gas, maquinaria pesada) — necesita un perfil revisado por expertos. </Cuándo_No_Usar>

<Requisitos_Previos>

• El repositorio clipnote en disco. Si no está presente, clónelo primero: git clone https://github.com/zlej123/clipnote y ejecute todos los comandos desde ese directorio.
• Variable de entorno GEMINI_API_KEY (clave de Google AI Studio). Si falta, solicite una al usuario (gratis en https://aistudio.google.com/apikey) — nunca continúe sin ella.
• ffmpeg en PATH (captura de fotogramas; no es necesario para --links-only).
• pip install -e . desde el repositorio (instala dependencias y el comando clipnote). </Requisitos_Previos>

<Cómo_Ejecutar> Un solo comando impulsa analizar → capturar → elegir → renderizar → exportar.

1. Totalmente automático (sin ffmpeg, enlaces de marca de tiempo en lugar de capturas de pantalla): clipnote <URL> --profile generic --language es --links-only

2. Totalmente automático con capturas de pantalla (Gemini elige el fotograma por guía): clipnote <URL> --profile recipe --language es --auto-pick --export goodnotes Revise el picker.html regenerado (IA elige previamente); si el usuario corrige alguna, ejecute python -m clipnote.feedback add <semantic-evaluation.json> para registrarla.

3. Selección manual/agente de fotogramas:

   • clipnote <URL> --profile recipe --language es
   • Ruta del agente: lea los tres fotogramas candidatos bajo work/frames/… directamente, escriba picks.json usted mismo (juicio semántico), luego vuelva a ejecutar con --picks <picks.json> --export goodnotes (o obsidian/bundle/notion).

La exportación a Notion necesita NOTION_TOKEN y --parent <page-id>. Los artefactos se colocan en el directorio actual (CLIPNOTE_DATA lo sobrescribe). </Cómo_Ejecutar>

<Verificación>

• python -m unittest discover -s tests — pruebas unitarias de contrato/normalización/selección/exportación.
• python tests/batch.py — regresión estructural y semántica sobre el corpus de fixtures.
• python tests/validate_fixtures.py --online — disponibilidad de URL de fixtures + estratos. </Verificación>

<Límites>

• Solo videos públicos; ≤ ~30 min recomendado por costo/tiempo.
• Límites de tarifa de Gemini en la capa gratuita bajo carga por lotes; el modelo predeterminado es gemini-flash-lite-latest.
• La precisión de la marca de tiempo de ±2-3 s se cubre con los candidatos anterior/centro/posterior. </Límites>