Files
esp32-server/app/xiaozhi/protocol.py
T
Macky b8950b38a4 feat: Phase 1 testable bridge skeleton (18 tests green)
Xiaozhi WebSocket endpoint with handshake/auth, mock STT/TTS/Hermes
backends, Thai chunker, barge-in queue, latency logger, GPU planner,
voice-profile guard (reasoning=none, session_search only).

CON-002: no GPU/audio libs loaded at import. MUST-NOT-001: all model
names/tokens from config.
2026-10-03 11:45:31 +07:00

67 lines
2.2 KiB
Python

"""Xiaozhi WebSocket handshake frame models (PoC).
CON-004: the exact field set of the Xiaozhi ``hello`` frame is a firmware
detail. These models capture the fields the plan names (Device-Id,
Client-Id, Authorization, audio_params) plus the standard handshake fields.
Every constant that must match the firmware is marked ``# FIRMWARE``.
"""
from __future__ import annotations
from typing import Any, Optional
from pydantic import BaseModel, Field
class AudioParams(BaseModel):
# FIRMWARE: Opus params the device reports/accepts.
format: str = "opus"
sample_rate: int = 16000
channels: int = 1
frame_duration: int = 20 # ms
class Hello(BaseModel):
"""Device -> Bridge greeting (first text frame)."""
type: str = "hello"
device_id: str
client_id: Optional[str] = None
authorization: Optional[str] = None # FIRMWARE: token field name
protocol_version: int = 1 # FIRMWARE
audio_params: AudioParams = Field(default_factory=AudioParams)
class HelloReply(BaseModel):
"""Bridge -> Device acknowledgement (keeps the session conversational)."""
type: str = "hello"
protocol_version: int = 1
server_time: int = 0
session_id: str = ""
audio_params: AudioParams = Field(default_factory=AudioParams)
# FIRMWARE: some firmwares expect a "name"/"text" greeting.
text: str = ""
def build_hello(payload: dict) -> Hello:
"""Parse a raw hello dict; tolerate firmware field-name drift.
Tolerant parsing is intentional: firmware builds differ, and the PoC must
connect, not reject, on a missing optional field.
"""
data: dict[str, Any] = dict(payload)
data.setdefault("type", "hello")
# Common firmware aliases.
for src, dst in (("deviceId", "device_id"), ("Device-Id", "device_id")):
if src in data and "device_id" not in data:
data["device_id"] = data[src]
if "audio" in data and "audio_params" not in data:
data["audio_params"] = data.pop("audio")
return Hello.model_validate(data)
def build_hello_reply(session_id: str, protocol: Hello) -> HelloReply:
return HelloReply(
session_id=session_id,
protocol_version=protocol.protocol_version,
audio_params=protocol.audio_params,
)