Architecture Overview ko

아키텍처 개요

English

개발자를 위한 ivLyrics 아키텍처 개요입니다.

---

프로젝트 구조

ivLyrics/
├── index.js                    # 메인 진입점
├── manifest.json               # 앱 매니페스트
├── style.css                   # 메인 스타일시트
│
├── Core Modules/
│   ├── LyricsService.js        # 가사 가져오기 및 처리
│   ├── AIAddonManager.js       # AI 제공자 관리
│   ├── LyricsAddonManager.js   # 가사 제공자 관리
│   ├── I18n.js                 # 국제화
│   ├── Utils.js                # 유틸리티 함수
│   └── SettingsObject.js       # 설정 관리
│
├── UI Components/
│   ├── Settings.js             # 설정 UI
│   ├── FullscreenOverlay.js    # 전체 화면 모드
│   ├── OptionsMenu.js          # 컨텍스트 메뉴
│   ├── NowPlayingPanelLyrics.js# Now Playing 패널 통합
│   ├── SetupWizard.js          # 첫 실행 마법사
│   ├── SyncDataCreator.js      # 싱크 데이터 생성 도구
│   ├── TabBar.js               # 탭 네비게이션
│   └── Pages.js                # 페이지 라우팅
│
├── Features/
│   ├── VideoBackground.js      # 유튜브 비디오 배경
│   ├── VideoHelperService.js   # 비디오 헬퍼 유틸리티
│   ├── CommunityVideoSelector.js# 커뮤니티 비디오 선택
│   ├── GlobalShortcuts.js      # 키보드 단축키
│   ├── PlaybarButton.js        # 플레이바 통합
│   ├── LyricsShareImage.js     # 공유 이미지 생성
│   ├── SongInfoTicker.js       # 곡 정보 표시
│   ├── NoticeSystem.js         # 알림 시스템
│   └── FuriganaConverter.js    # 일본어 후리가나 지원
│
├── Addons/
│   ├── Addon_AI_*.js           # AI 제공자 애드온
│   └── Addon_Lyrics_*.js       # 가사 제공자 애드온
│
└── langs/
    └── Lang*.js                # 언어 파일 (18개 언어)

---

모듈 개요

핵심 모듈

index.js

메인 진입점으로 다음을 담당합니다:

• 애플리케이션 초기화
• Spicetify에 등록
• 이벤트 리스너 설정
• 메인 가사 컨테이너 관리

LyricsService.js

가사 관리를 위한 중앙 서비스:

• 제공자에서 가사 가져오기
• 번역 및 발음 요청 관리
• 캐싱 처리 (IndexedDB 기반)
• 트랙 변경 감지

AIAddonManager.js

AI 제공자 애드온 관리:

• 등록 및 검증
• 제공자 순서 및 설정
• 기능 관리 (번역, 발음, 메타데이터, TMI)
• 제공자 변경을 위한 이벤트 시스템

LyricsAddonManager.js

가사 제공자 애드온 관리:

• 등록 및 검증
• 제공자 우선순위 및 설정
• 가사 유형 지원 (노래방, 싱크, 일반)
• ivLyrics Sync 통합

I18n.js

국제화 시스템:

• 언어 감지
• 번역 함수 _t()
• 18개 지원 언어

---

데이터 흐름

사용자가 트랙 재생
       ↓
index.js가 트랙 변경 감지
       ↓
LyricsAddonManager.getLyrics()
       ↓
Lyrics Provider Addon (Spotify/LRCLIB)
       ↓
결과 캐시 (IndexedDB)
       ↓
UI에 가사 표시
       ↓
사용자가 번역 요청
       ↓
AIAddonManager.translate()
       ↓
AI Provider Addon (Gemini/ChatGPT/등)
       ↓
번역 캐시
       ↓
번역된 가사 표시

---

이벤트 시스템

ivLyrics는 모듈 간 통신을 위해 커스텀 이벤트 시스템을 사용합니다:

// 리스너 등록
AIAddonManager.on('provider:registered', (addon) => {
    console.log('새 제공자:', addon.name);
});

// 이벤트 발생
AIAddonManager.emit('provider:registered', addon);

주요 이벤트:

• provider:registered - 새 애드온 등록됨
• provider:unregistered - 애드온 제거됨
• settings:changed - 설정 값 변경됨
• lyrics:loaded - 새 가사 로드됨
• translation:complete - 번역 완료됨

---

캐싱 전략

ivLyrics는 영구 캐싱을 위해 IndexedDB를 사용합니다:

캐시 유형	만료	설명
lyrics	7일	원본 가사 데이터
translation	30일	번역된 가사
phonetic	30일	로마자 변환된 가사
metadata	30일	번역된 곡 정보
sync	7일	싱크 오프셋 데이터
youtube	7일	비디오 메타데이터
tmi	30일	트랙 정보 데이터

---

확장 로딩

ivLyrics는 두 가지 유형의 서브파일과 함께 Spicetify의 CustomApp 시스템을 사용합니다:

일반 서브파일 (앱과 함께 로드):

• UI 컴포넌트
• 언어 파일
• 설정

확장 서브파일 (전역으로 로드):

• LyricsService.js
• Addon 매니저
• 글로벌 단축키

이를 통해 글로벌 단축키와 같은 기능이 모든 Spotify 페이지에서 작동할 수 있습니다.

---

다음 단계

• 핵심 모듈 - 상세 모듈 문서
• AI 애드온 개발 - AI 제공자 만들기
• 가사 애드온 개발 - 가사 제공자 만들기