Waveforms Audio #

Flutter audio visualizers for voice chat, assistants, music, and waveform previews. The package turns PCM samples into animated shapes. Your app supplies the audio; recording, playback, microphone permissions, and compressed audio decoding stay in your app or audio SDK. Runtime code depends only on Flutter.

Install #

Requires Flutter 3.47.0 or newer and Dart 3.13.0 or newer within Dart 3.x.

dependencies:
  waveforms_audio: ^0.2.1

Run flutter pub get, then import:

import 'package:waveforms_audio/waveforms_audio.dart';

Choose a widget #

Quick start: audio from an API #

Flow: audio source → controller → widget. Create the controller once, outside build(). Describe the actual source format; this example expects 24 kHz, mono, signed PCM16, little-endian, without a WAV or other container header.

import 'dart:async';
import 'package:flutter/material.dart';
import 'package:waveforms_audio/waveforms_audio.dart';

class ApiVoiceView extends StatefulWidget {
  // Supply a stable stream from your audio SDK or WebSocket.
  const ApiVoiceView({super.key, required this.pcmStream});

  final Stream<List<int>> pcmStream;

  @override
  State<ApiVoiceView> createState() => _ApiVoiceViewState();
}

class _ApiVoiceViewState extends State<ApiVoiceView> {
  late final ReactiveAudioController audio;
  StreamSubscription<List<int>>? input;

  @override
  void initState() {
    super.initState();
    audio = ReactiveAudioController(
      format: const AudioFormat(
        encoding: AudioEncoding.pcm16,
        sampleRate: 24000,
      ),
    );
    // Attach the visualizer before forwarding input to the broadcast controller.
    WidgetsBinding.instance.addPostFrameCallback((_) {
      if (!mounted) return;
      input = widget.pcmStream.listen(
        audio.addBytes,
        onError: (Object error, StackTrace stack) => audio.addError(error, stack),
        onDone: audio.flush,
      );
    });
  }

  @override
  Widget build(BuildContext context) => VoiceChatVisualizer(
    controller: audio,
    speaker: VoiceChatSpeaker.remote,
    style: const VoiceVisualizerStyle.ribbon(
      colors: [Colors.blue, Colors.cyan, Colors.purple],
    ),
    onError: (error, stack) => debugPrint('Audio input failed: $error'),
  );

  @override
  void dispose() {
    final subscription = input;
    if (subscription != null) unawaited(subscription.cancel());
    unawaited(audio.dispose());
    super.dispose();
  }
}

Mount it with ApiVoiceView(pcmStream: yourPcmStream) inside your Flutter app. Keep that stream stable for the lifetime of this example, or give the view a new key when replacing the source. Start live audio after the view subscribes: neither the controller nor a broadcast input replays earlier events. A visualizer manages its own subscription but does not dispose a controller you supplied.

Feed remote/AI PCM at playback time so the animation follows what the user hears. MP3, AAC, Opus, and container files must first be decoded to headerless PCM.

Audio formats and input functions #

AudioFormat #

For stereo input use channels: 2; channel: 1 selects the right channel. The channel index must be less than channels. Decoding clamps finite values to -1–1 and replaces nonfinite Float32 values with zero.

ReactiveAudioController #

Constructor: ReactiveAudioController({required format, sampleRate}). format describes source PCM; optional sampleRate fixes the output rate and defaults to format.sampleRate. Rates must be positive; reactive widgets require at least 8000 Hz. Encoding and channel layout remain fixed for the controller.

Add methods and flush() throw StateError after closure. Invalid source rates throw ArgumentError. Stop/cancel upstream input before disposing. Closing can wait for a paused listener to resume; the controller cannot be reopened.

Resampling and segment boundaries #

final audio = ReactiveAudioController(
  format: const AudioFormat(
    encoding: AudioEncoding.pcm16,
    sampleRate: 24000,
  ),
  sampleRate: 48000, // Fixed output rate.
);

