@ghchinoy/lit-audio-ui

v0.6.1

Published

a month ago

A pure Lit WebComponents port of modern audio UI components

Downloads

541

0High
0Medium
0Low

ghchinoy

Lit Audio UI

A lightweight, framework-agnostic Web Components library for high-performance audio visualization and control, built natively for the browser using Lit.

Take a look at the interactive gallery and documentation to see the components in action.

Why Lit Web Components?

When building complex, high-frequency audio visualizers (like real-time canvas waveforms), performance and bundle size are critical. By leveraging Lit and native Web Components, this library offers distinct advantages:

Microscopic Footprint: No massive framework runtimes. Lit simply provides lightweight, reactive syntactic sugar over standard browser APIs.
Blazing Fast Canvas & Audio: Direct DOM access means no Virtual DOM bottlenecks when piping 60fps data directly into <canvas> elements.
Framework Agnostic: Compiles to standard HTML tags. Drop these into React, Vue, Angular, Svelte, or vanilla HTML with zero friction.
Atomic Design: Organized into Atoms, Molecules, Organisms, and Providers for maximum reusability.

How to Use (For AI Agents)

If you are an AI coding agent integrating this library into an application, please refer to the AGENT_SKILL.md for specialized integration protocols, state management patterns, and "Zero-JS" branding guidelines.

How to Use (For Users)

1. Installation

npm install @ghchinoy/lit-audio-ui

2. Import the Library

// Import the entire library
import '@ghchinoy/lit-audio-ui';

// Or import specific categories for better tree-shaking
import '@ghchinoy/lit-audio-ui/atoms/ui-audio-play-button.js';
import '@ghchinoy/lit-audio-ui/molecules/ui-live-waveform.js';

4. Required Fonts & Icons

This library utilizes Material Symbols for iconography. Ensure you include the font in your document <head>:

<link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,[email protected],100..700,0..1,-50..200" rel="stylesheet" />

3. Use in HTML

Once imported, custom elements are registered and used like standard HTML tags:

<!-- Example: A voice recording button -->
<ui-voice-button state="idle" label="Start Recording"></ui-voice-button>

<!-- Example: An audio visualizer canvas linked to an AnalyserNode -->
<ui-live-waveform .analyserNode="${myAudioAnalyser}"></ui-live-waveform>

Available Components

🧪 Atoms (Primitives)

<ui-audio-play-button>: Context-aware play/pause toggle with dynamic ARIA labels.
<ui-audio-next-button> / <ui-audio-prev-button>: Playlist navigation buttons.
<ui-audio-progress-slider>: Reactive scrubber for playback.
<ui-audio-volume-slider>: Mute toggle and volume control.
<ui-audio-player-error>: Visual indicator for resource loading or playback failures.
<ui-speech-record-button>: Atomic trigger for recording context.
<ui-speech-cancel-button>: Discards current recording state.
<ui-timed-text>: Transcript renderer with word-level highlighting.
<ui-shimmering-text>: Pure CSS text loading effect.

🧬 Molecules (Functional Units)

<ui-live-waveform>: Real-time visualizer for an active AudioContext.
<ui-scrolling-waveform>: Infinite, smooth-scrolling audio visualization.
<ui-spectrum-visualizer>: Traditional frequency-bar spectrum.
<ui-orb>: 3D WebGL (Three.js) agent visualizer with distinct states.
<ui-voice-pill>: Compact, unified voice interaction widget.
<ui-conversation-bar>: Complex bar for mic selection, visualization, and text input.
<ui-playlist>: Reactive list component for queue management.
<ui-mic-selector>: Hardware enumeration and permission handler.
<ui-voice-picker>: Searchable persona selector with audio previews.

🧩 Providers (State)

<ui-audio-provider>: Headless state machine for playback, playlists, and transcripts.
<ui-speech-provider>: Headless lifecycle manager for voice recording.
- Hardware Selection: Accepts an optional deviceId string property to bypass the system default microphone and request specific hardware (perfect for integrating with <ui-mic-selector>).
- Manual Mode: Accepts a manual boolean property. When true, it stops imperatively calling getUserMedia and instead emits intent events (@speech-request-start) allowing your application to orchestrate WebAudio nodes for duplex streaming.

♿ Accessibility

This library is designed to be accessible out-of-the-box:

Dynamic ARIA Labels: Stateful buttons (e.g., Play/Pause, Mute/Unmute) automatically update their aria-label to reflect the current state for screen readers.
Keyboard Navigation: All interactive elements support standard keyboard focus and activation.
High Contrast: Visualizers and text elements use Material 3 design tokens, ensuring high visibility in both light and dark modes.

🎨 Theming & Spacing

Customize colors, typography, and layout density via standard CSS variables:

:root {
  /* Colors (Material Design 3) */
  --md-sys-color-primary: #0066cc;
  
  /* Component Specific */
  --ui-speech-record-color: #ff4444;
  --ui-audio-error-color: #ba1a1a;

  /* Density & Spacing */
  --ui-audio-player-padding: 8px 16px; /* Create a compact player */
  --ui-audio-player-gap: 8px;
  --ui-audio-player-width: 100%; /* Allow player pill to be responsive */
  --ui-audio-player-slider-width: 200px; /* Base width for the slider, which flexes */
  --ui-message-bubble-padding: 12px 16px;
}

🔌 Framework Integration

While built with Lit, these are standard Web Components. For seamless integration with React (hooks), Vue, or Svelte, see our Framework Integration Guide.

📚 Samples & Demos

Check out the following resources in the repository:

Interactive Gallery: Comprehensive showcase of all components.
Reference A2UI Agent: A minimalist implementation for AI agents to follow.

Acknowledgements

Deeply inspired by the beautiful, open-source audio components built by ElevenLabs (@elevenlabs/ui). This project reimplement those designs as standard, universal browser APIs.

License

Apache 2.0; see LICENSE for details.