Files
stemengine_old/SUMMARIES.md
T

142 KiB
Raw Blame History

StemEngine — Session Summaries


2026-03-06

Diarization fix — whisperx.DiarizationPipeline not exposed

Problem: whisperx.DiarizationPipeline raised AttributeError because this version of WhisperX uses a lazy-loader __init__.py that only re-exports a handful of functions (load_model, align, assign_word_speakers, etc.) and never added DiarizationPipeline to the list.

Fix: Import directly from the submodule:

from whisperx.diarize import DiarizationPipeline as _DiarizationPipeline

Diarization fix — use_auth_token renamed to token

Problem: After fixing the import, DiarizationPipeline.__init__() raised TypeError: unexpected keyword argument 'use_auth_token'. The installed version renamed the parameter to match the huggingface_hub convention change.

Fix: Changed constructor call to _DiarizationPipeline(token=hf_token, device=device).

Also noted: this version defaults to pyannote/speaker-diarization-community-1, a community model that does not require accepting HuggingFace terms of use.


Diarization fix — speaker labels not propagated from words to segments

Problem: whisperx.assign_word_speakers in some versions assigns "speaker" only to individual word dicts, not to the parent segment dict. seg.get("speaker") returned None so |sp:SPEAKER_XX| tags were never emitted in LRC/ELRC output.

Fix (already applied in prior session): After assign_word_speakers, iterate segments and propagate the most-frequent word-level speaker to each segment that lacks one:

for _seg in wx_result.get("segments", []):
    if _seg.get("speaker"):
        continue
    _spk_counts = {}
    for _w in _seg.get("words", []):
        _s = _w.get("speaker")
        if _s:
            _spk_counts[_s] = _spk_counts.get(_s, 0) + 1
    if _spk_counts:
        _seg["speaker"] = max(_spk_counts, key=_spk_counts.get)

Timing fix — unaligned words all sharing seg["start"]

Problem: When WhisperX cannot align individual words (returns start=None), all such words in a segment received seg["start"] as their timestamp. In the frontend wordFillPct() function, consecutive words with identical timestamps produce dur = 0 → NaN fill percentage → broken karaoke highlight animation.

Fix: Distribute unaligned words evenly across [seg_start, seg_end] by index:

if _ws is None:
    _ws = _seg_start + (_wi / _n_words) * (_seg_end - _seg_start)
    _we = _seg_start + ((_wi + 1) / _n_words) * (_seg_end - _seg_start)

CUDA OOM — retry with reduced settings

Problem: Loading large, large-v2, or large-v3 models on cards with limited VRAM raised RuntimeError: CUDA out of memory, failing the job entirely.

Fix: Wrapped load_model + transcribe in a 2-attempt retry loop. On first OOM:

  • Clear CUDA cache (gc.collect() + torch.cuda.empty_cache())
  • Reduce batch_size to 4
  • Switch compute_type to "int8"
  • Update job progress to inform the user
  • Retry

On second OOM or any non-OOM error, re-raise. Also added _clear_cuda_cache() at job start to flush leftover allocations from previous jobs.

Added user-friendly error message on OOM failure suggesting smaller model or Eco preset.


WSL2 display stability — VRAM cap + CPU niceness + inter-phase yields

Problem: On WSL2, WhisperX saturates the shared GPU, starving the Windows Display Manager (DWM). This causes TDR timeouts, screen flicker, and display driver restarts.

Fixes added to lyric_transcriber_service.py:

  1. _apply_cuda_limits() called at job start:

    • os.nice(10) — lowers the job thread's CPU scheduling priority
    • torch.cuda.set_per_process_memory_fraction(fraction) — hard-caps VRAM usage, reserving headroom for DWM. Default 80%, configurable via STEMENGINE_GPU_MEMORY_FRACTION env var.
  2. time.sleep(0.15) inserted after each model-unload+cache-clear between the three heavy GPU phases (Whisper → alignment → diarization), giving the GPU scheduler a window to service DWM between compute bursts.

System-level recommendation (Windows host, not in code):

  • Create %UserProfile%\.wslconfig:
    [wsl2]
    memory=8GB
    processors=6
    
  • Set STEMENGINE_GPU_MEMORY_FRACTION=0.75 in Docker compose or .env for tighter cards.

2026-03-06 (continued)

Syllables checkbox + hide Phonemization in Auto Pipeline

Added lsyncAlign checkbox ("Syllables") to Auto Pipeline options (Settings.tsx, AutoPipelineDialog.tsx). Removed Phonemization from both ProjectDetail.tsx (Lyrics Sync tab) and Settings.tsx (Auto Pipeline step editor) — state kept for API compatibility.


Explicit mode — Whisper profanity uncensor

Added explicit: bool to LyricTranscribeRequest, run_lyric_transcription(), and frontend (ProjectDetail.tsx, AutoPipelineDialog.tsx, client.ts).

_uncensor_segments() in lyric_transcriber_service.py applies regex post-processing after transcription to restore censored words (f*** → fuck, etc.). Initial-prompt primer approach was discarded — it caused Whisper to reproduce the prompt text verbatim at the start of the transcription.


Hip-hop vocal style

