Reference

What every setting does

Every field in every panel, grouped the way the app groups them, with the parts the label doesn't tell you called out. Three are worth knowing first: the Settings tab edits whatever is selected, Audio8 ignores two of its own fields, and JIT streaming only exists for a project with no clips yet.

Options menuEngines, device, theme

Options > Settings… (Ctrl+,) opens the Settings window: everything about the program and the project, as opposed to a voice. The Settings tab keeps only what a voice sounds like.

Each character picks its engine, in the Settings tab's Engine row or in Edit > Characters, so one project can mix Kokoro and Audio8 voices; every engine a character uses stays loaded. The selected clip's character (or the first character, with nothing selected) decides what the Settings tab's fields look like and which editor the Voices tab opens on (Mixing for Kokoro, References for Audio8); the Voices tab's own Engine box opens another engine's editor without changing a character. Everything below is written per-engine where the two differ.

Language, the default voice, an engine's own Model fields and its Parallel threads are kept per engine, so a Kokoro and an Audio8 character each generate with their own. An engine this install doesn't have shows as "(not installed)": its characters keep it, their clips play and don't generate. Without the kokoro package the app runs Audio8 and Dummy.

Options > Device picks CPU / CUDA / Auto for the Kokoro pipeline (the CUDA entry is greyed out when torch reports no device) and re-initializes the engine. Options > Theme switches between the dark (default) and light palettes. The checkable entries under them are whether copying text carries its character and FX along, whether a paste splits off its own run, the Transcript details submenu, and JIT streaming for projects with no clips. The welcome dialog's "Show at startup" box is the one launch setting that isn't here; it lives on the dialog itself (File > Welcome…).

Transcript tabThe transcript

The transcript is a highlighting editor over the project's text, not a plain input field. Two combos sit above it: Character and FX, both reflecting the clip under the caret. Changing Character reassigns the selection (or the caret's whole clip, or its line for untagged text); changing FX sets a named FX override on the caret's clip, undoable like everything else. The left gutter names the speaker once per character/FX change (Narrator on one line, FX: Echo under it) and shows a small play button beside each stale clip that generates just that clip. Stale text is dash-underlined; a stale clip with a target duration whose text reads longer than the target gets a wavy amber or red underline instead (see Target (s) below). Thin rules mark clip boundaries and where Auto-split would cut. Options > Transcript details > Show details (off by default) adds more: every other segment of a clip in a lighter tint, a grey bar where a segment ends at a pause and an amber one where it had to end between two words, a dotted line over text the Lexicon rewrites, the gap before each clip on its rule, a status dot and length per clip in the gutter, and a line under the editor describing the clip under the caret. Hover a segment or a rewrite for details. Each of the four overlays (Segment boundaries, Clip info, Lexicon rewrites, Gaps) has its own toggle in the submenu. A music bed's line holds its file name and can't be edited; delete the whole line to remove the bed.

Every run of text is colored by its assigned character and FX, so the boundaries between speakers and effects are visible at a glance, without reading the inline [Speaker:FX]: syntax.

Selecting a range and opening the Characters menu reassigns that range's character/FX directly. Placing the caret inside an existing run instead shows that run's voice and FX in the Settings tab. Copying a range carries its character/FX metadata with it; pasting into a run belonging to a different character splits the paste into its own run rather than silently overwriting the destination's assignment, unless "character/FX paste splits" is turned off, in which case a paste inherits whatever it lands on.

Settings tabOne panel, three scopes

The top of the tab is built from the engine's own list of fields, and it edits whatever is selected:

Settings tab scopes
SelectionValues come fromEdits write to
Nothing selectedThe app's whole-document defaults, the shown engine's own for the per-engine fieldsApp settings (config_qt.json; per-engine fields under engines)
A clipIts character's settings, merged with its own overridesclip.overrides, never the app defaults
A characterThat character's settingsThe character directly, so every clip without its own override using it updates live

Voice, Speed and the Audio control fields can vary per clip or character. Language and an engine's Model fields (Audio8's sampling knobs) are shown disabled, not hidden, while a clip or character is selected, since they only apply to the whole document. Segmentation, output format, threads and the caches aren't here at all: they're program settings, in the Settings window.

