> For the complete documentation index, see [llms.txt](https://frostember-studios.gitbook.io/frostspeech-tts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://frostember-studios.gitbook.io/frostspeech-tts/getting-started/images-and-media.md).

# C# Scripting API (FrostSpeechAPI)

The `FrostSpeechAPI` class allows you to generate audio entirely via code. This is incredibly powerful for custom Editor tools, dialogue importers, or runtime procedural generation.

**Namespace Requirement:**

```csharp
using FrostemberStudios.FrostSpeechTTS;
using System.Threading.Tasks;
using System.Threading;
using UnityEngine;
```

#### Basic Generation (Explicit Parameters)

Use `FrostSpeechAPI.GenerateAudioAsync` to generate audio by explicitly passing the text, engine, and voice identifier.

```csharp
public async Task GenerateGreeting()
{
    string text = "Hello traveler! Welcome to the village.";
    
    // The relative path in your project where the AudioClip should be saved
    string outputPath = "Assets/Audio/Dialog/Greeting_01.wav";

    // Setup options (optional)
    TTSOptions options = new TTSOptions
    {
        Speed = 1.0f,
        NoiseScale = 0.667f,
        // Optional: Provide progress feedback to your UI
        OnProgress = (progress, label) => Debug.Log($"{label}: {progress * 100}%")
    };

    // Cancellation token allows you to abort long generations
    CancellationTokenSource cts = new CancellationTokenSource();

    // Generate! 
    AudioClip clip = await FrostSpeechAPI.GenerateAudioAsync(
        text, 
        FrostSpeechAPI.ENGINE_PIPER, // ENGINE_PIPER, ENGINE_SHERPA, ENGINE_KOKORO, ENGINE_ELEVENLABS
        "en_US-ryan-high",           // The exact Voice Key or ElevenLabs Voice ID
        outputPath, 
        options, 
        cts.Token
    );

    if (clip != null)
    {
        Debug.Log("Audio generated successfully!");
        // You can now play the clip using an AudioSource
    }
}
```

#### Generating from a Profile

If you have assigned a `FrostSpeechTTSProfile` via the Inspector, you can use it to completely override the `TTSOptions`. This guarantees the code generates audio exactly as configured in the Editor UI.

```csharp
[SerializeField] private FrostSpeechTTSProfile characterProfile;

public async Task GenerateFromProfile(string dialogueLine, string outputPath)
{
    // The profile already contains the Engine, Voice Key, Speed, and Text.
    // However, the API overrides the profile's saved text with the text parameter passed to the method below.
    
    // We update the profile's text so the API uses our new dialogue line.
    characterProfile.text = dialogueLine;

    AudioClip clip = await FrostSpeechAPI.GenerateAudioAsync(
        characterProfile, 
        outputPath, 
        null, // TTSOptions will be automatically created from the Profile
        CancellationToken.None
    );
}
```

#### Fetching Available Voices

You can programmatically retrieve a list of all available voice keys for a specific engine. Useful if you are building your own dropdowns in custom UI.

```csharp
public async Task PrintPiperVoices()
{
    var voiceKeys = await FrostSpeechAPI.GetVoiceKeysForEngineAsync(FrostSpeechAPI.ENGINE_PIPER);
    foreach (string key in voiceKeys)
    {
        Debug.Log("Available Voice: " + key);
    }
}
```

#### Runtime Audio Loading vs Editor Importing

**CRITICAL DIFFERENCE:**

* **In the Unity Editor:** The API saves the file and uses `AssetDatabase.ImportAsset()` to load it synchronously as a standard Unity asset.
* **In a Build (Runtime):** `AssetDatabase` does not exist. The API detects this and automatically falls back to using `UnityWebRequestMultimedia` to load the `.wav` or `.mp3` file from the disk asynchronously into an `AudioClip`.
* *Note:* Generating audio at runtime using local engines (Piper/Sherpa) requires you to manually copy the `Binaries~` and `Models` folders into your built game's `StreamingAssets` or persistent data path, and update the paths in the wrapper classes. **FrostSpeechTTS is officially supported as an Editor-only generation tool, with Runtime usage requiring manual binary management by the developer.**


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://frostember-studios.gitbook.io/frostspeech-tts/getting-started/images-and-media.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.