Live Streaming Platform (Preview/Live Split)

This repository contains a full-stack live streaming platform with:

• Spring Boot backend (room management, auth, preview/live flow)
• React + Vite frontend (studio console, viewer pages)
• Nginx RTMP (RTMP ingest + HLS output)
• OBS integration (auto-config preview, switch to live)

Branch: main (current) Feature work: feature/preview-live-split

---

1) Tech Stack

• Backend: Spring Boot 3.x, Spring Data JPA, MySQL 8
• Frontend: React + Vite
• Streaming: Nginx RTMP module, HLS
• Client: OBS Studio + OBS WebSocket

---

2) Project Layout

E:\live
├─ src\main\java\com\example\live\    # Spring Boot backend
├─ src\main\resources\               # application.properties
├─ live-stream-react\                # React frontend
├─ nginx-rtmp-win32\                 # Nginx RTMP (Windows)
└─ nginx-rtmp.conf.example            # reference config

---

3) Requirements

• JDK 17
• Maven 3.8+
• MySQL 8
• Node.js 18+
• OBS Studio 30+ (OBS WebSocket 5.x)
• Windows (paths in config use E:\live)

---

4) Database Setup

4.1 Create DB

CREATE DATABASE live_db;

4.2 Tables

The app uses JPA ddl-auto=update, but for preview/live split and avatar data you may need manual schema updates:

ALTER TABLE live_room
  ADD COLUMN preview_key VARCHAR(255),
  ADD COLUMN preview_rtmp_url LONGTEXT,
  ADD COLUMN preview_hls_url LONGTEXT,
  ADD COLUMN preview_auth_token VARCHAR(64);

ALTER TABLE live_room
  MODIFY cover_url LONGTEXT;

ALTER TABLE user_account
  MODIFY avatar_url LONGTEXT;

---

5) Backend Configuration

Edit: E:\live\src\main\resources\application.properties

Example:

server.port=8081

spring.datasource.url=jdbc:mysql://127.0.0.1:3306/live_db?useUnicode=true&characterEncoding=UTF-8&serverTimezone=Asia/Shanghai&useSSL=false&allowPublicKeyRetrieval=true
spring.datasource.username=live_user
spring.datasource.password=Live12345!
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.MySQL8Dialect

rtmp.base.url=rtmp://localhost/live
rtmp.preview.base.url=rtmp://localhost/preview
hls.base.url=http://localhost:8080/hls

cors.allowed-origins=http://localhost:3000

---

6) Nginx RTMP Setup

File: E:\live\nginx-rtmp-win32\conf\nginx.conf

Key blocks:

• application live for public streams
• application preview for private preview streams
• /hls/ and /hls/preview/ for HLS playback

Ensure preview path exists:

E:\live\nginx-rtmp-win32\temp\hls\preview

Start/Reload:

cd E:\live\nginx-rtmp-win32
.\nginx.exe -t
.\nginx.exe
# or reload:
.\nginx.exe -s reload

Stop all Nginx:

taskkill /F /IM nginx.exe

---

7) Backend Run

cd E:\live
mvn spring-boot:run

---

8) Frontend Run

cd E:\live\live-stream-react
npm install
npm run dev

Open: http://localhost:3000

---

9) OBS Setup (Preview -> Live)

9.1 Preview Stream (auto-config)

When creating a room in the Studio, you can enable: Auto configure OBS preview and start streaming

OBS WebSocket settings:

• Host: ws://127.0.0.1:4455
• Password: (if configured in OBS)

Preview RTMP settings (manual if needed):

• Server: rtmp://localhost/preview
• Stream key: <previewKey>?token=<previewAuthToken>

9.2 Go Live (switch)

Click Start Live in the Studio console:

1. OBS preview stream is stopped
2. Stream service switches to:
   • Server: rtmp://localhost/live
   • Key: <streamKey>
3. OBS starts streaming again
4. Backend status = live

9.3 End Live

Click Stop:

• OBS stream stopped
• Status = ended
• Preview disabled

---

10) URL Structure

Viewer:

• / Home
• /live Live list
• /live/:roomId Watch page

Studio:

• /studio
• /studio/rooms
• /studio/rooms/new
• /studio/rooms/:roomId

Settings:

• /settings/profile
• /settings/devices

Login:

• /login

---

11) Core API Endpoints

Rooms:

• GET /api/rooms
• GET /api/rooms/live
• POST /api/rooms
• POST /api/rooms/{id}/start
• POST /api/rooms/{id}/stop
• POST /api/rooms/tag-all?category=

Auth:

• POST /api/auth/register
• POST /api/auth/login
• GET /api/auth/profile?username=...
• POST /api/auth/profile

Preview Auth (Nginx):

• GET|POST /api/streams/preview-auth?name=...&token=...

---

12) Common Troubleshooting

12.1 No preview HLS file generated

Check:

1. OBS stream settings for preview:
   • server: rtmp://localhost/preview
   • key: previewKey?token=previewAuthToken
2. Nginx is running and has application preview configured
3. Preview folder exists: E:\live\nginx-rtmp-win32\temp\hls\preview
4. Nginx logs show PUBLISH: E:\live\nginx-rtmp-win32\logs\access.log

12.2 OBS "cannot change stream service while streaming"

Handled in the UI by stopping stream before switching. Make sure you are on the latest frontend build.

12.3 Preview HLS returns 404

It means OBS is not pushing preview stream or token auth failed. Check:

Invoke-WebRequest "http://localhost:8081/api/streams/preview-auth?name=<previewKey>&token=<previewAuthToken>"

If not 200, token is wrong.

12.4 Nginx port conflict

If netstat -ano | findstr :1935 shows multiple PIDs, stop all:

taskkill /F /IM nginx.exe

Then start once.

---

13) Notes

• ended status means the stream is finished and preview is disabled.
• Preview stream is only for streamer; viewers use public live stream.
• The Studio console automatically switches preview -> live.

---

14) Quick Start Checklist

1. Start MySQL
2. Start backend (mvn spring-boot:run)
3. Start Nginx (nginx.exe)
4. Start frontend (npm run dev)
5. Open Studio → Create room → Start preview
6. Click "Start Live" to go public

---

If you want more features (replay, chat, analytics), extend the backend and add new pages under /studio.