HipcallTts.Schema (hipcall_tts v0.5.0)

Defines the schema for HipcallTts parameters using NimbleOptions.

This module provides a comprehensive schema for validating TTS generation parameters, including nested retry options.

Usage

opts = [
  provider: :openai,
  text: "Hello, world!",
  voice: "en-US-Standard-A",
  retry_opts: [max_attempts: 3, initial_delay: 1000]
]

case NimbleOptions.validate(opts, HipcallTts.Schema.generate_schema()) do
  {:ok, validated_opts} ->
    # Use validated_opts
  {:error, error} ->
    # Handle validation error
end

Summary

Functions

generate_schema()

Generates the NimbleOptions schema for TTS generation parameters.

retry_opts_schema()

Generates the schema for nested retry options.

Functions

generate_schema()

Generates the NimbleOptions schema for TTS generation parameters.

Required Parameters

:provider - The TTS provider to use (:openai, :elevenlabs, :polly, or :soniox)
:text - The text to convert to speech

Optional Parameters

:voice - The voice identifier to use for speech synthesis
:model - The model identifier to use (provider-specific)
:format - Audio format (e.g., "mp3", "wav", "ogg")
:sample_rate - Sample rate in Hz (e.g., 22050, 44100)
:speed - Speech speed/rate (float, typically 0.25 to 4.0)
:pitch - Voice pitch adjustment (float, typically -20.0 to 20.0)
:language - Language code (e.g., "en-US", "en-GB")
:retry_opts - Nested keyword list of retry configuration options

Retry Options

The :retry_opts parameter accepts a nested keyword list with:

:max_attempts - Maximum number of retry attempts (default: 3)
:initial_delay - Initial delay before first retry in milliseconds (default: 1000)
:max_delay - Maximum delay between retries in milliseconds (default: 10000)
:backoff_factor - Exponential backoff multiplier (default: 2.0)
:retryable_errors - List of error codes/atoms that should trigger retries (default: [])

Examples

# Minimal valid params
opts = [provider: :openai, text: "Hello"]

# Full params with retry options
opts = [
  provider: :openai,
  text: "Hello, world!",
  voice: "en-US-Standard-A",
  model: "tts-1",
  format: "mp3",
  sample_rate: 44100,
  speed: 1.0,
  pitch: 0.0,
  language: "en-US",
  retry_opts: [
    max_attempts: 5,
    initial_delay: 500,
    max_delay: 5000,
    backoff_factor: 1.5,
    retryable_errors: [:timeout, :network_error]
  ]
]

retry_opts_schema()

@spec retry_opts_schema() :: [
  {:backoff_factor, [{any(), any()}, ...]}
  | {:initial_delay, [{any(), any()}, ...]}
  | {:max_attempts, [{any(), any()}, ...]}
  | {:max_delay, [{any(), any()}, ...]}
  | {:retryable_errors, [{any(), any()}, ...]},
  ...
]

Generates the schema for nested retry options.

This is used internally by generate_schema/0 but can also be used independently to validate retry options separately.

Options

:max_attempts - Maximum number of retry attempts (default: 3)
:initial_delay - Initial delay before first retry in milliseconds (default: 1000)
:max_delay - Maximum delay between retries in milliseconds (default: 10000)
:backoff_factor - Exponential backoff multiplier (default: 2.0)
:retryable_errors - List of error codes/atoms that should trigger retries (default: [])

Examples

retry_opts = [
  max_attempts: 5,
  initial_delay: 500,
  max_delay: 5000,
  backoff_factor: 1.5,
  retryable_errors: [:timeout, :network_error]
]

case NimbleOptions.validate(retry_opts, HipcallTts.Schema.retry_opts_schema()) do
  {:ok, validated} -> # Use validated options
  {:error, error} -> # Handle error
end