142 KiB
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_sizeto 4 - Switch
compute_typeto"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:
-
_apply_cuda_limits()called at job start:os.nice(10)— lowers the job thread's CPU scheduling prioritytorch.cuda.set_per_process_memory_fraction(fraction)— hard-caps VRAM usage, reserving headroom for DWM. Default 80%, configurable viaSTEMENGINE_GPU_MEMORY_FRACTIONenv var.
-
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.75in Docker compose or.envfor 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 injectmin_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:
isActiveRefis a ref so changing it doesn't trigger effects. Fixed by callingpublishMeta(...)immediately afterisActiveRef.current = truein bothDynamicMixPlayerandLyricsLivePreviewtogglePlaybranches. - Audio continuing after navigation:
unregisterPlaybackonly removes the registry reference, not the audio element. Fixed by callingstopPlayback()beforeunregisterPlayback()in unmount cleanup of both players. - X button: Added
stopCurrent()export toaudioRegistry.ts(calls registered stop callback + clears_current). Added X (lucide-react) button toGlobalAudioBar.tsx.
Karaoke fill/pop mode + Open Foundry fonts
LyricsLivePreview.tsx:
- Added
karaokeMode: 'fill' | 'pop'toStyleState(default'fill'). KaraokeWordnow acceptsisActive?: booleanandmode?: '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
KaraokeWordcall sites (karaoke, glow, blur styles) passisActiveandmode. - Added Fill/Pop toggle buttons to
StylePicker. - Replaced
FONT_OPTIONSwith 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>andbackground: '#1e293b', color: '#e2e8f0'on each<option>so the native OS dropdown renders dark. - Bold toggle: Added
fontBold: booleantoStyleState(defaultfalse). B button inStylePickernext to the font selector. Applied asfontWeight: 700 / 400on 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'andtextShadow: '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
fontSizetoggling withtransform: scale(1 + popScale/100)on the wrapper span — GPU-composited, zero layout reflow. fontSizeis now alwaysfontSize(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-outsnaps 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
fontSizealso 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 inheritedpaintOrder: stroke fillfrom 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:
-
_fill_transcript_gapsre-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. -
no_speech_threshold: 0.45was 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 from0.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:
-
N_FFT = 2048was wrong.librosa.stftwithn_fft=2048produces1025frequency bins. The ONNX models expect input withDIM_F = 3072bins (plus the Nyquist bin = 3073 total). The correctn_fftfor3073bins is6144. -
_spec_to_batchproduced(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. -
_batch_to_specinverted the wrong shape — inverse of the broken forward pass; was not the correct inverse of the corrected forward pass. -
Length mismatch in
_demix. After ISTFT,target_audiocan be slightly shorter or longer than the originalmixdue to STFT/ISTFT padding behaviour.mix - target_audioraised an operand-shape error.
Fixes applied to backend/services/mdxnet_separator.py:
-
N_FFT: Changed2048→6144. This produces 3073 freq bins; the top bin is cropped to 3072 before ONNX and zero-padded back after. -
_spec_to_batchrewritten: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_specrewritten 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 -
_demixlength guard added: after ISTFT,target_audiois trimmed or zero-padded to matchmix.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:
-
backend/routers/models.py—MODEL_DOWNLOAD_INFO["mel_band_karaoke"]:fileslist updated from["model.ckpt", "config.yaml"]to["mel_band_roformer_karaoke_becruily.ckpt", "config_karaoke_becruily.yaml"]. Also correctedsize_mbfrom170→1760to reflect the actual 1.72 GB checkpoint. -
backend/services/mel_band_specialized_separator.py—MelBandKaraokeSeparator.__init__:model_pathandconfig_pathupdated to use the correct filenames so that_ensure_model's existence check andsnapshot_downloadboth 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:
-
No VRAM cap on separation.
_apply_cuda_limits()(which callstorch.cuda.set_per_process_memory_fraction(0.80)) was only ever called bylyric_transcriber_service.py. If separation ran before transcription (or transcription never ran in the session), the allocator had no VRAM ceiling and could OOM. -
No OOM retry in
_run_mel_band_karaoke. On anout of memoryexception 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 ofrun_separation(), beforetorch.cuda.empty_cache(). Now separation and transcription share the same VRAM ceiling (default 80%, overridable viaSTEMENGINE_GPU_MEMORY_FRACTION). -
OOM retry in
_run_mel_band_karaoke: Wrappedsep.separate_into_parts(...)in a 2-attempt loop. On the firstout of memoryerror: clears CUDA cache, updates job progress ("GPU OOM — retrying with batch_size=1…"), and retries withbatch_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_karaokeimmediately before constructing the separator (which loads the model checkpoint). This second flush is necessary because allocations can accumulate between the start ofrun_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_bsroformerand_run_bsroformer_chorus(2-attempt loop, same as MelBand)._run_bsroformer_swgets flush only — it delegates to theaudio-separatorlibrary which doesn't expose abatch_sizeparameter. strict=Falseonload_state_dict: Applied tobs_roformer_separator.pyandbs_roformer_chorus_separator.pywith the same warning pattern asmel_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 withbatch_size_override=1._run_scnet: 2-attempt loop; on first OOM, gc+cache flush then retry withchunk_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 raisesRuntimeError("Cancelled by user"). This propagated torun_separation's top-levelexcept Exceptionblock, 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():
- Cancellation branch in
except: Addedif jm.should_cancel(job_id) or "Cancelled by user" in err_stras the first condition — sets status=CANCELLED (not ERROR) and skips the error message path. finallyblock: Added after theexceptblock — always runsgc.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:
nvidia-smi --power-limit: Caps hardware TDP. Default 100 W (min for this GPU); override withSTEMENGINE_GPU_POWER_LIMITenv var. Set to 0 to disable. Silently ignored if the driver rejects (e.g. insufficient privilege). Called once per job at limits-apply time.- 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. - 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: samemel_band_specialized_separator.py: samescnet_separator.py:torch.no_grad()+ autocast (enabled=(device.type == 'cuda')since device istorch.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: Addednvidia-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: Addedcap_add: [SYS_ADMIN]so the container has the driver-level permission to write the power limit via NVML. Also addedSTEMENGINE_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-initservice added tostemengine.yml: usesnvidia/cuda:12.1.0-base-ubuntu22.04, hascap_add: SYS_ADMIN, runsnvidia-smi --power-limitinline in its entrypoint, then exits (restart: "no"). The command is hardcoded in the compose file, not sourced from any mounted file.stemengineservice:cap_add: SYS_ADMINremoved entirely. Addeddepends_on: stemengine-gpu-init: condition: service_completed_successfullyso the main container waits for the init to finish before starting.start.shmount 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 whereoverflow: hiddenfails.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 triplegc.collect()in thefinallyblock. - Lines 651–655: added
jm.gpu_vram_lock.release()(wrapped in try/except RuntimeError) at the end of thefinallyblock, afterempty_cache().
Fix — backend/services/lyric_transcriber_service.py:
- Lines 859–875:
_clear_cuda_cache()updated to callgc.collect()three times instead of once, with an explanatory docstring. - Lines 1331–1334: added
jm.gpu_vram_lock.acquire()(with comment) immediately before the transcriptiontry:block inrun_lyric_transcription. - Lines 1859–1864: removed
_clear_cuda_cache()from theexceptblock (moved tofinally). - Lines 1866–1874: added new
finally:block (previously absent) that calls_clear_cuda_cache()andjm.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, andcpu_separation=self.cpu_separationfrom theSeparator()constructor call in_get_separator(). All three parameters were dropped from the audio-separatorSeparator.__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: fetchesaudioUrl, decodes with a dedicatedAudioContext(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 viaonSeekprop.KaraokeEditor: wraps the canvas with a header row showing line count and a note when waveform is unavailable (multi-stem mode with noaudioUrl).
Modified — frontend/src/components/LyricsLivePreview.tsx:
- Line 2: added
Activityto 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 (
Activityicon) that togglesshowAegisuband closes the other panels. - Lines 2243–2251: added
{showAegisub && <KaraokeEditor .../>}panel rendered after the existing LrcEditor panel; receiveslines,currentTimeRef,displayDuration,audioUrl ?? stems?.[0]?.url, andseekTime.
2026-03-10 — Feature — Waveform editor (Phase 2): TimingTable component
Modified — frontend/src/components/KaraokeEditor.tsx:
- Added
TimingTablesub-component: scrollable table (height 200 px) with columns#,Start,End,Text, and optionalSpeaker(shown only when any line has a speaker field). - End time derived as next line's start time, or
durationfor 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. linesRefpattern keeps the RAF closure reading the latest lines without re-subscribing.- Fixed:
React.MouseEvent→ReactMouseEvent(imported as type alias); typedelref callback asHTMLTableRowElement | null.
2026-03-10 — Feature — Waveform editor (Phase 3): inline timing/text editing
Modified — frontend/src/components/KaraokeEditor.tsx:
- Added
onLrcChange?: (newLrc: string) => voidtoKaraokeEditorPropsandTimingTableprops. - Added
reconstructLrc(lines): rebuilds a full LRC/ELRC string from aLrcLineKE[]array, preserving word-level timestamps and speaker tags. - Added
parseTs(raw): parses user-typedm:ss.xx/m:ss/m:ss.xtimestamps back to seconds; returnsnullon invalid input (edit is silently discarded). - Added
editing/draftstate toTimingTablefor the active inline edit cell. - Start time cell: double-click opens an inline
<input>pre-filled withformatTs(line.time). On commit (Enter / blur): parses the new time, rebuilds sortedLrcLineKE[], callsreconstructLrc→onLrcChange. Word timestamps on the line are preserved. - Text cell: double-click opens an inline
<input>pre-filled withline.text. On commit: setswords: []for that line (drops sub-word timing), callsreconstructLrc→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
eparameters explicitly typed (ReactMouseEvent<HTMLTableCellElement>,ReactMouseEvent<HTMLInputElement>,ReactChangeEvent<HTMLInputElement>) to satisfy the project's strictnoImplicitAnysetting.
Modified — frontend/src/components/LyricsLivePreview.tsx:
<KaraokeEditor>now receivesonLrcChangethat calls bothsetEditedLrc(newLrc)and the parent'sonLrcChange?.(newLrc), matching the same pattern used byLrcEditor.
2026-03-10 — Feature — Waveform editor (Phase 4): zoom, line markers, arrow-key navigation
Modified — frontend/src/components/KaraokeEditor.tsx:
Waveform zoom + scroll:
WaveformCanvasgainslinesprop for marker rendering.- Replaced
drawWaveform/drawEmptywith a unifieddrawFrame(ctx, peaks, lines, w, h, fraction, zoom, scrollFrac, duration, activeLineIdx)that handles all zoom/scroll/marker logic in one pass. zoomandscrollstored as both React state (drives controls re-render) and refs (read by RAF loop with zero re-render overhead).dirtyRefforce-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
deltaXalso 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; itsmaxtracks1 − 1/zoomso it can never scroll past the end. handleClickupdated 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 fromfindActiveLine.
Arrow-key navigation (in KaraokeEditor):
useEffectattaches akeydownlistener ondocumentwhile 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, orSELECT(so inline cell editing is unaffected). - Reads
linesRef.currentso 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
TimingTablePropsinterface extending the existing props withexpandedRow,onExpandRow,onWordTimeChange. - Lines with
words.length > 0show 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 amberwordInputStyle. - Word times clamped on commit:
[line.time … nextWord.time − 0.01s]. Tab moves between word cells. expandedRowstate andhandleWordTimeChangelive inKaraokeEditor; commits viareconstructLrc → onLrcChange.
Step B — Word markers on waveform:
- Added
WORD_MARKER_COLOR(amber-400/70),WORD_MARKER_DRAG_COLOR,WORD_MARKER_HIT_PX = 8. drawFramegained optionalwordLineanddragPreviewparams. New drawing pass: 2 px × 14 px amber ticks per word; drag preview word showsWORD_MARKER_DRAG_COLOR.WaveformCanvasPropsinterface added withselectedLineIdxandonWordTimeDrag. AddedselectedLineIdxRef,dragStateRef,dragPreviewRefrefs. RAF loop passeswordLineanddragPreviewRef.currenttodrawFrame.
Step C — Drag-to-retime:
- Removed
handleClick/useCallback; replaced with a pointer-eventuseEffect(pointerdown/pointermove/pointerup).canvas.setPointerCapturekeeps events during drag outside the canvas. onPointerDown: near a word marker → start drag. Otherwise → background click.onPointerMove: if dragging → updatedragPreviewRef+dirtyRef = true(no React re-renders). If not → set cursorew-resizenear a marker,crosshairotherwise.onPointerUp: if moved → clamp + commit viaonWordTimeDrag; else → seek click.handleWordTimeDrag(wordIdx, newTime)inKaraokeEditordelegates tohandleWordTimeChange(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.cssalready appliesappearance-noneandbg-brand-500(CSS variable) to allinput[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
divuses inline flex styles (no Tailwind) <header>uses MetroUIapp-bar/app-bar-brand/app-bar-item ml-autoclasses- 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-500CSS 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-closedCSS classes (fromindex.css) — no Tailwind layout classes - Toggle button: MetroUI
button cycle flatwith circular inline style - Active jobs accordion: React state
jobsOpencontrols open/close; header uses a sharedsectionHeaderStyleobject (inline styles matching Metro section headers); amber badge count ActiveJobItem: inline styles replacing Tailwind card; MetroUIbutton cycle flatfor cancel button; LucideStatusDoticons styled withvar(--color-*)CSS variablesProjectTile(replacesProjectItem): inline-styled row with hover state viauseState(hovered), brand-accent border/background whenisOpen, MetroUIbutton cycle flatfor delete; opacity-based reveal on hoverSubsonicPanelaccordion: React stateopen; samesectionHeaderStyleheader withvar(--color-blue)accent; native<input>styled with inline border/background; search button styled inline withvar(--color-blue)backgroundImportedFileRowextracted as separate component to enable hover state for action buttons- Collapsed strip: Lucide icons + count badges using inline
var(--color-gray)— no Tailwind data-roleattributes deliberately avoided throughout to prevent MetroUI JS DOM conflicts with React's virtual DOM; all accordion behavior is React-state-controlledvar(--border-color),var(--background),var(--body-background),var(--color-*)MetroUI CSS variables used for theme-aware colours (light/dark respected automatically viadata-themeset byThemeContext)
2026-03-11 (continued)
MetroUI Phase 3 — Separator page + FileUpload
Files:
frontend/src/pages/Separator.tsxfrontend/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
styleobject - Added React
dragOverstate for visual drag-over feedback (accent border colour + light tint) onDragLeavehandler added to clear drag state
Key changes — Separator.tsx:
- Removed
SELECT_CLS,INPUT_CLS,SLIDER_CLSTailwind string constants; replaced withfieldLabel,ctrl,cardCSSPropertiesobjects at module level - Page header: inline
h2/pstyles - Input-mode toggle: flex segmented button pair — active button gets
accentColorbackground (upload) orvar(--color-blue)(imported) - Selected file indicator:
cardstyle with brand accent border - Imported files empty state: dashed-border div with centered icon + text
ImportedFileButtonextracted as separate function (for hover state); active selection shows accent left-border + tinted background- Model/format grid: CSS
grid(3 columns) withctrlstyled native<select>elements - BS-RoFormer info box: violet-tinted border + background
- Project name:
ctrlstyled<input type="text"> - Preset type:
ctrlstyled<select>+ description text - Static options panel:
cardstyle withctrlselect - Dynamic options panel:
cardstyle; native<input type="range">sliders; percentage readout - Preset preview: brand-tinted border box with
<code>pre-formatted structure - Submit: MetroUI
button primaryclass, full-width - Auto Pipeline: inline amber-bordered/tinted button
- Success result box: green-tinted border inline
JobStatusandResultFilesstill 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):
- STEM_COLORS — Changed from Tailwind class strings to
{ bg, border, color }objects using RGBA/CSS-var theme colors. - JobBadge — Replaced Tailwind span with inline
styleusing MetroUI CSS vars (--color-green,--color-amber,--color-red,--border-color). - DownloadButton — Replaced anchor classes with
className="button flat"+ inline style. - StemChipButton — Replaced Tailwind-colored anchor with fully inline
styleusing the new STEM_COLORS object. - StemReprocessButton (return JSX) — Replaced relative wrapper, trigger button, dropdown panel, family tabs, model list, and cancel button with
button flat/button cycle flatclasses and inline styles using--border-color,--body-background,--background. - StemRenameButton — Replaced editing input and action buttons with inline styles and
button cycle flatclasses; normal state usesbutton cycle flat. - StemsSection header and list — Replaced collapsible header and stem-row cards with inline styles; accent color via
rgb(var(--brand-500, 59 130 246)). - MixesSection header — Replaced collapsible header with inline-style flex layout.
- MixesSection sub-tabs, generate buttons, error/result box — Replaced all Tailwind with inline styles; generate button uses
className="button". - MidiSection header — Replaced with violet-colored inline-style header using
--color-violet. - AbcSection header — Replaced with green-colored inline-style header using
--color-green. - LyricsSection header — Replaced with sky-blue inline-style header using
--color-blue. - 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×
bulkErrTailwind 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):
- Toggle — Replaced Tailwind
translate-x/bg-brand-500/bg-slate-300with a fully inline animated switch usingrgb(var(--brand-500))andvar(--border-color); addedtype="button",role="switch",aria-checked. - MaintenanceSettings — Replaced
space-y-8,flex items-center gap-3 pb-4 border-b, icon wrapperp-2 bg-slate-100 rounded-lg, andspace-y-3list with inline flex/gap/border styles matching the sharedsHdr/sCardpattern. - PowerSettings — Removed
btnBase/btnActiveTailwind class strings; replaced header, GPU banner, VRAM tier card grid (with active/disabled states), and AI Transcription toggle rows with inline styles usingrgb(var(--brand-500)),var(--color-green),var(--color-red),var(--border-color). - IntegrationsSettings — Replaced
space-y-8outer wrapper,flex items-center gap-3 pb-4 border-bheader, allclassNameinputs/buttons (including password field, Save, Remove) with inline styles; MetroUIbutton primaryclass used for Save; status messages usevar(--color-green)/var(--color-red). - Settings (main export) — Removed horizontal pill tab bar (
hidden sm:flex,sm:hiddenmobile 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 usesrgba(var(--brand-500), 0.1)background and brand color text. AddedElementTypetoreacttype import to replaceReact.ElementTypereference.
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: fixedbottom withvar(--border-color)top border,var(--body-background)background,backdrop-filter: blur. - Play/Pause: replaced Tailwind rounded-full +
bg-brand-500with inlinergb(var(--brand-500))circle; MetroUIbutton cycleclass kept. - Time spans, seek slider, volume slider: all inline styles;
accentColorusesrgb(var(--brand-500)). - Mute and dismiss buttons: MetroUI
button cycle flat. - Tailwind
classNamefully removed from the component.
Tailwind remnant sweep — All previously-migrated components audited and cleaned:
-
App.tsx — Removed
className="sm:hidden"from mobile backdrop div (now pure inline style); replacedmax-w-3xl mx-auto px-2 sm:px-4 py-4 sm:py-6+rounded-2xl border border-slate-200 ...wrapper with inline styles usingvar(--border-color)andvar(--body-background); replaced Tailwind<footer>classes with inline style; movedml-autofrom className to inlinemarginLeft: 'auto'. -
JobStatus.tsx — Full rewrite of the render: all
className="flex items-center gap-2 text-xs text-red-500"etc. replaced with sharedrowstyle object + CSS vars (var(--color-red),var(--color-green),var(--color-amber), brand color);truncatereplaced with inlineoverflow: hidden, textOverflow: ellipsis;animate-spinremoved (Tailwind animation — icon unchanged, class dropped). -
ResultFiles.tsx — Replaced
space-y-2wrapper, anchor Tailwind link row, andDownloadicon classes with inline styles; anchor uses MetroUIbutton flatclass + inline border style. -
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. -
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 MetroUIbutton cycle flat; M/S active states usevar(--color-red)/var(--color-amber). -
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;
StepIconcolors use CSS vars; MetroUIbutton primaryfor Close; amber background for Run button. -
Settings.tsx — Fixed
getStatusIcon()helper: replacedw-4 h-4 text-green-500etc. Tailwind icon classNames with inlinestyle+ 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:
-
Sidebar overlay blocking clicks — Removing
sm:hiddenfrom the mobile backdrop div caused it to render on all screen sizes, blocking content on desktop. RestoredclassName="sm:hidden"since Tailwind is still active. -
Dark mode not switching — Components now rely on
var(--body-background),var(--border-color)etc. instead of Tailwinddark:classes. These CSS custom properties were only being set if MetroUI's own CSS defined them under[data-theme="dark"].ThemeContext.tsxupdated to explicitly set all required CSS variables viaroot.style.setProperty(...)in theapply()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). -
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. Addedwidth: '100%',minWidth: 0,overflow: 'hidden',boxSizing: 'border-box'to the button, andoverflowWrap: '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 isflex-col(icon above label),flexShrink: 0,whiteSpace: nowrap, to prevent wrapping and allow horizontal scroll. Below it, aflex: 1, overflowY: autodiv holds the content atpadding: 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: setdocument.body.style.colordirectly inapply(). An inline style on<body>beats all stylesheet rules regardless of load order. Also sets--foreground(#e2e8f0dark /#1e293blight) and--foreground-muted(#94a3b8dark /#64748blight) as CSS vars for components that need explicit colour references. Added--label-colorand--color-grayto the same block.index.css: removed thecolor: 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 tintrgba(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 } }withhtml, 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, addedstyle={{ 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
fieldStyleconstant:{ background: 'var(--background)', color: 'var(--foreground)', borderColor: 'var(--border-color)' } - Applied
style={fieldStyle}to all 10 select/input/textarea elements withbg-white dark:bg-gray-9xxTailwind 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
!importantto the form control block intheme-overrides.css:background: var(--background) !important— forces ThemeContext's dark/light value regardless of MetroUIcolor: var(--foreground) !importantborder-color: var(--border-color) !importantcolor-scheme: dark— forces OS-native chrome (dropdown arrow, scrollbar) to dark theme
- Added
colorScheme: 'inherit'tofieldStyleinProjectDetail.tsxand toctrlinSeparator.tsx - Added
<meta name="color-scheme" content="light dark">toindex.html
LyricsLivePreview tab bar dark mode (LyricsLivePreview.tsx)
- Tab bar container: replaced
dark:bg-gray-800/80 dark:border-gray-700/50Tailwind classes with inlinestyle={{ background: 'var(--background)', borderColor: 'var(--border-color)' }} - All tab/icon buttons: replaced
dark:text-gray-400 dark:hover:bg-gray-700Tailwind classes with inlinestyle={{ color: 'var(--foreground-muted)' }}and addedlp-btnCSS class - Active state buttons: inline
style={{ background: 'rgb(var(--brand-500))', color: '#fff' }} - Added
.lp-btn:hover { background: rgba(128,128,128,0.15) }totheme-overrides.css
Sidebar toggle button visibility (Sidebar.tsx)
- Toggle button positioned at
right: -14(half outside sidebar) was clipped byoverflow: hiddenon the<aside> - Fix: changed aside
overflow: 'visible'; wrapped the collapsed icon strip in its ownoverflow: hiddendiv (expanded content already had its ownoverflow: hidden)
Frontend swap — restored Tailwind UI as active frontend
frontend(MetroUI migration) → renamed tofrontend-backup (metroui)frontend-backup (tailwind)(original) → renamed tofrontend(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()— deletessubsonic.jsonif it exists without_enc: True(legacy plaintext format written before encryption was added) - Encrypted configs (
_enc: True) are left untouched - Wired via FastAPI
lifespancontext 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.jsdoes not exist on npm so no types package was added; Two.js internals are accessed viaas anycasts in the renderer.src/utils/svgUtils.ts(new) — raw SVG DOM helpers:ensureDefs,injectClipPath,removeClipPath,injectFilter,applyClipPath,applyFilter. Only file touching_renderer.eleminternals.src/components/LyricsCanvas.tsx(new) — Two.js SVG lyrics renderer component. Implements a scene-graph approach withbuildScene,activateLineGroup,updateWordFills, andupdateScene. UsescurrentTimeReffor 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) — addedimport LyricsCanvas from './LyricsCanvas'; replaced thescrollDivRefdiv + fiverender*Style()calls inrenderLyricsArea()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:
KaraokeWordfunction component,WordEffectsinterface,hexToRgba,findActiveWord,wordFillPctrenderScrollStyle,renderFadeStyle,renderKaraokeStyle,renderGlowStyle,renderBlurStylelineStrokeVal,lineShadowVal,lineNeedsLayercomputed valuesscrollDivRef,translateYRef,activeLineRef,activeWordSpanRefrefsbrightRef,dimRef,karaokeModeRefrefs and their sync effects;wordEffectsuseMemouseLayoutEffect(CSS translateY scroll wrapper) andhandleRecenter- RAF loop word-tracking (
lastWordIdx) and direct DOM gradient-write block useLayoutEffectanduseMemoremoved 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?.elemto get the SVG root element for defs injection → always undefined →state.defs = null→activateLineGroupreturned early every call (never built word units). Fix: use(two as any).renderer?.defsdirectly (Two.js SVGRenderer creates<defs>at construction and exposes it asrenderer.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?.domElementto 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 rendererfrontend/src/utils/svgUtils.ts— SVG DOM helpers
Changes to frontend/src/components/LyricsLivePreview.tsx:
- Added
import LyricsCanvas from './LyricsCanvas' - Memoized
lines:parseLrcContent(activeLrc)→useMemo(() => parseLrcContent(activeLrc), [activeLrc])— prevents scene rebuild every frame - Replaced the
renderLyricsAreainnerscrollDivRefwrapper + conditionalrender*Style()calls with a single<LyricsCanvas>receiving all style props - Stripped now-irrelevant container CSS (fontFamily, fontWeight, clipPath, maskImage) — LyricsCanvas owns the canvas surface entirely
- Old
scrollDivRef/activeLineRefrefs and the oldrender*Stylefunctions 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:
- Added
activeColor: stringtoWordUnitinterface — stores the resolved per-line active color (speaker override orstyle.activeColor). buildWordUnits: addedspeakerColorFnparameter; computesspColor/lineTextColor/lineActiveColor/lineHighlightfrom speaker; addedactiveColorto bothunits.pushcalls (scroll/fade path useslineHighlight, word-unit path useslineActiveColor).buildSceneinactive line text:fillnow usesline.speaker ? speakerColorFn(line.speaker) : style.textColor.activateLineGroup: renamed_speakerColorFn→speakerColorFn; passes it tobuildWordUnits; restored old-line text fill usesoldLine.speaker ? speakerColorFn(oldLine.speaker) : style.textColor.updateWordFillspop mode: fill useswu.activeColorinstead ofstyle.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:
WordUnitinterface: addedbehindColor: stringandperWord: boolean.buildWordUnitsscroll/fade: addedbehindColor: lineHighlight, perWord: false.buildWordUnitsword loop: fill-mode front text gets explicitstroke: 'none', linewidth: 0; clip rect x =wordX - ww/2; pop mode setsfront = behind(single text); only fill-mode words push tofrontTexts.units.push: addedbehindColor: lineTextColor, perWord: true.updateWordFills:if (!wu.perWord) continue; pop mode resets fill towu.behindColorwhenfrac === 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
- svgUtils.ts
injectClipPath: Addedcp.setAttribute('clipPathUnits', 'userSpaceOnUse')— ensures clip rect coordinates are interpreted in the lineGroup's user-space, fixing the karaoke fill sweep. LrcWord.isWordEnd: AddedisWordEnd?: booleanto interface; removed(word as any)casts.- Comprehensive style rebuild: Replaced
useEffect([fontFamily, fontSize])with a single effect keyed onJSON.stringifyof all scene-affecting style properties. Ensures everyStyleStatechange triggers a scene rebuild. - Stale
speakerColorFnclosure: AddedspeakerColorFnRef; all closures inuseEffectandtwo.bind('update')now readspeakerColorFnRef.current. - Gradient edge mask: Added
clipPath: 'inset(0)'andmaskImagefade gradient to container div — matches reference's top/bottom edge fade. - Scroll bold: In
updateScene, setstextNode.weight = isActive ? 700 : 400for scroll mode. - Fade active scale 1.12:
targetScfor fade active line is now 1.12 — matches reference's 12% bump. - Past-line color (karaoke/glow/blur): In
updateScene, inactive linefillupdated tohighlightColor(past) ortextColor(future) per speaker color. - Pop-mode smooth scale:
updateWordFillslerps scale toward target usingpopSnap-derived factor. - Glow filter cleanup:
activateLineGroupremovesfilterattribute 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: AddedinjectGradient(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: replacedclipRect/clipIdwithgradStops/gradId.buildWordUnitsfill mode: injects gradient, front textfill="url(#grad-id)"set as Two.js fill property (output automatically on next render).activateLineGroupdeactivation: removes gradient elements from defs.activateLineGroupactivation: removedapplyClipPathcall.updateWordFillsfill mode: moves both gradient stops toString(frac)each frame.- Removed
injectClipPath,removeClipPath,applyClipPathfrom 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 largeglowSizevalues.
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
LineRecordinterface: addedyOffset: number(cumulative Y of the group) andsubRowCount: number(number of visual rows after wrapping). buildScene: replacedi * stridewith cumulativecumulativeYtracker; inactive lines now render oneTwo.Textper wrapped sub-row atri * strideY 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 fittwo.width - 48, then positions each row independently with correct center/right alignment per row. Words in each row placed atrowY = rowIdx * stride.activateLineGrouptext restoration: now callswrapTextand creates oneTwo.Textper sub-row (matchingbuildScene). Deferred shadow/paint-order section iterates all restored text nodes. Glow activation now updates bothfeDropShadowflood-color attributes to the active line's speaker color (falls back tostyle.activeColor).updateScene: scroll target now usesstate.lineRecords[scrollIdx].yOffset(with?? scrollIdx * stridefallback). 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:
lineActiveColorno longer uses speaker color — alwaysstyle.activeColor. Speaker color still tintslineTextColor(dim layer). Prevents invisible gradient when speaker color matches active color. - Fix B1: Added
frontElem: SVGElement | nullfield toWordUnitinterface. - Fix B2: In
activateLineGroup, after forced render, iterates word units: cacheswu.frontElem = _renderer.elemand callsfrontElem.setAttribute('fill', 'url(#grad-…)')to bypass Two.js Color conversion. - Fix B3: In
updateWordFillsfill mode branch, re-appliesfrontElem.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?: numberto theLrcLineinterface. - Fix C2:
parseLrcContentnow setssorted[i].endTime = sorted[i+1]?.time ?? sorted[i].time + 3after sorting, fixing the last-word 1-second hardcoded fallback inbuildWordUnits.
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 afterbuildScene. It immediately: (1) callsactivateLineGroupto rebuild word units for the current time position, (2) setslinesGroup.translation.ydirectly to the correct scroll target (no lerp), and (3) iterates alllineRecordssetting each group'sopacityandscaledirectly to the distance-based target values using the same switch-table asupdateScene. - Called
snapSceneStateafterbuildScenein 4 locations:styleRebuildKeyuseEffect,visualStyleuseEffect,ResizeObservercallback,linesuseEffect (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
VideoAnimStyleunion (12 presets),VideoTimingGranularity('line' | 'word' | 'syllable'),VideoAnimDefinterface, andVIDEO_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
LyricsVisualStyleextended with'video'.StyleStateextended withvideoAnimStyle: VideoAnimStyleandvideoGranularity: VideoTimingGranularity.SceneStateextended withoverlayEl: HTMLDivElement | null,activeAnimations: Animation[],lastVideoLineIdx: number.- Mount
useEffect: creates an<div>overlay (position:absolute, inset:0, pointer-events:none) appended to the container, initialized inSceneState. Cleanup cancels animations and removes overlay. - Container
<div>getsposition: 'relative'so the overlay positions correctly. buildScene: resetsactiveAnimations,lastVideoLineIdx, andoverlayEl.innerHTMLon every rebuild to force re-trigger of overlay on next frame.updateScene: whenvisualStyle === 'video'andnewActiveIdx !== state.lastVideoLineIdx, cancels previous animations, injects<span data-unit>elements into a flex container inside the overlay (split by line/word/syllable), finds the matchingVideoAnimDef, calls.animate(), and stores returnedAnimation[].updateScene+snapSceneState: video active line hastargetOp = 0(hidden in Two.js, shown via overlay); inactive lines use opacity 0.30/0.15/0.styleRebuildKeynow includesvideoAnimStyleandvideoGranularity.
src/components/LyricsLivePreview.tsx
LyricsVisualStyleextended with'video'.StyleStateextended withvideoAnimStyleandvideoGranularity;DEFAULT_STYLEdefaults to'fadeUp'/'word'.VISUAL_STYLESarray gets{ id: 'video', label: 'Video', ... }entry.- localStorage validation updated to include
'video'. StylePickergainshasElrcprop; renders a Video sub-panel whenvisualStyle === 'video': a<select>for animation preset (populated fromVIDEO_ANIM_REGISTRY) and segmented buttons for granularity (Syllable disabled with tooltip when!hasElrc).StylePickerinvocation passeshasElrc={hasElrc}.<LyricsCanvas>style prop passesvideoAnimStyleandvideoGranularity.
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: readsel.dataset.delay(ms) set by LyricsCanvas from LRC/ELRC word timestamps; falls back tofallback(defaulti * STAGGER_MS). Typewriter preset uses its own fallback ofi * 80. - Replaced
i * STAGGER_MSwithunitDelay(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
StyleStateextended withvideoDisplayMode: 'scroll' | 'line' | 'word' | 'syllable'.SceneStateextended withlastVideoWordIdx: number; initialized to-1; reset inbuildScene.- Added
findActiveWord(line, time)helper: returns index of currently active word inline.words, or-1. - Rewrote video overlay block in
updateScene:- Scroll mode: triggers on line change; splits by
videoGranularity; setsspan.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;lastVideoWordIdxtracks 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).
- Scroll mode: triggers on line change; splits by
- Opacity logic (
updateScene+snapSceneState):scrolldisplay mode keeps inactive lines dimmed (0.30/0.15);line/word/syllablemodes set all Two.js lines to opacity 0. styleRebuildKeynow includesvideoDisplayMode.
src/components/LyricsLivePreview.tsx
StyleStateextended withvideoDisplayMode; default'scroll'.StylePickervideo 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 passesvideoDisplayMode.
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
waveUpto includeopacity: 0in its first keyframe (enters from invisible).
src/components/LyricsCanvas.tsx
- Added
buildWordGroups(words)helper: groupsLrcWordsyllables into logical words (concatenating untilisWordEnd !== 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:0full-canvas overlay withstyle.fontSizedirectly (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 bygap:0.3em. - Line: single span,
max-width:100%;word-break:break-word,data-delay:0. - Word:
buildWordGroupsto get current word group (concatenated syllables),data-delay:0. - Syllable: current syllable span,
data-delay:0.
- Scroll/word: one
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(...)treateddisplayMode === '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:
- Changed the progressive branch condition from
displayMode === 'scroll'to:
displayMode === 'scroll' || displayMode === 'line'
- Line mode now uses the same progressive queued insertion model used by scroll mode (
videoLineUnits, per-frame reveal whenunit.time <= currentTime). - 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.
- Kept the old one-unit-at-a-time branch only for explicit
displayMode === 'word'anddisplayMode === 'syllable'modes. - Updated type narrowing logic so TS correctly treats the non-progressive branch as
word|syllableonly.
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 (
appendChildper due unit). - Center alignment recalculated as content width grew, causing horizontal drift.
Fix implemented:
- Extended
SceneState.videoLineUnitsentries withel: HTMLSpanElement | nullso each timed unit can reference a prebuilt DOM node. - 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)
- On each timed reveal tick, for Line mode:
- switch unit span to
visibility: visible - animate that existing span in place
- 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:
- React namespace typing cleanup (TS config compatibility)
- Updated import to include explicit type-only imports:
type RefObjecttype MutableRefObjecttype CSSProperties
- Replaced
React.RefObject,React.MutableRefObject, andReact.CSSPropertiesusages with imported types. - This removes dependence on global
Reactnamespace resolution and makes the file friendlier to strict/bundler TS setups.
- Per-frame word-group recomputation removed (video word mode perf)
- Added
lineWordGroupstoSceneState:Array<Array<{ text; startTime; syllables[] }>>
buildScene(...)now precomputes logical word groups once per line usingbuildWordGroups(...)and stores them instate.lineWordGroups.- Refactored
findActiveWordGroup(...)to accept precomputed groups ({ startTime }[]) instead of rawLrcWord[]. updateScene(...)now reads cached groups for:- active word index lookup in video
displayMode === 'word' - active span text selection in non-scroll word mode
- active word index lookup in video
- Result: avoids rebuilding grouped words every RAF frame.
- 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 entersBLUR_CULL_DISTfrom the active line. - Existing filters are reused via
state.blurPrimitivesmap. - 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.
- Async font-ready lifecycle guards (unmount safety)
- Mount effect: added
disposedguard fordocument.fonts.ready.then(...)callback. - Lines-change effect: added
cancelledguard with cleanup return to prevent late callback mutation after effect invalidation/unmount. - Guards also verify
stateRef.current === statebefore mutating scene. - Result: prevents stale async callbacks from mutating detached scene/DOM.
- State initialization alignment
- Added initialization for new
lineWordGroupsfield inSceneStateconstructor 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:
- Deduplicated per-line target logic used by both snap and RAF update paths
- Added
getLineVisualTargets(visualStyle, style, isActive, isPast, absDist)helper. - Centralizes
targetOp+targetScselection 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.
- 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
blurKeepsets in bothsnapSceneState(...)andupdateScene(...)to track lines currently withinBLUR_CULL_DIST. - After each pass, blur filters not in
blurKeepare removed from<defs>and deleted fromstate.blurPrimitives. - Active lines explicitly clear SVG
filterin 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 framesvideoWordEls: HTMLSpanElement[]— pre-built word containers for syllable modevideoLineUnits: 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
LyricsCanvaswas implemented through SVG stroke/filter application paths (buildWordUnits, deferred SVG filter passes), so video overlay spans never received equivalent CSS effects.
Fix implemented:
- Added
hexToRgba(hex, opacity)helper inLyricsCanvas.tsxto convert hex + opacity to CSSrgba(...)for shadow color parity. - In the Video branch of
updateScene(...), computed:strokeValfromstyle.strokeEnabled,style.strokeWidth,style.strokeColorshadowValfromstyle.shadowEnabled,style.shadowX/Y,style.shadowBlur,style.shadowColor,style.shadowOpacity
- Applied these styles to the video overlay container (
makeFlexDiv) so overlay text inherits effects:-webkit-text-stroketext-shadowpaint-order: stroke fill
- 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.