HipcallTts.Provider behaviour (hipcall_tts v0.5.0)

Behaviour for Text-to-Speech (TTS) providers.

This behaviour defines the contract that all TTS providers must implement. It includes callbacks for generating speech, streaming audio, validating parameters, and querying provider capabilities.

Types

params - Parameters for TTS generation (text, voice, model, etc.)
result - The generated audio data
error - Error information when generation fails
model - TTS model information
voice - Voice information (name, gender, language, etc.)
language - Language information
capabilities - Provider capabilities (streaming, formats, etc.)

Example

defmodule MyProvider do
  @behaviour HipcallTts.Provider

  @impl HipcallTts.Provider
  def generate(params) do
    # Implementation
  end

  # ... other callbacks
end

Summary

Types

capabilities()

error()

language()

model()

params()

result()

voice()

Callbacks

capabilities()

Returns the capabilities of this provider.

compatible_models(voice_id)

Returns the list of models compatible with a specific voice.

generate(params)

Generates speech audio from the given parameters.

languages()

Returns a list of supported languages for this provider.

models()

Returns a list of available models for this provider.

stream(params)

Streams speech audio generation from the given parameters.

validate_params(params)

Validates the given parameters before attempting generation.

voices()

Returns a list of available voices for this provider.

Types

capabilities()

@type capabilities() :: %{
  streaming: boolean(),
  formats: [String.t()],
  sample_rates: [integer()],
  max_text_length: integer() | :infinity
}

error()

@type error() :: %{message: String.t(), code: atom()} | String.t()

language()

@type language() :: %{code: String.t(), name: String.t(), locale: String.t() | nil}

model()

@type model() :: %{
  id: String.t(),
  name: String.t(),
  description: String.t() | nil,
  languages: [String.t()] | nil
}

params()

@type params() :: keyword() | map()

result()

@type result() ::
  binary() | %{audio: binary(), format: String.t(), sample_rate: integer()}

voice()

@type voice() :: %{
  id: String.t(),
  name: String.t(),
  gender: :male | :female | :neutral | nil,
  language: String.t() | [String.t()],
  locale: String.t() | nil,
  supported_models: [String.t()] | nil
}

Callbacks

capabilities()

@callback capabilities() :: capabilities()

Returns the capabilities of this provider.

This includes information about supported features like streaming, audio formats, sample rates, and text length limits.

Examples

caps = Provider.capabilities()
# => %{streaming: true, formats: ["mp3", "wav"], ...}

compatible_models(voice_id)

@callback compatible_models(voice_id :: String.t()) :: [model()]

Returns the list of models compatible with a specific voice.

For providers where some voices only support certain models/engines (e.g., AWS Polly), this filters the model list accordingly. For providers where all voices support all models, this returns the full model list.

Examples

models = Provider.compatible_models("Filiz")
# => [%{id: "standard", ...}]

models = Provider.compatible_models("Amy")
# => [%{id: "standard", ...}, %{id: "neural", ...}]

generate(params)

@callback generate(params()) :: {:ok, result()} | {:error, error()}

Generates speech audio from the given parameters.

Returns {:ok, result} on success or {:error, error} on failure.

Parameters

The params should include at minimum:

:text or "text" - The text to convert to speech
:voice or "voice" - The voice identifier to use
:model or "model" - The model identifier to use (optional)

Examples

{:ok, audio_data} = Provider.generate(text: "Hello", voice: "en-US-Standard-A")
{:error, "Invalid voice"} = Provider.generate(text: "Hello", voice: "invalid")

languages()

@callback languages() :: [language()]

Returns a list of supported languages for this provider.

Examples

languages = Provider.languages()
# => [%{code: "en", name: "English", ...}, ...]

models()

@callback models() :: [model()]

Returns a list of available models for this provider.

Examples

models = Provider.models()
# => [%{id: "model-1", name: "Standard Model", ...}, ...]

stream(params)

@callback stream(params()) :: {:ok, Enumerable.t()} | {:error, error()}

Streams speech audio generation from the given parameters.

Returns {:ok, Enumerable.t()} that yields audio chunks, or {:error, error} on failure.

This is useful for long texts or real-time applications where you want to start playing audio before the entire generation is complete.

Examples

{:ok, stream} = Provider.stream(text: "Long text...", voice: "en-US-Standard-A")
Enum.each(stream, fn chunk -> play_audio(chunk) end)

validate_params(params)

@callback validate_params(params()) :: :ok | {:error, String.t()}

Validates the given parameters before attempting generation.

Returns :ok if parameters are valid, or {:error, String.t()} with a description of the validation error.

This allows clients to check parameters before making potentially expensive API calls.

Examples

:ok = Provider.validate_params(text: "Hello", voice: "en-US-Standard-A")
{:error, "Text cannot be empty"} = Provider.validate_params(text: "", voice: "en-US-Standard-A")

voices()

@callback voices() :: [voice()]

Returns a list of available voices for this provider.

Examples

voices = Provider.voices()
# => [%{id: "voice-1", name: "Alice", gender: :female, ...}, ...]