# Voice input
> Simulated dictation control with a mirrored pixel spectrum and words that fade into focus; stopping collapses the bars to a point.
- Element: `<px-voice>`
- React: `import { PxVoice } from "@/components/lumesec/px-voice"`
- Collection: Pixel Lab (https://elements.lumesec.ai/components/pixel-lab)
- Registry item: https://elements.lumesec.ai/r/px-voice.json
- Page: https://elements.lumesec.ai/components/pixel-lab/voice



Live preview: https://elements.lumesec.ai/view/px-voice

```html
<script type="module" src="https://elements.lumesec.ai/cdn/px-voice.js"></script>

<px-voice></px-voice>
```

## Playground

Change a prop and the component updates. Props marked live animate to the new value; the others rebuild the element.

## Installation

```bash
npx shadcn@latest add @lumesec/px-voice
```

First time with the @lumesec registry? Register it once, or install by URL:

```bash
npx shadcn@latest registry add @lumesec=https://elements.lumesec.ai/r/{name}.json
npx shadcn@latest add https://elements.lumesec.ai/r/px-voice.json
```

## Usage

React:

```tsx
import { PxVoice } from "@/components/lumesec/px-voice";

export function Example() {
  return (
    <PxVoice />
  );
}
```

HTML:

```html
<script type="module" src="https://elements.lumesec.ai/cdn/px-voice.js"></script>

<px-voice></px-voice>
```

## Behaviour

A mirrored pixel spectrum with falling peak dots, and words that drift into focus as they are recognised. Stopping collapses the bars into a line and the line into a point. The audio is simulated, since a shared page can’t use the microphone.

## API reference

### Attributes

| Attribute | React prop | Type     | Default                                                                                         | Description                                                                                         |
| --------- | ---------- | -------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `text`    | `text`     | `string` | `Make the trail grow out of the thumb toward the left and stop at three quarters of the track.` | The sentence the simulated recognition types out, split on spaces. Read each time listening starts. |

### Events

Events bubble and cross the shadow boundary unless the description says otherwise.

| Event        | React prop     | Detail             | Description                                                                    |
| ------------ | -------------- | ------------------ | ------------------------------------------------------------------------------ |
| `transcript` | `onTranscript` | `{ text: string }` | Fires when listening stops, with the words recognised so far joined by spaces. |

### Methods

Call them on the element, for example through a React ref.

| Method    | Description                                                                                         |
| --------- | --------------------------------------------------------------------------------------------------- |
| `start()` | Clears the transcript and starts the simulated listening. Ignored while the closing animation runs. |
| `stop()`  | Stops listening and fires `transcript`. Only acts while listening.                                  |

### Properties

| Property               | Type     | Description                                    |
| ---------------------- | -------- | ---------------------------------------------- |
| `sentence` (read-only) | `string` | The `text` attribute, or the default sentence. |

## Accessibility

* The mic is a native button whose `aria-label` switches between "Start dictation" and "Stop dictation".
* The transcript paragraph is an `aria-live="polite"` region, so recognised words are announced as they arrive.
* The spectrum canvas has no role or label.
* Reduced motion: the mic's pulsing ring and the word fade-in are disabled and the status text swaps without the roll; the spectrum still animates.

## Theming

The element reads your shadcn theme tokens through its shadow root, so light and dark follow your theme. The accent comes from `--lumesec`. See [Theming](/docs/theming).

This component reads `--border`, `--card`, `--foreground`, `--lumesec`, `--lumesec-foreground` and `--muted-foreground`.

To restyle only LumeSec elements, set the matching `--ui-*` overrides: `--ui-accent`, `--ui-border`, `--ui-fg`, `--ui-muted`, `--ui-on-accent` and `--ui-surface`.

## Notes

* No microphone is used. Audio levels are generated and the transcript is the `text` attribute revealed word by word; listening stops on its own 0.7 seconds after the last word.
* The host carries `data-state="listening"` or `data-state="closing"` during those phases.