rickysynnot/magic-lists-for-navidrome

MagicLists for Navidrome**为您的个人音乐库提供AI辅助播放列表。**MagicLists为您带来Spotify或Apple Music式的精选动态播放列表——但完全在您自托管的Navidrome服务器上运行。无需订阅，无需为已拥有的音乐付费。只需从您已有的音乐库中生成智能混音。

核心功能

• 🎵 艺术家精选（This Is Artist） — 为库中任何艺术家创建权威播放列表，融合热门歌曲、 deep cuts 和合作曲目，确保无重复。
• 🎸 风格混音（Genre Mix） — 围绕特定音乐风格打造智能播放列表。
• 🔄 重新发现（Re-Discover） — 轮换久未播放的曲目，助您重拾对音乐收藏的热爱。
• 📚 多库支持 — 通过直观界面选择单个或多个Navidrome音乐库。
• ⏰ 自动刷新 — 按日、周或月更新播放列表，保持新鲜感。
• 🐳 跨平台 — 支持Intel和Apple Silicon Mac（多架构Docker镜像）。
• 🐳 快速设置 — 简单Docker安装，几分钟即可开始使用。

价值所在

Navidrome用户已拥有自己的音乐。MagicLists将现代推荐工具带入这一领域——让您的播放列表充满活力而非静止，让您的音乐收藏不断带来惊喜。

开发背景

我是Ricky，一名拥有20多年技术经验的产品设计师。我正在逐步构建MagicLists的每一个功能，从UI、CSS到播放列表逻辑，因为我热衷于开源、注重隐私的音乐工具。这不是 vaporware 或一次性实验——而是关于AI如何丰富个人音乐库的持续研究。

未来计划

即将推出的功能实验包括：

• 多艺术家"电台"融合
• 年代和探索主题列表
• 创意旅程类播放列表，如"回家漫漫长路"（曲目间的声音路径）和"风格考古"（追溯音乐风格的历史影响）。

MagicLists才刚刚起步，期待您在其成长过程中提供反馈。

安装

推荐：添加到现有Docker Compose**为何选择此方法？**您的MagicLists容器将与Navidrome位于同一网络，连接简单可靠。这也支持未来需要本地文件访问的功能（如音频分析）。

1.** 将MagicLists添加到现有docker-compose.yml**（运行Navidrome的配置文件）：

yaml
   services:
     navidrome:
       # ... 您现有的Navidrome配置 ...
     
     magiclists:
       image: rickysynnot/magic-lists-for-navidrome:latest
       container_name: magiclists
       ports:
         - "4545:8000"
       environment:
         - NAVIDROME_URL=http://navidrome:4533
         - NAVIDROME_USERNAME=您的用户名
         - NAVIDROME_PASSWORD=您的密码
         - DATABASE_PATH=/app/data/magiclists.db  # 可选：自定义数据库位置
         - AI_PROVIDER=openai  # 可选值：openai、anthropic或ollama
         - OPENAI_API_KEY=您的OpenAI API密钥
         - ANTHROPIC_API_KEY=您的Anthropic API密钥  # OpenAI的替代方案
         - OLLAMA_URL=http://host.docker.internal:11434  # 如使用Ollama
       volumes:
         - ./magiclists-data:/app/data          # 持久化配置和数据库
       restart: unless-stopped

2. 更新环境变量，填入您的Navidrome凭据和AI提供商信息
3. 启动服务栈：

bash
   docker-compose up -d

4. 通过 http://localhost:4545 访问MagicLists

注意：NAVIDROME_URL使用容器名称（navidrome）作为主机名。如果您的Navidrome服务在compose文件中使用不同名称，请相应更新。

替代方案：独立Docker容器

如果无法或不想修改现有Docker Compose配置，可使用此方法。** Navidrome可公开访问时：使用您的公开Navidrome URL（例如[*]

