# Lyrics4fb2k

**Repository Path**: acnx/lyrics4fb2k

## Basic Information

- **Project Name**: Lyrics4fb2k
- **Description**: Mac 版本的 foobar2000 歌词插件
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# foo_lyrics_mac

foobar2000 lyrics display component for macOS. Automatically fetches and displays synchronized lyrics while playing music.

## Features

- **Multiple lyric sources** — LRCLIB, NetEase, QQ Music, local files with automatic fallback
- **Synchronized lyrics** — Highlights the current line and scrolls through timed LRC lyrics
- **Rate limiting** — Built-in request throttling with exponential backoff to avoid API bans
- **Search avoidance** — Skips repeated failed searches for the same track
- **Dark mode** — Follows macOS system appearance via KVO
- **Preferences** — Configurable via foobar2000 Preferences → Components → Lyrics

## Requirements

- macOS 11.0+
- foobar2000 for Mac
- [foobar2000 SDK](https://www.foobar2000.org/SDK) (included in `3rdparty/foobar2000-sdk/`)

## Building

```bash
# Generate Xcode project (if needed)
python3 generate_project.py

# Build
xcodebuild -project foo_lyrics_mac.xcodeproj -scheme foo_lyrics_mac -configuration Release build
```

## Installation

Copy the built component to foobar2000's user components directory:

```bash
mkdir -p ~/Library/foobar2000-v2/user-components/foo_lyrics_mac/
cp -R build/Release/foo_lyrics_mac.component ~/Library/foobar2000-v2/user-components/foo_lyrics_mac/
```

Then restart foobar2000.

## Adding the Lyrics Panel

1. Open foobar2000
2. Go to **File → Preferences → Display → Default UI**
3. Click **+** to add a panel
4. Search for **"Lyrics Panel"** and add it

## Project Structure

```
foo_lyrics_mac/
├── core/                    # Core logic
│   ├── lyric_data.h         # LyricData, TrackInfo, LyricState
│   ├── lyric_search.h       # Search orchestrator (fallback across sources)
│   ├── lyric_cache.h        # LRU memory cache
│   ├── preferences.h/.mm    # NSUserDefaults preferences
│   └── search_avoidance.h   # Repeated failure cooldown
├── sources/                 # Lyric source implementations
│   ├── lyric_source.h       # Abstract base + self-registering factory
│   ├── lrclib_source.h      # LRCLIB (lrclib.net)
│   ├── netease_source.h     # NetEase Cloud Music
│   ├── qqmusic_source.h     # QQ Music
│   └── local_file_source.h  # Local .lrc/.txt files
├── net/                     # Networking
│   ├── http_client.h/.mm    # NSURLSession HTTP client
│   ├── rate_limiter.h       # Per-source rate limiting + backoff
│   └── parsers/
│       └── lrc_parser.h     # LRC format parser
├── ui/                      # macOS UI
│   ├── ui_element.mm        # ui_element_mac registration
│   ├── lyric_panel.h/.mm    # Main lyrics NSView
│   └── preferences_page.mm  # Preferences page (NSViewController)
├── util/                    # Utilities
│   ├── string_util.h        # URL encoding, trim, replace, etc.
│   ├── tag_util.h/.mm       # File path utilities
│   ├── error.h              # Error type
│   └── logging.h            # File + stderr logging
├── main.mm                  # Entry point, initquit, DECLARE_COMPONENT_VERSION
├── play_callback.mm         # Playback callbacks, notification posting
├── generate_project.py      # Xcode project generator
└── build.sh                 # Build + install script
```

## Architecture

- **Search flow**: `play_callback` → `lyric_search` → tries each `LyricSource` in priority order → posts `NSNotification` → `LyricPanel` updates
- **Rate limiting**: Minimum 2s per source, 500ms global, exponential backoff on failures
- **Self-registering sources**: Each source file uses `LyricSourceFactory<T>` to auto-register at static init time
- **Threading**: GCD background queue for network requests, main thread for UI via `NSNotificationCenter`

## Configuration

Preferences are stored in `NSUserDefaults` under `com.foo_lyrics_mac`:

| Key | Default | Description |
|-----|---------|-------------|
| `auto_search` | `true` | Search lyrics automatically on track change |
| `search_local_first` | `true` | Check local files before online sources |
| `auto_scroll` | `true` | Auto-scroll to current line |
| `show_timestamps` | `true` | Show time labels |
| `font_size` | `14` | Lyrics font size |
| `scroll_speed` | `1.0` | Scroll speed multiplier |

## Logging

Logs are written to `~/Library/foobar2000-v2/foo_lyrics_mac.log`.

## License

MIT