asyouplz_SpeechNote/docs/api-reference.md

API 레퍼런스 (API Reference)

목차

1. 개요
2. 핵심 클래스
3. 서비스 인터페이스
4. 유틸리티 함수
5. 타입 정의
6. 이벤트 시스템
7. 에러 처리
8. 설정 옵션

---

개요

이 문서는 Obsidian Speech-to-Text 플러그인의 주요 API를 설명합니다. 모든 public 클래스, 메서드, 인터페이스에 대한 상세 정보를 제공합니다.

API 버전

• 현재 버전: 3.0.0
• 최소 Obsidian 버전: 0.15.0
• TypeScript 버전: 5.0.4
• 지원 Provider: OpenAI Whisper, Deepgram Nova 2

---

핵심 클래스

SpeechToTextPlugin

플러그인의 메인 클래스입니다.

class SpeechToTextPlugin extends Plugin {
  settings: SpeechToTextSettings;
  
  /**
   * 플러그인 로드 시 호출됩니다.
   */
  async onload(): Promise<void>
  
  /**
   * 플러그인 언로드 시 호출됩니다.
   */
  onunload(): void
  
  /**
   * 설정을 로드합니다.
   */
  async loadSettings(): Promise<void>
  
  /**
   * 설정을 저장합니다.
   */
  async saveSettings(): Promise<void>
}

사용 예제

// 플러그인 인스턴스는 Obsidian이 자동으로 생성합니다
export default class MyPlugin extends SpeechToTextPlugin {
  async onload() {
    await super.onload();
    // 추가 초기화 로직
  }
}

---

서비스 인터페이스 (Service Interfaces)

ITranscriber 인터페이스

모든 음성 변환 Provider가 구현해야 하는 공통 인터페이스입니다.

interface ITranscriber {
  /**
   * Provider 이름
   */
  readonly name: string;
  
  /**
   * 음성을 텍스트로 변환합니다.
   * @param audio - 오디오 버퍼 데이터
   * @param options - Provider별 옵션
   * @returns 변환된 텍스트와 메타데이터
   */
  transcribe(
    audio: ArrayBuffer,
    options?: TranscriptionOptions
  ): Promise<TranscriptionResponse>;
  
  /**
   * Provider 상태를 확인합니다.
   */
  isAvailable(): Promise<boolean>;
  
  /**
   * 지원하는 파일 형식을 반환합니다.
   */
  getSupportedFormats(): string[];
  
  /**
   * 최대 파일 크기를 반환합니다.
   */
  getMaxFileSize(): number;
  
  /**
   * 진행 중인 요청을 취소합니다.
   */
  cancel(): void;
}

Provider별 기능 비교

기능	Whisper	Deepgram
최대 파일 크기	25MB	2GB
지원 형식	m4a, mp3, wav, mp4	m4a, mp3, wav, mp4, webm, ogg, flac
언어 지원	50+ 언어	40+ 언어
실시간 스트리밍	❌	✅ (예정)
화자 분리	❌	✅
자동 문장부호	✅	✅
단어 타임스탬프	✅	✅
API 응답 속도	중간	빠름
비용	$0.006/분	$0.0043/분

WhisperAdapter

OpenAI Whisper API를 위한 어댑터 클래스입니다.

class WhisperService implements IWhisperService {
  /**
   * 오디오를 텍스트로 변환합니다.
   * @param audio - 오디오 버퍼 데이터
   * @param options - Whisper API 옵션
   * @returns 변환된 텍스트와 메타데이터
   * @throws {WhisperAPIError} API 호출 실패 시
   * @throws {FileTooLargeError} 파일 크기 초과 시
   * @example
   * const result = await whisperService.transcribe(audioBuffer, {
   *   language: 'ko',
   *   responseFormat: 'verbose_json'
   * });
   */
  async transcribe(
    audio: ArrayBuffer, 
    options?: WhisperOptions
  ): Promise<WhisperResponse>;
  
  /**
   * API 키 유효성을 검증합니다.
   * @param key - OpenAI API 키
   * @returns 유효성 여부
   */
  async validateApiKey(key: string): Promise<boolean>;
  
  /**
   * 진행 중인 요청을 취소합니다.
   */
  cancel(): void;
  
  /**
   * Circuit Breaker를 리셋합니다.
   */
  resetCircuitBreaker(): void;
}

TranscriptionOptions 상세

interface TranscriptionOptions {
  // 공통 옵션
  provider?: 'whisper' | 'deepgram' | 'auto';  // Provider 선택
  language?: string;              // 언어 코드 (ko, en, ja 등)
  
  // Whisper 전용 옵션
  model?: 'whisper-1';           // Whisper 모델
  prompt?: string;                // 컨텍스트 프롬프트 (최대 224 토큰)
  temperature?: number;           // 0-1 사이 값, 창의성 조절
  responseFormat?: 'json' | 'text' | 'verbose_json';  // 응답 형식
  
