A4P plaud

Plaud 녹음·전사록을 옵시디언으로 가져와 사이드패널에서 스트리밍 재생하고, 템플릿·성경 wikilink 자동화로 PKM과 통합하는 옵시디언 플러그인입니다.

📦 ai4pastor 강의 수강생 배포용. 데스크탑 전용 (모바일 미지원).

주요 기능

• 사이드패널에서 Plaud 녹음 검색·기간 필터(오늘/7일/30일)·정렬, 한눈에 보는 카드 리스트
• 노트 임포트: AI 요약·트랜스크립트를 메타와 함께 vault에 저장. 일괄 임포트(미임포트 N개 한 번에) 지원
• 임포트 시 자동 STT (옵션): Plaud 전사가 없는 녹음은 Groq/OpenAI Whisper로 자동 전사 후 저장
• 오디오 볼트 저장: 상세 모달에서 mp3를 vault에 내려받고 노트에 자동 임베드 (장기 보관용)
• 다이제스트 노트: 명령 한 번으로 최근 7일/30일 녹음 요약을 한 노트로 롤업 (임포트 노트 wikilink 연결)
• 새 녹음 자동 감지 (옵션): 설정한 주기로 서버를 확인해 새 녹음 도착 시 알림
• 타임스탬프 점프: 모달·노트의 [1:23] 클릭 → 플레이어가 그 위치부터 재생
• 노트 재동기화: 현재 노트 또는 임포트된 전체 노트를 서버 최신 요약/전사로 갱신 (직접 쓴 메모는 보존)
• 스트리밍 플레이어: vault에 mp3 저장하지 않고 재생 직전 URL 갱신 (vault 무거워지지 않음)
• 임포트 템플릿 + Templater 연동: 사용자 템플릿 스크립트로 frontmatter 자동 채움
• 성경 구절 자동 wikilink 변환 (한국어 66권, 요한복음 3:16 → [[요3_16]]) — 임포트 시 자동 적용(설정에서 끄기 가능)
• 활성 노트 ↔ 카드 시각 동기: 노트 열면 사이드패널 카드 자동 강조·스크롤
• 감시 폴더 자동 업로드 (v0.8.0, 실험): 지정 폴더(vault 안/밖·아이클라우드)에 mp3/opus를 넣으면 자동으로 내 Plaud 계정에 업로드 → Plaud 전사·요약 → 노트 자동 임포트

설치 (BRAT)

1. 옵시디언에 BRAT(Beta Reviewers Auto-update Tester) 플러그인 설치·활성화
2. 명령 팔레트 → "BRAT: Add a beta plugin for testing"
3. 입력: ai4pastor/a4p-plaud
4. 설치 완료 후 설정 → 커뮤니티 플러그인에서 A4P plaud 활성화

Plaud 로그인 (v0.6.0+)

설정 → A4P plaud → "Plaud 로그인" 버튼을 누르면 브라우저가 열립니다. 평소 쓰시던 방식(구글·Apple·이메일) 그대로 로그인하면 끝입니다. 토큰 복사·붙여넣기가 필요 없고, 기존 녹음이 그대로 연결됩니다.

플러그인은 Plaud가 공식 MCP/CLI(@plaud-ai/mcp, @plaud-ai/cli)에 사용하는 **공식 개발자 API(OAuth)**로 인증하며, 토큰이 만료되면 자동으로 갱신합니다. 로그아웃하거나 접근 권한을 회수하지 않는 한 다시 로그인할 필요가 없습니다.

ℹ️ v0.4~0.5의 mcp.plaud.ai 연결에서 며칠마다 재로그인이 필요하던 문제가 이 방식으로 해결됩니다. v0.5 이하에서 업데이트한 경우 한 번만 다시 로그인해 주세요.

🔒 보안

