grabación-a-obsidian

¿Qué hace grabación-a-obsidian?

Convierte una reunión o una clase en una parte autónoma y completamente enlazada de una bóveda de Obsidian. Ambos modos comparten el pipeline, las convenciones y el paso de verificación; se diferencian en lo que extraen y en cómo se estructuran las notas.

	Modo reunión	Modo clase
Propósito	recordar lo que se decidió y quién hace qué y cuándo	reaprender las ideas rápidamente en cualquier momento
Centro	un centro de reunión por sesión + un MOC de serie con una entrada por reunión	un MOC por clase
Notas principales	registros de decisiones estilo ADR; notas de temas para conocimiento duradero	notas ancla (densas) + notas atómicas (una idea cada una)
Trazabilidad	marcas de tiempo de la transcripción [00:12:34] en decisiones y elementos de acción	enlaces a diapositivas PDF++ [[deck.pdf#page=5]]; marcas de tiempo para contenido solo hablado
Referencia	references/meeting-mode.md	references/lecture-mode.md

<skill> a continuación se refiere a la carpeta donde se encuentra este archivo.

1. Pipeline

materiales ──► 1 configuración ──► 2 transcripción ──► 3 elegir modo ──► 4 escritor de notas ──► 5 verificar ──► 6 informe
             config,      scripts/          reunión o      escribe notas     check_vault
             python       transcribe.py     clase          (un subagente)    scan_secrets

1.1 Configuración

Primero anota la hora de inicio: ejecuta date +%s y guarda el número; la verificación solo comprueba las notas escritas después de esa hora.

Lee <skill>/config.toml. Establece el backend/modelo/idioma de transcripción, la diarización, notes.output_language, notes.default_mode y los nombres de las carpetas de la bóveda (notes_dir, moc_dir, meetings_dir, sources_dir; se usan los valores predeterminados a continuación). El intérprete para los scripts es runtime.python; si está vacío, usa ~/.local/share/recording-to-obsidian/venv/bin/python. Llámalo $PY — esto es notación: en los comandos escribe las rutas literales completas del intérprete y los scripts, un comando por llamada, sin variables de shell ni cadenas cd … && (las reglas del agente coinciden con el comando literal, y las variables lo hacen imposible de verificar). Si no existe, dile al usuario que ejecute install.sh (README) — no hagas pip-install en los entornos Python del usuario.

Establece los hechos antes que cualquier otra cosa (pregunta solo por lo que no puedas inferir):

• bóveda — la ruta del usuario, o el directorio de trabajo actual si contiene .obsidian/ o el usuario dijo "esta bóveda"; escribe solo dentro de ella;
• materiales — rutas absolutas de cada archivo; clasifica cada uno por extensión: audio/video, subtítulos (.srt/.vtt), diapositivas (.pdf/.pptx), cuadernos/código, imágenes/fotos, documentos;
• título, serie/curso, fecha — del usuario, de los nombres de archivo o de los materiales; nunca inventes una fecha o lista de asistentes (escribe PENDIENTE y dilo);
• idioma de salida — notes.output_language a menos que el usuario haya solicitado uno.

1.2 Transcripción

Para cada grabación sin un archivo de subtítulos coincidente (misma raíz), ejecuta:

$PY <skill>/scripts/transcribe.py <grabación> -o <scratch>/transcripts

• <scratch> es una carpeta temporal fuera de la bóveda (ej. $TMPDIR/recording-to-obsidian-<fecha>-<slug>), utilizada para todos los archivos intermedios.
• Opciones cuando sea necesario: --model small (más rápido, menos preciso), --language en (omitir detección), --diarize (etiquetas de hablante; necesita install.sh --diarize y un token de Hugging Face en la variable de entorno nombrada por diarize.hf_token_env). La primera ejecución descarga el modelo, lo que puede llevar minutos; imprime el progreso en stderr — déjalo terminar.
• Escribe <raíz>.srt y <raíz>.txt (una línea [HH:MM:SS] Hablante N: texto por segmento) e imprime una línea de resumen JSON (idioma, modelo, duración, hablantes, estadísticas de limpieza, rutas de archivos). Conserva ese resumen: el idioma, el modelo y la diarización van a la sección Fuente de las notas.
• Los subtítulos existentes de cualquier herramienta se pueden normalizar de la misma manera: $PY <skill>/scripts/transcribe.py charla.vtt -o <scratch>/transcripts (no implica modelo; los bucles de repetición se pliegan y se escribe un .txt con marcas de tiempo).
• Las grabaciones largas están bien: el script maneja horas de audio; no dividas el archivo.

Si la transcripción falla, informa la línea de error; $PY <skill>/scripts/transcribe.py --check muestra lo que falta.

1.3 Elegir el modo

Un modo explícito del usuario (o notes.default_mode distinto de auto) gana. De lo contrario:

1. Diapositivas, cuadernos, código de laboratorio o folletos entre los materiales → clase.
2. De lo contrario, lee los primeros ~5 minutos de la transcripción y hojea el resto:

Señales de reunión	Señales de clase
varios hablantes con tiempo de intervención comparable	un hablante dominante explicando
agenda, actualizaciones de estado, "¿en qué estamos con…"	"hoy cubriremos…", "la semana pasada vimos…"
propuestas, compensaciones debatidas, "vamos con…", "de acuerdo"	definiciones, derivaciones, ejemplos resueltos, ejercicios
propietarios y fechas: "¿puedes encargarte de eso para el viernes?"	preguntas de la audiencia para entender, no para decidir
proyectos, clientes, plazos, riesgos	numeración de curso/clase, lecturas, tareas

3. Los casos mixtos se deciden por el propósito: las revisiones de diseño, planificación, retrospectivas, informes y reuniones 1:1 son reuniones; las charlas técnicas grabadas, capacitaciones, seminarios y tutoriales son clases, incluso si hay algo de discusión.

Registra la elección y las dos o tres señales que la motivaron (van en el informe). Si es un verdadero empate y puedes preguntar, pregunta; de lo contrario, elige y di por qué.

1.4 Modelo de ejecución: orquestador + un escritor de notas

Leer una transcripción completa, una presentación página por página y cuadernos, y luego escribir decenas de archivos llena la ventana de contexto rápidamente, así que divide los roles:

• Orquestador — la sesión que recibió la solicitud. Hace 1.1–1.3 (la salida de la transcripción permanece en el disco; solo lee lo suficiente de la transcripción para elegir el modo), entrega la escritura a un subagente escritor de notas, luego ejecuta la verificación en 1.5 e informa.
• Escritor de notas — un subagente que realiza todo el trabajo de escritura para el modo elegido en su propio contexto: leer cada material, planificar, escribir, autoverificar. Una reunión o una clase cabe cómodamente en un contexto; no dividas páginas o fragmentos de transcripción entre agentes (eso pierde referencias cruzadas y duplica notas).

Haz el trabajo tú mismo en lugar de delegar cuando no haya una herramienta de subagente disponible, cuando un subagente no pueda hacer lo que el trabajo necesita (ver imágenes, ejecutar scripts, escribir archivos). En modo reunión también puedes escribir directamente cuando la reunión sea lo suficientemente corta como para que el resumen sea tan largo como el trabajo (una grabación de menos de ~15 minutos sin diapositivas ni documentos). El modo clase siempre usa el escritor de notas a menos que un subagente no esté disponible o no pueda hacer el trabajo: una presentación debe leerse página por página, y eso pertenece al contexto del escritor, no al tuyo. Di cuál elegiste en el informe. La verificación (1.5) nunca se omite. Para varias sesiones, usa un escritor de notas por sesión, secuencialmente cuando añaden al mismo MOC.

Resumen para el escritor de notas — comienza sin contexto, así que dale todo:

• la ruta absoluta de este skill; el modo; los archivos a seguir: references/meeting-mode.md o references/lecture-mode.md, además de references/note-templates.md, references/transcript-processing.md, references/mermaid-style.md;
• ruta de la bóveda, carpeta temporal, $PY, idioma de salida, título/serie/fecha (o "derivar"), nombres de carpeta de la configuración;
• rutas absolutas de cada material y de los archivos de transcripción, con el resumen de transcripción (idioma, modelo, hablantes);
• el MOC de la serie/curso existente y el centro/MOC de la sesión anterior si los hay; cualquier cosa que el usuario haya solicitado específicamente;
• reglas: escribir solo dentro de la bóveda; nunca modificar notas preexistentes excepto las adiciones documentadas; sin secretos;
• qué devolver: el bloque de informe de la Sección 3 más cualquier cosa que no haya podido resolver.

1.5 Verificar (orquestador)

Cuando el escritor de notas regrese, verifica su trabajo de forma independiente en lugar de confiar en su resumen:

$PY <skill>/scripts/check_vault.py <bóveda> --since <segundos epoch cuando comenzó el trabajo>
$PY <skill>/scripts/scan_secrets.py <bóveda>/sources

check_vault.py debe terminar con issues: 0; corrige también las advertencias a menos que haya una razón para no hacerlo (di cuál). Resuelve los enlaces como lo hace Obsidian (nombre de archivo o ruta parcial, sin distinción entre mayúsculas y minúsculas, ignorando #heading/|alias, saltándose bloques de código), por lo que un enlace roto que informa está roto en Obsidian. Comprueba: [[enlaces]] rotos/inserciones/enlaces Markdown, enlaces PDF++ sin .pdf, frontmatter (title, type, date_created), cobertura del centro (cada nota nueva está enlazada desde un MOC o centro de reunión; cada centro de reunión desde un MOC), secretos; advertencias para notas sin conexiones, Mermaid sin estilo y enlaces ambiguos.

Luego verifica lo que los scripts no pueden:

• ninguna nota preexistente cambió excepto las adiciones documentadas (entrada del MOC de la serie, estado de decisión reemplazado, enlace "siguiente" del MOC de la clase anterior);
• modo reunión: cada decisión tiene un registro o es explícitamente menor; cada elemento de acción tiene un propietario (o PENDIENTE), una fecha límite (o PENDIENTE) y una marca de tiempo;
• modo clase: el MOC enumera cada nota nueva exactamente una vez; se cumplen la granularidad y los objetivos de anclaje de la autoverificación de la clase.

Corrige los problemas pequeños directamente; envía los más grandes de vuelta al escritor de notas con la lista exacta. Vuelve a ejecutar check_vault.py hasta que informe 0 problemas. Elimina la carpeta temporal (contiene el wav y las imágenes de página) a menos que el usuario la quiera.

2. Convenciones compartidas

Diseño de la bóveda — las notas son planas; la navegación proviene de los MOC y centros, no de las carpetas.

bóveda/
├── notes/                         # notas atómicas, ancla, de decisión y de tema (planas)
├── meetings/<serie>/             # centros de reunión: "AAAA-MM-DD <título>.md"
├── moc/<serie o curso>/        # MOC de serie (reuniones) / un MOC por clase
└── sources/<serie o curso>/<AAAA-MM-DD o Clase_NN>/
    ├── <prefijo>_transcript.srt / .txt
    ├── <prefijo>.pdf               # diapositivas, para enlaces PDF++
    ├── slide_images/  whiteboard_photos/  notebooks/
    └── structured_slides.json     # registro de lectura opcional por página

Dale a cada archivo copiado en sources/ un prefijo de serie/curso + sesión (Atlas_2026-11-12_transcript.srt, Optics101_L03.pdf, Optics101_L03_p08.jpg): Obsidian resuelve los enlaces por nombre de archivo, por lo que dos sesiones que contengan transcript.srt o page-08.jpg se vincularían de forma cruzada. Los nombres de carpeta usan el nombre de la serie/curso con espacios reemplazados por -.

Nombres de archivo — el título legible por humanos, sin ID (los centros de reunión son la excepción: comienzan con la fecha para que se ordenen). Evita / \ : * ? " < > | # ^ [ ]; escribe — en lugar de :. Los títulos son lo suficientemente específicos para ser autónomos: Rate limits use a token bucket per API key.md, no Rate limiting.md.

Frontmatter — cada nota comienza con frontmatter YAML con al menos title, type y date_created. type es moc, meeting, decision o topic (modo reunión) y moc, anchor o atomic (modo clase). Los campos específicos del modo están en references/note-templates.md. Las etiquetas (tags) están en minúsculas en inglés con kebab-case: una etiqueta de serie/curso, 2–4 etiquetas de tema, una etiqueta de tipo; reutiliza etiquetas que ya estén en la bóveda antes de inventar nuevas.

Idioma — output_language = "auto" significa: escribe en el idioma de los materiales (el idioma detectado de la transcripción, o el de las diapositivas). Cuando el idioma de salida difiere del idioma de los materiales, mantén los términos técnicos en el idioma original y glosa cada uno en la primera aparición — notas en chino de una reunión en inglés: 功能开关 (feature flag); notas en inglés de una clase en alemán: error propagation (Fehlerfortpflanzung) — luego usa la forma que sea más natural de leer. El código, los comandos, las rutas, los nombres de productos y herramientas nunca se traducen. Los encabezados siguen el idioma de salida.

Enlaces — cada [[wikilink]] debe resolverse a una nota o archivo en la bóveda. Enlaza a una nota existente en lugar de escribir un duplicado. Usa una ruta ([[sources/Atlas/2026-11-12/Atlas_2026-11-12_transcript.srt|transcript]]) cuando un nombre simple podría ser ambiguo. Los enlaces a páginas PDF++ siempre mantienen .pdf: [[Optics101_L03.pdf#page=5|Diapositiva p.5 "Ley de Snell"]].

Marcas de tiempo — cita [HH:MM:SS] de la transcripción para cada decisión, elemento de acción y afirmación que provenga solo del habla. Son la pista de auditoría de regreso a la grabación.

Secretos — nunca escribas credenciales en la bóveda. Antes de copiar cuadernos o código en sources/, ejecuta $PY <skill>/scripts/scan_secrets.py --redact <copia> en la copia (los valores se convierten en <REDACTED>, los nombres de las variables permanecen). Las contraseñas dichas en voz alta, números de tarjeta o datos personales sensibles en una reunión tampoco se registran en las actas — escribe "las credenciales se compartieron verbalmente (no registradas aquí)".

Visuales — lee references/mermaid-style.md antes de escribir cualquier diagrama Mermaid: tiene la paleta y las reglas que mantienen los diagramas renderizables. Una sintaxis inválida es peor que ningún diagrama.

Salidas del modo

• Reunión → references/meeting-mode.md: 1 centro, 1 registro de decisión por decisión significativa, 0–N notas de tema para conocimiento que valga la pena conservar, una entrada añadida al MOC de la serie (creado en el primer uso), transcripción copiada a sources/.
• Clase → references/lecture-mode.md: 1 MOC, 8–15 notas ancla para una presentación normal de 30+ páginas, en promedio al menos una nota atómica por diapositiva de contenido, diapositivas/cuadernos/transcripción copiados a sources/.

3. Informe

Modo reunión:

Reunión 2026-11-12 — <título>  (serie: <serie>)   modo: reunión (señales: …)
  Transcripción: 00:41:07, mlx:whisper-large-v3-turbo, 3 hablantes, en → notas es
  Centro: meetings/<serie>/2026-11-12 <título>.md
  Decisiones: 3 (registros: 3)   Elementos de acción: 7 (propietario PENDIENTE: 1, fecha PENDIENTE: 2)
  Notas de tema: 2   Preguntas abiertas: 2   Riesgos: 1
  MOC de serie: moc/<serie>/MOC — <serie>.md (entrada añadida)
  check_vault: issues 0, warnings 0
  No resuelto: <hablantes no coincidentes con nombres, pasajes poco claros, …>

Modo clase:

Clase NN — <tema>   modo: clase (señales: …)
  Diapositivas: 45 páginas (contenido 37)    Puntos de conocimiento: 68
  Notas: 56 atómicas + 12 ancla     arquetipos: concepto=34, práctica-demostración=6, …
  Notas por diapositiva de contenido: 1.5     Anclas con ≥2 elementos ricos: 12/12
  Mermaid: 14 (tipos: secuencia, mapa mental, diagrama de flujo, diagrama de clase, diagrama de Gantt)
  check_vault: issues 0, warnings 0
  No resuelto: <diapositivas sin notas, huecos, …>

Cada informe va al usuario como una respuesta directa (no dentro de un archivo). Los elementos de acción tienen un enlace a su nota de decisión/registro; los enlaces rotos conocidos se enumeran en "No resuelto".