elevenlabs

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 30, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Overview

Package elevenlabs provides production ElevenLabs speech-to-text and text-to-speech clients for LiveKit Agents.

The package implements Scribe batch and realtime transcription, HTTP PCM synthesis, and the ElevenLabs multi-context websocket protocol. Network and stream buffers are bounded, every blocking operation is context-aware, and compressed output is rejected unless it can be decoded into the PCM frames required by the agents TTS contract.

Index

Constants

View Source
const (
	DefaultBaseURL               = "https://api.elevenlabs.io/v1"
	DefaultVoiceID               = "bIHbv24MWmeRgasZH58o"
	DefaultTTSModel     TTSModel = ElevenTurboV25
	DefaultEncoding              = PCM22050
	DefaultSTTModel     STTModel = ScribeV1
	AuthorizationHeader          = "xi-api-key"
)
View Source
const Version = "1.7.1"

Variables

View Source
var (
	ErrUnsupportedEncoding  = errors.New("elevenlabs: unsupported output encoding")
	ErrUnsupportedTransport = errors.New("elevenlabs: model is unsupported by this transport")
	ErrInvalidProtocol      = errors.New("elevenlabs: invalid provider protocol message")
	ErrReplayLimit          = errors.New("elevenlabs: uncommitted audio exceeds reconnect replay limit")
)

Functions

func Register

func Register() error

Register adds the plugin metadata to the process registry. Registration is explicit so importing this package has no startup work or global side effect.

Types

type ChunkedStream

type ChunkedStream struct {
	*tts.BaseChunkedStream
	// contains filtered or unexported fields
}

func (*ChunkedStream) Close

func (s *ChunkedStream) Close() error

func (*ChunkedStream) Wait

func (s *ChunkedStream) Wait(ctx context.Context) error

type ElevenLabsSTTModels

type ElevenLabsSTTModels = STTModel

type Plugin

type Plugin struct{}

func (Plugin) DownloadFiles

func (Plugin) DownloadFiles(context.Context) error

func (Plugin) Package

func (Plugin) Package() string

func (Plugin) Title

func (Plugin) Title() string

func (Plugin) Version

func (Plugin) Version() string

type PreferredAlignment

type PreferredAlignment string
const (
	NormalizedAlignment PreferredAlignment = "normalized"
	OriginalAlignment   PreferredAlignment = "original"
)

type PronunciationDictionaryLocator

type PronunciationDictionaryLocator struct {
	PronunciationDictionaryID string `json:"pronunciation_dictionary_id"`
	VersionID                 string `json:"version_id"`
}

type ProtocolError

type ProtocolError struct {
	Message string
	Cause   error
}

func (*ProtocolError) Error

func (e *ProtocolError) Error() string

func (*ProtocolError) Unwrap

func (e *ProtocolError) Unwrap() error

type ProviderError

type ProviderError struct {
	Type          string
	Message       string
	Details       string
	RetryableFlag bool
	Body          any
}

func (*ProviderError) Error

func (e *ProviderError) Error() string

func (*ProviderError) Retryable

func (e *ProviderError) Retryable() bool

type STT

type STT struct {
	*stt.Base
	// contains filtered or unexported fields
}

func NewSTT

func NewSTT(options STTOptions) (*STT, error)

func (*STT) Close

func (s *STT) Close(ctx context.Context) error

func (*STT) Recognize

func (s *STT) Recognize(ctx context.Context, frames []agents.AudioFrame, options stt.RecognizeOptions) (stt.SpeechEvent, error)

func (*STT) Stream

func (s *STT) Stream(ctx context.Context, options stt.StreamOptions) (stt.SpeechStream, error)

func (*STT) UpdateOptions

func (s *STT) UpdateOptions(options STTUpdateOptions) error

func (*STT) UpdateSessionKeyterms

func (s *STT) UpdateSessionKeyterms(keyterms []string) error

UpdateSessionKeyterms applies framework-managed keyterms without replacing terms supplied directly by the application.

type STTModel

type STTModel string
const (
	ScribeV1         STTModel = "scribe_v1"
	ScribeV2         STTModel = "scribe_v2"
	ScribeV2Realtime STTModel = "scribe_v2_realtime"
)

type STTOptions