로그인 토큰은 운영체제 키체인(safeStorage)으로 암호화되어 vault에 평문으로 저장되지 않습니다. 로그인은 브라우저에서만 이뤄지며 플러그인은 비밀번호를 저장하지 않습니다. 통신은 Plaud 서버(web.plaud.ai·platform.plaud.ai, 감시 폴더 기능 사용 시 api.plaud.ai)와만 이뤄지고, 설정에서 언제든 로그아웃으로 토큰을 제거할 수 있습니다.

감시 폴더 기능(선택)에 웹 계정 이메일/비밀번호를 저장하는 경우에도 키체인으로 암호화되며, 토큰 만료 시 자동 재로그인에만 사용됩니다. 비밀번호 저장을 원치 않으면 토큰 직접 붙여넣기 방식을 사용할 수 있습니다.

사용법

사이드패널 열기

• 좌측 리본의 🎙 마이크 아이콘 클릭 또는 명령 팔레트 → "Plaud 패널 열기"

녹음 듣기

• 카드를 클릭하면 플레이어에 로드됩니다 (자동 재생 X)
• 플레이어의 ▶ 재생 버튼으로 시작 — 첫 재생 시 mp3 URL을 받아옵니다
• 컨트롤: ⏪10초 / 10초⏩ / 1.0x · 1.5x · 2.0x 배속 / 시크바

노트 임포트

• 카드 우측 📄 노트 보기 클릭 → 모달에서 AI 요약(마크다운 렌더링)·트랜스크립트 미리보기 + 노트로 가져오기
• 일괄 임포트: 미임포트 녹음이 있으면 툴바에 ⬇ N 배지가 표시 — 클릭 한 번으로 전부 가져오기
• 임포트된 카드는 좌측 그린 보더 + 📄 노트 열기 (강조색)
• 저장 폴더: 설정에서 지정 (입력란 클릭 시 vault 폴더 자동완성, 지정 전에는 임포트 시 안내 표시)
• 노트 파일명: {녹음 제목}.md (동명 노트가 있으면 (2) 자동 부여)
• 노트 구성: AI 요약 + 접힌 "타임스탬프 트랜스크립트" 콜아웃 (요약이 없으면 트랜스크립트만)

타임스탬프 점프

• 상세 모달 또는 임포트된 노트(읽기 모드)에서 [1:23] 타임스탬프 클릭 → 사이드패널 플레이어가 그 위치부터 재생
• "그 대목에서 정확히 뭐라고 했지?" 설교 복기·강의 복습에 유용

노트 재동기화

• 녹음 직후 가져와서 AI 요약이 비어 있었다면, 나중에 명령 팔레트 → "현재 노트를 Plaud 최신 요약/전사로 갱신"
• 플러그인이 만든 요약/전사 구간만 교체하고, 노트에 직접 쓴 메모·Templater frontmatter는 그대로 보존

임포트 템플릿 (선택)

설정 → 임포트 → 기본 임포트 템플릿에 vault 내 .md 파일 경로 지정. 모달에서도 매번 변경 가능.

지원 변수 (단순 치환):

변수	값
{{plaud_id}}	녹음 고유 ID
{{transcript}}	전체 트랜스크립트
{{summary}}	AI 요약 (없으면 빈 문자열)
{{filename}}	원본 파일명
{{date}}	녹음일 (YYYY-MM-DD HH:mm)
{{duration}}	길이 (mm:ss)
{{duration_seconds}}	길이 (초)
{{region}}	데이터 리전 (us / eu / apne1 등)
{{imported_at}}	임포트 시각

Templater 연동: Templater 플러그인이 설치되어 있으면, 사용자 템플릿 안의 <% ... %> 또는 <%* ... _%> 블록을 노트 생성 직후 자동 실행합니다. 사용자 스크립트가 processFrontMatter로 채운 값은 본 플러그인이 자동으로 보존합니다.

옵션 X 모드: 노트 본문(메타·요약·트랜스크립트)은 본 플러그인이 채우고, 사용자 템플릿은 본문 끝에 append됩니다. 사용자 템플릿 시작 부분의 frontmatter 블록은 자동 제거되므로 스크립트만 두셔도 됩니다.