  // Deepgram 전용 옵션
  tier?: 'nova-2' | 'nova' | 'enhanced' | 'base';  // Deepgram 티어
  punctuate?: boolean;            // 자동 문장부호
  diarize?: boolean;              // 화자 분리
  smart_format?: boolean;         // 스마트 포매팅
  utterances?: boolean;           // 발화 구분
  detect_language?: boolean;      // 자동 언어 감지
}

DeepgramAdapter

Deepgram Nova 2 API를 위한 어댑터 클래스입니다.

class DeepgramAdapter implements ITranscriber {
  readonly name = 'deepgram';
  
  /**
   * Deepgram API를 사용하여 음성을 변환합니다.
   * @param audio - 오디오 버퍼
   * @param options - Deepgram 옵션
   * @example
   * const result = await deepgramAdapter.transcribe(audioBuffer, {
   *   language: 'ko',
   *   tier: 'nova-2',
   *   smart_format: true
   * });
   */
  async transcribe(
    audio: ArrayBuffer,
    options?: TranscriptionOptions
  ): Promise<TranscriptionResponse>;
  
  /**
   * 실시간 스트리밍 변환을 시작합니다.
   * @param stream - 오디오 스트림
   * @param onResult - 결과 콜백
   */
  async startStreaming(
    stream: ReadableStream,
    onResult: (result: Partial<TranscriptionResponse>) => void
  ): Promise<void>;
}

ITranscriptionService

음성 변환 서비스의 인터페이스입니다.

interface ITranscriptionService {
  /**
   * 오디오 파일을 텍스트로 변환합니다.
   * @param file - 변환할 오디오 파일
   * @returns 변환 결과
   */
  transcribe(file: TFile): Promise<TranscriptionResult>;
  
  /**
   * 진행 중인 변환을 취소합니다.
   */
  cancel(): void;
  
  /**
   * 현재 변환 상태를 반환합니다.
   */
  getStatus(): TranscriptionStatus;
}

구현 예제

class TranscriptionService implements ITranscriptionService {
  async transcribe(file: TFile): Promise<TranscriptionResult> {
    // 1. 파일 검증
    const isValid = await this.audioProcessor.validate(file);
    if (!isValid) {
      throw new ValidationError('Invalid audio file');
    }
    
    // 2. 오디오 처리
    const processedAudio = await this.audioProcessor.process(file);
    
    // 3. API 호출
    const response = await this.whisperService.transcribe(
      processedAudio.buffer,
      { language: this.settings.language }
    );
    
    // 4. 텍스트 포맷팅
    const formattedText = this.textFormatter.format(response.text);
    
    return {
      text: formattedText,
      language: response.language,
      duration: processedAudio.metadata.duration
    };
  }
}

SettingsManager

플러그인 설정을 관리하며 API 키 암호화를 담당합니다.

class SettingsManager implements ISettingsManager {
  /**
   * 설정을 로드합니다.
   * @returns 로드된 설정 객체
   * @example
   * const settings = await settingsManager.load();
   * console.log(settings.language); // 'ko'
   */
  async load(): Promise<PluginSettings>;
  
  /**
   * 설정을 저장합니다.
   * @param settings - 저장할 설정 객체
   */
  async save(settings: PluginSettings): Promise<void>;
  
  /**
   * 특정 설정 값을 가져옵니다.
   * @param key - 설정 키
   * @returns 설정 값
   */
  get<K extends keyof PluginSettings>(key: K): PluginSettings[K];
  
  /**
   * 특정 설정 값을 업데이트합니다.
   * @param key - 설정 키
   * @param value - 새로운 값
   */
  async set<K extends keyof PluginSettings>(
    key: K, 
    value: PluginSettings[K]
  ): Promise<void>;
  
  /**
   * API 키를 안전하게 설정합니다.
   * @param apiKey - OpenAI API 키
   * @returns 설정 성공 여부
   */
  async setApiKey(apiKey: string): Promise<boolean>;
  
  /**
   * 마스킹된 API 키를 반환합니다.
   * @returns 마스킹된 키 (예: "sk-XXXXX...XXXX")
   */
  getMaskedApiKey(): string;
  
  /**
   * 설정 유효성을 검증합니다.
   * @returns 검증 결과와 에러 목록
   */
  validateSettings(): { valid: boolean; errors: string[] };
  
  /**
   * 설정을 초기값으로 리셋합니다.
   */
  async reset(): Promise<void>;
}

PluginSettings 타입

interface PluginSettings {
  // Provider 설정
  provider: 'whisper' | 'deepgram' | 'auto';  // Provider 선택
  openaiApiKey?: string;         // OpenAI API 키
  deepgramApiKey?: string;       // Deepgram API 키
  encryptedOpenaiKey?: string;   // 암호화된 OpenAI 키
  encryptedDeepgramKey?: string; // 암호화된 Deepgram 키
  
