flutter_soloud Audio Visualization

Visualization in flutter_soloud

flutter_soloud has two unrelated ways to get drawable sample data out of the SoLoud engine:

1. Live visualization — the engine emits AudioVisualizationData packets (waveform and/or FFT magnitudes of the mixed output) on a broadcast stream, at mixer rate. For real-time spectrum/waveform widgets.
2. Offline waveform reading — readSamplesFromFile / readSamplesFromMem decode an audio file in a background isolate and return a fixed number of equally-spaced samples. For static waveform previews (SoundCloud-style).

Pick the right one. The live stream cannot give you the waveform of a not-yet-played file; the offline readers cannot follow playback.

Minimal example (live FFT + wave)

import 'dart:async';

import 'package:flutter/material.dart';
import 'package:flutter_soloud/flutter_soloud.dart';

class Visualizer extends StatefulWidget {
  const Visualizer({super.key});
  @override
  State<Visualizer> createState() => _VisualizerState();
}

class _VisualizerState extends State<Visualizer> {
  StreamSubscription<AudioVisualizationData>? _sub;
  AudioVisualizationData? _data;

  @override
  void initState() {
    super.initState();
    _init();
  }

  Future<void> _init() async {
    await SoLoud.instance.init(); // must complete first
    SoLoud.instance.setVisualizationEnabled(
      true,
      windowSize: 256,
      kind: VisualizationKind.waveAndFft,
      channel: VisualizationChannel.merged,
    );
    SoLoud.instance.setFftSmoothing(0.8);
    _sub = SoLoud.instance.audioVisualizationEvents.listen((data) {
      if (mounted) setState(() => _data = data);
    });
  }

  @override
  void dispose() {
    _sub?.cancel();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    final fft = _data?.fftData; // Float32List? of windowSize/2 magnitudes
    if (fft == null) return const SizedBox(height: 100);
    return CustomPaint(
      size: const Size(double.infinity, 100),
      painter: BarsPainter(fft),
    );
  }
}

class BarsPainter extends CustomPainter {
  BarsPainter(this.fft);
  final Float32List fft;

  @override
  void paint(Canvas canvas, Size size) {
    final barWidth = size.width / fft.length;
    final paint = Paint()..strokeWidth = barWidth * 0.8;
    for (var i = 0; i < fft.length; i++) {
      final h = size.height * fft[i].clamp(0.0, 1.0);
      canvas.drawLine(
        Offset(i * barWidth + barWidth / 2, size.height),
        Offset(i * barWidth + barWidth / 2, size.height - h),
        paint,
      );
    }
  }

  @override
  bool shouldRepaint(BarsPainter oldDelegate) => true; // data changes every event
}

Minimal example (offline waveform)

import 'package:flutter/foundation.dart';
import 'package:flutter_soloud/flutter_soloud.dart';

// No SoLoud.instance.init() needed — the readers run their own decoder
// inside a `compute` isolate.
Future<Float32List> waveformBars(String path, Uint8List bytes, int bars) {
  if (kIsWeb) {
    // readSamplesFromFile does not exist on Web; feed it the bytes.
    return SoLoud.instance.readSamplesFromMem(bytes, bars, average: true);
  }
  return SoLoud.instance.readSamplesFromFile(path, bars, average: true);
}

A common choice for bars is the widget's pixel width (MediaQuery.sizeOf(context).width.toInt() * 4 in the plugin's example). Draw each value as a vertical line centered on the middle (see example/lib/wave_data/wave_data.dart).

The API shape

All on SoLoud.instance (singleton), imported from package:flutter_soloud/flutter_soloud.dart.

Live

• void setVisualizationEnabled(bool enabled, {int windowSize = 256, VisualizationKind kind = VisualizationKind.waveAndFft, int channel = VisualizationChannel.merged}) — turns the analyzer on/off. Must be called after init(); throws SoLoudNotInitializedException otherwise, SoLoudCppException on bad params.
• Stream<AudioVisualizationData> get audioVisualizationEvents — broadcast stream; emits one packet per mixer buffer while enabled.
• AudioVisualizationData — channelCount, wave (List<Float32List>, one per channel, length windowSize, values [-1.0, 1.0]), fft (List<Float32List>, one per channel, length windowSize / 2, magnitudes [0.0, 1.0]). Either list is empty if its kind is disabled. waveData / fftData are nullable convenience getters for wave.first / fft.first.
• VisualizationKind — real enum: wave, fft, waveAndFft.
• VisualizationChannel — not an enum, an abstract final class of int constants: merged = -1 (downmix to mono), all = -2 (per-channel lists), or pass any 0-based channel index (0 = left). There is no VisualizationChannel.values; don't switch over it.
• void setFftSmoothing(double smooth) — exponential decay on falling FFT bins, 0.0–1.0. Rise is never smoothed.
• double getApproximateVolume(int channel) — instantaneous overall output volume per output channel (speaker). Poll it on a Timer for a VU meter. Returns 0 for invalid channels.

Offline

• Future<Float32List> readSamplesFromFile(String completeFileName, int numSamplesNeeded, {double startTime = 0, double endTime = -1, bool average = false}) — native platforms only.
• Future<Float32List> readSamplesFromMem(Uint8List buffer, int numSamplesNeeded, {double startTime = 0, double endTime = -1, bool average = false}) — everywhere; buffer is the encoded file bytes (mp3/wav/flac/ogg, from assets, File.readAsBytes(), or a network fetch).
• Times are in seconds; endTime: -1 means "to end of file". average: true makes each returned value the mean of its time bucket instead of a single point sample — smoother waveforms, negligible cost.

Divergences from audioplayers / just_audio / web Audio API assumptions

• No AudioPlayer-style per-sound analyser. Live visualization taps the whole mixed engine output (all voices, post-filter), not an individual track.
• There is no onPositionChanged-style callback to hook FFT onto; you enable the analyzer once and consume a stream.
• getApproximateVolume is per output channel, not per voice — there is no built-in per-sound level meter.
• The offline readers don't require init() and don't need the sound loaded via loadMem/loadAsset first — they decode independently (asset bytes via rootBundle.load are fine).