# xiaozhi-music-services

**Repository Path**: ucortex/xiaozhi-music-services

## Basic Information

- **Project Name**: xiaozhi-music-services
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-01
- **Last Updated**: 2026-03-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ESP32音乐服务API

## 项目简介

这是一个基于Spring Boot的REST API服务，专门为ESP32音乐播放器提供音乐搜索、播放、歌词等功能的API接口。该服务模拟了ESP32音乐播放器的核心功能，包括音乐搜索、歌词解析、音频流处理等。

**QQ: 992383405**

## 技术栈

- **框架**: Spring Boot 2.3.12
- **数据库**: H2 (内存数据库)
- **ORM**: Spring Data JPA
- **HTTP客户端**: Apache HttpClient
- **缓存**: Spring Cache
- **构建工具**: Maven

## 功能特性

### 1. 音乐搜索功能
- 支持按歌曲名称、艺术家、专辑搜索
- 支持关键词模糊搜索
- 支持多种音频格式 (MP3, WAV, FLAC, OGG)
- 提供音频元数据信息 (采样率、声道数、时长等)

### 2. 歌词管理功能
- 支持LRC格式歌词解析
- 支持时间戳歌词同步
- 支持歌词的增删改查
- 支持按时间范围获取歌词

### 3. 音频流处理
- 支持音频流式下载
- 支持断点续传
- 支持多种音频格式检测
- 支持音频质量参数配置

## 快速开始

### 环境要求
- Java 8+
- Maven 3.6+

### 启动步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd music-services
```

2. **编译项目**
```bash
mvn clean compile
```

3. **运行项目**
```bash
mvn spring-boot:run
```

4. **访问服务**
- API服务地址: http://localhost:8080/api
- H2数据库控制台: http://localhost:8080/h2-console
- 健康检查: http://localhost:8080/api/music/health

## API接口文档

### 音乐搜索接口

#### 1. 搜索音乐
```http
POST /api/music/search
Content-Type: application/json

{
  "songName": "告白气球",
  "artist": "周杰伦",
  "album": "周杰伦的床边故事"
}
```

#### 2. 根据歌曲名称搜索
```http
GET /api/music/search?songName=告白气球
```

#### 3. 关键词搜索
```http
GET /api/music/search/keyword?keyword=告白
```

#### 4. 获取音乐详情
```http
GET /api/music/{id}
```

#### 5. 获取所有音乐
```http
GET /api/music
```

### 歌词接口

#### 1. 获取歌词
```http
GET /api/lyric/music/{musicId}
```

#### 2. 根据歌曲名称获取歌词
```http
GET /api/lyric/song?songName=告白气球
```

#### 3. 获取当前播放时间的歌词
```http
GET /api/lyric/current?musicId=1&time=60000
```

#### 4. 解析并保存歌词
```http
POST /api/lyric/parse
Content-Type: application/json

{
  "musicId": 1,
  "lyricContent": "[00:00.00]告白气球\n[00:03.50]演唱：周杰伦"
}
```

## 数据库设计

### 音乐信息表 (music_info)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 主键ID |
| song_name | VARCHAR | 歌曲名称 |
| artist | VARCHAR | 艺术家 |
| title | VARCHAR | 标题 |
| album | VARCHAR | 专辑 |
| audio_url | VARCHAR | 音频URL |
| lyric_url | VARCHAR | 歌词URL |
| format | VARCHAR | 音频格式 |
| file_size | BIGINT | 文件大小(字节) |
| duration | INT | 时长(秒) |
| sample_rate | INT | 采样率 |
| channels | INT | 声道数 |
| quality | VARCHAR | 音质 |
| create_time | TIMESTAMP | 创建时间 |
| update_time | TIMESTAMP | 更新时间 |

### 歌词行表 (lyric_line)
| 字段 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 主键ID |
| music_info_id | BIGINT | 音乐信息ID |
| timestamp | INT | 时间戳(毫秒) |
| content | VARCHAR | 歌词内容 |
| line_number | INT | 行号 |
| create_time | TIMESTAMP | 创建时间 |

## 配置说明

### 应用配置 (application.properties)
```properties
# 服务器配置
server.port=8080
server.servlet.context-path=/api