// Examples: choose the input form provided by your source.
audio.addBytes(pcmBytes, sourceSampleRate: 16000);
audio.addBase64(base64Pcm, sourceSampleRate: 24000);
audio.addSamples(monoSamples, sourceSampleRate: 44100);
audio.flush(); // End of an utterance/independent segment.

sourceSampleRate defaults to format.sampleRate on each call; an override is not sticky. Rate changes flush the previous segment and discard incomplete PCM frames. Keep chunks of one continuous source at the same rate. Call flush() at an utterance boundary, or resetDecoder() to drop unfinished audio. Output chunk sizes can differ from input sizes; an input chunk may produce no output.

The lightweight linear resampler preserves timing across chunks, including 16/24/44.1/48 kHz conversions. It is intended for visualization and does not apply an anti-aliasing filter for high-fidelity downsampling.

Low-level adapters #

These exported helpers work without widgets or a controller.

AudioDecoder and Pcm16Decoder do not resample. PcmResampler does not clamp, decode, or sanitize its input; use the controller when those steps are needed.

Reactive widget parameters #

Both widgets accept either controller or audioStream + sampleRate. For direct streams, samples must be normalized mono PCM, not FFT bins or peaks. The rate must match the supplied samples; it is unrelated to screen refresh rate.

ReactiveAudioVisualizer(
  audioStream: monoPcmStream, // Stream<List<double>>
  sampleRate: 48000,
  style: const VoiceVisualizerStyle.wave(),
  motionPreset: AudioMotionPreset.music,
);

Shared parameters #

Voice activity is a heuristic from audio level and voice-band energy, not a probability from a speech-recognition model or a speaker identity detector. System reduced-motion settings disable continuous deformation and speaker-color animation while preserving incoming audio state.

ReactiveAudioVisualizer extras #

Analysis spans approximately 60 Hz to the smaller of 16 kHz and half the sample rate. Larger FFT windows improve frequency resolution but increase work. Replacing the source or analysis settings resets analysis; the widget replaces its stream subscription when the source changes.

VoiceChatVisualizer extras #

Explicit style.colors overrides speaker palettes. For three/four-stop gradients, set style.colors. VoiceChatSpeakerColors exposes the default palette through VoiceChatSpeaker.local.colors and .remote.colors. Changing speaker does not switch audio streams: your app chooses the appropriate controller/source.

VoiceChatVisualizer(
  controller: activeAudio,
  speaker: isRemoteSpeaking
      ? VoiceChatSpeaker.remote
      : VoiceChatSpeaker.local,
  localColors: const [Colors.blue, Colors.cyan],
  remoteColors: const [Colors.red, Colors.orange],
  style: const VoiceVisualizerStyle.halo(),
);

This wrapper uses the reactive widget's default FFT size, band count, and silence timeout. Use ReactiveAudioVisualizer when you need to tune those values. For simultaneous speakers, render one visualizer per feed or choose one feed to drive a shared widget.

Styles and their parameters #

VoiceVisualizerStyle holds visual settings. Named constructors choose defaults; the generic constructor and copyWith() expose every field. Treat supplied color lists as immutable. Equality compares all fields and color contents.

All style fields #

Fields apply where the selected shape supports them. Bars, wave, dots, capsules, and minimal line interpret direction; radial shapes keep radial geometry. Ribbon and mirror spectrum retain their own layouts. Spacing/corner radius do not reshape fluid effects. Halo has 12–192 rays and bloom 6–12 lobes after density/capping; fixed wave/ribbon layers and some shader effects do not use barCount.

Named constructors and defaults #

Every named constructor accepts colors, inactiveColor, glow, density, and symmetric. The table shows all remaining exposed parameters and any changed common defaults. Values not listed use density: 1, symmetric: true, empty colors, and no inactive color. Constructor names also name the VoiceVisualizerKind values.

copyWith({kind, colors, inactiveColor, clearInactiveColor, barCount, spacing, cornerRadius, glow, density, symmetric, direction}) preserves omitted/null values. clearInactiveColor: true removes the resting color even if an inactiveColor is also supplied. Changing kind preserves existing configuration; it does not apply the new kind's named-constructor defaults.

