mirror of https://github.com/asyouplz/SpeechNote.git synced 2026-07-22 16:30:31 +00:00

asyouplz 7f776af999 Initial commit: Obsidian Speech-to-Text Plugin

- Set up project structure and architecture
- Implement core transcription services with OpenAI Whisper API
- Add comprehensive UI components and settings
- Create documentation in Korean and English
- Establish testing framework and examples

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

2025-08-25 20:00:43 +09:00

15 KiB

Raw Blame History

Obsidian Speech-to-Text Plugin

옵시디언에서 음성 파일을 텍스트로 변환하는 강력한 플러그인입니다.

Convert audio recordings to text directly in Obsidian using OpenAI's Whisper API.

English | 한국어

주요 기능 (Features)

🎙️ 음성 변환 (Audio Transcription)

지원 형식: M4A, MP3, WAV, MP4
최대 파일 크기: 25MB (Whisper API 제한)
고품질 변환: OpenAI Whisper 모델 활용

🌐 다국어 지원 (Multi-language Support)

자동 언어 감지: 음성 언어 자동 인식
수동 선택 가능: 한국어, 영어, 일본어, 중국어 등 지원
정확한 변환: 언어별 최적화된 모델 사용

📝 스마트 텍스트 삽입 (Smart Text Insertion)

커서 위치: 현재 커서 위치에 삽입
노트 시작/끝: 노트의 처음이나 끝에 추가
자동 생성: 활성 에디터가 없을 시 새 노트 생성

⚡ 성능 최적화 (Performance Optimization)

실시간 진행 표시: 상태바에 진행 상황 표시
비동기 처리: UI 차단 없는 백그라운드 처리
취소 가능: 진행 중인 변환 즉시 취소

💾 캐싱 시스템 (Caching System)

중복 방지: 동일 파일 재처리 방지
빠른 재사용: 캐시된 결과 즉시 활용
설정 가능: 캐시 활성화/비활성화 옵션

🎨 커스터마이징 (Customization)

타임스탬프: 인라인/사이드바 형식 선택
텍스트 포맷팅: 변환 결과 자동 정리
유연한 설정: 사용자 환경에 맞춘 조정

설치 방법 (Installation)

🏪 옵시디언 커뮤니티 플러그인 (Community Plugins) - 준비 중

설정(Settings) → 커뮤니티 플러그인(Community plugins) 열기
"Speech to Text" 검색
설치(Install) 후 활성화(Enable)

📦 수동 설치 (Manual Installation)

릴리즈 다운로드

최신 릴리즈 페이지에서 다운로드
압축 해제 후 파일들을 vault의 .obsidian/plugins/speech-to-text/ 폴더에 복사
옵시디언 재시작
설정 → 커뮤니티 플러그인에서 "Speech to Text" 활성화

개발 버전 설치

# 저장소 클론
git clone https://github.com/yourusername/obsidian-speech-to-text.git
cd obsidian-speech-to-text

# 의존성 설치
npm install

# 빌드
npm run build

# 플러그인 폴더로 복사 (예시)
cp main.js manifest.json styles.css /path/to/your/vault/.obsidian/plugins/speech-to-text/

초기 설정 (Setup)

🔑 API 키 설정 (API Key Configuration)

1. OpenAI API 키 발급

OpenAI Platform 접속
계정 로그인 또는 회원가입
"Create new secret key" 클릭
키 이름 입력 후 생성
생성된 키 복사 (⚠️ 한 번만 표시되므로 안전하게 저장)

2. 플러그인에 API 키 등록

옵시디언 설정 열기 (Cmd/Ctrl + ,)
왼쪽 메뉴에서 "Speech to Text" 선택
"OpenAI API Key" 필드에 키 입력
설정 저장

3. API 키 검증

올바른 형식: sk- 로 시작하는 48자 문자열
Whisper API 접근 권한 필요
유료 계정 또는 크레딧 필요

사용 방법 (Usage)

📋 기본 사용법 (Basic Usage)

음성 파일 변환

명령 팔레트 열기: Cmd/Ctrl + P
명령 검색: "Transcribe audio file" 입력
파일 선택: 목록에서 음성 파일 선택
변환 대기: 진행 상태바 확인
완료: 텍스트가 노트에 자동 삽입

빠른 실행 (Quick Actions)

