🎵 Audio To Tidied Notes (ATTN)

📖 Language / 언어: English | 한국어 | 📋 Documentation: PRD (English) | PRD (한국어)

🚀 TDD로 구축된 고품질 Obsidian 플러그인 M4A 오디오 파일을 5가지 STT 엔진(OpenAI, Gemini, Groq, Local Whisper, Local MLX)을 통해 체계적인 회의록으로 자동 변환

✨ 핵심 기능

⚡ 5가지 STT 제공자 지원 (v2.0 Phase 5A NEW!)

• 🍎 Local MLX (Apple Silicon 전용): 16.45x realtime, 무료, 무제한
• ⚡ Groq: 70x realtime, 초고속 클라우드 처리
• 💎 Google Gemini: 2GB 파일 지원, 81% 저렴
• 🔒 OpenAI Whisper: 최고 안정성과 품질
• 🏠 Local Whisper: 완전 오프라인, 크로스 플랫폼

🎯 원클릭 자동화

• M4A 파일 우클릭 → "ATTN: 노트 생성하기" 선택만으로 완료
• 다양한 STT 엔진으로 음성을 텍스트로 변환
• GPT-4로 구조화된 회의록 자동 생성

🛠️ 고급 커스터마이징 (v2.0 NEW!)

• 📁 저장 폴더 경로: 생성될 노트 저장 위치 자유 설정
• 📝 파일명 템플릿: 플레이스홀더로 동적 파일명 생성
• 🎨 노트 내용 템플릿: 완전 맞춤형 노트 구조 디자인

🔧 템플릿 엔진

사용 가능한 플레이스홀더:

{{filename}}        - 원본 오디오 파일명
{{summary}}          - AI 생성 요약
{{transcript}}       - 전체 텍스트 (향후 지원)
{{date:YYYY-MM-DD}}  - 날짜 (다양한 형식 지원)
{{time:HH:mm}}       - 시간 (다양한 형식 지원)

템플릿 예시:

📁 저장 폴더: "회의록/{{date:YYYY}}/{{date:MM월}}"
📄 파일명 템플릿: "{{date:MM-DD}}-{{filename}}"
📝 내용 템플릿:
# 📅 {{date:YYYY년 MM월 DD일}} 회의록

**🎵 원본 파일:** {{filename}}  
**⏰ 생성 시각:** {{time:HH:mm}}

## 📋 요약
{{summary}}

---
*🤖 ATTN 플러그인으로 자동 생성됨*

🌍 다국어 지원

• 한국어 최적화: 한국어 음성 인식 및 요약에 특화
• 다른 언어도 OpenAI API 지원 범위 내에서 동작

🔐 보안

• API 키 로컬 저장 (안전한 Obsidian 플러그인 데이터)
• 외부 서버에 데이터 저장하지 않음 (OpenAI 처리 제외)

📦 설치 방법

수동 설치(현재 가능한 방법)

1. 필요한 파일 다운로드

GitHub 릴리스 페이지에서 최신 버전의 다음 파일들을 다운로드하세요:

• manifest.json
• main.js
• styles.css (있는 경우)

또는 전체 소스를 원하는 경우:

• scripts/ 디렉토리
• src/ 디렉토리

2. 플러그인 폴더 생성 및 파일 복사

1. Obsidian 볼트의 플러그인 디렉토리 찾기:

   [볼트 경로]/.obsidian/plugins/
   

2. 새 플러그인 폴더 생성:

   [볼트 경로]/.obsidian/plugins/audio-to-tidied-notes/
   

3. 다운로드한 파일들을 새로 생성한 폴더에 복사

3. 플러그인 활성화

1. Obsidian 설정 → Community plugins 이동
2. "Reload plugins" 버튼 클릭 (또는 Obsidian 재시작)
3. 플러그인 목록에서 "Audio To Tidied Notes" 찾기
4. 활성화 토글을 ON으로 설정

4. 설정 완료 확인

• 활성화 후 우측 설정에서 "Audio To Tidied Notes" 설정 탭이 나타나는지 확인
• M4A 파일을 우클릭했을 때 "ATTN: 요약 노트 생성하기" 메뉴가 나타나는지 확인

⚙️ 초기 설정

STT 제공자 선택 및 설정

🍎 Local MLX (Apple Silicon 전용 - 권장)

필수 요구사항:

• Apple Silicon Mac (M1/M2/M3)
• Python 3.9 이상
• macOS 12.0+

설치:

# Python 확인
python3 --version

# MLX Whisper 설치
cd /path/to/attn-obsidian/python
python3 -m venv venv
source venv/bin/activate
pip install mlx-whisper

