recording-to-obsidian

O que recording-to-obsidian faz?

Transforme uma reunião ou uma aula em uma parte autocontida e totalmente interligada de um vault do Obsidian. Ambos os modos compartilham o pipeline, as convenções e a etapa de verificação; eles diferem no que extraem e em como as notas são formatadas.

	Modo Reunião	Modo Aula
Propósito	lembrar o que foi decidido e quem faz o quê até quando	reaprender as ideias rapidamente a qualquer momento
Hub	um hub de reunião por sessão + um MOC de série com uma entrada por reunião	um MOC por aula
Notas principais	registros de decisão estilo ADR; notas de tópicos para conhecimento duradouro	notas-âncora (densas) + notas atômicas (uma ideia cada)
Rastreabilidade	timestamps da transcrição [00:12:34] em decisões e itens de ação	links para slides PDF++ [[deck.pdf#page=5]]; timestamps para conteúdo apenas falado
Referência	references/meeting-mode.md	references/lecture-mode.md

<skill> abaixo significa a pasta onde este arquivo está.

1. Pipeline

materiais ──► 1 configuração ──► 2 transcrever ──► 3 escolher modo ──► 4 escritor de notas ──► 5 verificar ──► 6 relatório
             config,      scripts/          reunião ou      escreve notas     check_vault
             python       transcribe.py     aula            (um subagente)   scan_secrets

1.1 Configuração

Anote o horário de início primeiro: execute date +%s e guarde o número; a verificação checa apenas notas escritas após ele.

Leia <skill>/config.toml. Ele define o backend/modelo/idioma da transcrição, diarização, notes.output_language, notes.default_mode e os nomes das pastas do vault (notes_dir, moc_dir, meetings_dir, sources_dir; os padrões são usados abaixo). O interpretador para os scripts é runtime.python; se estiver vazio, use ~/.local/share/recording-to-obsidian/venv/bin/python. Chame-o de $PY — isso é notação: nos comandos, escreva os caminhos completos literais do interpretador e dos scripts, um comando por chamada, sem variáveis de shell ou cadeias cd … && (as regras de permissão do agente correspondem ao comando literal, e variáveis o tornam impossível de verificar). Se não existir, diga ao usuário para executar install.sh (README) — não faça pip-install nos ambientes Python do usuário.

Estabeleça os fatos antes de qualquer outra coisa (pergunte apenas pelo que não puder inferir):

• vault — o caminho do usuário, ou o diretório de trabalho atual se contiver .obsidian/ ou se o usuário disse "este vault"; escreva apenas dentro dele;
• materiais — caminhos absolutos de cada arquivo; classifique cada um por extensão: áudio/vídeo, legendas (.srt/.vtt), slides (.pdf/.pptx), cadernos/código, imagens/fotos, documentos;
• título, série/curso, data — do usuário, nomes de arquivos ou dos materiais; nunca invente uma data ou lista de participantes (escreva TBD e avise);
• idioma de saída — notes.output_language a menos que o usuário peça um.

1.2 Transcrever

Para cada gravação sem um arquivo de legenda correspondente (mesmo radical), execute:

$PY <skill>/scripts/transcribe.py <gravação> -o <rascunho>/transcripts

• <rascunho> é uma pasta temporária fora do vault (ex.: $TMPDIR/recording-to-obsidian-<data>-<slug>), usada para todos os arquivos intermediários.
• Opções quando necessário: --model small (mais rápido, mais grosseiro), --language en (pular detecção), --diarize (rótulos de falante; precisa de install.sh --diarize e um token do Hugging Face na variável de ambiente nomeada por diarize.hf_token_env). A primeira execução baixa o modelo, o que pode levar minutos; ele imprime o progresso no stderr — deixe terminar.
• Ele escreve <radical>.srt e <radical>.txt (uma linha [HH:MM:SS] Falante N: texto por segmento) e imprime uma linha de resumo JSON (idioma, modelo, duração, falantes, estatísticas de limpeza, caminhos de arquivo). Guarde esse resumo: idioma, modelo e diarização vão para a seção Fonte das notas.
• Legendas existentes de qualquer ferramenta podem ser normalizadas da mesma forma: $PY <skill>/scripts/transcribe.py talk.vtt -o <rascunho>/transcripts (nenhum modelo envolvido; loops de repetição são condensados e um .txt com timestamps é escrito).
• Gravações longas são normais: o script lida com horas de áudio; não divida o arquivo.

Se a transcrição falhar, relate a linha de erro; $PY <skill>/scripts/transcribe.py --check mostra o que está faltando.

1.3 Escolher o modo

Um modo explícito do usuário (ou notes.default_mode diferente de auto) vence. Caso contrário:

1. Slides, cadernos, código de laboratório ou apostilas entre os materiais → aula.
2. Caso contrário, leia os primeiros ~5 minutos da transcrição e examine o restante:

Sinais de reunião	Sinais de aula
vários falantes com tempo de fala comparável	um falante dominante explicando
pauta, atualizações de status, "onde estamos em…"	"hoje vamos cobrir…", "na semana passada vimos…"
propostas, trade-offs discutidos, "vamos com…", "concordo"	definições, derivações, exemplos resolvidos, exercícios
responsáveis e datas: "você pode fazer isso até sexta?"	perguntas da plateia para entender, não para decidir
projetos, clientes, prazos, riscos	numeração de curso/aula, leituras, lição de casa

3. Casos mistos vão pelo propósito: revisões de design, planejamento, retros, debriefs e 1:1 são reuniões; palestras técnicas gravadas, treinamentos, seminários e tutoriais são aulas, mesmo com alguma discussão.

Registre a escolha e os dois ou três sinais que a motivaram (eles vão no relatório). Se for um verdadeiro impasse e você puder perguntar, pergunte; caso contrário, escolha e diga por quê.

1.4 Modelo de execução: orquestrador + um escritor de notas

Ler uma transcrição inteira, um deck página por página e cadernos, e depois escrever dezenas de arquivos enche o contexto rapidamente, então divida os papéis:

• Orquestrador — a sessão que recebeu a solicitação. Ele faz 1.1–1.3 (a saída da transcrição fica no disco; ele lê apenas o suficiente da transcrição para escolher o modo), entrega a escrita para um subagente escritor de notas, depois executa a verificação em 1.5 e relata.
• Escritor de notas — um subagente que faz todo o trabalho de escrita para o modo escolhido em seu próprio contexto: ler cada material, planejar, escrever, auto-verificar. Uma reunião ou uma aula cabe confortavelmente em um contexto; não divida páginas ou partes da transcrição entre agentes (isso perde referências cruzadas e duplica notas).

Faça o trabalho você mesmo em vez de delegar quando nenhuma ferramenta de subagente estiver disponível, quando um subagente não puder fazer o que o trabalho exige (ver imagens, executar scripts, escrever arquivos). No modo reunião você também pode escrever diretamente quando a reunião for curta o suficiente para que o briefing seja tão longo quanto o trabalho (uma gravação de menos de ~15 minutos sem slides ou documentos). O modo aula sempre usa o escritor de notas a menos que um subagente esteja indisponível ou não possa fazer o trabalho: um deck tem que ser lido página por página, e isso pertence ao contexto do escritor, não ao seu. Diga qual você escolheu no relatório. A verificação (1.5) nunca é pulada. Para várias sessões, use um escritor de notas por sessão, sequencialmente quando elas anexarem ao mesmo MOC.

Briefing para o escritor de notas — ele começa sem contexto, então dê tudo a ele:

• o caminho absoluto deste skill; o modo; os arquivos a seguir: references/meeting-mode.md ou references/lecture-mode.md, mais references/note-templates.md, references/transcript-processing.md, references/mermaid-style.md;
• caminho do vault, pasta de rascunho, $PY, idioma de saída, título/série/data (ou "derivar"), nomes de pasta do config;
• caminhos absolutos de cada material e dos arquivos de transcrição, com o resumo da transcrição (idioma, modelo, falantes);
• o MOC de série/curso existente e o hub/MOC da sessão anterior, se houver; qualquer coisa que o usuário pediu especificamente;
• regras: escreva apenas dentro do vault; nunca modifique notas pré-existentes exceto os anexos documentados; sem segredos;
• o que retornar: o bloco de relatório da Seção 3 mais qualquer coisa que não pôde resolver.

1.5 Verificar (orquestrador)

Quando o escritor de notas retornar, verifique seu trabalho de forma independente, em vez de confiar em seu resumo:

$PY <skill>/scripts/check_vault.py <vault> --since <segundos epoch quando o trabalho começou>
$PY <skill>/scripts/scan_secrets.py <vault>/sources

check_vault.py deve terminar com issues: 0; corrija avisos também, a menos que haja um motivo para não fazê-lo (diga qual). Ele resolve links da forma que o Obsidian faz (nome de arquivo ou caminho parcial, insensível a maiúsculas/minúsculas, ignorando #heading/|alias, pulando blocos de código), então um link quebrado que ele relata está quebrado no Obsidian. Ele verifica: [[links]]/embeds/links markdown quebrados, links PDF++ sem .pdf, frontmatter (title, type, date_created), cobertura do hub (toda nova nota está linkada de um MOC ou hub de reunião; todo hub de reunião de um MOC), segredos; avisos para notas sem conexões, Mermaid sem estilo e links ambíguos.

Depois, verifique o que os scripts não podem:

• nenhuma nota pré-existente foi alterada exceto os anexos documentados (entrada do MOC de série, status de decisão substituído, link "próximo" do MOC da aula anterior);
• modo reunião: toda decisão tem um registro ou é explicitamente menor; todo item de ação tem um responsável (ou TBD), uma data de vencimento (ou TBD) e um timestamp;
• modo aula: o MOC lista cada nova nota exatamente uma vez; a granularidade e os alvos das âncoras da auto-verificação da aula são atendidos.

Corrija problemas pequenos diretamente; envie os maiores de volta para o escritor de notas com a lista exata. Reexecute check_vault.py até que relate 0 problemas. Exclua a pasta de rascunho (ela contém o wav e as imagens das páginas) a menos que o usuário a queira.

2. Convenções compartilhadas

Layout do vault — as notas são planas; a navegação vem de MOCs e hubs, não de pastas.

vault/
├── notes/                         # notas atômicas, âncora, decisão e tópico (planas)
├── meetings/<série>/             # hubs de reunião: "YYYY-MM-DD <título>.md"
├── moc/<série ou curso>/        # MOC de série (reuniões) / um MOC por aula
└── sources/<série ou curso>/<YYYY-MM-DD ou Aula_NN>/
    ├── <prefixo>_transcript.srt / .txt
    ├── <prefixo>.pdf               # slides, para links PDF++
    ├── slide_images/  whiteboard_photos/  notebooks/
    └── structured_slides.json     # registro opcional de leitura por página

Dê a cada arquivo copiado para sources/ um prefixo de série/curso + sessão (Atlas_2026-11-12_transcript.srt, Optics101_L03.pdf, Optics101_L03_p08.jpg): o Obsidian resolve links pelo nome do arquivo, então duas sessões que ambas contenham transcript.srt ou page-08.jpg criariam links cruzados. Nomes de pasta usam o nome da série/curso com espaços substituídos por -.

Nomes de arquivo — o título legível por humanos, sem IDs (hubs de reunião são a exceção: eles começam com a data para ordenar). Evite / \ : * ? " < > | # ^ [ ]; escreva — em vez de :. Títulos são específicos o suficiente para ficar sozinhos: Rate limits usam um token bucket por chave de API.md, não Rate limiting.md.

Frontmatter — toda nota começa com frontmatter YAML com pelo menos title, type e date_created. type é moc, meeting, decision ou topic (modo reunião) e moc, anchor ou atomic (modo aula). Campos específicos do modo estão em references/note-templates.md. Tags são em inglês minúsculo em kebab-case: uma tag de série/curso, 2–4 tags de tópico, uma tag de tipo; reutilize tags já existentes no vault antes de inventar novas.

Idioma — output_language = "auto" significa: escreva no idioma dos materiais (o idioma detectado da transcrição, ou dos slides'). Quando o idioma de saída difere do idioma dos materiais, mantenha termos técnicos no idioma original e forneça um glossário na primeira ocorrência — notas em chinês de uma reunião em inglês: 功能开关 (feature flag); notas em inglês de uma aula em alemão: error propagation (Fehlerfortpflanzung) — depois use a forma que soar mais natural. Código, comandos, caminhos, nomes de produtos e ferramentas nunca são traduzidos. Cabeçalhos seguem o idioma de saída.

Links — todo [[wikilink]] deve resolver para uma nota ou arquivo no vault. Link para uma nota existente em vez de escrever uma duplicata. Use um caminho ([[sources/Atlas/2026-11-12/Atlas_2026-11-12_transcript.srt|transcrição]]) quando um nome simples puder ser ambíguo. Links de página PDF++ sempre mantêm .pdf: [[Optics101_L03.pdf#page=5|Slide p.5 "Lei de Snell"]].

Timestamps — cite o [HH:MM:SS] da transcrição para toda decisão, item de ação e afirmação que vem apenas da fala. Eles são a trilha de auditoria de volta à gravação.

Segredos — nunca escreva credenciais no vault. Antes de copiar cadernos ou código para sources/, execute $PY <skill>/scripts/scan_secrets.py --redact <cópia> na cópia (os valores se tornam <REDACTED>, os nomes das variáveis permanecem). Senhas faladas, números de cartão ou dados pessoais sensíveis em uma reunião também não são registrados em ata — escreva "credenciais foram compartilhadas verbalmente (não registradas aqui)".

Visuais — leia references/mermaid-style.md antes de escrever qualquer diagrama Mermaid: ele tem a paleta e as regras que mantêm os diagramas renderizando. Sintaxe inválida é pior do que nenhum diagrama.

Saídas do modo

• Reunião → references/meeting-mode.md: 1 hub, 1 registro de decisão por decisão significativa, 0–N notas de tópico para conhecimento que vale a pena manter, uma entrada anexada ao MOC de série (criado no primeiro uso), transcrição copiada para sources/.
• Aula → references/lecture-mode.md: 1 MOC, 8–15 notas-âncora para um deck normal de 30+ páginas, em média pelo menos uma nota atômica por slide de conteúdo, slides/cadernos/transcrição copiados para sources/.

3. Relatório

Modo reunião:

Reunião 2026-11-12 — <título>  (série: <série>)   modo: reunião (sinais: …)
  Transcrição: 00:41:07, mlx:whisper-large-v3-turbo, 3 falantes, en → notas en
  Hub: meetings/<série>/2026-11-12 <título>.md
  Decisões: 3 (registros: 3)   Itens de ação: 7 (responsável TBD: 1, vencimento TBD: 2)
  Notas de tópico: 2   Perguntas em aberto: 2   Riscos: 1
  MOC de série: moc/<série>/MOC — <série>.md (entrada anexada)
  check_vault: issues 0, avisos 0
  Não resolvido: <falantes não correspondidos a nomes, passagens pouco claras, …>

Modo aula:

Aula NN — <tópico>   modo: aula (sinais: …)
  Slides: 45 páginas (conteúdo 37)    Pontos de conhecimento: 68
  Notas: 56 atômicas + 12 âncora     arquétipos: conceito=34, prática-demo=6, …
  Notas por slide de conteúdo: 1.5    Âncoras com ≥2 elementos ricos: 12/12
  Mermaid: 14 (tipos: sequência, mapa mental, fluxograma, diagrama de classe)
  check_vault: issues 0, avisos 0
  PDF++: 22 links de slide, 0 sem .pdf
  Não resolvido: <páginas não correspondidas a notas, perguntas não respondidas, …>

O relatório sempre começa com o bloco acima. Se o escritor de notas foi um subagente, acrescente Escritor: subagente; caso contrário, Escritor: orquestrador. Inclua quaisquer ações que o usuário precisa tomar (itens de ação sem dono, notas com TBD, passagens que não pôde resolver).