@ghchinoy/lit-audio-ui 0.4.2 → 0.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +41 -105
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -2,51 +2,40 @@
2
2
 
3
3
  A lightweight, framework-agnostic Web Components library for high-performance audio visualization and control, built natively for the browser using [Lit](https://lit.dev/).
4
4
 
5
- Take a look at the [examples and documentation](https://ghchinoy.github.io/scream-ui/) to see the components in action.
5
+ Take a look at the [interactive gallery and documentation](https://ghchinoy.github.io/scream-ui/) to see the components in action.
6
6
 
7
7
  ## Why Lit Web Components?
8
8
 
9
- When building complex, high-frequency audio visualizers (like real-time canvas waveforms), performance and bundle size are critical. Traditional React/ShadcnUI libraries often bring significant overhead due to Virtual DOM reconciliation loops and heavy CSS framework dependencies (like Tailwind).
10
-
11
- By leveraging **Lit** and native Web Components, this library offers distinct advantages:
9
+ 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:
12
10
 
13
11
  * **Microscopic Footprint:** No massive framework runtimes. Lit simply provides lightweight, reactive syntactic sugar over standard browser APIs.
14
- * **Blazing Fast Canvas & Audio:** Direct DOM access means no Virtual DOM bottlenecks when piping 60fps `AnalyserNode` data directly into `<canvas>` elements.
15
- * **Framework Agnostic:** Because they compile to standard HTML tags (e.g., `<ui-live-waveform>`), you can drop these components into **any** frontend stack—React, Vue, Angular, Svelte, or vanilla HTML—with zero friction.
16
- * **Scoped Styling:** Uses standard CSS variables and Material Design 3 tokens. No Tailwind installation, complex class merging, or CSS-in-JS runtime required.
17
- * **Atomic Composition:** Powered by `@lit/context`, the complex monolithic audio players are broken down into atomic, highly composable state machines.
18
-
12
+ * **Blazing Fast Canvas & Audio:** Direct DOM access means no Virtual DOM bottlenecks when piping 60fps data directly into `<canvas>` elements.
13
+ * **Framework Agnostic:** Compiles to standard HTML tags. Drop these into React, Vue, Angular, Svelte, or vanilla HTML with zero friction.
14
+ * **Atomic Design:** Organized into **Atoms, Molecules, Organisms, and Providers** for maximum reusability.
19
15
 
20
- ## How to Use the Lit Components (For Users)
16
+ ## How to Use (For AI Agents)
21
17
 
22
- As a Web Components library, you can use these elements directly in your HTML or inside any frontend framework.
18
+ If you are an AI coding agent integrating this library into an application, please refer to the [AGENT_SKILL.md](https://github.com/ghchinoy/scream-ui/blob/main/packages/lit-audio-ui/AGENT_SKILL.md) for specialized integration protocols, state management patterns, and "Zero-JS" branding guidelines.
23
19
 
20
+ ## How to Use (For Users)
24
21
 
25
22
  ### 1. Installation
26
- Install the package via npm:
27
23
  ```bash
28
24
  npm install @ghchinoy/lit-audio-ui
29
25
  ```
30
26
 
31
- ### 2. Usage (CDN)
32
- For a zero-install experience, you can use the library directly from a CDN like [esm.run](https://esm.run/):
33
- ```html
34
- <script type="module" src="https://esm.run/@ghchinoy/lit-audio-ui"></script>
35
- ```
36
-
37
- ### 3. Import the Library (Bundlers)
38
- Import the components into your JavaScript/TypeScript entry point:
27
+ ### 2. Import the Library
39
28
  ```javascript
40
29
  // Import the entire library
41
30
  import '@ghchinoy/lit-audio-ui';
42
31
 
43
- // Or import specific components
44
- import '@ghchinoy/lit-audio-ui/components/ui-voice-button';
45
- import '@ghchinoy/lit-audio-ui/components/ui-live-waveform';
32
+ // Or import specific categories for better tree-shaking
33
+ import '@ghchinoy/lit-audio-ui/atoms/ui-audio-play-button.js';
34
+ import '@ghchinoy/lit-audio-ui/molecules/ui-live-waveform.js';
46
35
  ```
47
36
 
48
- ### 4. Use in HTML
49
- Once imported, the custom elements are registered with the browser and can be used like standard HTML tags:
37
+ ### 3. Use in HTML
38
+ Once imported, custom elements are registered and used like standard HTML tags:
50
39
 
51
40
  ```html
52
41
  <!-- Example: A voice recording button -->
@@ -56,98 +45,45 @@ Once imported, the custom elements are registered with the browser and can be us
56
45
  <ui-live-waveform .analyserNode="${myAudioAnalyser}"></ui-live-waveform>
57
46
  ```
58
47
 
59
- ### 5. Theming (Material Design 3)
60
- These components are deeply theme-aware and utilize Material Design 3 design tokens. To customize their colors (or support light/dark modes), simply define the CSS variables in your stylesheet:
61
-
62
- ```css
63
- :root {
64
- --md-sys-color-primary: #0066cc;
65
- --md-sys-color-on-primary: #ffffff;
66
- --md-sys-color-surface-container: #f3f3f3;
67
- /* ...other MD3 tokens */
68
- }
69
-
70
- .dark {
71
- --md-sys-color-primary: #a8c7fa;
72
- --md-sys-color-on-primary: #003062;
73
- --md-sys-color-surface-container: #212121;
74
- }
75
- ```
76
-
77
48
  ## Available Components
78
49
 
79
- The library currently ships with the following native WebComponents:
80
-
81
- * 🎙️ **`<ui-voice-button>`**: A compound interactive button that dynamically mounts a live visualizer depending on its state. Cycles gracefully through `idle`, `recording`, `processing`, `success`, and `error` states.
82
- * 📊 **`<ui-waveform>`**: A static, pre-computed scrubbable waveform timeline for audio playback visualization.
83
- * 🌊 **`<ui-live-waveform>`**: A real-time visualizer that responds to an active `AudioContext`. Includes aggressive noise-gating, center-out mirroring, and a synthetic "processing" animation state.
84
- * 〰️ **`<ui-scrolling-waveform>`**: An infinitely scrolling procedural audio visualization animation. Perfect for active "listening" states where a live `AnalyserNode` is unavailable.
85
- * 🎵 **`<ui-audio-player>`**: A classic monolithic pill-shaped audio player.
86
- * 🧩 **Compound Audio Architecture**: Use `<ui-audio-provider>`, `<ui-audio-play-button>`, `<ui-audio-progress-slider>`, and `<ui-audio-time-display>` to construct entirely custom audio layouts powered by a headless state machine via `@lit/context`.
87
- * ✨ **`<ui-shimmering-text>`**: A pure CSS, dependency-free text loading effect translating complex gradients into native `@keyframes`.
88
- * 🎛️ **`<ui-mic-selector>`**: Handles hardware microphone enumeration (`navigator.mediaDevices`), permissions, and displays a live audio preview directly inside a dropdown menu.
89
- * 🎭 **`<ui-voice-picker>`**: A searchable dropdown menu (combobox) that handles rendering complex persona objects, including real-time audio previews injected directly into the menu items.
90
- * 🗣️ **Atomic Speech Architecture**: Use `<ui-speech-provider>`, `<ui-speech-record-button>`, `<ui-speech-preview>`, and `<ui-speech-cancel-button>` to build custom recording UIs (like the Smart Textarea) with built-in state management and visualization.
91
-
50
+ ### 🧪 Atoms (Primitives)
51
+ * **`<ui-audio-play-button>`**: Context-aware play/pause toggle.
52
+ * **`<ui-audio-next-button>` / `<ui-audio-prev-button>`**: Playlist navigation buttons.
53
+ * **`<ui-audio-progress-slider>`**: Reactive scrubber for playback.
54
+ * **`<ui-audio-time-display>`**: Flexible time visualizer (elapsed, remaining, combined).
55
+ * **`<ui-speech-record-button>`**: Atomic trigger for recording context.
56
+ * **`<ui-shimmering-text>`**: Pure CSS text loading effect.
92
57
 
93
- ## How to Build & Extend (For Developers)
58
+ ### 🧬 Molecules (Functional Units)
59
+ * **`<ui-live-waveform>`**: Real-time visualizer for an active `AudioContext`.
60
+ * **`<ui-spectrum-visualizer>`**: Traditional frequency-bar spectrum.
61
+ * **`<ui-orb>`**: 3D WebGL (Three.js) agent visualizer.
62
+ * **`<ui-3d-flip>`**: Layout utility for 3D card-flipping interactions.
63
+ * **`<ui-playlist>`**: Reactive list component for queue management.
64
+ * **`<ui-mic-selector>`**: Hardware enumeration and permission handler.
65
+ * **`<ui-voice-picker>`**: Searchable persona selector with audio previews.
94
66
 
95
- We welcome contributions! If you want to extend the components, tweak the canvas math, or add new visualizers, here is how you can get started.
67
+ ### 🧩 Providers (State)
68
+ * **`<ui-audio-provider>`**: Headless state machine for playback and playlists.
69
+ * **`<ui-speech-provider>`**: Headless lifecycle manager for voice recording (Auto, Simulation, or Manual mode).
96
70
 
97
- ### Prerequisites
98
- - Node.js (v18+)
99
- - npm or pnpm
71
+ ## Theming (Material Design 3)
100
72
 
101
- ### Local Development Setup
73
+ Customize colors and typography via standard CSS variables:
102
74
 
103
- 1. **Clone & Install**
104
- ```bash
105
- git clone <repository-url>
106
- cd packages/lit-audio-ui
107
- npm install
108
- ```
109
-
110
- 2. **Start the Dev Server**
111
- This will start a local Vite development server. It serves the `index.html` file, which acts as our component workbench and functional test bed.
112
- ```bash
113
- npm run dev
114
- ```
115
-
116
- 3. **Code Structure**
117
- - `/packages/lit-audio-ui/src/components/`: This is where the Lit elements (`.ts`) live. Each component should be self-contained with its scoped CSS (`static styles`).
118
- - `/packages/lit-audio-ui/src/utils/`: Shared utilities, such as the `AudioContext` and FFT math ported from the original ElevenLabs React repository.
119
- - `/packages/lit-audio-ui/demo/index.html`: The development workbench. Whenever you create a new component or port a feature, add a demo block here.
120
- - `/packages/lit-audio-ui/demo/demo-layouts.ts`: Complex composite examples and layout logic used in the workbench.
121
-
122
- ### Building for Production
123
- To compile the TypeScript and bundle the library for distribution:
124
- ```bash
125
- cd packages/lit-audio-ui
126
- npm run build
127
- ```
128
- This generates the optimized assets in the `/dist` folder.
129
-
130
- ### Linting
131
- We use `google/gts` (Google TypeScript Style) and the `eslint-plugin-lit` ruleset to enforce code quality and Lit best practices.
132
- ```bash
133
- cd packages/lit-audio-ui
134
- npm run lint
135
- npm run fix
75
+ ```css
76
+ :root {
77
+ --md-sys-color-primary: #0066cc;
78
+ --ui-speech-record-color: #ff4444; /* Custom branding */
79
+ --ui-speech-preview-font-size: 18px;
80
+ }
136
81
  ```
137
82
 
138
83
  ## Acknowledgements
139
84
 
140
- This project is deeply inspired by the beautiful, open-source audio components designed and built by **[ElevenLabs](https://elevenlabs.io/)** (`@elevenlabs/ui`).
141
-
142
- We are incredibly grateful for their contribution to the open-source community. Their original repository provided the foundational audio mathematics, canvas drawing logic, and WebGL shader configurations that make these visualizers look buttery smooth. While their library focuses heavily on the React ecosystem, this project reimagines those beautiful designs as standard, universal browser APIs.
85
+ Deeply inspired by the beautiful, open-source audio components built by **[ElevenLabs](https://elevenlabs.io/)** (`@elevenlabs/ui`). This project reimplement those designs as standard, universal browser APIs.
143
86
 
144
87
  # License
145
88
 
146
89
  Apache 2.0; see [`LICENSE`](LICENSE) for details.
147
-
148
-
149
- # Disclaimer
150
-
151
- This project is not an official Google project. It is not supported by
152
- Google and Google specifically disclaims all warranties as to its quality,
153
- merchantability, or fitness for a particular purpose.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ghchinoy/lit-audio-ui",
3
- "version": "0.4.2",
3
+ "version": "0.4.4",
4
4
  "description": "A pure Lit WebComponents port of modern audio UI components",
5
5
  "author": "G. Hussain Chinoy",
6
6
  "license": "Apache-2.0",