ATTN 설정:

1. STT Provider → "Local MLX" 선택
2. Python Path: 가상환경 경로 지정 (예: .../venv/bin/python3)
3. Model: medium (권장) 또는 다른 크기 선택

성능: 16.45x realtime, 무료, 무제한 파일

📖 상세 가이드: MANUAL-ko.md 참조

⚡ Groq (70x 초고속)

• Groq Console에서 API 키 발급
• 무료 티어 사용 가능
• 25MB 파일 크기 제한

💎 Google Gemini (2GB 지원)

• Google AI Studio에서 API 키 발급
• 무료 티어 사용 가능 (제한적)
• 2GB 파일까지 청킹 없이 처리

🔒 OpenAI Whisper (최고 안정성)

• OpenAI Platform에서 API 키 생성
• 결제 방법 등록 필요 (사용량 기반 과금)
• 25MB 파일 크기 제한

🏠 Local Whisper (완전 오프라인)

• whisper.cpp 기반
• 크로스 플랫폼 지원 (Intel Mac, Windows, Linux)
• 무료, 무제한

선택 사항

FFmpeg 설치 (오디오 속도 조절용, 선택사항)

# macOS (Homebrew)
brew install ffmpeg

# Windows (Chocolatey)
choco install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

FFmpeg 경로 확인:

# 설치된 FFmpeg 경로 확인
which ffmpeg          # macOS/Linux
where ffmpeg          # Windows

3. 플러그인 설정

   Obsidian 설정 → Community Plugins → Audio To Tidied Notes
   
   📝 기본 설정:
   - OpenAI API Key: sk-... (필수)
   - 저장 폴더 경로: / (루트)
   - 파일명 템플릿: {{date:YYYY-MM-DD}}-{{filename}}-회의록
   - 내용 템플릿: (기본 회의록 형식)
   - 오디오 속도 배수: 1x (기본) / 2x / 3x
   - FFmpeg 경로: (선택사항, 자동 감지 실패시 수동 설정)
   

🚀 사용 방법

기본 사용법

1. M4A 파일을 Obsidian 볼트에 추가
2. 파일 탐색기에서 우클릭
3. "ATTN: 요약 노트 생성하기" 선택
4. 처리 완료까지 대기 (진행률 알림 표시)
5. 자동 생성된 체계적인 회의록 확인! 🎉

고급 커스터마이징 예시

비즈니스 미팅용 템플릿:

📁 저장 폴더: "Business/Meetings/{{date:YYYY}}"
📄 파일명: "{{date:MM-DD}}-{{filename}}"
📝 내용:
# 📊 비즈니스 미팅 - {{date:YYYY.MM.DD}}

**참석자 파일:** {{filename}}  
**일시:** {{date:YYYY년 MM월 DD일}} {{time:HH:mm}}

## 🎯 핵심 요약
{{summary}}

## 📋 액션 아이템
- [ ] TBD (요약에서 추출)

---
**다음 미팅:** 미정  
*🤖 Generated by ATTN*

스터디 그룹용 템플릿:

📁 저장 폴더: "Study/{{date:YYYY}}/{{date:MM월}}"
📄 파일명: "Week{{date:WW}}-{{filename}}"
📝 내용:
# 📚 스터디 노트

**날짜:** {{date:YYYY-MM-DD (ddd)}}  
**시간:** {{time:HH:mm}}  
**파일:** {{filename}}

## 💡 주요 내용
{{summary}}

## 📝 메모
- 

---
*📖 Study Group*

🧪 개발자 정보

TDD 방법론으로 구축된 고품질 코드베이스

✅ Jest 기반 종합 테스트 스위트 구축
✅ TypeScript 기반 type-safe 구현
✅ ESLint + Prettier 코드 품질 관리
✅ GitHub Actions CI/CD 자동화
✅ 모듈식 아키텍처 (확장성 & 유지보수성)

테스트 실행 방법:

# 의존성 설치 (최초 1회)
npm install

# 테스트 실행
npm test

# 커버리지 포함 테스트
npm test -- --coverage

# 타입 체크
npm run typecheck

# 린트 검사
npm run lint

개발 환경 설정

# 리포지토리 클론
git clone https://github.com/bongho/attn-obsidian.git
cd attn-obsidian

# 의존성 설치
npm install

# 개발 모드 실행 (Hot reload)
npm run dev

# 프로덕션 빌드
npm run build

⚠️ npm 설치 시 권한 오류가 발생하는 경우:

# macOS/Linux
sudo chown -R $USER:$(id -gn $USER) ~/.npm

