API Reference

Audience: developers needing the raw, exhaustive reference for every gRPC field, HTTP endpoint, and error mode.

For a tutorial-style walk-through with examples and gotchas, see grpc-integration.md. This doc is the field-by-field reference; nothing here is omitted for brevity.

gRPC service: TranslationService

Defined in protos/translation.proto. Package: hibikivoice.translation.

TranslateStream(stream TranslateStreamRequest) → stream TranslateStreamResponse

Bidirectional streaming RPC. Audio in, translation events out. The main contract.

Request: TranslateStreamRequest

A oneof payload — exactly one of these per message:

StreamConfig

message StreamConfig {
    string src_lang = 1;
    string tgt_lang = 2;
    string session_id = 3;
    bool enable_diarization = 4;
    bool enable_emotion = 5;
    string whisper_model = 6;
    bool skip_post_stitcher = 7;
}

AudioChunk

message AudioChunk {
    bytes pcm = 1;
    int64 pts_start_ms = 2;
    int64 pts_end_ms = 3;
}

Both PTS values may be 0 to indicate "unknown timing"; output will then have src_pts_*_ms = 0 too.

StreamControl

message StreamControl {
    bool flush = 1;
    bool end = 2;
}

Response: TranslateStreamResponse

A oneof payload:

TranslatedSentence

message TranslatedSentence {
    string translated_text = 1;
    string src_text = 2;
    int32 sequence = 3;
    int32 speaker_id = 4;
    string speaker_gender = 5;
    string emotion = 6;
    string emotion_instruction = 7;
    float latency_ms = 8;
    string model_used = 9;
    float start_time = 10;
    float end_time = 11;
    int64 src_pts_start_ms = 12;
    int64 src_pts_end_ms = 13;
    bool is_replacement = 14;
    string translation_status = 15;
}

PartialTranscript

message PartialTranscript {
    string text = 1;
    int32 speaker_id = 2;
}

Treat as advisory, not authoritative. Inconsistent across STT engines.

LiveTranscriptUpdate

message LiveTranscriptUpdate {
    repeated TranscriptLine lines = 1;
    string buffer_transcription = 2;
    string buffer_diarization = 3;
    string buffer_translation = 4;
    string status = 5;
    bool speculative = 6;
    float remaining_time_transcription = 7;
    float remaining_time_diarization = 8;
}

message TranscriptLine {
    int32 speaker = 1;
    string text = 2;
    string translation = 3;
    string speaker_gender = 4;
    float start = 5;
    float end = 6;
    string detected_language = 7;
}

TranslateText(TranslateTextRequest) → TranslateTextResponse

Unary text-only translation. No audio. Useful for testing and one-shot use cases.

TranslateTextRequest

message TranslateTextRequest {
    string text = 1;
    string src_lang = 2;
    string tgt_lang = 3;
    bool enable_emotion = 4;
}

TranslateTextResponse

message TranslateTextResponse {
    string translated_text = 1;
    string emotion = 2;
    string emotion_instruction = 3;
    float latency_ms = 4;
    string model_used = 5;
}

Identical shape to TranslatedSentence minus the audio-related fields (no sequence, speaker_id, speaker_gender, timestamps, PTS).

HealthCheck(HealthRequest) → HealthResponse

Liveness check. No-op request, returns server status.

message HealthResponse {
    string status = 1;          // "ok", "initializing", or error string
    string models_loaded = 2;   // comma-separated list of loaded models
    string device = 3;          // "cuda:0", "cpu", etc.
}

Use this in load balancer health checks and deploy-readiness probes.

gRPC error codes

grpc.RpcError code() values you may see:

The server doesn't currently distinguish many of these; most failure modes return either UNAVAILABLE (network), FAILED_PRECONDITION (config order), or INTERNAL (anything else).

HTTP API (engine operator surface)

These are non-gRPC HTTP endpoints exposed by web_server.py. They serve the operator UI and runtime configuration. Most of them are not relevant to a gRPC client like hibiki-stage — but documenting here for completeness.

Public

Engine configuration (auth required when AUTH_MODE=normal)

WebSocket endpoint (legacy / dev)

Pages

Environment variables

Set on the server, not the client. Documented here for clients that may want to detect server config (via /translate/config).

See deployment.md for which CDK context vars produce these env vars at deploy time.

Versioning

The proto file is the source of truth. Treat field numbers as immutable; never reuse a deprecated number. Adding new optional fields is backward-compatible; renaming or removing fields is not.

Current proto version: see git log -- protos/translation.proto for history.

When breaking changes are necessary, mark the old field with // DEPRECATED (as audio already is) and add a new one rather than mutating the existing field.