blueion76/octogen

🎵 OctoGen - 为Navidrome生成Spotify风格自动播放列表

OctoGen 自动为Navidrome服务器生成个性化音乐播放列表，支持LLM、LastFM、ListenBrainz和AudioMuse-AI，并可无缝集成https://github.com/V1ck3s/octo-fiesta下载缺失曲目。

---

✨ 核心功能

🤖 LLM驱动推荐

• 多LLM提供商：支持Gemini和OpenAI兼容API
• 智能上下文缓存：高效低耗API调用
• 多样性种子：每日生成不同推荐

🎵 生成的播放列表

• Discovery（50首）：新音乐发现
• Daily Mix 1-6（各30首）：基于流派的混合
• Chill Vibes（30首）：放松曲目
• Workout Energy（30首）：高能量音乐
• Focus Flow（30首）：氛围/器乐
• Drive Time（30首）： upbeat驾驶音乐
• Time-of-Day Playlist（30首）：匹配当前时段情绪

总计：12个播放列表，自动精选380+首歌曲！

🕐 时段播放列表

根据时段自动切换情绪适配的播放列表：

• Morning Mix（4 AM - 10 AM）：活力、积极
• Afternoon Flow（10 AM - 4 PM）：平衡、高效
• Evening Chill（4 PM - 10 PM）：放松、舒缓
• Night Vibes（10 PM - 4 AM）：氛围、平静

特性：

• ✅ 混合生成：25首来自AudioMuse-AI + 5首来自LLM
• ✅ 时段变化时自动轮换
• ✅ 生成新列表时自动删除非活跃时段列表（或设置TIMEOFDAY_PLAYLISTS_PERSIST=true保留所有四个）
• ✅ 可配置时段边界
• ✅ LLM提示增强时段上下文

启用方式：

bash
TIMEOFDAY_ENABLED=true

🎛️ 混合模式（AudioMuse-AI集成）

OctoGen可集成AudioMuse-AI进行增强音频分析：

• 默认模式：所有播放列表使用LLM
• 混合模式：多数播放列表使用25首AudioMuse-AI +5首LLM歌曲

启用混合模式：

bash
AUDIOMUSE_ENABLED=true
AUDIOMUSE_URL=http://localhost:8000

🎯 智能特性

• 星级过滤：排除1-2星歌曲
• 重复检测：播放列表无重复曲目
• Octo-Fiesta集成：自动下载缺失曲目（或设置OCTOFIESTA_ENABLED=false仅本地运行）
• 每日缓存：高效库扫描
• 异步操作：快速并行处理
• 内置调度：无需外部cron

📊 监控与可观察性

• Web UI仪表盘：实时服务健康监控（自动刷新）
• Prometheus指标：跟踪播放列表、下载、API调用、延迟
• 断路器：防止外部API级联故障
• 结构化日志：JSON格式支持日志聚合
• 健康检查：监控Navidrome、Octo-Fiesta、LLM等服务

---

🚀 快速开始

前提条件

• Navidrome服务器运行中
• Octo-Fiesta配置完成
• 至少一个音乐来源：LLM API密钥、AudioMuse-AI、LastFM或ListenBrainz

1. 获取API密钥（可选，若使用LLM）

访问：https://aistudio.google.com/apikey

2. 创建配置

bash
# 创建.env文件
cat > .env << 'EOF'
# 必填
NAVIDROME_URL=http://192.168.1.100:4533
NAVIDROME_USER=admin
NAVIDROME_PASSWORD=your_password
OCTOFIESTA_URL=http://192.168.1.100:5274
AI_API_KEY=your_llm_api_key

# 可选
AI_MODEL=gemini-2.5-flash
AI_BACKEND=gemini
LOG_LEVEL=INFO

# 调度
SCHEDULE_CRON=0 2 * * *
TZ=Asia/Shanghai
EOF

3. Docker运行

bash
# 拉取镜像
docker pull docker.xuanyuan.run/blueion76/octogen:latest

# 运行OctoGen（自动调度）
docker run -d \
  --name octogen \
  -v octogen-data:/data \
  --env-file .env \
  --restart unless-stopped \
  docker.xuanyuan.run/blueion76/octogen:latest

# 查看日志
docker logs -f octogen

---

🐳 Docker Compose（推荐）

yaml
version: '3.8'

