mpup 0.1.0__py3-none-any.whl

mpup/cover.py

@@ -0,0 +1,244 @@
+"""Extract and normalize cover artwork for deterministic browser rendering."""
+
+from __future__ import annotations
+
+import io
+import os
+import subprocess
+import tempfile
+import unicodedata
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal
+from urllib.request import Request, urlopen
+
+from PIL import Image, UnidentifiedImageError
+
+from mpup.itunes import DEFAULT_USER_AGENT, ItunesTrack, search_track
+from mpup.metadata import AudioMetadata
+
+
+MAX_IMAGE_BYTES = 10 * 1024 * 1024
+Runner = Callable[..., subprocess.CompletedProcess[str]]
+CoverSource = Literal["embedded", "itunes", "default"]
+SearchFn = Callable[[str, str], ItunesTrack | None]
+Downloader = Callable[[str], bytes]
+Extractor = Callable[..., tuple[int, int]]
+
+
+@dataclass(frozen=True)
+class CoverResolution:
+    cover_path: Path | None
+    source: CoverSource
+    warnings: tuple[str, ...] = ()
+
+
+def normalize_image_bytes(
+    payload: bytes,
+    destination: Path,
+    *,
+    max_bytes: int = MAX_IMAGE_BYTES,
+) -> tuple[int, int]:
+    """Fully decode an image and atomically publish a browser-safe PNG."""
+    if not payload or len(payload) > max_bytes:
+        raise RuntimeError(f"封面图片大小必须在 1 字节到 {max_bytes} 字节之间")
+
+    try:
+        with Image.open(io.BytesIO(payload)) as source:
+            source.load()
+            dimensions = source.size
+            mode = "RGBA" if "A" in source.getbands() else "RGB"
+            normalized = source.convert(mode)
+    except (OSError, ValueError, UnidentifiedImageError) as error:
+        raise RuntimeError("封面不是可完整解码的图片") from error
+
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temp_path: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            dir=destination.parent,
+            prefix=f".{destination.name}.",
+            suffix=".png",
+            delete=False,
+        ) as temporary:
+            temp_path = Path(temporary.name)
+        normalized.save(temp_path, format="PNG")
+        os.replace(temp_path, destination)
+        temp_path = None
+    finally:
+        if temp_path is not None:
+            temp_path.unlink(missing_ok=True)
+        normalized.close()
+    return dimensions
+
+
+def extract_embedded_cover(
+    audio_path: Path,
+    stream_index: int,
+    destination: Path,
+    *,
+    ffmpeg: str = "ffmpeg",
+    runner: Runner = subprocess.run,
+    temp_root: Path | None = None,
+) -> tuple[int, int]:
+    """Extract one FFmpeg attached-picture stream and normalize it to PNG."""
+    if stream_index < 0:
+        raise ValueError("封面流索引不能小于 0")
+
+    with tempfile.TemporaryDirectory(dir=temp_root) as directory:
+        extracted = Path(directory) / "cover.img"
+        command = [
+            ffmpeg,
+            "-v",
+            "error",
+            "-i",
+            str(audio_path),
+            "-map",
+            f"0:{stream_index}",
+            "-frames:v",
+            "1",
+            "-c:v",
+            "copy",
+            "-f",
+            "image2",
+            str(extracted),
+        ]
+        result = runner(command, capture_output=True, text=True, check=False)
+        if result.returncode != 0:
+            detail = result.stderr.strip() or "未知错误"
+            raise RuntimeError(f"FFmpeg 提取内嵌封面失败：{detail[-2000:]}")
+        if not extracted.is_file():
+            raise RuntimeError("FFmpeg 未生成内嵌封面")
+        if extracted.stat().st_size > MAX_IMAGE_BYTES:
+            raise RuntimeError("内嵌封面超过 10 MiB 限制")
+        return normalize_image_bytes(extracted.read_bytes(), destination)
+
+
+def download_artwork(
+    url: str,
+    *,
+    opener: Callable[..., Any] = urlopen,
+    max_bytes: int = MAX_IMAGE_BYTES,
+) -> bytes:
+    """Download at most ``max_bytes`` of artwork with a bounded request."""
+    request = Request(url, headers={"User-Agent": DEFAULT_USER_AGENT, "Accept": "image/*"})
+    with opener(request, timeout=10) as response:
+        payload = response.read(max_bytes + 1)
+    if not payload or len(payload) > max_bytes:
+        raise RuntimeError("远程封面为空或超过 10 MiB 限制")
+    return payload
+
+
+def _warning(prefix: str, error: Exception) -> str:
+    detail = str(error).strip() or error.__class__.__name__
+    return f"{prefix}：{detail[-1000:]}"
+
+
+def resolve_cover(
+    audio_path: Path,
+    metadata: AudioMetadata,
+    destination: Path,
+    *,
+    ffmpeg: str = "ffmpeg",
+    search: SearchFn = search_track,
+    downloader: Downloader = download_artwork,
+    extractor: Extractor = extract_embedded_cover,
+) -> CoverResolution:
+    """Resolve embedded artwork, then iTunes artwork, with a safe default fallback."""
+    warnings: list[str] = []
+    if metadata.cover_stream_index is not None:
+        try:
+            extractor(
+                audio_path,
+                metadata.cover_stream_index,
+                destination,
+                ffmpeg=ffmpeg,
+            )
+            return CoverResolution(destination, "embedded")
+        except Exception as error:
+            destination.unlink(missing_ok=True)
+            warnings.append(_warning("内嵌封面不可用", error))
+
+    if not metadata.title or not metadata.artist:
+        return CoverResolution(None, "default", tuple(warnings))
+
+    try:
+        track = search(metadata.title, metadata.artist)
+    except Exception as error:
+        warnings.append(_warning("iTunes 封面查询失败", error))
+        return CoverResolution(None, "default", tuple(warnings))
+
+    if track is None or track.artwork_url is None:
+        return CoverResolution(None, "default", tuple(warnings))
+
+    try:
+        normalize_image_bytes(downloader(track.artwork_url), destination)
+        return CoverResolution(destination, "itunes", tuple(warnings))
+    except Exception as error:
+        destination.unlink(missing_ok=True)
+        warnings.append(_warning("iTunes 封面下载或解码失败", error))
+        return CoverResolution(None, "default", tuple(warnings))
+
+
+def _cache_text(value: str) -> str:
+    normalized = unicodedata.normalize("NFKC", value)
+    return " ".join(normalized.split()).casefold()
+
+
+class BatchCoverResolver:
+    """Resolve covers while caching iTunes searches and artwork bytes per batch."""
+
+    def __init__(
+        self,
+        *,
+        search: SearchFn = search_track,
+        downloader: Downloader = download_artwork,
+        extractor: Extractor = extract_embedded_cover,
+    ) -> None:
+        self._search = search
+        self._downloader = downloader
+        self._extractor = extractor
+        self._search_cache: dict[tuple[str, str], ItunesTrack | None | Exception] = {}
+        self._download_cache: dict[str, bytes | Exception] = {}
+
+    def _cached_search(self, title: str, artist: str) -> ItunesTrack | None:
+        key = (_cache_text(title), _cache_text(artist))
+        if key not in self._search_cache:
+            try:
+                self._search_cache[key] = self._search(title, artist)
+            except Exception as error:
+                self._search_cache[key] = error
+        result = self._search_cache[key]
+        if isinstance(result, Exception):
+            raise result
+        return result
+
+    def _cached_download(self, url: str) -> bytes:
+        if url not in self._download_cache:
+            try:
+                self._download_cache[url] = self._downloader(url)
+            except Exception as error:
+                self._download_cache[url] = error
+        result = self._download_cache[url]
+        if isinstance(result, Exception):
+            raise result
+        return result
+
+    def resolve(
+        self,
+        audio_path: Path,
+        metadata: AudioMetadata,
+        destination: Path,
+        *,
+        ffmpeg: str = "ffmpeg",
+    ) -> CoverResolution:
+        return resolve_cover(
+            audio_path,
+            metadata,
+            destination,
+            ffmpeg=ffmpeg,
+            search=self._cached_search,
+            downloader=self._cached_download,
+            extractor=self._extractor,
+        )

