lrcget

The frontend uses a composable-based state management pattern instead of a dedicated store library (like Pinia or Vuex). State is managed via module-level ref singletons in the composables/ directory.

Key composables include:

• useGlobalState(): Manages isHotkey, themeMode, and lrclibInstance.
• usePlayer(): Manages playingTrack, status, duration, progress, and volume. It listens to player-state events from the backend.
• useDownloader(): Manages the download queue and progress.
• useSearchLibrary(): Provides shared search text and filters for Tracks, Albums, and Artists.
• useEditLyricsV2(): Manages the state for the lyrics editing modal.

LRCGET is built using the Tauri v2 (Rust) framework with a SQLite backend. It utilizes Kira for audio playback and integrates with the LRCLIB API for lyric retrieval.

Core Patterns

• State Management: Uses a global AppState containing Mutex<Connection> (for database access) and Mutex<Player> (for audio control).
• Database Access: Implements the ServiceAccess trait on AppHandle to facilitate read/write operations.
• Communication: Uses asynchronous backend-to-frontend events via app.emit() and organizes all FFI (Foreign Function Interface) commands in main.rs by domain.
• Scanning: Employs a single-pass streaming approach with batch processing (groups of 100 files).
• Exporting: Supports manual sidecar export (.txt/.lrc) and embedded metadata export.

If you are updating a frontend integration, follow these migration steps to move from the deprecated fs_track logic to the new scanner implementation:

1. Replace Commands: Replace calls to initialize_library and refresh_library with scan_library_incremental.
2. Update Event Listeners:
   • Stop listening for initialize-progress.
   • Start listening for scan-progress and scan-complete.
3. Update Progress UI: Instead of showing filesScanned/filesCount, use the message field from the scan-progress event (e.g., {{ scanProgress.message }}) and calculate percentage using scanProgress.progress.
4. Fix Directory Changes: Ensure that when directories are saved (e.g., in ChooseDirectory.vue), a scan is explicitly triggered if no tracks currently exist in the library.

Keyboard shortcuts are managed via a central registry in composables/edit-lyrics-v2/shortcutRegistry.js.

Key Features:

• Access: Open the shortcut menu using Ctrl+/ or the header keyboard icon.
• Configuration: Use the KeyboardShortcutsModal.vue to remap keys. The system detects duplicate assignments and provides warnings.
• Persistence: Custom shortcuts are persisted in the browser's localStorage.
• Programmatic Control: Shortcuts can be modified via registry override APIs:
  • setShortcutOverride
  • resetShortcutOverride
  • resetAllShortcutOverrides

Download the appropriate .dmg file based on your hardware:

• Mac x64 (Intel)
• Mac Apple Silicon (aarch64)

To install the Fake Music Generator, navigate to the tools directory and install the required Python dependencies using pip.

Optional dependencies for enhanced functionality:

• faker: Provides more realistic artist and album names.
• mutagen: Enables proper ID3 metadata tags.
• pydub: Provides better MP3 generation capabilities.

cd tools
pip install -r requirements.txt

When scanning music directories, you can choose between two detection modes to balance speed and accuracy:

1. Hash (Default): Uses xxhash3 on the first 64KB of the file. This is 100% accurate for detecting moved files.
2. Metadata: Uses mtime (modification time) and file_size. This is faster but may result in duplicate entries if metadata changes without the file moving.

Scan Results: The scanning process returns a ScanResult object containing total_files, added, modified, deleted, moved, unchanged, is_initial_scan, and duration_ms.

When creating LRCGET files, adhere to these rules:

1. Timing: All timestamps must be integers in milliseconds and must be monotonically increasing.
2. Trailing Spaces: In word.text, include trailing spaces except for the last word of the line.
3. CJK Support: No spaces are required between words for CJK (Chinese, Japanese, Korean) languages.
4. Instrumental Songs: When metadata.instrumental is true, both lines and plain should be empty or omitted.
5. Plain Field: Use the YAML literal block scalar (|) for the plain field to preserve newlines and spacing exactly as written.

The project uses Vitest for testing. Tests are located next to the source files they exercise.

• npm test: Run tests once.
• npm run test:watch: Run tests in watch mode.