6.0 KiB
SingUI Karaoke Presets Implementation
Date: April 16, 2026
Status: Complete and deployed (updated with queue-on-ready follow-up fix)
Overview
Replaced the single "Package" button in SingUI search results with three separate preset buttons, allowing users to choose between three curated karaoke processing pipelines directly from the search interface.
Follow-up fix (April 16, 2026): once a song reaches ready state, preset buttons switch to a ready (green) style and clicking them queues playback instead of triggering another prepare run.
Three Karaoke Presets
1. Quick Karaoke
- Model: MDX-Net Karaoke
- Lyrics: WhisperX (small) — word-level precision
- Processing: Fast, minimal post-processing
- Use case: Quick turnaround, acceptable quality
2. Pro Karaoke
- Model: MelBand RoFormer (4-stem)
- Lyrics: WhisperX (small) — word-level precision
- Processing: Standard post-processing
- Use case: Balanced quality/speed tradeoff
3. Rich Karaoke
- Model: MelBand RoFormer (4-stem)
- Lyrics: WhisperX (small) — syllable-level precision, two-pass transcription
- Processing: Enhanced lyrics alignment (syllable-level ELRC)
- Use case: Maximum quality for professional use
Files Changed
New Files
- src/utils/karaokePresets.ts
- Defines
KARAOKE_PRESETSarray with three AutoPreset objects - Each preset includes model, format, and processing steps
- Exported
getPresetByName()helper for preset lookup
- Defines
Modified Files
1. src/components/singui/SongPreviewSheet.tsx
Changes:
- Updated
SongPreviewSheetPropsinterface:- Added optional
onPrepareWithPreset?: (presetName: string) => voidcallback - Kept legacy
onPrepare: () => voidfor backward compatibility
- Added optional
- Replaced single "Prepare for karaoke" button with 3-column grid
- Each button:
- Shows abbreviated preset name (Quick/Pro/Rich)
- Displays Mic2 icon
- Calls
onPrepareWithPreset(presetName)when clicked - Falls back to
onPrepare()if new callback not provided
- Maintains disabled states and loading indicators
UI Layout:
┌─────────────────────────────┐
│ KARAOKE PRESET │
│ ┌──────┬──────┬──────┐ │
│ │Quick │ Pro │ Rich │ │
│ │ 🎤 │ 🎤 │ 🎤 │ │
│ └──────┴──────┴──────┘ │
└─────────────────────────────┘
2. src/pages/SearchPage.tsx
Changes:
- Added import:
import { KARAOKE_PRESETS } from '../utils/karaokePresets' - Updated
SongRowPropsinterface:- Added optional
onPrepareWithPreset?: (presetName: string) => voidcallback
- Added optional
- Modified
SongRowcomponent:- Replaced single "Prepare" button with three buttons in a row (Quick, Pro, Rich)
- Each button shows only the preset name's first word (abbreviated for mobile)
- Full preset name visible on hover via title attribute
- Hidden on small screens (
hidden sm:inline) for mobile optimization - All buttons maintain same styling and disabled states as original
- Added
handlePrepareWithPreset()function:- Logs
'preset_selected'telemetry event with preset name - Calls
handlePrepare()to execute preparation
- Logs
- Updated
SongRowrender call to passonPrepareWithPresetcallback - Updated
SongPreviewSheetrender call to passonPrepareWithPresetcallback
UI Layout (Search Results):
Song Row: [info] [Quick] [Pro] [Rich] [+]
🎤 🎤 🎤
On mobile (hidden):
Song Row: [info] [+]
Telemetry
When users select a preset, the following event is logged:
telemetryPrepareAction({
action: 'preset_selected',
song_id: 'subsonic-id',
role: 'host' | 'curator' | null,
preset: 'Quick Karaoke' | 'Pro Karaoke' | 'Rich Karaoke'
})
This allows tracking:
- Which presets are most popular
- User role preferences for presets
- Prepare workflow engagement
Backward Compatibility
onPreparecallback still works ifonPrepareWithPresetnot provided- Existing code that passes only
onPreparewill function with default behavior - No breaking changes to existing component interfaces
Implementation Details
Button Layout Strategy
- Desktop: All three buttons visible side-by-side with full first-word abbreviation
- Mobile: Buttons shown with abbreviated labels; full names available on hover
- Uses Tailwind's
hidden sm:inlinefor responsive text
Click Handler
Each button:
- Calls
onPrepareWithPreset(presetName)if provided - Otherwise falls back to
onPrepare() - Logs telemetry event with preset selection
- Triggers same preparation flow as before
Ready/Disabled State
- Not ready: buttons trigger preset processing (prepare)
- Ready: buttons change to green "ready" styling and queue playback
- Buttons are disabled when:
- User is offline (
!isConnected) - Already preparing (
isPreparing) - Song already queued (
isQueued) while still in pre-ready state
- User is offline (
Build & Deployment
Compiled: April 16, 2026, 15:14 JST
SearchPage Bundle: SearchPage-oSfl4xYR.js (31.75 kB, 9.18 kB gzipped)
All changes are live immediately after frontend rebuild.
Architecture Notes
The preset definitions are frontend-only UI elements. The actual preset configuration (model, format, steps) is defined in karaokePresets.ts but the backend determines which preset to use based on:
- Server-side
auto_presetssettings - Runtime settings (from the GPU resource management plan)
- User selection (via telemetry if integrated)
The three presets defined here align with the benchmark test presets used in benchmark_run_2026-04-16.json.