Runtime Contract

This repository contains only the Combrabo Voice LiveKit runtime helper. It is a media worker, not a business service.

Responsibilities

Connect to the LiveKit room using bot credentials generated by lmrobot-app.
Publish one bot-main-audio track.
Play prepared greeting audio from CV_GREETING_AUDIO_FILE or CV_GREETING_AUDIO_URL.
Receive user audio in S7 and pass one completed voice turn to the Java turn bridge.
Publish reliable LiveKit Data Message for device_output smoke and later voice command output.

Non-goals

No SDK token authentication.
No database access.
No order, entitlement or billing logic.
No prompt, ASR, LLM, TTS or message persistence authority.
No LiveKit server modification.

lmrobot-app remains the business authority for call state, role permission, greeting prepare/consume, ASR, prompt/history, LLM, TTS, message persistence, activity, diagnostics and reasonCode.

Required environment variables

Name	Source	Notes
`CV_CALL_ID`	`lmrobot-app`	Public call alias, not DB id.
`CV_TRACE_ID`	`lmrobot-app`	Used to correlate logs and activity.
`CV_LIVEKIT_URL`	`lmrobot-app`	Helper reachable LiveKit URL.
`CV_LIVEKIT_ROOM_ID`	`lmrobot-app`	Sensitive connection material; do not log raw value in shared docs.
`CV_LIVEKIT_BOT_TOKEN`	`lmrobot-app`	Sensitive connection token.
`CV_LIVEKIT_BOT_PARTICIPANT_IDENTITY`	`lmrobot-app`	Sensitive connection material.

Optional first-audio variables:

Name	Notes
`CV_FIRST_AUDIO_SOURCE`	`fixed_greeting_tts`, `cached_tts` or diagnostic value.
`CV_GREETING_AUDIO_FILE`	Local WAV / MP3 file path.
`CV_GREETING_AUDIO_URL`	WAV / MP3 URL fetched by helper.
`CV_GREETING_TEXT`	Diagnostic metadata only; do not log user/private content.

Optional device-output smoke variables:

Name	Notes
`CV_DEVICE_OUTPUT_SMOKE_ENABLED`	`true` enables deterministic Data Message smoke. Default false.
`CV_DEVICE_OUTPUT_DESTINATION_IDENTITIES`	Comma-separated target identities. Empty falls back to user identity or room broadcast.

LiveKit Data Message payload

For device output, helper sends reliable Data Message:

{
  "type": "device_output",
  "schemaVersion": "1.0",
  "commandId": "cmd_xxx",
  "callId": "cv_call_xxx",
  "traceId": "trace_xxx",
  "turnId": "turn_xxx",
  "commandCode": "vibration.start",
  "params": {
    "step": 1,
    "durationSec": 3,
    "extension": {}
  },
  "source": {
    "kind": "voice_command"
  }
}

The payload must not include token, room credential, user raw speech, ASR text, LLM prompt or full reply text.