  // Whisper 설정
  whisperModel: 'whisper-1';     // Whisper 모델
  whisperPrompt?: string;         // Whisper 프롬프트
  whisperTemperature?: number;    // Whisper 온도
  
  // Deepgram 설정
  deepgramTier: 'nova-2' | 'nova' | 'enhanced' | 'base';  // Deepgram 티어
  deepgramPunctuate: boolean;     // 자동 문장부호
  deepgramDiarize: boolean;       // 화자 분리
  deepgramSmartFormat: boolean;   // 스마트 포매팅
  
  // 공통 설정
  language: string;              // 기본 언어 (auto, ko, en 등)
  autoInsert: boolean;           // 자동 삽입 여부
  insertPosition: 'cursor' | 'end' | 'beginning';  // 삽입 위치
  timestampFormat: 'none' | 'inline' | 'sidebar';  // 타임스탬프 형식
  maxFileSize: number;           // 최대 파일 크기 (바이트)
  enableCache: boolean;          // 캐시 활성화
  cacheTTL: number;             // 캐시 유효 시간 (밀리초)
  enableDebugLogging: boolean;  // 디버그 로깅
  enableFallback: boolean;       // Fallback Provider 사용
  smartRouting: boolean;         // 스마트 라우팅 사용
}

TranscriberFactory

Provider 선택과 인스턴스 생성을 담당하는 팩토리 클래스입니다.

class TranscriberFactory {
  /**
   * 지정된 Provider의 인스턴스를 생성합니다.
   * @param provider - Provider 이름
   * @param settings - 설정 객체
   * @returns Transcriber 인스턴스
   */
  static create(
    provider: 'whisper' | 'deepgram' | 'auto',
    settings: PluginSettings
  ): ITranscriber;
  
  /**
   * 파일에 가장 적합한 Provider를 선택합니다.
   * @param file - 오디오 파일
   * @param settings - 설정 객체
   * @returns 최적 Provider
   */
  static selectBestProvider(
    file: TFile,
    settings: PluginSettings
  ): 'whisper' | 'deepgram';
  
  /**
   * 모든 사용 가능한 Provider를 반환합니다.
   * @param settings - 설정 객체
   * @returns 사용 가능한 Provider 목록
   */
  static getAvailableProviders(
    settings: PluginSettings
  ): string[];
}

ProviderSelector

파일 특성에 따른 최적 Provider 선택 로직을 구현합니다.

class ProviderSelector {
  /**
   * 파일 크기와 형식을 고려하여 최적 Provider를 선택합니다.
   * @param fileInfo - 파일 정보
   * @param preferences - 사용자 선호
   * @returns 추천 Provider
   */
  selectProvider(
    fileInfo: FileInfo,
    preferences: ProviderPreferences
  ): ProviderRecommendation;
  
  /**
   * Provider 성능 메트릭을 반환합니다.
   */
  getProviderMetrics(): Map<string, ProviderMetrics>;
  
  /**
   * Fallback 체인을 구성합니다.
   * @param primary - 기본 Provider
   * @returns Fallback Provider 순서
   */
  getFallbackChain(primary: string): string[];
}

FileUploadManager

대용량 오디오 파일 처리 및 업로드를 관리합니다. Provider별 최적화를 지원합니다.

class FileUploadManager {
  /**
   * 오디오 파일을 준비하고 처리합니다.
   * @param file - 처리할 오디오 파일
   * @param onProgress - 진행 상황 콜백
   * @returns 처리된 오디오 데이터
   * @throws {Error} 파일 검증 실패 시
   * @example
   * const processed = await uploadManager.prepareAudioFile(file, (progress) => {
   *   console.log(`${progress.percentage}% - ${progress.message}`);
   * });
   */
  async prepareAudioFile(
    file: TFile,
    onProgress?: ProgressCallback
  ): Promise<ProcessedAudioFile>;
  
  /**
   * 청크 단위로 파일을 업로드합니다.
   * @param buffer - 업로드할 버퍼
   * @param chunkSize - 청크 크기 (기본 5MB)
   * @yields 각 청크 데이터
   */
  async *uploadInChunks(
    buffer: ArrayBuffer,
    chunkSize?: number
  ): AsyncGenerator<ArrayBuffer, void, unknown>;
  
  /**
   * 진행 중인 업로드를 취소합니다.
   */
  cancel(): void;
  
  /**
   * 리소스를 정리합니다.
   */
  cleanup(): void;
}

ProcessedAudioFile 타입

interface ProcessedAudioFile {
  buffer: ArrayBuffer;           // 처리된 오디오 버퍼
  metadata: AudioFileMetadata;   // 파일 메타데이터
  compressed: boolean;           // 압축 여부
  originalSize: number;          // 원본 크기 (바이트)
  processedSize: number;         // 처리 후 크기 (바이트)
}

