MoviePilot V3 是独立的主版本，重点是继续复用电影、电视剧的自动化流程，同时把音乐作为并列媒体类型接入搜索、下载、订阅和整理。
V3 兼容 V2 的配置和数据库数据，未使用变更合同的 V2 插件也可直接复用，不需要执行用户数据迁移。此兼容方向是 V2 数据库向前升级到 V3；V3 首次启动并完成数据库升级后，如需回到 V2，必须先按 从 V3 降级回 V2 恢复 V2 所需字段。涉及媒体身份、音乐链或宿主 REST API 等新合同的插件，需要按插件仓库的 V2 插件迁移到 V3 建立 V3 专用实现。V2 容器不能通过内建的重启升级直接跨主版本升级到 V3，需要拉取 V3 最新镜像并重建容器。V1 版本无法兼容升级，需要重新配置安装。
V3 不以内置音乐媒体库为目标。音乐的播放、歌单、歌手库和文件索引继续交由 Navidrome、Emby、Jellyfin、Plex 等现成媒体软件负责；MoviePilot 负责把音乐资源找到、下载并整理到指定目录。
V3 全新安装时，启动过程不会把超级管理员用户名、密码或 API Key 写入数据库，也不会在日志中输出初始密码。首次打开 Web 地址时，如果数据库中还没有用户，系统会自动跳转到初始化页面。
在初始化页面完成以下操作：
初始化接口只允许在实例尚未创建任何用户时执行；如果从 V2 升级到 V3 时数据库中已经存在用户，则不会进入初始化页面，原有用户数据继续保留。V1、V2 的管理员和密码配置方式保持不变。
V3 Docker 全新安装模板不再需要填写 SUPERUSER、SUPERUSER_PASSWORD 或 API_TOKEN，这些值由初始化页面在保存时写入运行时配置。
/config 配置目录和 SQLite/PostgreSQL 数据库；未使用 V3 变更合同的已安装插件也可直接复用，无需迁移用户数据。V3 完成数据库升级后不能直接换回 V2 镜像，降级前需要恢复 V2 字段，因此切换前必须保留完整备份。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 等常见格式写入内嵌发行封面。远端存储复用现有下载、修改和覆盖上传流程。
歌词使用独立刮削策略，默认“质量升级”。整理时会迁移同名 .lrc、.txt 和 .lyricsfile.yaml，刮削时优先读取已有旁挂和音频内嵌歌词，再查询插件、LRCLIB 和 AMLL TTML，最后使用 TheAudioDB 纯文本兜底。逐字 Lyricsfile、逐行同步歌词、纯文本按质量依次降低，系统不会用低质量结果覆盖高质量歌词。Lyricsfile 会原样保留，并同时生成播放器兼容的 .lrc。
在 设定 -> 系统 -> 高级设置 -> 媒体 可修改 LRCLIB 地址、AMLL TTML 地址、歌词批次预算和来源重试等待。AMLL 默认使用无需 API Key 的公共服务，优先按 ISRC 查询，再匹配歌曲和艺术家；TTML 主唱的逐词或逐行时间轴会转换为 Lyricsfile 和 LRC，缺少完整行时间时只保存纯文本，翻译、音译和背景人声不会混入主句。额外歌词来源可由插件匹配并下载，主程序统一选择合适内容并写入歌词文件，接入方式见歌词插件开发说明。
接口使用者可参考以下 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 是否有效，以及该站点的音乐分类是否仍在站点页面中存在。