mpup/discovery.py

@@ -0,0 +1,33 @@
+"""Discover supported audio inputs."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+
+SUPPORTED_SUFFIXES = frozenset({".mp3", ".m4a"})
+
+
+def _is_supported(path: Path) -> bool:
+    return path.is_file() and path.suffix.casefold() in SUPPORTED_SUFFIXES
+
+
+def discover_audio(input_path: Path) -> list[Path]:
+    """Resolve one audio file or discover immediate audio children."""
+    path = input_path.expanduser()
+    if not path.exists():
+        raise ValueError(f"输入路径不存在：{input_path}")
+    if path.is_file():
+        if not _is_supported(path):
+            raise ValueError(f"不支持的音频格式：{path.suffix or '(无扩展名)'}")
+        return [path.resolve()]
+    if not path.is_dir():
+        raise ValueError(f"输入路径既不是文件也不是目录：{input_path}")
+
+    audio_paths = sorted(
+        (child.resolve() for child in path.iterdir() if _is_supported(child)),
+        key=lambda child: (child.name.casefold(), child.name),
+    )
+    if not audio_paths:
+        raise ValueError(f"目录中没有支持的音频文件：{input_path}")
+    return audio_paths

mpup/enriched_audio.py

@@ -0,0 +1,147 @@
+"""Write a playable MP3 copy with resolved artwork and synchronized lyrics."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import tempfile
+from collections.abc import Callable, Sequence
+from pathlib import Path
+
+from mpup.lyrics import LyricCue
+
+
+Runner = Callable[..., subprocess.CompletedProcess[str]]
+_UNSAFE_FILENAME_CHARACTER = re.compile(r"[\\\\/:\x00]")
+
+
+def _filename_component(value: str) -> str:
+    """Keep the requested name readable without letting metadata escape its folder."""
+    cleaned = _UNSAFE_FILENAME_CHARACTER.sub("-", value.strip())
+    if not cleaned:
+        raise ValueError("歌名和歌手不能为空")
+    return cleaned
+
+
+def enriched_mp3_path(source_path: Path, title: str, artist: str) -> Path:
+    """Return the sibling MP3 path requested for a resolved song."""
+    return source_path.parent / f"{_filename_component(title)}-{_filename_component(artist)}.mp3"
+
+
+def lrc_from_cues(cues: Sequence[LyricCue] | None) -> str | None:
+    """Serialize renderer cues as deterministic, timestamped LRC tag text."""
+    if not cues:
+        return None
+    lines: list[str] = []
+    for cue in cues:
+        total_seconds, milliseconds = divmod(cue.start_ms, 1000)
+        minutes, seconds = divmod(total_seconds, 60)
+        lines.append(f"[{minutes:02d}:{seconds:02d}.{milliseconds:03d}]{cue.text}")
+    return "\n".join(lines)
+
+
+def build_enriched_mp3_command(
+    source_path: Path,
+    destination: Path,
+    title: str,
+    artist: str,
+    cover_path: Path | None,
+    lyrics: Sequence[LyricCue] | None,
+    *,
+    ffmpeg: str = "ffmpeg",
+) -> list[str]:
+    """Build a shell-free transcode that maps source audio plus optional cover."""
+    command = [
+        ffmpeg,
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-y",
+        "-i",
+        str(source_path),
+    ]
+    if cover_path is not None:
+        command.extend(["-i", str(cover_path), "-map", "0:a:0", "-map", "1:v:0"])
+    else:
+        command.extend(["-map", "0:a:0"])
+    command.extend(
+        [
+            "-map_metadata",
+            "-1",
+            "-c:a",
+            "libmp3lame",
+            "-q:a",
+            "0",
+            "-id3v2_version",
+            "3",
+            "-metadata",
+            f"title={title}",
+            "-metadata",
+            f"artist={artist}",
+        ]
+    )
+    lyrics_text = lrc_from_cues(lyrics)
+    if lyrics_text is not None:
+        command.extend(["-metadata", f"syncedlyrics={lyrics_text}"])
+    if cover_path is not None:
+        command.extend(
+            [
+                "-c:v",
+                "mjpeg",
+                "-disposition:v:0",
+                "attached_pic",
+                "-metadata:s:v:0",
+                "title=Album cover",
+                "-metadata:s:v:0",
+                "comment=Cover (front)",
+            ]
+        )
+    command.append(str(destination))
+    return command
+
+
+def write_enriched_mp3(
+    source_path: Path,
+    title: str,
+    artist: str,
+    cover_path: Path | None,
+    lyrics: Sequence[LyricCue] | None,
+    *,
+    ffmpeg: str = "ffmpeg",
+    overwrite: bool = False,
+    runner: Runner = subprocess.run,
+) -> Path:
+    """Atomically create the sibling ``<title>-<artist>.mp3`` metadata copy."""
+    destination = enriched_mp3_path(source_path, title, artist)
+    if destination.exists() and destination != source_path and not overwrite:
+        raise FileExistsError(f"元数据 MP3 已存在：{destination}")
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    temporary = tempfile.NamedTemporaryFile(
+        prefix=f".{destination.stem}.",
+        suffix=".tmp.mp3",
+        dir=destination.parent,
+        delete=False,
+    )
+    temporary_path = Path(temporary.name)
+    temporary.close()
+    try:
+        command = build_enriched_mp3_command(
+            source_path,
+            temporary_path,
+            title,
+            artist,
+            cover_path,
+            lyrics,
+            ffmpeg=ffmpeg,
+        )
+        result = runner(command, capture_output=True, text=True, check=False)
+        if result.returncode != 0:
+            detail = result.stderr.strip() or "未知错误"
+            raise RuntimeError(f"FFmpeg 写入 MP3 元数据失败：{detail[-2000:]}")
+        if not temporary_path.is_file() or temporary_path.stat().st_size == 0:
+            raise RuntimeError("FFmpeg 未生成元数据 MP3")
+        os.replace(temporary_path, destination)
+    finally:
+        temporary_path.unlink(missing_ok=True)
+    return destination

