# `ALLM.TranscriptionStreamRequest`
[🔗](https://github.com/cykod/ALLM/blob/v0.6.1/lib/allm/transcription_stream_request.ex#L1)

The configuration of a streaming (realtime) transcription session.
Layer A serializable data.

    iex> cfg = ALLM.TranscriptionStreamRequest.new(sample_rate: 16_000, language: "en")
    iex> ALLM.Validate.transcription_stream_request(cfg)
    :ok

The audio itself is not a field. It is an enumerable passed alongside
this struct, whose elements are 16-bit little-endian mono PCM binaries at
`:sample_rate`, or the atom `:commit` to end a segment under `:manual`
commit. An enumerable is not serializable data, which is why it stays out
of the struct.

## Fields

- `:model`: the realtime model, or `nil` for the adapter's default. There
  is no fallback to the engine's transcription model: batch and realtime
  model names are separate namespaces on some providers, so a batch model
  would be rejected here.
- `:language`: an optional hint for the spoken language (for example
  `"en"`).
- `:sample_rate`: the rate in Hz of the PCM being sent. Defaults to
  16,000. Each adapter accepts its own set of rates.
- `:commit_strategy`: `:vad` (the default) lets the provider decide when
  a segment ends; `:manual` ends one only when the input yields `:commit`.
  One of `commit_strategies/0`.
- `:timestamps`: `true` asks for per-word start and end times on each
  committed segment's `:spans` (see `ALLM.TranscriptSpan` and
  `ALLM.TranscriptionEvent`). Defaults to `false`.
- `:logprobs`: `true` asks for per-word or per-token log-probabilities
  on each committed segment's `:spans`. Defaults to `false`. With both
  flags `false`, no event carries a `:spans` key.
- `:options`: a raw provider passthrough for parameters ALLM does not
  model. An adapter merges it under the fields it sets itself.
- `:metadata`: caller-owned. Use string keys when it will round-trip
  through JSON.

## Construction

`new/1` is a bare `struct!/2` pass-through: unknown keys raise
`KeyError`, and nothing else is checked. `new(sample_rate: 0)` constructs,
and `ALLM.Validate.transcription_stream_request/1` is what rejects it.

# `commit_strategy`

```elixir
@type commit_strategy() :: :vad | :manual
```

How a streaming transcription session decides a segment has ended.

# `t`

```elixir
@type t() :: %ALLM.TranscriptionStreamRequest{
  commit_strategy: commit_strategy(),
  language: String.t() | nil,
  logprobs: boolean(),
  metadata: map(),
  model: String.t() | nil,
  options: map(),
  sample_rate: pos_integer(),
  timestamps: boolean()
}
```

# `commit_strategies`

```elixir
@spec commit_strategies() :: [commit_strategy()]
```

The closed list of `:commit_strategy` values.

## Examples

    iex> ALLM.TranscriptionStreamRequest.commit_strategies()
    [:vad, :manual]

# `new`

```elixir
@spec new(keyword()) :: t()
```

Build a `%TranscriptionStreamRequest{}` from keyword opts.

Unknown keys raise `KeyError` via `struct!/2`. Call
`ALLM.Validate.transcription_stream_request/1` to check the field rules.

## Examples

    iex> cfg = ALLM.TranscriptionStreamRequest.new()
    iex> {cfg.sample_rate, cfg.commit_strategy, cfg.model}
    {16000, :vad, nil}

---

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