Transcribe and dictate

pip install fermion-research
pip install mlx mlx-audio mlx-lm soundfile scipy zstandard
fermion models
fermion transcribe phonon-2 meeting.wav

The second line is the speech runtime on Apple silicon: a small MLX stack, installed once and separately from the CLI; if anything is missing, fermion transcribe prints the exact command. On Linux and Windows the same commands run on the CPU after pip install fermion-research torch safetensors soundfile scipy zstandard. Speech platforms has the notes for each platform and the container images.

fermion transcribe phonon-2 meeting.wav
fermion transcribe phonon-2 clip.flac --json

transcribe turns an audio file into a line of text. It reads anything libsndfile decodes: wav, flac, ogg, and aiff at any sample rate or channel count, resampled to 16 kHz mono. mp3 and m4a are refused with the exact ffmpeg conversion command to run first.

Standard output carries only the transcript, so fermion transcribe phonon-2 clip.wav > out.txt writes exactly the words. Progress, warnings, and timings go to standard error. --json returns a JSON object with the text, the model id, the decode-only and wall-clock seconds, a start and end time per decoded segment, awords list with the start and end of every word in seconds from the start of the file (Phonon-2; Phonon-1 returns null), and a truncated flag that is true if any segment ran out of token budget. There are no sampler flags: transcription decodes greedily, and punctuation and capitalization come from the model itself.

Phonon-2 transcribes a single stream at 174 times realtime on an M5 MacBook Air, decode time with the model already loaded. The first command in a session loads the engine (10 to 40 s); transcription itself runs at the quoted speed. Files longer than 35 s are decoded in 25 to 35 s windows cut at pauses, each with its own token budget, and the window transcripts are joined with single spaces.

fermion transcribe phonon-2 call.wav --hotwords "Ada, Quillon, Neutrino"
fermion transcribe phonon-2 call.wav --hotwords @names.txt
fermion listen phonon-2 --hotwords "Ada, Quillon"

Hotwords are names and terms you want the model to get right: people, products, places, project names, jargon. Give Phonon-2 up to 25 of them and the decoder favours them whenever the audio is close. The audio still decides: a listed word that was not said stays out of the transcript. Without hotwords the transcript is unchanged.

--hotwords takes comma-separated terms and is repeatable; @FILE or --hotwords-file reads one term per line, with # starting a comment. Multi-word terms such as Ada Lovelace are kept whole. --hotword-lambda sets how hard the listed words pull (default 2.0). Hotwords work on every Phonon-2 engine: Apple silicon, the CPU engine on Linux, Windows and macOS, and the CUDA image.

import fermion

speech = fermion.load_speech("phonon-2")
text, decode_s, audio_s = speech.transcribe("call.wav", hotwords=["Ada", "Quillon", "Neutrino"])

In Python, transcribe, transcribe_detailed and transcribe_array take hotwords=[...] and hotword_lambda= for that call; speech.set_hotwords([...]) sets them for every later call. The server takes them per request, as a hotwords field or the OpenAI prompt field read as a vocabulary list:

client.audio.transcriptions.create(model="phonon-2", file=open("call.wav", "rb"), prompt="Ada, Quillon, Neutrino")

The full reference, including how the words are favoured, is docs/hotwords.md in the phonon repository.

fermion listen phonon-2
fermion listen phonon-2 > note.txt
fermion listen phonon-2 --wav clip.wav

listen transcribes the microphone live. The current hypothesis updates on one terminal line, finished segments print permanently, and Ctrl-C stops the session and prints the full transcript to standard output.--wav streams a file through the identical live path, paced to real time.

• The first hypothesis appears after about 0.35 s of speech and updates about twice per second.
• A segment finalizes after about 0.7 s of silence, or at the 30 s segment cap.
• On macOS, grant your terminal microphone access under System Settings, Privacy & Security, Microphone.

fermion serve phonon-2

With a speech model, serve mounts the audio routes and answers OpenAI audio clients unmodified againstbase_url=http://127.0.0.1:8000/v1. The chat routes are not mounted; a request to one returns a 404 naming the endpoint that exists.

curl -s http://127.0.0.1:8000/v1/audio/transcriptions \
  -F file=@clip.wav
# {"text": "The transcript."}

response_format selects json (default), text, or verbose_json. Withtimestamp_granularities=word, verbose_json carries a words list (word, start, end) and thesegments list, in the shape OpenAI clients expect. Themodel form field is checked: a name this process does not serve returns 404 rather than a transcript from a different model. Request bodies are capped at 32 MB; the model handles utterances up to 30 s and decodes longer audio in chunks. --api-key requires a bearer token on every /v1 route. The container images serve this same API.

Streaming API covers the live WebSocket route: the opening frame, audio formats, server frames, and session limits.

Phonon-2 is the default and the more accurate model: a 164 MB download that averages 5.21 % word error across the seven public English test sets of the Open ASR Leaderboard, scored with the leaderboard's own scorer on the full test sets. Phonon-1 remains one model name away, phonon-1, and Phonon-1 Micro is the smallest download.

fermion transcribe phonon-2 meeting.wav
fermion transcribe phonon-1 meeting.wav
fermion listen FermionResearch/Phonon-1-Micro

All of them transcribe English from 16 kHz audio. The Phonon-1 models were trained at 2.4 bits per weight from the start and are open under Apache 2.0; the Phonon-2 weights are released under CC-BY-4.0. fermion models lists every published model and marks the ones already on your machine. Speech models lists every Phonon release with its measurements.