---
name: Transcripts CRUD and search
type: architecture-map-page
slice: 02-tauri-runtime
last_verified: 2026/05/09
---

# `commands::transcripts`

> **Where you are:** [Architecture map](../../README.md) → [Tauri runtime](../README.md) → [Commands](README.md) → Transcripts

**Plain English summary.** SQLite-backed transcripts: insert, paginated list, count, get, update text/title, patch metadata (starred, manual_tags, template, language, segments_json, llm_tags), delete, and FTS5 search. Replaces the old localStorage cache. Day 4 of the upgrade plan; the History page rename flow had a TODO waiting on `update_transcript` to exist, and now it does. The legacy global-dictionary commands (`list_dictionary_command` and friends) were removed — profile-scoped `profile_terms` is now canonical.

## At a glance

- Path: `src-tauri/src/commands/transcripts.rs`.
- LOC: 253.
- Tauri commands exposed (8 total):
  - `add_transcript(state, transcript: CreateTranscriptRequest) -> Result<(), String>`.
  - `list_transcripts(state, limit, offset) -> Result<Vec<TranscriptDto>, String>` — defaults 50 rows, clamp 1..=500.
  - `count_transcripts_command(state) -> Result<i64, String>`.
  - `get_transcript(state, id) -> Result<Option<TranscriptDto>, String>`.
  - `update_transcript(state, id, text: Option<String>, title: Option<String>) -> Result<u64, String>` — returns affected row count (0 if id not found).
  - `update_transcript_meta_cmd(state, id, patch: UpdateTranscriptMetaRequest) -> Result<TranscriptDto, String>` — patch shape with COALESCE semantics.
  - `delete_transcript(state, id) -> Result<(), String>`.
  - `search_transcripts(state, query) -> Result<Vec<TranscriptDto>, String>` — FTS5; up to 50 best-rank.
- Events emitted: none.
- Depends on: `lumotia_storage::{insert_transcript, list_transcripts_paged, count_transcripts, get_transcript, update_transcript, update_transcript_meta, delete_transcript, search_transcripts, InsertTranscriptParams, TranscriptRow, DEFAULT_PROFILE_ID}`.
- Called from frontend at: History page (list / search / get / update / delete), dictation result panel (`add_transcript`), Settings → About (`count_transcripts_command`), History viewer window (`update_transcript_meta_cmd` for star / template / language / llm_tags).

## What's in here

### `TranscriptDto` (`src-tauri/src/commands/transcripts.rs:35`)

camelCase frontend shape. The Task 2.5 fields (`starred`, `manualTags`, `template`, `language`, `segmentsJson`) were added when localStorage was retired. Phase 9 added `llmTags`.

### `CreateTranscriptRequest` (`:79`)

Wide shape covering everything an insert needs: id, text, source, profile_id, title, audio_path, duration, engine, model_id, inference_ms, sample_rate, audio_channels, format_mode, plus the post-processing flags (remove_fillers, british_english, anti_hallucination).

### `UpdateTranscriptMetaRequest` (`:215`)

Patch shape for Task 2.5 / Phase 9 metadata: each field is `Option`. `None` preserves via COALESCE; `Some` overwrites. `Some("")` explicitly clears (relevant for `manual_tags` and `llm_tags`).

### Commands

- `add_transcript` (`:103`) builds an `InsertTranscriptParams` from the wide request and calls `lumotia_storage::insert_transcript`. The FTS5 index is updated automatically by an SQLite trigger inside the storage crate.
- `list_transcripts` (`:135`) — paginated with sane defaults.
- `count_transcripts_command` (`:150`).
- `get_transcript` (`:157`).
- `update_transcript` (`:172`) — fixes the long-standing "rename in History never persists" bug per architecture-review.md §13.
- `delete_transcript` (`:184`).
- `search_transcripts` (`:196`) — empty / whitespace queries return empty results without hitting the DB. FTS5 query syntax (bare words AND together, quoted phrases, OR / NOT / prefix `*`) flows through verbatim.
- `update_transcript_meta_cmd` (`:235`) — patch the meta columns and return the updated row.

## Data flow

```
dictation result panel -> add_transcript(req) -> insert_transcript -> FTS5 trigger updates
History page mount -> list_transcripts(50, 0)
                  -> count_transcripts_command  (for "showing 50 of 1273")
History page rename -> update_transcript(id, text=None, title=Some(new))
History page delete -> delete_transcript(id)
History page search box -> search_transcripts(q)
Viewer window star toggle -> update_transcript_meta_cmd(id, { starred: Some(true) })
Viewer window LLM tag pass -> update_transcript_meta_cmd(id, { llm_tags: Some(joined) })
```

## Watch-outs

- **No `ensure_main_window` guard.** Both the main window AND the `transcript-viewer` secondary window need to call these commands, and the secondary-windows capability does include `core:event:default`. The DB layer is the only enforcement. If you ever want to hide certain transcripts (private profile?), add a profile-id check at the command layer.
- **`segmentsJson` is a JSON string, not a parsed array.** The shape is whatever `commands::transcription` and `commands::live` chose to write at insert time. The frontend re-parses. If you ever change the segment shape, write a migration that touches the existing rows.
- **`update_transcript` returns the affected row count (`u64`), not the updated row.** Callers that need the new shape have to follow up with `get_transcript`. `update_transcript_meta_cmd` returns the row directly. Consider unifying.
- **FTS5 search caps at 50 results.** History page would need pagination over search if a transcripts library grows beyond a few hundred rows.
- **`profile_id` defaults to `DEFAULT_PROFILE_ID` at insert time** if the request omits it. The frontend should be passing the active profile; if it ever silently omits this, all transcripts pile into the default profile.

## See also

- [Transcription](transcription.md) — the upstream that produces the segments + raw_text payload that lands in `add_transcript`.
- [Live transcription](live.md) — same upstream.
- [LLM](llm.md) — `extract_content_tags_cmd` produces the value that goes into `llm_tags`.
- [Profiles](profiles.md) — `profile_id` scoping.
- [Diagnostics](diagnostics.md) — `count_transcripts_command` is referenced from the Settings → About counts row.