type STTOptions struct {
	APIKey            string
	BaseURL           string
	Language          agents.LanguageCode
	LanguageCode      agents.LanguageCode // Deprecated: use Language.
	TagAudioEvents    *bool
	UseRealtime       *bool // Deprecated: select ScribeV2Realtime with Model.
	SampleRate        STTRealtimeSampleRate
	ServerVAD         *VADOptions
	IncludeTimestamps bool
	Model             STTModel
	ModelID           STTModel // Deprecated: use Model.
	Keyterms          []string
	NoVerbatim        bool
	EnableLogging     *bool

	HTTPClient        *http.Client
	WebSocketDialer   *websocket.Dialer
	InputCapacity     int
	OutputCapacity    int
	ProviderEventCap  int
	MaxResponseBytes  int64
	MaxWSMessageBytes int64
	MaxReplayDuration time.Duration
	ReadWriteTimeout  time.Duration
	UserAgent         string
}

type STTRealtimeSampleRate

type STTRealtimeSampleRate int
const (
	SampleRate8000  STTRealtimeSampleRate = 8000
	SampleRate16000 STTRealtimeSampleRate = 16000
	SampleRate22050 STTRealtimeSampleRate = 22050
	SampleRate24000 STTRealtimeSampleRate = 24000
	SampleRate44100 STTRealtimeSampleRate = 44100
	SampleRate48000 STTRealtimeSampleRate = 48000
)

type STTRealtimeSampleRates

type STTRealtimeSampleRates = STTRealtimeSampleRate

type STTUpdateOptions

type STTUpdateOptions struct {
	TagAudioEvents *bool
	ServerVAD      agents.Override[VADOptions]
	Keyterms       agents.Override[[]string]
	NoVerbatim     *bool
}

type SpeechStream

type SpeechStream struct {
	*stt.BaseStream
	// contains filtered or unexported fields
}

func (*SpeechStream) Close

func (s *SpeechStream) Close() error

func (*SpeechStream) UpdateOptions

func (s *SpeechStream) UpdateOptions(options STTUpdateOptions) error

UpdateOptions changes only this realtime stream. Updates become active at a safe committed-turn boundary so buffered audio cannot be lost.

func (*SpeechStream) Wait

func (s *SpeechStream) Wait(ctx context.Context) error

type SynthesizeStream

type SynthesizeStream struct {
	*tts.BaseSynthesizeStream
	// contains filtered or unexported fields
}

func (*SynthesizeStream) Close

func (s *SynthesizeStream) Close() error

func (*SynthesizeStream) ContextID

func (s *SynthesizeStream) ContextID() string

func (*SynthesizeStream) Wait

func (s *SynthesizeStream) Wait(ctx context.Context) error

type TTS

type TTS struct {
	*tts.Base
	// contains filtered or unexported fields
}

func NewTTS

func NewTTS(options TTSOptions) (*TTS, error)

func (*TTS) Close

func (t *TTS) Close(ctx context.Context) error

func (*TTS) ListVoices

func (t *TTS) ListVoices(ctx context.Context) ([]Voice, error)

func (*TTS) Stream

func (t *TTS) Stream(ctx context.Context, options tts.StreamOptions) (tts.SynthesizeStream, error)

func (*TTS) Synthesize

func (t *TTS) Synthesize(ctx context.Context, text string, options tts.SynthesizeOptions) (tts.ChunkedStream, error)

func (*TTS) UpdateOptions

func (t *TTS) UpdateOptions(ctx context.Context, update TTSUpdateOptions) error

type TTSEncoding

type TTSEncoding string
const (
	MP32205032  TTSEncoding = "mp3_22050_32"
	MP34410032  TTSEncoding = "mp3_44100_32"
	MP34410064  TTSEncoding = "mp3_44100_64"
	MP34410096  TTSEncoding = "mp3_44100_96"
	MP344100128 TTSEncoding = "mp3_44100_128"
	MP344100192 TTSEncoding = "mp3_44100_192"
	PCM16000    TTSEncoding = "pcm_16000"
	PCM22050    TTSEncoding = "pcm_22050"
	PCM44100    TTSEncoding = "pcm_44100"
)

type TTSModel

