syntax = "proto3";

package omnivoice.v1;

// voice-generator gRPC interface (mirrors the REST API under /api/v1).
service SpeechService {
  // Static information about the loaded engine.
  rpc GetInfo(GetInfoRequest) returns (EngineInfo);
  // Supported languages (id + lowercase English name).
  rpc ListLanguages(ListLanguagesRequest) returns (ListLanguagesResponse);
  // Valid voice-design instruct items.
  rpc GetInstructCatalog(GetInstructCatalogRequest) returns (InstructCatalog);

  // Synthesize speech; returns a complete 16-bit PCM WAV file.
  rpc Synthesize(SynthesizeRequest) returns (SynthesizeResponse);
  // Streaming synthesis: raw PCM chunks are sent as soon as each text chunk
  // has been generated (short first chunk for low first-audio latency).
  rpc SynthesizeStream(SynthesizeRequest) returns (stream AudioChunk);
  // Streaming synthesis delivered as audio *codes* (~2 kbps) for client-side
  // decoding with omnivoice-decoder. First message is `meta`, then `chunk`s.
  rpc SynthesizeCodesStream(SynthesizeRequest) returns (stream CodeStreamMessage);

  // Register a reference recording (WAV bytes + transcript) as a reusable voice.
  rpc CreateVoice(CreateVoiceRequest) returns (Voice);
  rpc ListVoices(ListVoicesRequest) returns (ListVoicesResponse);
  rpc GetVoice(GetVoiceRequest) returns (Voice);
  rpc DeleteVoice(DeleteVoiceRequest) returns (DeleteVoiceResponse);
}

message GetInfoRequest {}

message EngineInfo {
  string model = 1;
  string device = 2;
  string dtype = 3;
  uint32 sample_rate = 4;
  uint32 frame_rate = 5;
  uint32 num_codebooks = 6;
}

message ListLanguagesRequest {}

message Language {
  string id = 1;
  string name = 2;
}

message ListLanguagesResponse {
  repeated Language languages = 1;
}

message GetInstructCatalogRequest {}

message InstructCatalog {
  repeated string english = 1;
  repeated string chinese = 2;
}

// Decoding knobs; unset fields use the engine defaults
// (num_step 32, guidance_scale 2.0, t_shift 0.1, layer_penalty_factor 5.0,
// position_temperature 5.0, class_temperature 0.0, denoise true, postprocess_output true).
message SynthesisOptions {
  optional uint32 num_step = 1;
  optional float guidance_scale = 2;
  optional float t_shift = 3;
  optional float layer_penalty_factor = 4;
  optional float position_temperature = 5;
  optional float class_temperature = 6;
  optional bool denoise = 7;
  optional bool postprocess_output = 8;
  optional uint64 seed = 9;
  // Streaming: target duration (s) of the first chunk (default 5).
  optional float first_chunk_duration = 10;
  // Streaming: num_step override for the first chunk.
  optional uint32 first_chunk_num_step = 11;
  // Target duration (s) of subsequent chunks (default 15).
  optional float chunk_duration = 12;
}

message SynthesizeRequest {
  // Text to synthesize (max 5000 characters).
  string text = 1;
  // Language name ("English") or id ("en"); empty = language-agnostic.
  optional string language = 2;
  // Voice-design instruction, e.g. "female, young adult, british accent".
  optional string instruct = 3;
  // Stored voice id for cloning (see CreateVoice).
  optional string voice_id = 4;
  // Fixed output duration in seconds (overrides speed).
  optional float duration = 5;
  // Speaking speed factor (> 1 faster).
  optional float speed = 6;
  SynthesisOptions options = 7;
}

message SynthesizeResponse {
  // Complete WAV file (mono, 16-bit PCM).
  bytes wav = 1;
  uint32 sample_rate = 2;
  float duration_secs = 3;
  float elapsed_secs = 4;
  optional string voice_id = 5;
}

message AudioChunk {
  // Raw little-endian 16-bit mono PCM of this chunk. Chunks are contiguous:
  // concatenating them yields the whole utterance (fades/gaps included).
  bytes pcm16 = 1;
  uint32 sample_rate = 2;
  // 0-based chunk index and planned total.
  uint32 index = 3;
  uint32 total = 4;
  // Text covered by this chunk.
  string text = 5;
  bool last = 6;
  // Duration of this chunk in seconds.
  float duration_secs = 7;
  // Seconds since the request started when this chunk became available.
  float elapsed_secs = 8;
}

// Parameters a client needs to decode / post-process the code stream.
message CodeStreamMeta {
  uint32 sample_rate = 1;
  uint32 frame_rate = 2;
  uint32 num_codebooks = 3;
  uint32 codebook_size = 4;
  uint32 total_chunks = 5;
  optional float ref_rms = 6;
  bool remove_silence = 7;
  float pad_duration = 8;
  float fade_duration = 9;
}

message CodeChunk {
  uint32 index = 1;
  uint32 total = 2;
  string text = 3;
  // Row-major (num_codebooks × num_frames) codes.
  repeated uint32 codes = 4 [packed = true];
  uint32 num_codebooks = 5;
  uint32 num_frames = 6;
  bool last = 7;
  float elapsed_secs = 8;
}

message CodeStreamMessage {
  oneof msg {
    CodeStreamMeta meta = 1;
    CodeChunk chunk = 2;
  }
}

message CreateVoiceRequest {
  string name = 1;
  // Transcript of the reference audio (required).
  string ref_text = 2;
  // Reference recording as a WAV file (any sample rate, mono or stereo, <= 60 s).
  bytes wav = 3;
  // Trim silences / add end punctuation (default true).
  optional bool preprocess = 4;
}

message Voice {
  string id = 1;
  string name = 2;
  string ref_text = 3;
  uint32 num_frames = 4;
  float reference_secs = 5;
  // RFC 3339 timestamp.
  string created_at = 6;
}

message ListVoicesRequest {}

message ListVoicesResponse {
  repeated Voice voices = 1;
}

message GetVoiceRequest {
  string id = 1;
}

message DeleteVoiceRequest {
  string id = 1;
}

message DeleteVoiceResponse {}