pylrclib-cli 0.4.1__py3-none-any.whl

pylrclib/__init__.py

@@ -0,0 +1,4 @@
+"""pylrclib package."""
+
+__all__ = ["__version__"]
+__version__ = "1.2.0"

pylrclib/__main__.py

@@ -0,0 +1,3 @@
+from .cli.main import main
+
+raise SystemExit(main())

pylrclib/api/__init__.py

@@ -0,0 +1,3 @@
+from .client import ApiClient
+
+__all__ = ["ApiClient"]

pylrclib/api/client.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..config import CommonOptions
+from ..models import LookupResult, LyricsRecord, TrackMeta
+from .http import http_request_json
+from .publish import build_publish_payload, publish_with_retry
+
+
+class ApiClient:
+    def __init__(self, options: CommonOptions) -> None:
+        self.options = options
+
+    def _lookup(self, meta: TrackMeta, endpoint: str, source: str) -> LookupResult:
+        data = http_request_json(
+            self.options,
+            method='GET',
+            url=f'{self.options.lrclib_base}/{endpoint}',
+            label=source,
+            params={
+                'track_name': meta.track,
+                'artist_name': meta.artist,
+                'album_name': meta.album,
+                'duration': meta.duration,
+            },
+        )
+        if not data:
+            return LookupResult(record=None, duration_diff=None, duration_ok=False, source=source)
+        record = LyricsRecord.from_api(data)
+        diff = None
+        ok = True
+        if record.duration is not None and meta.duration > 0:
+            diff = abs(record.duration - meta.duration)
+            ok = diff <= 2
+        return LookupResult(record=record, duration_diff=diff, duration_ok=ok, source=source)
+
+    def get_cached(self, meta: TrackMeta) -> LookupResult:
+        return self._lookup(meta, 'get-cached', 'cache')
+
+    def get_external(self, meta: TrackMeta) -> LookupResult:
+        return self._lookup(meta, 'get', 'external')
+
+    def get_by_id(self, lrclib_id: int) -> LyricsRecord | None:
+        data = http_request_json(
+            self.options,
+            method='GET',
+            url=f'{self.options.lrclib_base}/get/{int(lrclib_id)}',
+            label=f'get_by_id:{lrclib_id}',
+            treat_404_as_none=True,
+        )
+        if not isinstance(data, dict):
+            return None
+        return LyricsRecord.from_api(data)
+
+    def search(
+        self,
+        *,
+        query: str | None = None,
+        track_name: str | None = None,
+        artist_name: str | None = None,
+        album_name: str | None = None,
+    ) -> list[LyricsRecord]:
+        if not query and not track_name:
+            raise ValueError('Either query or track_name is required for search')
+        data = http_request_json(
+            self.options,
+            method='GET',
+            url=f'{self.options.lrclib_base}/search',
+            label='search',
+            params={
+                'q': query,
+                'track_name': track_name,
+                'artist_name': artist_name,
+                'album_name': album_name,
+            },
+            treat_404_as_none=True,
+        )
+        if data is None:
+            return []
+        if isinstance(data, list):
+            return [LyricsRecord.from_api(item) for item in data if isinstance(item, dict)]
+        if isinstance(data, dict):
+            return [LyricsRecord.from_api(data)]
+        return []
+
+    def upload_lyrics(self, meta: TrackMeta, plain: str, synced: str) -> bool:
+        payload = build_publish_payload(meta, plain, synced, instrumental=False)
+        return publish_with_retry(self.options, meta, payload, 'upload lyrics')
+
+    def upload_instrumental(self, meta: TrackMeta) -> bool:
+        payload = build_publish_payload(meta, None, None, instrumental=True)
+        return publish_with_retry(self.options, meta, payload, 'upload instrumental')