interface AudioFileMetadata {
  name: string;                  // 파일명
  path: string;                  // 파일 경로
  extension: string;             // 확장자
  mimeType: string;              // MIME 타입
  duration?: number;             // 재생 시간 (초)
  sampleRate?: number;           // 샘플링 레이트
  bitrate?: number;              // 비트레이트 (kbps)
  channels?: number;             // 채널 수
}

Provider별 지원 형식

형식	Whisper	Deepgram	최대 크기
m4a	✅	✅	25MB/2GB
mp3	✅	✅	25MB/2GB
wav	✅	✅	25MB/2GB
mp4	✅	✅	25MB/2GB
webm	❌	✅	-/2GB
ogg	❌	✅	-/2GB
flac	❌	✅	-/2GB

• 압축 방식:
  • Whisper: Web Audio API (16kHz 모노)
  • Deepgram: 원본 품질 유지 가능

EditorService

Obsidian 에디터와의 통합을 담당하며 텍스트 삽입, 커서 관리, Undo/Redo를 지원합니다.

class EditorService {
  /**
   * 활성 에디터를 가져옵니다.
   * @returns 현재 활성 에디터 또는 null
   */
  getActiveEditor(): Editor | null;
  
  /**
   * 커서 위치에 텍스트를 삽입합니다.
   * @param text - 삽입할 텍스트
   * @param recordHistory - 히스토리 기록 여부
   * @returns 삽입 성공 여부
   * @example
   * await editorService.insertAtCursor("변환된 텍스트");
   */
  async insertAtCursor(
    text: string, 
    recordHistory?: boolean
  ): Promise<boolean>;
  
  /**
   * 선택 영역을 대체합니다.
   * @param text - 대체할 텍스트
   * @param recordHistory - 히스토리 기록 여부
   */
  async replaceSelection(
    text: string, 
    recordHistory?: boolean
  ): Promise<boolean>;
  
  /**
   * 특정 위치에 텍스트를 삽입합니다.
   * @param text - 삽입할 텍스트
   * @param position - 삽입 위치
   */
  async insertAtPosition(
    text: string,
    position: EditorPosition,
    recordHistory?: boolean
  ): Promise<boolean>;
  
  /**
   * 문서 끝에 텍스트를 추가합니다.
   * @param text - 추가할 텍스트
   * @param addNewLine - 새 줄 추가 여부
   */
  async appendToDocument(
    text: string, 
    addNewLine?: boolean
  ): Promise<boolean>;
  
  /**
   * 현재 커서 위치를 반환합니다.
   * @returns 커서 위치 또는 null
   */
  getCursorPosition(): EditorPosition | null;
  
  /**
   * 선택된 텍스트를 반환합니다.
   */
  getSelection(): string;
  
  /**
   * Undo를 실행합니다.
   */
  async undo(): Promise<boolean>;
  
  /**
   * Redo를 실행합니다.
   */
  async redo(): Promise<boolean>;
  
  /**
   * 새 노트를 생성하고 엽니다.
   * @param fileName - 파일명
   * @param content - 초기 내용
   * @param folder - 폴더 경로
   */
  async createAndOpenNote(
    fileName: string,
    content: string,
    folder?: string
  ): Promise<boolean>;
}

TextInsertionHandler

변환된 텍스트의 포맷팅과 삽입을 담당합니다. 다양한 포맷과 템플릿을 지원합니다.

class TextInsertionHandler {
  /**
   * 텍스트를 포맷팅하고 삽입합니다.
   * @param text - 삽입할 텍스트
   * @param options - 삽입 옵션
   * @returns 삽입 성공 여부
   * @example
   * await handler.insertText("변환된 텍스트", {
   *   mode: 'cursor',
   *   format: 'quote',
   *   addTimestamp: true
   * });
   */
  async insertText(
    text: string,
    options: InsertionOptions
  ): Promise<boolean>;
  
  /**
   * 마지막 삽입된 텍스트를 반환합니다.
   */
  getLastInsertedText(): string;
  
  /**
   * 삽입 히스토리를 반환합니다.
   */
  getInsertionHistory(): InsertionRecord[];
  
  /**
   * 프리뷰 모드를 설정합니다.
   * @param enabled - 활성화 여부
   */
  setPreviewMode(enabled: boolean): void;
}

InsertionOptions 타입

interface InsertionOptions {
  mode: InsertionMode;           // 삽입 모드
  format: TextFormat;            // 텍스트 포맷
  addTimestamp?: boolean;        // 타임스탬프 추가
  timestampFormat?: string;      // 타임스탬프 형식 (YYYY-MM-DD HH:mm:ss)
  template?: string;             // 텍스트 템플릿
  language?: string;             // 언어 코드 (ko, en, ja, zh)
  preview?: boolean;             // 프리뷰 표시
  createNewNote?: boolean;       // 새 노트 생성
  noteTitle?: string;            // 노트 제목
  noteFolder?: string;           // 노트 폴더
  