final style = const VoiceVisualizerStyle.bars(
  colors: [Colors.blue, Colors.cyan, Colors.purple, Colors.pink],
  inactiveColor: Colors.grey,
).copyWith(barCount: 40, spacing: 2, clearInactiveColor: true);

Motion controls #

AudioMotionPreset provides .voice, .music, .ambient, and .energetic. Use AudioMotionSettings.preset(preset) as a starting point, then copyWith() to change individual settings. Supplying motion replaces the widget preset entirely.

Use positive attack/release durations for stable interpolation. copyWith() accepts every constructor field; null preserves its value. Settings support value equality. Preset durations below are milliseconds, shown as attack/release pairs.

final motion = AudioMotionSettings.preset(AudioMotionPreset.voice).copyWith(
  noiseGate: 0.01,
  idleBreathing: 0,
  peakHold: const Duration(milliseconds: 140),
);

ReactiveAudioVisualizer(controller: audio, motion: motion);

Rendering and shader loading #

GPU styles: orb, wave, halo, ribbon, liquidOrb, pulseRings, voiceBloom. Other styles use Canvas. While shaders load, when loading fails, or when a palette has more than four colors, widgets use Canvas. One through four GPU color stops retain intermediate colors. Geometry, lighting, and some style controls remain renderer-specific; outputs are not pixel-identical. Halo and bloom use a seamless spatial gradient rather than a discontinuous angular palette.

Future<void> precacheWaveformsAudioShaders() optionally loads the cached program before displaying a visualizer. Call after Flutter binding initialization. It has no arguments and propagates loading errors; widgets themselves handle failures by falling back to Canvas. Example optional warmup:

WidgetsFlutterBinding.ensureInitialized();
try {
  await precacheWaveformsAudioShaders();
} catch (_) {
  // Canvas remains available if this platform cannot load the shader.
}

No extra shader declaration is needed in the consuming app. Audio decoding, analysis, envelope updates, and scheduling run on the CPU for both renderers.

Classic waveform API #

AudioData and AudioProcessor #

Use finite samples. Empty input or nonpositive bucketCount returns empty data. The bucket count is capped to input length. maxAmplitude retains the original largest peak before normalization; extraction is for visual buckets, not PCM sample-rate conversion.

AudioVisualizer #

AudioVisualizer(
  audioData: AudioProcessor.extractPeaks(samples, 100),
  type: VisualizerType.linear,
  spacing: 4,
  strokeWidth: 3,
  animatePulsate: true,
);

New data eases from the displayed snapshot. A changed sample count, zero transition duration, or system reduced motion causes an immediate update. Reduced motion also stops pulse and rotation loops.

LiveAudioVisualizer #

Accepts the same key, size, type, strokeWidth, spacing, animatePulsate, animateRotation, animationDuration, and transitionDuration parameters/defaults as AudioVisualizer, with these differences:

LiveAudioVisualizer(
  audioStream: monoPcmStream,
  windowSize: 80,
  type: VisualizerType.linear,
);

Each nonempty chunk contributes its largest finite absolute sample, clamped to 0–1. History starts with zeros; its duration depends on chunk arrival cadence. Changing the stream replaces the subscription while retaining history. Resizing trims old buckets or prepends zeros. The widget cancels its subscription on dispose but does not close your source. Handle input errors upstream: this widget has no onError parameter.

Troubleshooting #

Example, API docs, and checks #

cd example
flutter run

The example offers microphone input and synthetic signals. Microphone audio stays in memory and is not uploaded or saved by the example.

Public API is exported from package:waveforms_audio/waveforms_audio.dart. Canvas painters and analysis internals under src/ are implementation details. Dart documentation comments provide IDE help for constructors, fields, and methods.

From the package root:

flutter analyze
flutter test
(cd example && flutter test)
dart doc

dart doc writes browsable API documentation under doc/api/.