TalkEdit/polish_plan.md

TalkEdit — UI Polish Plan

1. Tooltips: show what it does + keyboard shortcut

Every toolbar button and action button should have a title that explains the action and shows the keyboard shortcut if one exists.

Toolbar buttons (App.tsx)

Current: title={label} → shows just the name. New format: title="Cut the selected or marked range [Ctrl+X]"

Button	Current tooltip	New tooltip
Cut	"Cut"	"Cut selected word range or mark in/out area [Ctrl+X]"
Mute	"Mute"	"Mute selected word range or mark in/out area [Ctrl+M]"
Gain Zone	"Gain Zone"	"Add gain zone from selection or mark in/out [Ctrl+G]"
Speed Zone	"Speed Zone"	"Add speed zone from selection or mark in/out [Ctrl+Shift+S]"
Zones	"Zones"	"Open zone editor panel [Ctrl+Shift+Z]"
Pause Trim	"Pause Trim"	"Detect and remove silent pauses [Ctrl+T]"
Markers	"Markers"	"Add and manage timeline markers [Ctrl+Shift+M]"
Music	"Music"	"Add background music track [Ctrl+Shift+B]"
Append	"Append"	"Append additional video clips [Ctrl+Shift+A]"
Reprocess	"Reprocess transcript with selected model"	"Re-transcribe entire video with selected model
AI	"AI"	"AI filler detection and clip suggestions [Ctrl+I]"
Export	"Export"	"Export video with current edits [Ctrl+E]"
Settings	"Settings"	"Configure AI providers, shortcuts, models [Ctrl+,]"

File menu dropdown items

Item	Current	New
New Project	none	"Start a new empty project"
Open File	none	"Open a video or audio file for transcription"
Load Project	none	"Open a saved .aive project file"
Save	none	"Save current project [Ctrl+S]"
Save As	none	"Save a copy of the current project"

Waveform timeline controls

Element	New tooltip
Show adjusted timeline checkbox	"Compress cut regions to see the output timeline without gaps"
Cut zones toggle	"Show/hide cut ranges on the timeline"
Mute zones toggle	"Show/hide mute ranges on the timeline"
Gain zones toggle	"Show/hide gain ranges on the timeline"
Speed zones toggle	"Show/hide speed ranges on the timeline"
Zoom instruction text	"Scroll to pan · Ctrl+Scroll to zoom [Ctrl+= to reset zoom]"
Thumbnail toggle	"Show waveform thumbnail previews from the video"

Transcript selection toolbar

Button	New tooltip
Cut	"Remove this word range from the output"
Mute	"Silence audio for this word range"
Gain	"Adjust volume for this word range — positive boosts, negative reduces"
Speed	"Change playback speed for this word range — lower is slower, higher is faster"
Re-transcribe	"Re-run Whisper transcription on just this segment to improve accuracy"

AIPanel buttons

Button	New tooltip
Detect Filler Words	"Scan the entire transcript for filler words (um, uh, like, you know…) and mark for removal"
Apply All	"Create cut ranges for all detected filler words at once"
Dismiss	"Clear detected filler word results without applying"
Find Best Clips	"Analyze transcript to find the most engaging 20-60 second segments for social media"
Preview clip	"Seek to this clip's position and play a preview"
Export clip	"Export just this segment as a standalone video file"

ExportDialog controls

Every control needs a tooltip — this is the most complex panel with zero tooltips.

Control	Tooltip
Fast export card	"Stream copy — no re-encoding, fast but no effects or cuts applied"
Re-encode card	"Full re-encode — applies cuts, gain, speed, zoom, captions, and effects"
Resolution select	"Output video resolution — higher = larger file"
Format select	"Output container format — MP4 is most compatible"
Enable zoom checkbox	"Crop and reposition the video frame — useful for removing black bars or reframing"
Zoom slider	"Magnification level — 1.0x is original, higher values zoom in"
Pan X slider	"Horizontal position of the crop window — negative moves left, positive moves right"
Pan Y slider	"Vertical position of the crop window — negative moves up, positive moves down"
Background removal checkbox	"Remove or replace the background behind the speaker"
Background blur slider	"Amount of Gaussian blur applied to the background"
Loudness normalization checkbox	"Normalize audio to a consistent loudness target — recommended for YouTube"
LUFS target select	"Loudness target: YouTube (-14), Spotify (-16), Broadcast (-23)"
Audio enhancement checkbox	"Apply noise reduction and speech enhancement (DeepFilterNet)"
Captions select	"Burn captions into video, export as separate file (SRT/VTT), or none"
Export Transcript section	"Export just the transcript text or subtitles without the video"

SettingsPanel controls

