#18이 오디오를 남기게 했다면, 이 PR은 그 오디오를 실제로 쓴다.
Web Speech 포착률 7~10%를 끌어올리는 유일한 방법은 인식 엔진 교체다.
## 두 경로가 하나로 만난다
실시간 녹음 ─┐
├→ recordingId → /api/transcribe → 확정 전사문
파일 업로드 ─┘
`/api/upload`는 파일을 디스크에 떨궈만 두고 "실시간 녹음 탭에서 하세요"라고
안내하던 막다른 길이었다. 이제 녹음 저장소에 넣고 recordingId를 돌려주므로
브라우저 녹음과 완전히 같은 파이프라인을 탄다.
## 실제 타임스탬프
Whisper `verbose_json`이 구간별 실제 오디오 시각을 준다. Web Speech 경로가 쓰던
`결과 이벤트 시각 − 2초` 추정값과 달리 구간 재생·화자 분리에 그대로 쓸 수 있다.
이 값이 있어야 PR #17의 diarization 화자 배정이 비로소 의미를 갖는다.
verbose_json을 지원하지 않는 모델(gpt-4o-transcribe 등)은 400을 주므로 `json`
으로 한 번 더 시도해 텍스트만이라도 받는다.
## 프로바이더별 지원
| 프로바이더 | webm 녹음 | 업로드 파일 | 기본 모델 |
|---|:---:|:---:|---|
| OpenAI · OrcaRouter · 로컬 whisper | O | O | whisper-1 |
| Gemini | X | O | gemini-3.6-flash |
Gemini가 문서로 밝힌 오디오 형식에 webm이 없다. 조용히 실패시키지 않고
"OpenAI 호환 프로바이더를 쓰라"고 명시적으로 안내하며, 설정 화면에도 경고를 띄운다.
## 비트레이트 128k → 32k
이 오디오는 감상용이 아니라 STT 입력이다. 128kbps면 46분 회의가 44MB가 되어
Whisper 상한(25MB)도 Gemini inline 상한도 넘긴다. 32kbps mono Opus는 음성
인식 정확도에 영향이 없으면서 46분을 11MB로 줄인다.
## 참석자·용어 힌트
홈 화면에 입력란을 두고 전사 요청의 어휘 힌트로 보낸다. 실측 transcript에서
"계명대동산병원 → 저희 키스해 주셔서", "양식대로 → 양복점" 같은 고유명사
붕괴가 심했던 부분이다.
## 검증
가짜 Whisper 서버를 세워 종단간 확인:
- 업로드 → recordingId → 전사 → `[00:00]/[00:03]/[00:12]` 전사문
- multipart 필드 검증: model · response_format=verbose_json · language=ko ·
prompt(어휘 힌트) · Bearer 인증 · 파일 바이트 정확히 일치
- webm 녹음도 Whisper로 정상 전사 (5000 bytes 그대로 전달)
- Gemini+webm 거부 / 미설정 400 / 경로조작 400 / 없는 녹음 404
테스트 206 → 229 통과, 신규 타입 에러 0, 린트 baseline과 동일, 빌드 성공.
### 검증하지 못한 것
실제 Whisper·Gemini API를 호출하지 못했다(키 없음). 모든 프로바이더 코드는
목 fetch와 가짜 서버로만 검증했다. 요청 형식은 문서를 따랐으나 실제 응답에
대한 확인이 필요하다.
포착률이 실제로 얼마나 오르는지도 아직 모른다. 다음 회의에서 같은 오디오로
Web Speech와 STT를 나란히 놓고 재야 한다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzAH7GPWSYTe2AoBV6CZDP
46분 대면 회의 실측에서 Web Speech 포착률이 7~10%에 그쳤다(489어절 /
분당 10.6어절, 30초 이상 공백 26곳 26분 29초). 빈 텍스트 청크 19개는
Chrome이 `isFinal: true`에 `transcript: ""`를 준 것으로, 소리는 감지했으나
인식에 실패했다는 신호다.
지금까지는 오디오를 어디에도 남기지 않아 놓친 발화를 복구할 수도, 얼마나
놓쳤는지 잴 수도 없었다. 전사와 독립적으로 원음을 파일로 남긴다.
## 유실 방지 설계
메모리에 모았다가 종료 시 한 번에 쓰지 않는다. 그러면 탭이나 서버가 죽는
순간 회의 전체가 사라진다. 15초 조각마다 디스크에 append 하므로 어느
시점에 중단되든 그때까지의 오디오는 남는다.
- 서버 업로드가 실패해도 녹음을 멈추지 않고 브라우저 사본으로 회수한다
- 조각이 3회 재시도 후에도 실패하면 뒤를 이어 붙이지 않고 멈춘다.
중간이 빈 파일은 짧은 파일보다 나쁘다 — 재생도 전사도 안 된다
- 한 조각도 못 받았으면 "보관됨"이라고 하지 않고 오류를 띄운다
- 서버 사본이 로컬보다 짧으면 경고한다
## 캡처 제약 변경
`noiseSuppression: false, echoCancellation: false, autoGainControl: true`.
브라우저 기본값은 전화 통화용 튜닝이라 멀리 앉은 화자를 노이즈로 지운다.
AGC는 조용한 화자를 끌어올려 주므로 남긴다. 실측으로 검증할 가설이며
회귀 방지 테스트를 걸어 뒀다.
## 검증
- 서버 파이프라인: 184조각 755KB 업로드 → 다운로드 SHA256 바이트 일치
- 클라이언트 전 경로: 합성 스트림으로 48초 녹음 → 로컬·서버 크기 일치,
서버 파일이 decodeAudioData로 48.12초 실제 오디오로 디코딩됨
- 경로 조작 400 / 없는 세션 404 / 빈 조각 400 / 미허용 mimeType 400
- 테스트 162 → 206 통과, 신규 타입 에러 0, 린트 baseline과 동일
실제 마이크 경로는 테스트하지 못했다. Web Speech와 getUserMedia가 같은
마이크를 두고 경합하는지 실사용 확인이 필요하다.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WzAH7GPWSYTe2AoBV6CZDP
고정 제목(## 주요 논의 사항)을 강요하던 프롬프트를, 회의가 실제로 다룬
주제에서 섹션 제목을 도출하도록 바꿨다. 제목만 훑어도 내용이 파악된다.
- meeting·one_on_one: 본문 섹션 제목을 AI가 직접 짓도록 지시
- brainstorm: 카테고리도 미리 정해진 목록이 아님을 명시
- 액션 아이템에 (담당자)·기한 표기 요청 + 예시 제공
- COMMON_RULES 신설 — 환각 방지, 발화자 표기 활용,
영어 기술 용어 원문 유지(한영 코드 스위칭 대응). 프리셋에만 적용하고
custom 프롬프트는 사용자가 전적으로 제어하도록 유지
- LIVE_MODIFIER에 섹션 제목이 갱신될 수 있다는 안내 추가
버그 수정: 기존 meeting 프롬프트는 액션 아이템을 "담당자와 기한이 명확한
항목만"으로 제한해, 담당자를 정하지 않은 회의에서는 액션 아이템이 하나도
추출되지 않았다. 담당자가 불분명해도 포함하도록 변경.
`- [ ]` 체크박스 형식은 그대로 유지해 parseActionItems와 호환된다.
테스트 102 → 113.
Co-authored-by: csbae <csbae@RP-002.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
롤링 요약이 30초마다 누적 전사 전체를 다시 보내고 있었다. 호출 N회차가
그때까지의 전사 전부를 담으므로 총 토큰이 회의 길이의 제곱으로 늘어난다.
1시간 회의 기준 약 116만 입력 토큰, 2시간이면 2배가 아니라 4배가 된다.
[지금까지의 요약] + [새로 추가된 발화]만 보내도록 바꿔 호출당 토큰을
회의 길이와 무관하게 일정하게 만들었다.
- templates.ts: BuildPromptArgs.incremental 추가, INCREMENTAL_MODIFIER 신설.
증분 모드에서는 전사 블록이 자체 라벨을 갖는다
- live-summary.ts: previousSummary 옵션. 값이 있으면 증분 모드로 동작
- live-summary.ts: planLiveSummaryRequest() — 전체/증분 결정을 순수 함수로
분리해 단위 테스트 가능하게 함
- useLiveSummary: 마지막 요약 지점 인덱스를 추적해 델타만 전송.
성공했을 때만 전진시켜 실패해도 발화를 잃지 않는다
- 요약을 요약하는 구조라 오차가 누적되므로 fullRefreshEvery(기본 20회)마다
전사 전체로 한 번 다시 요약해 오차를 끊는다
기본 설정에서 1시간 회의 기준 약 7배, 전체 재요약을 끄면 약 12배 절감된다.
회의가 2~3분보다 짧으면 지시문 오버헤드 때문에 오히려 조금 늘어난다.
테스트 141 → 151.
Co-authored-by: csbae <csbae@RP-002.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* feat: OpenAI 호환 프로바이더 지원 (OrcaRouter · OpenAI · 로컬 모델)
Gemini 직접 호출만 가능하던 구조를 프로바이더 레이어로 분리.
base URL과 모델 ID만 지정하면 OpenAI Chat Completions 형식을 따르는
엔드포인트는 모두 연결된다 (OrcaRouter, OpenAI, Ollama, LM Studio, vLLM).
- src/lib/providers/ 신설 (gemini / openai-compatible 어댑터 + 프리셋)
- /settings에 프로바이더 선택 UI 추가, 기존 Gemini 키는 자동 승계
- LLM_PROVIDER / LLM_BASE_URL / LLM_MODEL / LLM_API_KEY 환경변수 지원
- base URL은 http/https만 허용 (서버가 대신 fetch하므로 SSRF 방어)
- SECURITY.md에 프로바이더별 전송 경로와 SSRF 주의사항 문서화
- 테스트 102 → 141
DB에 저장되는 summaryMode 값('gemini')은 기존 레코드 호환을 위해 유지하고
UI 라벨만 "AI 요약"으로 변경했다.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* chore: 기본 Gemini 모델을 3.5 Flash Lite로 갱신
gemini-2.5-flash-lite → gemini-3.5-flash-lite. 같은 저비용·고속 티어의
최신 세대이며, 무료 등급 중심의 사용 프로필을 그대로 유지한다.
- providers/gemini.ts: DEFAULT_GEMINI_MODEL
- presets.ts: OrcaRouter 기본 모델과 모델 힌트 문구
- .env.example, README 참조 갱신
참고: 화자 분리를 지원하는 gemini-3.5-transcribe는 오디오 입력 전용
음성인식 모델이라 이 자리(텍스트 → 회의록 요약)에 넣을 수 없다.
오디오 캡처가 들어오는 시점에 STT 경로로 별도 추가해야 한다.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: csbae <csbae@RP-002.local>
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
* feat(phase-1): 저장/목록/상세 UI + 마크다운 라이브러리 + 검색
ROADMAP Phase 1 #3~#7 완료.
## Markdown 렌더링 (#6)
- marked + isomorphic-dompurify 도입
- src/lib/markdown.ts 공용 유틸 (renderMarkdownToSafeHtml + markdownToPlainText)
- 기존 커스텀 파서(export-minutes.ts) 교체 — 표/리스트/인용/코드블록 정상 렌더
- globals.css에 .prose-minutes 스타일 추가
## 저장 버튼 (#3)
- MinutesViewer에 📌 저장 버튼 + 상태별 피드백
- 미리보기/원문 토글
- 저장 성공 시 /meetings/[id] 상세 링크 배너
- URL.revokeObjectURL 타이밍을 setTimeout으로 지연 (Firefox/Safari 호환)
## 목록 페이지 (#4)
- /meetings 서버 컴포넌트, 페이지네이션 (prev/next)
- MeetingCard: 제목/날짜/템플릿 배지/참석자/태그/preview
- 빈 상태 UI (검색 결과 없음 / 첫 녹음 안내)
- preview는 markdown → plain text 변환 후 160자로 자르기
## 상세 페이지 + 편집 (#5)
- /meetings/[id] 서버 컴포넌트 + 클라이언트 편집 island
- 제목/본문/참석자/태그 인라인 편집
- 편집 모드에서 좌(textarea) · 우(live preview) 분할
- 삭제 버튼 (confirm)
- 원본 transcript는 <details>로 접어둠
## 검색 (#7)
- MeetingSearchBar 클라이언트 컴포넌트
- 300ms debounce + useTransition + URL query 동기화 (replace, scroll false)
- 서버에서 ILIKE contains로 title/transcript/markdown 검색
- tsvector GIN 인덱스는 후속 최적화로 분리 (개인용 규모에서 ILIKE 충분)
## Prisma 7 호환
- @prisma/adapter-pg + pg 추가 (driver adapter 필수)
- generator를 prisma-client-js로 전환 (안정적 레거시)
- src/lib/db.ts에 PrismaPg 어댑터 사용 + DATABASE_URL 누락 시 placeholder로 fallback
- DB 접근 페이지/라우트에 export const dynamic = 'force-dynamic' 추가
(Next 16 pre-render 시 Prisma 초기화 회피)
- Dockerfile에서 src/generated 복사 제거, .gitignore도 정리
## UX
- 메인 페이지 우상단 "📚 저장된 회의록" 링크 추가
## 테스트
- src/__tests__/markdown.test.ts 9개 신규 (렌더/sanitize/plain text)
- 전체: 80 tests passing (이전 71 + 9)
* docs: PR#2 본문 드래프트 추가
* feat(phase-1.5): 웹에서 Gemini API 키 설정 (LocalStorage)
.env를 만지지 않고도 브라우저에서 키를 설정·관리할 수 있게 함.
개인용 단일 인스턴스 가정으로 LocalStorage만 사용 (DB 미관여).
## 구조
- src/lib/api-keys.ts (서버): resolveGeminiApiKey() 우선순위
요청 body 키 → process.env.GEMINI_API_KEY → null
- src/lib/api-key-storage.ts (클라이언트): get/set/clear/maskApiKey
- /api/settings/status: 환경변수 키 존재 여부만 노출 (값 X)
- /api/settings/test: 키로 짧은 Gemini 호출 → 200/401/403/429 분류
- /settings 페이지: 입력/저장/삭제/마스킹 표시/테스트 호출
## 라우트 변경
- /api/summarize, /api/summarize-live가 body.apiKey 수용
- 키 없을 때 summarize는 단순 변환으로 폴백 (UX 보존)
- summarize-live는 503 + 안내 메시지 (라이브 요약은 키 필수)
## UI
- 메인 헤더에 ⚙️ 설정 링크 추가
- 설정 페이지에 현재 키 소스 배지 (브라우저 / 환경변수 / 없음)
- 보이기/숨기기 토글, 테스트 호출 버튼, 보안 안내
## 테스트
- api-keys.test.ts: 7개 (요청>env, 공백 처리, env 미설정 시 null)
- api-key-storage.test.ts: 7개 (LocalStorage CRUD + 마스킹)
- 전체: 94 tests (이전 80 + 14)
## 비목표 (개인용 가정)
- 다중 사용자 / 권한
- DB 영속화 / 키 암호화
* docs: PR#3 본문 드래프트 추가
* feat(phase-2): 액션 아이템 추출/체크리스트 + Google Docs 호환 복사
## 액션 아이템 (ROADMAP #8~#11)
ROADMAP의 Gemini JSON 출력 대신 마크다운 체크박스 휴리스틱 채택.
모든 템플릿이 이미 - [ ] 형식 출력하므로 Gemini 호출 비용 0.
### Schema
- ActionItem 테이블 추가 (Meeting 1:N, cascade delete)
- 필드: id, meetingId, task, isDone, position, createdAt, updatedAt
- 인덱스: (meetingId, position) / isDone
- 마이그레이션 20260428071709_add_action_items
### 추출 (src/lib/action-items.ts)
- /^\s*[-*]\s+\[(x|X|\s)\]\s+(.+)/ 매칭
- 빈/짧은(<2자)/점만(...) task 노이즈 제거
- 들여쓰기/대문자 X 모두 허용
- 단위 테스트 8개
### API
- POST /api/meetings: 마크다운에서 액션 아이템 자동 추출 후 함께 저장
- GET /api/meetings (목록): _count로 미완료 액션 카운트 포함
- GET /api/meetings/[id] (상세): actionItems include
- PATCH /api/action-items/[id]: isDone 토글, task 수정
- DELETE /api/action-items/[id]
- POST /api/meetings/[id]/reparse-action-items: 마크다운 재파싱으로 교체
### UI
- ActionItemList 컴포넌트: 체크박스 + 낙관적 업데이트 + 진행률(완료/전체)
+ 개별 삭제 (hover ✕) + 🔄 재추출 버튼
- MeetingDetail에 통합 (조회 모드에서만 노출, 편집 중에는 숨김)
- MeetingCard에 미완료 카운트 배지 (✅ N 미완료)
- /meetings 상단에 "내 미완료 액션 (최근 5)" 위젯
### 비목표 (이번 단계)
- assignee/dueDate 필드 — Gemini JSON 모드 도입 시 추가
- 홈 페이지 대시보드 승격 — 녹음 흐름 보존이 우선
## Google Docs 호환 복사
- src/lib/markdown.ts: copyMarkdownAsRichText()
- ClipboardItem({text/html, text/plain}) 우선
- 미지원 브라우저는 contenteditable + execCommand 폴백
- MinutesViewer / MeetingDetail에 📋 Docs용 버튼 추가
- 기존 .md 복사는 📋 .md로 분리 라벨링
- 다운로드 버튼은 ⬇ 접두로 구분
## 테스트
- action-items.test.ts: 8개 (다양한 마크다운 패턴)
- 전체: 102 tests passing (이전 94 + 8)
* docs: PR#4 본문 드래프트 추가
* feat(phase-1): Prisma 연동 + 회의록 CRUD API
Phase 1 foundation (ROADMAP #1~#3):
- src/lib/db.ts: Prisma 클라이언트 싱글톤 (dev hot-reload 대응)
- Meeting 스키마 확장: attendees/tags (String[]), template/depth/
summaryMode/customPrompt (향후 참조 복원용), createdAt 인덱스
- 첫 마이그레이션 `20260421104750_init` 생성
- /api/meetings (GET 목록 + POST 생성)
- q 파라미터로 제목/transcript/markdown 부분 검색
- limit (max 100), offset 페이지네이션
- attendees/tags 배열 타입 정규화
- /api/meetings/[id] (GET/PUT/DELETE)
- PUT은 markdownMinutes/title/attendees/tags만 편집 허용
- 존재하지 않는 id에 대해 404
- docker-compose.yml: tools 프로필에 migrate 서비스 추가
(app 컨테이너 bloat 없이 마이그레이션 실행)
- Prisma mock 기반 API 테스트 14개 신규 (총 71 tests)
* docs: migrate 실행 단계 추가, ROADMAP의 #1/#2 완료 체크
* docs: PR 본문 드래프트 추가
회의록 외 다양한 용도로 쓸 수 있도록 출력 구조와 요약 깊이를 분리.
템플릿:
- 🗂️ 회의록 (표준, 라이브 O)
- 🎓 강의·세미나 노트 (상세, 라이브 O)
- 🤝 1:1 미팅 (표준, 라이브 O)
- 💡 브레인스토밍 (상세, 라이브 O)
- 🎤 인터뷰 (표준, 라이브 X — Q&A 포맷)
- 📝 원문 정리 (상세 고정, 라이브 X — 요약 없이 문단화만)
- ⚙️ 커스텀 (자유 프롬프트)
강도: 간결 / 표준 / 상세 — 템플릿별 기본값 프리셋, 언제든 override.
변경:
- src/lib/templates.ts 신규 — 프리셋 + 프롬프트 빌더
- minutes-generator / live-summary 가 buildPrompt 공유
- /api/summarize{-live} 가 template/depth/customPrompt 파라미터 수용
- page.tsx UI: 템플릿 픽커, 강도 라디오, 커스텀 textarea
- LiveRecorder 가 설정을 useLiveSummary 로 전달 (ref 기반 최신값)
- 단순 변환 모드는 기존 동작 유지 (템플릿 미적용)
- 프롬프트 빌더 단위 테스트 19개 (총 57 tests)
녹음 중 30초 간격으로 Gemini가 중간 회의록을 갱신하고, 녹음 중지 시
최종 회의록을 자동 생성한다. Gemini 실패 시 단순 변환 마크다운으로
폴백하여 사용자는 항상 결과물을 받는다.
- 실시간 요약 폴링 (25단어 시작, 40단어 증분 게이트)
- 429 쿼터 초과 60초 쿨다운 + 일반 실패 지수 백오프
- Web Speech API 네트워크 단절 자동 재연결 (최대 8회)
- Hydration mismatch (React #418) 수정 — isSupported를 mount 후 결정
- gemini-2.5-flash-lite 모델로 통일 (무료 등급 15 RPM / 1000 RPD)
- Gemini 호출 URL → x-goog-api-key 헤더 인증으로 전환
- 좌우 분할 뷰 (실시간 텍스트 / 실시간 회의록) + 자동 스크롤
- 진행률 바, 쿨다운 카운터, interim 텍스트 커서
- Prisma 7 호환 위해 schema.prisma의 datasource url 제거
(prisma.config.ts로 이동됨)
- Docker Compose에 test 프로필 서비스 추가 (vitest 38 tests)
- 오디오 파일 업로드 + 유효성 검사
- 실시간 음성 인식 (Web Speech API)
- 회의록 생성 (단순 STT→MD 변환 / Gemini AI 요약)
- 마크다운/HTML 내보내기
- PostgreSQL + Prisma ORM
- Docker Compose 배포 지원
- TDD: 31개 테스트, 96% 커버리지
csbaeandClaude Opus 5
