Skip to content

OmniVoice Providers

The OmniVoice providers implement the stt.Provider and tts.Provider interfaces from omnivoice-core.

Features

STT (Speech-to-Text)

  • Whisper model transcription
  • Word-level timestamps
  • Segment-level timestamps
  • Multiple audio format support (mp3, wav, flac, opus, m4a, webm)
  • Language detection

TTS (Text-to-Speech)

  • 13 distinct voices
  • Multiple output formats (mp3, opus, aac, flac, wav, pcm), plus mu-law and A-law for phone calls
  • Adjustable speed (0.25x to 4.0x)
  • Streaming output
  • HD quality model option

Installation

import "github.com/plexusone/omni-openai/omnivoice"

STT Provider

Basic Usage

provider, err := omnivoice.NewSTTProviderFromEnv()
if err != nil {
    log.Fatal(err)
}

result, err := provider.Transcribe(ctx, audioData, stt.TranscriptionConfig{
    Encoding: "mp3",
    Language: "en-US", // Optional: auto-detected if omitted
})
if err != nil {
    log.Fatal(err)
}

fmt.Println("Text:", result.Text)
fmt.Println("Language:", result.Language)
fmt.Println("Duration:", result.Duration)

Language takes a BCP 47 tag such as en-US or fr, as in every OmniVoice provider. OpenAI expects ISO 639-1 codes, so the provider sends the tag's language (en-US is sent as en). Leave it empty to have OpenAI detect the language.

Encoding names the audio's format (mp3, wav, flac, opus, m4a or webm, defaulting to mp3). It becomes the uploaded file's name and content type, which OpenAI uses to recognize the format.

With Word Timestamps

result, err := provider.Transcribe(ctx, audioData, stt.TranscriptionConfig{
    Encoding:             "mp3",
    EnableWordTimestamps: true,
})

for _, segment := range result.Segments {
    fmt.Printf("[%s - %s] %s\n", segment.StartTime, segment.EndTime, segment.Text)
    for _, word := range segment.Words {
        fmt.Printf("  %s (%s)\n", word.Text, word.StartTime)
    }
}

From File

result, err := provider.TranscribeFile(ctx, "speech.mp3", stt.TranscriptionConfig{})

TTS Provider

Basic Usage

provider, err := omnivoice.NewTTSProviderFromEnv()
if err != nil {
    log.Fatal(err)
}

result, err := provider.Synthesize(ctx, "Hello, world!", tts.SynthesisConfig{
    VoiceID: omnivoice.VoiceNova,
})
if err != nil {
    log.Fatal(err)
}

// result.Audio contains MP3 data
os.WriteFile("output.mp3", result.Audio, 0644)

Streaming Output

chunks, err := provider.SynthesizeStream(ctx, "Long text to synthesize...", tts.SynthesisConfig{
    VoiceID: omnivoice.VoiceAlloy,
})
if err != nil {
    log.Fatal(err)
}

for chunk := range chunks {
    if chunk.Error != nil {
        log.Fatal(chunk.Error)
    }
    if chunk.IsFinal {
        break
    }
    // Process chunk.Audio
}

Configuration Options

result, err := provider.Synthesize(ctx, "Hello!", tts.SynthesisConfig{
    Model:        "tts-1-hd",  // Higher quality
    VoiceID:      omnivoice.VoiceCoral,
    OutputFormat: "opus",
    Speed:        1.25,  // 25% faster
})

Available Voices

Voice Constant Description
alloy VoiceAlloy Neutral, balanced
ash VoiceAsh Warm, engaging
ballad VoiceBallad Melodic, expressive
coral VoiceCoral Clear, articulate
echo VoiceEcho Smooth, natural
fable VoiceFable Storytelling, dramatic
nova VoiceNova Bright, energetic
onyx VoiceOnyx Deep, resonant
sage VoiceSage Calm, wise
shimmer VoiceShimmer Light, cheerful
verse VoiceVerse Poetic, rhythmic
marin VoiceMarin Friendly, approachable
cedar VoiceCedar Grounded, trustworthy

Models

STT Models

Model Constant Description
whisper-1 ModelWhisper1 Whisper v2 large

TTS Models

Model Constant Description
tts-1 ModelTTS1 Fast, lower latency
tts-1-hd ModelTTS1HD Higher quality audio

Output Formats

Format Description
mp3 Default, widely supported
opus Efficient, good for streaming
aac Apple ecosystem
flac Lossless
wav Uncompressed PCM
pcm Raw PCM (24kHz, 16-bit, mono); another SampleRate is resampled
mulaw Raw G.711 mu-law for phone calls, 8kHz unless SampleRate says otherwise
alaw Raw G.711 A-law, 8kHz unless SampleRate says otherwise

OpenAI produces raw audio only as 24kHz PCM. The provider converts it for the other raw formats, in Synthesize and SynthesizeStream alike, and reports the sample rate of raw audio in the result. Aliases such as ulaw and names with the rate appended, such as ulaw_8000 or pcm_16000, are accepted, so a configuration written for another OmniVoice provider works unchanged:

// Mu-law at 8kHz, ready to play on a Twilio or Telnyx call.
result, err := provider.Synthesize(ctx, "Hello from a phone call.", tts.SynthesisConfig{
    VoiceID:      omnivoice.VoiceAlloy,
    OutputFormat: "mulaw",
    SampleRate:   8000,
})
// result.Format == "mulaw", result.SampleRate == 8000