성경 구절 자동 wikilink

활성 노트에서 명령 팔레트 → "활성 노트의 성경 구절을 wikilink로 변환"

입력	변환
요한복음 3장 16절	[[요3_16]]
요 3:16 / 요3:16	[[요3_16]]
시편 23편 1-6절	[[시23_1]] ~ [[시23_6]]
고린도전서 13:4~7	[[고전13_4]] ~ [[고전13_7]]

• 한국어 66권 책 이름·줄임표 모두 인식
• 코드 블록·기존 wikilink 안은 건드리지 않음
• frontmatter는 보존
• 실수 시 Cmd+Z로 되돌리기 가능

감시 폴더 자동 업로드 (v0.8.0, 실험)

일반 녹음 파일(Plaud 기기로 녹음하지 않은 오디오)도 폴더에 넣기만 하면 Plaud가 전사·요약해서 옵시디언 노트로 들어옵니다.

설정 → 🎙 감시 폴더 자동 업로드:

1. Plaud 웹 계정 연결 — 이메일/비밀번호로 연결하거나(키체인 암호화 저장, 만료 시 자동 재로그인), 비밀번호 저장이 싫으면 web.plaud.ai 개발자 도구에서 토큰을 직접 붙여넣기
2. 감시 폴더 지정 — vault 안 폴더(자동완성)와 vault 밖 절대경로(아이클라우드 드라이브 등) 둘 다 가능. "검증" 버튼으로 폴더·파일 수 확인
3. 기능 켜기 → 폴더에 mp3/opus 파일을 넣으면: 업로드 → Plaud 전사·요약 → 노트 자동 생성 (기존 임포트와 동일한 형식·템플릿·성경 wikilink 적용)

아이폰에서 쓰기: 감시 폴더를 아이클라우드 드라이브 폴더로 지정하면, 아이폰 파일 앱에서 오디오를 그 폴더에 저장하는 것만으로 (맥이 켜져 있고 옵시디언이 실행 중일 때) 자동 처리됩니다. 아직 다운로드되지 않은 .icloud 파일은 자동으로 내려받습니다.

동작 원칙:

• 원본 파일은 절대 이동·수정·삭제하지 않습니다
• 같은 파일은 다시 업로드하지 않습니다 (경로+크기+수정시각 기록)
• 실패 시 1·5·15분 간격으로 3회 자동 재시도, 이후 설정/명령어의 "실패 재시도"
• "미리보기 (dry-run)" 버튼으로 업로드 없이 대상만 확인 가능
• 명령 팔레트: "감시 폴더 지금 스캔", "감시 폴더: 실패한 업로드 재시도"

⚠️ 이 기능은 Plaud 웹앱이 내부적으로 쓰는 비공식 API(api.plaud.ai)를 사용합니다 (공식 개발자 API는 읽기 전용이라 업로드가 불가능). 전사 실행 시 요금제의 전사 시간이 차감되고, Plaud 측 변경으로 예고 없이 중단될 수 있습니다 — 이 경우에도 플러그인의 다른 기능(임포트·재생·재동기화 등)은 영향받지 않습니다. 업로드는 mp3/opus만 지원합니다 (m4a·wav는 웹/앱의 '오디오 가져오기'를 이용하세요).

활성 노트 ↔ 카드 동기

• vault에서 plaud 노트(plaud_id frontmatter가 있는 노트)를 열면 사이드패널 카드가 자동 강조 + 그 위치로 스크롤
• 일반 노트로 전환해도 플레이어 상태는 유지

알려진 제한

