1. Thông Tin Chung & Base URL
Hệ thống cung cấp API RESTful JSON chuẩn cùng hạ tầng streaming độ trễ thấp qua OvenMediaEngine và Centrifugo WebSocket.
| Thành phần | Địa chỉ kết nối (URL) | Mô tả |
|---|---|---|
| API Base URL | https://api-live.levanbac.io.vn |
RESTful API chính thức |
| WebRTC Server | wss://watch.levanbac.io.vn/app |
Xem luồng video siêu nhanh (Độ trễ < 1s) |
| HLS / LL-HLS Server | https://watch.levanbac.io.vn/app |
Xem qua HLS chuyển mã tự động (ABR 1080p, 720p...) |
| Realtime Chat WS | wss://chat.levanbac.io.vn/connection/websocket |
Centrifugo WebSocket cho Live Chat |
2. Luồng Phát Video Trực Tiếp (Playback)
Trước khi khởi tạo Video Player trên ứng dụng, client gọi API sau để lấy URL phát sóng:
Response mẫu (200 OK):
{
"status": "success",
"data": {
"channel": {
"id": 19,
"name": "Kênh Vietlott 1",
"status": "live",
"public_id": "9df7466c-e934-4585-8bb3-4463af0c6a7d",
"transcode_enabled": true
},
"playback": {
"webrtc_url": "wss://watch.levanbac.io.vn/app/7fb4cacb4a4c893d5a0be963e5dc6246",
"hls_url": "https://watch.levanbac.io.vn/app/7fb4cacb4a4c893d5a0be963e5dc6246/master.m3u8",
"llhls_url": "https://watch.levanbac.io.vn/app/7fb4cacb4a4c893d5a0be963e5dc6246/llhls.m3u8"
}
}
2.5. Cơ Chế Chủ Động Kết Thúc Phiên Live & Ngắt Luồng OBS
Hệ thống cung cấp 2 API để dừng livestream tùy theo mục đích vận hành:
Cách 1 (Khuyên dùng): Kết thúc phiên live theo sessionId (Không khóa kênh vĩnh viễn)
POST /api/livestream/:sessionId/end-live
Header yêu cầu: X-Api-Key: your-secret-api-key-here. Tham số :sessionId là ID phiên livestream (liveStreamId trong Webhook).
CƠ CHẾ HOẠT ĐỘNG CHUẨN YOUTUBE LIVE (SLIDING COOLDOWN):
1. Hủy chờ 3 phút & Đóng phiên ngay lập tức: Hủy bộ đếm live.paused (nếu có), chốt ended_at cho phiên live, bắn Outbound Webhook live.ended và kích hoạt gộp file MP4 + đồng bộ VOD lên S3.
2. Cắt kết nối OBS & Chặn Auto-Reconnect (DB + RAM Sliding Cooldown): Gửi lệnh ngắt luồng RTMP/SRT trên OvenMediaEngine. Nếu OBS chưa bấm Stop Streaming và tự động kết nối lại, hệ thống tự động từ chối (DENY) và gia hạn thời gian chặn (không tạo phiên live mới ngoài ý muốn).
3. Giữ nguyên is_active = true: Sau khi người vận hành dừng OBS (> 15 giây), lần bấm Start Streaming tiếp theo sẽ được phép lên sóng bình thường mà không cần gọi API mở khóa kênh.
Cách 2: Dừng cưỡng chế & Khóa cứng kênh (is_active = false)
POST /api/channels/:id/stop
Ngắt kết nối OBS và khóa quyền phát sóng của kênh (is_active = false). Để phát lại ở kỳ sau cần gọi POST /api/channels/:id/allow-stream để mở khóa.
3. Cơ Chế Đếm Lượt Xem Chuẩn Xác (Viewer Heartbeat)
QUY TẮC BẮT BUỘC KHI TÍCH HỢP PLAYER:
1. Lưu cố định device_uid vào thiết bị (không đổi khi mở lại app).
2. Khi video đang chạy, gửi request Heartbeat định kỳ mỗi 8 giây.
3. Khi thoát màn hình video, gọi API Leave để hệ thống giảm số người xem ngay lập tức.
3.1. Gửi Heartbeat định kỳ (Mỗi 8 giây)
POST /api/channels/:id/viewers/heartbeat
JSON Request
{
"viewer_uid": "device-uuid-vietlott-001"
}
3.2. Báo thoát khi đóng màn hình Player (Leave Event)
POST /api/channels/:id/viewers/leave
JSON Request
{
"viewer_uid": "device-uuid-vietlott-001"
}
3.3. Lấy Số Liệu Thống Kê View Hiển Thị
GET /api/channels/:id/viewers
JSON Response
{
"status": "success",
"data": {
"current_viewers": 28, // Số người xem trực tiếp lúc này
"peak_viewers": 150, // Kỷ lục xem cùng lúc cao nhất trong phiên
"total_views": 1420, // Tổng lượt vào xem tích lũy
"is_live": true // Kênh đang phát sóng hay không
}
}
3.4. Kho Video VOD S3, Phân Trang & Phát HLS Bảo Mật (.m3u8)
Truy xuất danh sách video ghi hình trên MinIO S3 (được đồng bộ tức thì vào bảng s3_file_cache ngay trước khi bắn webhook recording.completed). Mỗi video có sẵn hls_url, public_url và session_id (ID phiên livestream gốc):
GET /api/videos/s3?format=flat&page=1&limit=20
Tham số Query (Query Parameters):
Tham số Kiểu Mặc định Mô tả
pageInteger 1Số trang hiện tại (bắt đầu từ 1)
limitInteger 50 (flat) / 500 (group)Số lượng file mỗi trang (tối đa 1000)
formatString grouped Truyền flat (hoặc group=false) để nhận mảng phẳng từng video độc lập (khuyên dùng khi phân trang)
session_idInteger Tùy chọn Lọc đích danh file VOD theo ID phiên livestream (liveStreamId trong webhook)
public_idString Tùy chọn Lọc theo Public ID của kênh
channel_idInteger Tùy chọn Lọc theo ID số nguyên của kênh
searchString Tùy chọn Tìm kiếm theo tên kênh, tên file hoặc public_id
JSON Response — Chế độ Flat List (?format=flat&page=1&limit=20)
{
"status": "success",
"data": [
{
"object_name": "recordings/default/app/9df7466c-e934-4585-8bb3-4463af0c6a7d/20260826032526_20260826033228.mp4",
"file_name": "20260826032526_20260826033228.mp4",
"size": 147757109,
"last_modified": "2026-08-26T03:33:08Z",
"public_url": "https://s3.vtcmobile.vn/live-vietlott/recordings/default/app/9df7466c-e934-4585-8bb3-4463af0c6a7d/20260826032526_20260826033228.mp4",
"hls_url": "https://s3.vtcmobile.vn/live-vietlott/hls/default/app/9df7466c-e934-4585-8bb3-4463af0c6a7d/20260826032526_20260826033228/playlist.m3u8",
"public_id": "9df7466c-e934-4585-8bb3-4463af0c6a7d",
"channel_name": "Kênh Vietlott 1",
"channel_id": 19,
"file_type": "video",
"session_id": 142
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 39,
"total_pages": 2
}
}
JSON Response — Chế độ Mặc Định (Gom nhóm theo kênh)
{
"status": "success",
"data": [
{
"public_id": "9df7466c-e934-4585-8bb3-4463af0c6a7d",
"stream_key": "9df7466c-e934-4585-8bb3-4463af0c6a7d",
"channel_name": "Kênh Vietlott 1",
"files": [
{
"object_name": "recordings/default/app/9df7466c-e934-4585-8bb3-4463af0c6a7d/20260826032526_20260826033228.mp4",
"size": 147757109,
"last_modified": "2026-08-26T03:33:08Z",
"public_url": "https://s3.vtcmobile.vn/live-vietlott/recordings/default/app/9df7466c-e934-4585-8bb3-4463af0c6a7d/20260826032526_20260826033228.mp4",
"hls_url": "https://s3.vtcmobile.vn/live-vietlott/hls/default/app/9df7466c-e934-4585-8bb3-4463af0c6a7d/20260826032526_20260826033228/playlist.m3u8",
"session_id": 142
}
]
}
],
"pagination": {
"page": 1,
"limit": 500,
"total": 39,
"total_pages": 1
}
}
3.5. Tải Video Lên Hệ Thống (Upload Video VOD & Tự Động Phân Đoạn HLS)
Hệ thống cung cấp API chuẩn multipart/form-data để tải video MP4/MOV/MKV lên MinIO S3. Khi tải lên thành công, Server tự động phân đoạn HLS (.m3u8 & .ts) để phát bảo mật.
POST /api/videos/upload
Form Fields (multipart/form-data):
Field Kiểu Bắt buộc Mô tả
videoFile (Binary) Có File video định dạng .mp4, .mov, .mkv
titleString Có Tiêu đề video
public_idString Không Public ID kênh liên kết (Bảo mật, thay thế cho Stream Key)
descriptionString Không Mô tả chi tiết nội dung video
JSON Response (201 Created)
{
"status": "success",
"channel_public_id": "9df7466c-e934-4585-8bb3-4463af0c6a7d",
"data": {
"id": 12,
"title": "Video Quay Số Ngày 26/08",
"description": "Bản ghi quay số mở thưởng",
"object_name": "recordings/default/app/9df7466c-e934-4585-8bb3-4463af0c6a7d/1787654321_video.mp4",
"public_url": "https://s3.vtcmobile.vn/live-vietlott/recordings/default/app/9df7466c-e934-4585-8bb3-4463af0c6a7d/1787654321_video.mp4",
"file_size": 14582910,
"status": "active"
},
"hls_url": "https://s3.vtcmobile.vn/live-vietlott/hls/default/app/9df7466c-e934-4585-8bb3-4463af0c6a7d/1787654321_video/playlist.m3u8"
}
Code Mẫu Tích Hợp:
JavaScript (Có theo dõi % Progress Bar)
const formData = new FormData();
formData.append('title', 'Video Quay Thưởng 26/08');
formData.append('public_id', '9df7466c-e934-4585-8bb3-4463af0c6a7d');
formData.append('video', fileInput.files[0]);
const xhr = new XMLHttpRequest();
xhr.open('POST', 'https://api-live.levanbac.io.vn/api/videos/upload', true);
xhr.setRequestHeader('X-Api-Key', 'your-secret-api-key-here');
xhr.upload.onprogress = (e) => {
if (e.lengthComputable) {
const percent = Math.round((e.loaded / e.total) * 100);
console.log(`Đang tải lên: ${percent}%`);
}
};
xhr.onload = () => {
if (xhr.status === 201 || xhr.status === 200) {
const res = JSON.parse(xhr.responseText);
console.log('Upload thành công, HLS URL:', res.hls_url);
}
};
xhr.send(formData);
cURL
curl -X POST "https://api-live.levanbac.io.vn/api/videos/upload" \
-H "X-Api-Key: your-secret-api-key-here" \
-F "title=Video Quay Thưởng 26/08" \
-F "public_id=9df7466c-e934-4585-8bb3-4463af0c6a7d" \
-F "description=Mô tả chi tiết video..." \
-F "video=@/path/to/local/video.mp4"
Flutter / Dart
import 'package:http/http.dart' as http;
import 'dart:convert';
var uri = Uri.parse('https://api-live.levanbac.io.vn/api/videos/upload');
var req = http.MultipartRequest('POST', uri)
..headers['X-Api-Key'] = 'your-secret-api-key-here'
..fields['title'] = 'Video Quay Thưởng'
..fields['public_id'] = '9df7466c-e934-4585-8bb3-4463af0c6a7d'
..files.add(await http.MultipartFile.fromPath('video', filePath));
var streamedResponse = await req.send();
var res = await http.Response.fromStream(streamedResponse);
var data = jsonDecode(res.body);
print('HLS URL: ${data['hls_url']}');
React Native / Axios
import axios from 'axios';
const formData = new FormData();
formData.append('title', 'Video Quay Thưởng');
formData.append('public_id', '9df7466c-e934-4585-8bb3-4463af0c6a7d');
formData.append('video', {
uri: fileUri,
name: 'video.mp4',
type: 'video/mp4',
});
const res = await axios.post('https://api-live.levanbac.io.vn/api/videos/upload', formData, {
headers: {
'X-Api-Key': 'your-secret-api-key-here',
'Content-Type': 'multipart/form-data',
},
onUploadProgress: (e) => {
const percent = Math.round((e.loaded * 100) / e.total);
console.log(`Tiến trình: ${percent}%`);
},
});
console.log('HLS Stream:', res.data.hls_url);
3.6. Cơ Chế Job Tự Động Quản Lý & Đồng Bộ VOD Lên S3 Từ File Gốc (Local Retention & DB Tracking)
Hệ thống tích hợp Background Worker tự động quét và đồng bộ các file video ghi hình MP4 từ máy chủ OvenMediaEngine lên lưu trữ đám mây S3 / MinIO, đồng thời tự động phân đoạn HLS đa phân giải chuẩn bảo mật:
CÁC CẢI TIẾN TRỌNG YẾU (THAY THẾ SCRIPT NGOÀI):
• Bảo toàn file gốc & Quét đa thư mục (Multi-Directory Scanning): Tự động quét toàn bộ các thư mục bản ghi khả dụng trên máy chủ (/opt/ovenmediaengine/recordings, /data/ovenmedia/recordings). File MP4 gốc được giữ nguyên vẹn 100%, tuyệt đối không tự động xóa sau khi upload, đảm bảo an toàn lưu trữ và đối soát.
• Cập nhật Database tức thì (Immediate Persistence): Ngay khi file MP4 hoàn tất tải lên S3, hệ thống lập tức cập nhật trạng thái is_synced = true, synced_at = NOW() vào bảng video_records và bảng videos theo cặp khóa chuẩn stream_key + file_name. Trạng thái không bị gián đoạn hay mất mát kể cả khi quá trình phân đoạn HLS tốn thời gian.
• Dò tìm Audio AAC bằng ffprobe: File video ghi hình OME chứa nhiều audio track (Opus và AAC). Worker tự động phát hiện index chính xác của track AAC để remux HLS (-c copy), kèm cờ -nostdin và timeout an toàn, khắc phục hoàn toàn lỗi mất tiếng khi phát HLS trên trình duyệt Web/Mobile.
• Kích hoạt Worker 2 chế độ: Tự động kích hoạt định kỳ qua Background Worker và ngay khi phiên live kết thúc / stop stream, đồng thời hỗ trợ gọi thủ công theo yêu cầu qua API hoặc nút bấm trên CMS.
• Bắn Webhook recording.completed: Ngay khi file đồng bộ lên S3 và cập nhật VOD thành công, hệ thống tự động phát tán sự kiện Outbound Webhook recording.completed đến tất cả endpoint của bên thứ ba (chứa objectId là Channel ID, mediaId = null, link S3 MP4 & HLS, file_name, file_path và dung lượng file).
API Đồng Bộ Thủ Công VOD Lên S3 (Manual Sync):
POST /api/raw-recordings/sync
Header yêu cầu: X-Api-Key: your-secret-api-key-here
JSON Request Body:
Request
{
"files": [
"default/app/ch_7fb4cacb/20260917110000_20260917112000.mp4"
]
}
JSON Response Mẫu (200 OK):
Response
{
"status": "success",
"message": "Đã đồng bộ thành công 1/1 file lên S3 và lưu vào Database!",
"data": {
"total": 1,
"success_count": 1,
"results": [
{
"file": "default/app/ch_7fb4cacb/20260917110000_20260917112000.mp4",
"status": "success",
"hls_url": "https://s3.exo.io.vn/live-vietlott/hls/default/app/ch_7fb4cacb/20260917110000_20260917112000/playlist.m3u8"
}
]
}
}
API Tra Cứu Danh Sách Bản Ghi Gốc & Trạng Thái Đồng Bộ:
GET /api/raw-recordings
Trả về danh sách bản ghi gốc trên máy chủ. Trường is_synced_s3 chỉ có giá trị true khi file đã thực sự được tải lên S3 và được xác nhận trong cơ sở dữ liệu.
3.8. Cấu Hình Nhà Cung Cấp CDN Phân Phối VOD (Thay Thế Link S3)
Hệ thống cho phép cấu hình Nhà cung cấp CDN (ví dụ: VN Network, Akamai, Cloudflare) trực tiếp từ giao diện Admin. Khi một cấu hình CDN được kích hoạt làm Mặc định VOD, toàn bộ các đường dẫn phát HLS (hls_url, playlist.m3u8) và tải MP4 sẽ tự động thay thế địa chỉ MinIO S3 bằng domain CDN đã cấu hình.
API Quản Lý Nhà Cung Cấp CDN:
GET /api/cdn-providers
Lấy danh sách nhà cung cấp & cấu hình
POST /api/cdn-providers
Tạo mới nhà cung cấp
POST /api/cdn-providers/:id/configs
Thêm cấu hình kết nối CDN
POST /api/cdn-providers/:id/configs/:config_id/set-default
Kích hoạt làm CDN mặc định cho VOD
POST /api/cdn-providers/:id/configs/:config_id/test
Kiểm tra kết nối CDN thời gian thực
Quy Tắc Chuyển Đổi URL Phát VOD:
- Trước khi bật CDN (Origin S3):
https://s3.levanbac.io.vn/live-vietlott/hls/default/app/ch_7fb4/20260918_1000/playlist.m3u8
- Sau khi bật CDN (ví dụ
https://cdnvnw-ori1-ottcore.vtccore.com/):
https://cdnvnw-ori1-ottcore.vtccore.com/hls/default/app/ch_7fb4/20260918_1000/playlist.m3u8
- Cơ chế Fallback: Nếu tắt cấu hình CDN hoặc xóa khỏi hệ thống, backend tự động fallback về link MinIO S3 mặc định mà không làm gián đoạn việc phát video.
3.9. Hướng Dẫn Các Bước Tích Hợp Biên Tập & Cắt Video (Step-by-Step Workflow)
Quy trình trọn gói dành cho đối tác / lập trình viên Web & Mobile App khi tích hợp tính năng biên tập, trích xuất đoạn clip trúng thưởng từ video ghi hình livestream gốc, lấy link HLS phát ngay tức thì và đẩy video lên kênh YouTube:
SƠ ĐỒ 6 BƯỚC TÍCH HỢP TOÀN DIỆN:
1. Quét File Gốc:
GET /api/videos/s3
2. Lấy Video ID:
POST /api/videos/ensure
3. Cắt Video FFmpeg:
POST /api/videos/:id/editor
4. Lắng Nghe SSE (Tùy chọn):
SSE video_trim_status
5. Phát Luồng HLS:
Nhúng hls_url vào Trình phát
6. Đẩy Lên YouTube (Tùy chọn):
POST /api/videos/:id/youtube
BƯỚC 1: Quét Danh Sách File Video Gốc (Raw Recordings Trên S3)
Ứng dụng gọi API này để hiển thị danh sách các file video MP4 ghi hình vừa livestream xong đang lưu trữ trên MinIO S3 (hỗ trợ phân trang và lọc theo phiên live):
GET /api/videos/s3?format=flat&page=1&limit=20
Header: X-Api-Key: your-secret-api-key-here
Hỗ trợ phân trang chuẩn qua page và limit (kèm pagination.total_pages). Có thể truyền thêm ?session_id={liveStreamId} để lấy đích danh video của phiên live vừa kết thúc mà không cần duyệt trang.
Phát nhanh & tự chọn chất lượng (ABR) — khởi động ~1–2 giây
Ngay lúc đồng bộ, video được xếp hàng và worker nền vod_abr_optimizer mã hoá thẳng từ file MP4 local (không tải lại từ S3) thành nhiều chất lượng (≤ độ phân giải gốc: 1080p/720p/480p/360p), segment 2 giây, rồi thay playlist.m3u8 bằng master playlist. hls_url không đổi. Mức 480p đứng đầu master nên Safari, ExoPlayer và hls.js khởi động ở mức nhẹ (segment khoảng 150 KB), rồi tự tăng chất lượng theo băng thông. Mã hoá chạy nền, 1 video mỗi lần, ưu tiên CPU thấp, nên không ảnh hưởng Portal.
Trước Sau tối ưu
Chất lượng 1 mức (bằng nguồn OBS) 1080p / 720p / 480p / 360p (≤ nguồn)
Segment 8–10s, ~2,5 MB 2s, 480p ~150 KB
Khởi động (qua CDN) 3–5 giây ~1–2 giây
hls.js (Web) — cấu hình khuyến nghị cho VOD
const hls = new Hls({ capLevelToPlayerSize: true, abrEwmaDefaultEstimate: 1500000, startFragPrefetch: true });
hls.loadSource(video.hls_url); // giữ nguyên hls_url từ GET /api/videos/s3
hls.attachMedia(videoEl);
// iOS (AVPlayer) / Android (ExoPlayer) / Flutter video_player / react-native-video: truyền thẳng hls_url, player tự ABR
VOD mới được tối ưu tự động. Với VOD cũ, yêu cầu tối ưu từng video (trả 202, chạy nền):
POST /api/videos/abr-optimize
Body: {"hls_url": "..."} · Header: X-Api-Key
Theo dõi hàng đợi (dùng chung mọi server, mỗi video chỉ 1 server xử lý). Trạng thái: pending, running, done, failed (lỗi 3 lần), cancelled (video bị xoá trong lúc mã hoá):
GET /api/videos/abr-jobs?status=running&limit=50
Header: X-Api-Key · Trả data[] + counts
BƯỚC 2: Khởi Tạo / Lấy Video ID Gốc (Ensure Video)
Khi người dùng chọn một file MP4 từ Bước 1, gọi API này để hệ thống tạo hoặc lấy bản ghi Video trong Database và trả về data.id:
POST /api/videos/ensure
Header: X-Api-Key: your-secret-api-key-here
JSON Request Body
{
"object_name": "recordings/default/app/0c8086da-3580-4dc7-9995-cd443c977b7a/20260917071252_20260917071327.mp4",
"public_url": "https://cdn-vod.exo.io.vn/live-vietlott/recordings/default/app/0c8086da-3580-4dc7-9995-cd443c977b7a/20260917071252_20260917071327.mp4",
"size": 20362703
}
JSON Response (200 OK)
{
"status": "success",
"hls_url": "https://cdn-vod.exo.io.vn/live-vietlott/hls/default/app/0c8086da-3580-4dc7-9995-cd443c977b7a/20260917071252_20260917071327/playlist.m3u8",
"data": {
"id": 69,
"title": "20260917071252_20260917071327.mp4",
"stream_key": "0c8086da-3580-4dc7-9995-cd443c977b7a",
"object_name": "recordings/default/app/0c8086da-3580-4dc7-9995-cd443c977b7a/20260917071252_20260917071327.mp4"
}
}
💡 Lưu lại data.id (ví dụ: 69) để truyền vào API cắt video ở Bước 3.
BƯỚC 3: Gọi API Cắt Video Bằng FFmpeg (Tuỳ Chọn Ghi Đè Gốc Hoặc Tạo Mới)
Gửi mốc thời gian bắt đầu (start_time_sec) và kết thúc (end_time_sec) vào ID video gốc. Mặc định hệ thống sẽ **ghi đè video gốc và tự động xóa file gốc cũ trên S3** để tối ưu dung lượng:
POST /api/videos/:id/editor
Header: X-Api-Key: your-secret-api-key-here | :id là ID video gốc (ví dụ: 69)
Tham số Body (JSON) Kiểu Bắt buộc Mặc định Mô tả
start_time_secInteger Có — Giây bắt đầu cắt (ví dụ: 10)
end_time_secInteger Có — Giây kết thúc cắt (ví dụ: 45)
overwrite_originalBoolean Không trueMặc định true: Ghi đè vào video hiện tại và xóa luôn file MP4 gốc cũ cùng thư mục HLS cũ trên S3. Truyền false nếu muốn tạo video mới độc lập.
titleString Không — Tiêu đề video sau khi cắt
descriptionString Không — Mô tả nội dung clip đã cắt
sync_youtubeBoolean Không falseTự động đẩy video lên YouTube ngay sau khi render xong
JSON Response Mẫu (200 OK — Chế độ ghi đè mặc định)
{
"status": "success",
"message": "Đang xử lý cắt và ghi đè video gốc ngầm (file gốc cũ sẽ được xóa khi hoàn tất)",
"data": {
"id": 69,
"mode": "overwrite",
"overwrite_original": true,
"hls_url": "https://cdn-vod.exo.io.vn/live-vietlott/hls/default/app/0c8086da-3580-4dc7-9995-cd443c977b7a/trimmed_69_v2/playlist.m3u8",
"status": "processing"
}
}
QUY TẮC XỬ LÝ BIÊN TẬP & LƯU TRỮ S3:
• Ghi đè & Xóa sạch file cũ (Mặc định overwrite_original: true): Giữ nguyên ID video (69), tăng version lên v2. Sau khi FFmpeg render và upload MP4 + HLS mới thành công, hệ thống tự động xóa vĩnh viễn file MP4 cũ và toàn bộ thư mục HLS cũ trên MinIO S3, giải phóng dung lượng đĩa và làm sạch kho lưu trữ.
• Tạo mới độc lập (overwrite_original: false): Tạo ra bản ghi Video mới độc lập với ID mới (ví dụ: 70), giữ nguyên vẹn 100% video gốc trên S3.
• Phản hồi siêu tốc (< 0.4s): Tính toán trước đường dẫn hls_url chuẩn xác, trả về ngay lập tức cho Client và tiến hành băm HLS ngầm bằng FFmpeg.
• Cập nhật tức thì vào S3 Cache: Cả 2 chế độ đều tự động cập nhật ngay vào bảng s3_file_cache, client gọi GET /api/videos/s3 sẽ thấy file mới ngay lập tức.
BƯỚC 4: Theo Dõi Trạng Thái Cắt Video Qua SSE (Tùy chọn)
Nếu ứng dụng muốn cập nhật trạng thái "Đang cắt..." ➔ "Đã hoàn thành" theo thời gian thực:
JavaScript EventSource (SSE)
const sse = new EventSource('https://api-live.levanbac.io.vn/api/events');
sse.addEventListener('video_trim_status', (e) => {
const data = JSON.parse(e.data);
// data = { video_id: 70, status: "completed", hls_url: "...", trimmed_url: "..." }
if (data.status === 'completed') {
console.log(`✅ Video #${data.video_id} đã hoàn tất cắt và sẵn sàng phát!`);
}
});
BƯỚC 5: Nhúng Đường Dẫn HLS Vào Trình Phát (Web & Mobile App)
Sử dụng data.hls_url nhận được từ Bước 3 để phát luồng trên ứng dụng:
- Web: Khởi tạo qua thư viện
Hls.js (hoặc thẻ <video src="..."> trên Safari iOS).
- Flutter: Khởi tạo
VideoPlayerController.networkUrl(Uri.parse(hlsUrl)).
- React Native: Truyền vào
<Video source={{ uri: hlsUrl }} />.
- Android: Cung cấp URL cho
MediaItem.fromUri(hlsUrl) trên ExoPlayer.
- iOS: Khởi tạo
AVPlayer(url: URL(string: hlsUrl)!).
BƯỚC 6: Đẩy Video Đã Cắt Lên YouTube Bằng ID (Tùy chọn)
Khi muốn đăng tải đoạn video vừa cắt lên kênh YouTube chính thức của đài, chỉ cần truyền ID video vừa cắt vào URL:
POST /api/videos/:id/youtube
Header: X-Api-Key: your-secret-api-key-here | :id là ID video vừa cắt (ví dụ: 70)
JSON Response (200 OK)
{
"status": "success",
"message": "Đã đẩy video lên YouTube thành công",
"data": {
"id": 70,
"youtube_video_id": "8aJkF9zL2xM",
"youtube_url": "https://youtu.be/8aJkF9zL2xM"
}
}
CODE MẪU TRỌN GÓI TOÀN BỘ QUY TRÌNH:
JavaScript (Fetch Full Workflow)
const API_BASE = 'https://api-live.levanbac.io.vn';
const API_KEY = 'your-secret-api-key-here';
const headers = { 'Content-Type': 'application/json', 'X-Api-Key': API_KEY };
async function runVideoEditWorkflow(objectName, publicUrl, size, startSec, endSec, title) {
// Bước 2: Ensure video record & lấy ID gốc
const ensureRes = await fetch(`${API_BASE}/api/videos/ensure`, {
method: 'POST',
headers,
body: JSON.stringify({ object_name: objectName, public_url: publicUrl, size })
});
const { data: sourceVideo } = await ensureRes.json();
console.log(`1️⃣ Video gốc ID: ${sourceVideo.id}`);
// Bước 3: Cắt video FFmpeg Async (trả về video mới ID độc lập)
const trimRes = await fetch(`${API_BASE}/api/videos/${sourceVideo.id}/editor`, {
method: 'POST',
headers,
body: JSON.stringify({
start_time_sec: startSec,
end_time_sec: endSec,
title: title
})
});
const { data: newTrimmedVideo } = await trimRes.json();
console.log(`2️⃣ Video cắt mới ID: ${newTrimmedVideo.id}`);
console.log(`3️⃣ HLS URL phát video: ${newTrimmedVideo.hls_url}`);
// Bước 6 (Tùy chọn): Đẩy lên YouTube
const ytRes = await fetch(`${API_BASE}/api/videos/${newTrimmedVideo.id}/youtube`, {
method: 'POST',
headers: { 'X-Api-Key': API_KEY }
});
const { data: ytData } = await ytRes.json();
console.log(`4️⃣ Đã đẩy YouTube thành công: ${ytData.youtube_url}`);
return newTrimmedVideo;
}
cURL
# Bước 1: Quét danh sách file S3
curl -X GET "https://api-live.levanbac.io.vn/api/videos/s3" \
-H "X-Api-Key: your-secret-api-key-here"
# Bước 2: Khởi tạo/Lấy ID video gốc
curl -X POST "https://api-live.levanbac.io.vn/api/videos/ensure" \
-H "X-Api-Key: your-secret-api-key-here" \
-H "Content-Type: application/json" \
-d '{"object_name":"recordings/default/app/ch_key/video.mp4","public_url":"https://.../video.mp4","size":20362703}'
# Bước 3: Cắt video tạo video mới độc lập (nhận id mới và hls_url)
curl -X POST "https://api-live.levanbac.io.vn/api/videos/69/editor" \
-H "X-Api-Key: your-secret-api-key-here" \
-H "Content-Type: application/json" \
-d '{"start_time_sec":10,"end_time_sec":45,"title":"Clip Jackpot"}'
# Bước 6: Đẩy video đã cắt lên YouTube bằng ID
curl -X POST "https://api-live.levanbac.io.vn/api/videos/70/youtube" \
-H "X-Api-Key: your-secret-api-key-here"
Flutter / Dart
import 'dart:convert';
import 'package:http/http.dart' as http;
class VideoEditorWorkflow {
static const String baseUrl = 'https://api-live.levanbac.io.vn';
static const String apiKey = 'your-secret-api-key-here';
static Future
React Native / Axios
import axios from 'axios';
const api = axios.create({
baseURL: 'https://api-live.levanbac.io.vn',
headers: { 'X-Api-Key': 'your-secret-api-key-here' }
});
export const editAndPushWorkflow = async (objectName, publicUrl, size, startSec, endSec, title) => {
// 1. Ensure video ID
const { data: d1 } = await api.post('/api/videos/ensure', { object_name: objectName, public_url: publicUrl, size });
const sourceId = d1.data.id;
// 2. Cắt video
const { data: d2 } = await api.post(`/api/videos/${sourceId}/editor`, {
start_time_sec: startSec,
end_time_sec: endSec,
title
});
const newVideo = d2.data; // { id: 70, hls_url: '...' }
// 3. Đẩy YouTube
await api.post(`/api/videos/${newVideo.id}/youtube`);
return newVideo;
};
3.10. Upload Video Lớn Theo Phần (S3 Multipart Upload A1–A6)
Dành cho máy chủ CMS Vietlott tải lên các file video lớn theo từng phần (mỗi phần ≥ 5 MiB, mặc định 16 MiB, tối đa 10.000 phần). Khi rớt mạng hoặc khởi động lại chỉ cần tra danh sách phần đã nhận (A4) và gửi tiếp phần còn thiếu.
A1. Tạo phiên upload — POST /api/videos/uploads
Header bắt buộc: X-Api-Key và Idempotency-Key (trùng khoá trả 409 DUPLICATE_REQUEST kèm data của phiên đã tạo).
Request & Response (201 Created)
// POST /api/videos/uploads (Header: X-Api-Key, Idempotency-Key)
{
"title": "Kỳ quay Mega 6/45 #01234",
"description": "Video phát lại kỳ quay",
"public_id": "9df7466c-e934-4585-8bb3-4463af0c6a7d",
"file_name": "ky-quay-01234.mp4",
"file_size": 5368709120,
"content_type": "video/mp4"
}
// Response 201 Created:
{
"status": "success",
"message": "Đã tạo phiên upload",
"data": {
"upload_id": "upl_1776340119_9f3c2a",
"upload_status": "uploading",
"object_name": "recordings/default/app/9df7466c-e934-4585-8bb3-4463af0c6a7d/1776340119_ky-quay-01234.mp4",
"file_size": 5368709120,
"part_size": 16777216,
"part_count": 320,
"expires_at": "2026-11-19T15:00:00+07:00"
}
}
A2 & A3. Cấp Presigned URL & PUT từng phần thẳng lên MinIO
POST /api/videos/uploads/:upload_id/parts
Body: {"part_numbers": [1, 2, 3, 4]} (tối đa 100 số/lần)
Sau khi nhận mảng parts[].url (hạn 1 giờ), CMS gọi PUT <url> với body là dữ liệu nhị phân của phần đó (phần thứ n từ byte (n-1) * part_size, dài part_size byte). Không cần lưu giữ ETag ở phía CMS.
A4. Tra trạng thái phiên & phần đã nhận — GET /api/videos/uploads/:upload_id
Trả về upload_status (uploading | processing | completed | failed | aborted | expired), mảng uploaded_parts: [{ part_number, size, etag }] lấy trực tiếp từ MinIO ListParts, cùng video_id, hls_url, error.
A5. Hoàn tất ghép file & tạo HLS ngầm — POST /api/videos/uploads/:upload_id/complete
Không có request body. Backend tự kiểm tra đủ 1..part_count phần trên MinIO (nếu thiếu trả 400 MISSING_PARTS kèm data.missing_part_numbers), ghép file (CompleteMultipartUpload), tạo bản ghi Video và trả ngay 202 Accepted kèm video_id, object_name, public_url, hls_url. Tiến trình tạo HLS chạy nền và bắn webhook video.upload.started → video.upload.completed / video.upload.failed.
A6. Huỷ phiên upload — DELETE /api/videos/uploads/:upload_id
Gọi AbortMultipartUpload xoá toàn bộ các phần dở dang trên MinIO và đổi trạng thái sang aborted (trả 200 OK idempotent).
3.11. Chuyển Video Giữa Kho Nóng & Kho Lạnh (B1–B4)
Hỗ trợ chuyển toàn bộ các file của video (MP4 gốc, MP4 đã cắt, HLS playlist .m3u8, các segment .ts và các mức chất lượng ABR) giữa Kho nóng (s3.exo.io.vn) và Kho lạnh (openmaxio.vtcmobile.vn, bucket live-vietlott):
Mục Endpoint Mô tả & Hành vi
B1
POST /api/videos/:id/archive
Xếp hàng job chuyển video sang kho lạnh (trả 202 Accepted, storage_status = "archiving"). Trong lúc copy video vẫn phát được; copy xong mới xoá bản ở kho nóng và chuyển sang storage_status = "cold".
B2
POST /api/videos/:id/restore
Xếp hàng job khôi phục video từ kho lạnh về đúng S3 key cũ trên kho nóng (trả 202 Accepted, storage_status = "restoring") để giữ nguyên 100% hls_url và public_url đã gắn trên website/app.
B3
GET /api/videos/storage-jobs
Theo dõi hàng đợi chuyển kho (filter: video_id, action=archive|restore, status=pending|running|done|failed|cancelled, limit) kèm bộ đếm counts.
B4
GET /api/videos/:id
Trả kèm upload_status, upload_error, storage_status (hot | archiving | cold | restoring), storage_error, archived_at trong data và ở ngoài cùng.
CHẶN THAO TÁC KHI Ở KHO LẠNH: Khi video đang ở trạng thái cold hoặc restoring, các API editor, publish, schedule, youtube, batch-sync, abr-optimize sẽ trả về 409 Conflict với "code": "VIDEO_IN_COLD_STORAGE".
4. Tích Hợp Khung Chat Thời Gian Thực
Live Chat hỗ trợ hàng chục ngàn người chat đồng thời qua WebSocket Centrifugo.
4.1. Lấy Token JWT Chat cho Khách 🔒 Yêu cầu API Key
Lấy JWT token kết nối WebSocket và nhận mã viewer_uid riêng biệt cho người xem. Có thể truyền kèm viewer_uid đã lưu từ client (localStorage) hoặc ID người dùng từ app đối tác để giữ nguyên danh tính.
POST /api/chat/token
Header: X-Api-Key: your-secret-api-key-here
JSON Request
{
"display_name": "NguyenVanA",
"viewer_uid": "viewer_68fa12bc (Tùy chọn, bỏ trống để hệ thống tự sinh ngẫu nhiên)"
}
4.2. Gửi Tin Nhắn Chat 🔒 Yêu cầu JWT Token hoặc API Key
Gửi tin nhắn chat vào phòng live stream. Khuyên dùng xác thực bằng JWT Chat Token qua header Authorization: Bearer <token> hoặc field token trong body để khóa danh tính chống giả mạo user_id. Đối tác backend server-to-server có thể xác thực bằng X-Api-Key.
POST /api/chat/send
Header: Authorization: Bearer <jwt_token> (hoặc X-Api-Key: your-secret-api-key-here)
JSON Request
{
"stream_id": 19,
"user_id": "usr_99182312 (Tùy chọn nếu có JWT token)",
"display_name": "NguyenVanA",
"message": "Chúc mọi người may mắn trúng giải!",
"token": "JWT_TOKEN_HERE (Tùy chọn nếu đã gửi trong header Authorization)"
}
🛡️ Bộ lọc từ cấm & tự khoá chat
message và display_name được chuẩn hoá chống lách luật trước khi so khớp: không dấu (dit me), chèn dấu chấm/khoảng trắng (đ.ị.t, đ i t), số/ký hiệu thay chữ (d1t, c@c), lặp chữ (địttttt), viết liền (ditme), teencode đjt, ký tự vô hình. Bộ lọc so theo ranh giới từ nên accept, vlog không bị che nhầm. Từ thông dụng gõ không dấu như cac (các), lon (lon bia) nằm trong whitelist.
HTTP
code
Ý nghĩa
App nên xử lý
200 — (có moderation) Tin đã gửi nhưng từ cấm bị che *** Hiện moderation.warning (cảnh báo lần N/ngưỡng)
403 CHAT_AUTO_MUTEDVi phạm đủ ngưỡng → tự khoá chat tạm thời Khoá ô nhập đến muted_until
403 — Đang bị khoá (thủ công hoặc tự động) Khoá ô nhập, hiện message
429 — Gửi quá nhanh (1 tin/giây) Chờ 1 giây
JSON Response — có từ cấm (vẫn gửi, đã che)
{
"status": "sent",
"moderation": {
"strike": 1,
"strike_limit": 3,
"muted": false,
"warning": "Tin nhắn chứa từ ngữ không phù hợp đã bị che. Cảnh báo 1/3 — vi phạm 3 lần sẽ bị tạm khoá chat 5 phút."
}
}
JSON Response — HTTP 403 tự khoá chat
{
"status": "error",
"code": "CHAT_AUTO_MUTED",
"message": "Bạn bị tạm khoá chat 5 phút do sử dụng từ ngữ không phù hợp 3 lần.",
"muted_until": "2026-11-04T10:35:00+07:00",
"moderation": { "strike": 3, "strike_limit": 3, "muted": true, "mute_minutes": 5, "muted_until": "2026-11-04T10:35:00+07:00" }
}
JavaScript / React Native
const res = await fetch(`${BASE}/api/chat/send`, {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-Api-Key': API_KEY },
body: JSON.stringify({ stream_id, user_id, display_name, message }),
});
const data = await res.json();
if (res.ok && data.moderation?.warning) showToast(data.moderation.warning, 'warning');
if (res.status === 403 && data.code === 'CHAT_AUTO_MUTED') lockChatInputUntil(new Date(data.muted_until));
Flutter (Dart)
final res = await http.post(Uri.parse('$base/api/chat/send'),
headers: {'Content-Type': 'application/json', 'X-Api-Key': apiKey},
body: jsonEncode({'stream_id': streamId, 'user_id': userId, 'display_name': name, 'message': text}));
final data = jsonDecode(res.body);
if (res.statusCode == 200 && data['moderation'] != null) showWarning(data['moderation']['warning']);
if (res.statusCode == 403 && data['code'] == 'CHAT_AUTO_MUTED') lockInputUntil(DateTime.parse(data['muted_until']));
Quản trị bộ lọc (🔒 X-Api-Key): POST /api/chat/bad-words/test (chạy thử), GET|POST|DELETE /api/chat/bad-words/whitelist (chống che nhầm), GET|PUT /api/chat/bad-words/settings (strike_limit mặc định 3, 0 = tắt tự khoá; mute_minutes 5; strike_window_minutes 30). Admin mở khoá sẽ reset bộ đếm vi phạm.
4.3. Lấy Lịch Sử Tin Nhắn Chat & Cuộn Xem Tin Cũ (Infinite Scroll Up) 🔒 Yêu cầu API Key
Lấy danh sách tin nhắn chat của phòng livestream. Hỗ trợ tham số before_id để cuộn lên tải tin nhắn cũ hơn theo mốc ID của tin nhắn đầu tiên đang hiển thị.
Tham số Query
Kiểu
Bắt buộc
Mô tả
stream_id
Integer
Bắt buộc
ID của kênh livestream.
limit
Integer
Tùy chọn
Số lượng tin nhắn mỗi lần tải (mặc định 50, tối đa 200).
before_id
Integer
Tùy chọn
ID tin nhắn mốc để cuộn lên xem tin cũ (lấy các tin có id < before_id). Lấy từ trường id của tin nhắn cũ nhất đang có trên màn hình (messages[0].id).
offset
Integer
Tùy chọn
Số tin nhắn bỏ qua nếu dùng offset pagination.
GET /api/chat/history?stream_id=19&limit=50
Header: X-Api-Key: your-secret-api-key-here
GET /api/chat/history?stream_id=19&before_id=105&limit=50
(Cuộn lên xem tin cũ hơn tin #105)
JSON Response (HTTP 200)
{
"status": "success",
"has_more": true,
"messages": [
{
"id": 105,
"channel_id": 19,
"viewer_uid": "usr_99182312",
"display_name": "NguyenVanA",
"content": "Chúc mọi người may mắn trúng giải!",
"created_at": "2026-09-10T11:00:00Z"
}
]
}
5. Outbound Webhooks (Nhận Sự Kiện Tự Động)
Hệ thống hỗ trợ gửi HTTP POST tự động đến máy chủ của bên thứ ba khi xảy ra các sự kiện trong vòng đời của phiên live và phiên ghi hình (VOD).
5.1. Danh Sách Sự Kiện Được Hỗ Trợ (Supported Events)
Tên Sự Kiện (eventName)
Ý Nghĩa / Mô Tả
Thời Điểm Kích Hoạt
live.started
Bắt đầu livestream
Publisher kết nối thành công và bắt đầu phát sóng
live.paused
Tạm dừng livestream (Chờ kết nối lại 3 phút)
Mất tín hiệu từ OBS đột ngột, hệ thống giữ nguyên sessionId trong 180 giây chờ kết nối lại
live.resumed
Tiếp tục livestream (Kết nối lại thành công)
OBS kết nối lại trong thời gian < 3 phút, tiếp tục phát trên cùng sessionId hiện tại
live.ended
Kết thúc livestream
Phiên livestream dừng hẳn (khi quá 3 phút mất tín hiệu hoặc chủ động gọi API end-live)
live.health_degraded
Cảnh báo tín hiệu không ổn định
Throughput publisher giảm sút trong 2 chu kỳ kiểm tra liên tiếp
recording.started
Bắt đầu ghi phiên live
Xác nhận record đã hoạt động và bắt đầu ghi hình vào ổ đĩa
recording.interrupted
Record bị gián đoạn
Mất tín hiệu publisher hoặc mạng chập chờn. Cảnh báo file có thể bị chia đoạn
recording.resumed
Record tiếp tục
Tín hiệu phục hồi sau khi gián đoạn, luồng ghi tiếp tục bình thường
recording.completed
Hoàn thành file record thô
Media Server hoàn thành ghi file MP4 thô trên đĩa. Bắt đầu pipeline xử lý VOD
recording.failed
Record thất bại
Gặp lỗi ghi hình hoặc không tìm thấy file ghi hình hoàn chỉnh sau phiên live
youtube.upload.queued
Tạo job upload YouTube
Tạo job upload YouTube thành công, video được xếp hàng chờ xử lý đẩy lên YouTube
youtube.upload.completed
Upload YouTube hoàn tất
Đã tải video lên YouTube thành công, có ID và URL video YouTube chính thức
youtube.upload.failed
Upload YouTube thất bại
Quá trình upload hoặc cập nhật metadata video lên YouTube gặp lỗi
video.edit.started
Bắt đầu cắt / biên tập video
Bắt đầu chạy FFmpeg cắt video (currentStage: "started", canWatchVod: false)
video.edit.completed
Hoàn tất cắt / biên tập video
Đã cắt xong, tạo HLS và đẩy lên S3 thành công (currentStage: "completed", canWatchVod: true)
video.edit.failed
Cắt / biên tập video thất bại
Quá trình cắt video gặp lỗi, bản gốc được giữ nguyên (currentStage: "failed", canWatchVod: false)
video.upload.started
Bắt đầu tạo HLS sau upload theo phần (A5)
Đã ghép xong các phần trên MinIO, bắt đầu chạy nền tạo HLS (currentStage: "started", canWatchVod: false)
video.upload.completed
Hoàn tất tạo HLS sau upload theo phần
Đã tạo xong HLS, video sẵn sàng phát (currentStage: "completed", canWatchVod: true)
video.upload.failed
Tạo HLS sau upload theo phần thất bại
File upload hỏng hoặc lỗi FFmpeg khi tạo HLS (currentStage: "failed", canWatchVod: false)
video.archive.started
Bắt đầu chuyển video sang kho lạnh
Job archive bắt đầu copy sang kho lạnh; trong lúc copy bản kho nóng vẫn phát được (currentStage: "started", canWatchVod: true)
video.archive.completed
Đã chuyển xong video sang kho lạnh
Đã copy xong sang openmaxio.vtcmobile.vn và xóa bản kho nóng (currentStage: "completed", canWatchVod: false)
video.archive.failed
Chuyển kho lạnh thất bại
Archive lỗi sau 3 lần thử, video vẫn giữ nguyên ở kho nóng (currentStage: "failed", canWatchVod: true)
video.restore.started
Bắt đầu khôi phục video về kho nóng
Job restore bắt đầu chép file từ kho lạnh về kho nóng (currentStage: "started", canWatchVod: false)
video.restore.completed
Đã khôi phục xong video về kho nóng
Video đã về đúng S3 key cũ trên kho nóng, sẵn sàng phát và biên tập (currentStage: "completed", canWatchVod: true)
video.restore.failed
Khôi phục về kho nóng thất bại
Restore lỗi sau 3 lần thử, video vẫn ở kho lạnh (currentStage: "failed", canWatchVod: false)
Cơ chế giám sát tín hiệu (Health Check):
CMS định kỳ kiểm tra throughput từ OvenMediaEngine theo mã luồng streamKey. Hệ thống áp dụng thuật toán kiểm tra kép kết hợp giữa lastThroughputIn và avgThroughputIn để loại bỏ hiện tượng cảnh báo sai khi có độ trễ khung hình I-frame. Ngưỡng an toàn là 50 KB/s (~400 kbps) và yêu cầu 2 chu kỳ liên tiếp (60s) mới kích hoạt cảnh báo live.health_degraded. Khi tín hiệu phục hồi, sự kiện recording.resumed sẽ tự động khôi phục trạng thái.
5.2. Cấu Trúc Payload JSON Chuẩn
Mọi sự kiện webhook đều được gửi dưới dạng JSON với cấu trúc thống nhất:
Định danh phiên live (liveStreamId = sessionId):
Trong tất cả 11 sự kiện Webhook (từ live.started, recording.* cho đến youtube.upload.*), trường data.liveStreamId luôn được gán chính xác bằng sessionId của phiên livestream. Bên thứ 3 có thể dùng trực tiếp liveStreamId này để đối soát và tra cứu lịch sử phiên live qua API GET /api/sessions/:id hoặc GET /api/analytics/livestream/:session_id.
Webhook Standard JSON Payload
{
"version": "1.0",
"eventTime": 1789634567890,
"eventId": "evt_1789634567890123456",
"eventName": "recording.completed",
"objectType": "livestream",
"objectId": 19,
"provider": null,
"data": {
"streamKey": "7fb4cacb4a4c893d5a0be963e5dc6246",
"liveStreamId": 142,
"mediaId": null,
"fileName": "20260917110000_20260917112000.mp4",
"mediaFileName": "/data/recordings/default/app/ch_7fb4cacb/20260917110000_20260917112000.mp4",
"format": "mp4",
"durationSeconds": 1200,
"sizeBytes": 154829104,
"currentStage": "completed",
"targetId": 19,
"targetData": {
"channel_id": 19,
"channel_name": "Kênh Vietlott 1",
"public_id": "9df7466c-e934-4585-8bb3-4463af0c6a7d",
"file_path": "/data/recordings/default/app/ch_7fb4cacb/20260917110000_20260917112000.mp4",
"stage": "completed",
"message": "Media Server hoàn thành file record thô. Bắt đầu pipeline xử lý VOD"
},
"externalUrl": "https://s3.exo.io.vn/live-vietlott/hls/default/app/ch_7fb4cacb/file/playlist.m3u8"
}
}
5.3. Xác Thực Webhook Bằng API Key
Khi Webhook Endpoint được cấu hình api_key, mỗi request gửi đi từ CMS sẽ đính kèm trực tiếp api_key vào HTTP Header: api-key: {api_key} và X-API-Key: {api_key}. Phía server bên thứ ba chỉ cần kiểm tra giá trị api-key / X-API-Key trong header để xác thực:
Node.js / Express Verify API Key Example
app.post('/webhook-receiver', express.json(), (req, res) => {
const apiKey = req.headers['api-key'] || req.headers['x-api-key'];
const expectedKey = 'your-configured-webhook-api-key';
if (!apiKey || apiKey !== expectedKey) {
return res.status(401).json({ status: 'error', message: 'Invalid API Key' });
}
const payload = req.body;
console.log('Received event:', payload.eventName, payload.data);
res.status(200).json({ status: 'ok' });
});
5.4. Cơ Chế Bắn Bù Event & Chống Mất Webhook Khi Server Khởi Động Lại
Hệ thống áp dụng kiến trúc Transactional Outbox & Event Recovery lưu bền vững vào MariaDB (bảng webhook_deliveries & pending_event_tasks):
- Bắn bù tự động khi gửi thất bại / restart giữa chừng: Mọi event đều được ghi xuống DB trước khi gửi HTTP POST (giữ nguyên header
api-key & X-API-Key). Nếu server restart khi đang gửi hoặc endpoint bên thứ ba tạm lỗi (HTTP 5xx/timeout), worker tự động gửi bù theo cấp số nhân (5s → 15s → 30s → 1m → 3m → 5m → 10m → 20m → 30m).
- Khôi phục tác vụ bất đồng bộ bị ngắt: Các luồng chờ kết thúc phiên (
live.paused → live.ended), gộp file MP4, tạo HLS (recording.completed, video.edit.*, video.upload.*), đẩy YouTube (youtube.upload.*) và hẹn xoá file cũ sau overwrite được tự động nối tiếp & bắn bù ngay sau khi server bật lại.
GET /api/webhooks/deliveries?status=pending&limit=50
Xem hàng đợi & lịch sử bắn bù Webhook (🔒 X-Api-Key)
POST /api/webhooks/deliveries/replay
Kích hoạt bắn bù ngay (Body tuỳ chọn: {"delivery_id": 12, "event_name": "live.ended"})
6. Cấu Hình & Tích Hợp Đồng Bộ YouTube (OAuth 2.0 & VOD Sync)
Hệ thống CMS Livestream Vietlott tích hợp sẵn module đồng bộ hóa video VOD tự động lên kênh YouTube thông qua YouTube Data API v3 chuẩn bảo mật Google OAuth 2.0 (Authorization Code Flow). Tính năng này cho phép bên thứ ba tự động đăng tải video quay số mở thưởng, quản lý trạng thái xuất bản, hẹn giờ phát sóng và theo dõi tiến trình upload thời gian thực.
Luồng hoạt động tổng thể (Workflow Overview):
- Khởi tạo ứng dụng Google: Tạo OAuth 2.0 Client ID trên Google Cloud Console với Redirect URI trỏ về
/api/youtube/callback.
- Khai báo Credentials: Lưu
Client ID & Client Secret vào CMS qua giao diện hoặc API POST /api/integrations/settings.
- Xác thực ủy quyền (OAuth2): Lấy URL từ
GET /api/youtube/auth-url, chủ kênh YouTube thực hiện đăng nhập và cấp quyền youtube.upload.
- Lưu trữ Token an toàn: CMS tự động nhận authorization code, đổi lấy Access Token & Refresh Token, tự động gia hạn token vĩnh viễn trong Database.
- Đồng bộ VOD tự động: Khi kết thúc phiên live, pipeline cắt dựng VOD tự động đẩy video lên YouTube kèm tiêu đề, mô tả, tags và hẹn giờ phát sóng.
- Theo dõi tiến trình qua SSE: Lắng nghe event
youtube_sync_progress và nhận link YouTube hoàn tất qua youtube_sync_success.
6.1. Hướng Dẫn Thiết Lập Trên Google Cloud Console
Trước khi kết nối, đơn vị phát triển bên thứ ba hoặc bộ phận vận hành cần tạo ứng dụng xác thực trên Google Cloud Console theo 4 bước sau:
1
Tạo Project & Bật API
Truy cập Google Cloud Console → Tạo project mới → Vào APIs & Services > Library → Tìm và bấm Enable cho YouTube Data API v3.
2
Cấu Hình Màn Hình Đồng Ý
Vào OAuth consent screen → Chọn External → Điền App Name & Email → Thêm scopes: .../auth/youtube.upload, .../auth/youtube → Thêm email kênh vào Test users.
3
Tạo OAuth Client ID
Vào Credentials → Create Credentials → OAuth client ID → Chọn Web application → Đặt tên ứng dụng (ví dụ: CMS Livestream YouTube).
4
Khai Báo Redirect URI
Tại mục Authorized redirect URIs, thêm đường dẫn callback chính xác: https://<domain-cms>/api/youtube/callback → Nhấn Create để nhận Client ID và Client Secret.
6.2. Danh Sách REST API Quản Lý Kết Nối YouTube
POST
/api/integrations/settings
X-Api-Key Required
Lưu trực tiếp Google Client ID & Secret vào cơ sở dữ liệu CMS (bên thứ ba có thể cấu hình tự động mà không cần sửa file môi trường). Các trường bỏ qua hoặc truyền chuỗi rỗng (bao gồm chat_bad_words) sẽ được giữ nguyên, không ghi đè dữ liệu hiện có trong hệ thống:
Request Body JSON
{
"youtube_client_id": "1234567890-abcdef123456.apps.googleusercontent.com",
"youtube_client_secret": "GOCSPX-xxxxxxYourClientSecretHere",
"youtube_redirect_uri": "https://api-live.levanbac.io.vn/api/youtube/callback"
}
GET
/api/youtube/auth-url
X-Api-Key Required
Sinh đường dẫn URL ủy quyền Google OAuth2 với đầy đủ quyền upload và tự động refresh token:
Response JSON (200 OK)
{
"status": "success",
"data": {
"auth_url": "https://accounts.google.com/o/oauth2/auth?access_type=offline&client_id=1234567890-abcdef.apps.googleusercontent.com&prompt=consent&redirect_uri=https%3A%2F%2Fapi-live.levanbac.io.vn%2Fapi%2Fyoutube%2Fcallback&response_type=code&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.upload+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube+https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email&state=state"
}
}
GET
/api/youtube/callback?code={authorization_code}
Public Webhook
Tiếp nhận authorization code từ Google sau khi chủ kênh hoàn tất xác thực. Backend CMS tự động trao đổi lấy token, xác định YouTube Channel ID thật và redirect người dùng về CMS Studio.
GET
/api/youtube/status
X-Api-Key Required
Kiểm tra trạng thái kết nối YouTube hiện tại của hệ thống:
Response JSON (200 OK)
{
"status": "success",
"is_connected": true,
"data": {
"channel_name": "Vietlott - Xổ Số Tự Chọn",
"email": "channel-owner@gmail.com",
"youtube_channel_id": "UCxxxxxxYourChannelID",
"is_connected": true
}
}
DELETE
/api/integrations/disconnect/youtube
X-Api-Key Required
Hủy liên kết tài khoản YouTube và xóa sạch Access/Refresh Token khỏi hệ thống.
6.3. Tự Động Xuất Bản & Đồng Bộ Video VOD Lên YouTube
Cách 1: Tự động hóa khi tạo/chỉnh sửa bản ghi VOD (Automatic Sync)
Khi gửi payload tạo hoặc cập nhật video (POST /api/videos hoặc PUT /api/videos/:id), bật cờ sync_youtube: true. Hệ thống sẽ tự động tải file MP4 từ MinIO/S3 và đẩy lên YouTube theo chế độ Resumable Upload:
POST /api/videos
{
"title": "Trực Tiếp Quay Số Vietlott Keno Kỳ #01289 - 17/09/2026",
"description": "Chương trình phát sóng trực tiếp kết quả quay số mở thưởng Keno Vietlott.",
"tags": "vietlott, keno, xoso, livestream",
"channel_id": 19,
"sync_youtube": true,
"scheduled_at": "2026-09-17T18:30:00Z"
}
Cách 2: Kích hoạt đồng bộ hàng loạt / thủ công qua API (Batch Sync)
POST
/api/videos/batch-sync
X-Api-Key Required
Request Body JSON
{
"video_ids": [142],
"platforms": ["youtube"]
}
6.4. Theo Dõi Tiến Trình Upload Real-time Qua Server-Sent Events (SSE)
Bên thứ ba có thể theo dõi tiến trình upload video lên YouTube theo thời gian thực bằng cách kết nối vào luồng SSE tại GET /api/events:
JavaScript EventSource Example
const eventSource = new EventSource('https://api-live.levanbac.io.vn/api/events');
// 1. Lắng nghe tiến độ upload (% hoàn thành)
eventSource.addEventListener('youtube_sync_progress', (e) => {
const data = JSON.parse(e.data);
console.log(`Video #${data.video_id} đang tải lên YouTube: ${data.progress}%`);
});
// 2. Lắng nghe thông báo upload thành công
eventSource.addEventListener('youtube_sync_success', (e) => {
const data = JSON.parse(e.data);
console.log(`✅ Upload YouTube thành công! Video #${data.video_id}`);
console.log(`🔗 Link YouTube: ${data.youtube_url}`);
console.log(`🆔 Video ID: ${data.youtube_video_id}`);
});
// 3. Lắng nghe khi có lỗi upload
eventSource.addEventListener('youtube_sync_error', (e) => {
const data = JSON.parse(e.data);
console.error(`❌ Lỗi đồng bộ YouTube video #${data.video_id}:`, data.error);
});
6.4. Đẩy Trực Tiếp Hoặc Cập Nhật Đồng Bộ Video Lên YouTube
Khi bên thứ ba hoặc client muốn đẩy video lên YouTube hoặc đồng bộ lại thông tin tiêu đề/mô tả sau khi biên tập, truyền ID video trong URL path. Hệ thống sẽ tạo job upload ngầm, bắn ngay Outbound Webhook event youtube.upload.queued và trả về phản hồi 200 OK. Quá trình tải lên được thực hiện trong background và khi hoàn tất sẽ phát webhook youtube.upload.completed (hoặc youtube.upload.failed nếu lỗi):
POST /api/videos/:id/youtube
Header: X-Api-Key: your-secret-api-key-here | Hỗ trợ JSON Body: {"title": "...", "description": "..."}
JSON Response (200 OK)
{
"status": "success",
"message": "Tạo job upload YouTube thành công",
"event": "youtube.upload.queued",
"data": {
"id": 70,
"title": "Kỳ quay thưởng Vietlott Power 6/55 - Ngày 28/09/2026",
"youtube_video_id": "8aJkF9zL2xM",
"youtube_url": "https://youtu.be/8aJkF9zL2xM",
"youtube_sync_status": "syncing",
"event": "youtube.upload.queued"
}
}
Code Mẫu Tích Hợp Đẩy YouTube:
JavaScript (Fetch)
const res = await fetch('https://api-live.levanbac.io.vn/api/videos/70/youtube', {
method: 'POST',
headers: { 'X-Api-Key': 'your-secret-api-key-here' }
});
const { data } = await res.json();
console.log('YouTube Link:', data.youtube_url);
cURL
curl -X POST "https://api-live.levanbac.io.vn/api/videos/70/youtube" \
-H "X-Api-Key: your-secret-api-key-here"
Flutter / Dart
final res = await http.post(
Uri.parse('https://api-live.levanbac.io.vn/api/videos/70/youtube'),
headers: {'X-Api-Key': 'your-secret-api-key-here'},
);
final data = jsonDecode(res.body)['data'];
print('YouTube URL: ${data['youtube_url']}');
React Native / Axios
const res = await axios.post('https://api-live.levanbac.io.vn/api/videos/70/youtube', null, {
headers: { 'X-Api-Key': 'your-secret-api-key-here' }
});
console.log('YouTube URL:', res.data.data.youtube_url);
7. Nhật Ký Hệ Thống & Giám Sát Console (System Service Logs API)
Giám sát Realtime không cần SSH: Hệ thống tự động gom toàn bộ luồng console stdout/stderr từ backend Go, Gin HTTP routes, Worker đồng bộ VOD S3, FFMPEG HLS và Outbound Webhooks vào bộ nhớ đệm In-Memory Ring Buffer (tối đa 5.000 dòng). Admin có thể xem trực tiếp trên CMS hoặc bên thứ ba có thể truy vấn qua REST API / SSE.
7.1. Truy Vấn Danh Sách Logs (REST API)
Lấy danh sách các dòng log gần nhất kèm bộ lọc cấp độ hoặc tìm kiếm từ khóa:
GET /api/system/logs
GET
// Headers yêu cầu:
// X-Api-Key: YOUR_API_KEY (hoặc ?api_key=...)
// Ví dụ: Lấy 300 dòng log gần nhất chứa từ khóa "s3"
GET https://api-live.levanbac.io.vn/api/system/logs?limit=300&search=s3&level=SYNC
// Response JSON (200 OK):
{
"status": "success",
"data": {
"logs": [
{
"id": 1052,
"timestamp": "2026-09-18T09:30:15.123Z",
"time_str": "2026-09-18 09:30:15.123",
"level": "SYNC",
"message": "✅ Đã đồng bộ VOD lên S3: stream_key=ch_7fb4, file=sample.mp4",
"raw": "2026/09/18 09:30:15 ✅ Đã đồng bộ VOD lên S3: stream_key=ch_7fb4, file=sample.mp4"
}
],
"total": 1,
"stats": {
"total_in_memory": 450,
"errors": 0,
"warnings": 1,
"active_streams": 1
}
}
}
7.2. Stream Nhật Ký Thời Gian Thực (SSE Live Tail)
Tương tự lệnh tail -f hoặc docker logs -f, client có thể kết nối Server-Sent Events (SSE) để nhận log ngay tức thì:
JavaScript Server-Sent Events Example
SSE
const apiKey = 'YOUR_API_KEY';
const eventSource = new EventSource(`https://api-live.levanbac.io.vn/api/system/logs/stream?api_key=${apiKey}`);
eventSource.addEventListener('log', (e) => {
const logEntry = JSON.parse(e.data);
console.log(`[${logEntry.time_str}] [${logEntry.level}] ${logEntry.raw}`);
});
eventSource.onerror = (err) => {
console.error('Mất kết nối log stream, trình duyệt sẽ tự thử lại...', err);
};
7.3. Tải File Log & Xóa Bộ Nhớ Đệm
- Tải file log (.log):
GET /api/system/logs/download?limit=5000&api_key=YOUR_API_KEY
- Xóa bộ đệm RAM:
POST /api/system/logs/clear (Cần header X-Api-Key)
8. Mã Mẫu Tích Hợp (SDK Code Samples)
JavaScript + Hls.js Example
// 1. Khởi tạo Device ID cố định trong localStorage
function getDeviceId() {
let id = localStorage.getItem('app_device_id');
if (!id) {
id = 'web-' + Math.random().toString(36).substring(2, 12) + Date.now().toString(36);
localStorage.setItem('app_device_id', id);
}
return id;
}
const API_BASE = 'https://api-live.levanbac.io.vn';
const CHANNEL_ID = 19;
let heartbeatTimer = null;
// 2. Mở luồng & Bắt đầu gửi Heartbeat mỗi 8s
async function startPlayback() {
const res = await fetch(`${API_BASE}/api/channels/${CHANNEL_ID}/watch`);
const { data } = await res.json();
const video = document.getElementById('myVideoPlayer');
if (Hls.isSupported()) {
const hls = new Hls();
hls.loadSource(data.playback.hls_url);
hls.attachMedia(video);
video.play();
}
// Gửi heartbeat định kỳ 8 giây
sendHeartbeat();
heartbeatTimer = setInterval(sendHeartbeat, 8000);
}
function sendHeartbeat() {
fetch(`${API_BASE}/api/channels/${CHANNEL_ID}/viewers/heartbeat`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ viewer_uid: getDeviceId() })
}).catch(() => {});
}
// 3. Thoát hoặc đóng tab -> Báo server giảm view tức thì
function stopPlayback() {
if (heartbeatTimer) clearInterval(heartbeatTimer);
const url = `${API_BASE}/api/channels/${CHANNEL_ID}/viewers/leave`;
const payload = JSON.stringify({ viewer_uid: getDeviceId() });
if (navigator.sendBeacon) {
navigator.sendBeacon(url, new Blob([payload], { type: 'application/json' }));
} else {
fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: payload, keepalive: true });
}
}
window.addEventListener('beforeunload', stopPlayback);
Flutter / Dart Class
import 'dart:async';
import 'dart:convert';
import 'package:http/http.dart' as http;
import 'package:shared_preferences/shared_preferences.dart';
class VietlottLivestreamSDK {
static const String baseUrl = 'https://api-live.levanbac.io.vn';
final int channelId;
Timer? _timer;
String? _deviceId;
VietlottLivestreamSDK({required this.channelId});
Future _getDeviceId() async {
if (_deviceId != null) return _deviceId!;
final prefs = await SharedPreferences.getInstance();
_deviceId = prefs.getString('vietlott_device_uid');
if (_deviceId == null) {
_deviceId = 'flutter-${DateTime.now().millisecondsSinceEpoch}';
await prefs.setString('vietlott_device_uid', _deviceId!);
}
return _deviceId!;
}
// Khởi động Player & Gửi Heartbeat
Future startLive() async {
final res = await http.get(Uri.parse('$baseUrl/api/channels/$channelId/watch'));
final json = jsonDecode(res.body);
final hlsUrl = json['data']['playback']['hls_url'];
_sendHeartbeat();
_timer = Timer.periodic(const Duration(seconds: 8), (_) => _sendHeartbeat());
return hlsUrl;
}
Future _sendHeartbeat() async {
final uid = await _getDeviceId();
await http.post(
Uri.parse('$baseUrl/api/channels/$channelId/viewers/heartbeat'),
headers: {'Content-Type': 'application/json'},
body: jsonEncode({'viewer_uid': uid}),
);
}
// Dừng phát & Báo thoát tức thì
Future dispose() async {
_timer?.cancel();
final uid = await _getDeviceId();
await http.post(
Uri.parse('$baseUrl/api/channels/$channelId/viewers/leave'),
headers: {'Content-Type': 'application/json'},
body: jsonEncode({'viewer_uid': uid}),
);
}
}
React Native TypeScript Hook
import { useEffect, useRef } from 'react';
import AsyncStorage from '@react-native-async-storage/async-storage';
const API_BASE = 'https://api-live.levanbac.io.vn';
export const useViewerHeartbeat = (channelId: number) => {
const timerRef = useRef(null);
const getUid = async () => {
let uid = await AsyncStorage.getItem('vietlott_device_uid');
if (!uid) {
uid = 'rn-' + Math.random().toString(36).substring(2) + Date.now();
await AsyncStorage.setItem('vietlott_device_uid', uid);
}
return uid;
};
const sendHeartbeat = async () => {
const uid = await getUid();
fetch(`${API_BASE}/api/channels/${channelId}/viewers/heartbeat`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ viewer_uid: uid }),
}).catch(() => {});
};
const sendLeave = async () => {
const uid = await getUid();
fetch(`${API_BASE}/api/channels/${channelId}/viewers/leave`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ viewer_uid: uid }),
}).catch(() => {});
};
useEffect(() => {
sendHeartbeat();
timerRef.current = setInterval(sendHeartbeat, 8000);
return () => {
if (timerRef.current) clearInterval(timerRef.current);
sendLeave();
};
}, [channelId]);
};
8. Bảng Mã Lỗi (HTTP Status Codes)
Mã HTTP
Ý nghĩa
Giải thích & Hướng xử lý
200 OK
Thành công
Yêu cầu đã được xử lý chính xác
404 Not Found
Không tìm thấy
Kênh không tồn tại hoặc ID kênh không đúng
401 Unauthorized
Không có quyền
Thiếu hoặc sai X-Api-Key khi gọi các endpoint quản trị
429 Rate Limit
Quá nhiều yêu cầu
Gửi tin nhắn chat vượt quá 5 tin / 10s
400 INVALID_REQUEST
Thiếu/sai tham số
Kiểm tra lại các trường bắt buộc (Idempotency-Key, title, file_size, content_type...)
400 CHANNEL_NOT_FOUND
Sai public_id
Không tìm thấy kênh ứng với public_id đã truyền
400 PART_NUMBER_OUT_OF_RANGE
Sai thứ tự phần
part_number nằm ngoài khoảng 1..part_count
400 MISSING_PARTS
Chưa đủ phần khi hoàn tất
Kiểm tra mảng data.missing_part_numbers và upload bổ sung các phần còn thiếu
404 UPLOAD_NOT_FOUND / VIDEO_NOT_FOUND
Không tìm thấy phiên / video
Kiểm tra lại upload_id hoặc video_id
409 DUPLICATE_REQUEST
Trùng Idempotency-Key
Yêu cầu đã được xử lý trước đó; kết quả của lần gọi trước được trả lại trong data
409 INVALID_STATE
Trạng thái phiên không hợp lệ
Phiên upload đã bị huỷ (aborted) hoặc đã hoàn tất ghép file
409 VIDEO_ALREADY_PROCESSING
Video đang bận xử lý
Video đang tạo HLS, cắt FFmpeg, tối ưu ABR hoặc đang chuyển/khôi phục kho
409 VIDEO_IN_COLD_STORAGE
Video đang ở kho lạnh
Gọi POST /api/videos/:id/restore và đợi hoàn tất trước khi biên tập / xuất bản / đồng bộ
410 UPLOAD_EXPIRED
Phiên upload hết hạn
Khởi tạo phiên upload mới qua POST /api/videos/uploads
413 FILE_TOO_LARGE
Vượt dung lượng tối đa
File vượt ngưỡng cho phép (mặc định 50 GiB)