Added vocal_style: str = "general" parameter throughout the stack. When "hiphop":

  • VAD thresholds: vad_onset=0.25, vad_offset=0.15, no_speech_threshold=0.35, hallucination_silence_threshold=1.0
  • Monkeypatches Silero.__call__ in try/finally to inject min_speech_duration_ms=100, min_silence_duration_ms=150 (these params are commented out in whisperx's wrapper, so they must be injected at call time).

GlobalAudioBar fixes + X button

  • Bar not appearing: isActiveRef is a ref so changing it doesn't trigger effects. Fixed by calling publishMeta(...) immediately after isActiveRef.current = true in both DynamicMixPlayer and LyricsLivePreview togglePlay branches.
  • Audio continuing after navigation: unregisterPlayback only removes the registry reference, not the audio element. Fixed by calling stopPlayback() before unregisterPlayback() in unmount cleanup of both players.
  • X button: Added stopCurrent() export to audioRegistry.ts (calls registered stop callback + clears _current). Added X (lucide-react) button to GlobalAudioBar.tsx.

Karaoke fill/pop mode + Open Foundry fonts

LyricsLivePreview.tsx:

  • Added karaokeMode: 'fill' | 'pop' to StyleState (default 'fill').
  • KaraokeWord now accepts isActive?: boolean and mode?: 'fill' | 'pop':
    • fill: existing left-to-right gradient sweep.
    • pop: active word bright + 15% larger; already-sung words stay bright; future words dim. Line accumulates highlighted words as sung — no gradient, no fill.
  • All three KaraokeWord call sites (karaoke, glow, blur styles) pass isActive and mode.
  • Added Fill/Pop toggle buttons to StylePicker.
  • Replaced FONT_OPTIONS with 10 Open Foundry fonts (Archivo, EB Garamond, Inter, Libre Baskerville, Oswald, Poppins, Roboto, Work Sans, Young Serif + System fallback).

package.json: Added @fontsource/* packages for all 9 named fonts — self-hosted, no Google CDN calls. Installed automatically by start.sh at container start.

main.tsx: Imports each @fontsource/* package so Vite bundles the font files.


Font dropdown dark background + bold toggle

  • Dropdown white background fix: Added colorScheme: 'dark' on the <select> and background: '#1e293b', color: '#e2e8f0' on each <option> so the native OS dropdown renders dark.
  • Bold toggle: Added fontBold: boolean to StyleState (default false). B button in StylePicker next to the font selector. Applied as fontWeight: 700 / 400 on the lyrics container so it cascades to all rendered text.

Pop mode rendering bug fix

Problem: In pop mode, WebkitTextFillColor: 'transparent' set by a previous fill-mode render persisted on the DOM element (React doesn't always clear vendor-prefixed style properties when they're removed from the style object). This made text invisible while the gradient background showed as a colored rectangle.

Fix: In the KaraokeWord pop-mode branch, explicitly reset all gradient/clip properties:

backgroundImage: 'none',
WebkitBackgroundClip: 'border-box',
WebkitTextFillColor: 'currentColor',  // key: restores text color rendering
backgroundClip: 'border-box',

WebkitTextFillColor: 'currentColor' makes the text use the CSS color property again, which is what pop mode sets per-word.


Pop mode — RAF loop still writing gradient to DOM

Problem: Even after the React CSS resets in KaraokeWord, a fill bar kept appearing in pop mode. The real cause: a requestAnimationFrame loop writes backgroundImage directly to activeWordSpanRef.current.style every frame (to avoid 60fps React re-renders). This direct DOM write completely bypassed React's style reconciliation and overwrote the pop-mode resets on every tick.

Fix:

  • Added karaokeModeRef = useRef(karaokeMode) alongside the other RAF refs.
  • Updated it inline each render: karaokeModeRef.current = karaokeMode (outside any effect, so it's always current without restarting the loop).
  • Gated the gradient write in the RAF loop: if (activeWordSpanRef.current && lastLineIdx >= 0 && karaokeModeRef.current !== 'pop').

Pop mode — done words should stay bright

Corrected pop mode behavior: sung (done) words stay bright, not dim. Only future words are dim. Active word is bright + 15% larger.

Changed color: isActive ? bright : dim → color: (isActive || done) ? bright : dim in KaraokeWord.


Pop mode — active word shifts down

Problem: Active word is fontSize * 1.15; base uses verticalAlign: 'top', so the larger word's top aligns with others but extends further down.

Fix: Override to verticalAlign: 'middle' in the pop-mode branch so all words (normal and enlarged) center on the same axis.


Album card font not affected by font option

Both the small windowed overlay and the fullscreen album panel used hardcoded fontFamily / fontWeight values, so the user's font selection had no effect.

Fix: Added fontFamily to both text containers (windowed overlay <div> and fullscreen panel <div>). The subtitle in both also respects fontWeight: fontBold ? 700 : 400. Artist name stays at 700 (it's always a heading).

Also changed the windowed overlay from flexDirection: 'column' (art above, text below) to flexDirection: 'row', alignItems: 'center' so text sits beside and vertically centered on the art.


TypeScript error 7026 / 2875 / 2322 (pre-existing, not build-blocking)

These TS language server errors ("no interface JSX.IntrinsicElements exists", "react/jsx-runtime not found") appear on whichever line was last edited. They are a pre-existing tsconfig / language server cache issue — not introduced by any of the above changes. Vite uses esbuild for transpilation and does not type-check, so vite build is unaffected. Restart the TS server (VS Code: Ctrl+Shift+P → "TypeScript: Restart TS Server") or let the container run npm install to resolve.

Styling options — stroke, shadow, scale, pop size

Added to StyleState: strokeWidth, strokeColor, shadowBlur, shadowX, shadowY, shadowColor, scaleX, scaleY, popScale.

StylePicker gained two new rows:

  • Effects row: stroke color swatch + width slider (0–4), shadow color swatch + blur/X/Y sliders.
  • Scale row: W (horizontal) and H (vertical) scale sliders (0.5–2×). A Pop slider (15–25%) appears conditionally when karaokeMode === 'pop'.

Lyrics container (outer div): textShadow and WebkitTextStroke applied from state; as any cast used because the file uses named React imports (no React namespace for React.CSSProperties).

Inner lyrics div: transform updated to translateY(…) scaleX(…) scaleY(…).

KaraokeWord: accepts popScale?: number (default 15); pop branch uses fontSize * (1 + popScale / 100) for the active word size.

All three KaraokeWord call sites (karaoke / glow / blur renderers) updated to pass popScale={popScale}.

Stroke fix — proper outer border, not hollow outline; show/hide toggles; shadow opacity; Reset

Problem: -webkit-text-stroke strokes symmetrically inward and outward, hollowing the glyph fill. In gradient (fill) mode, -webkit-text-fill-color: transparent made it worse — just an outline with no visible fill.

Fix: Replaced -webkit-text-stroke entirely with a disc-shaped text-shadow simulation. makeStrokeShadow(width, color) generates zero-blur shadows at every integer offset within a radius, producing a filled outer ring. Works correctly with WebkitTextFillColor: transparent (gradient mode) and normal color fills (pop mode).

Added hexToRgba(hex, opacity) to apply shadow opacity to the drop shadow.

New StyleState fields: strokeEnabled: boolean, shadowEnabled: boolean, shadowOpacity: number (0–1).

DEFAULT_STYLE constant extracted so defaults are a single source of truth used by both useState and the new resetStyle handler.

StylePicker UI changes:

  • Stroke and Shadow labels are now toggle buttons (click to enable/disable); controls collapse when disabled.
  • Shadow controls gained an Opacity slider (0–1) next to the color swatch.
  • Reset button added in the font row (right side) — clears localStorage and restores DEFAULT_STYLE.

StylePicker prop: onReset: () => void added. resetStyle callback in main component removes the localStorage key and calls setStyle(DEFAULT_STYLE).

Stroke rendering order — abandoned text-shadow approach; switched to WebkitTextStroke + paint-order

Attempt 1 (disc text-shadow): Generated a disc of zero-blur text-shadow entries. Inner shadows covered the gradient interior, making text look hollow/broken.

Attempt 2 (ring text-shadow): Limited shadows to the outermost pixel band. Still jagged/bubbly in practice — each shadow entry is a full pixel-offset copy of the glyph shape; many overlapping copies create rough anti-aliasing artefacts visible as a bubbly halo.

Final fix: Removed makeStrokeShadow entirely. Now use:

  • WebkitTextStroke: '${strokeWidth}px ${strokeColor}' on the container (cascades to all child text)
  • paintOrder: 'stroke fill' on the container (cascades): renders stroke first, then fill on top — only the outer half of the stroke extends beyond the glyph edge; the inner half is covered by the opaque fill

For pop mode (solid fill): only the outer stroke ring is visible. Clean outer border. ✓ For fill/gradient mode (WebkitTextFillColor: transparent): fill is transparent, so inner half of stroke is slightly visible at the glyph edge. For thin strokes this is a minor tint at the very edge; outer border is clean and anti-aliased. Acceptable trade-off vs. jagged shadow approach. ✓

Drop shadow remains via textShadow on the container, unchanged.

Stroke/shadow layered DOM approach in KaraokeWord

Problem: WebkitTextStroke + paint-order: stroke fill still broke gradient text. CSS paints background (where the gradient lives via background-clip:text) before text-shadow/WebkitTextStroke, so any stroke technique on the same element appears on top of the gradient, not behind it. No single-element CSS solution can place the stroke behind a background-clip:text gradient.

Fix: Layered DOM structure inside KaraokeWord. When stroke or shadow is active:

<span style="position:relative">          ← wrapper (layout)
  <span aria-hidden style="position:absolute">  ← behind-layer: stroke + shadow
  <span ref={elRef}>                            ← fill-layer: gradient/pop text
  • Behind-layer: renders WebkitTextStroke + paintOrder: stroke fill + textShadow. With opaque fill color, only the outer half of the stroke extends beyond the glyph → clean outer ring.
  • Fill-layer: resets WebkitTextStroke: '0 transparent' and textShadow: 'none' to cancel container inheritance, then renders gradient or solid-color text on top.

Result: shadow (back) → stroke → base text (front), all properly layered.

WordEffects interface added; wordEffects object constructed from destructured style state; passed to all 3 KaraokeWord call sites as effects={wordEffects}.

hexToRgba moved above KaraokeWord so behindLayer can call it.

Superseded — stroke/shadow are now handled per-line via the behind-layer pattern for all modes. See "Universal behind-layer stroke/shadow" below.

Layer z-index fix + sluggishness fix

z-index bug: position: absolute elements paint on top of in-flow elements by default regardless of DOM order. The behind-layer (position: absolute) was rendering above the fill span. Fixed by adding zIndex: 0 to the behind-layer and position: relative; zIndex: 1 to the fill/pop front span via frontLayerBase. CSS z-index only applies to positioned elements, so the fill span needed position: relative to participate in z-index stacking.

Sluggishness: The RAF loop triggers React state updates (~60 fps), causing re-renders of the lyrics line. Each re-render was constructing a new wordEffects object, propagating as a changed prop to every KaraokeWord in the line. Fixed by wrapping wordEffects in useMemo with the style fields as dependencies — the object reference is now stable during playback and only changes when the user adjusts a style control. useMemo added to the React import.

Album art overlay text exempt from stroke/shadow

The windowed overlay (div wrapping artist + title <p> tags) and the fullscreen album panel (div with artist/title) both inherit WebkitTextStroke and textShadow from the outer lyrics container. Fixed by adding WebkitTextStroke: 'initial' and textShadow: 'none' to the style prop of each wrapper div (as any cast to avoid TS CSSProperties namespace error).

Pop mode syllable transition — font-size → transform: scale()

Problem: Pop mode used fontSize: activeFontSize (switching between base and scaled size) on the wrapper, with transition: 'font-size 0.08s ease'. Font-size changes trigger layout reflow on every transition frame, causing jank. 80ms was also too short, making the snap feel jarring.

Fix:

  • Replaced fontSize toggling with transform: scale(1 + popScale/100) on the wrapper span — GPU-composited, zero layout reflow.
  • fontSize is now always fontSize (base size); the wrapper transform handles the visual growth.
  • Transition: transform 0.15s ease-out, color 0.15s ease-out — 150ms feels smooth without lag; ease-out snaps into the active state and eases out of it naturally.
  • willChange: 'transform' added on pop-mode wrappers to hint the browser to promote them to a compositor layer.
  • Behind-layer fontSize also stays at base size (scales with the wrapper via inherited transform).

Stroke rounded joins — prevent "fang" artefacts

-webkit-text-stroke defaults to miter joins at sharp glyph corners, producing spike/fang artefacts. Fixed by adding strokeLinejoin: 'round' and strokeLinecap: 'round' (SVG stroke properties, honoured by Chromium/WebKit on HTML text with -webkit-text-stroke) to behind-layer spans. Superseded by universal behind-layer approach — see below.

Pop mode — Snap slider (transition duration)

Added popSnap: number (ms) to StyleState and DEFAULT_STYLE (default: 150ms). A Snap slider (50–500ms, step 25ms) appears next to the Pop slider when karaokeMode === 'pop'. The value is passed as snapMs prop to KaraokeWord (default 150) and used in the wrapStyle transition: `transform ${snapMs}ms ease-out, color ${snapMs}ms ease-out`. Range rationale: 50ms feels near-instant/snappy; 500ms is a slow, deliberate fade.

BG color scope fix — fullscreen root no longer inherits bgColor

The fullscreen root <div> had style={isFullscreen ? { backgroundColor: effectiveBg } : undefined}. This painted the entire fullscreen container (including toolbar, controls, album panel) with the user's BG color. The BG color is already applied correctly on the inner lyrics area div (backgroundColor: effectiveBg at line ~1804). Removed the root-level style entirely (style={undefined}).


Karaoke scroll jitter — root cause and fix

Root cause (windowed rendering): renderKaraokeStyle, renderGlowStyle, and renderBlurStyle each used a window = 3 slice (lines.slice(activeLine-3, activeLine+4)). Because the active line was always at index 3 within this window, its offsetTop was effectively constant (~3 × lineHeight) regardless of which line was active. The translateY formula containerHeight/2 − offsetTop − lineHeight/2 therefore produced the same value on every line transition — no scroll animation occurred and lines appeared to "jump" into place.

Fix: All three windowed render functions now iterate over all lines (lines.map(...)). Lines with dist > 5 from the active line get opacity: 0; lines with dist > 4 in blur mode skip the expensive blur() filter. The inner scroll div still uses overflow: hidden on its container, so only nearby lines are visible. With all lines in the DOM, offsetTop grows monotonically as activeLine advances, and the CSS transition: transform 0.35s cubic-bezier(0.33, 1, 0.68, 1) on the scroll div animates a true smooth vertical scroll.

Secondary fix — translateY bypasses React state: translateY was moved from useState to a direct DOM write in useLayoutEffect via scrollDivRef.current.style.transform. This eliminates the two-render sequence on line changes (content update → state update → second render) that could cause the transition to be interrupted. translateYRef tracks the current value for use by handleRecenter and the scaleX/scaleY deps in the same effect.


Glow slider — configurable glow radius

Added glowSize: number to StyleState and DEFAULT_STYLE (default: 8px). A Glow slider (2–24px, step 1px) appears in StylePicker when visualStyle === 'glow'. Required passing visualStyle as a new optional prop to StylePicker. The glow filter in renderGlowStyle uses glowSize for the inner shadow and glowSize * 2 for the wider outer shadow: `drop-shadow(0 0 ${glowSize}px ${color}cc) drop-shadow(0 0 ${glowSize*2}px ${color}66)`.


Smooth size transition between active and adjacent lines

Problem: The active line used a different fontSize multiplier (e.g. fontSize * 1.05) than inactive lines (fontSize * 0.85), causing an instant size jump on each line transition with no animation.

Why font-size transition wasn't used: CSS font-size transitions cause layout reflow on every frame, which would desync the scroll position (the useLayoutEffect measures offsetTop based on the final layout, but the font-size is still mid-animation, so lines aren't at their measured positions yet).

Fix: All three render functions (renderKaraokeStyle, renderGlowStyle, renderBlurStyle) now use a uniform base fontSize for all line divs in layout. Visual size is controlled via transform: scale() per line based on distance from active:

  • dist = 0 (active): scale(1.0)
  • dist = 1: scale(0.88)
  • dist = 2: scale(0.82)
  • dist ≥ 3: scale(0.78), opacity fades to 0 past dist 5

transformOrigin is set to match textAlign (left center / center center / right center). All lines get transition: 'transform 0.35s ease-out, opacity 0.35s ease-out' matching the scroll transition duration so both animate in sync. Since transform doesn't affect layout, offsetTop is stable and the scroll calculation remains correct. KaraokeWord now receives base fontSize (the wrapper div's scale handles visual enlargement).


Universal behind-layer stroke/shadow for all line types

Problem: Stroke and shadow were applied via WebkitTextStroke / textShadow on the outer lyrics container div, inherited by all descendant text. This caused:

  • Fangs on non-active karaoke/glow/blur lines: plain <span> elements inherited paintOrder: stroke fill from the container, producing miter-join spikes at sharp letter corners.
  • Stroke inside gradient fill: for wordless active lines using WebkitTextFillColor: transparent, the inherited stroke bled through the transparent fill area.

Previously only KaraokeWord (active words) used the behind-layer pattern. Non-active lines and wordless active lines inherited stroke/shadow from the container.

Fix: WebkitTextStroke, paintOrder, strokeLinejoin, strokeLinecap, and textShadow are removed from the container entirely. Every line in every mode now renders stroke and shadow via its own behind-layer:

Outer div          — opacity, transform/scale, font size (NO stroke/shadow/padding)
  behindLayer div  — position: absolute, zIndex: 0, aria-hidden
                     strokeColor fill, WebkitTextStroke, paintOrder: stroke fill
                     strokeLinejoin: round, textShadow
  frontLayer div   — position: relative, zIndex: 1, padding
                     WebkitTextStroke: '0 transparent', textShadow: none
                     actual text color / gradient fill

Three shared constants computed once per render:

const lineStrokeVal  = strokeEnabled && strokeWidth > 0 ? `${strokeWidth}px ${strokeColor}` : undefined
const lineShadowVal  = shadowEnabled ? `${shadowX}px ${shadowY}px ${shadowBlur}px ${hexToRgba(...)}` : undefined
const lineNeedsLayer = !!(lineStrokeVal || lineShadowVal)

When lineNeedsLayer is false the behindLayer is skipped entirely (single-div fast path).

Coverage: renderScrollStyle, renderFadeStyle, renderKaraokeStyle (non-active + active wordless), renderGlowStyle (non-active + active wordless), renderBlurStyle (non-active + active wordless). Active word-by-word lines continue to use KaraokeWord's existing behind-layer.

Result: Fill is always the top layer; stroke appears only outside the letterform; shadow is always behind both stroke and fill — in every mode, for every line.


2026-03-09

WhisperX hallucination fix — "Thank you", emoji, and Japanese subscription prompts appended to transcriptions

Problem: WhisperX transcriptions occasionally appended hallucinated text at the end of or within a transcription — e.g. "Thank you", emoji, or "チャンネル登録よろしくお願いします" ("Please subscribe to my channel"). Reproduced on 為に by Sasuke Haraguchi.

Root cause — two compounding factors:

  1. _fill_transcript_gaps re-transcribed trailing silence. The function (lyric_transcriber_service.py:1144) scanned for audio regions > 2 s with no detected speech and re-ran WhisperX on each slice. The trailing silence after the last lyric was included in this scan. With no real speech, WhisperX hallucinated YouTube-trained filler content (subscription prompts, sign-offs, "Thank you"). Whisper was trained heavily on YouTube video audio, and these are the completion patterns it learned for silence/ambient noise, especially when Japanese is the detected language.

  2. no_speech_threshold: 0.45 was too low. Whisper's stock default is 0.60. The lower value made WhisperX more aggressively classify silent or ambient-noise segments as "probably speech" rather than discarding them, which fed more silent audio to the decoder and increased hallucination frequency.

Fixes applied to backend/services/lyric_transcriber_service.py:

  • _fill_transcript_gaps: Removed the trailing-gap check. Mid-song gaps are still re-transcribed (catches lyrics in quiet passages), but the audio tail after the last segment is no longer sent back through the model. Comment added explaining the rationale.

  • no_speech_threshold: Raised from 0.45 → 0.50. Comment updated to document that 0.45 was too aggressive and caused silence to be treated as speech.


MDX-Net fix — module 'numpy' has no attribute 'stft'

Problem: mdxnet_separator.py called np.stft() and np.istft() in _stft / _istft. These functions do not exist in NumPy in any version — they were never part of the NumPy API. The code was broken from the start and had never been exercised.

Fix: Replaced both functions with librosa.stft / librosa.istft, which share the same n_fft / hop_length parameter names. librosa is already a dependency (used in _load_audio).

Shape contract preserved: _spec_to_batch expects (channels, freq, time, 2) where the last dimension is [real, imag]. librosa returns a complex (freq, time) array, so _stft now packs it with np.stack([spec.real, spec.imag], axis=-1), and _istft reconstructs the complex array with spec[ch,:,:,0] + 1j * spec[ch,:,:,1] before calling librosa.istft.


MDX-Net fix — [ONNXRuntimeError] : 2 : INVALID_ARGUMENT : Got invalid dimensions for input: input … index: 1

Problem: After the librosa fix, ONNX inference still failed with an input-dimension error. Three compounding bugs:

  1. N_FFT = 2048 was wrong. librosa.stft with n_fft=2048 produces 1025 frequency bins. The ONNX models expect input with DIM_F = 3072 bins (plus the Nyquist bin = 3073 total). The correct n_fft for 3073 bins is 6144.

  2. _spec_to_batch produced (batch, 2, dim_f, dim_t) instead of (batch, 4, dim_f, dim_t). UVR MDX-Net ONNX models expect 4 input channels: [L_real, L_imag, R_real, R_imag] — i.e. stereo(2) × complex(2) merged into one dimension. The old code kept stereo and complex as separate dimensions, producing the wrong channel count of 2.

  3. _batch_to_spec inverted the wrong shape — inverse of the broken forward pass; was not the correct inverse of the corrected forward pass.

  4. Length mismatch in _demix. After ISTFT, target_audio can be slightly shorter or longer than the original mix due to STFT/ISTFT padding behaviour. mix - target_audio raised an operand-shape error.

Fixes applied to backend/services/mdxnet_separator.py:

  • N_FFT: Changed 2048 → 6144. This produces 3073 freq bins; the top bin is cropped to 3072 before ONNX and zero-padded back after.

  • _spec_to_batch rewritten:

    Input:  (2, freq, time, 2) = (stereo, freq, time, complex)
    →  transpose to (stereo, complex, freq, time) = (2, 2, freq, time)
    →  reshape to merge: (4, freq, time)
    →  crop freq to dim_f, pad time to multiple of dim_t
    →  chunk time: (4, dim_f, t_chunks, dim_t)
    →  transpose: (t_chunks, 4, dim_f, dim_t)   ← correct ONNX input shape
    
  • _batch_to_spec rewritten as the exact inverse:

    Input:  (t_chunks, 4, dim_f, dim_t)
    →  reassemble time: (4, dim_f, time)
    →  remove time pad, restore freq (zero-pad back to n_fft//2+1)
    →  reshape: (2, 2, freq, time)  [stereo, complex]
    →  transpose: (2, freq, time, 2)   ← original spec format
    
  • _demix length guard added: after ISTFT, target_audio is trimmed or zero-padded to match mix.shape[1] before subtraction.

Second-pass fix (after inspecting actual model): Inspecting UVR_MDXNET_KARA.onnx with onnxruntime revealed the true input shape is (batch, 4, **2048**, **256**) — not (batch, 4, 3072, 8). The hardcoded DIM_F=3072 and DIM_T=8 were simply wrong; different model files have different dimensions. Fix: removed all module-level DIM_F, DIM_T, N_FFT constants. _get_session() now reads session.get_inputs()[0].shape and stores self.dim_f = shape[2], self.dim_t = shape[3], self.n_fft = self.dim_f * 2. All calls to _stft, _spec_to_batch, _batch_to_spec, _istft pass these instance values explicitly. _batch_to_spec now reads dim_f/dim_t from the metadata dict rather than globals.

Third-pass fix — name 'N_FFT' is not defined: After removing the module-level constants, the three function signatures (_stft, _istft, _spec_to_batch) still used N_FFT, DIM_F, DIM_T as default parameter values, causing a NameError at import time. Fixed by replacing the defaults with inline literals (n_fft=4096, dim_f=2048, dim_t=256) matching the KARA model's actual dimensions. These defaults are never used in practice — MDXNetSeparator._demix always passes explicit values derived from the session.


MelBand Karaoke fix — 404 on model download

Problem: mel_band_karaoke separation failed with 404 Client Error during model download. The repo becruily/mel-band-roformer-karaoke still exists on HuggingFace, but the filenames changed: the actual files are mel_band_roformer_karaoke_becruily.ckpt (1.72 GB) and config_karaoke_becruily.yaml, not model.ckpt / config.yaml.

Two locations had the wrong filenames:

  1. backend/routers/models.py — MODEL_DOWNLOAD_INFO["mel_band_karaoke"]: files list updated from ["model.ckpt", "config.yaml"] to ["mel_band_roformer_karaoke_becruily.ckpt", "config_karaoke_becruily.yaml"]. Also corrected size_mb from 170 → 1760 to reflect the actual 1.72 GB checkpoint.

  2. backend/services/mel_band_specialized_separator.py — MelBandKaraokeSeparator.__init__: model_path and config_path updated to use the correct filenames so that _ensure_model's existence check and snapshot_download both reference the right paths.


MelBand Karaoke fix — Missing key(s) in state_dict: static_alpha

Problem: After the download fix, model loading raised Error(s) in loading state_dict for MelBandRoformer: Missing key(s) in state_dict: "layers.0.0.layers.0.0.static_alpha", .... The installed bs_roformer library is newer than the checkpoint — a static_alpha learnable scalar was added to the RoFormer attention layers in a later release. The checkpoint was trained before this parameter existed, so it is absent from the saved weights.

Fix: Changed model.load_state_dict(state_dict) → model.load_state_dict(state_dict, strict=False) in MelBandSeparatorBase.get_model(). Missing keys keep their initialized values (static_alpha defaults to 1.0, a neutral multiplier). A logging.warning is emitted listing how many keys were missing, so any future version-mismatch is visible in logs without crashing the job.


MelBand Karaoke OOM fix — VRAM cap and OOM retry wired into separation path

Problem: mel_band_specialized_separator.py was not wired into StemEngine's global power/GPU settings. Two gaps:

  1. No VRAM cap on separation. _apply_cuda_limits() (which calls torch.cuda.set_per_process_memory_fraction(0.80)) was only ever called by lyric_transcriber_service.py. If separation ran before transcription (or transcription never ran in the session), the allocator had no VRAM ceiling and could OOM.

  2. No OOM retry in _run_mel_band_karaoke. On an out of memory exception the function just re-raised, letting the top-level handler report it as a CUDA error with no recovery.

Fixes applied to backend/services/separator_service.py:

  • VRAM cap: Added from .lyric_transcriber_service import _apply_cuda_limits; _apply_cuda_limits() at the top of run_separation(), before torch.cuda.empty_cache(). Now separation and transcription share the same VRAM ceiling (default 80%, overridable via STEMENGINE_GPU_MEMORY_FRACTION).

  • OOM retry in _run_mel_band_karaoke: Wrapped sep.separate_into_parts(...) in a 2-attempt loop. On the first out of memory error: clears CUDA cache, updates job progress ("GPU OOM — retrying with batch_size=1…"), and retries with batch_size=1. If the second attempt also fails, the exception propagates normally to the top-level CUDA error handler.


MelBand Karaoke OOM fix (second pass) — revert VRAM cap; add pre-load flush

Problem: After wiring _apply_cuda_limits() into run_separation(), users saw OOM even with 4 GB physically free on the GPU. Root cause: set_per_process_memory_fraction(0.80) caps the process at 9.6 GB. PyTorch's allocator holds a reserved cache from prior jobs inside that budget; within the remaining headroom, only 1.95 GB was truly free — not enough for the 1.04 GiB allocation the separator needed. The GPU monitor showed 4 GB free because it counts PyTorch's cache as "available" while CUDA counts it as "in use."

Fix:

  • run_separation() now flushes cache BEFORE applying the VRAM cap: gc.collect() + torch.cuda.empty_cache() runs first to release stale allocations from prior jobs, then _apply_cuda_limits() is called. The order matters: if stale cached blocks are counted against the cap before they're released, the cap appears tighter than it actually is. On this WSL2 system ~2 GB is permanently reserved for Windows (DWM); the 80% cap on 12 GB = 9.6 GB leaves that headroom for Windows processes. Flushing first ensures the separator starts with a clean budget within the cap.

  • Added gc.collect() + torch.cuda.empty_cache() flush in _run_mel_band_karaoke immediately before constructing the separator (which loads the model checkpoint). This second flush is necessary because allocations can accumulate between the start of run_separation() and when the model actually loads.


BSRoFormer wired into power settings (parity with MelBand Karaoke)

Audit of _run_bsroformer, _run_bsroformer_chorus, _run_bsroformer_sw revealed none had the pre-load VRAM flush or OOM retry that _run_mel_band_karaoke received. Applied the same pattern to all three:

  • Pre-load flush: gc.collect() + torch.cuda.empty_cache() added before the separator object is constructed in each runner.
  • OOM retry with batch_size=1: Added to _run_bsroformer and _run_bsroformer_chorus (2-attempt loop, same as MelBand). _run_bsroformer_sw gets flush only — it delegates to the audio-separator library which doesn't expose a batch_size parameter.
  • strict=False on load_state_dict: Applied to bs_roformer_separator.py and bs_roformer_chorus_separator.py with the same warning pattern as mel_band_specialized_separator.py — guards against future checkpoint/library version mismatches causing hard crashes.

2026-03-09 — Power settings wired into all remaining 10 separator runners

Extended the "power settings" pattern (pre-load VRAM flush + OOM retry + strict=False) to every remaining runner and separator that was missing it.

separator_service.py — pre-load gc+empty_cache flush added before the separator object is constructed in:

  • _run_mdxnet
  • _run_mel_band_roformer (also gets OOM retry)
  • _run_scnet (also gets OOM retry)
  • _run_medleyvox
  • _run_apollo
  • _run_aspiration
  • _run_bandit
  • _run_ensemble
  • _run_sepacap
  • _run_sepreformer

OOM retry loops added:

  • _run_mel_band_roformer: 2-attempt loop; on first OOM, gc+cache flush then retry with batch_size_override=1.
  • _run_scnet: 2-attempt loop; on first OOM, gc+cache flush then retry with chunk_size_override = (original or 262144) // 2.

strict=False on load_state_dict with warning applied to:

  • mel_band_roformer_separator.py (line 219): protects against missing keys (e.g. static_alpha) when library is newer than checkpoint.
  • scnet_separator.py (line 249): same guard.

2026-03-09 — Fix post-cancel VRAM leak and wrong job status after mid-run cancellation

Root cause diagnosis:

  • Cancellation is cooperative (flag-based). Once separate_into_parts() starts GPU compute, it runs to completion even after cancel — the flag is only checked between major stages. This is why the GPU keeps working after cancel; it's a fundamental limitation of thread-based execution (Demucs avoids this by using a subprocess that can be killed).
  • When a separator's internal should_cancel() check fires mid-run, it raises RuntimeError("Cancelled by user"). This propagated to run_separation's top-level except Exception block, where it didn't match "CUDA", so: (a) no VRAM cleanup was done, and (b) the job was stored with status=ERROR instead of CANCELLED. The model's VRAM wasn't freed until Python's GC got around to it — which could be after the next job's model load begins → OOM despite apparent free VRAM.

Fixes in separator_service.py run_separation():

  1. Cancellation branch in except: Added if jm.should_cancel(job_id) or "Cancelled by user" in err_str as the first condition — sets status=CANCELLED (not ERROR) and skips the error message path.
  2. finally block: Added after the except block — always runs gc.collect() + torch.cuda.empty_cache() regardless of how the job exits (success, error, or cancel). Ensures VRAM is returned to the CUDA driver before the next job starts.

2026-03-09 — Suppress noisy third-party FutureWarnings and demote missing-keys log to DEBUG

main.py: Added warnings.filterwarnings("ignore", ...) at startup to suppress FutureWarnings from rotary_embedding_torch (torch.cuda.amp.autocast deprecated) and contextlib (torch.backends.cuda.sdp_kernel deprecated). Both are upstream issues in third-party packages; the warnings are harmless.

All 5 separator files (mel_band_specialized_separator.py, mel_band_roformer_separator.py, scnet_separator.py, bs_roformer_separator.py, bs_roformer_chorus_separator.py): Demoted the "Checkpoint is missing N key(s)" log from WARNING to DEBUG. With up to 498 missing keys this was very noisy; the condition is expected and harmless (library newer than checkpoint, missing params use default init).


2026-03-09 — GPU power reduction: nvidia-smi power limit + TF32 + float16 autocast

Goal: Reduce GPU power draw (and fan noise) during inference.

lyric_transcriber_service.py _apply_cuda_limits() — three additions:

  1. nvidia-smi --power-limit: Caps hardware TDP. Default 100 W (min for this GPU); override with STEMENGINE_GPU_POWER_LIMIT env var. Set to 0 to disable. Silently ignored if the driver rejects (e.g. insufficient privilege). Called once per job at limits-apply time.
  2. TF32 flags: torch.backends.cuda.matmul.allow_tf32 = True, torch.backends.cudnn.allow_tf32 = True, torch.set_float32_matmul_precision('high') — enables TF32 for matmuls on Ampere+ GPUs; imperceptible quality difference for audio, reduces compute intensity.
  3. Both are no-ops if CUDA is unavailable or the call fails.

float16 autocast added to 4 separator inference loops (enabled only when device != cpu):

  • bs_roformer_separator.py: torch.inference_mode() + torch.amp.autocast('cuda', dtype=torch.float16, enabled=(device != 'cpu'))
  • mel_band_roformer_separator.py: same
  • mel_band_specialized_separator.py: same
  • scnet_separator.py: torch.no_grad() + autocast (enabled=(device.type == 'cuda') since device is torch.device)

Autocast runs the model forward pass in float16 (halving memory bandwidth) while keeping the float32 accumulation buffers (result, counter) unaffected — PyTorch widens float16 outputs back to float32 on the += assignment automatically.


2026-03-09 — Move GPU power limit to container startup (start.sh + SYS_ADMIN cap)

Problem: nvidia-smi --power-limit requires SYS_ADMIN capability. The previous implementation called it on every job from _apply_cuda_limits(), which lacked the capability and failed silently.

Changes:

  • start.sh: Added nvidia-smi --power-limit=${STEMENGINE_GPU_POWER_LIMIT:-100} near the top. Runs once at startup as root before uvicorn. Warns (does not abort) if it fails.
  • stemengine.yml: Added cap_add: [SYS_ADMIN] so the container has the driver-level permission to write the power limit via NVML. Also added STEMENGINE_GPU_POWER_LIMIT=${STEMENGINE_GPU_POWER_LIMIT:-100} to the environment block (default 100 W; set to 0 to skip).
  • lyric_transcriber_service.py _apply_cuda_limits(): Removed the per-job subprocess call; TF32 flags and VRAM fraction cap remain.

2026-03-09 — Harden SYS_ADMIN: move privilege to init container, main container unprivileged

Problem: SYS_ADMIN in the main container persists for its entire lifetime. Any RCE or path traversal in the app could exploit it. The start.sh volume mount (writable by default) was also a vector for injecting privileged commands.

Solution — init container pattern:

  • stemengine-gpu-init service added to stemengine.yml: uses nvidia/cuda:12.1.0-base-ubuntu22.04, has cap_add: SYS_ADMIN, runs nvidia-smi --power-limit inline in its entrypoint, then exits (restart: "no"). The command is hardcoded in the compose file, not sourced from any mounted file.
  • stemengine service: cap_add: SYS_ADMIN removed entirely. Added depends_on: stemengine-gpu-init: condition: service_completed_successfully so the main container waits for the init to finish before starting.
  • start.sh mount changed to read-only (:ro) — the container can no longer overwrite the startup script.
  • start.sh: GPU power limit block removed (now handled by init container).

2026-03-09 — Fix stem rename filename format; add rescan-stems endpoint

Bug fix — rename_stem_endpoint (routers/projects.py): The rename endpoint built the new filename as f"{new_name}{ext}", producing vocals.mp3 instead of Artist - Title (vocals).mp3. Fixed to use _stem_filename(project["name"], new_name, old_path.suffix) — the same helper used during separation. The DB stem key stays as the short name (e.g. "vocals"); only the filename on disk and in the files list changes.

New endpoint — POST /api/projects/{project_id}/rescan-stems: Recursively walks ProjectDir/Stems/ and registers any audio files not already in the separation job's files list. Stem name is inferred from the filename:

  • Artist - Title (vocals).mp3 → stem key "vocals" (parenthesised suffix pattern)
  • vocals.mp3 → stem key "vocals" (fallback: use filename stem directly) Also strips a leading project-name prefix if present. Returns {"added": N, "stems": [...]}. Idempotent — already-tracked paths are skipped.

2026-03-09

Fix: ELRC not generated + Syllables not appearing when Word Timestamps disabled

Root cause: lyricTranscribeProject in frontend/src/api/client.ts computed defaultFormats based on wordTs (from localStorage stemengine-whisper-word-ts). When the user had Word Timestamps disabled (wordTs=false), defaultFormats=['lrc','txt'] — no 'elrc' — regardless of lsyncAlign. Since syllable data lives in the ELRC file, both issues (no ELRC + no visible syllables) were caused by the same missing format.

Fix: Added lsyncAlign variable and effectiveWordTs = wordTs || lsyncAlign. When lsyncAlign=true, effectiveWordTs is forced true, ensuring 'elrc' is always included in defaultFormats and word_timestamps: true is sent to the backend.

Also reverted an earlier incorrect change that added 'sylrc' to formats when lsyncAlign=true (user confirmed sylrc is not needed; phonemeAlign is no longer used).

Fix: Lyrics preview lines overflowing the karaoke preview window

Problem: Non-active lines with CSS filter (e.g. blur() in blur-style, drop-shadow() in glow-style) could bleed visually outside the containerRef boundary because overflow: hidden alone does not reliably clip CSS filter effects across all browsers. Additionally, lines were hard-cut at the container edge rather than fading smoothly.

Fix: Added two properties to containerRef in LyricsLivePreview.tsx (renderLyricsArea()):

  • clipPath: 'inset(0)' — guarantees filter bleed is hard-clipped to the container box in all browsers, even where overflow: hidden fails.
  • maskImage / WebkitMaskImage: 'linear-gradient(to bottom, transparent 0%, black 18%, black 82%, transparent 100%)' — fades lines in/out at the top and bottom 18% of the preview window so non-active lines appear to enter and exit smoothly rather than being abruptly cut off.

2026-03-10

Fix: CUDA out-of-memory errors after several separation jobs

Root cause (primary): _gpu_executor (stem separation) and _transcription_executor (Whisper/WhisperX transcription) are independent ThreadPoolExecutor(max_workers=1) instances in job_manager.py. Each serialises its own job type, but both can run simultaneously. A separator model (3–6 GB VRAM) and Whisper large-v2 (3–4 GB VRAM) loading at the same time easily exhausts available VRAM on cards ≤12 GB, producing CUDA OOM errors that surface only after several jobs (whenever separation and transcription happen to overlap).

Root cause (secondary): gc.collect() was called only once in both separator_service.py's finally block and _clear_cuda_cache(). PyTorch model objects form reference cycles (_parameters → _modules → parent → …) that Python's generational GC may not fully collect in a single pass — objects promoted to older generations require additional passes. This could leave model tensors resident in VRAM when the next job started.

Fix — backend/job_manager.py:

  • Line 112: added gpu_vram_lock = threading.Lock() — a shared VRAM coordination lock that both executor paths must hold for the duration of model loading + inference.

Fix — backend/services/separator_service.py:

  • Lines 323–326: added jm.gpu_vram_lock.acquire() (with comment) immediately before the # Run separation / try: block.
  • Lines 644–646: changed single gc.collect() to triple gc.collect() in the finally block.
  • Lines 651–655: added jm.gpu_vram_lock.release() (wrapped in try/except RuntimeError) at the end of the finally block, after empty_cache().

Fix — backend/services/lyric_transcriber_service.py:

  • Lines 859–875: _clear_cuda_cache() updated to call gc.collect() three times instead of once, with an explanatory docstring.
  • Lines 1331–1334: added jm.gpu_vram_lock.acquire() (with comment) immediately before the transcription try: block in run_lyric_transcription.
  • Lines 1859–1864: removed _clear_cuda_cache() from the except block (moved to finally).
  • Lines 1866–1874: added new finally: block (previously absent) that calls _clear_cuda_cache() and jm.gpu_vram_lock.release() on both success and failure paths.

Effect: Separation and transcription jobs now queue against the same lock. Whichever starts first holds VRAM exclusively until its finally cleanup completes, then releases the lock so the other can proceed. No model can be double-loaded simultaneously regardless of how jobs are submitted.


2026-03-10

Fix — enable_denoise keyword removed from audio-separator Separator API

Problem: Separator.__init__() got an unexpected keyword argument 'enable_denoise' raised whenever the ensemble separator ran the bs_roformer_sw model component. The audio-separator library dropped enable_denoise from its Separator.__init__ signature in a recent update.

Fix — backend/services/bs_roformer_sw_separator.py:

  • Lines 48–55: removed enable_denoise=False, normalization_threshold=0.9, and cpu_separation=self.cpu_separation from the Separator() constructor call in _get_separator(). All three parameters were dropped from the audio-separator Separator.__init__ API (≥0.28.0). Constructor now matches the pattern used by all other working separators in this codebase.

2026-03-10 — Feature — Waveform editor (Phase 1): KaraokeEditor component

New file — frontend/src/components/KaraokeEditor.tsx:

  • WaveformCanvas: fetches audioUrl, decodes with a dedicated AudioContext (separate from the existing multi-stem gain graph; closed immediately after decoding), downsamples PCM to 1200 peak values, pre-renders bars, and runs its own RAF loop to draw a playhead at (currentTimeRef.current / duration) × width. Two-color bars: played = #60a5fa, unplayed = #1e3a5f. Click-to-seek via onSeek prop.
  • KaraokeEditor: wraps the canvas with a header row showing line count and a note when waveform is unavailable (multi-stem mode with no audioUrl).

Modified — frontend/src/components/LyricsLivePreview.tsx:

  • Line 2: added Activity to lucide-react imports.
  • Line 5: added import KaraokeEditor from './KaraokeEditor'.
  • Line 801: added const [showAegisub, setShowAegisub] = useState(false).
  • Lines 2152–2161: added "Waveform editor" toolbar button (Activity icon) that toggles showAegisub and closes the other panels.
  • Lines 2243–2251: added {showAegisub && <KaraokeEditor .../>} panel rendered after the existing LrcEditor panel; receives lines, currentTimeRef, displayDuration, audioUrl ?? stems?.[0]?.url, and seekTime.

2026-03-10 — Feature — Waveform editor (Phase 2): TimingTable component

Modified — frontend/src/components/KaraokeEditor.tsx:

  • Added TimingTable sub-component: scrollable table (height 200 px) with columns #, Start, End, Text, and optional Speaker (shown only when any line has a speaker field).
  • End time derived as next line's start time, or duration for the last line.
  • Active row highlight driven by its own RAF loop reading currentTimeRef.current — no React re-renders per frame. Direct DOM color mutations on <tr> and its <td> children. scrollIntoView({ block: 'nearest', behavior: 'smooth' }) called when active index changes.
  • Row click calls onSeek(line.time) to seek audio.
  • linesRef pattern keeps the RAF closure reading the latest lines without re-subscribing.
  • Fixed: React.MouseEvent → ReactMouseEvent (imported as type alias); typed el ref callback as HTMLTableRowElement | null.

2026-03-10 — Feature — Waveform editor (Phase 3): inline timing/text editing

Modified — frontend/src/components/KaraokeEditor.tsx:

  • Added onLrcChange?: (newLrc: string) => void to KaraokeEditorProps and TimingTable props.
  • Added reconstructLrc(lines): rebuilds a full LRC/ELRC string from a LrcLineKE[] array, preserving word-level timestamps and speaker tags.
  • Added parseTs(raw): parses user-typed m:ss.xx / m:ss / m:ss.x timestamps back to seconds; returns null on invalid input (edit is silently discarded).
  • Added editing / draft state to TimingTable for the active inline edit cell.
  • Start time cell: double-click opens an inline <input> pre-filled with formatTs(line.time). On commit (Enter / blur): parses the new time, rebuilds sorted LrcLineKE[], calls reconstructLrc → onLrcChange. Word timestamps on the line are preserved.
  • Text cell: double-click opens an inline <input> pre-filled with line.text. On commit: sets words: [] for that line (drops sub-word timing), calls reconstructLrc → onLrcChange. Tooltip warns when the line has ELRC word timing.
  • Tab navigation: Tab/Shift-Tab commits the current cell and moves to the adjacent editable cell (start → text → next-row start).
  • Escape discards the edit without calling onLrcChange.
  • All inline event handler e parameters explicitly typed (ReactMouseEvent<HTMLTableCellElement>, ReactMouseEvent<HTMLInputElement>, ReactChangeEvent<HTMLInputElement>) to satisfy the project's strict noImplicitAny setting.

Modified — frontend/src/components/LyricsLivePreview.tsx:

  • <KaraokeEditor> now receives onLrcChange that calls both setEditedLrc(newLrc) and the parent's onLrcChange?.(newLrc), matching the same pattern used by LrcEditor.

2026-03-10 — Feature — Waveform editor (Phase 4): zoom, line markers, arrow-key navigation

Modified — frontend/src/components/KaraokeEditor.tsx:

Waveform zoom + scroll:

  • WaveformCanvas gains lines prop for marker rendering.
  • Replaced drawWaveform/drawEmpty with a unified drawFrame(ctx, peaks, lines, w, h, fraction, zoom, scrollFrac, duration, activeLineIdx) that handles all zoom/scroll/marker logic in one pass.
  • zoom and scroll stored as both React state (drives controls re-render) and refs (read by RAF loop with zero re-render overhead). dirtyRef force-triggers a redraw whenever zoom or scroll changes.
  • Ctrl+scroll (or Cmd+scroll) zooms in/out up to 32×, centred on the mouse cursor position (anchor-preserving zoom math).
  • Plain scroll pans the waveform horizontally when zoomed in. Shift+scroll or horizontal deltaX also pans.
  • + / − buttons (top-right canvas overlay) snap zoom to the next/previous power of 2. ✕ resets to 1×.
  • Horizontal scrollbar (<input type="range">) appears below the canvas only when zoomed in; its max tracks 1 − 1/zoom so it can never scroll past the end.
  • handleClick updated to account for zoom and scroll when mapping canvas x to seek time.

Line-start markers:

  • Each lyric line gets a 1 px vertical tick at the top of the canvas at its start timestamp.
  • Active line marker: 10 px tall, rgba(96,165,250,0.9) (blue-400). Inactive: 5 px tall, rgba(100,116,139,0.55) (slate-500). Computed fresh each RAF frame from findActiveLine.

Arrow-key navigation (in KaraokeEditor):

  • useEffect attaches a keydown listener on document while the editor is mounted.
  • ArrowLeft → seek to the previous line's start time; ArrowRight → seek to the next line's start time.
  • Skipped when the active element is an INPUT, TEXTAREA, or SELECT (so inline cell editing is unaffected).
  • Reads linesRef.current so it never needs to re-subscribe when lines change.

2026-03-10 — Feature — Syllable/word timing editor (Phase 5, Steps A–C)

Modified — frontend/src/components/KaraokeEditor.tsx (only file changed):

Step A — Expandable word sub-rows in TimingTable:

  • Added TimingTableProps interface extending the existing props with expandedRow, onExpandRow, onWordTimeChange.
  • Lines with words.length > 0 show a ▶/▼ toggle in the # column. Clicking the cell expands/collapses without triggering a seek.
  • Word sub-rows render below the parent line using <Fragment key={i}>, with amber left border (rgba(251,191,36,0.3)). Columns: indent └ | Start (editable) | End (read-only) | Text (read-only).
  • Word start time editing uses the same double-click → <input> → Enter/blur/Escape/Tab flow as line editing, with amber wordInputStyle.
  • Word times clamped on commit: [line.time … nextWord.time − 0.01s]. Tab moves between word cells.
  • expandedRow state and handleWordTimeChange live in KaraokeEditor; commits via reconstructLrc → onLrcChange.

Step B — Word markers on waveform:

  • Added WORD_MARKER_COLOR (amber-400/70), WORD_MARKER_DRAG_COLOR, WORD_MARKER_HIT_PX = 8.
  • drawFrame gained optional wordLine and dragPreview params. New drawing pass: 2 px × 14 px amber ticks per word; drag preview word shows WORD_MARKER_DRAG_COLOR.
  • WaveformCanvasProps interface added with selectedLineIdx and onWordTimeDrag. Added selectedLineIdxRef, dragStateRef, dragPreviewRef refs. RAF loop passes wordLine and dragPreviewRef.current to drawFrame.

Step C — Drag-to-retime:

  • Removed handleClick/useCallback; replaced with a pointer-event useEffect (pointerdown/pointermove/pointerup). canvas.setPointerCapture keeps events during drag outside the canvas.
  • onPointerDown: near a word marker → start drag. Otherwise → background click.
  • onPointerMove: if dragging → update dragPreviewRef + dirtyRef = true (no React re-renders). If not → set cursor ew-resize near a marker, crosshair otherwise.
  • onPointerUp: if moved → clamp + commit via onWordTimeDrag; else → seek click.
  • handleWordTimeDrag(wordIdx, newTime) in KaraokeEditor delegates to handleWordTimeChange(expandedRow, wordIdx, newTime).

Documentation updated — Lyrics Editor Overview.md:

  • Added "Word / Syllable Timing" section, updated keyboard reference.

2026-03-10 — Fix — KaraokeEditor scrollbar color bleedover

Modified — frontend/src/components/KaraokeEditor.tsx:

  • Removed accentColor: '#60a5fa' from the horizontal scrollbar <input type="range"> inline style.
  • index.css already applies appearance-none and bg-brand-500 (CSS variable) to all input[type="range"] elements globally, so the hardcoded hex was both redundant and a violation of the theming system. The thumb now correctly follows the active accent color.

2026-03-11 — StemEngine WebUI redesign plan (MetroUI)

Created — StemEngine WebUI.md: High-level plan to redesign the StemEngine React frontend using MetroUI (@olton/metroui), replacing Tailwind CSS. Covers installation, design language decisions, layout shell changes (AppBar + SideNav), page-by-page redesign (Separator, ProjectDetail, Settings, Sidebar, GlobalAudioBar), Metro Live Tile project browser, 6-phase migration order, ThemeContext data-theme/data-accent attribute changes, components that must NOT be touched (KaraokeEditor, LyricsLivePreview internals), and risk notes (MetroUI JS + React event system, data-role auto-init in dynamic React renders, Vite side-effects config).

2026-03-11 — KaraokeEditor Phase 5 bug fixes + word row highlight

Modified — frontend/src/components/KaraokeEditor.tsx:

Bug fix — pointer events useEffect deps: The [duration, onSeek, onWordTimeDrag] dependency array caused the pointer event listeners on the waveform canvas to be torn down and re-added on every render (since onWordTimeDrag/onSeek are new function references each render of KaraokeEditor). Fixed by adding stable onSeekRef, onWordTimeDragRef, durationRef inline-updated refs in WaveformCanvas and reading from these inside the pointer event closures. Deps changed to [] — listeners registered once for the canvas lifetime.

Bug fix — waveform not redrawing on expand: When expandedRow changed (line expanded or collapsed), dirtyRef.current was never set, so the word markers didn't appear/disappear until the next playhead movement frame. Fixed by adding useEffect(() => { dirtyRef.current = true }, [selectedLineIdx]) in WaveformCanvas.

Feature — word sub-row highlight on click: Clicking a word sub-row in the timing table now applies an amber (rgba(251,191,36,0.12)) background highlight to that row (direct DOM mutation, no re-render). Clicking a different word row moves the highlight; the highlight clears automatically when the active line changes during playback (RAF loop). Implemented via wordRowRefsMap (keyed ${lineIdx}-${wordIdx}), activeWordRowRef, and highlightWordRow() helper in TimingTable.

2026-03-11 — Karaoke renderer Two.js rewrite plan

Created — Karaoke Renderer (Two JS).md: Plan to replace the DOM/CSS+RAF lyrics rendering layer of LyricsLivePreview with a Two.js SVG scene graph. Covers: scope (only the lyrics display window; audio, controls, settings, KaraokeEditor all untouched); why Two.js (native SVG clipPath word fill, scene-graph Z-ordering for stroke/shadow layering, per-object SVG filters for glow/blur, renderer-agnostic API); recommended SVG renderer with Canvas2D fallback; full scene graph structure (bgRect, fadeTop/Bottom gradient rects, linesGroup with per-line lineGroup containing wordsGroup / wordUnit / wordText_behind / wordText_front + clipPath); SVG clipRect injection technique (not part of Two.js public API, via _renderer.elem); word metrics computation via hidden canvas measureText with font-keyed cache; style mode mappings (scroll/fade/karaoke/glow/blur); speaker dot circles; React integration pattern (LyricsCanvas component with useEffect mount, two.bind('update') for RAF, ResizeObserver for resize, useEffect for style prop changes); 6 implementation phases; and risk notes (clipPath injection stability, font loading timing, HiDPI, StrictMode double-mount, long-song virtualisation, Safari feGaussianBlur performance).

2026-03-11 — StemEngine WebUI.md updated: LyricsLivePreview MetroUI scope

Updated — StemEngine WebUI.md: Added LyricsLivePreview as a component that also receives MetroUI treatment. The plan now distinguishes two layers: (1) the lyrics rendering canvas (RAF/Two.js — NOT touched by MetroUI) and (2) the surrounding UI shell (transport controls, style picker, speaker management, LRC editor — all reskinned with MetroUI). New section added with ASCII layout diagram, full MetroUI component mapping (radio tiles for style mode, sliders for seek/ volume/font-size/shadow, color-picker for accent colours, switch for stroke/shadow toggles, listview for speakers, Metro textarea for LRC editor). Phase 4 note updated to reflect only the outer panel shell changes; new Phase 7 added for the full LyricsLivePreview UI shell reskin. "What Does NOT Change" table split into rendering canvas (unchanged) and UI shell (changes in Phase 7).

2026-03-11 — MetroUI Phase 1: install + app shell

Backup created — frontend-backup/: Full copy of frontend/ (excluding node_modules) at /home/translator/docker/appdata/stemengine/frontend-backup/.

Modified — frontend/package.json: Added "@olton/metroui": "^5.1.20" to dependencies. Installed automatically on next container start via npm install --prefer-offline in start.sh. Tailwind packages kept — removed in Phase 6.

Modified — frontend/src/main.tsx: Added MetroUI CSS imports after index.css:

import '@olton/metroui/dist/css/metro.css'
import '@olton/metroui/dist/css/icons.css'

MetroUI JS not imported yet (not needed until JS-initialised components are used in later phases).

Modified — frontend/src/context/ThemeContext.tsx: Added root.setAttribute('data-theme', r) alongside the existing classList.add/remove('dark'). Both Tailwind dark mode (.dark class) and MetroUI dark mode (data-theme="dark") are now set simultaneously, so Tailwind inner pages and the new MetroUI shell both honour the user's theme.

Modified — frontend/src/index.css: Added migration comment block explaining coexistence of Tailwind + MetroUI. Tailwind @tailwind directives kept — removed in Phase 6.

Modified — frontend/src/App.tsx: Rewrote AppShell JSX to use MetroUI app-bar structure. Key changes:

  • Outer div uses inline flex styles (no Tailwind)
  • <header> uses MetroUI app-bar / app-bar-brand / app-bar-item ml-auto classes
  • Brand logo: gradient square icon + StemEngine wordmark in MetroUI flat button
  • GPU status button: MetroUI button cycle flat, with accent colour for error state
  • Settings button: MetroUI button cycle flat, highlighted with accent hex when active
  • Accent gradient line (3 px) above app-bar using --brand-500 CSS variable
  • Inner pages (Separator, ProjectDetail, Settings, Sidebar, GlobalAudioBar) completely untouched — still render with their existing Tailwind classes
  • Phase annotations in comments mark what is migrated in which future phase

2026-03-11

MetroUI Phase 2 — Sidebar redesign (Sidebar.tsx)

File: frontend/src/components/Sidebar.tsx

All business logic (React Query queries, state, handlers) identical to the Tailwind version. Only the JSX and class names were changed.

Key changes:

  • Outer <aside> uses inline styles + sidebar-open/sidebar-closed CSS classes (from index.css) — no Tailwind layout classes
  • Toggle button: MetroUI button cycle flat with circular inline style
  • Active jobs accordion: React state jobsOpen controls open/close; header uses a shared sectionHeaderStyle object (inline styles matching Metro section headers); amber badge count
  • ActiveJobItem: inline styles replacing Tailwind card; MetroUI button cycle flat for cancel button; Lucide StatusDot icons styled with var(--color-*) CSS variables
  • ProjectTile (replaces ProjectItem): inline-styled row with hover state via useState(hovered), brand-accent border/background when isOpen, MetroUI button cycle flat for delete; opacity-based reveal on hover
  • SubsonicPanel accordion: React state open; same sectionHeaderStyle header with var(--color-blue) accent; native <input> styled with inline border/background; search button styled inline with var(--color-blue) background
  • ImportedFileRow extracted as separate component to enable hover state for action buttons
  • Collapsed strip: Lucide icons + count badges using inline var(--color-gray) — no Tailwind
  • data-role attributes deliberately avoided throughout to prevent MetroUI JS DOM conflicts with React's virtual DOM; all accordion behavior is React-state-controlled
  • var(--border-color), var(--background), var(--body-background), var(--color-*) MetroUI CSS variables used for theme-aware colours (light/dark respected automatically via data-theme set by ThemeContext)

2026-03-11 (continued)

MetroUI Phase 3 — Separator page + FileUpload

Files:

  • frontend/src/pages/Separator.tsx
  • frontend/src/components/FileUpload.tsx

All business logic (state, queries, effects, handlers) unchanged. Tailwind replaced with MetroUI CSS classes + inline styles. Sub-components JobStatus and ResultFiles left unchanged (still Tailwind, to be migrated in Phase 4+).

Key changes — FileUpload.tsx:

  • Replaced Tailwind class string with inline style object
  • Added React dragOver state for visual drag-over feedback (accent border colour + light tint)
  • onDragLeave handler added to clear drag state

Key changes — Separator.tsx:

  • Removed SELECT_CLS, INPUT_CLS, SLIDER_CLS Tailwind string constants; replaced with fieldLabel, ctrl, card CSSProperties objects at module level
  • Page header: inline h2/p styles
  • Input-mode toggle: flex segmented button pair — active button gets accentColor background (upload) or var(--color-blue) (imported)
  • Selected file indicator: card style with brand accent border
  • Imported files empty state: dashed-border div with centered icon + text
  • ImportedFileButton extracted as separate function (for hover state); active selection shows accent left-border + tinted background
  • Model/format grid: CSS grid (3 columns) with ctrl styled native <select> elements
  • BS-RoFormer info box: violet-tinted border + background
  • Project name: ctrl styled <input type="text">
  • Preset type: ctrl styled <select> + description text
  • Static options panel: card style with ctrl select
  • Dynamic options panel: card style; native <input type="range"> sliders; percentage readout
  • Preset preview: brand-tinted border box with <code> pre-formatted structure
  • Submit: MetroUI button primary class, full-width
  • Auto Pipeline: inline amber-bordered/tinted button
  • Success result box: green-tinted border inline
  • JobStatus and ResultFiles still use Tailwind internally — visually mixed until Phase 4

2026-03-11

Phase 4 — MetroUI CSS migration: ProjectDetail.tsx

Replaced all targeted Tailwind CSS classes in frontend/src/pages/ProjectDetail.tsx with MetroUI classes and inline style={{}} objects. No business logic, state, handlers, or out-of-scope functions were touched.

Changes made (13 edits + 2 cleanup passes):

  1. STEM_COLORS — Changed from Tailwind class strings to { bg, border, color } objects using RGBA/CSS-var theme colors.
  2. JobBadge — Replaced Tailwind span with inline style using MetroUI CSS vars (--color-green, --color-amber, --color-red, --border-color).
  3. DownloadButton — Replaced anchor classes with className="button flat" + inline style.
  4. StemChipButton — Replaced Tailwind-colored anchor with fully inline style using the new STEM_COLORS object.
  5. StemReprocessButton (return JSX) — Replaced relative wrapper, trigger button, dropdown panel, family tabs, model list, and cancel button with button flat / button cycle flat classes and inline styles using --border-color, --body-background, --background.
  6. StemRenameButton — Replaced editing input and action buttons with inline styles and button cycle flat classes; normal state uses button cycle flat.
  7. StemsSection header and list — Replaced collapsible header and stem-row cards with inline styles; accent color via rgb(var(--brand-500, 59 130 246)).
  8. MixesSection header — Replaced collapsible header with inline-style flex layout.
  9. MixesSection sub-tabs, generate buttons, error/result box — Replaced all Tailwind with inline styles; generate button uses className="button".
  10. MidiSection header — Replaced with violet-colored inline-style header using --color-violet.
  11. AbcSection header — Replaced with green-colored inline-style header using --color-green.
  12. LyricsSection header — Replaced with sky-blue inline-style header using --color-blue.
  13. Main ProjectDetail export — Replaced loading spinner, error state, header, delete button, and all section wrappers with inline styles and MetroUI button classes.
  • Cleanup: Replaced 2× bulkErr Tailwind paragraphs and 3× "no items" italic paragraphs with inline styles. Two remaining occurrences (inside StemAbcRow and StemLyricsRow) were left untouched per scope rules.

Phase 5 — MetroUI CSS migration: Settings.tsx

Replaced all remaining Tailwind CSS classes in frontend/src/pages/Settings.tsx with inline style={{}} objects using MetroUI CSS variables. Changed the tab navigation from a horizontal pill bar to a vertical left-side sidebar nav. No business logic, state, or handlers were changed.

Components migrated (5 edits):

  1. Toggle — Replaced Tailwind translate-x/bg-brand-500/bg-slate-300 with a fully inline animated switch using rgb(var(--brand-500)) and var(--border-color); added type="button", role="switch", aria-checked.
  2. MaintenanceSettings — Replaced space-y-8, flex items-center gap-3 pb-4 border-b, icon wrapper p-2 bg-slate-100 rounded-lg, and space-y-3 list with inline flex/gap/border styles matching the shared sHdr/sCard pattern.
  3. PowerSettings — Removed btnBase/btnActive Tailwind class strings; replaced header, GPU banner, VRAM tier card grid (with active/disabled states), and AI Transcription toggle rows with inline styles using rgb(var(--brand-500)), var(--color-green), var(--color-red), var(--border-color).
  4. IntegrationsSettings — Replaced space-y-8 outer wrapper, flex items-center gap-3 pb-4 border-b header, all className inputs/buttons (including password field, Save, Remove) with inline styles; MetroUI button primary class used for Save; status messages use var(--color-green) / var(--color-red).
  5. Settings (main export) — Removed horizontal pill tab bar (hidden sm:flex, sm:hidden mobile select). Replaced with a vertical sidebar nav (176 px wide, flex-col gap-2) alongside a content panel in a two-column flex layout. Active nav item uses rgba(var(--brand-500), 0.1) background and brand color text. Added ElementType to react type import to replace React.ElementType reference.

CSS vars used throughout: --border-color, --body-background, --background, rgb(var(--brand-500, 59 130 246)), var(--color-green), var(--color-amber), var(--color-red).


Phase 6 — GlobalAudioBar reskin + Tailwind audit

GlobalAudioBar.tsx — Full reskin per Phase 6 spec:

  • Outer strip: position: fixed bottom with var(--border-color) top border, var(--body-background) background, backdrop-filter: blur.
  • Play/Pause: replaced Tailwind rounded-full + bg-brand-500 with inline rgb(var(--brand-500)) circle; MetroUI button cycle class kept.
  • Time spans, seek slider, volume slider: all inline styles; accentColor uses rgb(var(--brand-500)).
  • Mute and dismiss buttons: MetroUI button cycle flat.
  • Tailwind className fully removed from the component.

Tailwind remnant sweep — All previously-migrated components audited and cleaned:

  1. App.tsx — Removed className="sm:hidden" from mobile backdrop div (now pure inline style); replaced max-w-3xl mx-auto px-2 sm:px-4 py-4 sm:py-6 + rounded-2xl border border-slate-200 ... wrapper with inline styles using var(--border-color) and var(--body-background); replaced Tailwind <footer> classes with inline style; moved ml-auto from className to inline marginLeft: 'auto'.

  2. JobStatus.tsx — Full rewrite of the render: all className="flex items-center gap-2 text-xs text-red-500" etc. replaced with shared row style object + CSS vars (var(--color-red), var(--color-green), var(--color-amber), brand color); truncate replaced with inline overflow: hidden, textOverflow: ellipsis; animate-spin removed (Tailwind animation — icon unchanged, class dropped).

  3. ResultFiles.tsx — Replaced space-y-2 wrapper, anchor Tailwind link row, and Download icon classes with inline styles; anchor uses MetroUI button flat class + inline border style.

  4. SettingsPanel.tsx — Full rewrite: modal overlay, backdrop, panel shell, header, theme toggle buttons, Full Settings row, and description text all converted to inline styles + CSS vars; close button uses MetroUI button cycle flat.

  5. DynamicMixPlayer.tsx — Replaced space-y-3, flex flex-wrap, play button (rounded-full bg-brand-500), seek/volume range sliders (accent-brand-500), master volume section, and stem M/S buttons + sliders with inline styles; mute button uses MetroUI button cycle flat; M/S active states use var(--color-red) / var(--color-amber).

  6. AutoPipelineDialog.tsx — Full rewrite of the fixed bottom-right dialog: outer shell, header (Zap amber icon), body (project name input, pipeline step rows, live progress step list, error/success banners), footer (Dismiss/Cancel + Run Pipeline/Close buttons) all converted to inline styles; StepIcon colors use CSS vars; MetroUI button primary for Close; amber background for Run button.

  7. Settings.tsx — Fixed getStatusIcon() helper: replaced w-4 h-4 text-green-500 etc. Tailwind icon classNames with inline style + CSS vars.

Excluded from Phase 6 sweep (per plan):

  • LyricsLivePreview.tsx — Phase 7 scope.
  • KaraokeEditor.tsx — explicitly excluded (canvas engine, never to be reskinned).
  • ProjectDetail.tsx — was Phase 4; a handful of sub-row classNames (StemAbcRow, StemLyricsRow) remain per Phase 4 scope notes.

Post-sweep status: grep className= on all non-excluded TSX files returns only MetroUI class names (button, button cycle flat, button primary, button flat, app-bar, app-bar-brand, app-bar-item, sidebar-open/closed, icon). Zero Tailwind utility classes remain in the migrated scope.


Phase 6 — Bug fixes (post-migration)

Three regressions introduced in Phase 6 corrected:

  1. Sidebar overlay blocking clicks — Removing sm:hidden from the mobile backdrop div caused it to render on all screen sizes, blocking content on desktop. Restored className="sm:hidden" since Tailwind is still active.

  2. Dark mode not switching — Components now rely on var(--body-background), var(--border-color) etc. instead of Tailwind dark: classes. These CSS custom properties were only being set if MetroUI's own CSS defined them under [data-theme="dark"]. ThemeContext.tsx updated to explicitly set all required CSS variables via root.style.setProperty(...) in the apply() function, guaranteeing correct values for both themes regardless of MetroUI's internal CSS. Light values: --body-background: #ffffff, --border-color: #e2e8f0, etc. Dark values: --body-background: #0f172a, --border-color: #334155, etc. Semantic colors (--color-green, --color-red, --color-amber, --color-blue, --color-violet, --color-teal) set once (theme-neutral).

  3. VRAM tier card text overflow — Card <button> elements in PowerSettings had no width constraint or overflow control, causing description text to bleed across adjacent cards. Added width: '100%', minWidth: 0, overflow: 'hidden', boxSizing: 'border-box' to the button, and overflowWrap: 'break-word', wordBreak: 'break-word', width: '100%' to the description <span>.


UI Fix plan — created StemEngine UI Fix.md

Full audit of remaining Tailwind/dark-mode/mobile issues. Plan file saved at /home/translator/docker/appdata/stemengine/StemEngine UI Fix.md.

UI Fix #1 — MaintenanceCard accent colours (Settings.tsx)

Replaced the unused iconBg / iconColor Tailwind string props with a single accent prop ('blue' | 'purple' | 'amber' | 'cyan' | 'green' | 'red'). Added MAINTENANCE_ACCENT map using RGBA tokens (theme-neutral — same tint works on both light and dark backgrounds). Fixed a second latent bug: the outer card <div> was using bare sCard (no flex), so the icon and content were stacked vertically instead of side-by-side. Changed to { ...sCard, display: 'flex', gap: 12, alignItems: 'flex-start' }. Updated all six <MaintenanceCard> call-sites to pass accent="...". Zero Tailwind or dark: references remain in MaintenanceSettings.

UI Fix #2 — index.css scrollbar + range input

Replaced all @apply dark:* blocks with plain CSS reading from ThemeContext custom properties. Scrollbar thumb: background: var(--border-color) + color-mix() hover darkening. Range inputs: kept appearance: none (full cross-browser thumb control); added explicit height: 6px — without it the track collapses to ~0 px tall under appearance: none. Thumb 14 × 14 px, background: rgb(var(--brand-500)). No accent-color found anywhere in components (confirmed via grep) so nothing to remove.

UI Fix #4 — Settings mobile nav (Settings.tsx)

Added isMobile state (window.innerWidth < 640) with a resize event listener in the main Settings export. The component now renders two distinct layouts:

  • Mobile (< 640 px): outer div is flex-col, height: 100%. A horizontally scrollable <nav> strip sits at the top (overflowX: auto, scrollbarWidth: none, borderBottom). Each tab button is flex-col (icon above label), flexShrink: 0, whiteSpace: nowrap, to prevent wrapping and allow horizontal scroll. Below it, a flex: 1, overflowY: auto div holds the content at padding: 16px.
  • Desktop (≥ 640 px): original two-column layout (176 px vertical nav + card-bordered content panel) unchanged.

The active style object (activeStyle) and the content JSX block are extracted once and shared between both render paths to avoid duplication. No Tailwind classes used.

UI Fix #3 — GlobalAudioBar dark mode background

ThemeContext.tsx: added --bar-background CSS var — rgba(15,23,42,0.92) dark / rgba(255,255,255,0.92) light. This is the semi-transparent variant needed so backdropFilter: blur() actually produces a frosted-glass effect (blur has no visible effect on a fully opaque background). GlobalAudioBar.tsx: swapped background: var(--body-background) → var(--bar-background), increased blur radius to 12 px. Also removed two dead accentColor inline properties from the seek and volume <input type="range"> elements — accent-color is silently ignored when appearance: none is set (fixed in #2).

Phase 7 plan — created StemEngine WebUI Phase 7.md

Full audit of Sidebar.tsx and AutoPipelineDialog.tsx. Both are already fully on inline styles and MetroUI classes — zero Tailwind utility classes in their JSX. The remaining Phase 7 work is 3 edits across 2 files: (1) index.css @layer base → plain CSS; (2) index.css sidebar @layer utilities + @apply w-72/w-14 + theme() calls → plain rem values; (3) ThemeContext.tsx add --label-color and --color-gray vars (referenced in Sidebar but not previously set). @tailwind directives remain until Phase 11 (Separator/KaraokeEditor/etc. still depend on them).

start.sh + vite.config.ts — WSL2 watch polling fix (corrected)

Problem: vite build --watch uses chokidar inotify-based watching, which does not receive events from WSL2 host → Docker bind-mount writes. Source edits were silently ignored; the frontend never rebuilt.

First attempt (reverted): Added build.watch: { chokidar: { usePolling: true } } to vite.config.ts. This was wrong: any non-null build.watch in the static config enables watch mode for ALL vite build runs, including the blocking initial build in start.sh. The initial build never exited, uvicorn never started, and the frontend became inaccessible.

Correct fix: Reverted vite.config.ts to its original state (no build.watch). Set CHOKIDAR_USEPOLLING=1 CHOKIDAR_INTERVAL=800 as environment variables on only the background watch line in start.sh:

CHOKIDAR_USEPOLLING=1 CHOKIDAR_INTERVAL=800 npx vite build --watch 2>&1 &

Chokidar reads these env vars natively. The initial blocking vite build is unaffected. Requires one container restart to take effect.

Dark mode text colour fix

Root cause: ThemeContext was setting background/border CSS vars explicitly, but not text colour. MetroUI's own body { color: #333 } (un-layered, loaded after index.css) was winning in the cascade, keeping text dark in dark mode.

First attempt (didn't work): Added --foreground CSS var to ThemeContext and color: var(--foreground) inside @layer base in index.css. Styles inside @layer base have lower cascade priority than un-layered MetroUI rules — MetroUI's body color kept winning.

Correct fix:

  • ThemeContext.tsx: set document.body.style.color directly in apply(). An inline style on <body> beats all stylesheet rules regardless of load order. Also sets --foreground (#e2e8f0 dark / #1e293b light) and --foreground-muted (#94a3b8 dark / #64748b light) as CSS vars for components that need explicit colour references. Added --label-color and --color-gray to the same block.
  • index.css: removed the color: var(--foreground) line from @layer base (redundant).

Dark mode — MetroUI class overrides (theme-overrides.css)

Root cause: MetroUI CSS is un-layered and loaded after index.css. Un-layered rules beat @layer utilities (Tailwind dark: classes), so MetroUI's own light-mode button, app-bar, input etc. kept winning in the cascade. Result: MetroUI-classed elements and unmigrated Tailwind inputs stayed white in dark mode.

Fix: Created frontend/src/theme-overrides.css, imported in main.tsx immediately after metro.css. Its un-layered rules come last in the cascade, overriding MetroUI's own defaults for dark mode.

  • .dark .app-bar / [data-theme="dark"] .app-bar → background: var(--sidebar-background)
  • .dark .button:not(.primary):not(.secondary) → background: var(--background), border-color: var(--border-color), color: var(--foreground)
  • .dark .button.flat, .dark .button.cycle.flat → background: transparent, hover tint rgba(255,255,255,0.06)
  • .dark input/select/textarea → background: var(--background), color: var(--foreground) (excludes range/checkbox/radio/color inputs; inline styles on already-migrated elements still win)
  • .dark .card / .dark .panel → dark surface for any MetroUI card/panel elements

App.tsx: Added style={{ background: 'var(--sidebar-background)', borderBottom: ... }} directly on div.app-bar so it switches on first render before ThemeContext fires.

Affected: app bar, Reprocess buttons, collapse arrows (ProjectDetail), LiveLyric Preview buttons, transcript textarea.

Dark mode — Tailwind bg-white / pre / text-slate-* overrides

Problem: bg-white dark:bg-gray-900 on div and pre elements in unmigrated components (Live Preview headers, Transcript panel, Subsonic rows, ABC text view) was still rendering white in dark mode. Tailwind's @layer utilities has lower cascade priority than un-layered CSS, so even the .dark .dark\:bg-gray-900 override (which has higher specificity than .bg-white) was losing to MetroUI's un-layered element resets.

Fix: Added un-layered rules to theme-overrides.css (loaded after MetroUI):

  • .dark .bg-white → background: var(--background)
  • .dark .bg-slate-50 → background: var(--body-background)
  • .dark .bg-slate-100 → background: var(--background)
  • .dark pre → background: var(--body-background), color: var(--foreground)
  • .dark .text-slate-600/700/900 → color: var(--foreground)
  • .dark .text-slate-400/500 → color: var(--foreground-muted)
  • .dark .border-slate-200/300 → border-color: var(--border-color)

Mobile Settings nav — icon-only, 20px

Mobile tab strip in Settings.tsx updated: removed text labels from mobile buttons (icon only), increased icon from 16×16 to 20×20 px, changed layout from flex-col to flex centered, added title={label} for accessibility. Desktop nav unchanged.

Card padding increases

  • VRAM tier cards (PowerSettings): padding: 12 → padding: '14px 16px' — more horizontal breathing room
  • Font picker tiles (AppearanceSettings): padding: '8px 16px' → padding: '12px 16px' — more vertical space above/below the Aa sample

2026-03-11

Phase 7 — Remove Tailwind @apply / theme() from index.css

Edit 1 (@layer base → plain CSS):

  • Replaced @layer base { html { @apply h-full } body { @apply h-full antialiased } #root { @apply h-full } } with html, body, #root { height: 100%; } + explicit font-smoothing declarations

Edit 2 (@layer utilities + theme() → plain rem):

  • .sidebar-open: @apply w-72 → width: 18rem
  • .sidebar-closed: @apply w-14 → width: 3.5rem
  • Media query: theme('spacing.72') → 18rem, theme('spacing.10') → 2.5rem

Edit 3 (ThemeContext — already done in prior session): --label-color and --color-gray CSS vars added

Transcript panel dark mode fix (ProjectDetail.tsx)

  • Speaker diarization container (line ~2114): removed bg-white dark:bg-gray-950, added style={{ background: 'var(--body-background)', color: 'var(--foreground)' }}
  • Plain transcript <pre> (line ~2138): same treatment — inline CSS vars replace Tailwind dark-mode classes

MetroUI button hover popup dark mode (theme-overrides.css)

Added rules for:

  • .dark .button.cycle:hover — rgba(255,255,255,0.06) subtle highlight
  • .dark .button:hover::before/::after — dark background on pseudo-element overlays
  • .dark .info-box, .dark .metro-dropdown, .dark .dropdown-menu — dark surface for MetroUI popup panels

Form fields dark mode (ProjectDetail.tsx)

  • Added fieldStyle constant: { background: 'var(--background)', color: 'var(--foreground)', borderColor: 'var(--border-color)' }
  • Applied style={fieldStyle} to all 10 select/input/textarea elements with bg-white dark:bg-gray-9xx Tailwind classes — inline styles beat MetroUI/Tailwind cascade
  • Converted container divs (log body, ABC header) to style={{ background: 'var(--background/body-background)' }}
  • Converted Sheet/Text toggle buttons to use conditional style= objects instead of conditional Tailwind bg classes

Browser native tooltip / OS chrome dark mode (ThemeContext.tsx)

  • Added root.style.colorScheme = r — tells the browser to render native UI elements (title= tooltips, scrollbars, select arrows, checkboxes) in dark OS theme when dark mode is active

2026-03-12

Form control dark mode — root cause found and fixed (theme-overrides.css)

  • Root cause: MetroUI's un-layered select { background: var(--input-background) } (light: #fff, dark: #2b2d30) was winning over our CSS rules and in some cases over inline styles due to cascade position.
  • Fix: added !important to the form control block in theme-overrides.css:
    • background: var(--background) !important — forces ThemeContext's dark/light value regardless of MetroUI
    • color: var(--foreground) !important
    • border-color: var(--border-color) !important
    • color-scheme: dark — forces OS-native chrome (dropdown arrow, scrollbar) to dark theme
  • Added colorScheme: 'inherit' to fieldStyle in ProjectDetail.tsx and to ctrl in Separator.tsx
  • Added <meta name="color-scheme" content="light dark"> to index.html

LyricsLivePreview tab bar dark mode (LyricsLivePreview.tsx)

  • Tab bar container: replaced dark:bg-gray-800/80 dark:border-gray-700/50 Tailwind classes with inline style={{ background: 'var(--background)', borderColor: 'var(--border-color)' }}
  • All tab/icon buttons: replaced dark:text-gray-400 dark:hover:bg-gray-700 Tailwind classes with inline style={{ color: 'var(--foreground-muted)' }} and added lp-btn CSS class
  • Active state buttons: inline style={{ background: 'rgb(var(--brand-500))', color: '#fff' }}
  • Added .lp-btn:hover { background: rgba(128,128,128,0.15) } to theme-overrides.css

Sidebar toggle button visibility (Sidebar.tsx)

  • Toggle button positioned at right: -14 (half outside sidebar) was clipped by overflow: hidden on the <aside>
  • Fix: changed aside overflow: 'visible'; wrapped the collapsed icon strip in its own overflow: hidden div (expanded content already had its own overflow: hidden)

Frontend swap — restored Tailwind UI as active frontend

  • frontend (MetroUI migration) → renamed to frontend-backup (metroui)
  • frontend-backup (tailwind) (original) → renamed to frontend (now active)
  • Container restart required to rebuild from restored Tailwind frontend

Security: purge legacy plaintext Subsonic config at startup (main.py)

  • Added _purge_legacy_subsonic_config() — deletes subsonic.json if it exists without _enc: True (legacy plaintext format written before encryption was added)
  • Encrypted configs (_enc: True) are left untouched
  • Wired via FastAPI lifespan context manager so it runs once at process startup
  • Logs a WARNING when a legacy file is removed so the operator knows to re-enter credentials in the Settings UI

2026-03-12

Karaoke refactor WIP — Two.js SVG renderer scaffolding

Created /home/translator/docker/appdata/stemengine/frontend-karaoke-wip/ by rsyncing frontend/ (excluding node_modules/dist). Implemented all plan steps 0–10 in the WIP directory only; live frontend/ is untouched.

Files created/modified in WIP:

  • package.json — added "two.js": "^0.8.12" to dependencies. @types/two.js does not exist on npm so no types package was added; Two.js internals are accessed via as any casts in the renderer.
  • src/utils/svgUtils.ts (new) — raw SVG DOM helpers: ensureDefs, injectClipPath, removeClipPath, injectFilter, applyClipPath, applyFilter. Only file touching _renderer.elem internals.
  • src/components/LyricsCanvas.tsx (new) — Two.js SVG lyrics renderer component. Implements a scene-graph approach with buildScene, activateLineGroup, updateWordFills, and updateScene. Uses currentTimeRef for zero-re-render playback tracking. Supports all five visual styles (scroll/fade/karaoke/glow/blur) and word-level clip-path sweep animation.
  • src/components/LyricsLivePreview.tsx (modified) — added import LyricsCanvas from './LyricsCanvas'; replaced the scrollDivRef div + five render*Style() calls in renderLyricsArea() with a single <LyricsCanvas> instance. Cover art overlay, container div, and maskImage CSS are preserved untouched. Old render functions retained for review (Step 11 not implemented per plan).

Type mapping note: LyricsCanvas.StyleState uses activeColor while LyricsLivePreview.StyleState uses wordHighlight/highlightColor. The <LyricsCanvas style={...}> prop in renderLyricsArea maps style.wordHighlight → activeColor and effectiveBg → bgColor.


2026-03-12

Karaoke refactor — code review and bug fixes in frontend-karaoke-wip

Reviewed all files created in the previous session. Three bugs identified:

Bug 1 (critical, fixed): LyricsCanvas.tsx line 528 — styleRef.current (the StyleState value) was passed to updateScene where React.MutableRefObject<StyleState> was expected. updateScene then called .current on the plain object → undefined → crash on first RAF tick. Fixed: changed styleRef.current as any → styleRef as any.

Bug 2 (visual, fixed): updateScene computed targetSc (scale target per line) but never applied it. Added record.group.scale = lerp(curSc, targetSc, LERP_FACTOR) so inactive lines smoothly shrink to 0.92× and the active line lerps back to 1.0×.

Bug 3 (visual, fixed): The blur style previously injected a single shared <filter id="blur-inactive"> and the per-line update loop overwrote its stdDeviation on each iteration — only the last line's value survived, making all inactive lines identically blurred.

Fix — Option A with distance culling: each line gets its own <filter id="blur-line-{i}"> injected during buildScene. In updateScene, lines within BLUR_CULL_DIST = 4 steps of the active line have stdDeviation = dist * 1.5 (max 6) and filter="url(#blur-line-{i})" applied to their SVG group node. Lines beyond 4 steps have the filter attribute removed entirely — already near-invisible from opacity dimming, removing the filter eliminates up to ~12 unnecessary GPU compositing passes per frame. When a line becomes active, its filter is also cleared immediately in activateLineGroup.

Performance note: all three candidate options (per-line filters, shared filter, CSS filter) pay the same core GPU cost — one compositing pass per blurred element. Distance culling is the meaningful lever, capping simultaneous blurred elements at 8 (±4) instead of ~20.

Bug 4 (visual, fixed): buildWordUnits set lineY = lineIdx * lineStride(style) and used it as the Y for text nodes placed inside lineGroup. Since lineGroup already has translation.y = lineIdx * stride from buildScene, the text world Y was h/2 + 2*N*stride — double the intended position. Inactive line text (placed at y=0 in the same group) was correct, so the active line visually jumped downward every time word units were rebuilt. Fix: lineY = 0. Clip path y correspondingly changes from lineY - fontSize to -fontSize.

Minor fix: Removed always-true style.textAlign !== undefined guard in activateLineGroup (textAlign is a required field); simplified to if (state.defs).


2026-03-12

Karaoke refactor — Step 11: remove deprecated code from LyricsLivePreview.tsx

frontend-karaoke-wip/src/components/LyricsLivePreview.tsx reduced from 2360 → 1597 lines (−763).

Deleted:

  • KaraokeWord function component, WordEffects interface, hexToRgba, findActiveWord, wordFillPct
  • renderScrollStyle, renderFadeStyle, renderKaraokeStyle, renderGlowStyle, renderBlurStyle
  • lineStrokeVal, lineShadowVal, lineNeedsLayer computed values
  • scrollDivRef, translateYRef, activeLineRef, activeWordSpanRef refs
  • brightRef, dimRef, karaokeModeRef refs and their sync effects; wordEffects useMemo
  • useLayoutEffect (CSS translateY scroll wrapper) and handleRecenter
  • RAF loop word-tracking (lastWordIdx) and direct DOM gradient-write block
  • useLayoutEffect and useMemo removed from React import

Preserved: All audio/transport logic, speaker management, style picker panel, KaraokeEditor integration, cover art overlay. renderLyricsArea now contains only <LyricsCanvas> + cover art overlay.

Post-review fixes: (1) handleRecenter button still in toolbar called the deleted function — removed the button (LyricsCanvas auto-centres via lerp). (2) SpeakerDot component defined but never called after render functions removed — deleted. Crosshair removed from lucide-react import. Final line count: 1536.


2026-03-12

Karaoke refactor — Step 12: StyleState verification + fontSize fullscreen fix

Step 12 per the plan ("no new StyleState fields required") was confirmed — all LyricsCanvas.StyleState fields are already covered by LyricsLivePreview.StyleState and the mapping in renderLyricsArea.

Gap found and fixed: renderLyricsArea was passing style.fontSize (raw stored value) instead of the computed fontSize variable (which applies × 1.65 in fullscreen). LyricsCanvas now receives the fullscreen-scaled value. Fixed: fontSize: style.fontSize → fontSize.

Cleanup: isFullscreen was present in LyricsCanvasProps and the component signature but never used inside the component — the container CSS handles the height difference. Removed from both LyricsCanvas.tsx and the <LyricsCanvas> call site in LyricsLivePreview.tsx.


2026-03-12 — Blank canvas root-cause fix (Three bugs in Two.js API usage)

Files changed: frontend-karaoke-wip/src/components/LyricsCanvas.tsx

Root causes of blank canvas (nothing appearing in the karaoke preview):

Bug A — fitted: true kills setSize (critical) In Two.js 0.8.x, the fitted: true constructor option is implemented as an else if branch that sets display: block on the SVG and creates a this.fit function, but does not call setSize. The typeof params.width === 'number' branch that would call setSize is mutually exclusive with fitted: true. Result: two.width = 0, two.height = 0 forever. All geometry (bgRect, text positions, linesGroup translation) was built at zero dimensions. The SVG itself had no width/height attributes and rendered at browser default (300×150) while Two.js thought the canvas was 0×0. Fix: removed fitted: true. With explicit width and height provided, Two.js now falls into the else if branch and calls setSize correctly.

Bug B — _renderer vs renderer (affected defs and resize) _renderer is not a property on Two.js instances — the public property is renderer. Two places used the wrong name:

  • buildScene: used (two as any)._renderer?.elem to get the SVG root element for defs injection → always undefined → state.defs = null → activateLineGroup returned early every call (never built word units). Fix: use (two as any).renderer?.defs directly (Two.js SVGRenderer creates <defs> at construction and exposes it as renderer.defs).
  • ResizeObserver: used (two as any)._renderer?.setSize(w, h) → silent no-op → SVG width/height attributes never updated on resize. Fix: (two as any).renderer?.setSize(w, h).
  • Cleanup path: same fix for renderer?.domElement to remove the SVG on unmount.

Bug C — _renderer.elem timing (affected karaoke/glow/shadow) _renderer.elem on Two.js shapes and groups is created by the render loop when it first processes each object. In buildWordUnits (called from activateLineGroup during the update event), newly created Two.Text objects have not yet been rendered — their _renderer.elem is undefined. Calling applyClipPath / applyFilter immediately after construction silently no-ops. Fix: moved clip-path and shadow-filter attribute application out of buildWordUnits. After building word units, call (state.two as any).renderer?.render() to force one synchronous render pass (creates _renderer.elem for all new objects), then iterate word units and apply attributes. Added shadowFilterId: string | null field to WordUnit to carry the filter id from build to apply phase.

Also: removed now-unused ensureDefs import from svgUtils.


2026-03-12 — Visual fixes after first-render review

Files changed: frontend-karaoke-wip/src/components/LyricsCanvas.tsx

Bug D — Inactive lines not centered (x=0 with center anchor) buildScene placed all inactive-line text at (0, 0) with alignment: 'center'. In SVG, text-anchor: middle at x=0 puts the text center at the left edge — half the text was off-screen to the left. Fixed: compute textX from style.textAlign (two.width/2 for center, 24 for left, two.width - 24 for right) and pass alignment: style.textAlign to the Two.Text constructor.

Bug E — Double opacity on inactive lines (0.35 × 0.35 = 0.12) buildScene set opacity: INACTIVE_OPACITY on both the Two.Text object AND the lineGroup. Since group opacity multiplies child opacity, inactive lines rendered at ≈12% opacity (nearly invisible). Fixed: removed opacity from the Two.Text constructor; the group opacity alone controls fade.

Bug F — Karaoke "behind" layer had fill: 'none' (no dim underlayer) buildWordUnits created the behind text with fill: 'none'. This meant the unswept portion of the active line had no visible fill — only the stroke outline rendered. The intended design is: behind shows the full word in style.textColor (dim), front clips over it in style.activeColor as it sweeps. Fixed: changed behind.fill from 'none' to style.textColor. Also changed front.fill initialization to style.activeColor (was style.textColor) to clarify intent.

Bug G — Pop mode clip-path applied at width=0 (front text permanently invisible) buildWordUnits always created a <clipPath> with initial width=0 and activateLineGroup always called applyClipPath on the front text. For karaokeMode === 'pop' (instant fill-change, no sweep), the front text ended up permanently clipped to zero width and was invisible. Fixed: clip rect is only created when style.karaokeMode === 'fill'; pop mode skips clip creation entirely.

Also updated updateWordFills: restructured the loop guard from if (!wu.clipRect) continue (which silently skipped pop mode since pop has no clipRect) to if (wu.behindText === wu.frontText) continue (correctly skips scroll/fade words which share a single text object). Pop mode now handled in else branch: front.fill = frac > 0 ? style.activeColor : 'transparent'.

2026-03-12 — Fix z-order: front texts appearing behind behind texts

Root cause: buildWordUnits was adding texts to the lineGroup interleaved per word (behind0, front0, behind1, front1, …). In SVG, later children render on top of earlier ones, so behind1 rendered over front0, causing the bright active-color sweep layer to be obscured by subsequent words' dim underlayer.

Fix: Restructured buildWordUnits to collect behind and front texts into separate arrays during the word loop (behindTexts[] and frontTexts[]), then add them to the lineGroup in two explicit passes at the end: all behindTexts first (back layer), then all frontTexts (top layer). This guarantees every front text is always above every behind text in SVG z-order regardless of word count.

2026-03-12 — Fix centering, scale pivot, scroll, spaces, and pop-mode initial state

Four root causes fixed:

1. Centering broken by scale pivot (lineGroup.translation.x = 0) Two.js builds its transform matrix as T(translation) × S(scale). Scale is applied about the local origin (0,0), which was at the left edge of the SVG (x=0). scale=0.92 on inactive lines therefore pulled all text toward x=0, visibly off-centering text aligned with two.width/2. Fix: set lineGroup.translation.x = two.width/2 so the scale pivot is the canvas centre. All child x-coordinates shifted to be relative to this new origin (0 = canvas centre): centre text at x=0, left text at -(two.width/2)+24, right text at (two.width/2)-24. Same adjustment applied to buildWordUnits startX.

2. Scroll/fade broken — per-word split with no spaces buildWordUnits for !needsWordUnits (scroll/fade) split line.words into separate Two.Text objects per word, with no inter-word spacing. Replaced with an early-return path: scroll/fade creates ONE text node using line.text (preserves spaces) at the same x-position logic as inactive lines.

3. Spaces deleted in karaoke/glow/blur The word cursor advanced by ww only, with no space between words. Fixed by measuring spaceWidth = measureWord(' ', ctx, cache) and adding it to cursorX after each non-last word. totalWidth also includes inter-word spaces.

4. Pop mode: front text flashed activeColor on line activation For karaokeMode === 'pop', the front text was initialized with fill: style.activeColor. On activation, all words briefly showed the active colour before updateWordFills ran. Fixed: pop mode initialises front.fill = 'transparent'; fill only becomes style.activeColor once the word's start time is reached.

2026-03-12 — Fix scroll jitter: lines reference unstable across renders

Root cause: LyricsLivePreview called parseLrcContent(activeLrc) at render-time (no memo), returning a new array reference on every parent render. LyricsCanvas's useEffect([lines]) compares by reference, so it fired on every render — calling buildScene repeatedly, resetting state.activeIdx = -1, linesGroup.translation.y = two.height/2, and discarding all scroll state. Result: the preview jumped to the top every frame and appeared to jitter.

Fix: Wrapped the call in useMemo(() => parseLrcContent(activeLrc), [activeLrc]) in LyricsLivePreview. The lines array reference now only changes when activeLrc text changes. Added useMemo to the import.

2026-03-12 — Fix scroll freeze, fill bug, pop bug, and syllable spacing

Root causes and fixes (all in LyricsCanvas.tsx):

1. Scroll freezes — deactivation left stale SVG children in old line's group activateLineGroup only cleared oldRecord.wordUnits = [] (JavaScript array), leaving all word-unit Two.Text SVG nodes in the group's <g>. Previously-active lines therefore displayed their word-unit texts (at inactive opacity/scale) instead of a clean simple text node, causing visual corruption. Also, dotCircle was never re-added after the initial record.group.remove() on the new line.

Fix: on deactivation, call oldGroup.remove(...oldGroup.children), re-add oldRecord.dotCircle if present, then insert a new Two.Text(oldLine.text, ...) matching buildScene layout. On activation, likewise record.group.remove(...children) then re-add record.dotCircle before calling buildWordUnits.

2. Fill effect bugged — isWordEnd not respected buildWordUnits added spaceWidth between ALL consecutive words, including intra-word syllables where word.isWordEnd === false (ELRC format). This turned "walking" into "walk ing". Fixed: gate space on (w as any).isWordEnd !== false in both the totalWidth reduce and the cursorX advance.

3. Pop effect didn't work — 'transparent' vs 'none' Pop mode front text was initialised with fill: 'transparent' and toggled back to 'transparent' in updateWordFills. Two.js SVG renderer doesn't reliably handle CSS color 'transparent' for fill toggling. Changed both to 'none' (proper SVG no-fill value).

4. Scroll starts then freezes — wrong scroll target before first line targetY = two.height/2 - newActiveIdx * stride. When newActiveIdx = -1 (before any line plays), this gave targetY = two.height/2 + stride — scrolling the group DOWN by one stride, then it snapped back when line 0 activated. Fixed: const scrollIdx = Math.max(0, newActiveIdx) so the group rests at line 0 before playback begins.

2026-03-12 — Review: fix three structural bugs found in activateLineGroup / buildScene

Bug 1 — Seek-backward leaves old active line stuck with word units activateLineGroup had its early-return guard (newIdx < 0) BEFORE the old-line deactivation block, and state.activeIdx = newIdx was set at the very end (never reached on early return). Result: seeking to before the first line left the previously-active line's word-unit SVG nodes in place, and newActiveIdx !== state.activeIdx in updateScene fired every frame in an infinite no-op loop. Fix: moved old-line deactivation and state.activeIdx = newIdx before the guard.

Bug 2 — Shadow filter elements leaked into <defs> on every line transition Deactivation block called removeClipPath for each wu.clipId but never removed <filter id="shadow-X-Y"> elements. Fixed: for each wu.shadowFilterId, defs.querySelector('#id') then removeChild.

Bug 3 — Stale defs after buildScene rebuild two.clear() removes scene objects but NOT <defs> contents. Old clip paths and filters accumulated across font/resize rebuilds, causing duplicate IDs (browser uses first — stale — definition). Fix: after fetching state.defs, purge all children with while (defs.firstChild) defs.removeChild(defs.firstChild).

2026-03-12 — Implement 20260312_Fix_LyricsCanvas_Issues.md (8 steps)

Step 1 — highlightColor for scroll/fade active line Added highlightColor: string to StyleState interface. Scroll/fade active-line text now uses style.highlightColor (mapped from style.highlightColor in LyricsLivePreview) instead of style.activeColor (the per-word karaoke highlight). Added highlightColor: style.highlightColor to the LyricsCanvas props in LyricsLivePreview.tsx.

Step 2 — Fill-mode clip path coordinate fix injectClipPath was called with x = wordX - ww/2. Because Two.js places the <text> element at (wordX, lineY) via its transform matrix, userSpaceOnUse clip coordinates are in the text's post-transform (local) space where the glyph centre is (0, 0). The left glyph edge is therefore -ww/2, not wordX - ww/2. Fixed to injectClipPath(defs, clipId, -ww/2, -style.fontSize, style.fontSize * 2).

Step 3 — Stroke on inactive line texts buildScene now passes stroke and linewidth to the inactive line Two.Text constructor options so stroke is consistent between active and inactive states.

Step 4 — scaleX/scaleY stretch + deferred shadow/paint-order on inactive lines Each lineGroup now receives (lineGroup as any).scale = new Two.Vector(scaleX, scaleY) when non-unity. After the build loop a single forced render is performed, then each inactive text's SVG <text> node gets paint-order="stroke fill" (if stroke enabled) and an injected shadow filter (if shadow enabled), matching the active-line treatment.

Step 5 — paint-order + shadow on restored old-line text in activateLineGroup After the forced render inside activateLineGroup, the behind texts of the new active line receive paint-order="stroke fill". The newly-restored old-line simple text also gets paint-order and shadow applied via the same render pass.

Step 6 — Pop mode scale animation updateWordFills pop branch now sets (wu.frontText as any).scale = 1 + style.popScale / 100 while elapsed >= 0 && elapsed < wu.duration, and resets to 1 otherwise. Matches the KaraokeWord reference behaviour.

Step 7 — Per-style per-direction opacity/scale in updateScene Replaced the flat INACTIVE_OPACITY/INACTIVE_SCALE with a per-style, past/future-aware table. Active scale for scroll is 1.08 (slight zoom). Fade fades more aggressively for distant future lines. Karaoke/glow/blur use graduated scale (0.88/0.82/0.78) and clip future lines to 0 opacity beyond dist=5. Removed unused ACTIVE_OPACITY and ACTIVE_SCALE constants. scaleX/scaleY composition applied in the scale lerp.

Step 8 — Dual drop-shadow glow filter in svgUtils.ts injectFilter for type === 'glow' now creates two feDropShadow primitives (full radius at 0.8 opacity + double radius at 0.4 opacity) and composites them with the source via feMerge, matching the CSS double-drop-shadow reference behaviour.

2026-03-12 — Wire LyricsCanvas into live frontend/

Replaced the five HTML-based render*Style() functions in frontend/src/components/LyricsLivePreview.tsx with a single <LyricsCanvas> component.

Files copied to frontend/:

  • frontend/src/components/LyricsCanvas.tsx — Two.js SVG renderer
  • frontend/src/utils/svgUtils.ts — SVG DOM helpers

Changes to frontend/src/components/LyricsLivePreview.tsx:

  1. Added import LyricsCanvas from './LyricsCanvas'
  2. Memoized lines: parseLrcContent(activeLrc) → useMemo(() => parseLrcContent(activeLrc), [activeLrc]) — prevents scene rebuild every frame
  3. Replaced the renderLyricsArea inner scrollDivRef wrapper + conditional render*Style() calls with a single <LyricsCanvas> receiving all style props
  4. Stripped now-irrelevant container CSS (fontFamily, fontWeight, clipPath, maskImage) — LyricsCanvas owns the canvas surface entirely
  5. Old scrollDivRef/activeLineRef refs and the old render*Style functions remain as dead code (no-op) — safe to clean up later

Per-speaker coloring in LyricsCanvas — frontend/src/components/LyricsCanvas.tsx

Problem: Speaker color overrides (via speakerColorFn) were only applied to the dot-circle bullet. All text (inactive lines, word-unit behind/front layers, restored past-line text) used global style colors.

Changes in frontend/src/components/LyricsCanvas.tsx:

  1. Added activeColor: string to WordUnit interface — stores the resolved per-line active color (speaker override or style.activeColor).
  2. buildWordUnits: added speakerColorFn parameter; computes spColor/lineTextColor/lineActiveColor/lineHighlight from speaker; added activeColor to both units.push calls (scroll/fade path uses lineHighlight, word-unit path uses lineActiveColor).
  3. buildScene inactive line text: fill now uses line.speaker ? speakerColorFn(line.speaker) : style.textColor.
  4. activateLineGroup: renamed _speakerColorFn → speakerColorFn; passes it to buildWordUnits; restored old-line text fill uses oldLine.speaker ? speakerColorFn(oldLine.speaker) : style.textColor.
  5. updateWordFills pop mode: fill uses wu.activeColor instead of style.activeColor.

WIP sync: Copied updated LyricsCanvas.tsx and svgUtils.ts to frontend-karaoke-wip/src/.


Fix fill and pop karaoke mode bugs — frontend/src/components/LyricsCanvas.tsx

Fill mode root cause: clipPathUnits="userSpaceOnUse" coordinates are in the parent element's coordinate system (lineGroup's local space), not the referencing text element's own local space. The text sits at (wordX, lineY) in the lineGroup, so the clip rect left edge must be wordX - ww/2. The prior "fix" to -ww/2 was based on a misreading of the SVG spec.

Pop mode root cause: Creating two text nodes (behind + front) at the same position caused stroke bleed-through: the behind text's stroke (in the dim color) was visible around the front text's fill area. Also required tracking a separate dim color for seek-back reset.

Changes:

  1. WordUnit interface: added behindColor: string and perWord: boolean.
  2. buildWordUnits scroll/fade: added behindColor: lineHighlight, perWord: false.
  3. buildWordUnits word loop: fill-mode front text gets explicit stroke: 'none', linewidth: 0; clip rect x = wordX - ww/2; pop mode sets front = behind (single text); only fill-mode words push to frontTexts.
  4. units.push: added behindColor: lineTextColor, perWord: true.
  5. updateWordFills: if (!wu.perWord) continue; pop mode resets fill to wu.behindColor when frac === 0.

WIP sync: Copied updated LyricsCanvas.tsx to frontend-karaoke-wip/src/.


Phase 2 fixes per 20260312_Fix Canvas_Phase 2.md — LyricsCanvas.tsx + svgUtils.ts

  1. svgUtils.ts injectClipPath: Added cp.setAttribute('clipPathUnits', 'userSpaceOnUse') — ensures clip rect coordinates are interpreted in the lineGroup's user-space, fixing the karaoke fill sweep.
  2. LrcWord.isWordEnd: Added isWordEnd?: boolean to interface; removed (word as any) casts.
  3. Comprehensive style rebuild: Replaced useEffect([fontFamily, fontSize]) with a single effect keyed on JSON.stringify of all scene-affecting style properties. Ensures every StyleState change triggers a scene rebuild.
  4. Stale speakerColorFn closure: Added speakerColorFnRef; all closures in useEffect and two.bind('update') now read speakerColorFnRef.current.
  5. Gradient edge mask: Added clipPath: 'inset(0)' and maskImage fade gradient to container div — matches reference's top/bottom edge fade.
  6. Scroll bold: In updateScene, sets textNode.weight = isActive ? 700 : 400 for scroll mode.
  7. Fade active scale 1.12: targetSc for fade active line is now 1.12 — matches reference's 12% bump.
  8. Past-line color (karaoke/glow/blur): In updateScene, inactive line fill updated to highlightColor (past) or textColor (future) per speaker color.
  9. Pop-mode smooth scale: updateWordFills lerps scale toward target using popSnap-derived factor.
  10. Glow filter cleanup: activateLineGroup removes filter attribute from old line's SVG group on deactivation in glow mode.

WIP sync: Copied updated LyricsCanvas.tsx and svgUtils.ts to frontend-karaoke-wip/src/.


Replace clip-path fill mode with SVG linearGradient — LyricsCanvas.tsx + svgUtils.ts

Root cause: Clip-path fill sweep was still broken because SVG clipPathUnits="userSpaceOnUse" coordinate-system semantics are inherently ambiguous with nested transforms. The reference uses linear-gradient(to right, bright N%, dim N%) — a sharp color split. The correct SVG equivalent is a <linearGradient gradientUnits="objectBoundingBox"> — no coordinate math needed.

Changes:

  • svgUtils.ts: Added injectGradient(defs, id, brightColor, dimColor) — <linearGradient gradientUnits="objectBoundingBox" x1="0" x2="1"> with 2 stops at initial offset=0. Two stops at same offset create a sharp bright→dim split. Returns [brightStop, dimStop] for frame-by-frame animation.
  • WordUnit: replaced clipRect/clipId with gradStops/gradId.
  • buildWordUnits fill mode: injects gradient, front text fill="url(#grad-id)" set as Two.js fill property (output automatically on next render).
  • activateLineGroup deactivation: removes gradient elements from defs.
  • activateLineGroup activation: removed applyClipPath call.
  • updateWordFills fill mode: moves both gradient stops to String(frac) each frame.
  • Removed injectClipPath, removeClipPath, applyClipPath from imports.

WIP sync: Copied updated files to frontend-karaoke-wip/src/.


2026-03-13 — Phase 3: Text wrapping, glow fixes, filter region

Plan: 20260313_Canvas Fix_Phase 3.md

src/utils/svgUtils.ts

  • injectFilter: Expanded filter region from -50%/200% to -100%/300% to prevent sharp glow cutoff at large glowSize values.

src/components/LyricsCanvas.tsx

  • Added wrapText(text, ctx, cache, availableWidth): string[] helper — splits plain text by spaces into sub-rows that fit within the available canvas width.
  • Extended LineRecord interface: added yOffset: number (cumulative Y of the group) and subRowCount: number (number of visual rows after wrapping).
  • buildScene: replaced i * stride with cumulative cumulativeY tracker; inactive lines now render one Two.Text per wrapped sub-row at ri * stride Y offset. Deferred paint-order/shadow loop now iterates all text nodes per record (skips dotCircle).
  • buildWordUnits (karaoke/glow/blur path): replaced the single word for-loop with a two-pass sub-row approach — pre-groups words into sub-rows that fit two.width - 48, then positions each row independently with correct center/right alignment per row. Words in each row placed at rowY = rowIdx * stride.
  • activateLineGroup text restoration: now calls wrapText and creates one Two.Text per sub-row (matching buildScene). Deferred shadow/paint-order section iterates all restored text nodes. Glow activation now updates both feDropShadow flood-color attributes to the active line's speaker color (falls back to style.activeColor).
  • updateScene: scroll target now uses state.lineRecords[scrollIdx].yOffset (with ?? scrollIdx * stride fallback). Scroll bold and karaoke/glow/blur past-line color sections now iterate all text nodes in each group (skipping dotCircle) instead of targeting only the last child.

WIP sync: Copied updated files to frontend-karaoke-wip/src/.


2026-03-13 — Phase 4: Fill gradient fix, SVG fill passthrough, endTime

Plan: 20260313_Canvas Fix_Phase 4.md

src/components/LyricsCanvas.tsx

  • Fix A: lineActiveColor no longer uses speaker color — always style.activeColor. Speaker color still tints lineTextColor (dim layer). Prevents invisible gradient when speaker color matches active color.
  • Fix B1: Added frontElem: SVGElement | null field to WordUnit interface.
  • Fix B2: In activateLineGroup, after forced render, iterates word units: caches wu.frontElem = _renderer.elem and calls frontElem.setAttribute('fill', 'url(#grad-…)') to bypass Two.js Color conversion.
  • Fix B3: In updateWordFills fill mode branch, re-applies frontElem.setAttribute('fill', 'url(#…)') every frame after updating gradient stop offsets, guarding against Two.js overwriting it during render.

src/components/LyricsLivePreview.tsx

  • Fix C1: Added endTime?: number to the LrcLine interface.
  • Fix C2: parseLrcContent now sets sorted[i].endTime = sorted[i+1]?.time ?? sorted[i].time + 3 after sorting, fixing the last-word 1-second hardcoded fallback in buildWordUnits.

WIP sync: Copied updated files to frontend-karaoke-wip/src/.


2026-03-13 — Phase 5: Snap scene state after rebuild to prevent jitter

Plan: 20260313_Canvas Fix_Phase 5.md

src/components/LyricsCanvas.tsx

  • Added snapSceneState(state, lines, style, visualStyle, speakerColorFn, currentTimeRef) helper after buildScene. It immediately: (1) calls activateLineGroup to rebuild word units for the current time position, (2) sets linesGroup.translation.y directly to the correct scroll target (no lerp), and (3) iterates all lineRecords setting each group's opacity and scale directly to the distance-based target values using the same switch-table as updateScene.
  • Called snapSceneState after buildScene in 4 locations: styleRebuildKey useEffect, visualStyle useEffect, ResizeObserver callback, lines useEffect (inside .then()). Initial mount does NOT call it — the gradual lerp-in on first render is intentional.

WIP sync: Copied updated file to frontend-karaoke-wip/src/.


2026-03-13 — Video Lyrics style (Moving Letters entrance animations)

Plan: 20260312_Video Lyrics.md

src/utils/videoAnimations.ts (new file)

  • Exports VideoAnimStyle union (12 presets), VideoTimingGranularity ('line' | 'word' | 'syllable'), VideoAnimDef interface, and VIDEO_ANIM_REGISTRY.
  • 12 presets using Web Animations API: fadeUp, fadeDown, scaleIn, rotateIn, slideLeft, slideRight, popIn, waveUp, typewriter, blur, flipIn, swingIn. STAGGER_MS=40, DURATION=600, EASING=easeOutCubic. Each returns Animation[] for later cancellation.

src/components/LyricsCanvas.tsx

  • LyricsVisualStyle extended with 'video'.
  • StyleState extended with videoAnimStyle: VideoAnimStyle and videoGranularity: VideoTimingGranularity.
  • SceneState extended with overlayEl: HTMLDivElement | null, activeAnimations: Animation[], lastVideoLineIdx: number.
  • Mount useEffect: creates an <div> overlay (position:absolute, inset:0, pointer-events:none) appended to the container, initialized in SceneState. Cleanup cancels animations and removes overlay.
  • Container <div> gets position: 'relative' so the overlay positions correctly.
  • buildScene: resets activeAnimations, lastVideoLineIdx, and overlayEl.innerHTML on every rebuild to force re-trigger of overlay on next frame.
  • updateScene: when visualStyle === 'video' and newActiveIdx !== state.lastVideoLineIdx, cancels previous animations, injects <span data-unit> elements into a flex container inside the overlay (split by line/word/syllable), finds the matching VideoAnimDef, calls .animate(), and stores returned Animation[].
  • updateScene + snapSceneState: video active line has targetOp = 0 (hidden in Two.js, shown via overlay); inactive lines use opacity 0.30/0.15/0.
  • styleRebuildKey now includes videoAnimStyle and videoGranularity.

src/components/LyricsLivePreview.tsx

  • LyricsVisualStyle extended with 'video'.
  • StyleState extended with videoAnimStyle and videoGranularity; DEFAULT_STYLE defaults to 'fadeUp' / 'word'.
  • VISUAL_STYLES array gets { id: 'video', label: 'Video', ... } entry.
  • localStorage validation updated to include 'video'.
  • StylePicker gains hasElrc prop; renders a Video sub-panel when visualStyle === 'video': a <select> for animation preset (populated from VIDEO_ANIM_REGISTRY) and segmented buttons for granularity (Syllable disabled with tooltip when !hasElrc).
  • StylePicker invocation passes hasElrc={hasElrc}.
  • <LyricsCanvas> style prop passes videoAnimStyle and videoGranularity.

WIP sync: Copied all three files to frontend-karaoke-wip/src/.


2026-03-13 — Video style: LRC/ELRC timing, display modes, 1.69:1 aspect box

src/utils/videoAnimations.ts

  • Added unitDelay(el, i, fallback) helper: reads el.dataset.delay (ms) set by LyricsCanvas from LRC/ELRC word timestamps; falls back to fallback (default i * STAGGER_MS). Typewriter preset uses its own fallback of i * 80.
  • Replaced i * STAGGER_MS with unitDelay(el, i) across all 12 presets so animations fire at each word's actual scheduled time when timing data is available.

src/components/LyricsCanvas.tsx

  • StyleState extended with videoDisplayMode: 'scroll' | 'line' | 'word' | 'syllable'.
  • SceneState extended with lastVideoWordIdx: number; initialized to -1; reset in buildScene.
  • Added findActiveWord(line, time) helper: returns index of currently active word in line.words, or -1.
  • Rewrote video overlay block in updateScene:
    • Scroll mode: triggers on line change; splits by videoGranularity; sets span.dataset.delay = max(0, (word.time - currentTime) * 1000) so each word animates at its LRC/ELRC time.
    • Line mode: triggers on line change; shows full line text centered in a 1.69:1 aspect-ratio box; font size scales to fill box.
    • Word/syllable modes: triggers on word change via findActiveWord; shows single current word/syllable in 1.69:1 box; lastVideoWordIdx tracks changes; resets on line change.
    • Box geometry: boxW = min(canvasW, canvasH * 1.69), boxH = boxW / 1.69, centered in canvas.
    • Font sizing for non-scroll modes: line → min(boxW*0.85/(chars*0.55), 90), word/syllable → min(boxW*0.8/(chars*0.55), 220).
  • Opacity logic (updateScene + snapSceneState): scroll display mode keeps inactive lines dimmed (0.30/0.15); line/word/syllable modes set all Two.js lines to opacity 0.
  • styleRebuildKey now includes videoDisplayMode.

src/components/LyricsLivePreview.tsx

  • StyleState extended with videoDisplayMode; default 'scroll'.
  • StylePicker video block redesigned: Layout row (Scroll | Line | Word | Syllable buttons; Word/Syllable disabled when !hasElrc); Anim row (preset select + Unit granularity buttons shown only in scroll mode).
  • <LyricsCanvas> style prop passes videoDisplayMode.

WIP sync: Copied all three files to frontend-karaoke-wip/src/.


2026-03-13 — Video style: accumulation, word grouping, no-space syllables, remove 1.69 box

src/utils/videoAnimations.ts

  • Changed fill: 'forwards' → fill: 'both' on all 12 presets. fill: 'both' applies the first keyframe backwards before the delay fires (span starts invisible) and holds the last keyframe forward after completion — produces the accumulation effect where words appear one-by-one at their LRC-timed delays and stay visible.
  • Updated waveUp to include opacity: 0 in its first keyframe (enters from invisible).

src/components/LyricsCanvas.tsx

  • Added buildWordGroups(words) helper: groups LrcWord syllables into logical words (concatenating until isWordEnd !== false), returning {text, startTime, syllables[]}[].
  • Added findActiveWordGroup(words, time) helper: finds the active logical word index.
  • Removed all 1.69:1 box geometry. All display modes now use position:absolute;inset:0 full-canvas overlay with style.fontSize directly (user controls size via existing slider).
  • Rewrote video overlay content building:
    • Scroll/word: one [data-unit] span per logical word (syllables concatenated). data-delay = max(0, (word.startTime - currentTime) * 1000) drives LRC/ELRC-timed accumulation.
    • Scroll/syllable: word-container <span style="display:inline-flex"> wrapping individual syllable [data-unit] spans with no gap between them, eliminating intra-word spaces. Word containers separated by gap:0.3em.
    • Line: single span, max-width:100%;word-break:break-word, data-delay:0.
    • Word: buildWordGroups to get current word group (concatenated syllables), data-delay:0.
    • Syllable: current syllable span, data-delay:0.

WIP sync: Copied both files to frontend-karaoke-wip/src/.


2026-03-13 — Fix Video style one-frame opacity flash (accumulation broken)

File: frontend/src/components/LyricsCanvas.tsx

Problem diagnosed: When animDef.animate() was called on freshly-appended [data-unit] spans, all spans rendered at opacity:1 (CSS default) for one paint frame before Web Animations API's fill:'both' backward fill could apply opacity:0. This caused all words to flash visible simultaneously, breaking the intended one-word-at-a-time accumulation effect.

Fix: After state.overlayEl.appendChild(flexDiv) and before animDef.animate(...), added:

flexDiv.querySelectorAll('[data-unit]').forEach((el: Element) => {
  (el as HTMLElement).style.opacity = '0'
})

This pre-hides all spans so the backward fill takes effect without the one-frame flash.

WIP sync: Copied LyricsCanvas.tsx to frontend-karaoke-wip/src/components/.


2026-03-13 — Video Line mode fix: timed progressive reveal (ELRC syllables / LRC words)

File: frontend/src/components/LyricsCanvas.tsx

Problem observed: In Video Line layout mode, the full line rendered at once instead of revealing one timed unit at a time.

Root cause:

  • updateScene(...) treated displayMode === 'line' as a non-scroll single-unit mode.
  • On each line change it built one span with spanText = activeLine.text, then animated that single span.
  • Because only one span existed for the line, timing granularity from ELRC/LRC was never used in Line mode.

Fix implemented:

  1. Changed the progressive branch condition from displayMode === 'scroll' to:
  • displayMode === 'scroll' || displayMode === 'line'
  1. Line mode now uses the same progressive queued insertion model used by scroll mode (videoLineUnits, per-frame reveal when unit.time <= currentTime).
  2. Added auto granularity selection for Line mode:
  • If ELRC timed units (line.words) exist → reveal by syllable timing.
  • Else fallback to LRC-style word timing buckets.
  1. Kept the old one-unit-at-a-time branch only for explicit displayMode === 'word' and displayMode === 'syllable' modes.
  2. Updated type narrowing logic so TS correctly treats the non-progressive branch as word|syllable only.

Result:

  • Video Line mode now reveals text progressively according to available timing data instead of showing the entire line instantly.

2026-03-13 — Video Line mode UX fix: static centered line while revealing units

File: frontend/src/components/LyricsCanvas.tsx

Problem: After enabling timed Line mode reveal, the text position still shifted as units were inserted (line “grew” while revealing). Desired behavior is a static centered line with units being revealed in place.

Root cause:

  • The progressive queue inserted DOM nodes over time (appendChild per due unit).
  • Center alignment recalculated as content width grew, causing horizontal drift.

Fix implemented:

  1. Extended SceneState.videoLineUnits entries with el: HTMLSpanElement | null so each timed unit can reference a prebuilt DOM node.
  2. In displayMode === 'line', prebuild the full line structure at line start:
  • syllable path: prebuild all word containers and all syllable spans
  • word path: prebuild all word spans
  • each prebuilt unit span starts with visibility: hidden (occupies layout width but not visible)
  1. On each timed reveal tick, for Line mode:
  • switch unit span to visibility: visible
  • animate that existing span in place
  1. Updated animateSpan(...) to preserve in-place layout for existing elements:
  • remembers original parent/next sibling
  • runs registry animation through a temporary container
  • re-inserts span back to its original position immediately

Result:

  • Line stays visually centered and static from the first frame.
  • Words/syllables reveal at LRC/ELRC timing without lateral recenter drift.

2026-03-13 — LyricsCanvas hardening pass (perf + lifecycle + TS typing)

File: frontend/src/components/LyricsCanvas.tsx

Scope: Executed the previously agreed fix plan with Docker/container workflow in mind (code-only changes in frontend source; no host-specific assumptions added).

Changes applied:

  1. React namespace typing cleanup (TS config compatibility)
  • Updated import to include explicit type-only imports:
    • type RefObject
    • type MutableRefObject
    • type CSSProperties
  • Replaced React.RefObject, React.MutableRefObject, and React.CSSProperties usages with imported types.
  • This removes dependence on global React namespace resolution and makes the file friendlier to strict/bundler TS setups.
  1. Per-frame word-group recomputation removed (video word mode perf)
  • Added lineWordGroups to SceneState:
    • Array<Array<{ text; startTime; syllables[] }>>
  • buildScene(...) now precomputes logical word groups once per line using buildWordGroups(...) and stores them in state.lineWordGroups.
  • Refactored findActiveWordGroup(...) to accept precomputed groups ({ startTime }[]) instead of raw LrcWord[].
  • updateScene(...) now reads cached groups for:
    • active word index lookup in video displayMode === 'word'
    • active span text selection in non-scroll word mode
  • Result: avoids rebuilding grouped words every RAF frame.
  1. Blur filter lifecycle optimization (large lyric sets)
  • In buildScene(...), removed eager creation of one blur filter per line.
  • In updateScene(...) blur branch, filters are now lazy-created only when a line enters BLUR_CULL_DIST from the active line.
  • Existing filters are reused via state.blurPrimitives map.
  • Lines outside cull distance still have filter attribute removed (existing behavior retained).
  • Result: lower SVG defs churn and reduced initial scene setup overhead on long projects.
  1. Async font-ready lifecycle guards (unmount safety)
  • Mount effect: added disposed guard for document.fonts.ready.then(...) callback.
  • Lines-change effect: added cancelled guard with cleanup return to prevent late callback mutation after effect invalidation/unmount.
  • Guards also verify stateRef.current === state before mutating scene.
  • Result: prevents stale async callbacks from mutating detached scene/DOM.
  1. State initialization alignment
  • Added initialization for new lineWordGroups field in SceneState constructor path.

Behavioral intent preserved:

  • No visual-style feature removal.
  • No API/prop contract changes outside internal type refinement.
  • Existing karaoke/video logic kept intact while reducing hot-path work.

Validation note:

  • A build validation command was initiated, but terminal execution was cancelled before completion, so this entry documents code changes only.

2026-03-13 — LyricsCanvas follow-up: deduped style targets + bounded blur filter window

File: frontend/src/components/LyricsCanvas.tsx

Reason for follow-up: Continued the remaining plan items without forcing rebuilds (frontend is live-reloaded in the running container).

Changes applied:

  1. Deduplicated per-line target logic used by both snap and RAF update paths
  • Added getLineVisualTargets(visualStyle, style, isActive, isPast, absDist) helper.
  • Centralizes targetOp + targetSc selection for all visual styles (scroll, fade, karaoke, glow, blur, video).
  • Replaced duplicated switch/if blocks in:
    • snapSceneState(...)
    • updateScene(...)
  • Result: lower maintenance risk and reduced chance of behavior drift between immediate-snap and animated-frame code paths.
  1. Bounded blur filter lifecycle (window pruning, not just lazy creation)
  • Existing lazy blur creation remains in place (filters are created only when a line enters blur cull distance).
  • Added blurKeep sets in both snapSceneState(...) and updateScene(...) to track lines currently within BLUR_CULL_DIST.
  • After each pass, blur filters not in blurKeep are removed from <defs> and deleted from state.blurPrimitives.
  • Active lines explicitly clear SVG filter in snap path for deterministic sharp rendering.
  • Result: blur filter count remains bounded to nearby lines instead of gradually growing across the full track after long playback/seeks.

Net effect:

  • Same user-facing visuals, cleaner internal structure.
  • Lower long-session SVG defs growth and better runtime stability on long lyrics.

2026-03-13 — Fix video scroll mode: progressive DOM insertion replaces animation-delay approach

File: frontend/src/components/LyricsCanvas.tsx

Problem: Even with the pre-hide fix, all words appeared simultaneously because data-delay values were all 0 whenever time had already passed a word's LRC timestamp (normal for any seek or when the RAF fires late relative to line start). Root cause: relying on Web Animations API delay to control word-reveal order is fragile.

Fix: Progressive DOM insertion — spans are added to the overlay exactly when their timestamp arrives, with delay=0 animation fired immediately on each new span. New helper animateSpan(span, animDef) routes each span through an isolated temp container so the registry's animate() doesn't reanimate already-visible spans. A new videoLineUnits array tracks pending reveals; on each RAF frame, units with time <= currentTime and added=false are inserted and animated.

State additions to SceneState:

  • videoFlexEl: HTMLDivElement | null — persists the flex container across frames
  • videoWordEls: HTMLSpanElement[] — pre-built word containers for syllable mode
  • videoLineUnits: Array<{text,time,added,wordElIdx}> — pending unit queue

WIP sync: Copied LyricsCanvas.tsx to frontend-karaoke-wip/src/components/.


2026-03-13 — Video mode fix: apply stroke/shadow effects on HTML overlay text

File: frontend/src/components/LyricsCanvas.tsx

Problem: Stroke and shadow controls worked in SVG-rendered styles, but had no visible effect in Video mode.

Root cause:

  • Video mode renders text in an HTML overlay (<div>/<span>), not Two.js SVG text nodes.
  • Existing stroke/shadow logic in LyricsCanvas was implemented through SVG stroke/filter application paths (buildWordUnits, deferred SVG filter passes), so video overlay spans never received equivalent CSS effects.

Fix implemented:

  1. Added hexToRgba(hex, opacity) helper in LyricsCanvas.tsx to convert hex + opacity to CSS rgba(...) for shadow color parity.
  2. In the Video branch of updateScene(...), computed:
    • strokeVal from style.strokeEnabled, style.strokeWidth, style.strokeColor
    • shadowVal from style.shadowEnabled, style.shadowX/Y, style.shadowBlur, style.shadowColor, style.shadowOpacity
  3. Applied these styles to the video overlay container (makeFlexDiv) so overlay text inherits effects:
    • -webkit-text-stroke
    • text-shadow
    • paint-order: stroke fill
  4. Also applied the same styles directly to all unit spans created in video paths (scroll/line/word/syllable; static prebuilt and progressive-inserted spans) to ensure consistent rendering across browsers and dynamic insertion flows.

Result:

  • Stroke and shadow controls now affect Video mode text consistently, matching user expectations from other preview modes.