@nice2dev/ui-audio

Audio UI component library for React applications. Provides a complete set of DAW editor components, karaoke engine, audio player, playlist management, music visualizers, MIDI support, effects, and audio processing utilities.

Installation

npm install @nice2dev/ui-audio

Peer Dependencies

Required:

• react >= 17
• react-dom >= 17
• @nice2dev/ui-core — design tokens, i18n, shared primitives
• @nice2dev/ui — design-system components used by the higher-level controls (setup panel, song browser, studio, vocal-FX rack, audio-input picker, …)
• @nice2dev/icons — all iconography (Ntd* icons). This library uses no emoji or foreign icons — every icon comes from @nice2dev/icons.

Optional (enable specific features):

• react-youtube — YouTube player integration
• react-window — virtualized playlist rendering
• hls.js — HLS streaming support
• pitchy — real-time pitch detection
• recharts — charts in NiceVocalPerformanceReport
• phaser — Phaser-based karaoke renderer
• framer-motion — animated transitions
• @fortawesome/react-fontawesome + icon packages — icons
• music-metadata-browser — audio file metadata parsing
• fflate — compression utilities
• @ffmpeg/ffmpeg — audio format conversion
• @monaco-editor/react — code editor integration
• react-bootstrap — Bootstrap UI components
• wav-decoder — WAV file decoding

Usage

i18n Setup

Wrap your app with NiceI18nProvider to supply translations:

import { NiceI18nProvider } from '@nice2dev/ui-audio';

function App() {
  return (
    <NiceI18nProvider t={(key, fallback) => fallback ?? key}>
      <YourAudioApp />
    </NiceI18nProvider>
  );
}

Audio Player

import { GenericPlayer, GenericPlayerControls } from '@nice2dev/ui-audio';

<GenericPlayer src="/track.mp3" title="My Song" artist="Artist" />;

Karaoke

Turnkey orchestrator — backing track + per-player pitch timelines + lyrics + live mic→pitch→scoring + summary, with every backend piece injected and optional:

import { NiceKaraokeManager } from '@nice2dev/ui-audio';

<NiceKaraokeManager
  players={[{ id: 1, name: 'Aria', color: '#f472b6', micId }]}
  song={song} // KaraokeSongFile (UltraStar notes)
  difficulty="normal"
  searchYouTubeByArtistTitle={search} // optional — resolve a YouTube backing track
  onSaveResults={save} // optional — persist results
  fetchTopSingings={fetchTop} // optional — leaderboards
  renderReport={(close) => <NiceVocalPerformanceReport onClose={close} {...data} />}
/>;

Lower-level pieces are also exported (NiceKaraokeLyrics, NiceKaraokeTimeline, NiceKaraokeSongBrowser, NiceKaraokeUploader, NiceKaraokeSetupPanel, NiceKaraokeSessionJoin, NiceKaraokeSelectionMode, NiceLatencyCalibrator, NicePadKaraokeOverlay, NiceKaraokeSummaryOverlay).

DAW Editor

Turnkey multi-track studio (or compose the pieces directly):

import { NiceAudioStudio } from '@nice2dev/ui-audio';

<NiceAudioStudio initialTracks={tracks} onTracksChange={setTracks} initialBpm={120} />;

import { Waveform, PianoRoll, AudioTimeline, EditorTrackProvider, useEditorTrack } from '@nice2dev/ui-audio';

<EditorTrackProvider value={editorState}>
  <Waveform data={waveformData} zoom={zoom} />
  <PianoRoll notes={midiNotes} duration={duration} zoom={zoom} />
</EditorTrackProvider>;

Playlist

import { GenericPlaylist, PlaylistBrowser } from '@nice2dev/ui-audio';

<GenericPlaylist items={tracks} onSelect={handleSelect} />
<PlaylistBrowser
  renderLibrarySearch={(props) => <MySearch {...props} />}
  renderLibraryList={(props) => <MyList {...props} />}
/>

Visualizer

import { StageVisualizer } from '@nice2dev/ui-audio';

<StageVisualizer analyser={analyserNode} mode="spectrum" />;

API Architecture

This library is backend-agnostic. All API-dependent operations are exposed as callback props or dependency injection instead of hardcoded API calls:

