Settings, profiles, and analysis knobs¶

How to change TranscriptX behaviour from the GUI, env, and config files — without mixing up the several things named “profile”.

Where to start¶

Goal	Where
Everyday analysis depth (which modules run)	Run Analysis preset: Quick / Balanced / Thorough / Custom — edit policies under Settings → Analysis
Charts page Overview strip (enable, which charts, order)	Settings → Configuration → Charts overview (`dashboard.overview_enabled`, `dashboard.overview_charts`) — off by default; not Dashboard Builder
Overview / Insights page panels (layout profiles)	Settings → Dashboard Builder — see dashboard_builder.md
Common model and similarity knobs	Settings → Configuration → Common Settings
Full registry of knobs	Settings → Configuration → enable Show advanced/raw settings editor
Named module/workflow presets (disk JSON)	Profiles page (sidebar) — activate from Configuration for Project / Run
Paths, watcher, speakers, LLM models, questions, STT keyword lists	Other Settings tabs (Storage, Watcher, Speakers, Interface, Models, Questions, Keywords, Corrections)
Auto-name / auto-link after ingest	Settings → Speakers — auto-identify.md (`config_dir/identify.json`)
Duplicate recordings / transcripts	Settings → Storage → Duplicate library files (preview, then typed `DELETE DUPLICATES`)
Show/hide instructional ⓘ tips (widget help + Speakers methodology notes)	Settings → Interface → Help / info tips (`show_info_tooltips` in `interface_menus.json`; run-id ⓘ stays on)
Action-menu icon vs text	Settings → Interface → Action appearance (`action_display`: `icon` / `text` / `both`; per-section may `inherit`)
Install capability (`core` vs `full`)	Env / install marker — see installation details; not the Profiles page

Speaker identity/voice stores are a separate subsystem (Settings → Speakers), including ingest auto-name / auto-link defaults (config_dir/identify.json, all off until you enable them), name-token policy, and optional Twenty CRM people lookup (env TWENTY_API_KEY / TWENTY_BASE_URL, read-only). Operator guide: auto-identify.md. Contracts: speaker_profiles_v1, speaker_profiles_voice_v1, STORAGE.md.

Analysis presets¶

When you run analysis, choose a Preset that determines which modules run:

Quick — no LLM modules and no heavy modules (fast local path). Modules that hard-depend on excluded heavy/LLM modules are omitted so the DAG cannot pull them back in.
Balanced — recommended default: non-heavy modules plus a limited heavy allowlist (semantic_similarity) and global transcript LLM summary only (llm_summary). Experimental emotion classifiers stay off this preset — known limitations.
Thorough — all suitable modules for the target (including LLM and heavy).
Custom — pick exactly which modules to run for this launch.

Edit Quick / Balanced / Thorough policies (and optional full module overrides) under Settings → Analysis. Mode quick vs full still controls depth knobs (semantic/NER limits) for the chosen preset.

Single-speaker / unnamed-speaker behavior¶

Content-first runs (T0): Some modules (topics, word clouds, global sentiment, transcript quality, exports, and similar) can run when no human names exist yet — for example after import when labels are still SPEAKER_00 or when captions had no speakers. Interaction and multi-speaker modules still skip until you name speakers, enable the ungate below, or re-transcribe with diarization.

By default, modules require human-named speakers. Diarized placeholders (SPEAKER_00, …) do not count until you name speakers in Speaker Identification. Modules that need multiple speakers (conversation loops, contagion, interactions, semantic similarity, Q&A, echoes, and others) skip when the named-speaker count is below their minimum. For group runs, the module list is filtered by the minimum named speaker count across members.

Tier	When to use	Knobs
T0	No speaker labels or only `SPEAKER_00` with no names	Default content modules (`min_named_speakers: 0`); Overview and Charts show “No named speakers” when applicable
T1	Single-speaker monologue with one diarized label (`SPEAKER_00`)	Treat as single speaker (per run or `analysis.treat_as_single_speaker` / `TRANSCRIPTX_ANALYSIS_TREAT_AS_SINGLE_SPEAKER`) — ungates modules that need ≥1 speaker only when turn-taking count is exactly 1; does not satisfy multi-speaker modules
T2	Diarized multi-speaker, names optional	Allow analysis without named speakers (global or per run) — uses turn-taking counts for gates
T3	Named speakers (default policy)	Name speakers in Speaker Identification; Balanced/Thorough presets expect human names

To run modules on diarized labels without naming speakers (T2):

Global: Settings → analysis.allow_unnamed_speakers (or env TRANSCRIPTX_ANALYSIS_ALLOW_UNNAMED_SPEAKERS)
Per run: Run Analysis checkbox Allow analysis without named speakers