• 데스크탑 전용 (옵시디언 모바일 미지원 — safeStorage·프로토콜 핸들러 의존)
• 공식 연결은 읽기 전용: 공식 개발자 API는 조회만 제공하므로 Plaud 서버의 녹음 이름 변경 등 쓰기 기능은 지원하지 않습니다. (감시 폴더 업로드는 선택 기능으로 비공식 웹 API를 사용 — 위 안내 참고)
• 감시 폴더 업로드는 mp3/opus만 지원 (비공식 API 제약). 아이클라우드 파일은 다운로드가 끝나야 처리되므로 몇 분 지연될 수 있고, 처리에는 맥이 켜져 있고 옵시디언이 실행 중이어야 합니다
• 트랜스크립트 타임스탬프: 줄→오디오 점프 기능은 미지원
• 자동 동기화 없음: 새 녹음을 자동으로 가져오지 않음. 사이드패널 ↻ 새로고침 또는 카드 ⓘ 클릭으로 수동 임포트
• mp3 다운로드 없음 (기본): 재생 직전 URL을 새로 받아 스트리밍. 인터넷 필요 (오프라인 캐시는 추후 옵션)

트러블슈팅

로그인이 안 되거나 녹음이 안 보임 → 설정에서 로그아웃 후 **"Plaud 로그인"**을 다시 눌러 브라우저 로그인을 완료해 주세요. 브라우저에서 평소 쓰는 계정(구글 등)으로 로그인해야 기존 녹음이 보입니다.

브라우저에서 로그인했는데 완료가 안 됨 → 로그인 후 "로그인 완료!" 페이지가 뜨면 탭을 닫고 옵시디언으로 돌아오면 됩니다. "포트 8199가 사용 중" 오류가 나오면 다른 Plaud 로그인(공식 CLI 등)이 진행 중인지 확인하고 잠시 후 다시 시도해 주세요.

전사(트랜스크립트)가 안 보임 → v0.4.1부터 서버 인자명을 자동 감지해 해결됨. 그래도 안 보이면 ⓘ 상세 모달을 한 번 연 뒤 개발자 콘솔(Cmd+Opt+I)의 get_transcript raw 로그를 복사해 이슈로 보고해 주세요.

목록·재생이 비정상 → 명령 팔레트 → "Plaud MCP 도구 목록 콘솔 출력 (디버그)" 실행 후 개발자 콘솔(Cmd+Opt+I) 로그를 복사해 이슈로 보고해 주세요.

Templater 분류 결과가 사라짐 → v0.1.0부터 해결됨. 그래도 발생하면 콘솔 로그 확인.

오디오 재생이 안 됨 (특히 최근 녹음만) → 2026-09부터 Plaud 공식 API는 새 녹음에 of_ 접두어 ID를 쓰고, 서버에 mp3 변환본이 만들어지기 전까지는 오디오 URL이 기기 원본 .opus(브라우저가 열 수 없는 Plaud 컨테이너) 를 가리킵니다. v0.8.1부터 플레이어가 다음 순서로 자동 처리합니다:

1. URL을 새로 받아 1회만 재시도 (이전 버전은 무한 반복하며 Notice가 계속 쌓였음)
2. 실패하면 URL 머리 64바이트를 점검 — HTTP 403/404면 상태코드를 알리고 종료, 표준 Ogg면 전체를 받아 Ogg Opus로 재조립해 재생
3. Plaud 기기 원본이면 웹 계정 연결이 있을 때 서버 mp3 변환본(/file/temp-url?is_opus=false)으로 스트리밍. 연결이 없으면 설정 안내로 종료 서버가 mp3 변환본을 만든 뒤(oc_at_….mp3)에는 다시 1단계에서 바로 재생됩니다. "🔊 오디오 저장"도 같은 판별을 거쳐 .ogg/.mp3로 저장합니다. 자세한 원인은 개발자 콘솔(Cmd+Opt+I)의 [A4P Plaud] media error / 오디오 컨테이너 판별 / 웹 API mp3 임시 URL 로그에 남습니다. 이슈 보고 시 이 줄들을 복사해 주세요.

개발

git clone https://github.com/ai4pastor/a4p-plaud.git
cd a4p-plaud
npm install
npm run dev   # esbuild watch

옵시디언 dev vault의 .obsidian/plugins/a4p-plaud로 심볼릭 링크.

라이선스

MIT