chore: merge latest v3 into site protocol refactor

This commit is contained in:
jxxghp
2026-11-12 10:37:22 +08:00
6 changed files with 1087 additions and 26 deletions

View File

@@ -638,6 +638,9 @@ def scrape(
) -> Any:
"""
按请求级媒体身份、剧集组和音乐实体设置刮削单项媒体;会覆盖目标目录的图片和 NFO,与文件管理一样要求管理权限。
专辑曲目标题、艺人和曲序仅在音乐标签策略为覆盖且曲目可靠对位时更新;
未匹配或保留的情况通过响应消息说明。
"""
return _scrape_impl(
fileitem,

View File

@@ -16,7 +16,7 @@ from threading import Lock
from typing import Any, Iterable, List, Optional, Protocol, Self, Tuple, Union, cast
from urllib.parse import urlsplit
from app.application.audio import AudioMetadataHelper
from app.application.audio import AudioMetadataHelper, music_cue_enabled
from app.application.configuration import (
get_chain_runtime_config_snapshot,
get_configured_system_config,
@@ -35,7 +35,12 @@ from app.domain.context import (
from app.domain.meta.metabase import MetaBase
from app.domain.meta.metamusic import MetaMusic
from app.domain.metainfo import MetaInfo, MetaInfoPath
from app.domain.music import music_cover_priority
from app.domain.music import (
align_music_tracks,
music_album_has_consistent_tracks,
music_cover_priority,
music_isrc_conflicts,
)
from app.foundation.singleton import Singleton
from app.foundation.text import convert
from app.runtime.cache import cached
@@ -206,10 +211,12 @@ class _MusicScrapeFileResult:
:param metadata_success: 当前文件标签刮削是否成功,未发生标签写入错误时默认 True
:param lyrics_status: 歌词处理状态:disabled 表示未启用,saved 为新增,upgraded 为升级,existing 为已存在,
protected 为防降级保留,missing 为未匹配,budget_exceeded 为预算耗尽,failed 为失败
:param album_track_matched: 专辑标签写入时是否采用可靠匹配的曲目;未写入标签或写入失败时为 None
"""
metadata_success: bool = True
lyrics_status: str = "disabled"
album_track_matched: Optional[bool] = None
class ScrapingOption:
@@ -392,6 +399,8 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
}
MUSIC_LEGACY_LYRICS_EXTENSIONS = (".lyricsfile.yaml", ".txt")
# 与音频元数据读取器对同目录 CUE 的数量上限保持一致
MUSIC_MAX_CUE_FILES = 32
IMAGE_EXTENSIONS = frozenset({".jpg", ".jpeg", ".png", ".webp"})
_music_track_prefix_pattern = re.compile(
r"^\s*(?:(?:cd|disc)\s*\d+\s*[-_. ]+)?(?:\d+\s*[-_. ]+)+",
@@ -1496,8 +1505,16 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
音乐识别由 MediaChain 提供,标签、封面和歌词写入仅由当前刮削链编排。
:param audio_files: 已确认属于本批次的音频文件;为空时按 fileitem 展开
音乐标签设为覆盖时,只有可靠对位的专辑曲目才可替换本地曲目字段;
手动覆盖允许以唯一曲序纠正曲名,自动刮削继续使用严格证据。
:param fileitem: 待刮削的音频文件或目录
:param mediainfo: 用户或识别流程指定的音乐身份
:param overwrite: 是否按手动覆盖语义处理已有产物
:param media_source: 未指定身份时用于识别音频的来源
:param audio_files: 已确认属于本批次的音频文件;为 None 时按 fileitem 展开
:param media_by_path: 每个音频文件对应的音乐身份,避免批次内不同单曲互相覆盖
:return: 刮削是否成功及标签、歌词的处理说明
"""
files = self._normalize_music_audio_fileitems(
audio_files if audio_files is not None else self._music_audio_fileitems(fileitem)
@@ -1535,9 +1552,13 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
deadline=time.monotonic() + max(self.runtime_config.lyrics_batch_timeout, 0)
)
cover_cache: dict[str, tuple[Optional[bytes], str]] = {}
album_cache: dict[tuple[str, str], Optional[MusicAlbumInfo]] = {}
album_cache: dict[tuple[MediaSource, str, Optional[str]], Optional[MusicAlbumInfo]] = {}
album_tracks = self._plan_music_album_tracks(
files, file_media, album_cache, allow_title_override=overwrite,
) if nfo_option.is_overwrite and not nfo_option.is_skip else {}
failures: list[str] = []
track_counts = {True: 0, False: 0}
lyrics_counts = {
"saved": 0,
"existing": 0,
@@ -1559,20 +1580,7 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
if cover_url not in cover_cache:
cover_cache[cover_url] = self._download_music_cover(cover_url)
item_cover = cover_cache[cover_url]
album_info = None
if (
item_media
and item_media.music_type == MUSIC_ENTITY_ALBUM
and item_media.media_source
and item_media.media_id
):
album_key = (item_media.media_source, item_media.media_id)
if album_key not in album_cache:
album_cache[album_key] = MediaChain().get_music_album(
media_source=item_media.media_source,
media_id=item_media.media_id,
)
album_info = album_cache[album_key]
album_info = self._music_scrape_album(item_media, album_cache)
result = self._scrape_music_file(
audio_item,
item_media,
@@ -1586,6 +1594,7 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
lyrics_chain=lyrics_chain,
album_info=album_info,
media_source=media_source,
album_track=album_tracks.get(self._music_file_key(audio_item)),
)
if not result.metadata_success:
failures.append(
@@ -1595,8 +1604,14 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
lyrics_counts[result.lyrics_status] += 1
if result.lyrics_status == "failed":
failures.append(f"{audio_item.name or audio_item.path} 歌词保存失败")
if result.album_track_matched is not None:
track_counts[result.album_track_matched] += 1
message = f"已刮削 {len(files)} 个音频文件"
track_summary = self._music_album_track_summary(track_counts, nfo_option.is_overwrite)
if track_summary:
message += f",{track_summary}"
logger.info(f"音乐专辑刮削:{track_summary}")
if not lyrics_option.is_skip:
message += (
f",歌词新增 {lyrics_counts['saved']} 首"
@@ -1613,6 +1628,203 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
return False, f"{message};{';'.join(failures[:3])}"
return True, message
@staticmethod
def _music_album_track_summary(counts: dict[bool, int], overwrite: bool) -> str:
"""
说明已对位和保留的曲目,避免把专辑字段更新误认为曲目标签已覆盖。
"""
matched, preserved = counts[True], counts[False]
if not matched and not preserved:
return ""
if not overwrite:
return f"{preserved} 个文件保留已有曲名、艺人和曲序;音乐标签设为覆盖可尝试更新"
if preserved:
return f"曲目匹配 {matched} 个,{preserved} 个文件未可靠匹配,保留已有曲名、艺人和曲序"
return f"曲目匹配 {matched} 个"
@staticmethod
def _music_album_key(info: Optional[MusicInfo]) -> Optional[tuple[MediaSource, str, Optional[str]]]:
"""
区分专辑来源、发行组和明确选择的 MusicBrainz 发行版本。
"""
if not info or info.music_type != MUSIC_ENTITY_ALBUM or not info.media_source or not info.media_id:
return None
release_id = (
info.musicbrainz_release_id.lower()
if info.media_source == MediaSource.MusicBrainz and info.musicbrainz_release_id
else None
)
return info.media_source, info.media_id, release_id
def _music_scrape_album(
self,
info: Optional[MusicInfo],
cache: dict[tuple[MediaSource, str, Optional[str]], Optional[MusicAlbumInfo]],
) -> Optional[MusicAlbumInfo]:
"""
获取并复用专辑曲目;显式发行版本不能被默认代表版本替换。
"""
key = self._music_album_key(info)
if key is None:
return None
if key not in cache:
source, media_id, release_id = key
kwargs: dict[str, Any] = {"media_source": source, "media_id": media_id}
if release_id:
kwargs["musicbrainz_release_id"] = release_id
cache[key] = MediaChain().get_music_album(**kwargs)
return cache[key]
@staticmethod
def _music_file_key(item: _SchemaFileItem) -> tuple[str, str]:
"""
用存储和规范路径区分批次内的音频文件。
"""
return item.storage or "local", Path(item.path or "").as_posix()
@staticmethod
def _remote_music_copy_matches(item: _SchemaFileItem, path: Path, directory: Path) -> bool:
"""
远端音轨必须以原文件名下载到指定目录,CUE 才能按原引用定位它。
"""
return bool(
item.path and path.name == Path(item.path).name and path.parent.resolve() == directory.resolve()
)
def _read_music_track_evidence(self, item: _SchemaFileItem) -> Optional[MetaMusic]:
"""
只读取得对位证据;远端副本逐个释放,避免把整张专辑常驻临时目录。
"""
if item.storage == "local":
path = self.storagechain.download_file(item)
return AudioMetadataHelper.read(path) if path else None
with TemporaryDirectory(prefix="moviepilot-music-align-") as directory:
path = self.storagechain.download_file(item, path=Path(directory))
if not path or not self._remote_music_copy_matches(item, path, Path(directory)):
return None
if not self._stage_remote_music_cues(item, Path(directory)):
return None
return AudioMetadataHelper.read(path)
def _stage_remote_music_cues(self, item: _SchemaFileItem, directory: Path) -> bool:
"""
将远端同目录 CUE 带到临时副本旁;目录或索引不可读取时不猜测曲目。
"""
if not music_cue_enabled():
return True
parent = self.storagechain.get_parent_item(item)
if not parent:
return False
siblings = self.storagechain.list_files(parent, recursion=False)
if siblings is None or not any(
sibling.type == "file" and self._music_file_key(sibling) == self._music_file_key(item)
for sibling in siblings
):
# 普通目录列表可能把失败当成空列表;至少要能确认当前音轨在返回结果中。
return False
cues = [
sibling for sibling in siblings
if sibling.type == "file"
and (name := Path(sibling.path or sibling.name or "")).suffix.casefold() == ".cue"
and not name.name.startswith(".")
]
if len(cues) > self.MUSIC_MAX_CUE_FILES:
return False
for sibling in cues:
cue = self.storagechain.download_file(sibling, path=directory)
if (
not cue or cue.name != Path(sibling.path or "").name
or cue.suffix.casefold() != ".cue" or cue.parent.resolve() != directory.resolve()
):
return False
return True
@staticmethod
def _music_track_evidence_unchanged(expected: MetaMusic, current: MetaMusic) -> bool:
"""
写入前复核对位所用的标签和 CUE 证据,避免使用过期匹配覆盖新内容。
"""
fields = (
"title", "artists", "track_number", "disc_number", "duration", "version", "isrc",
"media_source", "media_id", "music_type", "musicbrainz_release_id",
"musicbrainz_release_group_id", "musicbrainz_release_track_id",
"composers", "conductors", "orchestras", "performers",
"music_layout", "cue_tracks", "organization_error",
)
return all(getattr(expected, key) == getattr(current, key) for key in fields) and all(
expected.field_sources.get(key) == current.field_sources.get(key)
for key in ("title", "artists")
)
@staticmethod
def _music_track_identity_conflicts(local: MetaMusic, track: MusicInfo) -> bool:
"""
手动纠正曲名也不能忽略明确不同的录音、发行身份或 ISRC。
"""
local_id, track_id = local.media_id, track.media_id
if local.media_source == track.media_source == MediaSource.MusicBrainz:
local_id = local_id.lower() if local_id else None
track_id = track_id.lower() if track_id else None
return bool(
music_isrc_conflicts(track, local)
or (
local_id and track_id and local.media_source == track.media_source and local_id != track_id
)
or any(
getattr(local, key) and getattr(track, key)
and getattr(local, key).lower() != getattr(track, key).lower()
for key in ("musicbrainz_release_id", "musicbrainz_release_group_id", "musicbrainz_release_track_id")
)
)
def _plan_music_album_tracks(
self,
files: list[_SchemaFileItem],
file_media: list[Optional[MusicInfo]],
cache: dict[tuple[MediaSource, str, Optional[str]], Optional[MusicAlbumInfo]],
*,
allow_title_override: bool,
) -> dict[tuple[str, str], tuple[MetaMusic, MusicInfo]]:
"""
为每张专辑按整批双向唯一证据对位,拒绝整轨 CUE 和身份冲突。
远端音频在对位与实际写入时分别下载,写入前重新核对证据;
不依赖文件排序或把尚未匹配的剩余文件强行分配给曲目。
"""
groups: dict[tuple[MediaSource, str, Optional[str]], list[_SchemaFileItem]] = {}
infos: dict[tuple[MediaSource, str, Optional[str]], MusicInfo] = {}
for item, info in zip(files, file_media):
key = self._music_album_key(info)
if key is not None and info is not None:
groups.setdefault(key, []).append(item)
infos[key] = info
planned: dict[tuple[str, str], tuple[MetaMusic, MusicInfo]] = {}
for key, items in groups.items():
album = self._music_scrape_album(infos[key], cache)
if not album or not album.tracks or not music_album_has_consistent_tracks(album):
continue
if album.media_source != key[0] or album.media_id != key[1] or (key[2] and album.musicbrainz_release_id != key[2]):
continue
tracks = [track for track in album.tracks if track.music_type == MUSIC_ENTITY_RECORDING]
evidence = [(item, self._read_music_track_evidence(item)) for item in items]
eligible = [
(item, meta) for item, meta in evidence
if meta is not None and meta.music_layout != "image_cue" and not meta.organization_error
]
if len(eligible) != len(items):
# 不完整的本地证据无法证明整批文件与线上曲目之间的双向唯一性。
continue
aligned = align_music_tracks(
[meta for _, meta in eligible], tracks, allow_title_override=allow_title_override,
)
for index, remote in aligned.items():
item, meta = eligible[index]
track = tracks[remote]
if not self._music_track_identity_conflicts(meta, track):
planned[self._music_file_key(item)] = meta, deepcopy(track)
return planned
@staticmethod
def _music_scrape_identity(
info: MusicInfo,
@@ -1768,6 +1980,7 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
lyrics_chain: Optional[LyricsChain] = None,
album_info: Optional[MusicAlbumInfo] = None,
media_source: Optional[MediaSource] = None,
album_track: Optional[tuple[MetaMusic, MusicInfo]] = None,
) -> _MusicScrapeFileResult:
"""
下载单个音轨并执行标签、封面和歌词刮削,远端产物写回原目录。
@@ -1799,12 +2012,18 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
lyrics_chain=lyrics_chain,
album_info=album_info,
media_source=media_source,
album_track=album_track,
)
with TemporaryDirectory(prefix="moviepilot-music-scrape-") as temp_dir:
local_path = storage.download_file(fileitem, path=Path(temp_dir))
if not local_path:
return download_failure
if album_track and (
not self._remote_music_copy_matches(fileitem, local_path, Path(temp_dir))
or not self._stage_remote_music_cues(fileitem, Path(temp_dir))
):
album_track = None
return self._apply_music_file_scrape(
fileitem=fileitem,
local_path=local_path,
@@ -1819,6 +2038,7 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
lyrics_chain=lyrics_chain,
album_info=album_info,
media_source=media_source,
album_track=album_track,
)
def _apply_music_file_scrape(
@@ -1836,11 +2056,25 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
lyrics_chain: Optional[LyricsChain],
album_info: Optional[MusicAlbumInfo],
media_source: Optional[MediaSource],
album_track: Optional[tuple[MetaMusic, MusicInfo]] = None,
) -> _MusicScrapeFileResult:
"""
在本地音轨副本上执行刮削,并将变更后的音频和歌词写回目标存储。
"""
scrape_info = self._resolve_music_scrape_info(local_path, mediainfo, media_source=media_source)
album_track_matched = None
scrape_info: Optional[Union[MetaMusic, MusicInfo]]
if write_tags and mediainfo and mediainfo.music_type == MUSIC_ENTITY_ALBUM:
local_meta = AudioMetadataHelper.read(local_path)
track = (
album_track[1]
if album_track and self._music_track_evidence_unchanged(album_track[0], local_meta)
else None
)
album_track_matched = track is not None
self._preserve_music_image_tags(local_path, local_meta)
scrape_info = self._merge_music_album_metadata(local_meta, mediainfo, track)
else:
scrape_info = self._resolve_music_scrape_info(local_path, mediainfo, media_source=media_source)
if with_cover:
if cover is None:
cover_url = getattr(mediainfo, "cover_url", None) or getattr(scrape_info, "cover_url", None)
@@ -1886,14 +2120,43 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
return _MusicScrapeFileResult(
metadata_success=metadata_success,
lyrics_status=lyrics_status,
album_track_matched=album_track_matched if metadata_success else None,
)
@staticmethod
def _merge_music_album_metadata(local_meta: MetaMusic, album: MusicInfo) -> MetaMusic:
def _preserve_music_image_tags(path: Path, meta: MetaMusic) -> None:
"""
把专辑级字段合并到单个音轨标签,同时保留该文件自己的标题、艺术家和曲序。
整轨 CUE 的识别结果使用专辑标题,但已有音频标签仍须按保留策略留存。
:param path: 已下载的音频路径
:param meta: 可原地调整的 CUE 合并元数据
"""
if meta.music_layout != "image_cue":
return
tags = AudioMetadataHelper.read_tags(path)
if not tags:
return
meta.title = tags.title or meta.title
meta.artists = list(tags.artists or meta.artists)
meta.track_number = tags.track_number
@staticmethod
def _merge_music_album_metadata(
local_meta: MetaMusic,
album: MusicInfo,
track: Optional[MusicInfo] = None,
) -> MetaMusic:
"""
把专辑级字段合并到音轨;仅在曲目已可靠对位时采用非空的线上曲目字段。
单碟专辑除外:线上碟数已确认为 1 时碟号必为 1,本地错标的碟号不能
再与 total_discs=1 配成 "2/1" 写进标签。
再与 total_discs=1 配成 "2/1" 写进标签。音轨身份仍使用本地录音 ID,
不能用专辑 ID 补位。
:param local_meta: 当前音频读取的标签与路径证据
:param album: 需要合并的专辑信息
:param track: 已可靠对位的专辑曲目;为 None 时保留本地曲目字段
:return: 不修改输入对象的合并结果
"""
merged = deepcopy(local_meta)
merged.artists = list(local_meta.artists or album.artists)
@@ -1904,6 +2167,13 @@ class ScrapingChain(ChainBase, ConfigReloadMixin, metaclass=Singleton):
merged.total_discs = album.total_discs or local_meta.total_discs
if album.total_discs == 1:
merged.disc_number = 1
if track:
merged.title = track.title or merged.title
merged.artists = list(track.artists or merged.artists)
merged.track_number = track.track_number or merged.track_number
merged.total_tracks = track.total_tracks or merged.total_tracks
if album.total_discs != 1:
merged.disc_number = track.disc_number or merged.disc_number
# MetaMusic 的身份代表音轨;保留已有单曲 ID,不能用专辑 ID 补位,
# 否则会误写 musicbrainz_trackid,使下次拿 release-group 查询 recording。
return merged

View File

@@ -594,6 +594,8 @@ Emby、Jellyfin、Plex、Navidrome 的目录、条目、搜索、季集和活动
`media.scrape` 遇到不支持的媒体文件或 NFO 保存失败时返回 `success: false` 及原因,目录中的媒体保存失败也会向上传递。不要将这种响应报告为刮削完成。
音乐专辑刮削默认保留已有曲名、艺人和曲序,响应 `message` 与日志会说明。需要尝试更新时,可在系统刮削设置中将“音乐标签”设为“覆盖”:只有与专辑曲目双向唯一对位、且录音身份和时长没有冲突的文件才会采用来源提供的曲目字段;未可靠匹配的文件继续保留本地字段。手动刮削可按唯一曲序纠正曲名,自动刮削使用更严格的证据;启用 CUE 读取时,整轨 CUE 不会被当作单曲覆盖。结果中的匹配数量不等同于实际发生变化的标签数量。远端音轨在对位和写入阶段分别下载;启用 CUE 读取时,目录未列出当前音轨或索引下载失败会保留曲目字段。普通远端存储列表不保证返回全部子项,使用此类存储前应核对 CUE 或通过本地挂载操作。
### 分页与截断
- 按选定操作的合同使用分页字段。例如 `subscription.list` 使用 `page` / `count`,`subscription.execution.list` 使用 `limit`,原生服务列表常用 `offset` / `limit`。

View File

@@ -374,8 +374,11 @@ token exchange downloads retain their existing credential rules.
- Treat `success=false`, HTTP error data, empty results, and validation errors as
real outcomes. Do not claim success without checking the response.
- `media.scrape` reports rejected media and failed NFO writes as business failures,
including failures within a directory. For concurrent custom-filter changes,
re-read the rules and confirm the intended change before retrying a conflict.
including failures within a directory. For music albums, report its `message`:
track titles, artists and numbers are retained by default; the music tag
overwrite policy only updates reliably aligned tracks. An aligned count does
not prove every tag changed. For concurrent custom-filter changes, re-read
the rules and confirm the intended change before retrying a conflict.
- Respect an explicit `execution_outcome`: `pending` is accepted but unfinished,
`unknown` means a write may have happened, and `replayed` means this call did
not execute; `previous_status` describes the earlier receipt. Do not repeat an

View File

@@ -40,8 +40,9 @@ recognition, transfer, and history tools are not available.
7. Call `transfer.file` once per verified unit. For an album, transfer the album
directory once only after its supported audio-file count is consistent with
the selected album detail.
8. If requested, call `media.scrape` after a successful transfer. Report actual
tag, cover, and lyrics counts; never assume all lyrics were found.
8. If requested, call `media.scrape` after a successful transfer. Report its
actual message, including any preserved album track fields and lyrics counts;
never assume all tracks were overwritten or all lyrics were found.
## Structured Calls

View File

@@ -0,0 +1,782 @@
"""
验证专辑刮削对曲目标签的覆盖策略、对位保护和结果提示。
"""
import os
import shutil
from pathlib import Path
from types import SimpleNamespace
from typing import Optional
from unittest.mock import Mock
import pytest
from fastapi import FastAPI
from fastapi.testclient import TestClient
from mutagen.flac import FLAC
from app.api.dependencies.auth import get_current_active_user
from app.api.endpoints import media as media_endpoint
from app.application.audio import AudioMetadataHelper, use_music_cue
from app.chain.scraping import ScrapingChain, ScrapingConfig
from app.domain.context import MusicAlbumInfo, MusicInfo
from app.schemas.file import FileItem
from app.schemas.types import MediaSource
_GROUP = "25aa1b18-5e85-43c2-94c4-4b07ad96268a"
_RECORDINGS = (
"38035858-f990-4fbb-b3b2-f2f8b958eeba",
"f4f1b7b2-22b0-4ce0-9ac6-31c336c52812",
)
_OTHER_RECORDING = "70b71113-b078-4f07-9d24-374482016a41"
def _album() -> MusicAlbumInfo:
"""
构造包含两首不同曲目和独立录音身份的专辑。
"""
return MusicAlbumInfo(
media_source=MediaSource.MusicBrainz,
media_id=_GROUP,
musicbrainz_release_group_id=_GROUP,
title="正确专辑",
artists=["专辑歌手"],
total_discs=1,
tracks=[
MusicInfo(
media_source=MediaSource.MusicBrainz,
media_id=recording_id,
album_id=_GROUP,
musicbrainz_release_group_id=_GROUP,
title=title,
artists=[artist],
disc_number=1,
track_number=number,
total_tracks=2,
)
for number, (recording_id, title, artist) in enumerate(
zip(_RECORDINGS, ("正确一", "正确二"), ("线上歌手一", "线上歌手二")),
start=1,
)
],
)
def _audio(path: Path, title: str, artist: str, track: int, recording_id: str = "") -> Path:
"""
创建真实 FLAC 文件并写入待修正的本地标签。
"""
path.parent.mkdir(parents=True, exist_ok=True)
shutil.copyfile(Path(__file__).parent / "fixtures/audio/silence.flac", path)
tags = FLAC(path)
tags["title"] = [title]
tags["artist"] = [artist]
tags["album"] = ["旧专辑"]
tags["tracknumber"] = [str(track)]
tags["discnumber"] = ["1"]
if recording_id:
tags["musicbrainz_trackid"] = [recording_id]
tags.save()
return path
def _item(path: Path, storage: str = "local") -> FileItem:
"""
将测试音频路径转换为刮削链使用的文件项。
"""
return FileItem(storage=storage, path=path.as_posix(), type="file", name=path.name)
def _chain(monkeypatch: pytest.MonkeyPatch, album: MusicAlbumInfo, policy: str) -> ScrapingChain:
"""
构造隔离的刮削链,专辑详情使用离线替身,封面和歌词关闭。
"""
chain = object.__new__(ScrapingChain)
chain.storagechain = Mock()
chain.storagechain.download_file.side_effect = lambda item, **_kwargs: Path(item.path)
chain.scraping_policies = ScrapingConfig({
"music_nfo": policy,
"music_poster": "skip",
"music_lyrics": "skip",
})
media_chain = Mock()
media_chain.get_music_album.return_value = album
monkeypatch.setattr("app.chain.scraping.MediaChain", lambda: media_chain)
return chain
def _scrape(chain: ScrapingChain, album: MusicAlbumInfo, files: list[FileItem], *, overwrite: bool = True):
"""
按指定专辑刮削测试文件,保持文件顺序由调用方决定。
"""
return chain.scrape_music_metadata(
fileitem=FileItem(storage=files[0].storage, path="/music/album", type="dir"),
mediainfo=album.to_music_info(),
audio_files=files,
overwrite=overwrite,
)
def _remote_storage(chain: ScrapingChain, audio: Path, cue: Optional[Path] = None):
"""
用临时文件模拟远端目录、逐次下载和上传,不访问真实存储服务。
"""
audio_item = _item(Path("/music/album") / audio.name, "u115")
cue_item = _item(Path("/music/album") / cue.name, "u115") if cue else None
contents = {audio_item.path: audio}
if cue_item:
contents[cue_item.path] = cue
storage = Mock()
storage.get_parent_item.return_value = FileItem(storage="u115", path="/music/album", type="dir")
storage.list_files.return_value = [audio_item, *([cue_item] if cue_item else [])]
def download(item, path=None):
"""
把远端测试文件复制到每次调用自己的临时目录。
"""
target = path / item.name
shutil.copyfile(contents[item.path], target)
return target
def upload(_parent, path, new_name=None):
"""
模拟上传更新后的音频,不修改同目录 CUE。
"""
assert new_name == audio.name
shutil.copyfile(path, audio)
return audio_item
storage.download_file.side_effect = download
storage.upload_file.side_effect = upload
chain.storagechain = storage
return audio_item, cue_item, storage
def test_missing_only_preserves_track_tags_and_explains_how_to_overwrite(tmp_path, monkeypatch):
"""
手动刮削也保留仅缺失策略下的本地曲目字段,并告知可切换音乐标签策略。
"""
album = _album()
path = _audio(tmp_path / "01.flac", "旧拼接标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "missingOnly")
success, message = _scrape(chain, album, [_item(path)])
result = AudioMetadataHelper.read_tags(path)
assert success
assert (result.title, result.artists, result.track_number) == ("旧拼接标题", ["本地歌手"], 1)
assert result.album == "正确专辑"
assert "保留" in message and "曲名" in message and "艺人" in message and "曲序" in message
assert "音乐标签" in message and "覆盖" in message
def test_overwrite_aligns_each_track_and_preserves_linked_source(tmp_path, monkeypatch):
"""
覆盖策略按整批唯一证据纠正曲名、艺人和错序,同时不修改硬链接源文件。
"""
album = _album()
seeds = [
_audio(tmp_path / "seed" / "first.flac", "旧拼接标题", "本地一", 1),
_audio(tmp_path / "seed" / "second.flac", "正确二", "本地二", 1),
]
library = tmp_path / "library"
library.mkdir()
files = [library / f"{number}.flac" for number in (1, 2)]
for seed, target in zip(seeds, files):
os.link(seed, target)
before = [seed.read_bytes() for seed in seeds]
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(path) for path in files])
assert success
assert "匹配 2" in message
for index, (seed, target) in enumerate(zip(seeds, files)):
result = AudioMetadataHelper.read_tags(target)
track = album.tracks[index]
assert (result.title, result.artists, result.track_number) == (track.title, track.artists, track.track_number)
assert result.album == "正确专辑"
assert result.media_id is None
assert seed.read_bytes() == before[index]
assert not os.path.samefile(seed, target)
def test_overwrite_preserves_duplicate_and_ambiguous_local_tracks(tmp_path, monkeypatch):
"""
两个文件争用相同曲目时不得按遍历顺序决定谁被覆盖。
"""
album = _album()
paths = [_audio(tmp_path / f"{number}.flac", "未知旧标题", "本地歌手", 1) for number in (1, 2)]
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(path) for path in paths])
assert success
assert "未可靠匹配" in message and "保留" in message
assert all(AudioMetadataHelper.read_tags(path).title == "未知旧标题" for path in paths)
assert all(AudioMetadataHelper.read_tags(path).track_number == 1 for path in paths)
def test_overwrite_preserves_conflicting_recording_identity(tmp_path, monkeypatch):
"""
不同录音 ID 不能仅凭相同曲序被改成另一首歌,也不能污染原身份。
"""
album = _album()
path = _audio(tmp_path / "01.flac", "旧标题", "本地歌手", 1, _OTHER_RECORDING)
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(path)])
result = AudioMetadataHelper.read_tags(path)
assert success
assert "未可靠匹配" in message and "保留" in message
assert (result.title, result.artists, result.media_id) == ("旧标题", ["本地歌手"], _OTHER_RECORDING)
def test_overwrite_preserves_track_on_duration_conflict(tmp_path, monkeypatch):
"""
本地时长与线上曲目显著冲突时,即使曲序相同也不覆盖标题。
"""
album = _album()
album.tracks[0].duration = 300
path = _audio(tmp_path / "01.flac", "旧标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(path)])
assert success
assert "未可靠匹配" in message
assert AudioMetadataHelper.read_tags(path).title == "旧标题"
def test_automatic_overwrite_does_not_guess_from_position_alone(tmp_path, monkeypatch):
"""
自动刮削即使启用覆盖,也不能把手动选择专辑时的曲名纠正放宽到普通自动识别。
"""
album = _album()
path = _audio(tmp_path / "01.flac", "本地不同曲名", "本地歌手", 1)
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(path)], overwrite=False)
assert success
assert "未可靠匹配" in message
assert AudioMetadataHelper.read_tags(path).title == "本地不同曲名"
def test_automatic_overwrite_corrects_position_with_strict_title_evidence(tmp_path, monkeypatch):
"""
自动刮削在曲名和艺人有严格证据时,覆盖策略仍可修正错标曲序。
"""
album = _album()
path = _audio(tmp_path / "01.flac", "正确一", "线上歌手一", 2)
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(path)], overwrite=False)
assert success and "匹配 1" in message
assert AudioMetadataHelper.read_tags(path).track_number == 1
def test_partial_track_matches_report_both_updated_and_preserved_files(tmp_path, monkeypatch):
"""
一个曲目成功对位、另一个录音身份冲突时,应分别报告匹配与保留数量。
"""
album = _album()
first = _audio(tmp_path / "01.flac", "旧一", "本地一", 1)
second = _audio(tmp_path / "02.flac", "旧二", "本地二", 2, _OTHER_RECORDING)
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(first), _item(second)])
assert success and "曲目匹配 1 个" in message and "1 个文件未可靠匹配" in message
assert AudioMetadataHelper.read_tags(first).title == "正确一"
assert AudioMetadataHelper.read_tags(second).title == "旧二"
def test_matched_track_with_missing_fields_keeps_local_values(tmp_path, monkeypatch):
"""
线上曲目缺少标题或艺人时不能用空值清除本地标签。
"""
album = _album()
album.tracks[0].title = None
album.tracks[0].artists = []
path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(path)])
result = AudioMetadataHelper.read_tags(path)
assert success and "匹配 1" in message
assert (result.title, result.artists) == ("本地标题", ["本地歌手"])
def test_overwrite_rechecks_metadata_before_writing(tmp_path, monkeypatch):
"""
对位后用户修改了音轨证据时,不能按过期快照覆盖新标签。
"""
album = _album()
path = _audio(tmp_path / "01.flac", "旧标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "overwrite")
downloads = []
def download(item, **_kwargs):
"""
在计划读取后模拟用户修改标签,再交还同一个本地文件。
"""
downloads.append(item.path)
if len(downloads) == 2:
tags = FLAC(path)
tags["title"] = ["用户新标题"]
tags.save()
return path
chain.storagechain.download_file.side_effect = download
success, message = _scrape(chain, album, [_item(path)])
assert success
assert "未可靠匹配" in message
assert AudioMetadataHelper.read_tags(path).title == "用户新标题"
def test_incomplete_batch_evidence_cannot_authorize_other_track_overwrites(tmp_path, monkeypatch):
"""
一个文件无法读取时,剩余文件不能声称已在整个批次中唯一对位。
"""
album = _album()
paths = [_audio(tmp_path / f"{number}.flac", "旧标题", "本地歌手", 1) for number in (1, 2)]
chain = _chain(monkeypatch, album, "overwrite")
calls = []
def download(item, **_kwargs):
"""
仅让计划阶段的第二个文件读取失败,后续写入阶段仍可访问。
"""
calls.append(item.path)
return None if len(calls) == 2 else Path(item.path)
chain.storagechain.download_file.side_effect = download
success, message = _scrape(chain, album, [_item(path) for path in paths])
assert success and "未可靠匹配" in message
assert all(AudioMetadataHelper.read_tags(path).title == "旧标题" for path in paths)
def test_overwrite_applies_simplified_track_text_supplied_by_source(tmp_path, monkeypatch):
"""
专辑曲目已按系统设置转为简体时,覆盖应实际写入曲名和艺人。
"""
album = _album()
album.tracks[0].title = "后来"
album.tracks[0].artists = ["优里"]
path = _audio(tmp_path / "01.flac", "後來", "優里", 1)
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(path)])
result = AudioMetadataHelper.read_tags(path)
assert success and "匹配 1" in message
assert (result.title, result.artists) == ("后来", ["优里"])
def test_overwrite_preserves_track_if_album_details_are_unavailable(tmp_path, monkeypatch):
"""
专辑详情无曲目时仍可刮削专辑字段,但必须报告保留本地曲目。
"""
album = _album()
path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "overwrite")
provider = Mock()
provider.get_music_album.return_value = None
monkeypatch.setattr("app.chain.scraping.MediaChain", lambda: provider)
success, message = _scrape(chain, album, [_item(path)])
result = AudioMetadataHelper.read_tags(path)
assert success and "未可靠匹配" in message and "保留" in message
assert (result.title, result.artists, result.album) == ("本地标题", ["本地歌手"], "正确专辑")
def test_overwrite_rejects_conflicting_isrc(tmp_path, monkeypatch):
"""
两个有效 ISRC 明确不同时,不能用匹配曲序覆盖另一录音的标签。
"""
album = _album()
album.tracks[0].isrc = "USQX91300105"
path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1)
tags = FLAC(path)
tags["isrc"] = ["USRC17607839"]
tags.save()
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(path)])
result = AudioMetadataHelper.read_tags(path)
assert success and "未可靠匹配" in message
assert (result.title, result.isrc) == ("本地标题", "USRC17607839")
def test_overwrite_preserves_conflicting_release_identity(tmp_path, monkeypatch):
"""
已知具体发行版本冲突时不覆写曲目,以免标签与保留的发行 ID 自相矛盾。
"""
album = _album()
album.musicbrainz_release_id = _RECORDINGS[1]
for track in album.tracks:
track.musicbrainz_release_id = album.musicbrainz_release_id
path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1)
tags = FLAC(path)
tags["musicbrainz_albumid"] = [_OTHER_RECORDING]
tags.save()
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(path)])
result = AudioMetadataHelper.read_tags(path)
assert success and "未可靠匹配" in message
assert (result.title, result.musicbrainz_release_id) == ("本地标题", _OTHER_RECORDING)
def test_overwrite_requests_selected_release_and_rejects_other_release(tmp_path, monkeypatch):
"""
已选择具体发行时必须传递该 ID,来源返回另一版本时不能套用其曲目。
"""
album = _album()
requested = album.to_music_info()
requested.musicbrainz_release_id = _OTHER_RECORDING.upper()
album.musicbrainz_release_id = _RECORDINGS[0]
path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "overwrite")
provider = Mock()
provider.get_music_album.return_value = album
monkeypatch.setattr("app.chain.scraping.MediaChain", lambda: provider)
success, message = chain.scrape_music_metadata(
fileitem=_item(path), mediainfo=requested, overwrite=True,
)
assert success and "未可靠匹配" in message
assert AudioMetadataHelper.read_tags(path).title == "本地标题"
provider.get_music_album.assert_called_once_with(
media_source=MediaSource.MusicBrainz, media_id=_GROUP, musicbrainz_release_id=_OTHER_RECORDING,
)
def test_overwrite_uses_confirmed_selected_release(tmp_path, monkeypatch):
"""
已确认的具体发行版本按规范化 ID 获取一次并用于曲目覆盖。
"""
album = _album()
album.musicbrainz_release_id = _OTHER_RECORDING
for track in album.tracks:
track.musicbrainz_release_id = _OTHER_RECORDING
requested = album.to_music_info()
requested.musicbrainz_release_id = _OTHER_RECORDING.upper()
path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "overwrite")
provider = Mock()
provider.get_music_album.return_value = album
monkeypatch.setattr("app.chain.scraping.MediaChain", lambda: provider)
success, message = chain.scrape_music_metadata(fileitem=_item(path), mediainfo=requested, overwrite=True)
assert success and "匹配 1" in message
assert AudioMetadataHelper.read_tags(path).title == "正确一"
provider.get_music_album.assert_called_once_with(
media_source=MediaSource.MusicBrainz, media_id=_GROUP, musicbrainz_release_id=_OTHER_RECORDING,
)
def test_overwrite_does_not_guess_between_discs_without_disc_number(tmp_path, monkeypatch):
"""
多碟发行中同一曲序重复且本地缺少碟号时不能选第一碟。
"""
album = _album()
album.total_discs = 2
album.tracks[1].disc_number = 2
album.tracks[1].track_number = 1
path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1)
tags = FLAC(path)
del tags["discnumber"]
tags.save()
chain = _chain(monkeypatch, album, "overwrite")
success, message = _scrape(chain, album, [_item(path)])
assert success and "未可靠匹配" in message
assert AudioMetadataHelper.read_tags(path).title == "本地标题"
def test_overwrite_keeps_image_cue_as_album_instead_of_one_track(tmp_path, monkeypatch):
"""
整轨 CUE 是包含多首歌的物理文件,不能将任意单曲标题写入该文件。
"""
album = _album()
path = _audio(tmp_path / "image.flac", "本地整轨", "本地歌手", 1)
cue = tmp_path / "album.cue"
cue.write_text(
'PERFORMER "本地歌手"\nTITLE "整轨专辑"\nFILE "image.flac" WAVE\n'
' TRACK 01 AUDIO\n TITLE "第一首"\n INDEX 01 00:00:00\n'
' TRACK 02 AUDIO\n TITLE "第二首"\n INDEX 01 00:01:00\n',
encoding="utf-8",
)
before = cue.read_bytes()
chain = _chain(monkeypatch, album, "overwrite")
with use_music_cue(True):
assert AudioMetadataHelper.read(path).music_layout == "image_cue"
success, message = _scrape(chain, album, [_item(path)])
result = AudioMetadataHelper.read_tags(path)
assert success and "未可靠匹配" in message
assert (result.title, result.artists, result.track_number) == ("本地整轨", ["本地歌手"], 1)
assert result.media_id is None and cue.read_bytes() == before
def test_remote_overwrite_rechecks_and_uploads_real_audio(tmp_path, monkeypatch):
"""
远端音轨使用隔离副本两次确认后上传,匹配结果和实际标签一致。
"""
album = _album()
path = _audio(tmp_path / "remote" / "01.flac", "旧标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "overwrite")
audio_item, _, storage = _remote_storage(chain, path)
with use_music_cue(True):
success, message = _scrape(chain, album, [audio_item])
result = AudioMetadataHelper.read_tags(path)
assert success and "匹配 1" in message
assert (result.title, result.artists) == ("正确一", ["线上歌手一"])
assert storage.download_file.call_count == 2
assert storage.list_files.call_count == 2
storage.upload_file.assert_called_once()
def test_remote_image_cue_does_not_receive_a_single_track_title(tmp_path, monkeypatch):
"""
远端整轨的 CUE 必须参与对位,不能因临时目录只有音频而误认为普通单曲。
"""
album = _album()
path = _audio(tmp_path / "remote" / "image.flac", "本地整轨", "本地歌手", 1)
cue = path.parent / "album.cue"
cue.write_text(
'PERFORMER "本地歌手"\nTITLE "整轨专辑"\nFILE "image.flac" WAVE\n'
' TRACK 01 AUDIO\n TITLE "第一首"\n INDEX 01 00:00:00\n'
' TRACK 02 AUDIO\n TITLE "第二首"\n INDEX 01 00:01:00\n',
encoding="utf-8",
)
before = cue.read_bytes()
chain = _chain(monkeypatch, album, "overwrite")
audio_item, _, storage = _remote_storage(chain, path, cue)
with use_music_cue(True):
success, message = _scrape(chain, album, [audio_item])
assert success and "未可靠匹配" in message
assert AudioMetadataHelper.read_tags(path).title == "本地整轨"
assert cue.read_bytes() == before
storage.upload_file.assert_called_once()
def test_remote_cue_added_after_planning_invalidates_track_match(tmp_path, monkeypatch):
"""
对位后出现整轨 CUE 时,写入阶段必须重新读取并取消过期的单曲匹配。
"""
album = _album()
path = _audio(tmp_path / "remote" / "image.flac", "本地整轨", "本地歌手", 1)
cue = path.parent / "album.cue"
cue.write_text(
'PERFORMER "本地歌手"\nTITLE "整轨专辑"\nFILE "image.flac" WAVE\n'
' TRACK 01 AUDIO\n TITLE "第一首"\n INDEX 01 00:00:00\n'
' TRACK 02 AUDIO\n TITLE "第二首"\n INDEX 01 00:01:00\n',
encoding="utf-8",
)
chain = _chain(monkeypatch, album, "overwrite")
audio_item, cue_item, storage = _remote_storage(chain, path, cue)
storage.list_files.side_effect = [[audio_item], [audio_item, cue_item]]
with use_music_cue(True):
success, message = _scrape(chain, album, [audio_item])
assert success and "未可靠匹配" in message
assert AudioMetadataHelper.read_tags(path).title == "本地整轨"
assert storage.list_files.call_count == 2
def test_remote_upload_failure_is_not_reported_as_matched(tmp_path, monkeypatch):
"""
临时音轨完成对位但上传失败时,响应必须报告失败而非声称远端已匹配。
"""
album = _album()
path = _audio(tmp_path / "remote" / "01.flac", "本地标题", "本地歌手", 1)
before = path.read_bytes()
chain = _chain(monkeypatch, album, "overwrite")
audio_item, _, storage = _remote_storage(chain, path)
storage.upload_file.side_effect = None
storage.upload_file.return_value = None
with use_music_cue(True):
success, message = _scrape(chain, album, [audio_item])
assert not success and "写入失败" in message
assert "曲目匹配" not in message
assert path.read_bytes() == before
def test_remote_overwrite_honors_disabled_cue_policy(tmp_path, monkeypatch):
"""
用户关闭 CUE 读取时,曲目对位不能额外扫描远端目录或下载索引。
"""
album = _album()
path = _audio(tmp_path / "remote" / "01.flac", "旧标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "overwrite")
audio_item, _, storage = _remote_storage(chain, path)
storage.list_files.side_effect = AssertionError("CUE 关闭时不得扫描目录")
with use_music_cue(False):
success, message = _scrape(chain, album, [audio_item])
assert success and "匹配 1" in message
assert AudioMetadataHelper.read_tags(path).title == "正确一"
storage.list_files.assert_not_called()
def test_remote_directory_with_too_many_cues_is_not_guessed(tmp_path, monkeypatch):
"""
远端 CUE 数量超过读取器上限时应保留标签,不能下载部分索引后猜测。
"""
album = _album()
path = _audio(tmp_path / "remote" / "01.flac", "本地标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "overwrite")
audio_item, _, storage = _remote_storage(chain, path)
storage.list_files.return_value = [
audio_item,
*[_item(Path(f"/music/album/{number}.cue"), "u115") for number in range(33)],
]
with use_music_cue(True):
success, message = _scrape(chain, album, [audio_item])
assert success and "未可靠匹配" in message
assert AudioMetadataHelper.read_tags(path).title == "本地标题"
assert all(call.args[0] == audio_item for call in storage.download_file.call_args_list)
@pytest.mark.parametrize("failure", ["list", "empty", "missing_audio", "cue"])
def test_remote_unknown_cue_state_preserves_track_tags(tmp_path, monkeypatch, failure):
"""
远端目录或 CUE 读取失败时不能假设音轨没有整轨索引。
"""
album = _album()
path = _audio(tmp_path / "remote" / "01.flac", "本地标题", "本地歌手", 1)
cue = path.parent / "album.cue"
cue.write_text("FILE \"01.flac\" WAVE\n", encoding="utf-8")
chain = _chain(monkeypatch, album, "overwrite")
audio_item, cue_item, storage = _remote_storage(chain, path, cue)
if failure == "list":
storage.list_files.return_value = None
elif failure == "empty":
storage.list_files.return_value = []
elif failure == "missing_audio":
storage.list_files.return_value = [cue_item]
else:
original_download = storage.download_file.side_effect
storage.download_file.side_effect = lambda item, path=None: (
None if item == cue_item else original_download(item, path=path)
)
with use_music_cue(True):
success, message = _scrape(chain, album, [audio_item])
assert success and "未可靠匹配" in message
assert AudioMetadataHelper.read_tags(path).title == "本地标题"
def test_remote_renamed_download_does_not_authorize_track_overwrite(tmp_path, monkeypatch):
"""
音频下载名不等于远端原名时,CUE 无法可靠引用,必须保留已有曲目。
"""
album = _album()
path = _audio(tmp_path / "remote" / "01.flac", "本地标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "overwrite")
audio_item, _, storage = _remote_storage(chain, path)
def download(_item, path=None):
"""
模拟存储提供方意外更改本地副本文件名。
"""
target = path / "renamed.flac"
shutil.copyfile(audio_item_path, target)
return target
audio_item_path = path
storage.download_file.side_effect = download
with use_music_cue(True):
success, message = _scrape(chain, album, [audio_item])
assert success and "未可靠匹配" in message
assert AudioMetadataHelper.read_tags(path).title == "本地标题"
def test_album_preservation_summary_is_logged(tmp_path, monkeypatch):
"""
手动调用不仅返回保留提示,也应在刮削日志中留下同样的信息。
"""
album = _album()
path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "missingOnly")
logger = Mock()
monkeypatch.setattr("app.chain.scraping.logger", logger)
success, message = _scrape(chain, album, [_item(path)])
assert success and "保留" in message
assert any("保留" in call.args[0] and "音乐标签" in call.args[0] for call in logger.info.call_args_list)
def test_album_lyrics_counts_and_track_preservation_are_both_reported(tmp_path, monkeypatch):
"""
歌词成功数量和专辑曲目保留提示必须同时返回,不能互相覆盖。
"""
album = _album()
path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, "missingOnly")
chain.scraping_policies = ScrapingConfig({
"music_nfo": "missingOnly", "music_poster": "skip", "music_lyrics": "upgrade",
})
chain._scrape_music_lyrics = Mock(return_value="saved")
monkeypatch.setattr("app.chain.scraping.LyricsChain", Mock(return_value=Mock()))
success, message = _scrape(chain, album, [_item(path)])
assert success and "保留已有曲名、艺人和曲序" in message
assert "歌词新增 1 首" in message
@pytest.mark.parametrize("policy,expected", [("missingOnly", "保留"), ("overwrite", "匹配 1")])
def test_music_album_http_response_reports_track_outcome(tmp_path, monkeypatch, policy, expected):
"""
真实管理权限路由必须把专辑曲目处理说明返回给 REST 调用方。
"""
album = _album()
path = _audio(tmp_path / "01.flac", "本地标题", "本地歌手", 1)
chain = _chain(monkeypatch, album, policy)
recognizer = Mock()
recognizer.return_value.recognize_media.return_value = album.to_music_info()
monkeypatch.setattr(media_endpoint, "MediaChain", recognizer)
monkeypatch.setattr(media_endpoint, "ScrapingChain", lambda: chain)
app = FastAPI()
app.include_router(media_endpoint.router, prefix="/api/v1/media")
app.dependency_overrides[get_current_active_user] = lambda: SimpleNamespace(
is_active=True, is_superuser=True, permissions={},
)
response = TestClient(app).post(
"/api/v1/media/scrape/local",
params={"media_source": "musicbrainz", "media_id": _GROUP, "type_name": "音乐", "music_type": "album"},
json=_item(path).model_dump(mode="json"),
)
assert response.status_code == 200
assert response.json()["success"] is True
assert expected in response.json()["message"]