단축키 설정: 설정 → 단축키에서 커스텀 키 지정
리본 아이콘: 왼쪽 리본에서 마이크 아이콘 클릭 (준비 중)
컨텍스트 메뉴: 오디오 파일 우클릭 → "Transcribe" (준비 중)

🎵 지원 오디오 형식 (Supported Formats)

형식	확장자	권장	최대 크기	설명
M4A	.m4a	✅	25MB	Apple 기기 기본 녹음 형식
MP3	.mp3	✅	25MB	범용 오디오 형식
WAV	.wav	⚠️	25MB	무손실, 파일 크기 큼
MP4	.mp4	⚠️	25MB	비디오 파일의 오디오 추출

📏 파일 크기 제한 (File Size Limits)

최대 크기: 25MB (Whisper API 제한)
권장 크기: 10MB 이하 (빠른 처리)
긴 녹음: 파일 분할 권장

💡 사용 팁 (Pro Tips)

녹음 품질: 조용한 환경에서 명확하게 녹음
파일 정리: 음성 파일을 전용 폴더에 보관
언어 설정: 특정 언어 고정 시 정확도 향상
캐시 활용: 동일 파일 재변환 시 캐시 사용

설정 옵션 (Settings)

⚙️ 주요 설정 (Main Settings)

설정	설명	기본값
API Key	OpenAI API 키	없음
Language	변환 언어 설정	자동 감지
Insert Position	텍스트 삽입 위치	커서 위치
Auto-insert	자동 텍스트 삽입	활성화
Timestamp Format	타임스탬프 형식	없음
Enable Cache	캐시 사용 여부	활성화
Max File Size	최대 파일 크기	25MB

🌍 언어 옵션 (Language Options)

auto: 자동 감지 (기본값)
ko: 한국어
en: 영어
ja: 일본어
zh: 중국어
es: 스페인어
fr: 프랑스어
de: 독일어

📍 삽입 위치 옵션 (Insert Position Options)

cursor: 현재 커서 위치
end: 노트 끝에 추가
beginning: 노트 시작에 추가

명령어 (Commands)

📌 사용 가능한 명령어

명령어	설명	단축키	상태
Transcribe audio file	음성 파일 선택 및 변환	설정 가능	✅ 사용 가능
Cancel transcription	진행 중인 변환 취소	설정 가능	✅ 사용 가능
Transcribe from clipboard	클립보드의 오디오 변환	-	🚧 개발 중
Show transcription history	변환 기록 보기	-	🚧 개발 중
Batch transcribe	여러 파일 일괄 변환	-	📋 계획 중
Export transcriptions	변환 결과 내보내기	-	📋 계획 중

개발 정보 (Development)

🔧 사전 요구사항 (Prerequisites)

항목	최소 버전	권장 버전	확인 명령
Node.js	16.0.0	18.x LTS	`node -v`
npm	7.0.0	9.x	`npm -v`
Obsidian	0.15.0	최신 버전	앱 정보 확인
TypeScript	4.7.4	5.x	`tsc -v`

🚀 개발 환경 설정 (Development Setup)

# 1. 저장소 클론
git clone https://github.com/yourusername/obsidian-speech-to-text.git
cd obsidian-speech-to-text

# 2. 의존성 설치
npm install

# 3. 개발 모드 실행 (파일 변경 감지)
npm run dev

# 4. 프로덕션 빌드
npm run build

# 5. 코드 품질 검사
npm run lint          # ESLint 실행
npm run lint:fix      # ESLint 자동 수정
npm run format        # Prettier 포맷팅
npm run format:check  # 포맷팅 검사

# 6. 테스트 실행
npm test              # 모든 테스트
npm run test:watch    # Watch 모드
npm run test:coverage # 커버리지 측정

# 7. 타입 체크
npm run typecheck

📁 프로젝트 구조 (Project Structure)

