@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.

Nothing else has to be installed. Every module the build imports is declared, so an app builds whether or not it uses the karaoke, chart or YouTube parts.

Dependencies

Installed with the package:

• pitchy — real-time pitch detection
• react-youtube — YouTube sources in the players
• hls.js — HLS streams, loaded on first use in browsers without native HLS

Charts (NiceVocalPerformanceReport) are NiceChart / NicePieChart and virtual lists are NiceVirtualScroller, all from @nice2dev/ui; the karaoke text preview (NiceKaraokePhaserRenderer) is plain DOM and no longer needs Phaser.

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