pylrclib/api/http.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+import requests
+from requests import RequestException
+
+from ..config import CommonOptions
+from ..logging_utils import log_warn
+from .retry import calculate_backoff, is_retryable_status, parse_retry_after
+
+
+def http_request_json(
+    options: CommonOptions,
+    method: str,
+    url: str,
+    label: str,
+    *,
+    params: Optional[dict[str, Any]] = None,
+    json_data: Optional[dict[str, Any]] = None,
+    timeout: int = 20,
+    max_retries: Optional[int] = None,
+    treat_404_as_none: bool = True,
+) -> Any:
+    retries = max_retries if max_retries is not None else options.max_http_retries
+    for attempt in range(1, retries + 1):
+        try:
+            response = requests.request(
+                method=method,
+                url=url,
+                params=params,
+                json=json_data,
+                timeout=timeout,
+                headers={"User-Agent": options.user_agent},
+            )
+        except RequestException as exc:
+            if attempt == retries:
+                log_warn(f"{label} failed after {attempt} attempts: {exc}")
+                return None
+            delay = calculate_backoff(attempt)
+            log_warn(f"{label} request error on attempt {attempt}/{retries}: {exc}; retrying in {delay:.1f}s")
+            time.sleep(delay)
+            continue
+
+        if response.status_code == 404 and treat_404_as_none:
+            return None
+        if 200 <= response.status_code < 300:
+            try:
+                return response.json()
+            except ValueError:
+                log_warn(f"{label} returned invalid JSON: {response.text[:200]}")
+                return None
+        if is_retryable_status(response.status_code):
+            if attempt == retries:
+                log_warn(f"{label} failed after {attempt} attempts: HTTP {response.status_code} {response.text[:200]}")
+                return None
+            delay = parse_retry_after(response.headers.get("Retry-After")) or calculate_backoff(attempt)
+            log_warn(f"{label} failed with HTTP {response.status_code}; retrying in {delay:.1f}s")
+            time.sleep(delay)
+            continue
+        log_warn(f"{label} failed with HTTP {response.status_code}: {response.text[:200]}")
+        return None
+    return None

pylrclib/api/pow.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+import hashlib
+
+from ..exceptions import PoWError
+
+
+def solve_pow(prefix: str, target_hex: str) -> str:
+    if not prefix or not target_hex:
+        raise PoWError(f"invalid PoW params: prefix={prefix!r}, target={target_hex!r}")
+    target = int(target_hex, 16)
+    nonce = 0
+    while True:
+        digest = hashlib.sha256(f"{prefix}{nonce}".encode("utf-8")).hexdigest()
+        if int(digest, 16) <= target:
+            return str(nonce)
+        nonce += 1

pylrclib/api/publish.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import time
+from typing import Any, Optional
+
+import requests
+from requests import RequestException
+
+from ..config import CommonOptions
+from ..logging_utils import log_warn
+from ..models import TrackMeta
+from .http import http_request_json
+from .pow import solve_pow
+from .retry import calculate_backoff, is_retryable_status, parse_retry_after
+
+
+def request_publish_token(options: CommonOptions) -> Optional[str]:
+    data = http_request_json(
+        options,
+        method="POST",
+        url=f"{options.lrclib_base}/request-challenge",
+        label="request publish challenge",
+        treat_404_as_none=False,
+    )
+    if not data:
+        return None
+    prefix = data.get("prefix")
+    target = data.get("target")
+    if not prefix or not target:
+        return None
+    nonce = solve_pow(prefix, target)
+    return f"{prefix}:{nonce}"
+
+
+def build_publish_payload(meta: TrackMeta, plain: Optional[str], synced: Optional[str], *, instrumental: bool = False) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "trackName": meta.track,
+        "artistName": meta.artist,
+        "albumName": meta.album,
+        "duration": meta.duration,
+    }
+    if instrumental:
+        return payload
+    plain_text = (plain or "").strip()
+    synced_text = (synced or "").strip()
+    if plain_text:
+        payload["plainLyrics"] = plain_text
+    if synced_text:
+        payload["syncedLyrics"] = synced_text
+    return payload
+
+
+def publish_with_retry(options: CommonOptions, meta: TrackMeta, payload: dict[str, Any], label: str) -> bool:
+    url = f"{options.lrclib_base}/publish"
+    retries = options.max_http_retries
+    for attempt in range(1, retries + 1):
+        token = request_publish_token(options)
+        if not token:
+            if attempt == retries:
+                return False
+            delay = calculate_backoff(attempt)
+            time.sleep(delay)
+            continue
+        try:
+            response = requests.post(
+                url,
+                json=payload,
+                headers={
+                    "User-Agent": options.user_agent,
+                    "Content-Type": "application/json",
+                    "X-Publish-Token": token,
+                },
+                timeout=30,
+            )
+        except RequestException as exc:
+            if attempt == retries:
+                log_warn(f"{label} failed after {attempt} attempts: {exc}")
+                return False
+            delay = calculate_backoff(attempt)
+            time.sleep(delay)
+            continue
+        if response.status_code == 201:
+            return True
+        if is_retryable_status(response.status_code):
+            if attempt == retries:
+                return False
+            delay = parse_retry_after(response.headers.get("Retry-After")) or calculate_backoff(attempt)
+            time.sleep(delay)
+            continue
+        log_warn(f"{label} failed with HTTP {response.status_code}: {response.text[:200]}")
+        return False
+    return False