Control	Tooltip
Zone preview padding	"Extra context time shown before and after each zone when previewing"
Confidence threshold	"Words below this confidence get an orange underline — lower = show fewer warnings"
AI provider selector	"Choose which AI backend powers filler detection, chapters, and suggestions"
Ollama base URL	"URL of your Ollama instance — default is localhost:11434"
Ollama model	"Model name to use for AI features — requires Ollama running with this model pulled"
OpenAI API key	"Your OpenAI API key — stored encrypted on your machine"
Claude API key	"Your Anthropic Claude API key — stored encrypted on your machine"
Keyboard shortcut inputs	"Click then press the key combination you want to assign"

Zone detail tooltips

Element	Tooltip
Zone preview button	"Preview this zone with {N}s of context before and after"
Gain dB input	"Volume adjustment in decibels — +6 dB doubles volume, -6 dB halves it"
Speed multiplier	"Playback speed multiplier — 1.0x is normal, 2.0x is twice as fast"
Delete zone button	"Remove this zone permanently"

---

2. Help menu / feature documentation

2.1 Help button in toolbar

Add a ? help button to the right side of the toolbar (next to Settings):

[? Help]

Clicking it opens a Help panel (not a dialog — uses the existing sidebar panel system, or slides in as an overlay).

2.2 Help panel sections

Getting Started (for first-time users)

Welcome to TalkEdit

1. Open a video file → click "Open Video File" or press Ctrl+O
2. Wait for transcription — Whisper processes your audio and creates a word-level transcript
3. Edit by selecting words → choose Cut, Mute, Gain, or Speed from the toolbar
4. Use AI tools → detect filler words, find clips, auto-chapter
5. Export → apply all edits and save your final video

Pro tip: press ? anytime to see all keyboard shortcuts

Feature reference

Transcription

• Select a Whisper model from the toolbar dropdown (larger = more accurate but slower)
• Click a word to select it, Shift+click to extend the selection
• Ctrl+click any word to seek the video to that timestamp
• Double-click any word to edit its text
• Right-click or use the selection toolbar to apply Cut/Mute/Gain/Speed
• Select a word range and click Re-transcribe to improve accuracy on that segment

Zones (Cut / Mute / Gain / Speed)

• Zones are time-range edits applied during export
• Create zones by: selecting words in the transcript, using mark-in/mark-out on the timeline, or dragging on the waveform while in zone mode
• Cut = removes the segment from output entirely
• Mute = silences audio but keeps the video
• Gain = adjust volume (positive = louder, negative = quieter)
• Speed = change playback speed
• All zones can be resized and moved on the waveform timeline
• View and manage all zones in the Zone Editor panel

Waveform Timeline

• The waveform shows your audio with all zone overlays
• Click to seek, drag to scrub
• Enter Cut/Mute/Gain/Speed mode from the toolbar, then drag on the waveform to create a zone
• Click an existing zone to select it — drag edges to resize, drag body to move
• Press Delete or Backspace to remove the selected zone
• Ctrl+Scroll to zoom in/out, Scroll to pan horizontally
• Toggle individual zone types on/off with the colored buttons
• "Show adjusted timeline" compresses cut regions to preview the output

AI Features

• Filler word detection: finds "um", "uh", "like", "you know" and similar words. Add custom fillers in the AI panel. Apply All to create cut ranges for all detected fillers at once.
• Clip suggestions: analyzes your transcript to find the best 20-60 second segments for TikTok, YouTube Shorts, or Instagram Reels.
• AI features work locally with the bundled Qwen3 model (no internet needed) or via Ollama/OpenAI/Claude — configure in Settings.

Markers

• Markers are named timestamps pinned to the waveform
• Add markers at the current playhead position with a label and color
• Markers auto-sort as chapters — copy as YouTube timestamps format
• Useful for chapter breaks, key moments, or section headings

Music & Append

• Background Music: add a music track with auto-ducking (music lowers when someone speaks)
• Append Clips: load additional video files to concatenate during export
• Both are applied during re-encode export only

Export

• Fast mode (stream copy): no quality loss, but doesn't apply cuts, effects, or music — only works if you haven't made any edits
• Re-encode mode: applies all edits, cuts, effects, captions, and music
• Captions: burn directly into video or export as separate SRT/VTT file
• Loudness normalization: match YouTube (-14 LUFS), Spotify (-16), or Broadcast (-23) standards
• Audio enhancement: noise reduction and speech clarity via DeepFilterNet
• Video zoom: crop and reposition the frame (useful for removing letterboxing or reframing)

Keyboard Shortcuts [Full table of all shortcuts — same as the ? cheatsheet but always visible in this section]

Settings

