chore: enhance comments

LICENSE

@@ -1,4 +1,4 @@
-Copyright 2026 Uyanide me@uyani.de
+Copyright 2026 Uyanide pywang0608@foxmail.com
 
 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:
 

lrx_cli/__main__.py

@@ -1,4 +1,10 @@
-from lrx_cli.cli import run
+"""
+Author: Uyanide pywang0608@foxmail.com
+Date: 2026-04-06 08:19:54
+Description: The entry point.
+"""
+
+from .cli import run
 
 if __name__ == "__main__":
     run()

lrx_cli/authenticators/__init__.py

@@ -1,5 +1,6 @@
 """
 Author: Uyanide pywang0608@foxmail.com
+Date: 2026-04-06 08:21:01
 Description: Credential authenticators for third-party provider APIs
 """
 

lrx_cli/authenticators/base.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 03:18:14
-Description: Base class for credential authenticators
+Description: Base class for credential authenticators.
 """
 
 from abc import ABC, abstractmethod

lrx_cli/authenticators/dummy.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 03:36:44
-Description:
+Description: A dummy authenticator that does nothing and always reports as configured.
 """
 
 from .base import BaseAuthenticator

lrx_cli/authenticators/musixmatch.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 03:27:56
-Description: Musixmatch authenticator — token management, 401 retry, and cooldown
+Description: Musixmatch authenticator — token management, 401 retry, and cooldown.
 """
 
 import time

lrx_cli/authenticators/qqmusic.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 03:47:30
-Description: QQ Music API authenticator - currently only a proxy
+Description: QQ Music API authenticator - currently only a proxy.
 """
 
 from typing import Optional

lrx_cli/authenticators/spotify.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 03:18:14
-Description: Spotify authenticator — TOTP-based access token via SP_DC cookie
+Description: Spotify authenticator — TOTP-based access token via SP_DC cookie.
 """
 
 import hashlib
@@ -134,9 +134,7 @@ class SpotifyAuthenticator(BaseAuthenticator):
             return db_token
 
         if not credentials.SPOTIFY_SP_DC:
-            logger.error(
+            logger.error("Spotify: SPOTIFY_SP_DC env var not set — cannot authenticate")
-                "Spotify: settings.SPOTIFY_SP_DC env var not set — cannot authenticate"
-            )
             return None
 
         headers = {

lrx_cli/cache.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 10:18:03
-Description: SQLite-based lyric cache with per-source storage and TTL expiration
+Description: SQLite-based lyric cache with per-source storage and TTL expiration.
 """
 
 import json
@@ -79,7 +79,7 @@ class CacheEngine:
         self._init_db()
 
     def _init_db(self) -> None:
