# `OmnivoiceEx.Server`
[🔗](https://github.com/boyzwj/omnivoice_ex/blob/v0.1.0/lib/omnivoice_ex/server.ex#L1)

GenServer that manages a Python OmniVoice bridge via Erlang Port.

## Protocol

Frame format: `[4-byte BE total_length][msgpack-encoded payload]`

Audio is WAV bytes inside msgpack — no base64.

## Operations

  * `init` — Load model from HuggingFace
  * `generate` — TTS synthesis (synchronous, returns full audio)
  * `ping` — Health check

# `generate_opt`

```elixir
@type generate_opt() ::
  {:ref_audio, String.t()}
  | {:ref_text, String.t()}
  | {:instruct, String.t()}
  | {:language, String.t()}
  | {:duration, float()}
  | {:speed, float()}
  | {:num_step, pos_integer()}
  | {:guidance_scale, float()}
```

# `model_option`

```elixir
@type model_option() ::
  {:model, String.t()}
  | {:device, String.t()}
  | {:dtype, String.t()}
  | {:name, atom()}
```

# `start_opts`

```elixir
@type start_opts() :: [model_option()]
```

# `await_ready`

```elixir
@spec await_ready(GenServer.server(), timeout()) :: :ok | {:error, term()}
```

Waits for the model to finish loading.

Returns `:ok` when ready, `{:error, :loading}` if still initializing,
or `{:error, reason}` if initialization failed.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `generate`

```elixir
@spec generate(GenServer.server(), String.t(), [generate_opt()]) ::
  {:ok, binary()} | {:error, term()}
```

# `generate`

```elixir
@spec generate(GenServer.server(), String.t(), [generate_opt()], timeout()) ::
  {:ok, binary()} | {:error, term()}
```

# `info`

```elixir
@spec info(GenServer.server()) :: map()
```

Returns runtime model info: device, sample_rate, status.

# `save`

```elixir
@spec save(binary(), Path.t()) :: :ok | {:error, term()}
```

# `start_link`

```elixir
@spec start_link(start_opts()) :: GenServer.on_start()
```

# `stop`

```elixir
@spec stop(GenServer.server()) :: :ok
```

Gracefully stops the GenServer and the Python bridge process.

---

*Consult [api-reference.md](api-reference.md) for complete listing*