# vstream

**Repository Path**: wooddeep/vstream

## Basic Information

- **Project Name**: vstream
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-23
- **Last Updated**: 2026-06-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# VStream - 视频直播系统

基于开源方案的最小视频直播系统，包含 Spring Boot 服务端和 Android 客户端。

## 架构

```
Android (推流) ──RTMP──> SRS Media Server ──HLS/RTMP──> Android (拉流)
                              │
                              │ HTTP Callback
                              ▼
                     Spring Boot Server
                     (流管理 / REST API / WebSocket)
```

**开源组件：**
- [SRS (Simple Realtime Server)](https://github.com/ossrs/srs) — RTMP/HLS 媒体服务器
- [Spring Boot](https://spring.io/projects/spring-boot) — 后端服务
- [ExoPlayer / Media3](https://github.com/androidx/media) — Android 播放器

---

## 最小系统启动流程

### 前置条件
- JDK 17+
- Maven 3.8+
- Docker (用于运行 SRS)
- Android Studio (用于编译 Android 端)

### 第 1 步：启动 SRS 媒体服务器

```bash
docker run -d --name srs \
  -p 1935:1935 \
  -p 8080:8080 \
  -p 1985:1985 \
  ossrs/srs:5 \
  ./objs/srs -c conf/docker.conf
```

验证 SRS 启动成功：
```bash
curl http://localhost:1985/api/v1/versions
```

### 第 2 步：启动 Spring Boot 服务端

```bash
cd vstream-server

# 编译
mvn clean package -DskipTests

# 运行
java -jar target/vstream-server-1.0.0.jar
```

注意：Spring Boot 默认端口 8080，与 SRS 的 HTTP 端口冲突。修改 SRS 的 HTTP 端口或修改 Spring Boot 端口：

```bash
# 方式1：修改 Spring Boot 端口
java -jar target/vstream-server-1.0.0.jar --server.port=9090

# 方式2：修改 SRS 端口（docker 模式）
docker run -d --name srs \
  -p 1935:1935 \
  -p 8088:8080 \
  -p 1985:1985 \
  ossrs/srs:5 ./objs/srs -c conf/docker.conf
# 此时 HLS 地址为 http://localhost:8088/live/xxx.m3u8
```

验证服务端启动：
```bash
curl http://localhost:8080/api/v1/streams
# 返回 {"code":0,"message":"success","data":[]}
```

### 第 3 步：编译运行 Android 端

```bash
cd vstream-android

# 用 Android Studio 打开项目
# File > Open > 选择 vstream-android 目录

# 或命令行编译
./gradlew assembleDebug
./gradlew clean assembleDebug # 清理
rm -rf app/build
```

在 Android Studio 中：
1. 连接 Android 设备或启动模拟器
2. 运行 app
3. 在 "服务器地址" 中填写 Spring Boot 服务端地址（模拟器用 `http://10.0.2.2:8080`，真机用局域网 IP）
4. "开播" 标签页 → 填写标题和主播名 → 点击 "开始直播"
5. "观看" 标签页 → 刷新 → 点击直播间观看

---

## API 接口

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/v1/streams` | 创建直播间 |
| GET | `/api/v1/streams` | 列出所有直播间 |
| GET | `/api/v1/streams/living` | 列出正在直播的 |
| GET | `/api/v1/streams/{id}` | 查询直播间详情 |
| DELETE | `/api/v1/streams/{id}` | 删除直播间 |
| POST | `/api/v1/srs/callback` | SRS 回调（on_publish/on_unpublish） |
| WS | `/ws/live` | WebSocket 实时推送流状态 |

### 创建直播间示例

```bash
curl -X POST http://localhost:8080/api/v1/streams \
  -H "Content-Type: application/json" \
  -d '{"title":"测试直播","hostName":"主播1"}'
```

返回：
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "streamId": "a1b2c3d4e5f6",
    "title": "测试直播",
    "hostName": "主播1",
    "rtmpPushUrl": "rtmp://localhost:1935/live/a1b2c3d4e5f6",
    "rtmpPlayUrl": "rtmp://localhost:1935/live/a1b2c3d4e5f6",
    "hlsPlayUrl": "http://localhost:8080/live/a1b2c3d4e5f6.m3u8",
    "status": "CREATED",
    "createdAt": "2026-06-11T12:00:00Z"
  }
}
```

---

## 推流测试 (FFmpeg)

如果暂时没有 Android 设备，可以用 FFmpeg 测试推流：

```bash
# 先创建直播间，获取 streamId
STREAM_ID=$(curl -s -X POST http://localhost:8080/api/v1/streams \
  -H "Content-Type: application/json" \
  -d '{"title":"FFmpeg测试","hostName":"test"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['streamId'])")

# 用 FFmpeg 推流（测试视频源）
ffmpeg -re -f lavfi -i testsrc=size=1280x720:rate=30 \
       -f lavfi -i sine=frequency=1000:sample_rate=44100 \
       -vcodec libx264 -preset ultrafast -tune zerolatency \
       -acodec aac -f flv \
       rtmp://localhost:1935/live/$STREAM_ID

# 用 FFplay 或 VLC 播放 HLS
ffplay http://localhost:8080/live/$STREAM_ID.m3u8
```

---

## 目录结构

```
vstream/
├── vstream-server/                    # Spring Boot 服务端
│   ├── pom.xml
│   └── src/main/java/com/vstream/
│       ├── VStreamApplication.java    # 启动类
│       ├── config/                    # 配置 (CORS, WebSocket, SRS属性)
│       ├── controller/               # REST API + SRS回调
│       ├── handler/                  # WebSocket处理器
│       ├── model/                    # 数据模型
│       └── service/                  # 业务逻辑
│
├── vstream-android/                   # Android 客户端
│   ├── build.gradle.kts
│   ├── settings.gradle.kts
│   └── app/src/main/
│       ├── AndroidManifest.xml
│       ├── java/com/vstream/android/
│       │   ├── ui/push/              # 推流界面
│       │   ├── ui/play/              # 拉流/列表界面
│       │   ├── network/              # API客户端
│       │   └── rtmp/                 # RTMP推流引擎
│       └── res/layout/               # 布局文件
│
└── README.md
```