lrclib-synced 0.3.0__py3-none-any.whl

lrclib_synced-0.3.0.dist-info/METADATA

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: lrclib-synced
+Version: 0.3.0
+Summary: Time-synced song lyrics from LRCLIB with a Yandex Music fallback, checked against track length
+Author: nowplaylab
+License: MIT
+Project-URL: Homepage, https://github.com/nowplaylab/synced-lyrics
+Project-URL: Issues, https://github.com/nowplaylab/synced-lyrics/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Framework :: AsyncIO
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.8
+Dynamic: license-file
+
+# synced-lyrics
+
+**English** | [Русский](https://github.com/nowplaylab/synced-lyrics/blob/main/README.ru.md)
+
+Song lyrics with a time for every line, for karaoke-style display. Looks on [LRCLIB](https://lrclib.net) first; if nothing is there, takes plain lyrics from Yandex Music (no account needed).
+
+Timed lyrics are only accepted when the track length matches (within 4 s, or 2 s when the artist is unknown). Otherwise a remix or live version would show lines at the wrong moments; you get plain lyrics instead.
+
+Made by [nowplaylab](https://github.com/nowplaylab) for [NowPlaying](https://github.com/nowplaylab/nowplaying-display).
+
+## Install
+
+```
+pip install git+https://github.com/nowplaylab/synced-lyrics@v0.2.0
+```
+
+Python 3.9+, depends only on aiohttp.
+
+## Use
+
+```python
+import aiohttp, synced_lyrics
+
+async def main():
+    async with aiohttp.ClientSession(headers={'User-Agent': 'my-app/1.0'}) as http:
+        lyrics = await synced_lyrics.fetch(http, 'Blinding Lights', 'The Weeknd', duration_ms=200040)
+        for line in lyrics.synced:          # [{'t': milliseconds, 'text': line}], empty if no timing
+            print(line['t'], line['text'])
+        print(lyrics.plain)                 # plain text, may exist without timing
+        print(lyrics.source)                # 'lrclib', 'yandex' or ''
+```
+
+- `fetch()` never raises on network errors. Busy or failing services are retried a few times; if one still does not answer, you get `lyrics.complete == False`. Empty with `complete=True` means there really are no lyrics; empty with `complete=False` means "could not check, ask again later", so do not cache it for long.
+- Titles with extras like `(feat. …)`, `(Prod. by …)` or ` - Remastered 2011` are searched again without them (`synced_lyrics.simplify_title()`).
+- `use_yandex=False` turns the fallback off.
+- `local_dirs=['~/Music/Lyrics']` checks your own files first, with no network: `Artist - Title.lrc`, `Title - Artist.lrc` or `Title.lrc` (a `.txt` works too, as plain lyrics). A `.lrc` with any name is found by its `[ti:]` and `[ar:]` tags. If the file has `[length:3:34]`, it is used only when the track length matches (within 4 s). `lyrics.source` is then `'file'`. Use `synced_lyrics.local.find()` and `read()` on their own if you like.
+- `parse_lrc()` understands `[offset:±ms]` and drops per-word times (`<00:10.80>`), keeping the line.
+- `synced_lyrics.parse_lrc(text)` parses any LRC text on its own.
+- `synced_lyrics.yandex` has the search helpers: `find_tracks()`, `same_track()`, `plain_lyrics()`.
+- LRCLIB asks clients to send their own User-Agent.
+
+## Licence
+
+MIT. Not affiliated with LRCLIB or Yandex.

lrclib_synced-0.3.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+lrclib_synced-0.3.0.dist-info/licenses/LICENSE,sha256=YEAebu59O4eQUftdMcKSnu2g4u1K4X2V-Usk2vETUzs,1090
+synced_lyrics/__init__.py,sha256=fI_WtUm6VQi9CshPToQ3zTWk-f9_nCTvcKjA4KQFEAs,7805
+synced_lyrics/local.py,sha256=fdwtp2NnD3lAQOSHF_-1dCtU3Oaj0xttpApVK79XFnc,4613
+synced_lyrics/yandex.py,sha256=Z5NZCsTCEGDkkfFH1fSmOctt3nyYAeas2u8BAerWHfw,3786
+lrclib_synced-0.3.0.dist-info/METADATA,sha256=YmTROWFqM1fphwbtqLPJHL7j13MQDtfgYthobtPcK8o,3261
+lrclib_synced-0.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+lrclib_synced-0.3.0.dist-info/top_level.txt,sha256=N8GVwrdJJ0R8TAFUagTv5mP_9LnnUITuQO5WuMPIo6o,14
+lrclib_synced-0.3.0.dist-info/RECORD,,

lrclib_synced-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

lrclib_synced-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nowplaylab (tryshyzov and Claude)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lrclib_synced-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+synced_lyrics

synced_lyrics/__init__.py

@@ -0,0 +1,161 @@
+"""Тексты песен со временем строк: LRCLIB (синхронный и обычный текст) и запасной — Яндекс Музыка.
+
+    lyrics = await synced_lyrics.fetch(http, 'Blinding Lights', 'The Weeknd', duration_ms=200040)
+    for line in lyrics.synced:      # [{'t': мс, 'text': строка}] — пусто, если таймингов нет
+        ...
+    lyrics.plain                    # обычный текст (может быть и без синхронного)
+    lyrics.source                   # 'file', 'lrclib', 'yandex' или ''
+    lyrics.complete                 # False — какой-то источник не ответил, стоит спросить позже
+
+Свои файлы: fetch(..., local_dirs=['~/Music/Lyrics']) сначала ищет «Исполнитель - Название.lrc»
+(или .txt) в этих папках, см. synced_lyrics.local.
+
+Синхронный текст берётся, только если длительность совпала (±4 с; без исполнителя — ±2 с),
+иначе строки разъедутся с песней (ремикс, live, другая версия).
+
+Пустой результат с complete=True значит «текста правда нет»; с complete=False — «не смогли
+проверить» (сеть, сервис перегружен). Такой результат не стоит запоминать надолго.
+"""
+import asyncio
+import logging
+import re
+from dataclasses import dataclass, field
+
+import aiohttp
+
+from . import yandex
+
+__version__ = '0.3.0'
+__all__ = ['Lyrics', 'fetch', 'parse_lrc', 'simplify_title', 'local', 'LRCLIB']
+
+log = logging.getLogger('synced_lyrics')
+LRCLIB = 'https://lrclib.net/api'
+NET_ERRORS = (aiohttp.ClientError, asyncio.TimeoutError, ValueError, OSError)
+
+
+@dataclass
+class Lyrics:
+    synced: list = field(default_factory=list)   # [{'t': мс, 'text': строка}]
+    plain: str = ''
+    source: str = ''
+    complete: bool = True                        # все источники ответили
+
+    def __bool__(self):
+        return bool(self.synced or self.plain)
+
+
+def parse_lrc(text):
+    """LRC → [{'t': мс, 'text': строка}] по времени. Строка с несколькими метками повторяется.
+    Метка [offset:±мс] сдвигает все строки (плюс — раньше, как в стандарте LRC).
+    Время отдельных слов <мм:сс.xx> внутри строки отбрасывается — остаётся текст строки."""
+    m = re.search(r'^\s*\[offset:\s*([+-]?\d+)\s*\]', text or '', re.M | re.I)
+    offset = int(m.group(1)) if m else 0
+    lines = []
+    for raw in (text or '').splitlines():
+        stamps = re.findall(r'\[(\d+):(\d+(?:\.\d+)?)\]', raw)
+        words = re.sub(r'<\d+:\d+(?:\.\d+)?>', '', re.sub(r'\[[^\]]*\]', '', raw))
+        words = re.sub(r'\s+', ' ', words).strip()
+        for mm, s in stamps:
+            lines.append({'t': max(0, int((int(mm) * 60 + float(s)) * 1000) - offset), 'text': words})
+    return sorted(lines, key=lambda l: l['t'])
+
+
+def simplify_title(title):
+    """Название без приписок: (feat. …), (Prod. by …), [Explicit], « - Remastered 2011» и т. п."""
+    t = re.sub(r'\s*[\(\[][^\)\]]*[\)\]]', '', title or '')
+    t = re.sub(r'\s+[-–—]\s+[^-–—]*\b(remaster\w*|live|version|edit|mix|mono|stereo)\b.*$', '', t, flags=re.I)
+    return t.strip() or (title or '').strip()
+
+
+async def _get_json(http, url, params, tries=3):
+    """(ok, данные). 200 — данные; 400/404 — (True, None): ответили, что нет; прочее — повтор."""
+    for i in range(tries):
+        try:
+            async with http.get(url, params=params) as r:
+                if r.status == 200:
+                    return True, await r.json(content_type=None)
+                if r.status in (400, 404):
+                    return True, None
+                log.info('%s -> %s', url, r.status)
+        except NET_ERRORS as e:
+            log.info('%s: %s', url, e)
+        if i < tries - 1:
+            await asyncio.sleep(0.6 * (i + 1) ** 2)
+    return False, None
+
+
+def _pick(cands, artist, duration_ms):
+    def diff(c):
+        return abs((c.get('duration') or 0) * 1000 - duration_ms) if duration_ms and c.get('duration') else None
+
+    limit = 4000 if artist else 2000    # без исполнителя — строже
+    synced = [c for c in cands if c.get('syncedLyrics') and
+              (diff(c) is None and duration_ms == 0 and artist or diff(c) is not None and diff(c) <= limit)]
+    synced.sort(key=lambda c: diff(c) or 0)
+    plain = [c for c in cands if c.get('plainLyrics') and (artist or (diff(c) is not None and diff(c) <= 5000))]
+    plain.sort(key=lambda c: diff(c) if diff(c) is not None else 10 ** 9)
+    if synced:
+        return Lyrics(parse_lrc(synced[0]['syncedLyrics']), synced[0].get('plainLyrics') or '', 'lrclib')
+    if plain:
+        return Lyrics([], plain[0]['plainLyrics'], 'lrclib')
+    return Lyrics()
+
+
+async def from_lrclib(http, title, artist='', album='', duration_ms=0, base=LRCLIB):
+    """Lyrics из LRCLIB; complete=False, если LRCLIB не ответил."""
+    complete = True
+    short = simplify_title(title)
+    best = Lyrics()
+    for t in [title] + ([short] if short != title else []):
+        q = {'track_name': t, 'artist_name': artist}
+        cands = []
+        if artist and duration_ms:   # /get без длительности LRCLIB не принимает
+            ok, d = await _get_json(http, f'{base}/get', dict(q, album_name=album, duration=round(duration_ms / 1000)))
+            complete &= ok
+            if isinstance(d, dict):
+                cands.append(d)
+        ok, d = await _get_json(http, f'{base}/search', q if artist else {'q': t})
+        complete &= ok
+        if isinstance(d, list):
+            cands += d
+        got = _pick(cands, artist, duration_ms)
+        if got.synced:
+            return got
+        if got and not best:
+            best = got
+    best.complete = complete
+    return best
+
+
+async def fetch(http, title, artist='', album='', duration_ms=0, use_yandex=True, lrclib=LRCLIB, local_dirs=None):
+    """Найти текст. http — aiohttp.ClientSession (лучше со своим User-Agent). Ошибки сети не бросает:
+    если источник не ответил даже после повторов, у результата complete=False.
+    local_dirs — папки со своими .lrc/.txt: проверяются первыми, без сети (source='file')."""
+    if local_dirs:
+        try:
+            path = await asyncio.get_running_loop().run_in_executor(
+                None, local.find, local_dirs, title, artist, duration_ms)
+            if path:
+                got = local.read(path)
+                if got:
+                    return got
+        except OSError as e:
+            log.warning('local lyrics: %s', e)
+    try:
+        result = await from_lrclib(http, title, artist, album, duration_ms, lrclib)
+    except NET_ERRORS as e:
+        log.warning('lrclib: %s', e)
+        result = Lyrics(complete=False)
+    if not result and use_yandex:
+        try:
+            text, ok = await yandex.plain_lyrics_checked(http, title, artist, duration_ms)
+        except NET_ERRORS as e:
+            log.warning('yandex lyrics: %s', e)
+            text, ok = '', False
+        if text:
+            return Lyrics([], text, 'yandex')
+        result.complete = result.complete and ok
+    return result
+
+
+from . import local  # noqa: E402  (local использует Lyrics и parse_lrc отсюда)

synced_lyrics/local.py

@@ -0,0 +1,113 @@
+"""Свои тексты из файлов: .lrc (со временем строк) или .txt (просто текст) в папках на компьютере.
+
+    path = synced_lyrics.local.find(['~/Music/Lyrics'], 'Ночной маршрут', 'Кассета', duration_ms=214000)
+    lyrics = synced_lyrics.local.read(path)
+
+Как файл находится (без учёта регистра, лишних пробелов и знаков):
+  * по имени: «Исполнитель - Название.lrc», «Название - Исполнитель.lrc» или «Название.lrc»;
+  * по меткам внутри LRC: [ti:Название] и [ar:Исполнитель].
+Если в LRC есть [length:3:34] и длина трека известна, файл берётся, только когда они сходятся (±4 с).
+Папки просматриваются с подпапками (до двух уровней), .lrc важнее .txt.
+"""
+import os
+import re
+
+from . import Lyrics, parse_lrc, simplify_title
+
+EXTS = ('.lrc', '.txt')
+MAX_FILES = 5000          # не читать бесконечно огромную папку
+LENGTH_LIMIT = 4000
+
+
+def _norm(text):
+    text = (text or '').lower().replace('ё', 'е')
+    return re.sub(r'[\W_]+', ' ', text).strip()
+
+
+def _read_text(path):
+    with open(path, 'rb') as f:
+        raw = f.read(2_000_000)
+    for enc in ('utf-8-sig', 'cp1251'):
+        try:
+            text = raw.decode(enc)
+            break
+        except UnicodeDecodeError:
+            continue
+    else:
+        text = raw.decode('utf-8', 'replace')
+    return text.replace('\r\n', '\n').replace('\r', '\n')   # файлы из Windows и старых Mac
+
+
+def _tags(text):
+    """Метки LRC из шапки: {'ti': ..., 'ar': ..., 'length': ...}."""
+    return {k.lower(): v.strip() for k, v in re.findall(r'^\s*\[([a-zA-Z]+):([^\]]*)\]\s*$', text, re.M)}
+
+
+def _length_ms(value):
+    m = re.fullmatch(r'\s*(\d+):(\d+(?:\.\d+)?)\s*', value or '')
+    return int((int(m.group(1)) * 60 + float(m.group(2))) * 1000) if m else 0
+
+
+def _files(dirs):
+    n = 0
+    for d in dirs or ():
+        root = os.path.expanduser(str(d))
+        if not os.path.isdir(root):
+            continue
+        base_depth = root.rstrip(os.sep).count(os.sep)
+        for cur, subdirs, files in os.walk(root):
+            if cur.count(os.sep) - base_depth >= 2:
+                subdirs[:] = []
+            for name in files:
+                if name.lower().endswith(EXTS):
+                    yield os.path.join(cur, name)
+                    n += 1
+                    if n >= MAX_FILES:
+                        return
+
+
+def find(dirs, title, artist='', duration_ms=0):
+    """Путь к подходящему файлу или None."""
+    titles = {_norm(title), _norm(simplify_title(title))} - {''}
+    if not titles:
+        return None
+    art = _norm(artist)
+    names = set()
+    for t in titles:
+        names.add(t)
+        if art:
+            names.update({f'{art} {t}', f'{t} {art}'})
+    best = None   # (приоритет, путь): меньше — лучше
+    for path in _files(dirs):
+        stem, ext = os.path.splitext(os.path.basename(path))
+        rank = 0 if ext.lower() == '.lrc' else 1
+        hit = _norm(stem) in names
+        if not hit and ext.lower() == '.lrc':
+            try:
+                tags = _tags(_read_text(path))
+            except OSError:
+                continue
+            hit = _norm(tags.get('ti')) in titles and (not art or not tags.get('ar') or _norm(tags.get('ar')) == art)
+            rank += 2                     # совпадение по меткам — после совпадения по имени
+        if not hit:
+            continue
+        if ext.lower() == '.lrc' and duration_ms:
+            try:
+                length = _length_ms(_tags(_read_text(path)).get('length'))
+            except OSError:
+                continue
+            if length and abs(length - duration_ms) > LENGTH_LIMIT:
+                continue
+        if best is None or rank < best[0]:
+            best = (rank, path)
+    return best[1] if best else None
+
+
+def read(path):
+    """Lyrics из файла: .lrc — со временем строк, .txt — обычный текст. source='file'."""
+    text = _read_text(path)
+    if path.lower().endswith('.lrc'):
+        synced = parse_lrc(text)
+        plain = '\n'.join(l['text'] for l in synced) if synced else re.sub(r'\[[^\]]*\]', '', text).strip()
+        return Lyrics(synced, plain, 'file')
+    return Lyrics([], text.strip(), 'file')

synced_lyrics/yandex.py

@@ -0,0 +1,83 @@
+"""Открытый API Яндекс Музыки (без входа в аккаунт): поиск трека и обычный текст песни."""
+import asyncio
+import re
+
+import aiohttp
+
+YM_API = 'https://api.music.yandex.net'
+
+
+def norm(s):
+    s = (s or '').lower().replace('ё', 'е')
+    s = re.sub(r'\s*[\(\[][^\)\]]*[\)\]]', '', s)   # (feat. …), [Explicit] и т. п.
+    return re.sub(r'[^\w]+', ' ', s).strip()
+
+
+def artist_set(artist):
+    return {norm(a) for a in re.split(r',|&| feat\.? | ft\.? | x ', artist or '', flags=re.I) if a.strip()}
+
+
+def same_track(title, artist, dur_ms, cand_title, cand_artists, cand_dur_ms, tolerance_ms=6000):
+    """Тот же ли трек: название совпало, хотя бы один исполнитель общий, длительность рядом."""
+    if norm(cand_title) != norm(title):
+        return False
+    want = artist_set(artist)
+    have = set().union(*(artist_set(a) for a in cand_artists)) if cand_artists else set()
+    if want and not (have & want):   # у разных сервисов дуэт бывает и одной строкой, и списком
+        return False
+    return not (dur_ms and cand_dur_ms and abs(cand_dur_ms - dur_ms) > tolerance_ms)
+
+
+async def call(http, path, params=None, tries=3):
+    """(ok, result). ok=False — Яндекс так и не ответил (сеть, перегрузка); ok=True и None — ответил, что нет."""
+    for i in range(tries):  # Яндекс иногда отвечает пустотой на первый запрос
+        try:
+            async with http.get(f'{YM_API}/{path}', params=params) as r:
+                if r.status == 404:
+                    return True, None
+                if r.status == 200:
+                    try:
+                        return True, ((await r.json(content_type=None)) or {}).get('result')
+                    except ValueError:
+                        pass
+        except (aiohttp.ClientError, asyncio.TimeoutError, OSError):
+            pass
+        if i < tries - 1:
+            await asyncio.sleep(1)
+    return False, None
+
+
+async def api(http, path, params=None):
+    """result из ответа или None."""
+    return (await call(http, path, params))[1]
+
+
+def _matching(res, title, artist, dur_ms):
+    tracks = ((res or {}).get('tracks') or {}).get('results') or []
+    return [t for t in tracks if same_track(title, artist, dur_ms, t.get('title'),
+                                            [a.get('name') for a in t.get('artists') or []], t.get('durationMs'))]
+
+
+async def find_tracks(http, title, artist, dur_ms):
+    """Треки из поиска Яндекс Музыки, которые совпали с играющим."""
+    res = await api(http, 'search', {'text': f'{artist} {title}'.strip(), 'type': 'track', 'page': '0'})
+    return _matching(res, title, artist, dur_ms)
+
+
+async def plain_lyrics_checked(http, title, artist, dur_ms):
+    """(текст или '', ok). ok=False — Яндекс не ответил, «текста нет» утверждать нельзя."""
+    ok, res = await call(http, 'search', {'text': f'{artist} {title}'.strip(), 'type': 'track', 'page': '0'})
+    if not ok:
+        return '', False
+    for t in _matching(res, title, artist, dur_ms)[:2]:
+        ok2, sup = await call(http, f'tracks/{t["id"]}/supplement')
+        ok = ok and ok2
+        text = ((sup or {}).get('lyrics') or {}).get('fullLyrics') or ''
+        if text.strip():
+            return text, True
+    return '', ok
+
+
+async def plain_lyrics(http, title, artist, dur_ms):
+    """Обычный текст песни (без таймингов) или ''."""
+    return (await plain_lyrics_checked(http, title, artist, dur_ms))[0]