  // 포맷별 옵션
  paragraphBreaks?: boolean;     // 문단 구분
  quoteAuthor?: string;          // 인용 작성자
  bulletChar?: string;           // 불릿 문자 (-, *, +)
  headingLevel?: number;         // 제목 레벨 (1-6)
  codeLanguage?: string;         // 코드 언어
  calloutType?: string;          // 콜아웃 타입 (info, warning, error)
  calloutTitle?: string;         // 콜아웃 제목
  calloutFoldable?: boolean;     // 콜아웃 접기 가능
}

type InsertionMode = 
  | 'cursor'      // 커서 위치
  | 'replace'     // 선택 영역 대체
  | 'append'      // 문서 끝
  | 'prepend'     // 문서 시작
  | 'line-end'    // 현재 줄 끝
  | 'new-line';   // 새 줄

type TextFormat = 
  | 'plain'       // 일반 텍스트
  | 'markdown'    // 마크다운
  | 'quote'       // 인용구
  | 'bullet'      // 불릿 리스트
  | 'heading'     // 제목
  | 'code'        // 코드 블록
  | 'callout';    // 콜아웃

EventManager

애플리케이션 전체의 이벤트를 관리하는 중앙 이벤트 버스입니다. Observer 패턴과 Singleton 패턴을 활용합니다.

class EventManager extends EventEmitter<AppEventMap> {
  /**
   * 이벤트를 발생시킵니다.
   * @param event - 이벤트 이름
   * @param data - 이벤트 데이터
   * @example
   * eventManager.emit('transcription:complete', {
   *   text: "변환된 텍스트",
   *   duration: 10.5
   * });
   */
  emit<K extends keyof AppEventMap>(
    event: K, 
    data: AppEventMap[K]
  ): void;
  
  /**
   * 이벤트를 구독합니다.
   * @param event - 이벤트 이름
   * @param listener - 이벤트 핸들러
   * @returns 구독 해제 함수
   * @example
   * const unsubscribe = eventManager.on('file:selected', (data) => {
   *   console.log(`파일 선택됨: ${data.file.path}`);
   * });
   */
  on<K extends keyof AppEventMap>(
    event: K,
    listener: EventListener<AppEventMap[K]>
  ): Unsubscribe;
  
  /**
   * 일회성 이벤트를 구독합니다.
   * @param event - 이벤트 이름
   * @param listener - 이벤트 핸들러
   */
  once<K extends keyof AppEventMap>(
    event: K,
    listener: EventListener<AppEventMap[K]>
  ): Unsubscribe;
  
  /**
   * 이벤트를 디바운싱합니다.
   * @param event - 이벤트 이름
   * @param wait - 대기 시간 (밀리초)
   * @param listener - 이벤트 핸들러
   */
  debounce<K extends keyof AppEventMap>(
    event: K,
    wait: number,
    listener: EventListener<AppEventMap[K]>
  ): Unsubscribe;
  
  /**
   * 이벤트를 쓰로틀링합니다.
   * @param event - 이벤트 이름
   * @param limit - 제한 시간 (밀리초)
   * @param listener - 이벤트 핸들러
   */
  throttle<K extends keyof AppEventMap>(
    event: K,
    limit: number,
    listener: EventListener<AppEventMap[K]>
  ): Unsubscribe;
  
  /**
   * 이벤트 체인을 생성합니다.
   * @param sourceEvent - 소스 이벤트
   * @param targetEvent - 타겟 이벤트
   * @param transformer - 데이터 변환 함수
   */
  chain<K extends keyof AppEventMap, K2 extends keyof AppEventMap>(
    sourceEvent: K,
    targetEvent: K2,
    transformer?: (data: AppEventMap[K]) => AppEventMap[K2]
  ): Unsubscribe;
  
  /**
   * 이벤트 통계를 조회합니다.
   * @returns 이벤트별 발생 횟수
   */
  getStats(): Map<keyof AppEventMap, number>;
  
  /**
   * 디버그 모드를 설정합니다.
   * @param enabled - 활성화 여부
   */
  setDebugMode(enabled: boolean): void;
}

AppEventMap 정의

interface AppEventMap {
  // 변환 이벤트
  'transcription:start': { fileName: string; fileSize: number };
  'transcription:complete': { text: string; duration: number; autoInsert?: boolean };
  'transcription:error': { error: Error; fileName?: string };
  'transcription:progress': { progress: number; message?: string };
  
  // 에디터 이벤트
  'editor:changed': { editor: any };
  'editor:active': { view: any; editor: any };
  'editor:text-inserted': { text: string; position?: any };
  'editor:text-replaced': { oldText: string; newText: string };
  
  // 파일 이벤트
  'file:selected': { file: any };
  'file:uploaded': { file: any; size: number };
  'file:validated': { file: any; valid: boolean; errors?: string[] };
  
  // 설정 이벤트
  'settings:changed': { key: string; value: any };
  'settings:loaded': { settings: any };
  'settings:saved': { settings: any };
  