• AI Providers: configure Ollama (local), OpenAI (cloud), or Claude (cloud). The bundled Qwen3 model works with zero setup.
• Model Management: view and delete downloaded Whisper and LLM models to free disk space
• Keyboard Shortcuts: remap any shortcut — click a binding then press your desired combination
• Confidence threshold: adjust the low-confidence word highlighting sensitivity
• Zone preview padding: how much context to show before/after zones during preview

2.3 First-run onboarding

When a user opens the app for the first time (no license activated, no project loaded):

Show a welcome overlay with:

1. "Welcome to TalkEdit" heading
2. Brief description: "The offline video editor for long-form content"
3. Three quick-start steps with icons:
   • Open a video → starts transcription
   • Edit by deleting words → cuts out the matching video
   • Export your final cut
4. "Got it" button that dismisses permanently (store in localStorage)
5. A "Show this again" checkbox in the Help panel

---

3. Keyboard shortcut cheatsheet improvements

Current: ? key appends a <div> to document.body with a table of shortcuts.

Fixes:

• Render the cheatsheet as a React portal (inside a modal overlay) instead of manual DOM
• Add a close button (×) in the top-right corner
• Group shortcuts by category with visual headers (Transport, Editing, File, View)
• Show the current active preset name at the top
• Add the ? tooltip "Show/hide keyboard shortcuts" to itself
• Show the cheatsheet from the Help panel too (not just ? key)

Categories and grouping:

Transport	Edit	File	View
Space — Play/Pause	Delete — Cut selection	Ctrl+S — Save	? — Toggle cheatsheet
← → — Skip 5s	I — Mark in	Ctrl+O — Open	Ctrl+F — Find
J — Slow down	O — Mark out	Ctrl+E — Export
K — Pause	Ctrl+Z — Undo
L — Speed up	Ctrl+Shift+Z — Redo

---

4. Missing states (empty/loading/error)

Empty states

Component	Current	Fix
MarkersPanel	Shows nothing when no markers	Add: "No markers yet. Press M or click Add Marker to create one."
AIPanel (clips)	Shows nothing before first detection	Add: "Click 'Find Best Clips' to discover the most shareable moments in your video."
AppendClipPanel	"No additional clips loaded"	Keep but add hint: "Add video files to concatenate during export."
WaveformTimeline (zones)	Canvas is empty	No change needed — zones are overlays, not content

Error states

Component	Current	Fix
AIPanel	Errors logged to console only	Show error message in the panel with a retry button
ExportDialog	Shows export error in a red box	Keep, but add a "Copy error" button
VideoPlayer	No error for broken video	Add an error state with "Could not load video" + re-select button
WaveformTimeline	Shows error text in a <pre> tag	Keep, but add a "Retry" button
Silence detection	Errors use alert()	Show error inline in the panel

Loading states

Component	Current	Fix
WaveformTimeline	Blank canvas while audio loads	Add a centered "Loading waveform…" spinner
Export	Percentage text only	Add a determinate progress bar
Transcription	Spinning waveform bars + text	Add a determinate progress bar for model download phase
AI features	Spinner + "Processing…"	Add descriptive step text ("Analyzing transcript…")

---

5. Consistency fixes

5.1 Fix mute zone color in ZoneEditor

ZoneEditor.tsx uses border-orange-500/40 for mute zones — should be border-blue-500/40 to match the waveform timeline's blue mute color.

5.2 Unify disabled opacity

• All disabled buttons: opacity-40 (currently some use 50%)

5.3 Unify border radius

• All toolbar buttons: rounded-md (keep)
• All sidebar panel inputs: rounded-lg (keep)
• All zone/detection list items: rounded-lg (currently rounded)

5.4 Remove orphaned VolumePanel

VolumePanel.tsx is not imported anywhere. Either wire it into the sidebar or remove it.

---

6. Quick wins (implement first)

• Add title tooltips to ALL toolbar buttons with shortcut hints
• Add title tooltips to ALL ExportDialog controls
• Fix mute zone color in ZoneEditor (orange → blue)
• Add empty state to MarkersPanel
• Add error display to AIPanel
• Add close button to keyboard cheatsheet
• Unify disabled opacity to 40% everywhere
• Remove orphaned VolumePanel.tsx
• Add loading spinner to WaveformTimeline

7. Help system (implement second)

• Create HelpContent.tsx with all feature documentation content
• Add Help button to toolbar (? icon, opens sidebar)
• Wire Help as a sidebar panel (like AI, Export, Settings)
• Build first-run welcome overlay component
• Add "Show help on startup" checkbox to Settings
• Render keyboard cheatsheet as React portal with close button

8. Polish (implement third)

• Progress bar for export (determinate bar, not just text)
• Progress bar for model downloads
• Retry button on waveform load error
• Confirmation dialog for zone/marker deletion
• Keyboard-accessible split pane resizing
• Larger hit targets for canvas zone handles (r=4 → r=6)
• Search bar match indicator contrast improvement