SpeechNote/
├── 📦 src/                          # 소스 코드
│   ├── 🎯 main.ts                   # 플러그인 진입점
│   ├── 💼 application/              # 애플리케이션 계층
│   │   ├── EventManager.ts         # 이벤트 관리
│   │   └── StateManager.ts         # 상태 관리
│   ├── 🧠 core/                     # 핵심 비즈니스 로직
│   │   └── transcription/
│   │       ├── AudioProcessor.ts   # 오디오 처리
│   │       ├── TextFormatter.ts    # 텍스트 포맷팅
│   │       └── TranscriptionService.ts # 변환 서비스
│   ├── 📊 domain/                   # 도메인 모델
│   │   └── models/
│   │       └── Settings.ts         # 설정 모델
│   ├── 🔌 infrastructure/          # 외부 시스템 통합
│   │   ├── api/
│   │   │   └── WhisperService.ts   # Whisper API 클라이언트
│   │   ├── logging/
│   │   │   └── Logger.ts           # 로깅 시스템
│   │   └── storage/
│   │       └── SettingsManager.ts  # 설정 영속성
│   ├── 🛠️ utils/                    # 유틸리티
│   │   └── ErrorHandler.ts         # 에러 처리
│   └── 📝 types/                    # 타입 정의
│       └── index.ts                # 공통 타입
├── 📚 docs/                         # 문서
│   ├── setup-guide.md              # 개발 환경 설정
│   ├── project-structure.md        # 프로젝트 구조
│   └── api-reference.md            # API 문서
├── 🏗️ architecture/                 # 아키텍처 문서
│   ├── system-design.md            # 시스템 설계
│   └── diagrams/                   # 다이어그램
├── 📋 guidelines/                   # 가이드라인
│   └── development-guide.md        # 개발 가이드
├── 🧪 tests/                        # 테스트 (준비 중)
├── ⚙️ 설정 파일
│   ├── manifest.json               # 플러그인 메타데이터
│   ├── package.json                # 프로젝트 설정
│   ├── tsconfig.json               # TypeScript 설정
│   ├── esbuild.config.mjs          # 빌드 설정
│   └── jest.config.js              # 테스트 설정
└── 📄 문서
    ├── README.md                   # 프로젝트 소개
    └── CONTRIBUTING.md             # 기여 가이드

문제 해결 (Troubleshooting)

❗ 자주 발생하는 문제 (Common Issues)

🔑 "Invalid API Key" 오류

증상: API 키 인증 실패

해결 방법:

API 키가 sk-로 시작하는지 확인
OpenAI 대시보드에서 키 상태 확인
키 앞뒤 공백 제거
Whisper API 사용 권한 확인
크레디트 또는 결제 정보 확인

📁 "File too large" 오류

증상: 25MB 초과 파일 업로드 실패

해결 방법:

파일 크기 확인 (최대 25MB)

음성 파일 압축:

# FFmpeg를 사용한 압축
ffmpeg -i input.m4a -b:a 128k output.m4a

긴 녹음 분할:
- 10-15분 단위로 녹음
- 오디오 편집 도구 사용

🎵 "No Audio Files Found" 오류

증상: 음성 파일이 목록에 표시되지 않음

해결 방법:

지원 형식 확인: .m4a, .mp3, .wav, .mp4
파일이 vault 내부에 있는지 확인
옵시디언 재시작 (Cmd/Ctrl + R)
파일 인덱싱 대기 (큰 vault의 경우)

🌐 네트워크 오류

증상: "Network Error" 또는 타임아웃

해결 방법:

인터넷 연결 확인
VPN/프록시 설정 확인
방화벽 설정 확인
OpenAI API 상태 확인: status.openai.com

⚡ 변환 속도 느림

증상: 변환이 예상보다 오래 걸림

해결 방법:

파일 크기 최적화 (10MB 이하 권장)
음질 설정 조정
캐시 기능 활성화
네트워크 속도 확인

기여하기 (Contributing)

🤝 기여 환영!

이 프로젝트는 커뮤니티 기여를 환영합니다. 기여 가이드를 참고해주세요.

📝 기여 방법

Fork: 저장소 Fork

Branch: 기능 브랜치 생성

git checkout -b feature/amazing-feature

Commit: 변경사항 커밋

git commit -m 'feat: add amazing feature'

Push: 브랜치에 푸시

git push origin feature/amazing-feature

PR: Pull Request 생성

🏷️ 커밋 컨벤션

feat: 새로운 기능
fix: 버그 수정
docs: 문서 변경
style: 코드 스타일 변경
refactor: 리팩토링
test: 테스트 추가/수정
chore: 빌드, 설정 변경

라이선스 (License)

이 프로젝트는 MIT 라이선스를 따릅니다. 자세한 내용은 LICENSE 파일을 참조하세요.

This project is licensed under the MIT License - see the LICENSE file for details.

크레딧 (Credits)

🙏 감사의 말

Obsidian Team: Obsidian Plugin API 제공
OpenAI: Whisper API 제공
Community: 옵시디언 커뮤니티의 피드백과 기여
Contributors: 모든 기여자들께 감사드립니다

🛠️ 사용된 기술