mpup/itunes.py

@@ -0,0 +1,112 @@
+"""Look up music metadata through the public iTunes Search API."""
+
+from __future__ import annotations
+
+import json
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+from urllib.error import HTTPError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+
+ITUNES_SEARCH_URL = "https://itunes.apple.com/search"
+DEFAULT_USER_AGENT = "MPUp/0.1.0 (https://github.com/)"
+
+
+@dataclass(frozen=True)
+class ItunesTrack:
+    """A song match returned by iTunes, with a downloadable artwork URL."""
+
+    title: str
+    artist: str
+    album: str | None
+    artwork_url: str | None
+
+
+Opener = Callable[..., Any]
+Sleeper = Callable[[float], None]
+
+
+def _clean_string(value: object) -> str | None:
+    if not isinstance(value, str):
+        return None
+    return value.strip() or None
+
+
+def _high_resolution_artwork(url: str | None) -> str | None:
+    if url is None:
+        return None
+    return url.replace("100x100bb", "600x600bb")
+
+
+def _track_from_payload(payload: object) -> ItunesTrack | None:
+    if not isinstance(payload, dict):
+        raise RuntimeError("iTunes 返回了无效 JSON 对象")
+    results = payload.get("results")
+    if not isinstance(results, list):
+        raise RuntimeError("iTunes 返回了无效搜索结果")
+    if not results:
+        return None
+
+    match = results[0]
+    if not isinstance(match, dict):
+        raise RuntimeError("iTunes 返回了无效歌曲结果")
+    title = _clean_string(match.get("trackName"))
+    artist = _clean_string(match.get("artistName"))
+    if title is None or artist is None:
+        raise RuntimeError("iTunes 返回的歌曲缺少歌名或歌手")
+    return ItunesTrack(
+        title=title,
+        artist=artist,
+        album=_clean_string(match.get("collectionName")),
+        artwork_url=_high_resolution_artwork(_clean_string(match.get("artworkUrl100"))),
+    )
+
+
+def search_track(
+    title: str,
+    artist: str,
+    *,
+    opener: Opener = urlopen,
+    sleeper: Sleeper = time.sleep,
+    max_rate_limit_retries: int = 3,
+) -> ItunesTrack | None:
+    """Return iTunes' best song match, retrying 429 responses with backoff."""
+    cleaned_title = title.strip()
+    cleaned_artist = artist.strip()
+    if not cleaned_title or not cleaned_artist:
+        raise ValueError("歌名和歌手不能为空")
+    if max_rate_limit_retries < 0:
+        raise ValueError("限流重试次数不能小于 0")
+
+    query = urlencode(
+        {
+            "term": f"{cleaned_artist} {cleaned_title}",
+            "media": "music",
+            "entity": "song",
+            "limit": "1",
+        }
+    )
+    request = Request(
+        f"{ITUNES_SEARCH_URL}?{query}",
+        headers={"User-Agent": DEFAULT_USER_AGENT, "Accept": "application/json"},
+    )
+
+    for attempt in range(max_rate_limit_retries + 1):
+        try:
+            with opener(request, timeout=10) as response:
+                body = response.read()
+            try:
+                payload = json.loads(body.decode("utf-8"))
+            except (AttributeError, UnicodeDecodeError, json.JSONDecodeError) as error:
+                raise RuntimeError("iTunes 返回了无效 JSON") from error
+            return _track_from_payload(payload)
+        except HTTPError as error:
+            if error.code != 429 or attempt == max_rate_limit_retries:
+                raise
+            sleeper(float(2**attempt))
+
+    raise AssertionError("unreachable")