bash
   docker run -d \
      --name magiclists \
      -p 4545:8000 \
      -e NAVIDROME_URL=https://music.yourdomain.com \
      -e NAVIDROME_USERNAME=您的用户名 \
      -e NAVIDROME_PASSWORD=您的密码 \
      -e DATABASE_PATH=/app/data/magiclists.db \
      -e AI_PROVIDER=openai \
      -e OPENAI_API_KEY=您的OpenAI API密钥 \
      -v ./magiclists-data:/app/data \
      rickysynnot/magic-lists-for-navidrome:latest
```** Navidrome在同一主机时：**使用host.docker.internal访问主机上的服务：
```bash
   docker run -d \
      --name magiclists \
      -p 4545:8000 \
      -e NAVIDROME_URL=http://host.docker.internal:4533 \
      -e NAVIDROME_USERNAME=您的用户名 \
      -e NAVIDROME_PASSWORD=您的密码 \
      -e DATABASE_PATH=/app/data/magiclists.db \
      -e AI_PROVIDER=openai \
      -e OPENAI_API_KEY=您的OpenAI API密钥 \
      -v ./magiclists-data:/app/data \
      rickysynnot/magic-lists-for-navidrome:latest
```** Navidrome在本地网络时：**使用运行Navidrome的机器的本地IP地址：
```bash
   docker run -d \
      --name magiclists \
      -p 4545:8000 \
      -e NAVIDROME_URL=http://192.168.1.100:4533 \
      -e NAVIDROME_USERNAME=您的用户名 \
      -e NAVIDROME_PASSWORD=您的密码 \
      -e DATABASE_PATH=/app/data/magiclists.db \
      -e AI_PROVIDER=openai \
      -e OPENAI_API_KEY=您的OpenAI API密钥 \
      -v ./magiclists-data:/app/data \
      rickysynnot/magic-lists-for-navidrome:latest

通过 http://localhost:4545 访问MagicLists

更多详情请参见GitHub仓库：https://github.com/rsynnot/magic-lists-for-navidrome

环境变量

必填

• NAVIDROME_URL - Navidrome服务器URL
• NAVIDROME_USERNAME - Navidrome用户名
• NAVIDROME_PASSWORD - Navidrome密码

可选

• NAVIDROME_API_KEY - 用于身份验证的API密钥（用户名/密码的替代方案）
• NAVIDROME_LIBRARY_ID - 特定库ID（如果有多个库）
• DATABASE_PATH - 自定义数据库位置（默认：/app/data/magiclists.db）
• AI_PROVIDER - AI提供商：openai、anthropic或ollama
• OPENAI_API_KEY - OpenAI API密钥
• ANTHROPIC_API_KEY - Anthropic API密钥
• OLLAMA_URL - Ollama服务器URL（默认：http://localhost:***%EF%BC%89

连接问题排查

无法连接到Navidrome？最常见问题是NAVIDROME_URL设置不正确。以下是确定正确值的方法：

• 同一Docker网络：使用容器名称（例如[***]

• 同一主机：使用[] Desktop）或[]

• 局域网内其他机器：使用本地IP（例如[***]

