# VoiceOptions

> Tracon documentation. Tracon is a .NET package family that adds a control
> plane on Microsoft Agent Framework, published as NuGet packages that run
> inside your own ASP.NET Core application.
>
> Page: https://tracon.dev/api/tracon.voiceoptions/
> Summary: VoiceOptions: Settings for the voice tools.

<div class="api-provenance">Namespace Tracon · Assembly <code>Tracon.Voice.dll</code></div>

Settings for the voice tools.

```csharp
public sealed class VoiceOptions
```

<dl class="api-relations"><dt>Inheritance</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object">object</a> ← <a href="/api/tracon.voiceoptions/">VoiceOptions</a></dd><dt>Inherited Members</dt><dd><a href="https://learn.microsoft.com/dotnet/api/system.object.gettype">object.GetType()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.tostring">object.ToString()</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object)">object.Equals(object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.equals#system-object-equals(system-object-system-object)">object.Equals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.referenceequals">object.ReferenceEquals(object?, object?)</a>, <a href="https://learn.microsoft.com/dotnet/api/system.object.gethashcode">object.GetHashCode()</a></dd></dl>

## Remarks

The type **cannot** be a `record`: the compiler-generated
`ToString` writes every property, and a single `LogDebug("{Options}", o)`
call would leak [VoiceOptions.ApiKey](/api/tracon.voiceoptions/#Tracon_VoiceOptions_ApiKey) into the log.
`SecretLeakTests` verifies the type does not define its own `ToString`.

## Constructors

### <a id="Tracon_VoiceOptions__ctor"></a> VoiceOptions\(\)

```csharp
public VoiceOptions()
```

## Fields

### <a id="Tracon_VoiceOptions_DefaultOutputFormat"></a> DefaultOutputFormat

Default output format.

```csharp
public const string DefaultOutputFormat = "mp3_44100_128"
```

#### Field Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)

#### Remarks

MP3 is chosen because the attachment store does type checking from the
**magic byte**. `pcm_*` and `ulaw_*` outputs have no header
and are rejected.

### <a id="Tracon_VoiceOptions_SectionName"></a> SectionName

Default name of the configuration section.

```csharp
public const string SectionName = "Tracon:Voice"
```

#### Field Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)

## Properties

### <a id="Tracon_VoiceOptions_ApiKey"></a> ApiKey

The API key. A **secret**: it lives only in
`dotnet user-secrets` or an environment variable.

```csharp
public string? ApiKey { get; set; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

#### Remarks

The key's *value* is held here, not its *name*. The rule forbids
writing secrets to the DATABASE; voice configuration never reaches the
database, and the other four provider packages also carry a plain `ApiKey`.

### <a id="Tracon_VoiceOptions_DefaultVoiceId"></a> DefaultVoiceId

Voice to use when the request gives no voice id.

```csharp
public string? DefaultVoiceId { get; set; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

### <a id="Tracon_VoiceOptions_DialogueModelId"></a> DialogueModelId

The dialogue model of the built-in client. When empty, the request names none and
the provider uses its own default.

```csharp
public string? DialogueModelId { get; set; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

#### Remarks

[VoiceOptions.SynthesisModelId](/api/tracon.voiceoptions/#Tracon_VoiceOptions_SynthesisModelId) is not used for a dialogue: the single-voice default
(`eleven_multilingual_v2`) is not a dialogue model. A result made with the
provider's default reports no model, so its price is looked up without one.

### <a id="Tracon_VoiceOptions_Endpoint"></a> Endpoint

Base address. When empty, the provider's public address is used.

```csharp
public Uri? Endpoint { get; set; }
```

#### Property Value

 Uri?

### <a id="Tracon_VoiceOptions_MaxCharactersPerRequest"></a> MaxCharactersPerRequest

Maximum characters that can be spoken in a single request. Default 5,000.

```csharp
public int MaxCharactersPerRequest { get; set; }
```

#### Property Value

 [int](https://learn.microsoft.com/dotnet/api/system.int32)

#### Remarks

When the limit is exceeded, the tool **returns an error**; it does
not silently truncate the text. Truncation produces a sentence the user never
hears, and the reason becomes invisible.

### <a id="Tracon_VoiceOptions_MaxConcurrentRequests"></a> MaxConcurrentRequests

How many voice requests can run at once. Default 2.

```csharp
public int MaxConcurrentRequests { get; set; }
```

#### Property Value

 [int](https://learn.microsoft.com/dotnet/api/system.int32)

#### Remarks

Synthesis, dialogue and transcription share this one limit.

### <a id="Tracon_VoiceOptions_MaxDialogueCharactersPerRequest"></a> MaxDialogueCharactersPerRequest

Maximum characters one dialogue request can carry, summed over its turns. Default
2,000, the provider's guidance for reliable generation.

```csharp
public int MaxDialogueCharactersPerRequest { get; set; }
```

#### Property Value

 [int](https://learn.microsoft.com/dotnet/api/system.int32)

#### Remarks

A longer dialogue is refused, not split: the caller splits it at a point that suits
its content and joins the audio. `ISpeechDialogueSynthesizer.DialogueCapabilities`
reports this value.

### <a id="Tracon_VoiceOptions_OutputFormat"></a> OutputFormat

Output format.

```csharp
public string OutputFormat { get; set; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)

### <a id="Tracon_VoiceOptions_Provider"></a> Provider

The built-in client to use. Currently only `elevenlabs` is supported.

```csharp
public string Provider { get; set; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)

#### Remarks

This setting, [VoiceOptions.ApiKey](/api/tracon.voiceoptions/#Tracon_VoiceOptions_ApiKey) and [VoiceOptions.Endpoint](/api/tracon.voiceoptions/#Tracon_VoiceOptions_Endpoint) configure the
built-in client only. When your own [ISpeechSynthesizer](/api/tracon.ispeechsynthesizer/) and
[ISpeechTranscriber](/api/tracon.ispeechtranscriber/) are registered BEFORE `UseVoice`, the
three are not validated and not required.

Prices in `Tracon:Pricing:Voice` are keyed by the `ProviderName`
of the implementation that did the work, not by this value.

### <a id="Tracon_VoiceOptions_RequireApproval"></a> RequireApproval

Whether voice tools require explicit approval before a call. Default [false](https://learn.microsoft.com/dotnet/csharp/language-reference/builtin-types/bool).

```csharp
public bool RequireApproval { get; set; }
```

#### Property Value

 [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

#### Remarks

The tool causes no irreversible side effect — it produces a file and spends
money. Cost can be a reason on its own; that is why the setting exists, off by default.

### <a id="Tracon_VoiceOptions_SynthesisModelId"></a> SynthesisModelId

Default synthesis model.

```csharp
public string? SynthesisModelId { get; set; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?

### <a id="Tracon_VoiceOptions_Timeout"></a> Timeout

Request timeout. 100 seconds when empty.

```csharp
public TimeSpan? Timeout { get; set; }
```

#### Property Value

 [TimeSpan](https://learn.microsoft.com/dotnet/api/system.timespan)?

#### Remarks

Must be from one millisecond to about 24.8 days ([Int32.MaxValue](https://learn.microsoft.com/dotnet/api/system.int32) milliseconds) when set; any other value fails at startup.

### <a id="Tracon_VoiceOptions_TranscriptionModelId"></a> TranscriptionModelId

Default transcription model.

```csharp
public string? TranscriptionModelId { get; set; }
```

#### Property Value

 [string](https://learn.microsoft.com/dotnet/api/system.string)?