plaud-pipeline

name	plaud-pipeline
description	PLAUD NotePin 녹음을 Plaud Web에서 자동 수집하고 로컬 faster-whisper로 음성 인식해 Obsidian Vault의 날짜별 Markdown에 저장하는 파이프라인. 사용자가 "plaud 가져와", "오늘 녹음 정리해줘", "녹음 처리해", "/plaud-daily" 같은 요청을 하면 발동. macOS 전용.

PLAUD 자동 수집 파이프라인

PLAUD NotePin → Plaud Web → 로컬 다운로드 → faster-whisper 음성 인식 → Obsidian Vault 저장의 전체 흐름을 자동화한다.

발동 조건

다음과 같은 사용자 요청에서 자동 활성화:

• "PLAUD 녹음 가져와줘" / "오늘 녹음 처리해" / "Plaud 수집 돌려"
• 슬래시 커맨드 /plaud-daily
• 서브에이전트 plaud-collector로부터의 위임

최초 설치 (한 번만)

cd ${CLAUDE_PROJECT_DIR}
./setup.sh           # 의존성 설치 + 디렉토리 준비
./setup.sh --check   # 점검만 (변경 없음)
./setup.sh --yes     # 확인 없이 자동 진행

setup.sh가 자동으로 처리:

• Node.js / Python / Homebrew 점검 (없으면 설치 명령 안내)
• npm install playwright + Chromium 다운로드
• Python .venv 생성 + faster-whisper 설치
• input/, logs/, ~/PLAUD-Data/, Vault 폴더 생성
• .env 자동 생성 (없을 때만)
• 스크립트 실행 권한 부여

만약 설치 후 동작이 의심스러우면 ./setup.sh --check로 상태만 다시 점검 가능.

파이프라인 단계

1. 로그인 및 토큰 취득 — Playwright로 Plaud Web 로그인, localStorage에서 인증 토큰 추출
2. 녹음 다운로드 — "미분류" 폴더의 음성 파일을 input/에 받고, 처리 후 Plaud Web의 다른 폴더로 이동(중복 방지)
3. 로컬 음성 인식 — faster-whisper(large-v3-turbo, 한국어, CPU int8)로 transcribe
4. 날짜별 Markdown 저장 — [HH:MM:SS] 발화 형식으로 Obsidian Vault의 Transcripts/YYYY-MM-DD.md에 추가 기입
5. 원본 음성 아카이브 — 처리된 음성을 ~/PLAUD-Data/로 이동

실행 방법

전체 파이프라인 한 번에:

bash ${CLAUDE_PROJECT_DIR}/.claude/skills/plaud-pipeline/scripts/run_pipeline.sh

개별 단계만:

• 다운로드만: node ${CLAUDE_PROJECT_DIR}/.claude/skills/plaud-pipeline/scripts/plaud_login_and_download.js --email "$PLAUD_EMAIL" --password "$PLAUD_PASSWORD" --download-dir "${CLAUDE_PROJECT_DIR}/input"
• 음성 인식만: python3 ${CLAUDE_PROJECT_DIR}/.claude/skills/plaud-pipeline/scripts/whisper_transcribe.py

환경 변수 (.env)

프로젝트 루트의 .env 파일에 정의 (.env.example 참고):

• PLAUD_AUTH_MODE — password(기본) / session(구글 OAuth 자동) / token(수동 토큰)
• PLAUD_EMAIL, PLAUD_PASSWORD — password 모드일 때만 필요
• PLAUD_TOKEN — token 모드일 때만 필요. Plaud Web 로그인 후 개발자도구의 localStorage.tokenstr 값
• PLAUD_PROFILE_DIR — session 모드 프로필 위치(기본 ~/.plaud-pipeline-profile)
• PLAUD_MOVE_TO_FOLDER_ID — 다운로드 후 옮길 Plaud Web 폴더 ID(선택). Plaud Web URL의 tagId= 뒤 값
• PLAUD_API_BASE — https://api-apne1.plaud.ai(기본) 또는 https://api.plaud.ai로 fallback

인증 모드 선택 가이드

상황	권장 모드	메모
Plaud에 비밀번호 추가 가능	password	가장 안정. 무인 cron 100%
구글 OAuth만 가능 + Playwright로 통과됨	session	자동 갱신 안 됨, 수 주마다 GUI 재로그인
구글 OAuth만 가능 + Playwright 차단됨	token	본인 Chrome에서 토큰 복사. 만료 시 갱신

구글 간편로그인 모드 사용법 (session)

Plaud 계정이 구글 OAuth만 쓰는 경우:

1. .env에서 PLAUD_AUTH_MODE=session 설정
2. 첫 실행 1회(반드시 GUI 환경):

   node ./.claude/skills/plaud-pipeline/scripts/plaud_session_login.js --first-time
   

   브라우저가 떠서 구글 로그인을 직접 완료. 토큰이 추출되면 자동 종료. 세션은 ~/.plaud-pipeline-profile/에 저장됨
