Core Modules ko

핵심 모듈

English

ivLyrics 핵심 모듈에 대한 상세 문서입니다.

---

LyricsService.js

모든 가사 관련 작업을 위한 중앙 서비스입니다.

주요 컴포넌트

LRUCache

Least Recently Used 제거 방식의 효율적인 인메모리 캐시:

const cache = new LRUCache(100);
cache.set('key', value);
cache.get('key');

LocalCache

IndexedDB 기반 영구 저장소:

// 캐시된 가사 가져오기
const lyrics = await LocalCache.getLyrics(trackId, provider);

// 가사 저장
await LocalCache.setLyrics(trackId, provider, lyricsData);

// 번역 가져오기/저장
await LocalCache.getTranslation(trackId, lang, isPhonetic);
await LocalCache.setTranslation(trackId, lang, isPhonetic, data);

Utils

언어 감지 및 유틸리티 함수:

// 가사 언어 감지
const lang = Utils.detectLanguage(lyricsArray);
// 반환값: 'ja', 'ko', 'zh', 'en' 등

ApiTracker

API 요청 추적을 위한 디버그 도구:

// 요청 로그
const logId = ApiTracker.logRequest('lyrics', 'Spotify API');

// 응답 로그
ApiTracker.logResponse(logId, responseData, 'success');

// 로그 가져오기
const logs = ApiTracker.getLogs();

---

AIAddonManager.js

번역 및 발음 기능을 위한 AI 제공자 애드온을 관리합니다.

클래스: AIAddonManager

메서드

// 매니저 초기화
await AIAddonManager.init();

// 애드온 등록
AIAddonManager.register(addon);

// ID로 애드온 가져오기
const addon = AIAddonManager.getAddon('gemini');

// 모든 애드온 가져오기
const addons = AIAddonManager.getAddons();

// 제공자 활성화 여부 확인
const enabled = AIAddonManager.isProviderEnabled('gemini');

// 제공자 활성화 상태 설정
AIAddonManager.setProviderEnabled('gemini', true);

// 특정 기능에 대해 활성화된 제공자 가져오기
const providers = AIAddonManager.getEnabledProvidersFor('translate');

// 가사 번역
const result = await AIAddonManager.translate({
    lyrics: lyricsArray,
    sourceLang: 'ja',
    targetLang: 'ko'
});

// 메타데이터 번역
const metadata = await AIAddonManager.translateMetadata({
    title: 'Original Title',
    artist: 'Artist Name',
    lang: 'ko'
});

기능 (Capabilities)

AIAddonManager.CAPABILITIES = {
    TRANSLATE: 'translate',      // 가사 번역
    PHONETIC: 'metadata',        // 발음/로마자 표기
    METADATA: 'metadata',        // 제목/아티스트 번역
    TMI: 'tmi'                   // 트랙 음악 정보
};

이벤트

AIAddonManager.on('provider:registered', (addon) => { });
AIAddonManager.on('provider:unregistered', (addonId) => { });
AIAddonManager.on('settings:changed', (key, value) => { });

---

LyricsAddonManager.js

가사 제공자 애드온을 관리합니다.

클래스: LyricsAddonManager

메서드

// 초기화
await LyricsAddonManager.init();

// 애드온 등록
LyricsAddonManager.register(addon);

// 가사 가져오기 (우선순위별 자동 선택)
const lyrics = await LyricsAddonManager.getLyrics({
    uri: 'spotify:track:xxx',
    title: 'Song Title',
    artist: 'Artist Name',
    album: 'Album Name',
    duration: 180000
});

// 특정 제공자에서 가사 가져오기
const lyrics = await LyricsAddonManager.getLyricsFrom('spotify', trackInfo);

// 특정 가사 유형을 지원하는 제공자 가져오기
const providers = LyricsAddonManager.getProvidersSupporting('karaoke');

가사 유형

LyricsAddonManager.TYPES = {
    KARAOKE: 'karaoke',     // 단어별 싱크
    SYNCED: 'synced',       // 줄별 싱크
    UNSYNCED: 'unsynced'    // 타이밍 없음
};

가사 결과 형식

{
    type: 'karaoke' | 'synced' | 'unsynced',
    provider: 'spotify',
    lines: [
        {
            startTime: 0,
            endTime: 5000,
            text: '가사 줄',
            words: [  // 노래방 모드에서만
                { startTime: 0, endTime: 500, text: '가사' },
                { startTime: 500, endTime: 1000, text: '줄' }
            ]
        }
    ]
}

---

I18n.js

국제화 시스템입니다.

사용법

// 번역 가져오기
const text = _t('settings.title');

// 기본값과 함께 가져오기
const text = _t('key.that.might.not.exist', '기본값');

// 현재 언어 가져오기
const lang = ivLyricsI18n.getCurrentLanguage();

// 언어 설정
ivLyricsI18n.setLanguage('ko');

// 사용 가능한 언어 목록
const languages = ivLyricsI18n.getAvailableLanguages();

언어 파일 형식

window.ivLyricsLangs = window.ivLyricsLangs || {};
window.ivLyricsLangs['ko'] = {
    settings: {
        title: '설정',
        save: '저장'
    },
    buttons: {
        ok: '확인',
        cancel: '취소'
    }
};

---

SettingsObject.js

localStorage를 사용한 설정 관리입니다.

사용법

// 설정 가져오기
const value = SettingsObject.get('key', defaultValue);

// 설정 저장
SettingsObject.set('key', value);

// 설정 제거
SettingsObject.remove('key');

// 존재 여부 확인
const exists = SettingsObject.has('key');

저장 키

설정은 ivLyrics: 접두사와 함께 저장됩니다:

• ivLyrics:translation:targetLang
• ivLyrics:visual:fontSize
• ivLyrics:sync:offset:{trackId}

---

Utils.js

애플리케이션 전체에서 사용되는 유틸리티 함수입니다.

주요 함수

// 트랙 유틸리티
Utils.getCurrentTrackInfo();
Utils.getTrackId(uri);

// 시간 포맷팅
Utils.formatTime(milliseconds);  // "3:42"
Utils.parseTime(timeString);     // 222000

// 색상 유틸리티
Utils.hexToRgb('#ff0000');
Utils.rgbToHex(255, 0, 0);

// Debounce/throttle
Utils.debounce(fn, delay);
Utils.throttle(fn, limit);

// 문자열 유틸리티
Utils.sanitizeHtml(text);
Utils.escapeRegex(text);

---

다음 단계

• AI 애드온 개발 - AI 제공자 만들기
• 가사 애드온 개발 - 가사 제공자 만들기
• UI 컴포넌트 - UI 모듈 문서