Raxol.Speech.Recognizer (RaxolSpeech v0.3.0)

Copy Markdown View Source

Speech recognition via Bumblebee/Whisper.

Wraps an Nx.Serving instance with a Whisper model for on-BEAM speech-to-text. Falls back gracefully when Bumblebee is not available.

Options

  • :model - HuggingFace model ID (default: "openai/whisper-tiny")
  • :compiler - Nx compiler (default: EXLA if available)
  • :recognize_timeout_ms - per-call transcription budget (default 30_000). The FIRST call after boot also pays the XLA graph compilation, which can take minutes on CPU; give a cold deployment a generous budget or warm the serving up front.
  • :load_model - load the model at start (default true). Loading fetches it from the Hugging Face Hub unless Bumblebee has it cached. With false the recognizer starts without one: available?/0 is false and recognize/1 returns {:error, :bumblebee_not_available}, as in a build without Bumblebee.

Summary

Functions

available?()

Returns whether the recognizer has a loaded model.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

handle_manager_cast(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_cast/2.

handle_manager_info(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_info/2.

recognize(audio_data)

Recognize speech from audio binary data.

start_link(init_opts \\ [])

Functions

available?()

@spec available?() :: boolean()

Returns whether the recognizer has a loaded model.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

handle_manager_cast(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_cast/2.

handle_manager_info(msg, state)

Callback implementation for Raxol.Core.Behaviours.BaseManager.handle_manager_info/2.

recognize(audio_data)

@spec recognize(binary()) :: {:ok, String.t()} | {:error, term()}

Recognize speech from audio binary data.

The binary must be raw PCM: 32-bit little-endian floats, one channel, at the model's sampling rate (16kHz for Whisper). Compressed audio (ogg/opus voice notes, mp3, wav) must be converted first, e.g.:

ffmpeg -i voice.ogg -f f32le -ac 1 -ar 16000 pipe:1

A binary that cannot be f32 PCM (empty, or not a multiple of 4 bytes) returns {:error, :invalid_pcm} without touching the model. Note the serving rejects whole WAV/AIFF/OGG files: container bytes are not samples.

Transcription runs in a separate Task to avoid blocking the GenServer.

start_link(init_opts \\ [])