sunoauxtool 1.6.0__py3-none-any.whl

sunoauxtool/__init__.py

@@ -0,0 +1,7 @@
+"""SmartNoteGen - 本地 AI 音乐生成 CLI。
+
+定位：程序化生成多轨 MIDI → 渲染 WAV → Suno 合规导出（10–30s 纯器乐），
+供用户上传 Suno Pro 合成成品。
+"""
+
+__version__ = "1.6.0"

sunoauxtool/__main__.py

@@ -0,0 +1,6 @@
+"""python -m sunoauxtool 入口。"""
+
+from sunoauxtool.cli import app
+
+if __name__ == "__main__":
+    app()

sunoauxtool/aggregate.py

@@ -0,0 +1,247 @@
+"""sunoaux：顶层聚合 CLI（前期 pre / 后期 post 的统一入口）。
+
+设计铁律（继承自重构计划 R3）：
+  - **薄转发层**：所有子命令直接二次注册既有命令函数（Typer 的 command
+    装饰器返回原函数，可安全挂到新 app 上），零参数复制、零业务逻辑；
+  - 核心层不得反向依赖 CLI 层——本模块只 import，不被 import；
+  - 旧入口 ``sunoauxtool`` / ``videomaker`` / ``downloadhelper`` 保留（兼容期 >= 1 个版本）。
+
+子命令结构：
+    sunoaux pre melody / midi / score / render / transcribe     （前期：创作）
+    sunoaux post probe / convert / fetch                        （后期：取回与转码）
+    sunoaux post video render / multi                           （后期：音乐视频）
+    sunoaux post dsp        （R6 已交付：DSP 算子链）
+    sunoaux post enhance    （AudioSR 音质提升，R5；依赖可选装）
+
+映射表（新 -> 旧）：
+    pre  melody      -> sunoauxtool generate melody
+    pre  midi        -> sunoauxtool generate midi
+    pre  score       -> sunoauxtool score
+    pre  render      -> sunoauxtool render
+    pre  transcribe  -> sunoauxtool transcribe
+    post probe       -> downloadhelper probe
+    post convert     -> downloadhelper decode
+    post fetch       -> downloadhelper batch
+    post video *     -> videomaker render / multi
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from sunoauxtool import __version__
+from sunoauxtool import cli as core_cli
+from sunoauxtool.ai.audiosr import AudioSRAdapter
+from sunoauxtool.commands.helpers import _guard
+from sunoauxtool.download import cli as download_cli
+from sunoauxtool.exceptions import InputFileError, ParameterError
+from sunoauxtool.video import cli as video_cli
+
+app = typer.Typer(
+    name="sunoaux",
+    help="SunoAuxTool 聚合入口：pre（前期创作）+ post（后期处理）",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"sunoaux {__version__}")
+        raise typer.Exit(0)
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        None, "--version", help="显示版本号", callback=_version_callback, is_eager=True
+    ),
+) -> None:
+    """sunoaux 聚合入口（薄转发层，业务逻辑在既有命令实现中）。"""
+
+
+# ---------------------------------------------------------------------------
+# pre：前期创作（映射 sunoauxtool 既有命令）
+# ---------------------------------------------------------------------------
+
+pre_app = typer.Typer(help="前期：旋律 / MIDI / 谱面 / 渲染 / 转谱", no_args_is_help=True)
+
+pre_app.command("melody", help="(= generate melody) 生成旋律 MIDI")(core_cli.generate_melody)
+pre_app.command("midi", help="(= generate midi) 程序化生成 MIDI")(core_cli.generate_midi)
+pre_app.command("score", help="(= score) 从 MIDI 生成谱面")(core_cli.score_cmd)
+pre_app.command("render", help="(= render) MIDI -> WAV 渲染")(core_cli.render_cmd)
+pre_app.command("transcribe", help="(= transcribe) WAV -> MIDI 转谱")(core_cli.transcribe_cmd)
+
+app.add_typer(pre_app, name="pre")
+
+
+# ---------------------------------------------------------------------------
+# post：后期处理（映射 downloadhelper / videomaker 既有命令）
+# ---------------------------------------------------------------------------
+
+post_app = typer.Typer(help="后期：取回 / 转码 / 视频 / DSP / 音质提升", no_args_is_help=True)
+
+post_app.command("probe", help="(= downloadhelper probe) 取证判定：明文 / 加密密文")(
+    download_cli.probe
+)
+post_app.command("convert", help="(= downloadhelper decode) fMP4 -> Opus/MP3 转码")(
+    download_cli.decode
+)
+post_app.command("convert-audio", help="(= downloadhelper convert) 音频互转 mp3/wav/m4a/flac")(
+    download_cli.convert
+)
+post_app.command("extract-audio", help="(= downloadhelper extract-audio) 视频分离音轨（直通优先）")(
+    download_cli.extract_audio
+)
+@post_app.command(
+    "fetch",
+    help="取回音频（R7）：catcatch=猫抓缓存扫描转码（默认）；suno-api/haimeng/tianyin=API 源",
+)
+@_guard
+def fetch_cmd(
+    query: str = typer.Argument(..., help="catcatch=缓存目录；API 源=歌曲/任务 ID"),
+    source: str = typer.Option(
+        "catcatch", "--source", "-s", help="源：catcatch | suno-api | haimeng | tianyin"
+    ),
+    out: Path = typer.Option(None, "-o", "--out", help="输出目录（catcatch 默认原目录；API 默认 ./fetched/<source>）"),
+    fmt: str = typer.Option("both", "--fmt", help="[catcatch] 输出格式: opus | mp3 | both"),
+    bitrate: str = typer.Option("192k", "--bitrate", help="[catcatch] MP3 码率"),
+    ffmpeg: Optional[str] = typer.Option(None, "--ffmpeg-path", help="[catcatch] ffmpeg 绝对路径"),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", help="[R11] 仅校验凭证/可用性：不实际取回；缺凭证报 25"
+    ),
+) -> None:
+    """统一取回入口（R7）：错误码 25=凭证缺失、26=请求失败；猫抓沿用 20-24。"""
+    if dry_run:
+        from sunoauxtool.download.sources.base import list_sources
+
+        valid = {s.name: s for s in list_sources()}
+        if source not in valid:
+            known = ", ".join(sorted(valid))
+            raise ParameterError(f"未知下载源: {source}（可用: {known}）", code=1)
+        typer.echo(f"🔎 dry-run（不取回）: {valid[source].check(query)}")
+        return
+
+    if source == "catcatch":
+        # 直通既有 batch 实现（能力零复制）
+        download_cli.batch(
+            directory=Path(query),
+            out=out,
+            fmt=fmt,
+            bitrate=bitrate,
+            ffmpeg=ffmpeg,
+        )
+        return
+
+    from sunoauxtool.download.sources.base import list_sources
+    from sunoauxtool.download.sources.catcatch import CatCatchSource
+
+    valid = {s.name: s for s in list_sources()}
+    if source not in valid:
+        known = ", ".join(sorted(valid))
+        raise ParameterError(f"未知下载源: {source}（可用: {known}）", code=1)
+
+    adapter = valid[source]
+    if isinstance(adapter, CatCatchSource):
+        adapter.fmt, adapter.bitrate, adapter.ffmpeg = fmt, bitrate, ffmpeg
+    target_out = out or Path("fetched") / source
+    files = adapter.fetch(query, target_out)
+    typer.echo(f"✅ 取回 {len(files)} 个文件（source={source}）:")
+    for f in files:
+        typer.echo(f"   {f.path}")
+
+
+@post_app.command(
+    "dsp",
+    help="DSP 算子链：norm/loudnorm/fade-in/fade-out/trim/resample/lowcut/compress/"
+         "expand/limiter/reverb/concat",
+)
+@_guard
+def dsp_cmd(
+    audio: str = typer.Argument(..., help="输入 WAV 路径"),
+    ops_spec: str = typer.Option(
+        ...,
+        "--ops",
+        help='算子串（逗号分隔），如 "norm -1, fade-in 0.5, trim 10-25, resample 32000"',
+    ),
+    output: Path = typer.Option(None, "-o", "--output", help="输出 WAV（默认 <输入>_dsp.wav）"),
+    bit_depth: int = typer.Option(16, "--bit-depth", help="输出位深：16 | 24"),
+) -> None:
+    """DSP 算子链（R6）：错误码 15=处理失败 / 16=参数错误。"""
+    from sunoauxtool.dsp.ops import OPS, apply_ops, parse_ops
+    from sunoauxtool.export import audio as audio_ops
+
+    src = Path(audio)
+    if not src.is_file():
+        raise InputFileError(f"输入音频不存在: {src}", code=3)
+    if bit_depth not in (16, 24):
+        raise ParameterError(f"bit_depth 只能是 16 或 24: {bit_depth}", code=16)
+
+    ops = parse_ops(ops_spec)
+    unknown = [op.name for op in ops if op.name not in OPS]
+    if unknown:
+        raise ParameterError(
+            f"未知算子: {', '.join(unknown)}（可用: {', '.join(sorted(OPS))}）", code=16
+        )
+
+    wave, sr = audio_ops.read_wav(src)
+    wave, sr = apply_ops(wave, sr, ops, base_dir=src.parent)
+
+    out = output or src.with_name(src.stem + "_dsp.wav")
+    written = audio_ops.write_wav(out, wave, sr, bit_depth=bit_depth)
+    typer.echo(f"✅ DSP 完成: {written}（{wave.shape[0] / sr:.2f}s @ {sr}Hz, {bit_depth}bit）")
+
+
+@post_app.command(
+    "enhance",
+    help="AudioSR 音质提升/超分（R5；长音频自动分块交叉淡化；未装依赖 exit 6）",
+)
+@_guard
+def enhance_cmd(
+    audio: str = typer.Argument(..., help="输入音频路径（WAV）"),
+    output: Path = typer.Option(None, "-o", "--output", help="输出 WAV（默认 <输入>_enhanced.wav）"),
+    model: str = typer.Option("basic", "--model", help="模型：basic（音乐/通用）| speech"),
+    seed: int = typer.Option(42, "--seed", help="随机种子"),
+    steps: int = typer.Option(50, "--steps", help="DDIM 步数（默认 50）"),
+    chunk: float = typer.Option(15.0, "--chunk", help="长音频分块秒数"),
+    overlap: float = typer.Option(2.0, "--overlap", help="分块重叠秒数"),
+) -> None:
+    """AudioSR 超分（R5）：输出单声道 48kHz WAV（上游管线行为）。"""
+    src = Path(audio)
+    if not src.is_file():
+        raise InputFileError(f"输入音频不存在: {src}", code=3)
+    out = output or src.with_name(src.stem + "_enhanced.wav")
+
+    adapter = AudioSRAdapter(
+        model_name=model,
+        seed=seed,
+        ddim_steps=steps,
+        chunk_duration_s=chunk,
+        overlap_duration_s=overlap,
+    )
+    if not adapter.is_available():
+        from sunoauxtool.exceptions import AiDependencyError
+
+        raise AiDependencyError(
+            "audiosr 不可用：未找到 AudioSR 源码目录"
+            "（设 AUDIOSR_DIR 或克隆到 src/versatile_audio_super_resolution，"
+            "依赖见 requirements/vasr.txt）",
+            code=6,
+        )
+
+    written = adapter.enhance(str(src), str(out))
+    typer.echo(f"✅ 音质提升完成: {written}")
+
+
+video_app = typer.Typer(help="音乐视频（sunoauxtool.video，原 videomaker）", no_args_is_help=True)
+video_app.command("render")(video_cli.render)
+video_app.command("multi")(video_cli.multi)
+video_app.command("presets")(video_cli.presets)
+video_app.command("config")(video_cli.config)
+video_app.command("version")(video_cli.version)
+post_app.add_typer(video_app, name="video")
+
+app.add_typer(post_app, name="post")

sunoauxtool/ai/__init__.py

@@ -0,0 +1,32 @@
+"""AI 适配器包（P1）。模块顶部零重型 import。"""
+
+from typing import Dict
+
+from sunoauxtool.ai.base import AIGenerator
+from sunoauxtool.ai.musicgen import MusicGenAdapter
+from sunoauxtool.ai.diffrhythm import DiffRhythmAdapter
+from sunoauxtool.ai.basicpitch import BasicPitchAdapter
+
+def discover_ai_backends() -> Dict[str, type]:
+    """AI 后端注册表 ``{name: AIGenerator 子类}`` = 内置 + entry point 插件。
+
+    扩展点：``sunoauxtool.ai_backends``（见 :mod:`sunoauxtool.plugins`）。
+    ``basic-pitch`` 是**转谱**后端（不走 generate），见
+    :func:`sunoauxtool.analysis.discover_transcribe_backends`。
+    """
+    from sunoauxtool.plugins import discover
+
+    builtins: Dict[str, type] = {
+        "musicgen": MusicGenAdapter,
+        "diffrhythm": DiffRhythmAdapter,
+    }
+    return discover("ai_backends", builtins, base=AIGenerator, instantiate=False)
+
+
+__all__ = [
+    "AIGenerator",
+    "MusicGenAdapter",
+    "DiffRhythmAdapter",
+    "BasicPitchAdapter",
+    "discover_ai_backends",
+]

sunoauxtool/ai/audiosr.py

@@ -0,0 +1,174 @@
+"""AudioSR（VASR）音质提升适配器（R5）。
+
+能力：音频超分 / 高频重建（**不是人声分离**——人声分离另行选型）。
+上游：haoheliu/versatile_audio_super_resolution（AudioSR）本地克隆 @ d312fba，
+源码位于 ``src/versatile_audio_super_resolution``（自带内嵌 .git，R5 入库时清理）。
+
+设计要点：
+- **零顶层重依赖**：本模块顶层只 import 标准库；audiosr/torch 全部在推理时
+  延迟导入（CI 零 torch 断言不受影响，未装依赖不影响主包任何功能）。
+- **可选装目录模式**（与 diffrhythm 同构）：目录定位顺序
+  环境变量 ``AUDIOSR_DIR`` > 默认 ``<repo>/src/versatile_audio_super_resolution``。
+- 长音频走上游 ``super_resolution_long_audio``：15s 分块 / 2s 重叠 Hann 交叉淡化
+  / 块级峰值还原 / overlap-add 归一化（2026-09-21 实测 32s 冒烟：时长精确对齐）。
+- 输出：**单声道 48kHz** WAV（上游管线内部将立体声混为单声道；这是上游行为，
+  保留立体声需改上游，暂不做）。
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+from sunoauxtool.exceptions import AiDependencyError, InputFileError
+
+_INSTALL_GUIDE = (
+    "audiosr 不可用：未找到 AudioSR 源码目录。\n"
+    "方式一：克隆上游仓库到 src/versatile_audio_super_resolution（默认探测路径）\n"
+    "  git clone https://github.com/haoheliu/versatile_audio_super_resolution\n"
+    "方式二：设环境变量 AUDIOSR_DIR 指向任意 audiosr 源码目录\n"
+    "依赖（torch/torchaudio 等）见 requirements/vasr.txt；首次运行自动下载约 2.6GB 权重。\n"
+    "网络：直连 huggingface.co 不通时设 HF_ENDPOINT=https://hf-mirror.com（国内镜像）。"
+)
+
+_DEFAULT_DIR = Path(__file__).resolve().parents[2] / "versatile_audio_super_resolution"
+
+
+def resolve_audiosr_dir() -> Optional[Path]:
+    """定位 audiosr 源码目录；找不到返回 None。"""
+    env = os.environ.get("AUDIOSR_DIR")
+    cand = Path(env) if env else _DEFAULT_DIR
+    return cand if (cand / "audiosr").is_dir() else None
+
+
+def _ensure_importable() -> None:
+    """把 audiosr 源码目录挂到 sys.path（幂等），失败抛 AiDependencyError。"""
+    d = resolve_audiosr_dir()
+    if d is None:
+        raise AiDependencyError(_INSTALL_GUIDE, code=6)
+    d_str = str(d)
+    if d_str not in sys.path:
+        sys.path.insert(0, d_str)
+
+
+class AudioSRAdapter:
+    """AudioSR 超分适配器（可选 AI 后端，R5）。
+
+    用法::
+
+        adapter = AudioSRAdapter()
+        if adapter.is_available():
+            adapter.enhance("in.wav", "out.wav")
+    """
+
+    def __init__(
+        self,
+        model_name: str = "basic",
+        device: Optional[str] = None,
+        seed: int = 42,
+        ddim_steps: int = 50,
+        guidance_scale: float = 3.5,
+        chunk_duration_s: float = 15.0,
+        overlap_duration_s: float = 2.0,
+    ) -> None:
+        """初始化（不触发模型加载）。
+
+        Args:
+            model_name: ``basic``（音乐/通用）或 ``speech``。
+            device: ``cuda`` / ``cpu``；None 自动选（有 CUDA 用 CUDA）。
+            ddim_steps: DDIM 采样步数（默认 50，R0 实测 50 步质量/耗时均衡）。
+            chunk_duration_s / overlap_duration_s: 长音频分块参数（须 chunk > overlap）。
+        """
+        if chunk_duration_s <= overlap_duration_s:
+            raise ValueError("chunk_duration_s 必须大于 overlap_duration_s")
+        self.model_name = model_name
+        self.device = device
+        self.seed = seed
+        self.ddim_steps = ddim_steps
+        self.guidance_scale = guidance_scale
+        self.chunk_duration_s = chunk_duration_s
+        self.overlap_duration_s = overlap_duration_s
+        self._model = None  # 惰性加载
+
+    # -- 可用性 ------------------------------------------------------------
+
+    def is_available(self) -> bool:
+        """audiosr 源码目录是否就位（不触发实际 import，轻量检查）。"""
+        return resolve_audiosr_dir() is not None
+
+    def _load_model(self):
+        """惰性加载 AudioSR 模型（权重缺失/下载失败转 AiDependencyError）。"""
+        if self._model is None:
+            _ensure_importable()
+            try:
+                import torch
+
+                import audiosr
+
+                if self.device is not None:
+                    device = self.device
+                else:
+                    device = "cuda" if torch.cuda.is_available() else "cpu"
+                self._model = audiosr.build_model(
+                    model_name=self.model_name, device=device
+                )
+            except AiDependencyError:
+                raise
+            except Exception as exc:
+                raise AiDependencyError(
+                    f"AudioSR 模型加载失败（权重下载/损坏？依赖缺失？）: {exc}", code=6
+                ) from exc
+        return self._model
+
+    # -- 推理 --------------------------------------------------------------
+
+    def enhance(self, input_path: str, output_path: str) -> str:
+        """对整段音频做超分增强，写 48kHz PCM_24 WAV，返回输出路径。
+
+        长音频自动分块（``super_resolution_long_audio``）；输出为
+        **单声道 48kHz**（上游行为）。
+
+        Raises:
+            InputFileError: 输入文件不存在（退出码 3）。
+            AiDependencyError: 依赖/模型不可用（退出码 6）。
+        """
+        src = Path(input_path)
+        if not src.is_file():
+            raise InputFileError(f"输入音频不存在: {src}", code=3)
+
+        import soundfile as sf
+
+        model = self._load_model()
+        try:
+            import audiosr
+
+            wave = audiosr.super_resolution_long_audio(
+                model,
+                str(src),
+                seed=int(self.seed),
+                ddim_steps=int(self.ddim_steps),
+                guidance_scale=float(self.guidance_scale),
+                chunk_duration_s=float(self.chunk_duration_s),
+                overlap_duration_s=float(self.overlap_duration_s),
+            )
+        except AiDependencyError:
+            raise
+        except Exception as exc:
+            hint = ""
+            # huggingface.co 直连不通（本机被墙）时给出镜像指引；
+            # 否则用户只会看到一串 ConnectTimeout，不知道怎么修。
+            if "huggingface.co" in str(exc) or "timed out" in str(exc):
+                hint = (
+                    "；网络提示：直连 huggingface.co 超时，"
+                    "设 HF_ENDPOINT=https://hf-mirror.com 走国内镜像；"
+                    "权重已缓存后可加 HF_HUB_OFFLINE=1 跳过联网校验"
+                )
+            raise AiDependencyError(f"AudioSR 推理失败: {exc}{hint}", code=6) from exc
+
+        out = Path(output_path)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        # wave: torch [1(ch), N] 48kHz -> numpy (N, 1)
+        sf.write(str(out), wave.squeeze(0).numpy().T, 48000, subtype="PCM_24")
+        return str(out)