TypeScript
ESBuild
Jest
ESLint & Prettier

지원 (Support)

📞 도움이 필요하신가요?

🐛 버그 제보: GitHub Issues
💡 기능 제안: Feature Requests
💬 토론 참여: Discussions
📖 문서 읽기: Documentation
❓ FAQ: 자주 묻는 질문
📧 이메일: support@example.com

🌟 프로젝트 지원

이 프로젝트가 도움이 되셨다면:

⭐ GitHub에 Star 주기
🐦 소셜 미디어에 공유
☕ Buy me a coffee

변경 사항 (Changelog)

📋 최신 버전: v1.0.0 (2025-08-22)

✨ 주요 기능

음성 파일을 텍스트로 변환
OpenAI Whisper API 통합
다국어 지원 (자동 감지)
유연한 텍스트 삽입 옵션
캐싱 시스템

전체 변경 내역은 CHANGELOG.md를 참조하세요.

로드맵 (Roadmap)

🎯 개발 계획

📅 v1.1.0 (2025 Q1)

📋 클립보드 오디오 지원
📊 변환 기록 뷰어
🔄 일괄 처리 기능
🎨 UI/UX 개선

📅 v1.2.0 (2025 Q2)

💬 커스텀 프롬프트 지원
🔍 검색 가능한 변환 아카이브
📈 변환 통계 대시보드
🌍 추가 언어 지원

📅 v2.0.0 (2025 하반기)

⚡ 실시간 변환 (스트리밍)
🖥️ 로컬 모델 지원
🤖 AI 요약 기능
🔗 타 플러그인 연동

💭 검토 중인 기능

화자 분리 (diarization)
음성 명령 지원
자동 노트 생성
템플릿 시스템

Made with ❤️ for the Obsidian community

옵시디언 커뮤니티를 위해 정성을 다해 만들었습니다.

⬆ 맨 위로

15 KiB Raw Blame History

Obsidian Speech-to-Text Plugin

주요 기능 (Features)

🎙️ 음성 변환 (Audio Transcription)

🌐 다국어 지원 (Multi-language Support)

📝 스마트 텍스트 삽입 (Smart Text Insertion)

⚡ 성능 최적화 (Performance Optimization)

💾 캐싱 시스템 (Caching System)

🎨 커스터마이징 (Customization)

설치 방법 (Installation)

🏪 옵시디언 커뮤니티 플러그인 (Community Plugins) - 준비 중

📦 수동 설치 (Manual Installation)

릴리즈 다운로드

개발 버전 설치

초기 설정 (Setup)

🔑 API 키 설정 (API Key Configuration)

1. OpenAI API 키 발급

2. 플러그인에 API 키 등록

3. API 키 검증

사용 방법 (Usage)

📋 기본 사용법 (Basic Usage)

음성 파일 변환

빠른 실행 (Quick Actions)

🎵 지원 오디오 형식 (Supported Formats)

📏 파일 크기 제한 (File Size Limits)

💡 사용 팁 (Pro Tips)

설정 옵션 (Settings)

⚙️ 주요 설정 (Main Settings)

🌍 언어 옵션 (Language Options)

📍 삽입 위치 옵션 (Insert Position Options)

명령어 (Commands)

📌 사용 가능한 명령어

개발 정보 (Development)

🔧 사전 요구사항 (Prerequisites)

🚀 개발 환경 설정 (Development Setup)

📁 프로젝트 구조 (Project Structure)

문제 해결 (Troubleshooting)

❗ 자주 발생하는 문제 (Common Issues)

🔑 "Invalid API Key" 오류

📁 "File too large" 오류

🎵 "No Audio Files Found" 오류

🌐 네트워크 오류

⚡ 변환 속도 느림

기여하기 (Contributing)

🤝 기여 환영!

📝 기여 방법

🏷️ 커밋 컨벤션

라이선스 (License)

크레딧 (Credits)

🙏 감사의 말

🛠️ 사용된 기술

지원 (Support)

📞 도움이 필요하신가요?

🌟 프로젝트 지원

변경 사항 (Changelog)

📋 최신 버전: v1.0.0 (2025-08-22)

✨ 주요 기능

로드맵 (Roadmap)

🎯 개발 계획

📅 v1.1.0 (2025 Q1)

📅 v1.2.0 (2025 Q2)

📅 v2.0.0 (2025 하반기)

💭 검토 중인 기능

15 KiB

Raw Blame History