# 数据库配置
spring.datasource.url=jdbc:h2:mem:musicdb
spring.datasource.username=sa
spring.datasource.password=

# 音乐API配置
music.api.base-url=http://localhost:8080
music.api.stream-pcm-path=/stream_pcm
music.api.audio-path=/audio
music.api.lyric-path=/lyric
```

## 示例数据

应用启动时会自动创建以下示例音乐数据：

1. **告白气球** - 周杰伦
2. **月亮代表我的心** - 邓丽君  
3. **海阔天空** - Beyond
4. **成都** - 赵雷
5. **Faded** - Alan Walker

## 与ESP32音乐播放器的对应关系

### 核心功能映射

| ESP32功能 | API接口 | 说明 |
|-----------|---------|------|
| `Download()` | `POST /api/music/search` | 音乐搜索和下载 |
| `ParseLyrics()` | `POST /api/lyric/parse` | 歌词解析 |
| `UpdateLyricDisplay()` | `GET /api/lyric/current` | 歌词同步显示 |
| `StartStreaming()` | 音频流处理 | 音频流式播放 |

### 数据结构映射

| ESP32变量 | API字段 | 说明 |
|-----------|---------|------|
| `current_song_name_` | `songName` | 当前歌曲名称 |
| `current_music_url_` | `audioUrl` | 音频URL |
| `current_lyric_url_` | `lyricUrl` | 歌词URL |
| `lyrics_` | `lyric_line`表 | 歌词数据 |

## 开发说明

### 项目结构
```
src/main/java/com/zzw/musicservices/
├── controller/          # 控制器层
│   ├── MusicController.java
│   └── LyricController.java
├── service/            # 服务层
│   ├── MusicService.java
│   └── LyricService.java
├── repository/         # 数据访问层
│   ├── MusicInfoRepository.java
│   └── LyricLineRepository.java
├── model/             # 数据模型
│   ├── MusicInfo.java
│   └── LyricLine.java
├── dto/               # 数据传输对象
│   ├── MusicSearchRequest.java
│   └── MusicSearchResponse.java
└── config/            # 配置类
    ├── RestTemplateConfig.java
    └── DataInitializer.java
```

### 扩展功能

1. **音频格式支持**: 可以在`MusicService`中添加更多音频格式的检测和处理
2. **缓存策略**: 可以配置Redis等外部缓存来提升性能
3. **音频处理**: 可以集成FFmpeg等工具进行音频转码和处理
4. **用户管理**: 可以添加用户认证和授权功能

## 测试

### 单元测试
```bash
mvn test
```

### 集成测试
```bash
mvn verify
```

### API测试
可以使用Postman或curl等工具测试API接口：

```bash
# 健康检查
curl http://localhost:8080/api/music/health

# 搜索音乐
curl -X POST http://localhost:8080/api/music/search \
  -H "Content-Type: application/json" \
  -d '{"songName": "告白气球"}'
```

## 部署

### 打包
```bash
mvn clean package
```

### 运行JAR文件
```bash
java -jar target/music-services-0.0.1-SNAPSHOT.jar
```

### Docker部署
```dockerfile
FROM openjdk:8-jre-alpine
COPY target/music-services-0.0.1-SNAPSHOT.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "/app.jar"]
```

## 贡献指南

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

## 许可证

本项目采用开源许可证，详见LICENSE文件。

## 联系方式

- 项目维护者: 张小胖
- QQ: 992383405
- 项目地址: [GitHub Repository]

---

**注意**: 这是一个模拟ESP32音乐播放器功能的API服务，主要用于开发和测试目的。