Either knob ungates the pipeline (global or per-run). When ungated, speaker-count gates use turn-taking labels and per-speaker artifacts include unidentified speakers.

For a single diarized speaker only (T1), use Treat as single speaker on Run Analysis (or CLI --treat-as-single-speaker). This is narrower than T2: it does not ungate when two or more turn-taking speakers are present.

Configuration scopes¶

Effective config for a run merges layers (highest wins first):

Environment (TRANSCRIPTX_*)
Run override (or Draft override when no run is selected)
Project config.json
Built-in defaults (plus active module/workflow profiles loaded into the runtime facade)

Authoritative precedence and path roots: STORAGE.md.

In Settings → Configuration:

Scope	Editable?	Persists to
Default	Read-only	—
Project	Yes	`{config_dir}/config.json`
Draft override	Yes (no Active Profiles)	`{config_dir}/drafts/...`
Run override	Yes (needs a run selected)	under the run directory

Draft overrides are reported with run-layer provenance (source: run) by design — see STORAGE.

Common vs advanced knobs¶

Charts overview (Configuration, edit mode): master enable (dashboard.overview_enabled, off by default) plus checkbox + ordered list for dashboard.overview_charts. When enabled, empty list → registry defaults for the run kind (transcript vs group). See group_charts_default_overview.md.
Common Settings are a curated allowlist (COMMON_SETTINGS_SCHEMA): models, semantic similarity, a few workflow/output/display keys.
- Speakers: analysis.allow_unnamed_speakers — when on, analysis runs on diarized labels (SPEAKER_00, …) without naming; default off. Per-run override: Run Analysis checkbox.
Advanced/raw exposes every registered config leaf (except profile activation keys). Registry fields may mark advanced=True for documentation; the GUI does not yet use that flag to partition the form — the toggle is the partition.
Prefer Common or Analysis presets unless you know why a leaf matters.

Smart rename and rename forms¶

Settings → Configuration → Rename (also under Advanced as input.*):

Knob	Default	Meaning
`input.smart_rename_mode`	`suggest_import`	`auto_import` / `suggest_import` / `suggest_rename_only` / `off`
`input.smart_rename_pattern`	`{yymmdd}_{period}_{n}`	Deterministic template rendered from the recording datetime
`input.prefill_rename_with_date_prefix`	`true`	Legacy YYMMDD_ + stem prefill when smart mode is `off`
`input.rename_content_suggestions`	`off`	`off` / `auto` — when `auto`, rename/import forms prefill from the suggestion service on open and show Suggested names
`input.rename_default_case`	`lower`	Default case for rename token buttons and the new file name field: `title` / `upper` / `lower`
`input.rename_suggest_transcript`	`true`	Transcript date/title cues when suggestions run (`auto` or Suggest names on the form)
`input.rename_suggest_llm`	`false`	Optional local LLM pass when suggestions run in auto mode (Ollama; model from Settings → Models → `rename_suggestions`). Suggest names on the rename form also runs the LLM when Ollama is enabled and a `rename_suggestions` model is configured, even if this flag is off. The LLM returns three distinct title options per run.
`input.rename_suggest_web`	`false`	Optional web lookup for public-event-like files (short DuckDuckGo query only; not the transcript body). Tries `site:youtube.com` first, then a general event query. Eligible when the filename looks like a webinar/platform recording, dialogue matches public-event markers, or the stem is a multi-word descriptive title (four or more non-stopword tokens).
`input.rename_suggestions_effort`	`low`	Effort tier for the rename-suggestion LLM pass (`max_input_chars`, timeout, output tokens)

Supported pattern tokens: {yymmdd}, {yyyymmdd}, {yyyy}, {yy}, {mm}, {dd}, {hhmmss}, {hhmm}, {hh}, {period} (morning/afternoon/evening/night), {n} (collision sequence), {stem}, {title} (slug from transcript/LLM/web title cues).

Device stems understood include RYYYYMMDD-HHMMSS, YYYYMMDDHHMMSS, and YYMMDD-HHMMSS, plus messaging-app and field-recorder patterns parsed in code (smart_name.py).

Rename form prefill (smart + titles)¶

On Rename Transcript and import rename (when smart_rename_mode is not off):

Device-style filename — prefills the date root (YYMMDD_) from the recording filename or file mtime when needed. Optional clickable token: {period} (morning/afternoon/evening/night) to append to the new name.
Descriptive title (already a human-readable stem, not a device pattern) — prefills YYMMDD_ plus an underscore-separated version of the current title (spaces, hyphens, and CamelCase split into words). Word token buttons help edit the title portion; common stopwords are omitted from buttons only.

Legacy prefill_rename_with_date_prefix still applies when smart rename is off.

Content rename suggestions (assistive)¶