• Player: searchYouTubeByArtistTitle callback prop on YouTubePlayer
• Karaoke: NiceKaraokeManager injects everything backend-specific — searchYouTubeByArtistTitle, onSaveResults, fetchTopSingings, rtc (multiplayer sync), renderReport; runs fully standalone with none of them
• Pitch Analysis: postPitch / postLibrosaPitchTrack callbacks on AudioPitchAnalyzer
• Song library: songs / fetchSongs + getCover / getTopScore on NiceKaraokeSongBrowser; client-side UltraStar parsing or a parseSong override on NiceKaraokeUploader
• Playlist: Render props (renderLibrarySearch, renderLibraryList) on PlaylistBrowser
• Editor CRUD: ProjectCRUDDeps interface for useProjectCRUD hook
• Settings: Optional fetchSettings callbacks for karaoke settings hydration
• Audio Sources: registerAudioSourceComponent() for pluggable audio source types

Exports

Components

All controls are also exported Nice*-prefixed (e.g. NiceWaveform); the unprefixed names are kept for backward compatibility.

| Module | Components | | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | DAW Studio | NiceAudioStudio (turnkey multi-track workspace) | | Editor | Waveform, PianoRoll, CCLane, AudioTimeline | | Editor Panels | AutoSavePanel, UndoRedoPanel, ZoomSnapControls, MasterFXPanel, RecordingOptionsPanel, CCAutomationLaneEditor, ArpeggiatorPanel, LFOPanel, StepSequencerPanel | | Karaoke | NiceKaraokeManager (orchestrator), KaraokeLyrics, KaraokeTimeline, BarFillEditor, AudioPitchAnalyzer, NiceKaraokeSummaryOverlay, NiceVocalPerformanceReport, NicePadKaraokeOverlay | | Karaoke — songs | NiceKaraokeSongBrowser, NiceKaraokeUploader (parseUltraStarText), NiceMusicLibraryExplorer | | Karaoke — session | NiceKaraokeSetupPanel, NiceKaraokeSessionJoin, NiceKaraokeSelectionMode (useCanPickSong), NiceLatencyCalibrator | | Karaoke Editor | KaraokeEditorManager, KaraokePhaserRenderer | | Player | GenericPlayer, GenericPlayerControls, GenericPlayerStage, GenericPlayerStageVisualizer, YouTubePlayer | | Input / FX | NiceAudioInputPicker, NiceVocalEffectsRack, NiceAudioEffectsRack | | Visualizer | StageVisualizer, ModeSwitcher | | Playlist | GenericPlaylist, GenericPlaylistItem, PlaylistTagEditor, DynamicRuleEditor, PlaylistDualPane, PlaylistBrowser, PlaylistList, PlaylistSidebar | | Effects | NoteRiver, NoteParticles |

Hooks

| Hook | Purpose | | ------------------- | ---------------------------------------------------- | | useEditorTrack | Shared DAW editor state via context | | useProjectCRUD | Project/section/layer CRUD with dependency injection | | useCCAutomation | CC automation lane management | | useStepSequencer | Step sequencer state | | useWebMidi | Web MIDI API access | | useMidiLearn | MIDI learn/mapping | | useOxygen25 | M-Audio Oxygen 25 controller profile | | usePitchWorker | Pitch detection Web Worker | | useScoringWorker | Karaoke scoring Web Worker | | useKaraokePitch | Live per-player mic → pitch loop (rtc optional) | | useKaraokeScoring | Live multi-player karaoke scoring | | useCanPickSong | Whether a player may pick (selection-mode aware) | | useLocalPlaylists | Local playlist storage |

Engine

| Export | Purpose | | --------------------- | --------------------------------------------------------- | | AudioPlaybackEngine | Multi-track audio playback | | VocalEffectsEngine | Real-time vocal effects (reverb, delay, distortion, etc.) | | SimpleSynth | Basic synthesizer | | getAudioContext | Shared AudioContext management |

Utilities

Karaoke scoring, pitch analysis, audio editor operations, timeline calculations, LFO engine, arpeggiator, step sequencer, CC automation, groove templates, vocal performance metrics, undo/redo, latency estimation.

Models

Type definitions for karaoke notes, audio projects, DMX channels, playlists, editor state, MIDI events, and timeline operations.

Build

npm run build       # Vite library build
npm run typecheck   # TypeScript type checking
npm run test        # Vitest unit tests

Styling

This package ships unstyled component logic. Import the shared CSS bundle once at your app entrypoint:

import '@nice2dev/ui/style.css';

Optional: opt into the legacy shorthand token aliases (--bg-*, --text-*, --border-*, ...) when migrating from a custom design-token system:

import '@nice2dev/ui/css/legacy-bg-text-aliases.css';

License

MIT © NiceToDev