MoviePilot V3 是独立的主版本，重点是继续复用电影、电视剧的自动化流程，同时把音乐作为并列媒体类型接入搜索、下载、订阅和整理。
V3 兼容 V2 的配置、数据库数据以及全部插件，可直接继续使用原有数据，不需要执行数据迁移。但 V2 容器不能通过内建的重启升级直接跨主版本升级到 V3，需要拉取 V3 最新镜像并重建容器。V1 版本无法兼容升级，需要重新配置安装。
V3 不以内置音乐媒体库为目标。音乐的播放、歌单、歌手库和文件索引继续交由 Navidrome、Emby、Jellyfin、Plex 等现成媒体软件负责；MoviePilot 负责把音乐资源找到、下载并整理到指定目录。
/config 配置目录、SQLite/PostgreSQL 数据库和已安装插件，无需迁移数据；切换前仍建议先完整备份。jxxghp/moviepilot-v3:latest，拉取最新镜像后重建容器，不要只重启原 V2 容器。resources.v3，站点包文件名为 user.sites.v3.bin，索引版本为 3.0.0。v3 分支构建，版本标签统一使用 v3.x。jxxghp/moviepilot-v3，正式版发布版本号标签（例如 3.0.0）和 latest；Beta 使用 beta 标签。ghcr.io/jxxghp/moviepilot-v3。latest 标签也会指向最新 V3 镜像；已部署容器仍需要重新拉取镜像并重建，仅重启不会替换本地镜像。MoviePilot-Resources 的 v3/resources.v3/，运行时自动更新也只筛选 v3.* 后端和前端发布版本。MoviePilot-Build 生成的站点索引和编译扩展通过面向 MoviePilot-Resources/v3 的 PR 发布，避免覆盖 V2 资源。| 媒体类型 | 主要能力 |
|---|---|
| 电影 | 元数据搜索、站点资源搜索、下载、订阅、整理 |
| 电视剧 | 元数据搜索、站点资源搜索、下载、订阅、追更和整理 |
| 音乐 | 歌曲/专辑/艺术家搜索、音乐资源搜索、下载、订阅和音频文件整理 |
音乐会沿用现有的搜索、下载、订阅、历史和通知链路，不另起一套下载器或任务队列。
搜索歌曲、专辑或艺术家
↓
选择音乐元数据
↓
搜索站点音乐资源
↓
选择资源并提交下载，或创建音乐订阅
↓
下载完成后识别音频标签和技术参数
↓
按音乐重命名格式整理到目标目录
↓
由现有媒体服务器负责扫描和播放
V3 当前通过 Python 模块完成音乐专用识别：
MusicMeta：统一歌曲、专辑、艺术家、曲序、碟号、年份、ISRC、音频格式等解析结果。MusicBrainzModule：搜索录音、读取详情、补全发行和艺术家信息。AudioMetadataHelper：读取本地音频标签和采样率、位深、码率、时长等技术参数，并在音乐刮削时写回标准标签和内嵌封面。ListenBrainzModule：提供推荐和探索榜单，不承担本地音乐库管理。目前 Rust 扩展并没有音乐专用识别实现。Rust 已支持通用 MetaInfo 解析、站点索引解析、资源过滤以及音乐分类映射；音乐字段识别和音频标签读取仍由 Python 侧完成。后续如需 Rust 化，应以兼容 MusicMeta 字段和 Python 回退路径为前提单独设计。
音乐站点分为两类：
搜索音乐资源时，MoviePilot 会根据 V3 索引中的 music 分类选择对应分支；没有音乐专用搜索路径时，会复用站点的通用搜索路径。站点是否为“音乐站点”不再作为唯一判断条件。
站点 Cookie 配置方式与影视站点一致，详见 站点。
音乐整理使用 设定 -> 目录 中独立的音乐重命名格式，默认结构为：
艺术家/专辑 (年份)/曲序 - 歌曲.扩展名
格式可使用 artist、album_artist、album、title、track、disc、year、fileExt 等音乐字段。MoviePilot 只负责下载后识别和整理，不提供音乐播放、歌单同步或内置音乐库。
文件管理中的“识别”会按音频扩展名进入音乐识别链，优先读取文件标签并使用 MusicBrainz 补全标准录音信息。手动刮削选择“音乐”后可按 MusicBrainz Recording UUID 指定目标，也可留空按每个音频文件自动识别；刮削会写回歌曲、艺术家、专辑、专辑艺术家、年份、曲序、碟号、ISRC，并为 MP3、FLAC、MP4/M4A 等常见格式写入内嵌发行封面。远端存储复用现有下载、修改和覆盖上传流程。
接口使用者可参考以下 V3 API：
| 接口 | 用途 |
|---|---|
GET /api/v1/music/search |
搜索音乐元数据 |
POST /api/v1/music/recognize |
根据来源和媒体 ID 获取音乐详情 |
GET /api/v1/music/explore |
按周期、热度和封面条件浏览热门音乐 |
GET /api/v1/recommend/music_weekly |
浏览本周推荐音乐 |
resources.v3。设定 -> 关于 检查站点资源版本，确认已加载 user.sites.v3.bin。FLAC 或具体艺术家，确认搜索结果分类为“音乐”。如果站点可以访问但结果被归类为“未知”，优先检查站点资源是否为 V3、站点 Cookie 是否有效，以及该站点的音乐分类是否仍在站点页面中存在。