pylrclib/api/retry.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import random
+from email.utils import parsedate_to_datetime
+from typing import Optional
+
+RETRYABLE_STATUSES = {408, 425, 429, 500, 502, 503, 504}
+
+
+def calculate_backoff(attempt: int, base: float = 1.0, max_delay: float = 30.0) -> float:
+    return min(base * (2 ** (attempt - 1)) + random.uniform(0, 1), max_delay)
+
+
+def parse_retry_after(value: Optional[str]) -> Optional[float]:
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        try:
+            dt = parsedate_to_datetime(value)
+            return max(0.0, (dt - dt.now(dt.tzinfo)).total_seconds())
+        except Exception:
+            return None
+
+
+def is_retryable_status(status: int) -> bool:
+    return status in RETRYABLE_STATUSES

pylrclib/cli/main.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .. import __version__
+from ..commands import cleanse, doctor, down, inspect, search, up
+from ..exceptions import CLIUsageError
+from ..i18n import setup_i18n
+from ..logging_utils import log_error
+
+
+def _detect_lang(argv: list[str]) -> str:
+    for index, value in enumerate(argv):
+        if value in {"--lang", "--language"} and index + 1 < len(argv):
+            return argv[index + 1]
+        if value.startswith("--lang="):
+            return value.split("=", 1)[1]
+        if value.startswith("--language="):
+            return value.split("=", 1)[1]
+    return "auto"
+
+
+def build_parser(lang: str) -> argparse.ArgumentParser:
+    setup_i18n(lang)
+    parser = argparse.ArgumentParser(prog="pylrclib", description="Upload, download, inspect, and cleanse lyrics around LRCLIB.")
+    parser.add_argument("--lang", "--language", default=lang, choices=["auto", "en_US", "zh_CN"])
+    parser.add_argument("--version", action="version", version=f"pylrclib {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    up.add_parser(subparsers)
+    down.add_parser(subparsers)
+    search.add_parser(subparsers)
+    cleanse.add_parser(subparsers)
+    inspect.add_parser(subparsers)
+    doctor.add_parser(subparsers)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    detected_lang = _detect_lang(argv)
+    parser = build_parser(detected_lang)
+    args = parser.parse_args(argv)
+    lang = setup_i18n(args.lang)
+    try:
+        return int(args.command_handler(args, lang) or 0)
+    except CLIUsageError as exc:
+        log_error(str(exc))
+        return 2
+    except KeyboardInterrupt:
+        log_error("interrupted by user")
+        return 130

pylrclib/commands/cleanse.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace
+from pathlib import Path
+
+from ..config import PREVIEW_LINES_DEFAULT, UNSET, resolve_int
+from ..logging_utils import log_info, log_warn
+from ..lrc import cleanse_lrc_file
+
+
+def add_parser(subparsers) -> ArgumentParser:
+    parser = subparsers.add_parser("cleanse", help="cleanse LRC files without uploading")
+    parser.add_argument("paths", nargs="*", default=[])
+    parser.add_argument("--lrc-dir", default=UNSET)
+    parser.add_argument("--write", action="store_true")
+    parser.add_argument("--preview-lines", default=UNSET)
+    parser.set_defaults(command_handler=run)
+    return parser
+
+
+def _collect_paths(args: Namespace) -> list[Path]:
+    if args.paths:
+        raw_paths = [Path(value).expanduser().resolve() for value in args.paths]
+    elif args.lrc_dir is not UNSET:
+        raw_paths = [Path(str(args.lrc_dir)).expanduser().resolve()]
+    else:
+        raw_paths = [Path.cwd().resolve()]
+    files: list[Path] = []
+    for path in raw_paths:
+        if path.is_file() and path.suffix.lower() == ".lrc":
+            files.append(path)
+        elif path.is_dir():
+            files.extend(sorted(path.rglob("*.lrc")))
+    return files
+
+
+def run(args: Namespace, lang: str) -> int:
+    del lang
+    preview_lines = resolve_int(args.preview_lines, "PYLRCLIB_PREVIEW_LINES", PREVIEW_LINES_DEFAULT)
+    files = _collect_paths(args)
+    if not files:
+        log_warn("no LRC files found")
+        return 0
+    stats = {"updated": 0, "unchanged": 0, "invalid": 0, "failed": 0}
+    for path in files:
+        result = cleanse_lrc_file(path, write=args.write)
+        stats[result.status] = stats.get(result.status, 0) + 1
+        log_info(f"{path}: {result.status}")
+        if result.cleaned_text:
+            lines = result.cleaned_text.splitlines()
+            for line in lines[:preview_lines]:
+                print(line)
+            if len(lines) > preview_lines:
+                print(f"... ({len(lines)} lines total)")
+    log_info("summary: " + ", ".join(f"{key}={value}" for key, value in sorted(stats.items())))
+    return 0

pylrclib/commands/doctor.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace
+
+from ..config import SUPPORTED_AUDIO_EXTENSIONS, SUPPORTED_YAML_EXTENSIONS, SUPPORTED_PLAIN_EXTENSIONS, SUPPORTED_SYNCED_EXTENSIONS, UNSET
+from ..logging_utils import log_info, log_warn
+from ..discovery import discover_inputs
+from .up import _build_config
+
+
+def add_parser(subparsers) -> ArgumentParser:
+    parser = subparsers.add_parser("doctor", help="diagnose the current workspace and resolved configuration")
+    parser.add_argument("--tracks", default=UNSET)
+    parser.add_argument("--lyrics-dir", default=UNSET)
+    parser.add_argument("--plain-dir", default=UNSET)
+    parser.add_argument("--synced-dir", default=UNSET)
+    parser.add_argument("--done-tracks", default=UNSET)
+    parser.add_argument("--done-lrc", default=UNSET)
+    parser.add_argument("-f", "--follow", action="store_true")
+    parser.add_argument("-r", "--rename", action="store_true")
+    parser.add_argument("-c", "--cleanse", action="store_true")
+    parser.add_argument("--lyrics-mode", default="auto", choices=["auto", "plain", "synced", "mixed", "instrumental"])
+    parser.add_argument("-d", "--default", nargs=2, metavar=("TRACKS_DIR", "LYRICS_DIR"))
+    parser.add_argument("-m", "--match", action="store_true")
+    parser.add_argument("--preview-lines", default=UNSET)
+    parser.add_argument("--max-retries", default=UNSET)
+    parser.add_argument("--user-agent", default=UNSET)
+    parser.add_argument("--api-base", default=UNSET)
+    parser.set_defaults(command_handler=run)
+    return parser
+
+
+def run(args: Namespace, lang: str) -> int:
+    args.cleanse_write = False
+    args.allow_non_lrc = False
+    args.ignore_duration_mismatch = False
+    args.yes = False
+    args.non_interactive = True
+    args.allow_derived_plain = True
+    config = _build_config(args, lang)
+    print("Resolved configuration:")
+    print(f"  tracks_dir={config.tracks_dir}")
+    print(f"  lyrics_dir={config.lyrics_dir}")
+    print(f"  plain_dir={config.plain_dir}")
+    print(f"  synced_dir={config.synced_dir}")
+    print(f"  done_tracks_dir={config.done_tracks_dir}")
+    print(f"  done_lrc_dir={config.done_lrc_dir}")
+    print(f"  follow_track={config.follow_track}")
+    print(f"  rename_lrc={config.rename_lrc}")
+    print(f"  cleanse={config.cleanse}")
+    print(f"  lyrics_mode={config.lyrics_mode}")
+    print(f"  mode={config.mode}")
+    print(f"  api_base={config.common.lrclib_base}")
+    print(f"  max_retries={config.common.max_http_retries}")
+
+    errors = 0
+    if not config.tracks_dir.exists():
+        log_warn(f"tracks_dir does not exist: {config.tracks_dir}")
+        errors += 1
+    if config.follow_track and config.done_lrc_dir:
+        log_warn("follow_track and done_lrc_dir should not be combined")
+        errors += 1
+
+    audio_count = 0
+    yaml_count = 0
+    plain_count = 0
+    synced_count = 0
+    if config.tracks_dir.exists():
+        for path in config.tracks_dir.rglob("*"):
+            if path.suffix.lower() in SUPPORTED_AUDIO_EXTENSIONS:
+                audio_count += 1
+            elif path.suffix.lower() in SUPPORTED_YAML_EXTENSIONS:
+                yaml_count += 1
+    for directory, exts, counter_name in [
+        (config.lyrics_dir, SUPPORTED_PLAIN_EXTENSIONS, "plain"),
+        (config.plain_dir, SUPPORTED_PLAIN_EXTENSIONS, "plain"),
+        (config.lyrics_dir, SUPPORTED_SYNCED_EXTENSIONS, "synced"),
+        (config.synced_dir, SUPPORTED_SYNCED_EXTENSIONS, "synced"),
+    ]:
+        if directory and directory.exists():
+            count = sum(1 for path in directory.rglob("*") if path.suffix.lower() in exts)
+            if counter_name == "plain":
+                plain_count += count
+            else:
+                synced_count += count
+    items = discover_inputs(config.tracks_dir)
+    print(f"Found audio={audio_count}, yaml={yaml_count}, plain={plain_count}, synced={synced_count}, valid_inputs={len(items)}")
+    if errors:
+        return 1
+    log_info("doctor finished without fatal issues")
+    return 0

pylrclib/commands/down.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+from argparse import ArgumentParser, Namespace
+from pathlib import Path
+
+from ..config import (
+    DEFAULT_USER_AGENT,
+    LRCLIB_BASE,
+    MAX_HTTP_RETRIES_DEFAULT,
+    PREVIEW_LINES_DEFAULT,
+    UNSET,
+    CommonOptions,
+    DownConfig,
+    resolve_int,
+    resolve_optional_int,
+    resolve_optional_str,
+    resolve_path,
+    resolve_str,
+)
+from ..exceptions import CLIUsageError
+from ..workflows.down import run_down
+
+
+SAVE_MODES = ['auto', 'plain', 'synced', 'both']
+NAMING_MODES = ['auto', 'track-basename', 'artist-title']
+
+
+def add_parser(subparsers) -> ArgumentParser:
+    parser = subparsers.add_parser('down', help='download lyrics from LRCLIB')
+    parser.add_argument('--tracks', default=UNSET, help='audio/YAML directory to query from')
+    parser.add_argument('--artist', default=UNSET)
+    parser.add_argument('--title', default=UNSET)
+    parser.add_argument('--album', default=UNSET)
+    parser.add_argument('--duration', default=UNSET)
+    parser.add_argument('--lrclib-id', default=UNSET)
+    parser.add_argument('--output-dir', default=UNSET)
+    parser.add_argument('--plain-dir', default=UNSET)
+    parser.add_argument('--synced-dir', default=UNSET)
+    parser.add_argument('--save-mode', default='auto', choices=SAVE_MODES)
+    parser.add_argument('--naming', default='auto', choices=NAMING_MODES)
+    parser.add_argument('--skip-existing', action='store_true')
+    parser.add_argument('--overwrite', action='store_true')
+    parser.add_argument('--allow-derived-plain', action='store_true', default=True)
+    parser.add_argument('--no-derived-plain', dest='allow_derived_plain', action='store_false')
+    parser.add_argument('--preview-lines', default=UNSET)
+    parser.add_argument('--max-retries', default=UNSET)
+    parser.add_argument('--user-agent', default=UNSET)
+    parser.add_argument('--api-base', default=UNSET)
+    parser.add_argument('--yes', action='store_true')
+    parser.add_argument('--non-interactive', action='store_true')
+    parser.set_defaults(command_handler=run)
+    return parser
+
+
+def _validate(args: Namespace) -> None:
+    manual = args.artist is not UNSET or args.title is not UNSET
+    by_id = args.lrclib_id is not UNSET
+    if by_id and (manual or args.tracks is not UNSET):
+        raise CLIUsageError('--lrclib-id cannot be combined with --tracks or manual --artist/--title mode')
+    if manual and args.tracks is not UNSET:
+        raise CLIUsageError('--tracks cannot be combined with manual --artist/--title mode')
+    if manual and (args.artist is UNSET or args.title is UNSET):
+        raise CLIUsageError('manual mode requires both --artist and --title')
+    if not by_id and not manual and args.tracks is UNSET:
+        raise CLIUsageError('either --lrclib-id, --tracks, or both --artist/--title are required')
+    if args.skip_existing and args.overwrite:
+        raise CLIUsageError('--skip-existing and --overwrite cannot be used together')
+
+
+def _build_config(args: Namespace, lang: str) -> DownConfig:
+    _validate(args)
+    cwd = Path.cwd().resolve()
+    tracks_dir = resolve_path(args.tracks, 'PYLRCLIB_TRACKS_DIR') if args.tracks is not UNSET else None
+    output_dir = resolve_path(args.output_dir, 'PYLRCLIB_OUTPUT_DIR', cwd) or cwd
+    plain_dir = resolve_path(args.plain_dir, 'PYLRCLIB_PLAIN_DIR')
+    synced_dir = resolve_path(args.synced_dir, 'PYLRCLIB_SYNCED_DIR')
+    common = CommonOptions(
+        lang=lang,
+        preview_lines=resolve_int(args.preview_lines, 'PYLRCLIB_PREVIEW_LINES', PREVIEW_LINES_DEFAULT),
+        max_http_retries=resolve_int(args.max_retries, 'PYLRCLIB_MAX_HTTP_RETRIES', MAX_HTTP_RETRIES_DEFAULT),
+        user_agent=resolve_str(args.user_agent, 'PYLRCLIB_USER_AGENT', DEFAULT_USER_AGENT),
+        lrclib_base=resolve_str(args.api_base, 'PYLRCLIB_API_BASE', LRCLIB_BASE),
+        interactive=not (args.non_interactive or args.yes),
+        assume_yes=args.yes,
+    )
+    return DownConfig(
+        tracks_dir=tracks_dir,
+        output_dir=output_dir,
+        plain_dir=plain_dir,
+        synced_dir=synced_dir,
+        save_mode=args.save_mode,
+        skip_existing=args.skip_existing,
+        overwrite=args.overwrite,
+        naming=args.naming,
+        artist=resolve_optional_str(args.artist, 'PYLRCLIB_ARTIST'),
+        track=resolve_optional_str(args.title, 'PYLRCLIB_TITLE'),
+        album=resolve_optional_str(args.album, 'PYLRCLIB_ALBUM'),
+        duration=resolve_optional_int(args.duration, 'PYLRCLIB_DURATION'),
+        lrclib_id=resolve_optional_int(args.lrclib_id, 'PYLRCLIB_LRCLIB_ID'),
+        allow_derived_plain=args.allow_derived_plain,
+        common=common,
+    )
+
+
+def run(args: Namespace, lang: str) -> int:
+    config = _build_config(args, lang)
+    return run_down(config)