Files
stemengine_old/docs/features/SingUI_Karaoke_Presets.md
2026-04-16 15:52:46 +09:00

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_PRESETS array with three AutoPreset objects
    • Each preset includes model, format, and processing steps
    • Exported getPresetByName() helper for preset lookup

Modified Files

1. src/components/singui/SongPreviewSheet.tsx

Changes:

  • Updated SongPreviewSheetProps interface:
    • Added optional onPrepareWithPreset?: (presetName: string) => void callback
    • Kept legacy onPrepare: () => void for backward compatibility
  • 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 SongRowProps interface:
    • Added optional onPrepareWithPreset?: (presetName: string) => void callback
  • Modified SongRow component:
    • 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
  • Updated SongRow render call to pass onPrepareWithPreset callback
  • Updated SongPreviewSheet render call to pass onPrepareWithPreset callback

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

  • onPrepare callback still works if onPrepareWithPreset not provided
  • Existing code that passes only onPrepare will 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:inline for responsive text

Click Handler

Each button:

  1. Calls onPrepareWithPreset(presetName) if provided
  2. Otherwise falls back to onPrepare()
  3. Logs telemetry event with preset selection
  4. 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

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:

  1. Server-side auto_presets settings
  2. Runtime settings (from the GPU resource management plan)
  3. 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.