  // UI 이벤트
  'ui:modal-opened': { modalType: string };
  'ui:modal-closed': { modalType: string };
  'ui:notification': { message: string; type: 'info' | 'warning' | 'error' | 'success' };
}

---

유틸리티 함수

ErrorHandler

중앙화된 에러 처리 유틸리티입니다.

class ErrorHandler {
  /**
   * 에러를 처리하고 로깅합니다.
   * @param error - 처리할 에러
   * @param context - 에러 컨텍스트
   */
  handle(error: Error, context?: any): void;
  
  /**
   * 에러를 사용자 친화적 메시지로 변환합니다.
   * @param error - 변환할 에러
   * @returns 사용자 메시지
   */
  getUserMessage(error: Error): string;
  
  /**
   * 재시도 가능한 에러인지 확인합니다.
   * @param error - 확인할 에러
   * @returns 재시도 가능 여부
   */
  isRetryable(error: Error): boolean;
}

사용 예제

try {
  await transcriptionService.transcribe(file);
} catch (error) {
  errorHandler.handle(error, { file: file.path });
  
  if (errorHandler.isRetryable(error)) {
    // 재시도 로직
  }
}

Logger

로깅 유틸리티입니다.

class Logger {
  /**
   * 디버그 메시지를 기록합니다.
   */
  debug(message: string, data?: any): void;
  
  /**
   * 정보 메시지를 기록합니다.
   */
  info(message: string, data?: any): void;
  
  /**
   * 경고 메시지를 기록합니다.
   */
  warn(message: string, data?: any): void;
  
  /**
   * 에러 메시지를 기록합니다.
   */
  error(message: string, error?: Error, data?: any): void;
}

로그 레벨

enum LogLevel {
  DEBUG = 0,
  INFO = 1,
  WARN = 2,
  ERROR = 3
}

---

타입 정의

기본 타입

/** 음성 변환 결과 */
interface TranscriptionResult {
  /** 변환된 텍스트 */
  text: string;
  
  /** 감지된 언어 */
  language: string;
  
  /** 오디오 길이 (초) */
  duration?: number;
  
  /** 변환 신뢰도 (0-1) */
  confidence?: number;
  
  /** 세그먼트 정보 */
  segments?: TranscriptionSegment[];
  
  /** 메타데이터 */
  metadata?: TranscriptionMetadata;
}

/** 변환 세그먼트 */
interface TranscriptionSegment {
  /** 세그먼트 ID */
  id: number;
  
  /** 시작 시간 (초) */
  start: number;
  
  /** 종료 시간 (초) */
  end: number;
  
  /** 세그먼트 텍스트 */
  text: string;
  
  /** 신뢰도 */
  confidence?: number;
}

/** 오디오 메타데이터 */
interface AudioMetadata {
  /** 길이 (초) */
  duration: number;
  
  /** 비트레이트 */
  bitrate: number;
  
  /** 샘플레이트 */
  sampleRate: number;
  
  /** 채널 수 */
  channels: number;
  
  /** 코덱 */
  codec: string;
  
  /** 파일 크기 (바이트) */
  size: number;
}

상태 타입

/** 변환 상태 */
type TranscriptionStatus = 
  | 'idle'          // 대기 중
  | 'validating'    // 검증 중
  | 'processing'    // 처리 중
  | 'uploading'     // 업로드 중
  | 'transcribing'  // 변환 중
  | 'formatting'    // 포맷팅 중
  | 'completed'     // 완료
  | 'cancelled'     // 취소됨
  | 'error';        // 에러

/** 앱 상태 */
interface AppState {
  /** 현재 상태 */
  status: TranscriptionStatus;
  
  /** 처리 중인 파일 */
  currentFile: TFile | null;
  
  /** 진행률 (0-100) */
  progress: number;
  
  /** 에러 정보 */
  error: Error | null;
  
  /** 변환 기록 */
  history: TranscriptionHistory[];
}

설정 타입

/** 플러그인 설정 (v3.0.0) */
interface SpeechToTextSettings {
  /** Provider 선택 */
  provider: 'whisper' | 'deepgram' | 'auto';
  
  /** API 키 */
  openaiApiKey?: string;
  deepgramApiKey?: string;
  
  /** Provider별 모델 설정 */
  whisperModel?: 'whisper-1';
  deepgramTier?: 'nova-2' | 'nova' | 'enhanced' | 'base';
  
  /** 언어 코드 */
  language: LanguageCode;
  
  /** 자동 삽입 여부 */
  autoInsert: boolean;
  
  /** 삽입 위치 */
  insertPosition: InsertPosition;
  
  /** 타임스탬프 형식 */
  timestampFormat: TimestampFormat;
  
  /** 최대 파일 크기 (바이트) */
  maxFileSize: number;
  
  /** 캐시 활성화 */
  enableCache: boolean;
  