Above the fields, the Engine row: with a character selected it sets that character's engine (refused while a job runs; the voice stays if the new engine has one by that name, else it becomes the new engine's default); with a clip selected it does the same for the clip's character, so every clip of that character follows; with nothing selected it is "Engine for new characters", the engine Add in Edit > Characters and subtitle import give a new character, and the Language and Voice under it switch to that engine's defaults, the voice a new character starts with. Picking an engine and then a voice is one stop.

The fields below are what the two engines declare. Rows marked Audio8 only don't appear for a Kokoro character at all. Language, Voice (with nothing selected) and the Audio8-only rows are remembered per engine.

Voice fields
SettingWhat it does
LanguageFor Kokoro, picks which phonemization pipeline runs; each language uses its own KPipeline and voice list. For Audio8 it's one of eleven labels from the model card. See the callout below: it currently isn't sent to the model at all.
VoiceKokoro: a named base voice (af_heart, bm_daniel, ...) or a saved Mix from the Voices tab. Audio8: a saved Reference (a WAV and its transcript) from the Voices tab.
SpeedKokoro: 0.5x-2.0x, passed straight to the pipeline as a native generation parameter. Audio8: shown in the same range, but see the callout below, it's currently not forwarded to the model either.
Max new tokens Audio8 onlyCaps how many tokens the model can generate per segment. Default 1024, hard-capped at 2048 to match the model's real max_seq_len; anything higher gets silently clamped by the model anyway.
Temperature Audio8 onlySampling temperature, default 0.8. Higher values add more variation between takes of the same text.
Top P / Top K Audio8 onlyNucleus and top-k sampling cutoffs, default 0.95 and 50. Standard token-sampling controls for the model's decoder.

Language and Speed do nothing on Audio8, currently. The model doesn't accept a language or speed at all, so the app never sends them. Audio8 takes the language from the reference clip and the text, and always speaks at its own pace. The two fields still show because the field list can't yet mark one as display-only. To change an Audio8 line's length, use Fit to slot, which time-stretches it on playback.

Settings tabClip fields

Under Audio control while a clip is selected. Every edit here is one undo step. The project's own fields (gaps, ripple, track layout, timecode, ...) are in the Settings window.

Clip fields
FieldWhat it does
Gap beforeThis clip's own gap, over the project's. Blank uses the project's. A [pause:x] marker sets it when Auto-split creates the clip.
TakeSwitch between the clip's takes, like the timeline's Take menu.
Status / NoteReview state and a note, for the timeline filter and the cue sheet.
Source textThe original line a dub is written against. Press Edit to change it and Save to store it. It shows as the transcript gutter's tooltip, and a rough syllable count of both lines sits underneath (vowel groups per word: a length check, not a real syllable count).
Original (s)The part of the source track this clip dubs, as start - end in seconds. Subtitle import fills it from the cue's times; blank for none. The transport's Original and Both play that slice where the clip starts, even after you drag the clip.
Target (s)How long the clip should last, from its time on the timeline; subtitle import sets it to the cue's length. Blank for none. The timeline draws it as a slot, and Fit to slot aims at it.

Options > Settings…Settings window

Program and project settings, laid out like OBS's: pick a page on the left, edit it on the right. Nothing changes until you press Apply or OK; Cancel drops the edits, and Apply stays greyed out until something differs. General, Generation and Performance are saved with the app (config_qt.json), the rest with the project. Each project value you change is its own undo step.

