waveform_pro #

A production-quality Flutter waveform widget with GPU-accelerated rendering, zoom, region selection, cue markers, and audio peak extraction.

Features #

• ⚡ GPU-accelerated rendering — multi-resolution pyramid cache for efficient drawing at any zoom level
• 🔍 Pinch-to-zoom & scroll — zoom into micro-detail or see the full track
• 🎯 Region selection — highlight and select portions of the waveform
• 📌 Cue markers — annotate the timeline with labeled bookmarks
• 📏 Time ruler — adaptive tick marks that respond to zoom level
• 🎨 Fully customizable styling — colors, sizes, stroke widths
• 📱 Touch-optimized — gestures designed for mobile interaction
• 🔊 Peak extraction — utilities for WAV, PCM, and FFmpeg audio sources

Installation #

dependencies:
  waveform_pro: ^1.0.0

Or use a Git dependency:

dependencies:
  waveform_pro:
    git:
      url: https://github.com/govindtank/waveform_pro.git

Quick Start #

import 'package:waveform_pro/waveform_pro.dart';

// Generate synthetic waveform data for demo
final data = WaveformData.generate(
  sampleCount: 3000,
  durationSeconds: 30,
);

// Or extract from real audio:
// final bytes = await File('audio.wav').readAsBytes();
// final data = PeakExtractor.fromWavBytes(bytes);

// Display with full interactive features
WaveformTimeline(
  data: data,
  height: 140,
  style: const WaveformStyle(
    waveColor: Color(0xFF4CAF50),
  ),
  onTap: (time) => print('Tapped at $time s'),
  enableZoom: true,
  enableMarkers: true,
);

Controller Usage #

Create a WaveformController to programmatically control zoom, scroll, regions, and markers.

final controller = WaveformController(
  initialPixelsPerSample: 2.0,
  maxPixelsPerSample: 100.0,
  minPixelsPerSample: 0.1,
);

WaveformTimeline(
  data: data,
  controller: controller,
  height: 140,
);

// Later — zoom, scroll, and reset programmatically
controller.zoomIn();          // 1.5x zoom in (default factor)
controller.zoomOut(2.0);      // 2x zoom out
controller.resetZoom();       // fit all in viewport
controller.scrollToTime(15);  // jump to 15-second mark

// Listen for state changes
controller.onZoomChanged = (pps) => print('Zoom: $pps px/sample');
controller.onScrollChanged = (offset) => print('Scrolled to $offset px');

// Query current state
final (startTime, endTime) = controller.visibleTimeRange;
print('Visible: ${startTime}s – ${endTime}s');

Regions & Markers #

Programmatically add and manage highlighted regions and cue markers.

final controller = WaveformController();

// Highlight a region from 20% to 50% of the track
controller.addRegion(WaveformRegion(
  startFraction: 0.2,
  endFraction: 0.5,
  color: Color(0x402196F3),
  label: 'Chorus',
));

// Place a cue marker at 75%
controller.addMarker(CueMarker(
  positionFraction: 0.75,
  label: 'Outro',
  color: Colors.red,
));

// Read them back
for (final r in controller.regions) {
  print('Region: ${r.startFraction} – ${r.endFraction}');
}
for (final m in controller.markers) {
  print('Marker: ${m.label} at ${m.positionFraction}');
}

// Clear
controller.clearRegions();
controller.clearMarkers();

WaveformTimeline(
  data: data,
  controller: controller,
  enableRegionSelection: true,
  enableMarkers: true,
  onRegionChanged: (start, end) {
    print('Region selected: ${start}s – ${end}s');
  },
);

Peak Extraction #

Extract waveform data from real audio files.

import 'dart:io';
import 'package:waveform_pro/waveform_pro.dart';

// From WAV file bytes
final bytes = await File('recording.wav').readAsBytes();
final wavData = PeakExtractor.fromWavBytes(bytes);

// From raw PCM float samples (e.g. from FFmpeg pipe)
final rawSamples = <double>[/* ... -1.0 to 1.0 ... */];
final pcmData = PeakExtractor.fromPcmFloats(
  rawSamples,
  sampleRate: 44100,
  targetSamples: 2000,
);

// Use the extracted data
WaveformTimeline(
  data: wavData,
  height: 140,
);

Full Example #

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

void main() => runApp(const MyApp());

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: const Text('Waveform Pro')),
        body: Padding(
          padding: const EdgeInsets.all(16),
          child: WaveformTimeline(
            data: WaveformData.generate(),
            controller: WaveformController(),
            enableZoom: true,
            enableMarkers: true,
          ),
        ),
      ),
    );
  }
}

API Reference #

WaveformData #

Holds peak samples with a multi-resolution pyramid cache for efficient rendering at any zoom level.

WaveformTimeline #

The main interactive waveform widget.

WaveformController #

Manages zoom, scroll, region selections, and cue markers programmatically.

WaveformStyle #

Visual styling for the waveform.

WaveformRegion #

A selected portion of the waveform.

CueMarker #

A labeled bookmark on the waveform timeline.

PeakExtractor #

Static utility methods for extracting waveform data from audio sources.

Audio Source Notes #

For production use, extract peaks on a server or via FFmpeg:

• Mobile: Use ffmpeg_kit_flutter to extract raw PCM → PeakExtractor.fromPcmFloats()
• Desktop: Use dart:io Process + FFmpeg -f f32le output
• Server: Any audio processing library → export as JSON peak array

Testing #

flutter test

License #

Apache 2.0