🎵 SoundScape

一个现代化的音乐播放器前端应用，专为 xiaomusic 服务设计，基于 React 19 和 HeroUI 构建。

📖 关于 xiaomusic

xiaomusic 是一个强大的后端服务，支持通过小爱音箱播放音乐。SoundScape 作为其官方前端客户端，提供了美观、易用的 Web 界面来控制音乐播放。

xiaomusic 核心功能

• 支持小爱音箱播放本地音乐文件
• 支持多种音频格式
• 播放列表管理
• 音乐搜索功能
• 音量控制
• 多设备管理

🎯 项目定位

SoundScape 是 xiaomusic 服务的现代化前端界面，提供：

• 🎨 美观的用户界面
• ⚡ 流畅的交互体验
• 🔧 完整的播放控制功能

🛠 技术栈

• React 19 - 最新版本的 React
• Vite - 下一代前端构建工具
• TailwindCSS - 实用优先的 CSS 框架
• HeroUI - 现代化的 React UI 组件库
• Zustand - 轻量级状态管理

✨ 功能特性

已实现功能

• ✅ 设备选择 - 选择播放设备
• ✅ 播放列表管理 - 选择和刷新播放列表
• ✅ 音乐播放 - 播放选中的歌曲
• ✅ 播放控制
  • 播放/暂停
  • 上一曲/下一曲
  • 音量调节
  • 随机播放
  • 循环模式（关闭/列表循环/单曲循环）
• ✅ 搜索功能 - 搜索歌曲
• ✅ 实时状态 - 显示当前播放状态

🚀 快速开始

前置条件

在开始之前，请确保你已经部署了 xiaomusic 后端服务。推荐使用 Docker 部署：

# 使用 Docker 部署 xiaomusic
docker run -p 8090:8090 \
  -v /xiaomusic/music:/app/music \
  -v /xiaomusic/conf:/app/conf \
  hanxi/xiaomusic

或使用 Docker Compose：

services:
  xiaomusic:
    image: hanxi/xiaomusic
    container_name: xiaomusic
    restart: unless-stopped
    ports:
      - 8090:8090
    volumes:
      - /xiaomusic/music:/app/music
      - /xiaomusic/conf:/app/conf

1. 克隆项目

git clone https://github.com/your-username/SoundScape.git
cd SoundScape

2. 安装依赖

npm install

3. 启动开发服务器

npm run dev

应用将在 http://localhost:5173 启动。

4. 构建生产版本

npm run build

📁 项目结构

SoundScape/
├── src/
│   ├── components/          # UI 组件
│   │   ├── MainContent.jsx         # 主内容区域
│   │   ├── PlayerBar.jsx           # 播放控制栏
│   │   └── Settings.jsx            # 设置页面
│   ├── hooks/               # 自定义 Hooks
│   ├── services/            # API 服务
│   │   └── api.js                  # xiaomusic API 调用
│   ├── store/               # 状态管理
│   │   └── useMusicStore.js        # 音乐播放器状态
│   ├── App.jsx              # 主应用组件
│   ├── main.jsx             # 应用入口
│   └── index.css            # 全局样式
├── public/                  # 静态资源
└── package.json             # 项目依赖

🔌 API 接口

应用通过 xiaomusic 服务的以下主要 API 接口进行交互：

• GET /getsetting - 获取设备列表
• GET /musiclist - 获取音乐列表
• GET /playlistnames - 获取播放列表名称
• GET /playlistmusics - 获取播放列表内容
• GET /searchmusic - 搜索音乐
• POST /playmusiclist - 播放播放列表
• POST /cmd - 发送播放控制命令
• GET /playingmusic - 获取当前播放信息
• GET /getvolume - 获取音量
• POST /setvolume - 设置音量

详细的 API 文档请参考 xiaomusic 项目 。

📖 使用说明

基本操作

1. 选择设备：在设置页面或顶部下拉框中选择要控制的小爱音箱设备
2. 播放音乐：
   • 在"播放列表"标签页中选择预设播放列表后播放
3. 控制播放：
   • 使用底部播放栏的播放/暂停按钮控制音乐播放
   • 使用上一曲/下一曲按钮切换歌曲
   • 拖动音量滑块调节播放音量
   • 点击随机播放和循环按钮切换播放模式

🛠 开发说明

• 所有 API 调用都包含完整的错误处理和加载状态
• 支持与 xiaomusic 服务的 HTTP Basic 认证（如配置）
• 使用 React 19 的最新特性和 Hooks
• 采用 Zustand 进行轻量级状态管理

🤝 贡献

欢迎提交 Issue 和 Pull Request 来改进这个项目！

📄 许可证

MIT License

🔗 相关链接

• xiaomusic 后端服务
• xiaomusic Docker 镜像
• 小爱音箱相关文档