Add a Custom TTS Provider

Use this guide when your project needs VoiceOver audio from a provider that is not already built into VRseBuilder.

The usual flow is:

1. Create a provider class.
2. Add provider-specific settings.
3. Let VRseBuilder discover the provider.
4. Select it in Text to Speech settings.
5. Generate VoiceOvers as usual.

info

This is a developer workflow. The generated VoiceOver nodes still use VoiceOver actions; the provider only changes how audio clips are generated from the text.

What You Are Building

A TTS provider is an adapter between VRseBuilder and a speech service such as ElevenLabs, Amazon Polly, Google Cloud TTS, or an internal API.

VRseBuilder discovers concrete classes that implement ITextToSpeechProvider. For multilingual and batch generation support, implement IVRBTextToSpeechProvider.

Interface	Use it when
ITextToSpeechProvider	You only need basic single-text conversion.
IVRBTextToSpeechProvider	You need language-aware or batch VoiceOver generation. Recommended for most projects.

1. Create the Provider Class

Create a runtime C# script for your provider. Keep it in a runtime assembly so it is available during editor generation and runtime workflows.

using System.Threading.Tasks;
using UnityEngine;
using VRseBuilder.Core.Systems.TextToSpeech;

public class MyCustomTTSProvider : IVRBTextToSpeechProvider
{
    private TextToSpeechConfiguration config;

    public void SetConfig(TextToSpeechConfiguration configuration)
    {
        config = configuration;
    }

    public Task<AudioClip> ConvertTextToSpeech(string text)
    {
        return ConvertTextToSpeechForLanguage(text, config.SourceLanguageId);
    }

    public async Task<AudioClip> ConvertTextToSpeechForLanguage(string text, string language)
    {
        // Call your provider API here and return an AudioClip.
        return await FetchClipFromService(text, language);
    }

    public async Task<AudioClip[]> ConvertMultipleTextToSpeech(string[] texts, string[] languages)
    {
        var clips = new AudioClip[texts.Length];

        for (int i = 0; i < texts.Length; i++)
        {
            clips[i] = await ConvertTextToSpeechForLanguage(texts[i], languages[i]);
        }

        return clips;
    }

    private Task<AudioClip> FetchClipFromService(string text, string language)
    {
        // Replace this with your web request / SDK call.
        return Task.FromResult<AudioClip>(null);
    }
}

2. Add Provider Settings

Provider-specific settings are stored through TTSProviderSettings. Create a settings class for API keys, endpoints, voice IDs, or other provider-specific values.

using System;
using VRseBuilder.Core.Systems.TextToSpeech;

[Serializable]
public class MyCustomTTSSettings : TTSProviderSettings
{
    public string apiKey;
    public string baseUrl;
    public string defaultVoiceId;

    public override string ProviderId => "my-custom-tts";
}

Inside your provider, read those settings from the configuration:

var settings = config.GetSettings<MyCustomTTSSettings>();
string apiKey = settings.apiKey;
string voiceId = settings.GetVoiceId(language) ?? settings.defaultVoiceId;

3. Give the Provider a Friendly Name

Add TTSProviderAttribute so the dropdown shows a stable provider ID and a readable display name.

[TTSProvider("my-custom-tts", "My Custom TTS")]
public class MyCustomTTSProvider : IVRBTextToSpeechProvider
{
    // Provider implementation
}

The provider ID is what VRseBuilder stores in the TTS configuration. The display name is what users see in the provider dropdown.

4. Implement the API Request

Most providers call an external API and convert the response into an AudioClip.

using UnityEngine;
using UnityEngine.Networking;

private async Task<AudioClip> FetchClipFromService(string text, string language)
{
    var settings = config.GetSettings<MyCustomTTSSettings>();
    string url = settings.baseUrl;

    using var request = UnityWebRequestMultimedia.GetAudioClip(url, AudioType.MPEG);
    request.SetRequestHeader("Authorization", "Bearer " + settings.apiKey);

    var operation = request.SendWebRequest();
    while (!operation.isDone)
    {
        await Task.Yield();
    }

    if (request.result != UnityWebRequest.Result.Success)
    {
        Debug.LogError($"TTS request failed: {request.error}");
        return null;
    }

    return DownloadHandlerAudioClip.GetContent(request);
}

5. Select the Provider in Unity

After the project recompiles:

1. Open Edit > Project Settings > VRseBuilder > Text To Speech.
2. Select your provider from the provider dropdown.
3. Fill in your provider settings.
4. Generate VoiceOvers from the normal VO generation flow.

What VoiceOver Nodes Still Need

Your custom provider does not change the VoiceOver action format.

In a story, VoiceOver still uses:

Field	What to use
Query	Leave blank.
Option	Play.
Data.text	The line to generate and play.
Voice selection	Comes from TTS provider settings, not the VoiceOver action node.

Limitations

• Custom providers are discovered automatically if they implement ITextToSpeechProvider.
• If a provider ID is missing or invalid, the factory falls back to the file/cache provider.
• Some VO preview tooling may only expose first-party provider settings. Configure custom providers from Project Settings.

Checklist

• Provider class implements IVRBTextToSpeechProvider.
• Provider has a stable provider ID.
• Provider settings are stored in a TTSProviderSettings class.
• API errors return null instead of crashing the editor.
• Generated audio is tested with a real VoiceOver action.