sunoauxtool/ai/base.py

@@ -0,0 +1,28 @@
+"""P1 AI 适配器抽象接口。
+
+隔离原则（架构 §5.1）：
+- 本包所有重型 import 均发生在函数体内（延迟导入），模块顶部零 torch/audiocraft/diffrhythm
+- AIGenerator 只暴露 generate(source_wav, prompt) -> str（输入输出均为文件路径）
+- P0 管线完全不感知 AI 内部实现
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+
+class AIGenerator(ABC):
+    """AI 生成器抽象接口（P1）。
+
+    generate 输入/输出均为音频文件路径字符串。
+    """
+
+    @abstractmethod
+    def generate(self, source_wav: str, prompt: str, **kw) -> str:
+        """基于输入音频与提示词生成新音频，返回输出文件路径。"""
+        raise NotImplementedError
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """当前环境是否可用（依赖已安装 / 显存满足）。"""
+        raise NotImplementedError

sunoauxtool/ai/basicpitch.py

@@ -0,0 +1,151 @@
+"""Basic Pitch 适配器（#13 预留，多音轨复调转谱的可选 AI 后端）。
+
+定位
+--------
+内置转谱（``analysis/transcribe.py``）只做单旋律/主导声部；多音轨复调（钢琴和弦、
+多乐器混音）是研究级问题，交给 Spotify 的 basic-pitch（轻量 NMP 模型，CPU 可跑）。
+
+隔离原则（与 ai/musicgen.py 同一模式）：
+- 模块顶部零 basic_pitch/torch import；``is_available()`` 用 ``find_spec`` 探测（不触发实际 import）
+- 依赖未装 → ``AiDependencyError``（退出码 6），带安装指引
+- basic-pitch **不在 base.txt**：走 requirements/ai.txt 可选装（见该文件「可选转谱后端」段）
+- 首次运行 ``ICModel()`` 会自动下载约 100MB 权重到用户缓存目录
+
+真实推理已实测（2026-09-22）
+--------------------------------
+在隔离环境 **Python 3.9 + basic-pitch 0.4.0（onnxruntime 后端）** 实跑通过，
+据此修正了三处与真实 API 不符的写法：
+
+1. **``ICModel`` 不存在**：``from basic_pitch import ICModel`` → ImportError
+   （0.4.0 顶层只有常量与子模块）。0.4.x 无需手动实例化模型，
+   ``predict()`` 第二参默认就是随包安装的 ``saved_models/icassp_2022/nmp.onnx``。
+2. **参数顺序是 ``(audio, model)`` 而非 ``(model, audio)``**：
+   ``predict(audio_path, model_or_model_path=..., onset_threshold=0.5, ...)``。
+3. **顺序写错抛的是 ``ValueError`` 不是 ``TypeError``**（模型路径被当音频去加载），
+   因此历史写法里的 ``except TypeError`` 兜不住，必须一开始就用对顺序。
+
+返回值为三元组 ``(model_output: dict, midi_data: PrettyMIDI, note_events: list)``，
+``midi_data`` 有 ``.write(path)``。实测 3 秒复调音频（C-E-G 和弦 → A-C）识别出 5 个音符。
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from pathlib import Path
+from typing import Optional
+
+from sunoauxtool.ai.base import AIGenerator
+from sunoauxtool.exceptions import AiDependencyError, InputFileError
+
+_INSTALL_GUIDE = (
+    "basic-pitch 不可用：未安装可选转谱依赖。\n"
+    "请安装: pip install basic-pitch（首次运行会自动下载约 100MB 权重）\n"
+    "或继续使用内置单旋律转谱：transcribe --backend builtin"
+)
+
+
+class BasicPitchAdapter(AIGenerator):
+    """basic-pitch 复调转谱适配器（可选 AI 后端，#13 预留）。"""
+
+    def __init__(
+        self,
+        device: str = "cpu",
+        model_path: Optional[str] = None,
+    ) -> None:
+        """初始化。
+
+        Args:
+            device: 推理设备（basic-pitch 主要面向 CPU，GPU 传 "cuda" 由其自行处理）。
+            model_path: 显式权重路径；None 用默认权重（首次运行自动下载）。
+        """
+        self.device = device
+        self.model_path = model_path
+
+    # -- 可用性 ------------------------------------------------------------
+
+    def is_available(self) -> bool:
+        """检查 basic_pitch 是否已安装（find_spec 不触发实际 import）。"""
+        return importlib.util.find_spec("basic_pitch") is not None
+
+    def _resolve_model_path(self) -> Optional[str]:
+        """解析模型路径（不实际实例化模型，0.4.x predict 内部自行加载）。"""
+        if self.model_path:
+            p = Path(self.model_path).expanduser().resolve()
+            if not p.is_file():
+                raise AiDependencyError(
+                    f"basic-pitch 模型路径不存在: {p}", code=6
+                ) from None
+            return str(p)
+        return None  # None 表示使用 predict 内置默认模型路径
+
+    # -- 推理 --------------------------------------------------------------
+
+    def transcribe(
+        self,
+        source_wav: str,
+        output_path: Optional[str] = None,
+        **_kw,
+    ) -> str:
+        """把音频转成多音轨 MIDI 文件。
+
+        Args:
+            source_wav: 输入音频路径。
+            output_path: 输出 .mid 路径；None 时 ``<stem>_basicpitch.mid`` 落在输入旁。
+
+        Returns:
+            输出 .mid 绝对路径字符串。
+
+        Raises:
+            AiDependencyError: 依赖未装或模型加载失败（退出码 6）。
+            InputFileError: 输入文件不存在（退出码 3）。
+        """
+        if not self.is_available():
+            raise AiDependencyError(_INSTALL_GUIDE, code=6)
+
+        src = Path(source_wav).expanduser().resolve()
+        if not src.is_file():
+            raise InputFileError(f"音频文件不存在: {src}", code=3)
+
+        # 延迟导入（P0 模块零重型 import 约束）
+        # 0.4.x 签名：predict(audio, model=...) -> (model_output, midi_data, note_events)。
+        # 实测官方顺序，此处直接使用；保留关键字序兜底兼容历史版本。
+        #
+        # 注意：basic_pitch/__init__.py 的后端选择链 if/elif **没有 else 分支**，
+        # 四个后端（tf/coreml/tflite/onnx）一个都没装时会在模块级抛
+        # `NameError: _default_model_type is not defined`。这种「装了包但没装后端」
+        # 的状态必须报成退出码 6 并给出可操作的指引，而不是漏成退出码 1 的 NameError。
+        try:
+            from basic_pitch.inference import predict
+        except Exception as exc:  # pragma: no cover - 依赖真实环境
+            raise AiDependencyError(
+                f"basic-pitch 已安装但导入失败（多半是没装推理后端）：{exc}。"
+                f"Windows/onnx 路线请执行 `pip install onnxruntime`；"
+                f"也可用 `pip install 'basic-pitch[tf]'` 走 TensorFlow 后端。",
+                code=6,
+            ) from exc
+
+        model = self._resolve_model_path()
+        try:
+            output = predict(str(src), model) if model is not None else predict(str(src))
+        except (TypeError, ValueError):
+            kw = {"audio": str(src)}
+            if model is not None:
+                kw["model"] = model
+            output = predict(**kw)
+
+        # 0.4.x 返回三元组 (dict, PrettyMIDI, list)，不用 getattr 裸三元组兼容
+        midi_data = output[1]
+
+        out = (
+            Path(output_path).expanduser().resolve()
+            if output_path
+            else src.with_name(f"{src.stem}_basicpitch.mid")
+        )
+        out.parent.mkdir(parents=True, exist_ok=True)
+        midi_data.write(str(out))
+        return str(out)
+
+    # AIGenerator 接口适配：basic-pitch 是转谱不是生成，映射为「输入音频 → 输出 MIDI」
+    def generate(self, source_wav: str, prompt: str = "", **kw) -> str:
+        """AIGenerator 接口兼容：prompt 忽略，行为同 :meth:`transcribe`。"""
+        return self.transcribe(source_wav, **kw)