General
SettingWhat it does
Theme / DeviceThe same choices as Options > Theme and Options > Device; either place updates the other.
Generation
SettingWhat it does
Target words per segment5-200, default 40. Text is generated in pieces of about this many words, one file and one subtitle cue each. A piece ends at the strongest enabled boundary between half and one and a half times the target; if there's none, it may run to twice the target to reach one. Only past that is a sentence cut, and never inside a word. Changing it marks the clips whose pieces move as stale.
Split at paragraphs / sentences / pausesWhich boundaries a piece may end at, strongest first: a blank line; a sentence end (. ! ? ..., not after Mr., Dr. or an initial); a pause (comma, semicolon, colon, dash, or a single line break). All on by default. Turning one off demotes its boundaries to the next level on, so with sentences off a full stop still counts as a pause.
Output formatwav, flac, mp3 or ogg, for whole-document generation in a project with no clips. Clips are always written in the project's bundle format (wav or flac, set in the Export dialog), and the exported file's format is chosen in Export.
Performance
SettingWhat it does
Parallel threads per engineKokoro: 1-32. Each thread runs its own pipeline, so more threads generate more pieces at once. Audio8: 1-4, but one shared model generates one piece at a time, so more threads don't speed up the model itself.
Enable segment cacheFor whole-document and JIT generation: keeps each generated piece under cache/, keyed by a hash of what produced it, so a re-run with the same text and settings skips it. Clips don't need it: each clip's audio is written once into the project, under a name made from the same hash.
Cache reference encoding Audio8 onlyA second, separate cache that stores the model's encoded reference audio, keyed by the reference file's contents. Repeated segments against the same Reference skip re-running the audio encoder, independent of the segment cache above.
Project
SettingWhat it does
Subproject titleShown while a subproject is focused. Its name: its line in the parent, its block and the breadcrumb show it. Stored in its own project.json.
Gap / Paragraph gapSeconds of silence between clips placed one after another (default 0.35), and between clips with a blank line between them (default 0.9). 0 gives the old back-to-back placement. Clips you've dragged to a fixed time ignore both.
Auto-crossfade overlapping clipsOff by default. On, a clip that starts or ends inside another gets at least a 10 ms fade at that edge. The clip's own fades aren't changed.
Ripple on regenerateOn by default. When a regenerated clip comes back longer or shorter, the clips you dragged to a fixed time after it move by the difference. A clip marked Lock in time (its right-click menu) stays put.
Align locked clips to their first wordA clip locked in time and placed at a fixed time starts early by the silence before its first word, so the word, not the breath before it, lands on the clip's time (a subtitle cue's in-time). The first word comes from the clip's word timings, else from the measured leading silence. Skipped for a clip with Trim Silence on. Until you change it, it's on in a project with any locked clip and off otherwise.
Timeline
SettingWhat it does
Track layoutOne per character (default): a character gets a track the first time it's used. Unified, N lanes (3 by default): clips go on N shared lanes in text order, moving to the next lane whenever the speaker changes. Mute, solo, fader and pan then act per lane.
Ducking-40 to 0 dB, default -12. How far a track with its D header button on goes down while clips on tracks without D play. Playback and export duck the same way.
Timecode / Frame rate / Start / Drop-frameShows the ruler and the transport clock as HH:MM:SS:FF. Start is the timecode of the project's first frame (broadcast material often starts at 01:00:00:00). Drop-frame applies at 29.97 and 59.94. Times inside the project stay in seconds.
Source track
SettingWhat it does
Track / Offset (s) / RemoveThe original dialogue File > Import Source Track… copied into the project, marked "(missing)" when its file isn't there. Source offset is where the reference times start in the file: a track with a two-second leader has 2. Remove clears it on Apply (the copy stays, so Undo brings it back). The transport's Original and Both play it.

Settings tabAudio control

Hand-coded, not schema-driven, so every engine gets the same fields here, still subject to the same three-scope rules above. These are the post-processing steps from the signal chain on the home page.

Audio control
SettingWhat it does
Volume0.1x-2.0x. A plain multiply on the waveform, applied second in the chain, after Trim and before Pitch.
Pitch (st)-12 to +12 semitones, shifted by resampling to a new length. This changes duration along with pitch, the classic "chipmunk" effect: raise the pitch and playback gets faster, lower it and playback gets slower. For pitch without a duration change, use the Audio FX tab's separate Pitch Shift effect instead.
FX Preset / ApplyLoads a saved FX into the Audio FX tab's sliders. The Apply checkbox is the master switch for the whole FX chain below; unchecked, none of the Audio FX tab's effects run even if individually enabled.
NormalizeScales the segment so its loudest peak sits at 98% of full scale. A simple peak normalize, not a loudness (LUFS) normalize. Runs last in the chain, after FX.
Trim silenceStrips leading and trailing audio below a fixed amplitude threshold. Runs first in the chain, before Volume.

TimelineTimeline

