Files
llama.cpp/ui/apps/chat/README.md
T
Aleksander GrygierandNicolas Mowen 79e81b0bd4 ui: voice messages and dictation with live waveforms and transcripts (#32531)
* ui: add a voice engine for capture, peaks and transcription

Voice input needs a live waveform, a clip that can be sent and drawn,
and a transcript, whether the model streams text while the user speaks
or not. This adds the engine for it in src/lib/voice, with no imports
of app stores or components, so it can move into a package later.

- VoiceCapture: one microphone start gives live levels (RMS on a dB
  curve, fixed history, newest last), PCM16 mono chunks at 16 kHz from
  an inline AudioWorklet (ScriptProcessor fallback), and on stop a
  16-bit mono WAV clip with its duration and peaks. Tracks, nodes and
  the context are released on stop, cancel, a failed start and page hide.
- computePeaks / computePeaksFromAudio: normalised peaks of samples, a
  buffer, or a stored base64 or Blob file.
- transcribeClip: POST /v1/audio/transcriptions, with the server's own
  error message on failure.
- RealtimeTranscriber: the /v1/realtime?intent=transcription socket,
  queueing audio until session.created, a final commit, and a typed
  RealtimeUnsupportedError when the model cannot stream or the socket
  is refused (a browser websocket cannot send the API key header).
- startVoiceSession and VoiceRecorder: try realtime, fall back to one
  HTTP transcription of the clip, and expose levels and live text.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: add voice waveform and transcript components to Llama UI

Voice input needs three visuals that the app can feed with its own
recording and transcription logic: the live waveform while recording,
a playable waveform of a recorded clip, and a clip with its transcript
that opens on hover, keyboard focus or a tap.

VoiceWaveformLive draws input levels as many bars as fit the width,
newest on the right, and holds still with reduced motion.
VoiceWaveform plays a clip through its own audio element, fills the
played part in the primary colour, seeks by press, drag and arrow keys
(a slider) and pauses any other clip that was playing.
VoiceTranscriptReveal keeps the transcript in the DOM for screen
readers while it is closed, and shows transcribing and error states.

The waveform math (resampling peaks, bar capacity, seek and time
formatting) is in src/lib/voice with unit tests. The components are
exported from the package root and from @ggml-org/llama-ui/voice, which
Llama Chat resolves to the sources like the other entry points.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: add stories and tests for the voice components

Storybook gets UI/Blocks/Voice: the live waveform fed by a fake
microphone meter in a chat form row, the clip waveform in its sizes and
states, and the transcript reveal in each state and on touch. The demo
audio is a WAV synthesised in the story, so no binary file is added.

The play functions check seeking by keys and by press, the reveal on
hover, keyboard focus and a tap, and a clip without audio. Pressing play
needs a real click before a browser plays audio, so a client test covers
play and pause and one clip pausing another.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: store voice messages with their transcript and send it to models that cannot hear

A voice message recorded in the chat form is an audio attachment like an
uploaded file, plus what the app needs to draw and read it. The audio
attachment gets four optional fields: voice (recorded in the app),
transcript, peaks and durationMs. Stored rows, export and import carry
them as they are, so no migration is needed and older messages keep
working.

The transcript is for reading. A model with audio input still gets the
audio alone; a model without it (the user switched models later) gets the
transcript as a labelled text part in place of the audio. When the
model's modalities are not known yet, or there is no transcript, the
audio goes as before.

A transcript often comes back after the message was sent. The new
voiceTranscriptsStore follows each pending transcript by the clip's name,
hands it to a send that happens after it arrived, and otherwise writes it
into the stored attachment of the message it went out with, in the open
chat or, if the user left it, in the database.

Copying a message now includes its voice transcript.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: add Voice settings and resolve what the microphone does per model

The user should not have to think about which kind of voice input is in
use, so the app decides it from the conversation's model and two
settings. resolveVoiceMode is a small pure function: with Voice input on
Automatic and a chat model that has audio input, a recording is a voice
message, transcribed by that same model so a router swaps nothing.
Otherwise it is dictation, with the chat model when it can hear, else,
in router mode, with the chosen transcription model. When no model can
transcribe, the microphone is unavailable and says why.

Settings get a Voice section of their own rather than more rows in
General, which is already long: these four belong together and one of
them lists the server's models.

- Voice input: Automatic (default) or Always dictate.
- Transcription model: Same as chat model (default) or, in router mode,
  any model with audio input; on a single-model server it only says
  whether that model can transcribe. It notes that dictating with
  another model loads it beside the chat model.
- Transcribe voice messages: on by default.
- Transcription language: empty for automatic.

The keys live in the settings registry like the others, so defaults,
storage, reset and export need nothing new. The model picker is drawn by
SettingsChatVoiceTab, the way Extensions and Tools draw their sections.

Assisted-by: Claude (Opus 5.5 Medium)
Co-authored-by: Nicolas Mowen <14866235+NickM-27@users.noreply.github.com>

* ui: record voice messages and dictation from the chat form

The microphone now does what the conversation's model allows, without
the user choosing a mode: its label says "Send a voice message" or
"Dictate", and when no model can take audio it is disabled and says why
(shown in router mode only when some model there has audio input, so the
reason can be acted on; a single-model server without audio keeps the
send button as before). The microphone errors keep their warning state
and toast, now also for the voice engine's own capture errors.

Recording goes through the voice engine's VoiceRecorder instead of the
MediaRecorder flow. While it records, the actions row becomes a
recording row: cancel, the live waveform, the elapsed time and stop.
Escape or cancel drops the recording. The form keeps its two rows while
recording, so the message stays visible on desktop and the row fits the
phone layouts and the expanded sheet.

- Dictation writes the live transcript into the message at the caret
  as it streams. DictationSpan replaces only the dictated stretch, moves
  it when the user types before it, keeps what is typed after it, and
  hands text the user edits over to them. When nothing streams, the row
  shows Transcribing... after stop and the text goes in once it is back.
  Cancel takes the dictated text out again. No audio is attached.
- A voice message streams its live text, if any, under the waveform,
  not into the message. On stop the clip is attached as a voice file
  with its peaks and length, and its transcript is followed by the voice
  transcripts store (unless Transcribe voice messages is off).

Realtime transcription is skipped for servers reached through a tunnel
or with an API key, which a browser websocket cannot carry. The first
dictation with a separate router model shows a one-time note that it
loads beside the chat model.

The form takes an optional voiceRecorder, so tests and stories can run
it without a microphone.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: draw audio attachments as playable waveforms with their transcript

A voice message should read as a clip, not as a file chip. Audio
attachments now render with Llama UI's VoiceWaveform inside
VoiceTranscriptReveal, through a direct branch in the core attachment
item (voice is core, so it does not go through the extension renderers):
the removable sm chip in the chat form, and the md clip in a sent
message, on the user bubble's surface.

- The audio plays from an object URL made from the stored base64 (or the
  uploaded file's data URL), revoked when the clip leaves the screen.
- A clip stored without peaks, an older voice message or an uploaded
  audio file, gets them computed from its audio once per session, in
  memory only; uploaded files keep their name under the waveform.
- The transcript opens under the clip on hover, keyboard focus or a tap,
  and shows Transcribing... while the voice transcripts store waits for
  it, Transcription unavailable when it failed, and nothing when none
  was asked for.
- The full-screen preview keeps its player and shows the transcript.

Tests run the chat form with a fake recorder: the microphone per mode,
the recording row, dictation around typed text, the Transcribing...
state, cancel, and a voice message chip whose transcript arrives later
and goes with the send. Stories show the form recording each kind, a
recorded chip, and sent voice messages with the transcript, pending,
and computed peaks.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: drop the old audio recorder and proxy realtime transcription in dev

The voice engine replaced AudioRecorder, so it goes. The dev server now
proxies WebSockets on /v1, so realtime transcription works under vite dev.
The VoiceCapture test waits for the tone to be recorded instead of a fixed
700 ms, which a loaded test run could miss.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: dictate with a model that is already loaded when the chat model cannot hear

The Transcription model setting's Automatic choice now falls back to a
router model with audio input that is already loaded, so dictating with a
text-only chat model works without picking a model and loads nothing.
A picked model still wins, and the empty value is a named constant.
Idea from upstream PR 27567, by NickM-27.

Assisted-by: Claude (Opus 5.5 Medium)
Co-authored-by: Nicolas Mowen <14866235+NickM-27@users.noreply.github.com>

* ui: fill the recording waveform, and open voice message transcripts

- The live waveform fills the row from the start: a recording shorter
  than the row is stretched over all its bars, a longer one scrolls with
  the newest level on the right. No dotted placeholder.
- A voice message's transcript is open under its clip, in the chat form
  while it comes in and in the sent message, with the toggle beside it
  to fold it.
- Settings > Voice > Collapse transcripts (off by default) keeps them
  folded instead, opening on hover, keyboard focus or a tap.

Assisted-by: Claude (Opus 5.5 Medium)
(cherry picked from commit 2a93f2f948ed976e40f693ce5d3acf1168284b05)

* ui: record voice without ducking other audio, from the first word

- Voice input asks for the raw microphone signal: no echo cancellation,
  noise suppression or auto gain. Echo cancellation made the system treat
  a recording as a call, which lowers or interrupts other playback, and
  auto gain faded the first words in.
- One AudioContext serves every recording, with the capture worklet
  loaded once, suspended in between and, where the browser allows it,
  without an output device, so recording never touches the speakers.
- The chat form prepares it when it gets focus (no microphone, so no
  recording indicator), and a mouse starts recording on press.
- A recording starts counting once audio flows: until then the bar says
  Starting... instead of running the timer. Development builds log how
  long each step of a start took.
- Settings > Voice > Microphone: Automatic (the system default, or the
  built-in microphone when the default is a Bluetooth headset, which
  would switch to its low-quality call mode), System default, or a
  listed microphone.

Assisted-by: Claude (Opus 5.5 Medium)
(cherry picked from commit 76643e7210d21617d734fdfde677e84af7273153)

* ui: show voice text live in the message box, and follow transcripts as spoken

- A model that hears but has no live ASR (e.g. LFM3-Omni) now gives text
  while you record: the realtime client commits the audio piece by piece,
  at the pauses the levels show, one piece at a time, and the final
  commit takes only what is left.
- A voice message's live text shows as the empty message box's
  placeholder. Clicking into the box makes it text to edit there, and
  what is said next follows it. On stop the text leaves the box and goes
  with the clip; when it was edited, the edit is the clip's transcript.
- Llama UI gains VoiceSpokenText and spokenLength(): spoken words in the
  full foreground colour, which they keep, the rest muted. A clip's
  transcript follows its playback (estimated over the parts with speech,
  as there are no word timings), and live text brightens as it arrives.
- The recording bar has a send button that stops and sends in one go.

Assisted-by: Claude (Opus 5.5 Medium)
(cherry picked from commit ce773017f902f8a5690ab9ecca368cecb6427422)

* ui: let the capture test start with silence

A capture starts with its first audio block, which can come before a
stream's first sound, so the steady tone is checked from where it begins.

Assisted-by: Claude (Opus 5.5 Medium)
(cherry picked from commit a41ee5337b83fef685a5cbaff176925f1647ce9d)

* ui: show live voice text sooner, and keep silence from becoming "yeah"

- A model that transcribes per commit (LFM3-Omni) gets shorter pieces:
  cut at a 0.35 s pause after speech, or at the next quiet moment once a
  piece reaches 3 s, so the text follows the speaker within a few
  seconds in dictation, the message box and voice mode.
- When the recording stops, the audio after the last piece is committed
  only if speech was heard in it. LFM3-Omni transcribes a commit of pure
  silence as "Yeah." (or "はい。"), which ended up at the end of the text.
  A recording whose only piece is that rest still commits it.

Assisted-by: Claude (Opus 5.5 Medium)
(cherry picked from commit 43e52cbab0fba9d8e84b9491890a406e3c6c90f3)

* ui: transcribe a recording cut at pauses once more as a whole

Live text comes piece by piece, cut at the speaker's short pauses, and a
model reads each piece as a sentence of its own: "I went. To the store."
When the recording ends, one pass over the whole clip gives the final
text, punctuated by meaning, in dictation and in voice mode alike. The
pieces' text stays the live text until then, and is kept when that pass
fails or the recording is longer than two minutes.

Assisted-by: Claude (Opus 5.5 Medium)
(cherry picked from commit 359dd9632e6c88000a1d23c2575bd1e6fcdd9ec1)

* ui: give live text over HTTP for models without a realtime session

A model that hears but cannot hold a realtime session, such as
Qwen3-ASR, was transcribed only after the recording, so dictation
showed no text while speaking. The recording is now cut at the
speaker's pauses as with a realtime session, and each piece sent to
/v1/audio/transcriptions on its own, one at a time, its text joined
live. The audio is kept from the start, so what is said while the
socket answers goes with the first piece. The whole clip is still
transcribed once more at the end, and the pieces' text is kept if
that fails. A server a websocket cannot reach (an API key, a remote
server) gets live text the same way.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: say when the browser processes the microphone despite the raw request

The browser keeps one processing setting per microphone: while a call,
another tab or voice mode has it open with echo cancellation, a
dictation that asked for the raw signal is processed too, sounds
distant, and the system may lower other sound. The capture now warns
when it gets processing it did not ask for, and its development log
names the microphone, its rate and what processing is on.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: keep the microphone beside the stop and send buttons

While a reply streams, or once the message has text, the microphone no longer
gives way to the main button: it stays beside it as a quieter, secondary
button, so more can be dictated without clearing the message or waiting for
the reply.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: show the voice components' stories with Llama UI

VoiceWaveform and VoiceTranscriptReveal are Llama UI components, so their
stories move to the library's Storybook, under Llama UI/Voice, with the demo
audio they play. Llama Chat's Storybook shows them there too, and its own
voice stories take the demo audio from the library. VoiceWaveformLive stays
with Llama Chat, as its demo records through the chat form's microphone.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: add a noise suppression setting for voice input

Recordings stay raw by default. Settings > Voice can now switch the
browser's noise suppression on; echo cancellation and automatic gain stay
off either way, as they interrupt other sound and fade the first words in.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: keep live voice text coming when the room is never quiet

Pieces were cut only at a quiet moment, so with music or talk in the room
none was ever cut and no text showed until the recording ended. A piece half
as long again as its longest length is now cut where it is.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: add echo cancellation and automatic gain settings for voice input

Settings > Voice now has a switch for each kind of microphone processing the
browser offers. All three stay off by default, so recordings are raw; each
one says what switching it on costs.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: put the microphone after the stop button, filled like it

While a reply streams, the microphone is the last button of the row and
looks like the stop and skip buttons beside it, instead of a bare icon
before them.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: say when dictated text is being refined, and send it refined

After a recording with live text, the whole clip is transcribed once more
so pauses do not end sentences. The form now says so while that pass is
out, and a send asked for meanwhile waits for it, so the message goes out
with the refined text rather than the pieces.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: keep the send button in place and put the microphone beside it

The send button no longer gives way to the microphone on an empty
message. The microphone stands before it as a quieter, tertiary button,
with the same tooltip, warning and recording states as before.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: let a recording be sent while a reply streams, once it has words

While a reply streams, the recording row now shows its send button as
soon as the first transcribed words are in the message, so the
recording no longer has to be stopped first. The microphone also stays
beside the send button once a voice message is attached.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: raise quiet speech for transcription, and say when it is too quiet

A quiet microphone gave the model near silence to transcribe. A new
Voice setting, Boost quiet speech (on by default), raises speech to a
level speech models hear well, up to eight times louder: the audio
streamed for live text as it goes, and the whole recording in one pass
when it stops, so its first words get the same gain as the rest. Only
speech is measured, never the silence around it, loud speech is left
as it is, and a soft limiter keeps raised peaks from clipping. When
speech stays quiet even at the highest gain, the recording row says so.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: keep the voice engine free of app code

The engine in lib/voice imported the microphone messages from the app's
utils and the WAV type from its enums, the only two things keeping it
from moving into a package of its own. The microphone checks and
messages move into the engine (voice/support.ts), next to the capture
that needs them; the uploaded-file helpers stay in the app's utils.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: start voice sessions from one voice service

How a recording reaches the server (routes, API key, whether the
realtime socket can be used) and how the Voice settings become capture
and transcribe options were built inside the chat form's voice hook,
and copied into every other feature that records. VoiceService builds
them in one place: a feature asks it for its session options and adds
only its own callbacks.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: tell speech from the room in one place

The pause detector, the speech gain and (in voice mode) the listener for
speech over a reply each followed a noise floor with their own numbers.
A SpeechDetector now does it for all of them, in dB, with one set of
settings in VOICE_SPEECH.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: let any text field take dictation

Writing dictated text into a field (at the caret, around the user's
typing, replaced by the whole recording's text when it comes) moves out
of the chat form's hook into a plain createDictation(). The hook keeps
what is the chat form's own: voice messages, toasts and the hint.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: move the recording row into Llama UI

VoiceRecordingBar draws the row shown while recording (cancel, waveform
and time, send, and a caption or warning under it) from data alone, so
voice mode or a notes page can show the same row. The chat form passes
its labels and its microphone button as the stop button.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: keep the voice engine's Svelte recorder behind its own entry

VoiceRecorder, the one part of lib/voice written with runes, moves to
lib/voice/svelte, so the rest of the engine is plain TypeScript any app
can use without Svelte.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: move voice input into its own package, Llama Voice

The voice engine (capture, the speech signal, transcription over the
realtime socket or HTTP) and dictation into a text field move from the
app to ui/lib/voice as @ggml-org/llama-voice, so another app, such as a
notes app, can use them. The Svelte recorder is its ./svelte entry.
Llama Chat compiles the sources, as it does Llama UI's, and keeps its
server and settings wiring. The package has its own type check, tests
and build, and a CI job for them.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: show which model does what in voice input

The model picker and the Models manager mark each model that hears:
Dictation on the one that transcribes dictation, Speech to text on
transcription models such as Qwen3-ASR, and Voice on chat models that
take voice messages. A loaded model kept only for dictation sits apart
from the chat models, a model can be made the dictation model from its
row, and Settings > Voice groups the transcription models apart from
the chat models with audio input. A voice store now resolves what the
microphone does, for the chat form and the model lists alike.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: warn of a quiet microphone inside the recording row

The too-quiet line under the waveform made the form grow and jump. The
warning now stays inside the row: the waveform turns the warning colour,
an icon sits by the time, and the advice opens above the row in a
tooltip for a few seconds, then on hover or focus. Screen readers still
hear it when it appears.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: open the microphone while the pointer is on its button

The first seconds of a recording could come out quiet while the
microphone settled, and the too-quiet warning showed for them. With the
pointer or the focus on the microphone button, the microphone now opens
ahead of the press (only when the page may already use it, so nothing
asks), and the recording takes it at once; it is let go shortly after
the pointer leaves without a press. The warning also waits until the
speech has stayed too quiet for two seconds.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: tidy voice input after review

Fix a microphone left open when a recording is cancelled while it starts
or the pointer leaves while it opens, a capture that is still letting go
silencing the next one, and live text stopping after a realtime error.
Share the dictation model choice, the transcript lookup, base64 decoding,
PCM joining and stopping a stream instead of repeating them, and export
only Llama Voice's public API.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: pin Llama Voice's dev dependencies to Llama UI's versions

Assisted-by: Claude (Opus 5.5 Medium)

* ui: let demos speak into a synthetic microphone

Assisted-by: Claude (Opus 5.5 Medium)

* ui: keep the microphone for voice input, off the audio files entry

The attach menu's Audio Files entry used a microphone, which now sits
beside the form's own microphone button. The microphone stands for
recording and dictation only; a model's audio modality is headphones, and
the audio files entry is a file with headphones.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: set voice input on the slimmed design tokens

Voice input's components use the type roles, the one corner scale and
shadcn's utility names for the neutral colours, as the rest of Llama UI
and Llama Chat do since the design tokens were slimmed down.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: name voice states, platform strings, patterns and tunings

Addresses the review on the voice PR:

- Llama Voice: VoiceCaptureState, VoiceRecorderStatus, RealtimeState and
  RealtimeUnsupportedReason are enums (src/enums.ts, exported); DOMException
  names, AudioContext states, transcription form fields, socket protocols,
  device kinds, worklet messages, error messages, regexes and tuning values
  are named constants.
- Llama UI: VoiceTranscriptStatus, VoiceWaveformSize and
  VoiceRecordingBarStatus are enums; KeyboardKey, MouseButton and PointerType
  join its UI enums; the voice components' sizes, labels, timings, selectors
  and patterns move to constants/voice.constants.ts. The voice unit tests
  move from src to tests/unit.
- App: ChatFormVoiceState is an enum, the recording bar's status comes from a
  map, and the voice code uses the enums above, BooleanString, HEADERS and
  new voice constants in place of inline strings, regexes and numbers.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: keep all of Llama UI's tests under tests

The Model UI formatting spec moves to tests/unit and the button spec to
tests/client, next to the voice specs; the test projects now read only
tests/unit and tests/client.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: show a transcript's words without the model's own format

Qwen3-ASR names the language before its text (language French<asr_text>...) and
VibeVoice-ASR answers with timed segments as JSON, which the server passes on as they
are. The voice engine now takes both off, over HTTP and over the realtime socket, also
while segments still stream, so the message box and the clip show the words alone.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: dictate when a speech-to-text model is picked for the conversation

A speech-to-text model has audio input, so on Automatic the microphone recorded a voice
message for it, which such a model has nothing to answer with. It now dictates, as the
model's badge already says it is for.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: say why a live-only model cannot transcribe behind an API key

A browser websocket cannot send the API key, so the realtime socket is left out on a
server that needs one, and a model that only transcribes over it (Voxtral Realtime)
answers the HTTP route with a 501. The clip and the dictation toast now say so instead of
only that transcription is unavailable.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: pick the dictation model with a microphone on its row

The model that transcribes dictation was marked with a filled Dictation badge. It is now
marked by a red microphone among the row's actions in the model picker, beside the heart,
and every other model that hears shows the same microphone on hover: a click makes it the
transcription model, and a click on the chosen one hands the choice back to Automatic. The
badge keeps saying what kind of hearing model a row is, and the Models manager marks the
dictation model with a small microphone beside its name.

Assisted-by: Claude (Opus 5.5 Medium)

---------

Co-authored-by: Nicolas Mowen <14866235+NickM-27@users.noreply.github.com>
2026-11-20 16:34:52 +01:00

13 KiB

Llama Chat

Llama Chat is the chat app for llama.cpp: a web interface for llama-server, built with SvelteKit on Llama UI (@ggml-org/llama-ui), the design system in ui/lib/ui. llama-server embeds it, and npx llama-chat runs it anywhere.

It works with a llama-server in either mode: MODEL (one model) or ROUTER (many models, loaded and unloaded on demand).

Contents

Run it with npx

Llama Chat is published to npm as @ggml-org/llama-chat, with llama-chat as its short name. It serves the prebuilt app as static files on localhost, or writes them to a folder for any static file server (see Self-hosting); it brings no server and no models of its own. It needs Node.js 20 or later.

npx @ggml-org/llama-chat                 # serve it on http://127.0.0.1:3000 and open the browser
npx llama-chat --host 0.0.0.0 --no-open  # the same, by its short name, reachable from other devices
npx llama-chat build                     # write the static app to ./llama-chat instead
Flag Default What it does
--port <n> 3000 Fixed, so the origin, and the chats the browser stores under it, stay the same between runs
--host <addr> 127.0.0.1 0.0.0.0 to open it to the LAN
--open / --no-open open Opens the default browser once it listens
-v, --version, -h, --help As usual

The bare command is the documented form; start is accepted as an alias for it. build takes --out <dir> (default ./llama-chat) and --force, which lets it write into a folder that is not empty.

How it works: the CLI only serves the files of dist, with llama-server's headers for the UI (index.html cross-origin isolated, the PWA files revalidated, hashed assets cached for good), and forwards nothing. The browser talks to each llama-server you add in the app by URL directly, so llama-server's own rules apply: start it with --cors-origins http://127.0.0.1:3000 (the address you open) when it restricts origins, as it does with tools or MCP enabled, and with --api-key when it is reachable from the LAN. An http:// page like this one can reach a plain http:// llama-server on the LAN, which an https:// page cannot.

Self-hosting

The app is static and uses relative paths and a hash router, so any static host can serve it at any path. npx @ggml-org/llama-chat build --out <dir> writes the files (as does npm run build here, to dist); serve them with any static file server, for example npx http-server llama-chat -p 3000. Send the headers listed above with index.html and the PWA files, so the app behaves as it does under llama-server (see Cross-origin isolation).

The app reaches the llama-server on its own origin, if there is one (llama-server serves it with --path, or your reverse proxy puts the API next to the files), and any other llama-server you add by URL, which needs --cors-origins for the app's address.

Features

  • Chat - streaming replies, reasoning blocks, branching by edit or regenerate, tabs, search, import and export
  • Attachments - images, PDFs (as text or as pages for vision models), audio and text files, by drag and drop or paste
  • Rendering - Markdown (GFM), code highlighting, KaTeX math and Mermaid diagrams
  • Models - in ROUTER mode, a selector and a models manager: load and unload, downloads, Discover from the Hugging Face Hub, favorites and hidden models
  • Tools - built-in browser tools, llama-server's tools and MCP servers, each behind a permission prompt
  • Everywhere - light and dark themes, phone layouts, installable as a PWA, keyboard shortcuts (Ctrl/Cmd+K search, Shift+Ctrl/Cmd+O new chat, Ctrl/Cmd+B sidebar)

Development

You need Node.js 20 or later and a llama-server to talk to.

cd ui/apps/chat
npm ci
npm run dev     # the app on http://localhost:5173, Storybook on http://localhost:6006

The dev server forwards the API (/v1, /props, /models, /tools, /slots, /cors-proxy) to llama-server on http://localhost:9931, or to VITE_PUBLIC_SERVER_ORIGIN when it is set.

Command What it does
npm run build The production build, in dist/
npm run check Type checking with svelte-check
npm run lint Prettier and ESLint; npm run format fixes what they can
npm run test:unit Unit tests (Vitest, tests/unit)
npm run test:client Component tests in the browser (Vitest, tests/client)
npm run test:ui Storybook stories run as tests (tests/stories)
npm run test:e2e End-to-end tests (Playwright, tests/e2e), with a llama-server
npm run storybook Storybook on its own

Locally the browser tests run in your installed Google Chrome; CI uses Playwright's bundled Chromium.

Architecture

Llama Chat is the first app on Llama UI, and the reference for the line between library and app: Llama UI draws and handles interaction, the app decides what happens.

  • In Llama UI: components, design tokens, fonts and surfaces, and the logic inside them (keyboard navigation, validation as you type, formatting a file size). Components take data in and report what the user did out.
  • In Llama Chat: talking to llama-server, storing conversations, the agentic loop and its tool permissions, MCP servers, managing models, settings.

The app imports the library as @ggml-org/llama-ui/ui/<name> and compiles its sources in its own build, with no install of the library (see scripts/vite-plugin-llama-ui.ts). Data flows one way, through these layers:

Layer Lives in What it holds
Routes src/routes /, /chat/[id], /models, /mcp-servers, /settings, /search
App components src/lib/components/app Chat, navigation, models, MCP, settings and dialogs, grouped by area
UI components ui/lib/ui shadcn-svelte on bits-ui, from Llama UI
Voice ui/lib/voice Microphone capture, transcription and dictation, from Llama Voice (@ggml-org/llama-voice)
Hooks src/lib/hooks View logic between components and stores: scroll, drag and drop, pickers, keyboard
Stores src/lib/stores Application state as Svelte 5 runes: chat, conversations, the agentic loop, tools, models, settings
Services src/lib/services Stateless I/O: the llama-server API, IndexedDB, MCP, the Hugging Face Hub, the tool sandbox
Storage + API the browser, llama-server IndexedDB and localStorage; llama-server's /v1, /props, /models, /tools, /slots
flowchart LR
    Routes --> Components["App components"]
    Components --> Hooks
    Components --> Stores
    Hooks --> Stores
    Stores --> Services
    Services --> DB[("IndexedDB, localStorage")]
    Services --> API["llama-server"]
    Components -. "imports" .-> UI["Llama UI"]
    Stores -. "reactive state" .-> Components

Sending a message

sequenceDiagram
    participant User
    participant Stores
    participant DB as IndexedDB
    participant API as llama-server

    Note over Stores,API: on start
    Stores->>API: GET /props, then the model list
    User->>Stores: send a message
    opt ROUTER mode, model not loaded
        Stores->>API: POST /models/load, then poll GET /models
    end
    Stores->>DB: save the user message
    Stores->>API: POST /v1/chat/completions (stream)
    loop streaming
        API-->>Stores: SSE chunks, shown as they arrive
    end
    opt the model called tools
        Stores->>Stores: run them (after permission), send the results, stream again
    end
    Stores->>DB: save the assistant message

Patterns worth knowing

  • Stores hold state as Svelte 5 runes ($state, $derived); larger ones live in folders and compose focused sub-stores. Services are stateless and do all I/O.
  • Per-conversation state: streaming, loading and abort controllers are kept per conversation, so several chats can stream at once.
  • Messages form a tree: each message knows its parent and children, and a conversation points at the branch tip it shows, so editing or regenerating branches without losing history.
  • Server role: one codebase serves MODEL and ROUTER mode; serverStore reads the role from /props, and ROUTER-only UI shows only there.
  • Modalities: attachments a model cannot read (images for a text-only model, say) are refused before sending, from the model's /props.
  • Storage: conversations and messages in IndexedDB (Dexie), settings and model preferences in localStorage, server state and Hub details in memory only.

Cross-origin isolation

llama-server serves the UI with Cross-Origin-Embedder-Policy: require-corp and Cross-Origin-Opener-Policy: same-origin, so every cross-origin asset needs the other origin's consent. Hugging Face Hub avatars and metadata are requested in CORS mode, which the Hub allows. MCP server icons and search-result favicons go through llama-server's /cors-proxy when it runs with --ui-mcp-proxy, and fall back to a bundled icon otherwise.

Build and embedding

npm run build generates the PWA icons, bundles the app with Vite and writes it to dist/ (or to LLAMA_UI_OUT_DIR) as static files: index.html, one JS and one CSS bundle under _app/, the service worker, the web manifest and build.json with the version (LLAMA_BUILD_NUMBER, b0000 locally). Paths are relative and routing uses the URL hash, so dist works from any path.

llama-server embeds it: when llama-server is built, scripts/ui-assets.cmake takes ui/apps/chat/dist if it exists, runs npm run build if LLAMA_BUILD_UI is on, or downloads the release's prebuilt dist.tar.gz from Hugging Face, and compiles every file into the binary. The same dist is what npx @ggml-org/llama-chat serves.

ui/apps/chat/
├── src/
│   ├── lib/              # components, hooks, stores, services, types, utils, constants, enums
│   ├── routes/           # SvelteKit routes
│   └── service-worker/   # the PWA's service worker
├── bin/, cli/            # the npx llama-chat command and its server
├── alias/                # the llama-chat npm package, the short name
├── scripts/              # Vite plugins and build scripts
├── static/               # static assets
└── tests/                # unit, client and end-to-end tests, and the Storybook stories

Publishing to npm

Two packages go out with the same version: @ggml-org/llama-chat, which carries the app and the CLI, and llama-chat (in alias/), which depends on it and only forwards to its CLI so that npx llama-chat works. A unit test (tests/unit/cli.test.ts) fails when their versions drift apart.

The version is set by hand and CI publishes it, as for @ggml-org/llama-ui (see Releases). To release, bump the version in the PR that should ship it:

cd ui/apps/chat
npm version <version> --no-git-tag-version
# then set the same version, and the same @ggml-org/llama-chat dependency, in alias/package.json

Once that reaches master, ui-chat-publish.yml builds dist, checks that the package holds dist/index.html and no source maps, and publishes both packages with npm trusted publishing. A version npm already has publishes nothing, and a PR that changes the packages gets a dry run.

To try a package before it is published:

npm run build
npm pack
npx ./ggml-org-llama-chat-<version>.tgz

Build right before packing: the package carries whatever is in dist, and this folder's .npmrc sets ignore-scripts, so npm runs no lifecycle script such as prepack that could build it for you.