Streaming API

Streaming API cho phép client gửi audio liên tục theo thời gian thực (realtime) qua WebSocket và nhận kết quả nhận dạng ngay lập tức (thời gian phản hồi trung bình ~ 500ms, tối đa 1s)

Tóm tắt luồng hoạt động

1. Kết nối WebSocket

2. Gửi cấu hình khởi tạo

3. Xác nhận từ hệ thống

4. Gửi dữ liệu âm thanh liên tục

5. Nhận kết quả theo thời gian thực

6. Thông báo khi hoàn tất gửi audio

7. Nhận kết quả cuối và kết thúc

Bước 1: Kết nối WebSocket

Client tạo kết nối WebSocket với API:

wss://api.vbee.vn/api/v1/stt/streaming?token=<access-token>&appId=<app-id>

Nếu token không hợp lệ → kết nối sẽ bị đóng ngay.

Bước 2: Gửi cấu hình khởi tạo (StreamingConfig)

Sau khi kết nối thành công, client bắt buộc gửi 1 message cấu hình bao gồm các tham số:

Tham số	Kiểu dữ liệu	Tính bắt buộc	Mô tả
sampleRateHertz	integer	Có	Tần số lấy mẫu (8000 hoặc 16000 Hz)
sampleSizeByte	integer	Có	Số byte mỗi sample (luôn = 2)
channel	integer	Có	Số kênh (chỉ hỗ trợ 1 – mono)
interimResults	boolean	Không	Nhận kết quả tạm thời khi đang nói Giá trị mặc định: false
sessionId	string	Không	Session ID tự đặt để tracking/debug
vadConfig.noInputTimeoutMs	integer	Không	Timeout (ms) nếu không phát hiện âm thanh. Range: 3000–10000
vadConfig.speechCompleteTimeoutMs	integer	Không	Thời gian im lặng (ms) để xác định hết câu. Range: 500–3000

Sau khi gửi config, cần chờ server trả về READY rồi mới gửi audio.

Bước 3: Xác nhận từ hệ thống (READY)

Server trả về sau khi sẵn sàng nhận audio:

{

"type": "READY",

"sessionId": "abc123"

}

Bước 4: Gửi dữ liệu âm thanh liên tục (AudioChunk)

Client gửi audio liên tục dưới dạng chunk:

{

"type": "AudioChunk",

"audioContent": "<base64-audio>"

}

Yêu cầu audio:

• Format: Raw PCM (không có WAV header)

• 16-bit, mono

• Sample rate phải khớp với config

Khuyến nghị:

• Gửi mỗi 80–100ms audio / lần

• Gửi đều để đảm bảo chất lượng nhận dạng

Bước 5: Nhận kết quả theo thời gian thực

5.1. Kết quả tạm thời (InterimResult)

Kết quả trả về trong lúc người dùng đang nói, có thể thay đổi liên tục và không phải kết quả cuối cùng.

Các kết quả nhận được như sau:

Tham số	Kiểu dữ liệu	Mô tả
text	string	Văn bản tạm thời, sẽ thay đổi ở interim tiếp theo
isFinal	boolean	Luôn là false
stability	float	Mức độ ổn định 0.0–1.0. Cao = ít thay đổi hơn
startTime	float	Thời điểm bắt đầu utterance (giây) trong stream
endTime	float	Thời điểm kết thúc tạm thời (giây) — tăng dần
startVoiceTime	float	Thời điểm phát hiện giọng nói bắt đầu
endVoiceTime	float	Thời điểm phát hiện giọng nói kết thúc tạm thời

5.2. Kết quả chính thức (FinalResult)

Kết quả trả về khi kết thúc một câu, là kết quả cuối cùng và không thay đổi.

Các kết quả nhận được như sau:

Tham số	Kiểu dữ liệu	Mô tả
text	string	Văn bản chính thức, đã qua hậu xử lý
textRaw	string	Văn bản thô chưa xử lý
isFinal	boolean	Luôn là true
confidenceScore	float	Độ tin cậy 0.0 – 1.0
startTime	float	Thời điểm bắt đầu utterance (giây)
endTime	float	Thời điểm kết thúc tạm thời (giây)
speechType	string	detected-speech: có tiếng nói no-speech: không có tiếng nói
status	string	SUCCESS hoặc FAILURE

Bước 6: Thông báo khi hoàn tất gửi audio (DONE)

Gửi sau khi truyền hết toàn bộ audio

{

"type": "Done"

}

Bước 7: Nhận kết quả cuối và kết thúc (StreamEnd)

Gửi sau khi server xử lý xong Done signal và đã gửi FinalResult cuối. Server sẽ đóng kết nối sau message này.

• sessionId: Session ID của session vừa kết thúc

• totalWords: Tổng số utterance đã nhận dạng trong session

Khi session vượt quá 90 giây sẽ nhận được:

• type: ERROR

• code: SESSION_TIMEOUT

• message: Session exceeded maximum duration