# Serene Player

**Repository Path**: Domdkw/serene-player

## Basic Information

- **Project Name**: Serene Player
- **Description**: 基于 React 和 TypeScript 构建的现代化优雅音乐播放器。由Gemini 3 Flash+TRAE+Hand 开发
- **Primary Language**: TypeScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://dmSerene-Player.netlify.app
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-01
- **Last Updated**: 2026-02-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<div align="center">
<img width="1200" height="475" alt="GHBanner" src="./屏幕截图 2026-01-02 003355.png" />
</div>

# Serene Player - 宁静播放器

基于 React 和 TypeScript 构建的现代化优雅音乐播放器。由 Gemini 3 Flash + TRAE + Hand 开发

## 功能特性

- 🎵 美观简约的用户界面，支持 3D 封面效果
- 🎨 流畅的动画过渡效果
- 🎧 完整播放控制（播放/暂停、切歌、音量调节、进度拖拽）
- 📋 播放列表管理，支持文件夹嵌套
- 🔗 支持外链歌单导入
- 🔄 多种播放模式（单曲、列表、重复、随机）
- 📊 实时进度追踪
- 🎼 歌词自动滚动显示，支持逐字高亮和逐行高亮
- 📝 歌词翻译显示（可开关）
- 🎨 音频可视化频谱效果
- 🎭 全局动态背景效果
- 👤 艺术家视图，按首字母排序
- 🔤 拼音首字母排序支持（中文艺术家）
- 📱 移动端适配，支持手势切换页面
- ⚙️ 可自定义设置（分块加载、字体、字体粗细、字间距、行高）
- 🪞 镜像源支持，加速音乐文件加载
- 💾 本地存储记住用户设置

## 本地运行

**前置要求：** Node.js 18+

1. 安装依赖：
   ```bash
   npm install
   ```
2. 启动应用：
   ```bash
   npm run dev
   ```
3. 在浏览器中访问 `http://localhost:5173`

## 构建部署

```bash
npm run build
```

构建后的文件将生成在 `dist/` 目录中。

## 项目结构

```
├── App.tsx                    # 主应用组件（桌面端）
├── mobile/
│   ├── App.tsx               # 移动端应用组件
│   ├── ArtistsView.tsx       # 移动端艺术家视图
│   └── SettingsPanel.tsx     # 移动端设置面板
├── components/
│   ├── MusicPlayer.tsx       # 音乐播放器组件
│   ├── MiniPlayerBar.tsx     # 迷你播放栏
│   ├── MusicLibrary.tsx      # 音乐库组件
│   ├── ArtistsView.tsx       # 艺术家视图组件
│   ├── FolderDisplay.tsx     # 文件夹显示组件
│   ├── SettingsPanel.tsx     # 设置面板组件
│   ├── LyricLine.tsx         # 歌词行组件
│   ├── AudioSpectrum.tsx     # 音频可视化组件
│   └── GlobalBackground.tsx  # 全局背景组件
├── utils/
│   ├── metadata.ts           # 音频元数据提取
│   ├── fontUtils.ts          # 字体工具
│   └── pinyinLoader.ts       # 拼音首字母排序
├── cli/
│   ├── mirrorMaker/          # 镜像生成工具
│   └── theme-color-extraction/  # 主题色提取工具
├── public/
│   ├── music/                # 音乐文件目录
│   ├── discList.json         # 播放列表配置
│   └── mirrors.json          # 镜像源配置
├── types.ts                  # TypeScript 类型定义
├── metadata.json             # 曲目元数据
├── vite.config.ts            # Vite 配置
└── tsconfig.json             # TypeScript 配置
```

## 使用说明

### 添加音乐

1. 将音乐文件添加到 `public/music/` 目录
2. 更新 `public/discList.json` 配置播放列表
3. 启动应用并享受音乐

### discList.json 格式

```json
{
  "文件夹名称": [
    {
      "name": "歌曲名称",
      "artist": "艺术家",
      "url": "./music/音乐文件.mp3",
      "themeColor": "#ff6b6b"
    }
  ],
  "外链文件夹": {
    "link": "https://example.com/discList.json"
  }
}
```

### 生成镜像源

使用 `cli/mirrorMaker/main.py` 生成镜像配置文件：

```bash
python cli/mirrorMaker/main.py
```

### 主题色提取

使用 `cli/theme-color-extraction/` 工具提取音乐封面主题色：

```bash
cd cli/theme-color-extraction
pip install -r requirements.txt
python main.py
```

## 技术栈

- React 19
- TypeScript 5.8
- Vite 6
- Lucide React Icons
- HTML5 Audio API
- fetch-in-chunks（分块加载）
- Tailwind CSS
- jsmediatags（元数据提取）

## 移动端特性

- 左右滑动手势切换页面（播放器/歌词/列表）
- 优化的触控体验
- 响应式布局适配
- 底部迷你播放栏

## 自定义设置

点击设置按钮可调整：

- **分块拉取片数**：1/4/8/16（数值越大加载越快）
- **字体选择**：多种中文字体可选
- **歌词字体粗细**：细体/常规/粗体
- **歌词字间距**：可调节
- **歌词行高**：可调节
- **翻译显示**：开启/关闭歌词翻译

## 浏览器支持

- Chrome 90+
- Firefox 88+
- Safari 14+
- Edge 90+

## 开发计划

- [ ] 支持更多音频格式（FLAC、WAV、OGG）
- [ ] 歌单分享功能
- [ ] 深色/浅色主题切换
- [ ] 音乐均衡器调节

## 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建您的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交您的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request

## 许可证

本项目基于 MIT 许可证开源 - 查看 [LICENSE](LICENSE) 文件了解详情

## 致谢

- 感谢 [jsmediatags](https://github.com/aadsm/jsmediatags) 提供元数据提取功能
- 感谢 [pinyin-pro](https://github.com/zh-lx/pinyin-pro) 提供拼音支持
- 感谢 [fetch-in-chunks](https://github.com/AnthumChris/fetch-in-chunks) 提供分块加载支持

---

### 英文版本

如需查看英文版本，请访问 [README_EN.md](README_EN.md)