VoiceBeam

Usage

TxVoiceBeam wraps exactly one element that carries its own corner radius, clips it, and paints a sound-reactive beam along its bottom edge. Feed it a MediaStream from the microphone, or drive it manually with level.

Microphone Input

useMicrophone() produces the stream. It requests getUserMedia with echo cancellation, noise suppression and auto gain turned off, so the glow sees the real dynamics of the voice. Call start() from a click; browsers only grant the mic inside a user gesture.

<script setup lang="ts">
import { useMicrophone } from '@talex-touch/tuffex/pro'

const mic = useMicrophone()
const live = computed(() => mic.state.value === 'live')
</script>

<template>
  <TxVoiceBeam :stream="mic.stream.value" :processing="transcribing">
    <TxCard :radius="16" :padding="24" shadow="none">Ask anything…</TxCard>
  </TxVoiceBeam>
  <TxButton :aria-pressed="live" @click="live ? mic.stop() : mic.start()">
    {{ live ? 'Stop' : 'Listen' }}
  </TxButton>
</template>

Types and Palettes

type picks the host preset (default for a ~350 px chat input, pill for a recording pill, mobile for the bottom of a phone screen); every geometry prop still wins over it. colorVariant selects the palette and colors overrides individual lobes.

<template>
  <TxVoiceBeam type="pill" color-variant="ocean" :scale="0.9">
    <div class="pill">Recording…</div>
  </TxVoiceBeam>

  <TxVoiceBeam type="mobile" color-variant="candy" :level="() => 0.8">
    <div class="screen">Listening</div>
  </TxVoiceBeam>
</template>

Best Practices

• Never rely on the glow as the only sign that the mic is live: keep a text status and a visible mic button state (aria-pressed), and announce changes with role="status".
• Pass a getter (:level="() => meter.value"), not a reactive number read 60 times a second — the getter is sampled once per frame with no re-render.
• stream wins over level: a stream with an audio track always drives the beam.
• Wrap exactly one element that carries the radius, and put content that must stay crisp at position: relative; z-index: 5. Anything with its own overlay (popovers, menus) inside the wrapped element gets clipped — portal it out.
• Call mic.stop() when the voice UI closes; the composable only stops tracks on unmount.
• Keep instances few. Each one runs blurred layers and a canvas; the component is not for dense lists.

API Reference

Props

Slots

Events

Exposed Methods

No public instance methods.

CSS Variables

Overview

• The component wraps its slot content and clips it to the child's border-top-left-radius (16 px when none is found), so the beam hugs the element edge.
• One shared requestAnimationFrame loop drives every instance, capped at about 60 fps; an instance scrolled offscreen (256 px margin) unregisters and releases its analyser.
• One AudioContext is shared per page, one source node per stream (reference-counted) and one analyser per instance. Audio is analysed, never played.
• prefers-reduced-motion: reduce stops the idle breathing, the colour flow, the hue drift, the distortion warp and the processing sweep; the reaction to sound stays, since it is a meter.
• Under stream, the analyser reads the RMS level plus three voice bands (80-300, 300-2000, 2000-6000 Hz).

Technologies

• Manually verified against index.ts, TxVoiceBeam.vue, types.ts and voice-beam.test.ts under packages/tuffex/packages/components/src/voice-beam/.
• styles.ts, presets.ts, voice-driver.ts, audio.ts and color.ts are verbatim ports of upstream voice-glow (MIT © Jakub Antalik) with strict-TS index hardening only; the Vue shell mirrors the upstream wrapper's fade lifecycle, offscreen pause and radius detection.
• useMicrophone is the Vue port of the upstream React hook, with the same constraints and track lifecycle.
• Component source: packages/tuffex/packages/components/src/voice-beam/src/TxVoiceBeam.vue.
• Types: packages/tuffex/packages/components/src/voice-beam/src/types.ts.
• Upstream: Jakubantalik/Libraries · voice-glow (MIT).
• Coverage: packages/tuffex/packages/components/src/voice-beam/__tests__/voice-beam.test.ts verifies preset resolution, unknown-type fallback, the microphone state machine and the manual-level path.