From b368d6366f66848717ab4586cc15f41d17590f60 Mon Sep 17 00:00:00 2001 From: ByteMe6 Date: Mon, 16 Nov 2026 10:48:17 +0200 Subject: [PATCH] feat: embed lyrics into MP3 ID3 tags Fetch plain and synchronized lyrics from LRCLIB and write them to USLT and SYLT. Both frames are written when timed lyrics exist, while plain-only results produce only USLT. Missing lyrics or lookup errors never fail a download, and existing tags, artwork, audio data and previously embedded lyrics are preserved. Add --lyrics/--no-lyrics and the lyrics_enabled config key. The feature is enabled by default for MP3 and does not affect M4A or Opus output. --- CHANGELOG.md | 2 + README.md | 40 ++- README.ru.md | 39 ++- README.uk.md | 39 ++- docs/tldr/trackfetch.md | 8 + tests/test_config.py | 1 + tests/test_lyrics.py | 527 ++++++++++++++++++++++++++++++++++++++++ tests/test_pipeline.py | 64 +++++ trackfetch.py | 270 ++++++++++++++++++++ 9 files changed, 984 insertions(+), 6 deletions(-) create mode 100644 tests/test_lyrics.py diff --git a/CHANGELOG.md b/CHANGELOG.md index aa33ffe..67efcac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/). ## [Unreleased] ### Added +- Optional lyrics embedding for MP3: plain lyrics from LRCLIB are written to the `USLT` ID3 frame and synchronized lyrics to `SYLT`. Both frames are written when timed lyrics exist, so players without `SYLT` support still show the words. Missing lyrics never fail the download. +- `--lyrics`/`--no-lyrics` and the `lyrics_enabled` config key. Embedding is enabled by default for MP3 and does not affect the audio data or existing non-lyrics tags. - Configurable free metadata providers: iTunes (the new default), Deezer, MusicBrainz with Cover Art Archive, VocaDB and optional Spotify. No API key is needed except for Spotify. - `-s`/`--metadata-sources` with priority ordering, `none`, duplicate removal and unknown-name validation. YouTube stays a separate artwork fallback and is not part of the metadata ordering. - `--disable-sources`, `--provider-opt NAME.KEY=VALUE`, `--match-threshold`, `--title-threshold` and `--list-sources`. diff --git a/README.md b/README.md index 6f188ab..4647475 100644 --- a/README.md +++ b/README.md @@ -182,7 +182,7 @@ trackfetch "My Playlist.txt" -o ~/Music/"My Playlist" ## Usage ```text -trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [-s SOURCES] [--disable-sources SOURCES] [--provider-opt NAME.KEY=VALUE] [--match-threshold SCORE] [--title-threshold SCORE] [--list-sources] [--spotify-client-id ID] [--spotify-client-secret SECRET] [--no-logs] [INPUT ...] +trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [-s SOURCES] [--disable-sources SOURCES] [--provider-opt NAME.KEY=VALUE] [--match-threshold SCORE] [--title-threshold SCORE] [--list-sources] [--spotify-client-id ID] [--spotify-client-secret SECRET] [--no-logs] [--lyrics | --no-lyrics] [INPUT ...] ``` | Option | Default | What it does | @@ -203,6 +203,7 @@ trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f { | `--spotify-client-id` | `$SPOTIFY_CLIENT_ID` | Spotify API client ID. See [Spotify credentials](#spotify-credentials). | | `--spotify-client-secret` | `$SPOTIFY_CLIENT_SECRET` | Spotify API client secret. | | `--no-logs` | off | Do not read `done.txt` and do not write `done.txt` or `failed.txt`. Progress from earlier runs is ignored, so finished songs are not skipped. | +| `--lyrics` / `--no-lyrics` | on | Embed lyrics fetched from LRCLIB into MP3 tags. Plain text goes to `USLT`; timed lyrics also go to `SYLT`. Missing lyrics never fail the download. | ```bash trackfetch songs.txt -o ~/Music/RoadTrip # save to a specific folder @@ -268,6 +269,38 @@ MIME type. MP3 and Opus can embed all four; M4A supports JPEG and PNG, so GIF or WebP artwork is skipped for that container instead of being mislabelled as JPEG. +### Lyrics + +For MP3 output trackfetch also looks up lyrics on [LRCLIB](https://lrclib.net/) +and embeds them in the ID3 tag, so players can show the words offline without +sidecar `.lrc` or `.txt` files. + +| Frame | Contents | +| --- | --- | +| `USLT` | The full plain text, without timestamps. | +| `SYLT` | Timed lines, only when the source returns synchronized lyrics. | + +When timed lyrics are available, both frames are written: `USLT` keeps the +full text for players without `SYLT` support. When only plain lyrics are +available, only `USLT` is written. Timestamps are never invented. + +The source is LRCLIB, which needs no API key. Lyrics embedding is enabled by +default for MP3 and can be turned off with `--no-lyrics` or +`lyrics_enabled = false` in the config file. The other formats (`m4a`, `opus`) +are not changed by this option. + +Missing lyrics, a timeout or an HTTP error never fails the download. The MP3 +is still saved with its usual metadata. If an MP3 already contains lyrics and +no new lyrics are found, the existing frames are left untouched. When new +lyrics are found, the old `USLT`/`SYLT` frames are replaced instead of +duplicated. Existing tags and cover art, and the audio data itself, are never +rewritten or re-encoded. + +```bash +trackfetch songs.txt --format mp3 # embed lyrics (default) +trackfetch songs.txt --format mp3 --no-lyrics # keep MP3 tags lyrics-free +``` + ### Inline tracks Skip the file and name the tracks right on the command line: @@ -322,6 +355,9 @@ vocadb_min_interval = 0.5 # YouTube artwork fallback youtube_enabled = true +# Lyrics embedding into MP3 tags +lyrics_enabled = true + # Matching thresholds match_threshold = 0.6 title_threshold = 0.8 @@ -386,7 +422,7 @@ environment variable. | `opus` | YouTube's **original** Opus audio, copied without re-encoding. The best quality you can get | most modern players, Android, browsers; not iTunes or older devices | | `mp3` | YouTube's audio **re-encoded** to the best VBR MP3. A second lossy encode, so slightly below the source | everything, including old players and car stereos | -All three get the same tags and embedded cover art. `done.txt` doesn't track the format, so use a separate `-o` folder for each format. +All three get the same metadata tags and embedded cover art. Embedded lyrics are written to MP3 only. `done.txt` doesn't track the format, so use a separate `-o` folder for each format. ### Input file diff --git a/README.ru.md b/README.ru.md index 30538d4..2e2ebda 100644 --- a/README.ru.md +++ b/README.ru.md @@ -182,7 +182,7 @@ trackfetch "My Playlist.txt" -o ~/Music/"My Playlist" ## Использование ```text -trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [-s SOURCES] [--disable-sources SOURCES] [--provider-opt NAME.KEY=VALUE] [--match-threshold SCORE] [--title-threshold SCORE] [--list-sources] [--spotify-client-id ID] [--spotify-client-secret SECRET] [--no-logs] [INPUT ...] +trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [-s SOURCES] [--disable-sources SOURCES] [--provider-opt NAME.KEY=VALUE] [--match-threshold SCORE] [--title-threshold SCORE] [--list-sources] [--spotify-client-id ID] [--spotify-client-secret SECRET] [--no-logs] [--lyrics | --no-lyrics] [INPUT ...] ``` | Параметр | По умолчанию | Что делает | @@ -203,6 +203,7 @@ trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f { | `--spotify-client-id` | `$SPOTIFY_CLIENT_ID` | Client ID для Spotify API. См. [Данные Spotify](#данные-spotify). | | `--spotify-client-secret` | `$SPOTIFY_CLIENT_SECRET` | Client secret для Spotify API. | | `--no-logs` | выключен | Не читать `done.txt` и не писать `done.txt` и `failed.txt`. Прогресс прошлых запусков не учитывается, поэтому готовые песни не пропускаются. | +| `--lyrics` / `--no-lyrics` | включён | Встраивать текст из LRCLIB в теги MP3. Обычный текст пишется в `USLT`, синхронизированный — ещё и в `SYLT`. Если текста нет, загрузка не считается ошибкой. | ```bash trackfetch songs.txt -o ~/Music/RoadTrip # сохранить в конкретную папку @@ -269,6 +270,37 @@ PNG, поэтому GIF или WebP для этого контейнера пр как JPEG. ``` +### Текст песни + +Для MP3 trackfetch также ищет текст на [LRCLIB](https://lrclib.net/) и +встраивает его в ID3-теги, чтобы плеер показывал слова без интернета и +отдельных файлов `.lrc` или `.txt`. + +| Фрейм | Содержимое | +| --- | --- | +| `USLT` | Полный обычный текст без таймкодов. | +| `SYLT` | Строки с временными метками, только если источник вернул синхронизированный текст. | + +Если синхронизированный текст есть, записываются оба фрейма: `USLT` нужен +плеерам без поддержки `SYLT`. Если есть только обычный текст, записывается +только `USLT`. Искусственные таймкоды не создаются. + +Источник — LRCLIB, ключ API не нужен. По умолчанию встраивание включено для +MP3; отключить можно флагом `--no-lyrics` или строкой +`lyrics_enabled = false` в конфиге. На форматы `m4a` и `opus` эта настройка +не влияет. + +Если текст не найден, произошла ошибка сети или сервер вернул ошибку, загрузка +не прерывается: MP3 сохраняется с обычными метаданными. Если в файле уже была +лирика, а новая не найдена, старые фреймы остаются. При новой лирике прежние +`USLT`/`SYLT` заменяются, а не дублируются. Остальные теги, обложка и сами +аудиоданные не перекодируются и не повреждаются. + +```bash +trackfetch songs.txt --format mp3 # встроить текст (по умолчанию) +trackfetch songs.txt --format mp3 --no-lyrics # не добавлять текст в MP3 +``` + ### Треки прямо в аргументах Можно не заводить файл, а назвать треки прямо в командной строке: @@ -324,6 +356,9 @@ vocadb_min_interval = 0.5 # Запасная обложка YouTube youtube_enabled = true +# Встраивание текста песни в теги MP3 +lyrics_enabled = true + # Пороги совпадения match_threshold = 0.6 title_threshold = 0.8 @@ -387,7 +422,7 @@ trackfetch songs.txt --spotify-client-id твой-id --spotify-client-secret т | `opus` | **Оригинальный** звук YouTube в Opus, скопированный без перекодирования. Лучшее доступное качество | большинство современных плееров, Android, браузеры; не iTunes и не старые устройства | | `mp3` | Звук YouTube, **перекодированный** в MP3 VBR максимального качества. Это повторное сжатие с потерями, поэтому чуть хуже исходника | везде, включая старые плееры и автомагнитолы | -Во всех трёх форматах одинаковые теги и встроенная обложка. `done.txt` не учитывает формат, поэтому для каждого формата указывай отдельную папку `-o`. +Во всех трёх форматах одинаковые метаданные и встроенная обложка. Текст песни встраивается только в MP3. `done.txt` не учитывает формат, поэтому для каждого формата указывай отдельную папку `-o`. ### Входной файл diff --git a/README.uk.md b/README.uk.md index 59006ec..4061ccb 100644 --- a/README.uk.md +++ b/README.uk.md @@ -182,7 +182,7 @@ trackfetch "My Playlist.txt" -o ~/Music/"My Playlist" ## Використання ```text -trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [-s SOURCES] [--disable-sources SOURCES] [--provider-opt NAME.KEY=VALUE] [--match-threshold SCORE] [--title-threshold SCORE] [--list-sources] [--spotify-client-id ID] [--spotify-client-secret SECRET] [--no-logs] [INPUT ...] +trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [-s SOURCES] [--disable-sources SOURCES] [--provider-opt NAME.KEY=VALUE] [--match-threshold SCORE] [--title-threshold SCORE] [--list-sources] [--spotify-client-id ID] [--spotify-client-secret SECRET] [--no-logs] [--lyrics | --no-lyrics] [INPUT ...] ``` | Параметр | За замовчуванням | Що робить | @@ -203,6 +203,7 @@ trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f { | `--spotify-client-id` | `$SPOTIFY_CLIENT_ID` | Client ID для Spotify API. Див. [Дані Spotify](#дані-spotify). | | `--spotify-client-secret` | `$SPOTIFY_CLIENT_SECRET` | Client secret для Spotify API. | | `--no-logs` | вимкнено | Не читати `done.txt` і не писати `done.txt` та `failed.txt`. Прогрес минулих запусків не враховується, тому готові пісні не пропускаються. | +| `--lyrics` / `--no-lyrics` | увімкнено | Вбудовувати текст із LRCLIB у теги MP3. Звичайний текст пишеться в `USLT`, синхронізований — ще й у `SYLT`. Якщо тексту немає, завантаження не вважається помилкою. | ```bash trackfetch songs.txt -o ~/Music/RoadTrip # зберегти в конкретну теку @@ -269,6 +270,37 @@ MIME тип. MP3 і Opus можуть вбудовувати всі чотири як JPEG. ``` +### Текст пісні + +Для MP3 trackfetch також шукає текст на [LRCLIB](https://lrclib.net/) і +вбудовує його в ID3-теги, щоб плеєр показував слова без інтернету та окремих +файлів `.lrc` чи `.txt`. + +| Фрейм | Вміст | +| --- | --- | +| `USLT` | Повний звичайний текст без таймкодів. | +| `SYLT` | Рядки з часовими мітками, лише якщо джерело повернуло синхронізований текст. | + +Якщо синхронізований текст є, записуються обидва фрейми: `USLT` потрібен +плеєрам без підтримки `SYLT`. Якщо є лише звичайний текст, записується тільки +`USLT`. Штучні таймкоди не створюються. + +Джерело — LRCLIB, ключ API не потрібен. За замовчуванням вбудовування +увімкнено для MP3; вимкнути можна прапорцем `--no-lyrics` або рядком +`lyrics_enabled = false` у конфігу. На формати `m4a` та `opus` це +налаштування не впливає. + +Якщо текст не знайдено, сталася помилка мережі або сервер повернув помилку, +завантаження не переривається: MP3 зберігається зі звичайними метаданими. Якщо +у файлі вже був текст, а новий не знайдено, старі фрейми залишаються. Коли +знайдено новий текст, попередні `USLT`/`SYLT` замінюються, а не дублюються. +Інші теги, обкладинка й самі аудіодані не перекодовуються й не пошкоджуються. + +```bash +trackfetch songs.txt --format mp3 # вбудувати текст (за замовчуванням) +trackfetch songs.txt --format mp3 --no-lyrics # не додавати текст у MP3 +``` + ### Треки просто в аргументах Можна не заводити файл, а назвати треки просто в командному рядку: @@ -324,6 +356,9 @@ vocadb_min_interval = 0.5 # Запасна обкладинка YouTube youtube_enabled = true +# Вбудовування тексту пісні в теги MP3 +lyrics_enabled = true + # Пороги збігу match_threshold = 0.6 title_threshold = 0.8 @@ -387,7 +422,7 @@ trackfetch songs.txt --spotify-client-id твій-id --spotify-client-secret т | `opus` | **Оригінальний** звук YouTube в Opus, скопійований без перекодування. Найкраща доступна якість | більшість сучасних плеєрів, Android, браузери; не iTunes і не старі пристрої | | `mp3` (за замовчуванням) | Звук YouTube, **перекодований** у MP3 VBR максимальної якості. Це повторне стиснення з втратами, тому трохи гірше за оригінал | усюди, зокрема старі плеєри й автомагнітоли | -У всіх трьох форматах однакові теги й вбудована обкладинка. `done.txt` не враховує формат, тому для кожного формату вказуй окрему теку `-o`. +У всіх трьох форматах однакові метадані й вбудована обкладинка. Текст пісні вбудовується лише в MP3. `done.txt` не враховує формат, тому для кожного формату вказуй окрему теку `-o`. ### Вхідний файл diff --git a/docs/tldr/trackfetch.md b/docs/tldr/trackfetch.md index cfe233b..a1b5fc6 100644 --- a/docs/tldr/trackfetch.md +++ b/docs/tldr/trackfetch.md @@ -16,6 +16,14 @@ `trackfetch {{path/to/songs.txt}} {{[-f|--format]}} {{opus|m4a}}` +- Embed lyrics from LRCLIB into MP3 tags (enabled by default): + +`trackfetch {{path/to/songs.txt}} {{[-f|--format]}} {{mp3}}` + +- Do not embed lyrics into MP3 tags: + +`trackfetch {{path/to/songs.txt}} {{[-f|--format]}} {{mp3}} --no-lyrics` + - Download a few tracks without a text file: `trackfetch {{"Artist - Title"}} {{"Another Artist - Another Title"}}` diff --git a/tests/test_config.py b/tests/test_config.py index 0d76419..1dad8e8 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -42,6 +42,7 @@ def fake_resolve_metadata(artist, title, source_config, runtime): monkeypatch.setattr(m, "download_audio", fake_download_audio) monkeypatch.setattr(m, "download_cover", fake_download_cover) monkeypatch.setattr(m, "get_spotify", lambda *a, **k: object()) + monkeypatch.setattr(m, "fetch_lyrics", lambda *a, **k: None) monkeypatch.setattr(m.time, "sleep", lambda s: None) return state diff --git a/tests/test_lyrics.py b/tests/test_lyrics.py new file mode 100644 index 0000000..8f97450 --- /dev/null +++ b/tests/test_lyrics.py @@ -0,0 +1,527 @@ +import argparse +import sys + +import pytest +from mutagen.id3 import COMM, ID3, TCOM, TIT2, USLT + +import trackfetch as m + +CYRILLIC_LYRICS = "Привет, мир!\nВторая строка — с тире и «кавычками»." +UNICODE_LYRICS = "Hello — “world”!\n第二行 🎵 & " +SYNCED_LRC = """[ar:Artist] +[00:01.50]First line +[00:03.000]Вторая строка +[00:04.25]Third line +""" + + +def make_args(**overrides): + values = { + "metadata_sources": None, + "disable_sources": None, + "provider_opt": None, + "match_threshold": None, + "title_threshold": None, + "lyrics_enabled": None, + } + values.update(overrides) + return argparse.Namespace(**values) + + +def make_mp3(path, payload=b"\x00" * 64): + path.write_bytes(payload) + return path + + +def audio_payload(path): + """Return the bytes after the leading ID3v2 tag.""" + data = path.read_bytes() + assert data[:3] == b"ID3" + size = ( + (data[6] << 21) + | (data[7] << 14) + | (data[8] << 7) + | data[9] + ) + return data[10 + size:] + + +class FakeResponse: + def __init__(self, payload=None, status_code=200, json_error=None): + self.payload = payload + self.status_code = status_code + self.json_error = json_error + + def json(self): + if self.json_error is not None: + raise self.json_error + return self.payload + + +class FakeSession: + def __init__(self, response): + self.response = response + self.calls = [] + + def get(self, url, **kwargs): + self.calls.append({"url": url, **kwargs}) + return self.response + + +def make_runtime(response): + session = FakeSession(response) + runtime = m.MetadataRuntime( + session=session, + limiter=m.RateLimiter({"lrclib": 0.0}), + ) + return runtime, session + + +class TestParseSyncedLyrics: + def test_parses_fractions_and_metadata(self): + assert m.parse_synced_lyrics(SYNCED_LRC) == [ + ("First line", 1500), + ("Вторая строка", 3000), + ("Third line", 4250), + ] + + def test_one_digit_fraction_means_tenths(self): + assert m.parse_synced_lyrics("[00:01.5]Line") == [("Line", 1500)] + + def test_multiple_timestamps_for_one_line(self): + assert m.parse_synced_lyrics("[00:01.00][00:02.00]Chorus") == [ + ("Chorus", 1000), + ("Chorus", 2000), + ] + + def test_sorts_out_of_order_timestamps(self): + assert m.parse_synced_lyrics( + "[00:05.00]Later\n[00:01.00]Earlier\n" + ) == [("Earlier", 1000), ("Later", 5000)] + + def test_skips_blank_lines(self): + assert m.parse_synced_lyrics("[00:01.00] ") == [] + + +class TestSelectLyrics: + def test_selects_best_matching_result(self): + results = [ + { + "trackName": "Another Song", + "artistName": "Artist", + "plainLyrics": "wrong", + }, + { + "trackName": "Song", + "artistName": "Artist", + "plainLyrics": "right", + "syncedLyrics": "[00:01.00]right", + }, + ] + + lyrics = m.select_lyrics(results, "Artist", "Song") + + assert lyrics["plain"] == "right" + assert lyrics["synced"] == "[00:01.00]right" + + def test_instrumental_is_ignored(self): + results = [ + { + "trackName": "Song", + "artistName": "Artist", + "instrumental": True, + "plainLyrics": "should not be used", + } + ] + + assert m.select_lyrics(results, "Artist", "Song") is None + + def test_plain_only_has_no_synced_text(self): + results = [ + { + "trackName": "Song", + "artistName": "Artist", + "plainLyrics": "Words", + } + ] + + lyrics = m.select_lyrics(results, "Artist", "Song") + + assert lyrics["plain"] == "Words" + assert lyrics["synced"] is None + + def test_timed_only_derives_plain_text(self): + results = [ + { + "trackName": "Song", + "artistName": "Artist", + "syncedLyrics": "[00:01.00]One\n[00:02.00]Two", + } + ] + + lyrics = m.select_lyrics(results, "Artist", "Song") + + assert lyrics["plain"] == "One\nTwo" + assert lyrics["synced"].startswith("[00:01.00]") + + def test_no_matching_result(self): + results = [ + { + "trackName": "Unrelated", + "artistName": "Someone", + "plainLyrics": "Words", + } + ] + + assert m.select_lyrics(results, "Artist", "Song") is None + + +class TestFetchLyrics: + def test_returns_matching_lyrics(self): + response = FakeResponse( + [ + { + "trackName": "Song", + "artistName": "Artist", + "plainLyrics": "Words", + "syncedLyrics": "[00:01.00]Words", + } + ] + ) + runtime, session = make_runtime(response) + + lyrics = m.fetch_lyrics("Artist", "Song", runtime) + + assert lyrics["plain"] == "Words" + assert session.calls[0]["params"] == { + "artist_name": "Artist", + "track_name": "Song", + } + assert session.calls[0]["url"] == m.LRCLIB_SEARCH_URL + + def test_404_means_no_lyrics(self): + runtime, _ = make_runtime(FakeResponse(status_code=404)) + + assert m.fetch_lyrics("Artist", "Song", runtime=runtime) is None + + def test_http_error_raises_provider_error(self): + runtime, _ = make_runtime(FakeResponse(status_code=500)) + + with pytest.raises(m.ProviderError, match="HTTP 500"): + m.fetch_lyrics("Artist", "Song", runtime=runtime) + + def test_invalid_json_raises_provider_error(self): + runtime, _ = make_runtime( + FakeResponse(json_error=ValueError("bad json")) + ) + + with pytest.raises(m.ProviderError, match="invalid JSON"): + m.fetch_lyrics("Artist", "Song", runtime=runtime) + + +class TestMp3Lyrics: + def test_writes_and_reads_uslt(self, tmp_path): + mp3 = make_mp3(tmp_path / "song.mp3") + + m.add_mp3_metadata( + mp3, + tmp_path / "missing.jpg", + m.fallback_metadata("Artist", "Song"), + {"plain": CYRILLIC_LYRICS}, + ) + + tags = ID3(mp3) + assert tags.getall("USLT")[0].text == CYRILLIC_LYRICS + assert not tags.getall("SYLT") + + def test_writes_and_reads_sylt(self, tmp_path): + mp3 = make_mp3(tmp_path / "song.mp3") + + m.add_mp3_metadata( + mp3, + tmp_path / "missing.jpg", + m.fallback_metadata("Artist", "Song"), + {"plain": CYRILLIC_LYRICS, "synced": SYNCED_LRC}, + ) + + sylt = ID3(mp3).getall("SYLT")[0] + assert sylt.format == 2 + assert sylt.type == 1 + assert sylt.text == [ + ("First line", 1500), + ("Вторая строка", 3000), + ("Third line", 4250), + ] + + def test_writes_both_frames_when_timed_lyrics_exist(self, tmp_path): + mp3 = make_mp3(tmp_path / "song.mp3") + + m.add_mp3_metadata( + mp3, + tmp_path / "missing.jpg", + m.fallback_metadata("Artist", "Song"), + {"plain": CYRILLIC_LYRICS, "synced": SYNCED_LRC}, + ) + + tags = ID3(mp3) + assert tags.getall("USLT")[0].text == CYRILLIC_LYRICS + assert tags.getall("SYLT")[0].text + + def test_unicode_and_special_characters_roundtrip(self, tmp_path): + mp3 = make_mp3(tmp_path / "song.mp3") + first, second = UNICODE_LYRICS.splitlines() + + m.add_mp3_metadata( + mp3, + tmp_path / "missing.jpg", + m.fallback_metadata("Artist", "Song"), + { + "plain": UNICODE_LYRICS, + "synced": f"[00:01.00]{first}\n[00:02.00]{second}", + }, + ) + + tags = ID3(mp3) + assert tags.getall("USLT")[0].text == UNICODE_LYRICS + assert tags.getall("SYLT")[0].text == [ + (first, 1000), + (second, 2000), + ] + + def test_no_lyrics_adds_no_empty_frames(self, tmp_path): + mp3 = make_mp3(tmp_path / "song.mp3") + + m.add_mp3_metadata( + mp3, + tmp_path / "missing.jpg", + m.fallback_metadata("Artist", "Song"), + None, + ) + + tags = ID3(mp3) + assert not tags.getall("USLT") + assert not tags.getall("SYLT") + + def test_empty_lyrics_adds_no_frames(self, tmp_path): + mp3 = make_mp3(tmp_path / "song.mp3") + + m.add_mp3_metadata( + mp3, + tmp_path / "missing.jpg", + m.fallback_metadata("Artist", "Song"), + {"plain": " ", "synced": "[00:01.00] "}, + ) + + tags = ID3(mp3) + assert not tags.getall("USLT") + assert not tags.getall("SYLT") + + def test_existing_lyrics_are_kept_when_none_found(self, tmp_path): + mp3 = make_mp3(tmp_path / "song.mp3") + old = ID3() + old.add(USLT(encoding=3, lang="eng", desc="", text="Old words")) + old.save(mp3) + + m.add_mp3_metadata( + mp3, + tmp_path / "missing.jpg", + m.fallback_metadata("Artist", "Song"), + None, + ) + + tags = ID3(mp3) + assert tags.getall("USLT")[0].text == "Old words" + assert not tags.getall("SYLT") + + def test_rewrites_without_duplicates(self, tmp_path): + mp3 = make_mp3(tmp_path / "song.mp3") + metadata = m.fallback_metadata("Artist", "Song") + + m.add_mp3_metadata( + mp3, + tmp_path / "missing.jpg", + metadata, + {"plain": "Old words", "synced": "[00:01.00]Old words"}, + ) + m.add_mp3_metadata( + mp3, + tmp_path / "missing.jpg", + metadata, + {"plain": "New words", "synced": "[00:02.00]New words"}, + ) + + tags = ID3(mp3) + assert len(tags.getall("USLT")) == 1 + assert len(tags.getall("SYLT")) == 1 + assert tags.getall("USLT")[0].text == "New words" + assert tags.getall("SYLT")[0].text == [("New words", 2000)] + + def test_preserves_existing_tags_and_cover(self, tmp_path): + mp3 = make_mp3(tmp_path / "song.mp3") + cover = tmp_path / "cover.jpg" + cover.write_bytes(b"\xff\xd8\xff\xe0jpeg") + + old = ID3() + old.add(TCOM(encoding=3, text="Composer")) + old.add(COMM(encoding=3, lang="eng", desc="", text="A comment")) + old.add(TIT2(encoding=3, text="Old title")) + old.save(mp3) + + m.add_mp3_metadata( + mp3, + cover, + m.fallback_metadata("Artist", "Song"), + {"plain": "Words"}, + ) + + tags = ID3(mp3) + assert tags.getall("TCOM")[0].text == ["Composer"] + assert tags.getall("COMM")[0].text == ["A comment"] + assert tags.getall("TIT2")[0].text == ["Song"] + assert tags.getall("APIC")[0].data == cover.read_bytes() + assert tags.getall("USLT")[0].text == "Words" + + def test_does_not_change_audio_payload(self, tmp_path): + payload = bytes(range(256)) * 4 + mp3 = make_mp3(tmp_path / "song.mp3", payload) + + m.add_mp3_metadata( + mp3, + tmp_path / "missing.jpg", + m.fallback_metadata("Artist", "Song"), + {"plain": "Words", "synced": "[00:01.00]Words"}, + ) + + assert audio_payload(mp3) == payload + + +class TestLyricsSettings: + def test_enabled_by_default(self): + assert m.build_source_config(make_args(), {}).lyrics_enabled is True + + def test_config_can_disable(self): + config = m.build_source_config( + make_args(), + {"lyrics_enabled": "false"}, + ) + + assert config.lyrics_enabled is False + + def test_config_can_enable(self): + config = m.build_source_config( + make_args(), + {"lyrics_enabled": "true"}, + ) + + assert config.lyrics_enabled is True + + def test_cli_enable_wins_over_config_disable(self): + config = m.build_source_config( + make_args(lyrics_enabled=True), + {"lyrics_enabled": "false"}, + ) + + assert config.lyrics_enabled is True + + def test_cli_disable_wins_over_config_enable(self): + config = m.build_source_config( + make_args(lyrics_enabled=False), + {"lyrics_enabled": "true"}, + ) + + assert config.lyrics_enabled is False + + def test_invalid_config_value_is_rejected(self): + with pytest.raises(ValueError, match="lyrics_enabled"): + m.build_source_config( + make_args(), + {"lyrics_enabled": "maybe"}, + ) + + +class TestLyricsCli: + def run_cli(self, monkeypatch, *args): + monkeypatch.setattr(sys, "argv", ["trackfetch", *map(str, args)]) + m.main() + + def test_no_lyrics_is_shown_by_list_sources( + self, monkeypatch, tmp_path, capsys + ): + monkeypatch.chdir(tmp_path) + monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg")) + monkeypatch.delenv("TRACKFETCH_CONFIG", raising=False) + monkeypatch.setattr( + m.Path, "home", classmethod(lambda cls: tmp_path / "home") + ) + + self.run_cli(monkeypatch, "--list-sources", "--no-lyrics") + + assert "Lyrics embedding: disabled" in capsys.readouterr().out + + def test_default_is_enabled_in_list_sources( + self, monkeypatch, tmp_path, capsys + ): + monkeypatch.chdir(tmp_path) + monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg")) + monkeypatch.delenv("TRACKFETCH_CONFIG", raising=False) + monkeypatch.setattr( + m.Path, "home", classmethod(lambda cls: tmp_path / "home") + ) + + self.run_cli(monkeypatch, "--list-sources") + + output = capsys.readouterr().out + assert "Lyrics embedding: enabled" in output + + def test_config_disables_lyrics(self, monkeypatch, tmp_path, capsys): + config = tmp_path / "cfg.ini" + config.write_text( + "[trackfetch]\nlyrics_enabled = false\n", + encoding="utf-8", + ) + + self.run_cli( + monkeypatch, + "--list-sources", + "--config", + config, + ) + + assert "Lyrics embedding: disabled" in capsys.readouterr().out + + def test_cli_enables_lyrics_over_disabled_config( + self, monkeypatch, tmp_path, capsys + ): + config = tmp_path / "cfg.ini" + config.write_text( + "[trackfetch]\nlyrics_enabled = false\n", + encoding="utf-8", + ) + + self.run_cli( + monkeypatch, + "--list-sources", + "--config", + config, + "--lyrics", + ) + + assert "Lyrics embedding: enabled" in capsys.readouterr().out + + def test_invalid_config_value_exits(self, monkeypatch, tmp_path, capsys): + config = tmp_path / "cfg.ini" + config.write_text( + "[trackfetch]\nlyrics_enabled = maybe\n", + encoding="utf-8", + ) + + with pytest.raises(SystemExit) as exc: + self.run_cli( + monkeypatch, + "--list-sources", + "--config", + config, + ) + + assert exc.value.code == 1 + assert "Invalid value for 'lyrics_enabled'" in capsys.readouterr().out diff --git a/tests/test_pipeline.py b/tests/test_pipeline.py index 88a02eb..7ee88c3 100644 --- a/tests/test_pipeline.py +++ b/tests/test_pipeline.py @@ -1,3 +1,4 @@ +import argparse import shutil import sys @@ -60,6 +61,7 @@ def fake_resolve_metadata(artist, title, source_config, runtime): monkeypatch.setattr(m, "download_audio", fake_download_audio) monkeypatch.setattr(m, "download_cover", fake_download_cover) monkeypatch.setattr(m, "get_spotify", lambda *a, **k: object()) + monkeypatch.setattr(m, "fetch_lyrics", lambda *a, **k: None) monkeypatch.setattr(m.time, "sleep", lambda s: None) return state @@ -76,6 +78,68 @@ def test_downloads_and_tags(self, pipeline, tmp_path): assert tags.getall("APIC") assert pipeline["downloaded_urls"] == ["https://www.youtube.com/watch?v=abc"] + def test_embeds_plain_and_timed_lyrics(self, pipeline, tmp_path, monkeypatch): + monkeypatch.setattr( + m, + "fetch_lyrics", + lambda *args, **kwargs: { + "plain": "Привет, мир!\nВторая строка", + "synced": "[00:01.00]Привет, мир!\n[00:02.00]Вторая строка", + }, + ) + + assert m.process_song( + None, "a", "b", tmp_path, False + ) == (True, "downloaded") + + tags = ID3(tmp_path / "Daft Punk - One More Time.mp3") + assert tags.getall("USLT")[0].text == "Привет, мир!\nВторая строка" + assert tags.getall("SYLT")[0].text == [ + ("Привет, мир!", 1000), + ("Вторая строка", 2000), + ] + + def test_missing_lyrics_does_not_fail_download( + self, pipeline, tmp_path, capsys + ): + assert m.process_song( + None, "a", "b", tmp_path, False + ) == (True, "downloaded") + + tags = ID3(tmp_path / "Daft Punk - One More Time.mp3") + assert not tags.getall("USLT") + assert not tags.getall("SYLT") + assert "Lyrics: not found" in capsys.readouterr().out + + def test_disabled_lyrics_are_not_fetched(self, pipeline, tmp_path, monkeypatch): + def boom(*args, **kwargs): + raise AssertionError("lyrics must not be fetched") + + monkeypatch.setattr(m, "fetch_lyrics", boom) + config = m.build_source_config( + argparse.Namespace( + metadata_sources=None, + disable_sources=None, + provider_opt=None, + match_threshold=None, + title_threshold=None, + lyrics_enabled=False, + ), + {}, + ) + + assert m.process_song( + None, + "a", + "b", + tmp_path, + False, + "mp3", + source_config=config, + ) == (True, "downloaded") + assert not ID3(tmp_path / "Daft Punk - One More Time.mp3").getall("USLT") + + def test_opus(self, pipeline, tmp_path): assert m.process_song(None, "a", "b", tmp_path, False, "opus") == (True, "downloaded") tags = OggOpus(tmp_path / "Daft Punk - One More Time.opus") diff --git a/trackfetch.py b/trackfetch.py index e7b7838..8f7b44d 100755 --- a/trackfetch.py +++ b/trackfetch.py @@ -23,12 +23,14 @@ from mutagen.id3 import ( APIC, ID3, + SYLT, TALB, TDRC, TIT2, TPE1, TPE2, TRCK, + USLT, ) from mutagen.mp4 import MP4, MP4Cover from mutagen.oggopus import OggOpus @@ -101,6 +103,15 @@ DEFAULT_MATCH_THRESHOLD = 0.6 DEFAULT_TITLE_THRESHOLD = 0.8 YOUTUBE_DEFAULT_ENABLED = True +LYRICS_DEFAULT_ENABLED = True +LYRICS_LANGUAGE = "und" +LYRICS_TIMEOUT = 15 +LYRICS_MIN_INTERVAL = 0.5 +LRCLIB_SEARCH_URL = "https://lrclib.net/api/search" + +LRC_TIMESTAMP_RE = re.compile( + r"\[(\d{1,3}):(\d{2})(?:[.:](\d{1,3}))?\]" +) CACHE_FILENAME = "metadata-cache.json" CACHE_VERSION = 1 @@ -264,6 +275,7 @@ def __init__( match_threshold, title_threshold, none_selected=False, + lyrics_enabled=LYRICS_DEFAULT_ENABLED, ): self.metadata_sources = list(metadata_sources) self.youtube_enabled = bool(youtube_enabled) @@ -271,6 +283,7 @@ def __init__( self.match_threshold = match_threshold self.title_threshold = title_threshold self.none_selected = bool(none_selected) + self.lyrics_enabled = bool(lyrics_enabled) def interval(self, name: str) -> float: return self.providers[name]["min_interval"] @@ -597,6 +610,19 @@ def build_source_config(args, settings): if "youtube" in all_disabled_sources: youtube_enabled = False + lyrics_enabled = LYRICS_DEFAULT_ENABLED + + if "lyrics_enabled" in settings and str(settings["lyrics_enabled"]).strip(): + lyrics_enabled = parse_bool( + settings["lyrics_enabled"], + "lyrics_enabled", + ) + + cli_lyrics = getattr(args, "lyrics_enabled", None) + + if cli_lyrics is not None: + lyrics_enabled = bool(cli_lyrics) + match_threshold = threshold_value( getattr(args, "match_threshold", None), threshold_value( @@ -623,6 +649,7 @@ def build_source_config(args, settings): match_threshold, title_threshold, none_selected, + lyrics_enabled, ) @@ -690,6 +717,12 @@ def format_source_list(config: SourceConfig) -> str: f"Metadata priority: {', '.join(config.metadata_sources) or 'none'}", f"Match threshold: {config.match_threshold}", f"Title threshold: {config.title_threshold}", + "Lyrics embedding: " + + ( + "enabled (LRCLIB, MP3 only)" + if config.lyrics_enabled + else "disabled" + ), ] ) @@ -1878,6 +1911,190 @@ def resolve_metadata(artist: str, title: str, config: SourceConfig, runtime): return fallback +def lrc_fraction_to_ms(fraction: str) -> int: + """Convert the fractional part of an LRC timestamp to milliseconds.""" + if not fraction: + return 0 + + return int(fraction.ljust(3, "0")[:3]) + + +def parse_synced_lyrics(text: str): + """Parse LRC text into (line, timestamp in milliseconds) pairs.""" + entries = [] + + for line in (text or "").splitlines(): + timestamps = LRC_TIMESTAMP_RE.findall(line) + + if not timestamps: + # LRC metadata such as [ar:Artist] has no timestamp and is skipped. + continue + + lyric = LRC_TIMESTAMP_RE.sub("", line).strip() + + if not lyric: + continue + + for minutes, seconds, fraction in timestamps: + timestamp = ( + int(minutes) * 60_000 + + int(seconds) * 1000 + + lrc_fraction_to_ms(fraction) + ) + entries.append((lyric, timestamp)) + + entries.sort(key=lambda entry: entry[1]) + + return entries + + +def select_lyrics(results, artist: str, title: str): + """Choose the best matching lyrics result and normalize its fields.""" + best = None + + for item in results or []: + if not isinstance(item, dict) or item.get("instrumental"): + continue + + candidate = { + "title": item.get("trackName") or "", + "artist": item.get("artistName") or "", + } + scored = score_metadata( + artist, + title, + candidate, + DEFAULT_MATCH_THRESHOLD, + DEFAULT_TITLE_THRESHOLD, + ) + + if scored is None: + continue + + plain = (item.get("plainLyrics") or "").strip() + synced = (item.get("syncedLyrics") or "").strip() + synced_entries = parse_synced_lyrics(synced) + + if not plain and synced_entries: + # Some sources only return timed lyrics. USLT still has to hold the + # full text, so strip the timestamps without inventing new ones. + plain = "\n".join(line for line, _ in synced_entries) + + if not plain and not synced_entries: + continue + + lyrics = { + "plain": plain or None, + "synced": synced or None, + "score": scored["score"], + } + + if best is None or lyrics["score"] > best["score"]: + best = lyrics + + return best + + +def fetch_lyrics( + artist: str, + title: str, + runtime=None, + timeout: float = LYRICS_TIMEOUT, +): + """Look up lyrics on LRCLIB, which returns plain and timed lyrics. + + Missing lyrics are a normal result, not an error. Transport and server + errors raise ProviderError so the caller can report them without failing + the download. + """ + params = { + "artist_name": artist, + "track_name": title, + } + + headers = {"User-Agent": USER_AGENT} + + try: + if runtime is not None: + runtime.limiter.wait("lrclib") + response = runtime.session.get( + LRCLIB_SEARCH_URL, + params=params, + headers=headers, + timeout=timeout, + ) + else: + response = requests.get( + LRCLIB_SEARCH_URL, + params=params, + headers=headers, + timeout=timeout, + ) + + except requests.RequestException as error: + raise ProviderError(f"lyrics request failed: {error}") from error + + status = getattr(response, "status_code", 200) + + if status == 404: + return None + + if status >= 400: + raise ProviderError(f"lyrics source returned HTTP {status}") + + try: + results = response.json() + + except (TypeError, ValueError) as error: + raise ProviderError("lyrics source returned invalid JSON") from error + + if isinstance(results, dict): + results = results.get("data") or [] + + return select_lyrics(results, artist, title) + + +def add_mp3_lyrics(audio, lyrics): + """Add or replace USLT/SYLT frames without touching other ID3 tags.""" + if not lyrics: + # No new lyrics is not a reason to delete lyrics that are already there. + return + + plain = (lyrics.get("plain") or "").strip() + synced_entries = parse_synced_lyrics(lyrics.get("synced") or "") + + if not plain and synced_entries: + plain = "\n".join(line for line, _ in synced_entries) + + if not plain and not synced_entries: + return + + audio.delall("USLT") + audio.delall("SYLT") + + if plain: + audio.add( + USLT( + encoding=3, + lang=LYRICS_LANGUAGE, + desc="", + text=plain, + ) + ) + + if synced_entries: + audio.add( + SYLT( + encoding=3, + lang=LYRICS_LANGUAGE, + format=2, + type=1, + desc="", + text=synced_entries, + ) + ) + + def download_audio( video_url: str, temp_dir: Path, @@ -1918,6 +2135,7 @@ def add_metadata( audio_path: Path, cover_path: Path, metadata: dict, + lyrics=None, ): if audio_path.suffix == ".opus": add_opus_metadata( @@ -1936,6 +2154,7 @@ def add_metadata( audio_path, cover_path, metadata, + lyrics, ) @@ -1943,6 +2162,7 @@ def add_mp3_metadata( mp3_path: Path, cover_path: Path, metadata: dict, + lyrics=None, ): try: audio = ID3(mp3_path) @@ -2021,6 +2241,8 @@ def add_mp3_metadata( ) ) + add_mp3_lyrics(audio, lyrics) + audio.save( mp3_path, v2_version=3, @@ -2309,11 +2531,40 @@ def process_song( if cover_path is None: cover_path = temp_dir / "cover.jpg" + lyrics = None + lyrics_enabled = ( + LYRICS_DEFAULT_ENABLED + if source_config is None + else source_config.lyrics_enabled + ) + + if audio_format == "mp3" and lyrics_enabled: + lyrics_error = False + + try: + lyrics = fetch_lyrics( + metadata["artist"], + metadata["title"], + runtime, + ) + + except Exception as error: + lyrics_error = True + print(f"Lyrics: not found ({error})") + + if lyrics: + kinds = "plain + timed" if lyrics.get("synced") else "plain" + print(f"Lyrics: embedded ({kinds})") + + elif not lyrics_error: + print("Lyrics: not found") + try: add_metadata( audio_path, cover_path, metadata, + lyrics, ) except Exception as error: @@ -2451,6 +2702,9 @@ def coerce_config_value(action, raw): if isinstance(action, argparse._StoreTrueAction): return raw.lower() in ("1", "true", "yes", "on") + if isinstance(action, argparse.BooleanOptionalAction): + return parse_bool(raw, action.dest) + return raw @@ -2751,6 +3005,17 @@ def main(): ), ) + parser.add_argument( + "--lyrics", + action=argparse.BooleanOptionalAction, + default=None, + dest="lyrics_enabled", + help=( + "Embed lyrics from LRCLIB into MP3 tags as USLT and, when " + "timed lyrics are available, SYLT (default: on)" + ), + ) + args = parser.parse_args() try: @@ -2911,6 +3176,10 @@ def main(): "YouTube artwork fallback: " + ("enabled" if source_config.youtube_enabled else "disabled") ) + print( + "Lyrics embedding: " + + ("enabled (MP3 only)" if source_config.lyrics_enabled else "disabled") + ) sys.stdout.flush() @@ -2921,6 +3190,7 @@ def main(): name: source_config.interval(name) for name in METADATA_PROVIDERS } + | {"lrclib": LYRICS_MIN_INTERVAL} ), spotify_args=args, )