3. 이후 run_pipeline.sh는 --headless --token-only로 그 세션을 재사용해 토큰만 추출
4. 세션 만료 시(보통 수 주 후) — 자동 실행이 "세션이 없거나 만료되었습니다"로 실패. 위 1단계 명령을 다시 한 번 GUI에서 실행

세션 프로필에는 사용자의 구글 쿠키가 들어 있으므로 절대 git에 올리거나 공유하지 말 것.

Whisper 동작 조정(선택):

• WHISPER_MODEL — 기본 large-v3-turbo. 더 빠르게는 medium, small
• WHISPER_DEVICE — 기본 cpu. faster-whisper는 macOS에서 mps 미지원
• WHISPER_COMPUTE_TYPE — 기본 int8

경로 override(선택):

• PLAUD_INPUT_DIR, PLAUD_PROCESSED_DIR, PLAUD_OUTPUT_DIR

기본 경로 약속

용도	경로
임시 다운로드	${CLAUDE_PROJECT_DIR}/input/
처리 완료 음성	~/PLAUD-Data/
인식 텍스트(Vault)	~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Transcripts/YYYY-MM-DD.md
요약(Vault)	~/Library/Mobile Documents/iCloud~md~obsidian/Documents/Daily Summary/YYYY-MM-DD_summary.md
실행 로그	${CLAUDE_PROJECT_DIR}/logs/plaud_*.log

자주 마주치는 문제

• "토큰을 찾을 수 없습니다" — Plaud Web 로그인 화면 셀렉터가 바뀐 것. scripts/plaud_login_and_download.js의 input[placeholder="이메일 주소"] 셀렉터를 현재 화면에 맞게 조정
• 다운로드 응답 401/403 — 토큰 만료. 재실행 시 자동 재로그인됨
• API 연결 실패 — PLAUD_API_BASE를 https://api.plaud.ai로 변경 시도
• 첫 실행 시 모델 다운로드가 길다 — large-v3-turbo는 약 1.5GB. 한 번 받으면 ~/.cache/huggingface/에 캐시됨
• "파일명 형식 오류" — Plaud 파일명이 YYYY-MM-DD HH_MM_SS.mp3 패턴이어야 함. 다른 패턴은 whisper_transcribe.py의 parse_start_dt() 보강 필요

후속 처리

날짜별 .md가 생긴 뒤 그날치 ADHD 친화 요약을 만들고 싶으면:

• plaud-collector 서브에이전트 호출, 또는
• templates/daily_summary.md의 프롬프트를 사용해 직접 요약

자동화 (cron 자동 등록)

npm run register-cron:dry    # 변경 미리보기 (적용 안 함)
npm run register-cron        # 적용 (백업 + 멱등 갱신)
npm run register-cron:check  # 등록 상태만 확인
npm run uncron               # PLAUD 항목 제거 (다른 cron은 보존)

기본 등록되는 두 항목:

• 매일 03:00 — run_pipeline.sh 실행 → logs/cron.log
• 매주 월요일 09:00 — health_check.sh 실행 → logs/health.log

시간을 바꾸려면 환경변수로:

PLAUD_CRON_TIME="0 4 * * *" PLAUD_HEALTH_CRON_TIME="0 8 * * 1" npm run register-cron

register_cron.sh는:

• 기존 crontab을 logs/crontab.backup.YYYYMMDD-HHMM.txt로 자동 백업
• PLAUD 마커가 있는 줄과 다음 줄을 한 쌍으로 제거 후 새 항목 추가 (멱등)
• 다른 cron 항목은 그대로 유지

⚠ macOS Full Disk Access (한 번만 수동)

cron이 iCloud Drive(Obsidian Vault)에 쓰려면 시스템 권한이 필요합니다:

1. 시스템 설정 > 개인정보 보호 및 보안 > 전체 디스크 접근 권한
2. 하단의 + 버튼 클릭
3. 파일 선택 창에서 ⌘ + Shift + G 동시 누르기 (한글 입력기 켜져 있으면 영문 전환)
4. 입력란에 /usr/sbin/cron 입력 → Enter → 선택된 cron의 "열기" 클릭
5. 목록의 cron 토글 ON

대안(⌘⇧G가 안 될 때): Finder에서 ⌘⇧G → /usr/sbin → cron 파일을 시스템 설정 창에 드래그.

이 권한이 없으면 cron 실행은 되지만 Vault에 못 씁니다(파이프라인은 성공으로 보이는데 Transcripts가 안 생김).

수동 헬스체크: npm run health

안전 수칙

• .env는 절대 git에 커밋 금지(.gitignore에 포함됨)
• 자격증명을 로그에 출력하지 않음
• 처리 완료 음성 자동 삭제 금지(필요 시 사용자 확인 후)