type TTSModel string
const (
	ElevenMonolingualV1  TTSModel = "eleven_monolingual_v1"
	ElevenMultilingualV1 TTSModel = "eleven_multilingual_v1"
	ElevenMultilingualV2 TTSModel = "eleven_multilingual_v2"
	ElevenFlashV2        TTSModel = "eleven_flash_v2"
	ElevenFlashV25       TTSModel = "eleven_flash_v2_5"
	ElevenTurboV2        TTSModel = "eleven_turbo_v2"
	ElevenTurboV25       TTSModel = "eleven_turbo_v2_5"
	ElevenV3             TTSModel = "eleven_v3"
)

func (TTSModel) String

func (m TTSModel) String() string

type TTSModels

type TTSModels = TTSModel

Compatibility aliases mirror the TypeScript plugin's exported union names.

type TTSOptions

type TTSOptions struct {
	APIKey        string
	VoiceID       string
	VoiceSettings *VoiceSettings
	Model         TTSModel
	Language      agents.LanguageCode

	Voice        *Voice              // Deprecated: use VoiceID and VoiceSettings.
	ModelID      TTSModel            // Deprecated: use Model.
	LanguageCode agents.LanguageCode // Deprecated: use Language.

	BaseURL                         string
	Encoding                        TTSEncoding
	StreamingLatency                *int
	Tokenizer                       TextTokenizer
	WordTokenizer                   TextTokenizer // Deprecated: use Tokenizer.
	ChunkLengthSchedule             []int
	EnableSSMLParsing               bool
	EnableLogging                   *bool
	InactivityTimeout               time.Duration
	SyncAlignment                   *bool
	ApplyTextNormalization          TextNormalization
	ApplyLanguageTextNormalization  *bool
	PreferredAlignment              PreferredAlignment
	AutoMode                        *bool
	PronunciationDictionaryLocators []PronunciationDictionaryLocator

	HTTPClient        *http.Client
	WebSocketDialer   *websocket.Dialer
	InputCapacity     int
	OutputCapacity    int
	WriterCapacity    int
	ProviderEventCap  int
	MaxResponseBytes  int64
	MaxWSMessageBytes int64
	ReadWriteTimeout  time.Duration
	MaxActiveContexts int
	UserAgent         string
}

type TTSUpdateOptions

type TTSUpdateOptions struct {
	VoiceID                         *string
	VoiceSettings                   agents.Override[VoiceSettings]
	Model                           *TTSModel
	Language                        agents.Override[agents.LanguageCode]
	PronunciationDictionaryLocators agents.Override[[]PronunciationDictionaryLocator]
}

type TextNormalization

type TextNormalization string
const (
	TextNormalizationAuto TextNormalization = "auto"
	TextNormalizationOn   TextNormalization = "on"
	TextNormalizationOff  TextNormalization = "off"
)

type TextTokenizer

type TextTokenizer interface {
	TokenizeSpans(string) []tokenize.Span
}

TextTokenizer is implemented by the core WordTokenizer and SentenceTokenizer. Spans allow the provider stream to retain an incomplete suffix across arbitrary caller chunk boundaries.

type UnsupportedEncodingError

type UnsupportedEncodingError struct {
	Encoding TTSEncoding
	Reason   string
}

func (*UnsupportedEncodingError) Error

func (e *UnsupportedEncodingError) Error() string

func (*UnsupportedEncodingError) Unwrap

func (e *UnsupportedEncodingError) Unwrap() error

type UnsupportedTransportError

type UnsupportedTransportError struct {
	Model     TTSModel
	Transport string
}

func (*UnsupportedTransportError) Error

func (e *UnsupportedTransportError) Error() string

func (*UnsupportedTransportError) Unwrap

func (e *UnsupportedTransportError) Unwrap() error

type VADOptions

type VADOptions struct {
	VADSilenceThreshold *time.Duration
	VADThreshold        *float64
	MinSpeechDuration   *time.Duration
	MinSilenceDuration  *time.Duration
}

VADOptions configures ElevenLabs realtime server-side VAD. Durations are serialized in the units required by the provider.

type Voice

type Voice struct {
	ID       string         `json:"voice_id"`
	Name     string         `json:"name"`
	Category string         `json:"category"`
	Settings *VoiceSettings `json:"settings,omitempty"`
}

type VoiceSettings

type VoiceSettings struct {
	Stability       float64  `json:"stability"`
	SimilarityBoost float64  `json:"similarity_boost"`
	Style           *float64 `json:"style,omitempty"`
	Speed           *float64 `json:"speed,omitempty"`
	UseSpeakerBoost *bool    `json:"use_speaker_boost,omitempty"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL