PhxDemo.TTS behaviour (phx_demo v0.1.1)

Copy Markdown View Source

Text-to-speech for PhxDemo.Steps.say/3.

Narration is on by default, using PhxDemo.TTS.Piper: a free, local, open-source voice. Run mix phx_demo.piper.setup once to install it. Choose another adapter, or turn narration off, in config/test.exs:

config :phx_demo, :tts, {PhxDemo.TTS.Piper, voice: "en_US-amy-medium"}
config :phx_demo, :tts, {PhxDemo.TTS.OpenAI, voice: "nova"}         # OPENAI_API_KEY
config :phx_demo, :tts, {PhxDemo.TTS.ElevenLabs, voice_id: "..."}  # ELEVENLABS_API_KEY
config :phx_demo, :tts, PhxDemo.TTS.MacSay                         # macOS only
config :phx_demo, :tts, false                                      # captions only

With an adapter, each say line is synthesized before it plays (cached by adapter, options and text), the demo pauses for the clip's real length, and mix demo.record mixes the clips into the MP4 at the right offsets.

Writing an adapter

Implement synthesize/3: write audio for text to path (no extension; add the one you produce) and return the final path. Any format ffmpeg reads works. Optionally implement check/1 to fail fast, before any demo runs, when the adapter isn't usable (missing binary, API key, …).

Summary

Callbacks

check(opts)
synthesize(text, path, opts)

Functions

cache_dir()

User-level cache directory for downloaded voices and tools.

check()

Runs the configured adapter's check/1, if any.

config()

The configured {adapter, opts}, or nil when narration is off. Defaults to Piper.

speak(text, opts \\ [])

Synthesizes text with the configured adapter, using a cache under <output_dir>/.tts_cache. Returns {:ok, %{path: path, duration_ms: ms}}, or :disabled when no adapter is configured.

Callbacks

check(opts)

(optional) 
@callback check(opts :: keyword()) :: :ok | {:error, String.t()}

synthesize(text, path, opts)

@callback synthesize(text :: String.t(), path :: Path.t(), opts :: keyword()) ::
  {:ok, Path.t()} | {:error, term()}

Functions

cache_dir()

User-level cache directory for downloaded voices and tools.

check()

Runs the configured adapter's check/1, if any.

config()

The configured {adapter, opts}, or nil when narration is off. Defaults to Piper.

speak(text, opts \\ [])

Synthesizes text with the configured adapter, using a cache under <output_dir>/.tts_cache. Returns {:ok, %{path: path, duration_ms: ms}}, or :disabled when no adapter is configured.