One track per character in use (or a few shared lanes, see Track layout) on a real seconds axis. Clips sit in text order across all tracks, 0.35 s apart (0.9 s across a blank line; both are Gap and Paragraph gap in Options > Settings… > Project, and a clip's Gap before overrides them): at their real duration once generated (with a waveform), at an estimated one before (dashed outline, no waveform; the estimate learns from generation_stats.json). A ruler runs across the top, a fixed header column names the tracks, and Ctrl+wheel zooms between 20 and 400 pixels per second.

Timeline
ActionWhat it does
Right-click a clip > GenerateGenerates just that clip's text and settings through the normal cache-aware generation path, populating its segments with real audio.
Right-click a clip > PlayPlays that clip's cached audio.
Per-clip FX buttonOpens an FX override for that one clip, applied on top of the FX chain and winning over its character's own FX. Button opacity shows state at a glance: 50% means no FX override, 90% means one's active.
Drag a clip left or rightPins it to that start time (snapping to other clips' edges and the playhead). Drop it at or before the start of the clip that precedes it in the text and its text moves there too, so the timeline and the transcript stay in the same order. Right-click > Unpin from timeline puts it back in the flow.
Drag a clip onto another trackReassigns the clip to that track's character (with a confirmation prompt when the characters actually differ) or just moves it to that lane.
Shift+drag inside a clipCarves out the selected sub-range and opens an editable transcript for it. Confirming replaces just that sub-range with fresh TTS, under any character, not necessarily the clip's own.
Click the rulerSeeks the transport to that time.
Right-click the rulerAdd marker here. On a marker's flag: Rename (with a note, for a listen-through flag), Delete, and Loop to next marker. Drag a flag to move it.
Shift+drag on the rulerLoops playback between the two points. Right-click the ruler > Clear loop to stop.
Drag a clip's top cornerThe small squares on a generated clip's top-left and top-right corners set its fade-in and fade-out. Settings with nothing selected > Auto-crossfade adds a 10 ms fade wherever clips overlap.
Overlap warningTwo clips that overlap on the same track get a red border.
A clip with a targetIts slot (Target (s) in the Settings tab) is drawn as a bracket from the clip's start, which may reach past the block, and its label gives the clip's length as a percentage of the target. Over 103% the clip is tinted amber, over 115% red.
Right-click a clip > Fit to slotShown for a clip with a target. Changes the clip until it's within 3% of the target, as one undo step. Kokoro regenerates it at a new speed, from 0.7x to 1.6x, up to three times. Audio8 has no speed control, so its playback is time-stretched instead, between 0.87x and 1.15x, without changing the pitch. A line still too long at 1.6x or 1.15x is set to Needs rewrite. Clips placed after it ripple as they do after a regenerate.
Fit all over slotThe button above the timeline, shown once any clip has a target. Fits every clip that runs more than 3% past its target.
A music bed's blockA file added with File > Import Audio…, on the Music track. Drag its left or right edge to trim the file; the audio stays where it was on the timeline. Right-click: Play, Loop (repeat the trimmed part; the right edge then sets how long it runs), Reset trim, Unpin from timeline, Lock in time, Remove. A bed has no Generate, Take or Align words.
A subproject's blockA folder glyph and its title. It plays the subproject's exported mix, hatched while that's stale and crossed out when the subproject can't be opened. Click it: the transcript, Settings and Audio FX tabs show the subproject ("Subproject: …" at the top, Back returns). Double-click it (or its line in the transcript) to enter it: the timeline shows it and a breadcrumb above goes back up. Right-click: Enter, Generate and render, Detach to file… / Embed, Relink…, Remove.
Right-click a clip > TakeEvery take the clip has, the active one ticked, with its length. Regenerating keeps the old take. A take made from text you've since changed says "old text"; picking it marks the clip stale. Delete take drops one.
Right-click a clip > StatusTo do, Generated, Approved or Needs rewrite. Generating sets Generated. The Show box above the timeline dims clips that don't match (All, Not approved, Needs rewrite).
Right-click a clip > Align wordsRuns Whisper over the clip's audio to work out when each word is spoken. This runs by itself after generating with Audio8, or with Kokoro outside English.
Track header: M, S, A, D, fader, panMute, solo (any soloed track silences the others), show the volume automation lane, and duck; below them a fader (0-200%) and pan (snaps to centre). In the automation lane, double-click adds a point, drag moves it, right-click deletes it and Alt+drag moves a segment. D turns the track down while clips on tracks without it play, by Options > Settings… > Timeline > Ducking; it starts off, the Music track's included. Music beds never duck other tracks, and the source track neither ducks nor is ducked. Playback and export both follow these.
Generate (transport)Once the project has clips, this generates every stale clip in one pass instead of the whole transcript, with bounded concurrency and cancel-safe queuing; each clip goes to its character's engine. Then every stale subproject is generated and its mix exported into the project, one at a time. A project with no clips yet still falls back to the original whole-document pipeline. Its menu holds Auto-split then generate and the Split by paragraph toggle.

TransportPlayback

Play / pause / stop, the position readout, the Dub / Original / Both switch and a Loop toggle, then Preview / Generate / Cancel, then one progress bar that carries the status text.

Transport
ControlWhat it does
Play / Pause / StopPlays the whole timeline through one stereo sounddevice output stream that mixes every clip at its timeline position with its track's fader, pan and automation and its own fades (overlaps are a plain sum, clipped to full scale). Position comes from the audio callback's frame counter, so the playhead is sample accurate. Space toggles playback anywhere except inside the text editor; Ctrl+Space toggles everywhere.
PlayheadA line across every lane plus a marker on the ruler. The transcript highlights the clip being played and scrolls to it without moving your caret. A clip that finishes generating mid-playback becomes audible without stopping.
Dub / Original / BothWhat playback plays. Dub is the project as it exports. Original plays the source track's slice under each clip that has an Original (s) range, and nothing else. Both plays the two together, each 6 dB down. Switching mid-play keeps the position. Greyed out on Dub while the project has no source track. The choice isn't saved with the project, and export is always the dub.
LoopWraps to the start instead of stopping at the end of the timeline. A loop region set on the ruler wraps inside that region instead.
Position readoutmm:ss.t, or HH:MM:SS:FF timecode when Options > Settings… > Timeline > Show timecode is on, at the frame rate and start time set there. 29.97 and 59.94 can be drop-frame.
Word highlightWhile playing, the transcript underlines the word being spoken. Ctrl+click a word to jump there.
PreviewSpeaks the selected text (or the first 1000 characters of the document) with the project-scope settings, through the fire-and-forget preview player.

Video tabReference video

A tab beside Settings, for dubbing against picture. File > Load Video… fills it; Workspace > Simple hides it. The video plays muted: the transport is the only thing that makes sound, and the video never moves the transport.

Video
ControlWhat it does
PictureFollows the transport: play, pause, stop and seek. While playing, it's put back in step whenever it drifts more than 40 ms. Where video playback can't load on the machine (Qt's multimedia libraries missing), the tab says so instead, and the rest of the app works as usual.
OffsetThe video time at the timeline's 0, in seconds. Positive skips into the video, negative starts it later. Saved with the project.
Where the video livesThe project stores the video's path, relative to the .tbaw when both are on the same drive. When the file isn't there on open, the app asks you to find it. The Export dialog's "Bundle the reference video in the project file" puts a copy inside the .tbaw instead.

Edit > CharactersCharacters

A character is a name, a highlight color, an engine, a voice and an FX. Every clip belongs to one. A character still used by clips can't be removed.

Characters dialog
Field or buttonWhat it does
Name / ColorThe name [Name]: tags match, and the tint its text and clips get. The color picker's presets are the eight default character colors.
EngineKokoro or Audio8 (and any plugin engine). One project can mix both. The Settings and Voices tabs follow the selected clip's character. A new character gets the Settings tab's "Engine for new characters" (its Engine row with nothing selected). An engine that isn't installed shows as "(not installed)".
Voice / FXA Kokoro voice or Mix, or an Audio8 Reference; and the FX every clip of this character plays through unless it has its own.
Variants Audio8Named alternative References, such as "angry" or "whisper". The transcript's Variant box picks one per clip.
ScopeGlobal lives in the character library (characters/), and every project that links it follows its voice, FX, color, engine and variants. Project belongs to the top-level project and is shared by its subprojects. Local belongs to this file only. A project always keeps its own copy, so it opens on a machine whose library lacks the character; the dialog then says "Library (not found here)".
Promote to Library / Promote to ProjectTurns a local character into a library entry, or, inside a subproject, shares it with the whole project.
Rename in libraryEach project keeps its own name for a library character. This copies this project's name to the library entry.
Add > From library...Brings library characters into the project. File > New starts with every library character.

Undo and redo (Edit menu or the usual shortcuts) cover typing, character and FX assignments, clip moves, FX overrides, track controls, fades, takes, statuses, markers the Settings tab's clip fields and the Settings window's project values. Typing undoes like a text editor; everything else has its own history, and Undo reverts whichever happened last.

File menuProjects

A project is a .tbaw bundle (text based audio workflow): one zip with the text and clips, every generated segment, and the Mixes, References and saved FX it uses, so it opens on another machine with the same engines installed. The layout is on the format page. Older .json projects open and are converted next to the original. Launch reopens the last project you had open, then shows the welcome dialog over it.

File menu
ActionWhat it does
Welcome…The dialog launch shows: recent projects with the open one first and Resume as the default button, New project, New from text file (an EPUB, or a PDF with a table of contents, becomes one subproject per chapter while "One subproject per chapter" is ticked), Open other, right-click a row to drop it, Clear list, and a details pane (path, modified time, character, clip and subproject counts, audio length, engines) read from the .tbaw manifests without extracting them. "Show at startup" is show_welcome in config_qt.json; untick it for a silent resume.
NewAn empty project with every character in the character library, linked to it. With an empty library, one "Default" character.
New SubprojectMoves the transcript's selection (widened to whole clips) and its clips into a new subproject embedded in this project, leaving one read-only line with its title in their place, on a Subprojects track. With nothing selected, adds an empty one. One undo step.
Add Subproject…Links an existing .tbaw as a subproject. The path is stored relative to this project's file. A linked file that has moved or turns out to be another project asks you to find it (Relink).
Open / RecentOpens a project file; Recent lists the last ten.
Save / Save AsAutosave writes the app's working copy of the project (under cache/projects/), never the .tbaw; Save writes the file in the background and Save As branches to a new file. The window title shows * while the working copy is ahead of the file. Closing with unsaved changes asks Save / Discard / Cancel; after a crash, opening the project offers to recover the unsaved session.
Import TextExtracts a .txt, .pdf, or .epub and asks whether to add it at the caret or start a new project from it. The insert is one undo step.
Import Subtitles…Reads an SRT, WebVTT or ASS/SSA file (UTF-8, UTF-16 with a byte order mark, or Latin-1). Each cue becomes a paragraph at the end of the transcript and a clip locked in time at the cue's start, with the cue's text as its Source text, its length as its Target (s) and its times as its Original (s). When the file names speakers (ASS Name, VTT <v Name>), a dialog asks which character voices each: the narrator, a new character named after the speaker, or an existing one; a speaker whose name matches a character starts on that character. Cancel imports nothing. One undo step, including the characters it made.
Import Audio…Asks first whether the file is a music bed or a recording to edit as text. For a music bed (WAV, FLAC, OGG, MP3 or AIFF) the file is copied into the project and placed on a Music track, locked in time at 0:00, or at the playhead if you pick that when it isn't at the start. Its file name becomes a read-only line at the end of the transcript. One undo step. A project with imported audio needs this version or newer to open.
Import Audio… > Recording to edit as textThe transcript comes from "Transcribe with Whisper" (runs in the background) or "Caption file (SRT, VTT, ASS)", which uses each cue's text with word times spread over the cue by character count; "Refine word timing with Whisper" (off by default) re-times those words and never changes the text. Whisper's words are grouped into clips at sentence ends, pauses over 0.7 s, or 15 s. A review step lists each clip with a play button and editable text (a corrected word keeps its times) and a speaker picker listing voice-cloning characters and "Unknown speaker" (a new character with no voice); caption-file speaker names use the subtitle mapping dialog instead. One undo step. In the transcript, deleting recorded words closes up the audio, cut/copy/paste and drag carry the audio, typed text is grey with a hollow circle in the gutter until it has a character, recorded words are faintly underlined and recording clips get a play button.
Import Source Track…Copies the original dialogue into the project and names it in Settings > Project > Source track. A second import replaces the first and keeps its offset. One undo step.
Load Video…Picks an MP4, MOV, MKV, WebM, AVI or M4V file as the project's reference video and shows the Video tab. See Video.
ExportThe dialog described next.

File > ExportExport

Generate only fills the per-clip cache. Export is what produces a deliverable: every clip mixed down at its timeline position into one file, using the same summing rule the transport plays. It refuses with a count when clips are stale and offers to generate first.

Export dialog
SettingWhat it does
Output folder / Base filenameWhere the exported file is written and what it's called. Remembered per project.
Project: bundle generated audio / Bundle audio formatWhether Save puts generated segments into the .tbaw (off gives a small file whose clips regenerate on open) and whether new segments are written as wav or flac. Remembered per project.
Bundle the reference video in the project fileOff by default. On, Save stores the reference video under video/ in the .tbaw, uncompressed; off keeps only its path. Opening the project where the video already is at that path doesn't extract the bundled copy. Save only reads a video you picked with Load Video on this machine; a project someone sent you keeps the copy it came with.
Bundle imported audio in the project fileOn by default. Music beds, the source track and imported recordings go under audio/imported/ in the .tbaw. Off leaves them out; a copy opened elsewhere plays without them.
Formatwav, mp3, flac or ogg.
ChannelsStereo, or mono (the average of the two channels). Muted and soloed-out tracks are left out either way.
RangeThe whole project, the stretch between any two neighbouring markers, or the loop region.
Also write .srtSubtitles timed from each clip's timeline start and duration, one row per generated clip. "One subtitle per word" writes a row per spoken word instead, from the stored word timings.
Also write a cue sheet (.csv)One row per clip: start, end (timecode when it's on), character, source text, text, status and note.
Keep per-clip filesWrites each clip next to the exported file as <base>_001_<Character>.<ext>, numbered in timeline order.

Workspace menuWorkspaces & theme

Every panel is a dock. Drag one by its title to move it, drop it on another to stack them as tabs, or pull it out of the window to float it. Nothing about the layout is fixed.

Workspace > Advanced opens with the transcript and the Settings, Audio FX, Lexicon, Voices and Video tabs above the timeline and transport. Simple hides the timeline and the Video tab so the transcript gets the full height; the project and Generate behave the same. Each workspace remembers what you do to it and brings it back next time. Reset layout puts the active one back to its default. A project can also name the workspace it opens in.

Options > Theme switches between dark (the default) and light. The gutter, timeline and ruler use the same palette as the rest of the window.

Audio FX tabFX

Five groups, each section gated behind its own enable checkbox except EQ, which is always live (a slider left at 0 dB is simply a no-op), and Convolution Reverb, which is off while its impulse response is None. All of it runs through one Pedalboard chain together as step 5 of the signal chain. The whole chain (and volume, pitch, normalize, trim) is applied on playback and export over the clip's raw generated audio: edit anything here and the timeline plays the change, with no regeneration and no clip marked stale. The tab follows the selection: project defaults, a character's FX, or one clip's override, layered in that order.

Dynamics
SettingWhat it does
CompressorThreshold (dB) and Ratio. Standard dynamic-range compression.
LimiterThreshold (dB). A hard ceiling on peak level, separate from the Compressor.
GainA flat gain change in dB, applied within the FX chain, on top of the separate Volume control above.
EQ & filters
SettingWhat it does
Bass (low shelf)±20 dB shelf below 250 Hz. No separate enable toggle; 0 dB does nothing.
Treble (high shelf)±20 dB shelf above 4000 Hz. Same, no toggle needed.
High-pass filterCutoff frequency, 20-1000 Hz. Removes content below the cutoff.
Low-pass filterCutoff frequency, 1000-20000 Hz. Removes content above the cutoff.
Spatial & time
SettingWhat it does
ReverbRoom Size, Wet Level, Damping, Width. Standard algorithmic reverb.
DelayTime (seconds), Feedback, Mix. Echo/repeat effect.
Convolution ReverbImpulse response and Mix (0-1, default 0.5): the sound of a real space or device, recorded as a .wav. The list shows None, then every impulse response the project carries (fx/ir/ in the .tbaw) and every one in the library (presets/fx/ir/); the project's copy wins when both have a name. Add… copies a .wav into the library. Save bundles every impulse response the project uses. One that can't be found plays dry and logs a warning. Runs after Reverb, before the dynamics.
Guitar / modulation
SettingWhat it does
ChorusRate (Hz), Depth. Layers a detuned, delayed copy of the signal.
DistortionDrive (dB). Harmonic distortion.
PhaserRate (Hz). Sweeping comb-filter effect.
ClippingThreshold (dB). Hard-clips the waveform above the threshold.
Quality / pitch
SettingWhat it does
Pitch Shift (High Quality)±12 semitones. The formant-aware shift mentioned above: changes pitch without the duration side effect the plain Pitch control has.
BitcrushBit depth, 2-16. Reduces sample resolution for a lo-fi, digital-artifact sound.
GSM CompressorA single checkbox, no slider. Runs the audio through a simulated GSM phone-call codec.

Lexicon tabLexicon

Lexicon
SettingWhat it does
Original text / ReplacementA list of literal find-and-replace rules, applied case-insensitively to every segment's text before generation, on every path: clips, whole document, JIT and Preview. Adding or removing a rule marks the clips whose text it changes as stale, and no others. Useful for acronyms, names, or jargon a voice mispronounces.

Rules apply whichever character a line belongs to, whether it was assigned by hand or by a tag. A character can't have its own rules.

The Voices tab's Engine box, at the top of either editor, lists the engines that have one. It follows the selected character; pick another to edit that engine's voices without touching a character, and the next selection puts it back. A saved or deleted voice shows up in the Settings tab's and Edit > Characters' voice lists at once.

Voices tab · KokoroMixing Kokoro characters

Mixing
SettingWhat it does
Voice A / Voice BEach has its own language and voice picker; the two voices being combined.
OperationMix, Add, Subtract, Multiply, or Divide, applied directly to the two voices' underlying tensors.
Mix slider0-100%. For Mix, a straight blend of the two: 0% is all Voice A, 100% is all Voice B. For the other four operations it's an influence amount, not a ratio, and the app's own label warns that Divide is "unstable and VERY LOUD."
Preview language / PreviewSpeaks a short preview line in the chosen language using the in-progress mix, before you commit to saving it.
New voice name / Create & SaveSaves the result as a Mix, which then shows up in the Voice dropdown alongside the built-in voices.

Voices tab · Audio8References Audio8 characters

References
SettingWhat it does
Reference audioBrowse to a WAV file of the voice to clone.
TranscriptWhat's actually said in that WAV, word for word. The cloning model uses this alongside the audio itself.
Auto-transcribeRuns the reference clip through the chosen ASR engine to pre-fill the transcript, in the background, so the app stays responsive. Whisper (the default, local, MIT) asks before its first download, about 1.6 GB, and offers another engine instead; WHISPER_MODEL in .env picks a smaller model. Audio8-ASR-0.1B is non-commercial; Vosk is offline and needs a model folder. Always worth proofreading the result before saving.
Save as / Saved referencesSaves the WAV and transcript as a named pair, which then shows up in the Voice dropdown like any other voice.

Files on diskPreset files

Saved FX are presets/fx/<name>.json, written by "Save FX Preset..." in the Audio FX tab. A project bundles the ones it uses under fx/, and its own copy wins over yours.

Character presets, presets/<name>.json, are from before characters existed. Nothing in the app writes them now. The first launch with the character library copies each one into characters/ and links matching characters in the open project. After that, only the whole-document path reads them, for [Name]: tags in a project with no clips.

Options menuJIT streaming

"JIT streaming (no-clips fallback only)" plays a project that has no clips yet while it's still generating: one thread fills a queue, another plays from it. That only works when the engine makes audio faster than it plays, with enough margin that playback never catches up.

Kokoro can. Audio8, one large model generating one piece at a time, can't, so with an Audio8 character selected the entry is greyed out and generation runs normally. Once a project has clips, Generate works clip by clip and the transport plays them, and this setting doesn't apply.

Options menuForce refresh

The Transcript and Timeline panels remember what they worked out about each clip (whether it's stale, where it sits, how its audio is post-processed, its waveform) and only work it out again when something that clip depends on changes. Force refresh throws all of that away and rebuilds it from the project and the files on disk.

You shouldn't need it. It's there for a panel that looks out of date, and for files changed in another program while KokoroGUI kept focus: a segment file deleted by hand is otherwise noticed when the window becomes active again, or after the next Generate, Open, Save or import.