yuwancumian2009/tunescout-v2

🎵 TuneScout - 智能音乐库管理与下载助手

TuneScout 是一个专为 NAS 和家庭媒体服务器（如 Navidrome, Jellyfin, Plex）设计的全能音乐管理工具。它集成了多平台音乐下载、元数据自动刮削、目录智能整理以及歌单同步功能，旨在打造一个整洁、高品质的本地音乐库。

!https://img.shields.io/docker/v/%E4%BD%A0%E7%9A%84Docker%E7%94%A8%E6%88%B7%E5%90%8D/tunescout-v2?label=Docker%20Image !https://img.shields.io/badge/platform-linux%2Famd64%20%7C%20linux%2Farm64-blue

✨ 核心功能

1. 全网聚合下载 (Multi-Source Downloader)

支持从多个主流音乐平台搜索并下载高品质音乐，支持自定义源优先级。

• 支持平台：网易云音乐、QQ 音乐、酷我音乐、Bilibili、***。
• 智能策略：
  • 无损优先：自动尝试下载 FLAC / Hi-Res 音质，失败则降级到 320k MP3。
  • Fallback 机制：当前源下载失败时，自动按照你设置的优先级尝试下一个源。
• 高级支持：
  • 支持 HTTP 代理（解决 ***/Wiki 访问问题）。
  • 支持 Cookie 注入（解决 VIP 歌曲下载、*** "Sign in" 验证问题）。

2. 歌单同步 (Playlist Sync)

一键将云端歌单同步到本地。

• 输入歌单 ID 或链接，自动抓取歌单内所有歌曲。
• 自动生成 .m3u8 歌单文件，完美适配 Navidrome 等流媒体服务。
• 智能去重：本地已存在的歌曲通过哈希/指纹匹配，不再重复下载。

3. 智能库整理 (Smart Organizer)

告别杂乱的文件名，让文件结构井井有条。

• 自动归档：将歌曲移动到 /Artist/Album/Song.ext 结构中。
• 合集/散曲处理：
  • 预览模式：在执行移动前，先生成变动日志预览，防止误操作。
  • 智能归类：自动将少量散曲整理到 合集1、合集2 等目录，防止根目录爆炸。
  • 多人合作提取：自动识别文件名中的 feat., vs, &，将其从合集中提取到 合作 目录，或强制标记 Album Artist 为“群星”。
• 空目录清理：整理或删除歌曲后，自动递归清理残留的空文件夹。

4. 元数据刮削 (Metadata Scraper)

• 自动补全：下载时自动写入 ID3 标签（标题、歌手、专辑、封面）。
• 批量刮削：支持对本地现有歌曲进行批量扫描，补全缺失的封面 (Cover) 和歌词 (Lyrics)。
• AI 辅助：集成 Google Gemini / OpenAI，智能分析文件名，提取准确的元数据信息。

5. 任务管理与可视化

• 后台异步任务：下载、整理、刮削等耗时操作全部在后台运行，不阻塞界面。
• 实时进度：通过 SQLite 任务队列，实时查看每个任务的进度条和日志。
• Web UI：基于 Vue3 + Naive UI 的现代化管理界面，响应式设计，操作丝滑。

🚀 部署指南 (Docker Compose)

本项目支持 x86 (amd64) 和 ARM (arm64) 架构，完美运行于各类 NAS（群晖、威联通、极空间）及树莓派。

1. 创建 docker-compose.yml

yaml
version: '3.8'
services:
  tunescout:
    image: yuwancumian2009/tunescout-v2:latest
    container_name: tunescout
    restart: unless-stopped
    ports:
      - "8503:8503"
    volumes:
      # 音乐库目录 (Navidrome 读取的目录)
      - /path/to/your/music:/music
      # 下载暂存目录
      - /path/to/your/download:/download
      # 歌单文件输出目录
      - /path/to/your/playlists:/playlists
      # 配置文件与数据库存储
      - ./config.json:/app/config.json
      - ./library_cache.db:/app/library_cache.db  #需自行在该位置创建同名空文件后构建镜像
      # (可选) 如果需要控制其他容器(如重启Navidrome)，需挂载 docker.sock
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - TZ=Asia/Shanghai

2. 访问 [***] 即可进入管理界面。

⚙️ 配置说明

在 Web 界面的 “系统设置” 中，你可以配置：

• 路径映射：对应 Docker 内部的路径（如 /music, /download）。
• 网络与账号：
  • 代理设置：填写 http://192.168.x.x:7890 以加速 *** 下载。
  • Cookie：填入网易云、QQ 音乐、B站的 Cookie 以获取高音质/VIP 资源；填入 *** Cookie (Netscape 格式) 以解决验证码问题。
• 下载源优先级：拖拽排序，决定优先从哪个平台搜索资源。
• 整理策略：
  • 是否开启“多人合作转群星”。
  • 设置专辑归档逻辑。