-        """Create or migrate the cache table."""
+        """Create or migrate the cache and credentials tables."""
         with sqlite3.connect(self.db_path) as conn:
             conn.execute("""
                 CREATE TABLE IF NOT EXISTS cache (

lrx_cli/cli.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-26 02:04:39
-Description: CLI interface
+Description: CLI interface.
 """
 
 import sys

lrx_cli/config.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 10:17:56
-Description: Global configuration constants and logger setup
+Description: Global configuration constants and logger setup.
 """
 
 import os

lrx_cli/core.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 11:09:53
-Description: Core orchestrator — coordinates fetchers with cache-aware fallback
+Description: Core orchestrator — coordinates fetchers with cache-aware fallback.
 """
 
 import asyncio

lrx_cli/enrichers/audio_tag.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-31 06:11:27
-Description: Enricher that reads metadata from audio file tags (mutagen)
+Description: Enricher that reads metadata from audio file tags.
 """
 
 from typing import Optional

lrx_cli/enrichers/base.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-31 06:08:16
-Description: Base class for metadata enrichers
+Description: Base class for metadata enrichers.
 """
 
 from abc import ABC, abstractmethod

lrx_cli/enrichers/file_name.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-31 06:08:44
-Description: Enricher that parses metadata from the audio file path
+Description: Enricher that parses metadata from the audio file path.
 """
 
 import re

lrx_cli/enrichers/musixmatch.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-05 02:13:49
-Description: Musixmatch metadata enricher (matcher.track.get by Spotify track ID)
+Description: Musixmatch metadata enricher (matcher.track.get by Spotify track ID).
 """
 
 from typing import Optional

lrx_cli/fetchers/__init__.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 02:33:26
-Description: Fetcher pipeline — registry and types
+Description: Fetcher pipeline — registry and types.
 """
 
 from typing import Literal, Optional

lrx_cli/fetchers/base.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 02:33:26
-Description: Base fetcher class and common interfaces
+Description: Base fetcher class and common interfaces.
 """
 
 from abc import ABC, abstractmethod

lrx_cli/fetchers/cache_search.py

@@ -1,13 +1,11 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-28 05:57:46
-Description: Cache-search fetcher — cross-album fuzzy lookup in the local cache
+Description: Cache-search fetcher — cross-album fuzzy lookup in the local cache.
-"""
 
-"""
+             Searches existing cache entries by artist + title with fuzzy normalization,
-Searches existing cache entries by artist + title with fuzzy normalization,
+             ignoring album and source. Useful when the same track appears on different
-ignoring album and source. Useful when the same track appears on different
+             albums or is played from different players.
-albums or is played from different players.
 """
 
 from typing import Optional

lrx_cli/fetchers/local.py

@@ -1,13 +1,10 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-26 02:08:41
-Description: Local fetcher — reads lyrics from .lrc sidecar files or embedded audio metadata
+Description: Local fetcher — reads lyrics from .lrc sidecar files or embedded audio metadata.
-"""
+             Priority:
-
+               1. Same-directory .lrc file (e.g. /path/to/track.lrc)
-"""
+               2. Embedded lyrics in audio metadata (FLAC, MP3 USLT/SYLT tags)
-Priority:
-  1. Same-directory .lrc file (e.g. /path/to/track.lrc)
-  2. Embedded lyrics in audio metadata (FLAC, MP3 USLT/SYLT tags)
 """
 
 from typing import Optional

lrx_cli/fetchers/lrclib.py

@@ -1,11 +1,8 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 05:23:38
-Description: LRCLIB fetcher — queries lrclib.net for synced/plain lyrics
+Description: LRCLIB fetcher — queries lrclib.net for synced/plain lyrics.
-"""
+             Requires complete track metadata (artist, title, album, duration).
-
-"""
-Requires complete track metadata (artist, title, album, duration).
 """
 
 from typing import Optional

lrx_cli/fetchers/lrclib_search.py

@@ -1,12 +1,8 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 05:30:50
-Description: LRCLIB search fetcher — fuzzy search via lrclib.net /api/search
+Description: LRCLIB search fetcher — fuzzy search via lrclib.net /api/search.
-"""
+             Used when metadata is incomplete (no album or duration) but title is available.
-
-"""
-Used when metadata is incomplete (no album or duration) but title is available.
-Selects the best match by duration when track length is known.
 """
 
 import asyncio

lrx_cli/fetchers/musixmatch.py

@@ -1,16 +1,14 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-04-04 15:28:34
-Description: Musixmatch fetchers (desktop API, usertoken auth)
+Description: Musixmatch fetchers (desktop API, anonymous or usertoken auth).
-"""
 
-"""
+             Uses the Musixmatch desktop API (apic-desktop.musixmatch.com).
-Uses the Musixmatch desktop API (apic-desktop.musixmatch.com).
+             Token and all HTTP calls are managed by MusixmatchAuthenticator.
-Token and all HTTP calls are managed by MusixmatchAuthenticator.
 
-Two fetchers:
+             Two fetchers:
-  musixmatch-spotify  — direct lookup by Spotify track ID (exact, no search)
+             musixmatch-spotify  — direct lookup by Spotify track ID (exact, no search)
-  musixmatch          — metadata search + best-candidate fallback
+             musixmatch          — metadata search + best-candidate fallback
 """
 
 import json
@@ -24,9 +22,7 @@ from ..lrc import LRCData
 from ..models import CacheStatus, LyricResult, TrackMeta
 from ..config import TTL_NETWORK_ERROR, TTL_NOT_FOUND
 
-_MUSIXMATCH_MACRO_URL = (
+_MUSIXMATCH_MACRO_URL = "https://apic-desktop.musixmatch.com/ws/1.1/macro.subtitles.get"
-    "https://apic-desktop.musixmatch.com/ws/1.1/macro.subtitles.get"
-)
 _MUSIXMATCH_SEARCH_URL = "https://apic-desktop.musixmatch.com/ws/1.1/track.search"
 
 # Macro-specific params (format/app_id injected by authenticator)

lrx_cli/fetchers/netease.py

@@ -1,15 +1,10 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 11:04:51
-Description: Netease Cloud Music fetcher
+Description: Netease Cloud Music fetcher.
-"""
 
-"""
+             Uses the public cloudsearch API for searching and the song/lyric API for
-Uses the public cloudsearch API for searching and the song/lyric API for
+             retrieving lyrics. No authentication required.
-retrieving lyrics. No authentication required.
-
-Search results are filtered by duration when the track has a known length
-to avoid returning lyrics for the wrong version of a song.
 """
 
 import asyncio

lrx_cli/fetchers/qqmusic.py

@@ -1,14 +1,12 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-31 01:54:02
-Description: QQ Music fetcher via self-hosted API proxy
+Description: QQ Music fetcher via self-hosted API proxy.
-"""
 
-"""
+             Requires a running qq-music-api instance.
-Requires a running qq-music-api instance.
+             The base URL is read from the QQ_MUSIC_API_URL environment variable.
-The base URL is read from the QQ_MUSIC_API_URL environment variable.
 
-Search → pick best match by duration → fetch LRC lyrics.
+             Search → pick best match → fetch LRC lyrics.
 """
 
 import asyncio

lrx_cli/fetchers/selection.py

@@ -1,9 +1,11 @@
 """
-Shared candidate-selection logic for search-based fetchers.
+Author: Uyanide pywang0608@foxmail.com
+Date: 2026-04-04 11:32:23
+Description: Shared candidate-selection logic for search-based fetchers.
 
-Each fetcher maps its API-specific results to SearchCandidate, then calls
+             Each fetcher maps its API-specific results to SearchCandidate, then calls
-select_best() which scores candidates by metadata similarity, duration
+             select_best() which scores candidates by metadata similarity, duration
-proximity, and sync status.
+             proximity, and sync status.
 """
 
 from dataclasses import dataclass

lrx_cli/lrc.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 21:54:01
-Description: Shared LRC time-tag utilities (definitely overengineered)
+Description: Shared LRC time-tag utilities (definitely overengineered).
 """
 
 import re

lrx_cli/models.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 04:09:36
-Description: Data models
+Description: Data models.
 """
 
 from __future__ import annotations

lrx_cli/mpris.py

@@ -1,7 +1,7 @@
 """
 Author: Uyanide pywang0608@foxmail.com
 Date: 2026-03-25 04:44:15
-Description: MPRIS integration for fetching track metadata
+Description: MPRIS integration for fetching track metadata.
 """
 
 import asyncio

lrx_cli/normalize.py

@@ -1,7 +1,8 @@
 """
-Shared text normalization utilities for fuzzy matching.
+Author: Uyanide pywang0608@foxmail.com
-
+Date: 2026-04-02 05:24:27
-Used by cache key generation, cache search, and candidate selection scoring.
+Description: Shared text normalization utilities for fuzzy matching.
+             Used by cache key generation, cache search, and candidate selection scoring.
 """
 
 import re