  /** 캐시 TTL (밀리초) */
  cacheTTL: number;
  
  /** Fallback 설정 */
  enableFallback: boolean;
  fallbackProvider?: 'whisper' | 'deepgram';
  
  /** 스마트 라우팅 */
  smartRouting: boolean;
}

/** 언어 코드 */
type LanguageCode = 'auto' | 'en' | 'ko' | 'ja' | 'zh' | string;

/** 삽입 위치 */
type InsertPosition = 'cursor' | 'end' | 'beginning';

/** 타임스탬프 형식 */
type TimestampFormat = 'none' | 'inline' | 'sidebar';

---

이벤트 시스템

EventManager

이벤트 발행/구독 시스템입니다.

class EventManager {
  /**
   * 이벤트를 발행합니다.
   * @param event - 이벤트 이름
   * @param data - 이벤트 데이터
   */
  emit(event: string, data?: any): void;
  
  /**
   * 이벤트를 구독합니다.
   * @param event - 이벤트 이름
   * @param handler - 이벤트 핸들러
   * @returns 구독 해제 함수
   */
  on(event: string, handler: EventHandler): Unsubscribe;
  
  /**
   * 한 번만 실행되는 이벤트를 구독합니다.
   */
  once(event: string, handler: EventHandler): Unsubscribe;
  
  /**
   * 이벤트 구독을 해제합니다.
   */
  off(event: string, handler?: EventHandler): void;
  
  /**
   * 모든 리스너를 제거합니다.
   */
  removeAllListeners(): void;
}

이벤트 목록

이벤트	설명	데이터
transcription:start	변환 시작	{ fileName: string }
transcription:progress	진행 상태 업데이트	{ progress: number }
transcription:complete	변환 완료	{ result: TranscriptionResult }
transcription:error	에러 발생	{ error: Error }
transcription:cancel	변환 취소	{}
settings:change	설정 변경	{ settings: Settings }

사용 예제

// 이벤트 구독
const unsubscribe = eventManager.on('transcription:progress', (data) => {
  console.log(`Progress: ${data.progress}%`);
});

// 이벤트 발행
eventManager.emit('transcription:progress', { progress: 50 });

// 구독 해제
unsubscribe();

---

에러 처리

에러 클래스

/** 기본 에러 클래스 */
abstract class BaseError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode?: number,
    public readonly isRetryable: boolean = false
  ) {
    super(message);
    this.name = this.constructor.name;
  }
}

/** 검증 에러 */
class ValidationError extends BaseError {
  constructor(message: string, public readonly field?: string) {
    super(message, 'VALIDATION_ERROR', 400, false);
  }
}

/** API 에러 */
class WhisperAPIError extends BaseError {
  constructor(
    message: string,
    public readonly status: number,
    public readonly response?: any
  ) {
    super(
      message,
      'WHISPER_API_ERROR',
      status,
      status >= 500 || status === 429
    );
  }
}

/** 네트워크 에러 */
class NetworkError extends BaseError {
  constructor(message: string, public readonly originalError?: Error) {
    super(message, 'NETWORK_ERROR', 0, true);
  }
}

/** 파일 크기 초과 에러 */
class FileSizeExceededError extends BaseError {
  constructor(
    public readonly actualSize: number,
    public readonly maxSize: number
  ) {
    super(
      `File size ${actualSize} exceeds maximum ${maxSize}`,
      'FILE_SIZE_EXCEEDED',
      413,
      false
    );
  }
}

에러 코드

코드	설명	재시도 가능
VALIDATION_ERROR	입력 검증 실패	❌
FILE_NOT_FOUND	파일을 찾을 수 없음	❌
FILE_SIZE_EXCEEDED	파일 크기 초과	❌
INVALID_FORMAT	지원하지 않는 형식	❌
WHISPER_API_ERROR	API 호출 실패	상황에 따라
NETWORK_ERROR	네트워크 오류	✅
RATE_LIMIT	API 호출 제한	✅
TIMEOUT	요청 시간 초과	✅
UNAUTHORIZED	인증 실패	❌

---

설정 옵션

기본 설정

const DEFAULT_SETTINGS: SpeechToTextSettings = {
  // Provider 설정
  provider: 'auto',
  openaiApiKey: '',
  deepgramApiKey: '',
  
  // Whisper 기본값
  whisperModel: 'whisper-1',
  
  // Deepgram 기본값
  deepgramTier: 'nova-2',
  deepgramPunctuate: true,
  deepgramSmartFormat: true,
  deepgramDiarize: false,
  
  // 공통 설정
  language: 'auto',
  autoInsert: true,
  insertPosition: 'cursor',
  timestampFormat: 'none',
  maxFileSize: 0, // 0 = Provider별 기본값 사용
  enableCache: true,
  cacheTTL: 3600000, // 1시간
  
  // 고급 기능
  enableFallback: true,
  smartRouting: true
};