# 또는 강제 설치
npm install --force

품질 검증:

# 전체 테스트 실행
npm test

# 커버리지 포함
npm test -- --coverage

# 타입 체크
npm run typecheck

# 린트 검사
npm run lint

프로젝트 구조

ATTN/
├── src/                          # 📁 소스 코드
│   ├── main.ts                  # 🎭 오케스트레이터 (모든 모듈 조율)
│   ├── settings.ts              # ⚙️ 설정 UI 관리
│   ├── templateProcessor.ts     # 🎨 템플릿 엔진 (NEW!)
│   ├── apiService.ts            # 🤖 OpenAI API 연동
│   ├── noteCreator.ts           # 📝 노트 생성 (리팩토링됨)
│   └── types.ts                 # 📋 TypeScript 인터페이스
├── tests/                       # 🧪 TDD 테스트 스위트
│   ├── TemplateProcessor.test.ts # 🆕 템플릿 엔진 테스트
│   ├── SettingsTab.test.ts      # 📈 확장된 설정 테스트
│   ├── ApiService.test.ts       # 🔄 API 로직 테스트
│   ├── NoteCreator.test.ts      # 🔄 노트 생성 테스트
│   └── main.test.ts             # 🔄 통합 테스트
├── package.json                 # 📦 의존성 관리
├── tsconfig.json               # ⚙️ TypeScript 설정
├── jest.config.js              # 🧪 테스트 설정
└── main.js                     # 🚀 빌드된 플러그인

💰 API 사용 비용

OpenAI API 사용료:

• Whisper API: ~$0.006/분 (음성 → 텍스트)
• GPT-4 API: 텍스트 길이에 따라 변동 (요약 생성)

예시: 30분 회의 → 약 $0.20~0.50

🏗️ 아키텍처 특징

Before & After 비교

TDD 개발 성과

🧪 Phase 1: Settings Enhancement & Template Engine
  ✅ ATTNSettings 인터페이스 확장
  ✅ SettingsTab UI 컴포넌트 추가
  ✅ TemplateProcessor 모듈 구현

🔄 Phase 2: Core Logic Refactoring  
  ✅ NoteCreator 책임 단순화
  ✅ main.ts 오케스트레이터 패턴 적용
  ✅ 모듈 간 결합도 최소화

✨ Result: 확장 가능하고 유지보수가 용이한 아키텍처

🤝 기여하기

1. Fork 리포지토리
2. Feature branch 생성 (git checkout -b feature/amazing-feature)
3. Tests 먼저 작성 (TDD 방식)
4. 구현 및 테스트 통과 확인
5. Commit (git commit -m 'Add some amazing feature')
6. Push (git push origin feature/amazing-feature)
7. Pull Request 생성

기여 가이드라인

• ✅ TDD 필수: 테스트를 먼저 작성해주세요
• ✅ TypeScript: 타입 안전성을 유지해주세요
• ✅ ESLint: 코드 스타일을 준수해주세요
• ✅ 테스트 커버리지: 새 기능은 90% 이상 커버리지 유지

📄 라이선스

MIT License - 자세한 내용은 LICENSE 파일 참조

🙋‍♂️ 지원 & 문의

문제 해결

1. 콘솔 에러 메시지 확인
2. OpenAI API 키 및 크레딧 상태 확인
3. GitHub Issues에 상세한 정보와 함께 문의

연락처

• 🐛 버그 리포트: GitHub Issues
• 💡 기능 요청: GitHub Discussions
• 📧 기타 문의: bongho@example.com

📊 성능 벤치마크 (Phase 5A)

테스트 환경: M2 Max, 50분 오디오 파일

🎯 권장 사용 시나리오

• Apple Silicon 사용자: Local MLX (최고 성능 + 무료)
• 긴 오디오 (1시간+): Gemini (2GB 제한, 청킹 불필요)
• 최고 속도: Groq (70x realtime)
• 완전 오프라인: Local Whisper

📈 업데이트 로드맵

v2.0 Phase 5A (완료) ✅

• 5가지 STT 제공자 지원
• Local MLX Whisper (Apple Silicon 최적화)
• CoreML 하이브리드 아키텍처 (선택사항)
• 16.45x realtime 처리 속도
• Settings UI에 Local MLX 추가

v2.1 (계획)

• Transcript 전문 텍스트 템플릿 지원
• 배치 처리 자동화
• 커스텀 프롬프트 설정
• CoreML 모델 자동 생성

v2.2 (계획)

• 화자 인식 기능 (Diarization)
• 실시간 오디오 처리
• VAD (Voice Activity Detection) 최적화

---