• 公共网络：使用域名（例如[*] 检查容器是否在同一网络：```bash

  列出Docker网络

  docker network ls

  检查网络详情

  docker network inspect 您的网络名称

  验证两个容器是否在同一网络

  docker ps --format "table {{.Names}}\t{{.Networks}}"

   - 检查Navidrome日志中的扫描问题
   - 如使用多个库，验证UI中的库选择**数据库错误 **- 确保数据库目录有写入权限
   - 检查磁盘空间
   - 如数据库损坏，重启应用**仍有问题？**启动后访问应用中的系统检查页面 - 它将测试您的连接并提供具体指导。

## 系统检查页面

MagicLists在启动时自动验证配置。如检测到问题，您将被重定向到系统检查页面，显示：

-** 环境变量 **：检查必填变量是否已设置
-** Navidrome URL **：验证服务器是否可达  
-** Navidrome身份验证 **：测试凭据有效性
-** Navidrome艺术家API **：确认API访问正常
-** AI提供商配置 **：检查AI功能是否已配置（可选）
-** 库配置 **：显示多库设置和选择状态

如检查失败，将提供详细解决建议。您也可随时通过`/system-check`访问系统检查页面。

## 多库支持

MagicLists现在支持从多个Navidrome音乐库中选择：

-** 自动检测 **：应用在启动时检测所有可用库
-** 交互式选择 **：通过直观的下拉界面选择单个或多个库
-** 设置持久化 **：库选择将保存并在会话间恢复
-** 验证 **：未选择至少一个库时，应用将阻止播放列表创建

## API端点

- `GET /` - Web界面
- `GET /api/artists` - 列出所选库中的所有艺术家
- `GET /api/genres` - 列出所选库中的所有风格
- `GET /api/music-folders` - 列出可用音乐库
- `POST /api/create_playlist` - 创建新的"艺术家精选"播放列表
- `POST /api/create_genre_playlist` - 创建新的"风格混音"播放列表
- `POST /api/create_playlist_with_reasoning` - 创建带详细说明的播放列表
- `GET /api/rediscover-weekly` - 生成"每周重新发现"推荐
- `POST /api/create-rediscover-playlist` - 在Navidrome中创建"每周重新发现"播放列表
- `GET /api/playlists` - 列出所有管理的播放列表
- `DELETE /api/playlists/{playlist_id}` - 删除管理的播放列表
- `GET /api/recipes` - 列出可用的播放列表生成规则版本
- `GET /api/recipes/validate` - 验证播放列表生成规则配置
- `GET /api/scheduler/status` - 检查自动刷新调度器状态
- `POST /api/scheduler/trigger` - 手动触发计划刷新
- `POST /api/scheduler/start` - 启动自动刷新调度器
- `GET /api/health-check` - 运行系统健康检查
- `GET /api/ai-model-info` - 获取当前AI模型信息
- `POST /api/track-library-size` - 跟踪库大小用于分析

## AI配置（可选）

AI功能通过智能曲目选择增强播放列表推荐。您可从多个提供商中选择：** 支持的提供商：**-** OpenAI **：`openai/gpt-3.5-turbo`、`openai/gpt-4o-mini`
-** Anthropic **：`claude-3-haiku`、`claude-3-sonnet`
-** Ollama **：本地模型如`llama3.1`、`mistral`** 配置示例：**```bash
   # OpenAI
   AI_PROVIDER=openai
   OPENAI_API_KEY=sk-您的密钥
   
   # Anthropic
   AI_PROVIDER=anthropic
   ANTHROPIC_API_KEY=sk-ant-您的密钥
   
   # Ollama（本地）
   AI_PROVIDER=ollama
   OLLAMA_URL=http://host.docker.internal:11434
```** 注意：**未配置AI时，应用将回退到基于播放次数的算法播放列表生成。

## 许可证

MIT许可证 - 详见LICENSE文件。

## 贡献指南

1. Fork仓库
2. 创建功能分支
3. 进行修改
4. 必要时添加测试
5. 提交拉取请求

## 📈 使用分析

本项目使用Umami Analytics***测量功能使用情况（不存储Cookie或个人数据）。

您可查看**公开仪表板**：magic-lists analytics

## 支持

遇到问题或有疑问：
- 查看故障排除部分
- 参考Navidrome文档
- 在仓库中创建issue

## ***免责声明**无担保**：本软件按"原样"提供，不提供任何明示或暗示的担保。** 用户责任 **：您需自行负责：
- 确保对通过本应用处理的任何音乐内容拥有适当权利
- 传输给第三方AI服务的任何数据
- 使用前备份您的音乐库
- 对播放列表或库所做的任何修改**责任限制**：开发者不对任何损害负责，包括但不限于数据丢失、音乐库损坏或因使用本软件引起的任何直接或间接损害。** 第三方服务**：本应用集成了外部AI服务。您对这些服务的使用受其各自服务条款约束。

使用本软件即表示您承认并接受这些条款。

---

© 2025 由Synnot Studio开发 — 基于MIT许可证。