설정 관리

class SettingsManager {
  /**
   * 설정을 로드합니다.
   */
  async load(): Promise<Settings>;
  
  /**
   * 설정을 저장합니다.
   */
  async save(settings: Settings): Promise<void>;
  
  /**
   * 특정 설정 값을 가져옵니다.
   */
  get<K extends keyof Settings>(key: K): Settings[K];
  
  /**
   * 특정 설정 값을 설정합니다.
   */
  async set<K extends keyof Settings>(
    key: K,
    value: Settings[K]
  ): Promise<void>;
  
  /**
   * 설정을 초기화합니다.
   */
  async reset(): Promise<void>;
}

---

사용 예제

기본 사용법

// 플러그인 초기화
class MyPlugin extends SpeechToTextPlugin {
  async onload() {
    await super.onload();
    
    // 명령어 추가
    this.addCommand({
      id: 'my-custom-command',
      name: 'My Custom Command',
      callback: () => this.handleCustomCommand()
    });
  }
  
  private async handleCustomCommand() {
    // 파일 선택
    const files = this.app.vault.getFiles()
      .filter(f => f.extension === 'm4a');
    
    if (files.length === 0) {
      new Notice('No audio files found');
      return;
    }
    
    // 변환 실행
    try {
      const result = await this.transcriptionService
        .transcribe(files[0]);
      
      console.log('Transcription result:', result);
    } catch (error) {
      this.errorHandler.handle(error);
    }
  }
}

이벤트 처리

// 진행 상태 모니터링
eventManager.on('transcription:progress', (data) => {
  const progressBar = document.getElementById('progress');
  if (progressBar) {
    progressBar.style.width = `${data.progress}%`;
  }
});

// 완료 처리
eventManager.on('transcription:complete', async (data) => {
  const { result } = data;
  
  // 텍스트 삽입
  const editor = this.app.workspace.getActiveViewOfType(MarkdownView)?.editor;
  if (editor) {
    editor.replaceSelection(result.text);
  }
  
  // 알림
  new Notice(`Transcription complete! Language: ${result.language}`);
});

커스텀 서비스

// 커스텀 변환 서비스 구현
class CustomTranscriptionService implements ITranscriptionService {
  async transcribe(file: TFile): Promise<TranscriptionResult> {
    // 커스텀 로직
    const customProcessor = new CustomAudioProcessor();
    const processed = await customProcessor.process(file);
    
    // API 호출
    const response = await this.callCustomAPI(processed);
    
    return {
      text: response.text,
      language: response.language,
      duration: processed.duration
    };
  }
  
  cancel(): void {
    // 취소 로직
  }
  
  getStatus(): TranscriptionStatus {
    return this.currentStatus;
  }
}

---

API 버전 관리

버전 확인

// 플러그인 버전 확인
const pluginVersion = this.manifest.version;
console.log(`Plugin version: ${pluginVersion}`);

// API 호환성 확인
if (!this.app.vault.adapter) {
  throw new Error('Incompatible Obsidian version');
}

Breaking Changes

v3.0.0 (2025-08-28)

• 주요 변경사항:
  • Deepgram Nova 2 API 통합
  • 다중 Provider 지원 (Whisper, Deepgram)
  • 자동 Provider 선택 기능
  • 대용량 파일 지원 (최대 2GB)
  • Fallback 메커니즘 구현
  • 스마트 라우팅 기능
• Breaking Changes:
  • apiKey → openaiApiKey, deepgramApiKey로 분리
  • model → whisperModel로 변경
  • Provider별 설정 분리

v2.0.0 (2025-08-25)

• Phase 3: UX 개선
• Phase 4: 성능 최적화

v1.0.0 (2025-08-22)

• 초기 릴리스
• 기본 API 구조 확립

---

개발자 도구

디버깅

// 디버그 모드 활성화
if (process.env.NODE_ENV === 'development') {
  window.speechToTextDebug = {
    plugin: this,
    services: {
      transcription: this.transcriptionService,
      whisper: this.whisperService
    },
    state: this.stateManager.getState()
  };
}

테스트 유틸리티

// Mock 생성
export function createMockAudioFile(): TFile {
  return {
    path: 'test.m4a',
    name: 'test.m4a',
    extension: 'm4a',
    stat: {
      size: 1024 * 1024, // 1MB
      ctime: Date.now(),
      mtime: Date.now()
    }
  } as TFile;
}

// 테스트 헬퍼
export async function waitForEvent(
  eventManager: EventManager,
  event: string,
  timeout = 5000
): Promise<any> {
  return new Promise((resolve, reject) => {
    const timer = setTimeout(() => {
      reject(new Error(`Timeout waiting for event: ${event}`));
    }, timeout);
    
    eventManager.once(event, (data) => {
      clearTimeout(timer);
      resolve(data);
    });
  });
}

---

최종 업데이트: 2025-08-28 API 버전: 3.0.0