services:
  octogen:
    image: docker.xuanyuan.run/blueion76/octogen:latest
    container_name: octogen
    restart: unless-stopped
    volumes:
      - octogen-data:/data
    ports:
      - "5000:5000" # Web UI
    environment:
      # 必填
      NAVIDROME_URL: http://navidrome:4533
      NAVIDROME_USER: admin
      NAVIDROME_PASSWORD: ${NAVIDROME_PASSWORD}
      OCTOFIESTA_URL: http://octofiesta:5274
      AI_API_KEY: ${GEMINI_API_KEY}

      # 调度
      SCHEDULE_CRON: "0 2,14 * * *" # 每日2点和14点
      TZ: Asia/Shanghai

      # 可选
      AI_MODEL: gemini-2.5-flash
      AI_BACKEND: gemini
      LOG_LEVEL: INFO

volumes:
  octogen-data:

运行：

bash
docker-compose up -d
docker-compose logs -f octogen

---

🌐 Web UI仪表盘

OctoGen包含实时监控仪表盘，访问http://localhost:5000：

• 服务健康状态（Navidrome、Octo-Fiesta等）
• 系统统计（播放列表数量、下载歌曲数）
• REST API（/api/health、/api/stats等）
• 自动刷新（每30秒）

---

🎨 AudioMuse-AI设置（可选）

1. 安装AudioMuse-AI

遵循https://github.com/NeptuneHub/AudioMuse-AI部署。

2. 初始分析

1. 打开http://localhost:8000
2. 导航到"Analysis and Clustering"
3. 点击"Start Analysis"（一次性分析库）
4. 等待完成

3. OctoGen中启用

在.env添加：

bash
AUDIOMUSE_ENABLED=true
AUDIOMUSE_URL=http://localhost:8000
AUDIOMUSE_AI_PROVIDER=gemini
AUDIOMUSE_AI_MODEL=gemini-2.5-flash
AUDIOMUSE_AI_API_KEY=your_api_key_here

---

🔧 配置

必填环境变量

可选配置

---

🎯 LLM提供商示例

Gemini（推荐，免费 tier）

bash
AI_BACKEND=gemini
AI_MODEL=gemini-2.5-flash
AI_API_KEY=your_llm_api_key

Ollama（本地离线）

bash
AI_BACKEND=openai
AI_BASE_URL=http://host.docker.internal:11434/v1
AI_MODEL=llama3.2
AI_API_KEY=ollama

---

🕐 自动调度

添加以下环境变量启用内置cron：

bash
SCHEDULE_CRON=0 2 * * * # 每日2点
TZ=Asia/Shanghai

---

📊 工作原理

1. 分析Navidrome库：读取收藏歌曲、识别顶级艺术家和流派
2. 生成推荐：使用LLM/AudioMuse/LastFM生成个性化曲目
3. 智能处理：检查库中是否存在、去重、触发下载
4. 创建播放列表：在Navidrome中创建12个主题播放列表
5. 监控调度：记录指标、更新仪表盘、等待下一次运行

---

🧪 Dry Run模式（测试）

bash
docker run --rm \
  -v octogen-data:/data \
  --env-file .env \
  docker.xuanyuan.run/blueion76/octogen:latest \
  python octogen.py --dry-run

---

📁 数据持久化

OctoGen数据存储在/data目录：

• octogen.log：应用日志
• octogen_cache.db：星级缓存
• gemini_cache.json：LLM上下文缓存

---

🔍 监控

日志

bash
docker logs -f octogen # 实时日志
docker logs --tail 100 octogen # 最后100行

Prometheus指标（可选）

启用：

bash
METRICS_ENABLED=true
METRICS_PORT=9090

访问：http://localhost:9090/metrics

---

🛠️ 故障排除

问题：无法连接Navidrome

解决：检查NAVIDROME_URL是否正确，使用Docker网络名称（如http://navidrome:4533）

问题：AI API错误

解决：验证API密钥、检查配额、尝试不同模型

---

📚 文档

• ENV_VARS.md：完整环境变量参考

---

🤝 贡献

欢迎贡献！提交Pull Request即可。

---

🙏 致谢

• Navidrome：开源音乐服务器
• **https://github.com/V1ck3s/octo-fiesta**：自动音乐下载器
• **https://github.com/NeptuneHub/AudioMuse-AI**：音频分析工具

---

🔗 链接

• Docker Hub：https://hub.docker.com/r/blueion76/octogen
• GitHub：https://github.com/Blueion76/Octogen

---

为自托管音乐社区打造 ❤️