음성 메모 — iOS Shortcuts 가이드

Endpoint: POST https://document.hyungi.net/api/memos/voice (multipart/form-data) 인증: Bearer JWT (단기 access token, 1시간). 만료 시 web 로그인 후 token 재복사. 제한: 10분 / 50MB. m4a/mp3/wav/webm/ogg/opus/aac. 플로우: 업로드 → STT (faster-whisper) → 자동 분류 (4B Gemma triage) → /memos inbox 노출.

장기 service token 발급 endpoint 는 PR-2C 안 포함 X — 1–2주 운영 후 끊김 빈도 보고 별 PR 결정 (plan v9 Memo Intake Upgrade 백로그).

1. JWT access token 복사

데스크탑/모바일 브라우저에서 https://document.hyungi.net/login 로그인 + TOTP (활성 시)

개발자 도구 콘솔에서 다음 명령 1줄 — access_token 출력

// Memo Intake Upgrade 임시 패턴 — service token PR 도입 전까지만
localStorage.getItem('access_token') ??
  // 또는 fetch refresh 후 res.access_token (refresh cookie 유효 시)
  (await (await fetch('/api/auth/refresh', {method:'POST',credentials:'include'})).json()).access_token

출력된 긴 문자열 (eyJ...) 을 Shortcuts 에 입력 (다음 단계)

1시간 후 만료. iOS Shortcut 사용 중 401 발생 시 token 다시 복사 + Shortcut 의 Text action 값 갱신.

2. iOS Shortcuts 만들기 (Apple Watch + iPhone 공용)

iPhone 의 단축어 (Shortcuts) 앱에서 새 단축어 생성:

단축어 이름

메모 녹음 (또는 임의)

Action 1: Dictate Text (받아쓰기 텍스트) 또는 Record Audio (오디오 녹음)

옵션 A — Whisper STT 사용 (권장, 한국어 정확도 ↑):

Record Audio action 추가
- Audio Quality: Normal (m4a 4kbps 정도, 충분)
- Start Recording: On Tap
- Stop Recording: On Tap

옵션 B — iOS native 받아쓰기 (간단, 정확도 보통):

Dictate Text action 추가 + 결과를 본문에 직접 넣어 POST /api/memos/ (text endpoint) 호출

이 가이드는 옵션 A (Whisper STT 경유) 기준.

Action 2: Get Contents of URL

URL: https://document.hyungi.net/api/memos/voice
Method: POST
Headers:
- Authorization: Bearer <위 1단계 토큰> (Text action 으로 분리해두면 갱신 편함)
Request Body: Form
- audio: 위 Action 1 의 출력 (Recorded Audio File)
- recorded_at (옵션): Current Date → Format Date → ISO 8601
- device_hint (옵션): apple_watch 또는 iphone

Action 3: Show Result (옵션)

결과 JSON 의 id 확인 (메모 inbox 에 들어갔는지)

Apple Watch 노출

단축어 이름이 메모 녹음 이면 Siri 로 "Hey Siri, 메모 녹음" 호출 시 Watch 에서 실행
또는 단축어 앱의 별 표시 → Watch 의 단축어 앱 첫 화면에 고정

3. 동작 확인

녹음 후 1–수분 안에:

https://document.hyungi.net/memos 진입
최상단에 새 메모 카드 (🎙️ 음성 배지 + audio player)
STT 완료 후 카드 본문에 변환 텍스트 + AI 분류 배지 (task/calendar/activity/reference/note 중 하나)
AI 추천이 task/일정/활동이면 4 버튼 표시 — 1-click 으로 events 승급

4. 트러블슈팅

증상	원인 / 조치
401 응답	JWT 만료 → web 에서 다시 복사
413 응답	50MB 초과 → 녹음 시간 단축 또는 quality 낮춤
415 응답	Content-Type 또는 확장자 미지원 → m4a/mp3 사용
503 응답	NAS 쓰기 실패 (드물게) → 1–2분 후 재시도
메모는 생겼는데 본문 비어 있음	STT 처리 중 (5분 polling). `stt-service` 컨테이너 health 확인
AI 분류 배지 안 나타남	classify worker 가 아직 큐 처리 안 함. `processing_queue` stage=classify pending 확인

5. 운영 1–2주 후 결정 사항

service token 발급 endpoint 신설: 단기 access token 만료가 자주 끊기면 별 PR.
frontend mic widget: 브라우저 직접 녹음 진입점 추가 (현재는 iOS Shortcuts 만).
녹음 자동 정리: 음성 메모 인입 빈도가 높아지면 archive 정책 또는 NAS 폴더 size 모니터링.
STT 한국어 정확도 평가: sample 5건 사용자 평가 후 large-v3 vs 다른 모델 (whisper-v3-turbo 등) 비교.

4.2 KiB Raw Blame History Unescape Escape