The rename form always shows Suggest names (transcript + LLM) (or transcript only when Ollama is off). That button runs the suggestion service on demand and fills Suggested names, even when input.rename_content_suggestions is off.

When input.rename_content_suggestions is auto, the same service also runs when you open the form: transcript date and title cues (default on), optional local LLM (rename_suggestions consumer; effort via input.rename_suggestions_effort), and optional web lookup for eligible filenames, dialogue, or long descriptive title stems (short DuckDuckGo queries, YouTube-biased first — never the transcript body). If the current stem already looks like a descriptive title, its underscore form is always included (and preferred) in Suggested names. The top-ranked full stem is prefilled and alternatives appear in Suggested names; nothing is written until you submit Rename. Event dates from transcript/web/LLM beat the file’s download/mtime date (shown as “file date, not the event date”). With no event date, a title-only stem may be offered without inventing a YYMMDD_ from file time. Results are cached under {data_dir}/.cache/rename/. auto_import smart rename on import stays filename-only.

“Profile” taxonomy (do not conflate)¶

Name	Meaning	Surface
Install profile	`core` \| `full` capability / dep story	`TRANSCRIPTX_CORE`, `{config_dir}/install_profile`, install_profiles_matrix.md
Analysis UI preset	Quick / Balanced / Thorough module sets	Run Analysis + Settings → Analysis
Module / workflow profile	Named JSON under `{config_dir}/profiles/<target>/`	Profiles page + Active Profiles in Configuration
In-config semantic profiles	Mapping `analysis.semantic_similarity_profiles` (`fast` / `balanced` / `deep`)	Advanced config / code — shares activation key naming with disk profiles; different store
UI layout profiles	Ordered blocks for Overview / Insights	Settings → Dashboard Builder (`profiles/ui_layouts/`) — not Charts overview
STT command profiles	Named JSON under `profiles/`	Transcribe Audio
Merge source profile	Match + day/gap rules for Tools → Merge suggestions / auto-merge	Merge tab expander; `{config_dir}/audio_merge_profiles.json`
Merge dismissed groups	Auto-merge Don’t suggest again keys (rule + stem)	Auto-merge tab; `{config_dir}/audio_merge_dismissed.json`
Speaker profile	Longitudinal identity (+ optional voice)	Settings → Speakers — see Speakers

Tracked files under repo data/profiles/*/default.json are fixtures / allowlisted samples. Runtime defaults are virtual (dataclass/Pydantic); ProfileManager does not treat disk default as loadable user presets. Runtime profiles live under {config_dir}/profiles/ (override with TRANSCRIPTX_PROFILES_DIR).

Env overrides¶

Copy .env.example to .env. Infra path keys (TRANSCRIPTX_*_DIR, host/port, downloads, …) are separate from config-bag overrides. Set TRANSCRIPTX_CONFIG_STRICT=1 to reject unknown TRANSCRIPTX_* keys.

Legacy TRANSCRIPTX_AUDIO_*_ENABLED variables are rejected — use the corresponding *_MODE keys.

Speakers¶

Settings → Speakers controls the Speakers directory filters and optional local voice matching. Canonical files live under speaker_profiles/ (STORAGE.md, speaker_profiles_v1).

Directory toggles (session): include ignored appearances in headline totals; show archived; show merged. Speakers “show archived” is for profiles. Transcript library archive is on Library (inspector Archive / Unarchive, plus Include archived transcripts on Library and Search) — not a Settings toggle. See STORAGE.md.

Local voice matching (optional extra speaker_match):

Read the privacy notice and enable matching. Consent is privacy.voice_settings.json. Defaults off. Opt-in enrols nothing.
Set Max confirmed links per voice enrol (default 40) if you need a larger bootstrap.
Enrol trusted voice for all profiles — reference samples from every active profile that already has confirmed links. Per-profile enrol also exists on the Speakers Voice & lifecycle tab.
Pre-load voice suggestions — analyse every non-ignored managed occurrence into .cache/voice for Speaker Identification. Speaker ID Analyse all speakers does the same for the open transcript only.

Order: name and link a seed cast → Enrol all → Pre-load → confirm suggestions in Speaker Identification. Empty corpus → analyse succeeds with no match. Scores never auto-name. Full walkthrough: Assist naming with voice.

Assistive LLM suggestions (name dropdowns, rename prefills) can be warmed library-wide from Settings or cron — see llm-suggestion-batch.md. Distinct from voice pre-load above.

Keyword lists (STT)¶

Settings → Keywords stores named term lists (acronyms, product names) under {PROFILES_DIR}/keyword_lists/. They are not project-config registry knobs and are not Corrections known_acronyms.

On Transcribe Audio, Keyword biasing is off by default. When enabled, the selected list plus extra terms are passed to Granite Speech at decode time (cap 2,000). Whisper providers ignore the lists in this version.