zlej123/stepkeeper

¿Qué hace stepkeeper?

<Propósito> Convertir un vídeo tutorial de YouTube en un documento para seguir paso a paso donde cada instrucción verbal vaga ("tamaño de un bocado", "hasta que la salsa reduzca", "dóblalo aquí") esté respaldada por el fotograma exacto del vídeo que la muestra. Funciona en distintos 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 tutorial y desea una guía limpia y clara con texto e imágenes.
• El usuario se queja de que las instrucciones habladas de un tutorial son ambiguas y desea el fotograma que "muestre" la acción.
• El usuario desea guardar una receta o procedimiento en una aplicación de notas. </Cuándo_Usar>

<Cuándo_No_Usar>

• El vídeo es una conferencia, vlog, reseña o pódcast sin acciones visualmente resolubles.
• El contenido es crítico para la seguridad (médico, electricidad, gas, maquinaria pesada): necesita un perfil revisado por expertos. </Cuándo_No_Usar>

<Cómo_Ejecutar> Un solo comando que ejecuta: analizar → capturar → elegir → renderizar → exportar. --language es el idioma del documento (BCP-47: en, ko, ja, …), no el idioma hablado del vídeo. Los tutoriales en inglés funcionan tanto con salida en como ko.

1. Totalmente automático (sin ffmpeg, enlaces a marcas de tiempo en lugar de capturas de pantalla):

   • Documento en coreano: stepkeeper <URL> --profile generic --language ko --links-only
   • Documento en inglés (para usuarios angloparlantes): stepkeeper <URL> --profile generic --language en --links-only

2. Totalmente automático con capturas de pantalla (Gemini elige el fotograma por guía visual): stepkeeper <URL> --profile recipe --language en --auto-pick --export goodnotes Revisar el picker.html regenerado (la IA elige preseleccionado); si el usuario corrige alguno, ejecutar python -m stepkeeper.feedback add <semantic-evaluation.json> para registrarlo.

3. Selección manual/de agente de fotogramas:

   • stepkeeper <URL> --profile recipe --language en
   • Ruta del agente: leer los tres fotogramas candidatos en work/frames/… directamente, escribir picks.json manualmente (juicio semántico) y luego re-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 guardan en el directorio actual (STEPKEEPER_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 + semántica sobre el corpus de fixtures.
• python tests/batch.py --domain en_output --analyze — prueba de humo de salida en inglés (tests/fixtures/urls.json → en_output, escribe work/analyses/<id>/*.<en>.json).
• Después de la captura, guardar el semantic-evaluation.json del picker como tests/evaluations/<id>.<profile>.en.json para que batch pueda informar la tasa de aciertos de top-3 para en.
• python tests/validate_fixtures.py --online — disponibilidad de URL de fixtures + estratos. </Verificación>

<Límites>

• Solo vídeos públicos; se recomienda ≤ ~30 minutos por coste/tiempo.
• Límites de tarifa de Gemini en el nivel gratuito 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 antes/centro/después. </Límites>