@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

Optional (enable specific features):

• react-youtube — YouTube player integration
• react-window — virtualized playlist rendering
• hls.js — HLS streaming support
• pitchy — real-time pitch detection
• 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

import { KaraokeLyrics, KaraokeTimeline } from '@nice2dev/ui-audio';

<KaraokeLyrics notes={karaokeNotes} currentTime={time} />
<KaraokeTimeline notes={karaokeNotes} currentTime={time} duration={180} />

DAW Editor

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
• Pitch Analysis: postPitch / postLibrosaPitchTrack callbacks on AudioPitchAnalyzer
• 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

| Module | Components | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Editor | Waveform, PianoRoll, CCLane, AudioTimeline | | Editor Panels | AutoSavePanel, UndoRedoPanel, ZoomSnapControls, MasterFXPanel, RecordingOptionsPanel, CCAutomationLaneEditor, ArpeggiatorPanel, LFOPanel, StepSequencerPanel | | Karaoke | KaraokeLyrics, KaraokeTimeline, BarFillEditor, AudioPitchAnalyzer | | Karaoke Editor | KaraokeEditorManager, KaraokePhaserRenderer | | Player | GenericPlayer, GenericPlayerControls, GenericPlayerStage, GenericPlayerStageVisualizer, YouTubePlayer | | 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 | | 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