# Agent Skill: Lit Audio UI Integration A specialized skill for AI agents to autonomously implement high-performance audio visualizations and controls using the `@ghchinoy/lit-audio-ui` library. ## Capabilities - Orchestrate complex audio playback using a headless provider. - Implement real-time 2D and 3D audio visualizations (Orb, Waveforms, Spectrum). - Construct accessible, theme-aware audio interfaces. - Manage multi-track playlists with automatic state synchronization. ## Protocol: The "Lit Way" ### 1. Bootstrapping the Provider Always wrap atomic components in a `` (for playback) or `` (for recording). These components manage the state machine and shared context. ### 2. Registry Collision Mitigation (CRITICAL) In plain HTML/back-end environments (Go, Python), browsers may crash if Material Web components are loaded multiple times (e.g., `md-elevation` error). - **Solution:** Use a "Fat Bundle" (single-file library) OR an **Import Map**. - **Import Map Example:** ```html ``` ### 3. State-Driven Visuals (The "Sentiment" Pattern) Drive visual components like `` using application-specific logic. - **Pattern:** Map market/AI sentiment to the `colors` property. - **Example:** Green ramps for `improving`, red/warm ramps for `worsening`. - **Manual Mode:** Set `volumeMode="manual"` to explicitly pass `inputVolume` (mic) and `outputVolume` (agent) for precise synchronization. ### 4. Visualizer "Bridge" Logic Most visual components require an `analyserNode`. - They attempt to consume this from context automatically. - **Tip:** When bridging to Gemini Live, manually map the PCM byte stream volume to the orb's `inputVolume` or `outputVolume`. ### 5. Theming & Branding (Zero-JS) The library uses Material Design 3 tokens. Use these for dark-theme consistency: - `--md-sys-color-primary`: Main theme color. - `--ui-speech-wave-color`: Custom color for waveforms inside buttons. ### 6. Component Utility Registry - ``: Use `format="elapsed"` or `format="remaining"` for single values. - ``: Requires a `.height` property for reliable rendering. ## Simulation Mode For development without microphone access, enable the `simulation` property on ``. This generates procedural audio data and mock transcription events. ## Quality Gates - **CORS:** Ensure `crossorigin="anonymous"` is set on audio/video tags. - **Layout:** Use `positioning="popover"` for `md-menu` inside 3D containers. - **Performance:** In plain HTML projects, prefer the single-file `.es.js` bundle to minimize network waterfall. ### 7. Explicit Typings for Strict Mode (GTS) When integrating into strict TypeScript environments, explicitly type your providers to avoid `Unexpected any` errors. ```ts import type { AudioProviderElement, SpeechProviderElement } from '@ghchinoy/lit-audio-ui'; const audioEl = document.querySelector('ui-audio-provider') as AudioProviderElement; if (audioEl.state.isPlaying) { audioEl.pause(); } ``` ### 8. Required Fonts & Icons Do not forget to inject the Material Symbols font into the host document's ``, otherwise icons (play, pause, volume) will render as fallback text: ```html ``` ### 9. Component API Enhancements (v0.4.17+) - **Streaming Audio Waveforms:** For long/streamed audio where the browser cannot decode the full buffer, use the `peaks` property on `` and ``. Provide a lightweight array of floats (0.0 to 1.0) generated by your backend to bypass client-side decoding. - **Vertical Volume Slider:** Use `` to conserve horizontal space in compact music players. ### 10. Advanced Styling with CSS Parts (v0.4.18+) - **Transparent Progress Overlays:** The `` exposes its internal Material slider via `part="slider"`. This allows you to create "Producer Bar" layouts by setting `--md-slider-inactive-track-color: transparent` and layering it directly over a ``. - **Waveform Alignment:** Use `align="bottom"` on static or scrolling waveforms to draw bars upwards from the bottom of the container, rather than the default vertically-centered mirrored style. ### 11. Interactive UX (v0.4.19+) - **Hover Timestamps:** To give users precision seeking capabilities, add `hoverTimestamp="true"` to ``. This will automatically render a floating `MM:SS` tooltip above the cursor based on the context's total duration.