Architecture Overview

Architecture Overview

한국어

This document provides an overview of the ivLyrics architecture for developers.

---

Project Structure

ivLyrics/
├── index.js                    # Main entry point
├── manifest.json               # App manifest
├── style.css                   # Main stylesheet
│
├── Core Modules/
│   ├── LyricsService.js        # Lyrics fetching and processing
│   ├── AIAddonManager.js       # AI provider management
│   ├── LyricsAddonManager.js   # Lyrics provider management
│   ├── I18n.js                 # Internationalization
│   ├── Utils.js                # Utility functions
│   └── SettingsObject.js       # Settings management
│
├── UI Components/
│   ├── Settings.js             # Settings UI
│   ├── FullscreenOverlay.js    # Fullscreen mode
│   ├── OptionsMenu.js          # Context menu
│   ├── NowPlayingPanelLyrics.js# Now Playing panel integration
│   ├── SetupWizard.js          # First-run wizard
│   ├── SyncDataCreator.js      # Sync data creation tool
│   ├── TabBar.js               # Tab navigation
│   └── Pages.js                # Page routing
│
├── Features/
│   ├── VideoBackground.js      # YouTube video background
│   ├── VideoHelperService.js   # Video helper utilities
│   ├── CommunityVideoSelector.js# Community video selection
│   ├── GlobalShortcuts.js      # Keyboard shortcuts
│   ├── PlaybarButton.js        # Playbar integration
│   ├── LyricsShareImage.js     # Share image generation
│   ├── SongInfoTicker.js       # Song info display
│   ├── NoticeSystem.js         # Notification system
│   └── FuriganaConverter.js    # Japanese furigana support
│
├── Addons/
│   ├── Addon_AI_*.js           # AI provider addons
│   └── Addon_Lyrics_*.js       # Lyrics provider addons
│
└── langs/
    └── Lang*.js                # Language files (18 languages)

---

Module Overview

Core Modules

index.js

The main entry point that:

• Initializes the application
• Registers with Spicetify
• Sets up event listeners
• Manages the main lyrics container

LyricsService.js

Central service for lyrics management:

• Fetches lyrics from providers
• Manages translation and phonetic requests
• Handles caching (IndexedDB-based)
• Track change detection

AIAddonManager.js

Manages AI provider addons:

• Registration and validation
• Provider ordering and settings
• Capability management (translate, phonetic, metadata, TMI)
• Event system for provider changes

LyricsAddonManager.js

Manages lyrics provider addons:

• Registration and validation
• Provider priority and settings
• Lyrics type support (karaoke, synced, unsynced)
• ivLyrics Sync integration

I18n.js

Internationalization system:

• Language detection
• Translation function _t()
• 18 supported languages

---

Data Flow

User plays track
       ↓
index.js detects track change
       ↓
LyricsAddonManager.getLyrics()
       ↓
Lyrics Provider Addon (Spotify/LRCLIB)
       ↓
Cache result (IndexedDB)
       ↓
Display lyrics in UI
       ↓
User requests translation
       ↓
AIAddonManager.translate()
       ↓
AI Provider Addon (Gemini/ChatGPT/etc.)
       ↓
Cache translation
       ↓
Display translated lyrics

---

Event System

ivLyrics uses a custom event system for module communication:

// Register listener
AIAddonManager.on('provider:registered', (addon) => {
    console.log('New provider:', addon.name);
});

// Emit event
AIAddonManager.emit('provider:registered', addon);

Key events:

• provider:registered - New addon registered
• provider:unregistered - Addon removed
• settings:changed - Setting value changed
• lyrics:loaded - New lyrics loaded
• translation:complete - Translation finished

---

Caching Strategy

ivLyrics uses IndexedDB for persistent caching:

Cache Type	Expiry	Description
lyrics	7 days	Raw lyrics data
translation	30 days	Translated lyrics
phonetic	30 days	Romanized lyrics
metadata	30 days	Translated song info
sync	7 days	Sync offset data
youtube	7 days	Video metadata
tmi	30 days	Track info data

---

Extension Loading

ivLyrics uses Spicetify's CustomApp system with two types of subfiles:

Regular subfiles (loaded with app):

• UI components
• Language files
• Settings

Extension subfiles (loaded globally):

• LyricsService.js
• Addon managers
• Global shortcuts

This allows features like global shortcuts to work across all Spotify pages.

---

Next Steps

• Core Modules - Detailed module documentation
• Creating AI Addons - Build AI providers
• Creating Lyrics Addons - Build lyrics providers