diff --git a/CHANGELOG.md b/CHANGELOG.md index 3beb9051..c0193cad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,7 @@ ## 2.1.0 (#unreleased) - Feature [#468](https://github.com/SimformSolutionsPvtLtd/audio_waveforms/pull/468) - Add macOS support +- Feature [#91](https://github.com/SimformSolutionsPvtLtd/audio_waveforms/issues/91) - Add `WaveStyle.maxDuration` to bound recording waveform width proportionally ## 2.0.2 diff --git a/doc/documentation.md b/doc/documentation.md index a130d796..9de0ef4d 100644 --- a/doc/documentation.md +++ b/doc/documentation.md @@ -847,6 +847,34 @@ AudioWaveforms( ) ``` +## Bounded Recording Width + +By default the recording waveform scrolls once it reaches the middle of the +available width. Set `WaveStyle.maxDuration` to instead bound the waveform to a +fixed maximum duration: the waveform fills only +`elapsedRecordingDuration / maxDuration` of the width and never scrolls. For +example, with a `maxDuration` of 10 seconds, stopping the recording at 5 seconds +draws the waveform across half of the width; reaching 10 seconds fills the full +width (recording past it stays clamped to the full width). + +This is useful when you want the final waveform length to reflect how long the +recording is, relative to a cap. + +```dart +AudioWaveforms( + controller: recorderController, + size: Size(MediaQuery.of(context).size.width, 100), + waveStyle: const WaveStyle( + maxDuration: Duration(seconds: 10), + ), +) +``` + +> Note: `maxDuration` only applies to `WaveformRenderMode.ltr` (ignored for +> `rtl`, like `extendWaveform`) and takes precedence over `extendWaveform` when +> both are set. A non-positive value (`Duration.zero` or less) is ignored and +> falls back to the default scrolling behavior. + ## Waveform Gradients Apply gradients to waveforms: @@ -1708,6 +1736,7 @@ This section provides a quick reference for the main classes and their propertie | `durationLinesHeight` | `double` | - | Duration line height | | `gradient` | `Shader?` | `null` | Wave gradient | | `scaleFactor` | `double` | `20.0` | Wave scaling factor | +| `maxDuration` | `Duration?` | `null` | Bound recording width | ## PlayerWaveStyle (for Player) diff --git a/lib/src/audio_waveforms.dart b/lib/src/audio_waveforms.dart index 7943cc5a..a49f8c80 100644 --- a/lib/src/audio_waveforms.dart +++ b/lib/src/audio_waveforms.dart @@ -157,6 +157,7 @@ class _AudioWaveformsState extends State { scaleFactor: _waveStyle.scaleFactor, currentlyRecordedDuration: currentlyRecordedDuration, isRtl: _isRtl, + maxDuration: _waveStyle.maxDuration, ), ), ), diff --git a/lib/src/base/wave_style.dart b/lib/src/base/wave_style.dart index f75befe8..e13cb53d 100644 --- a/lib/src/base/wave_style.dart +++ b/lib/src/base/wave_style.dart @@ -31,6 +31,7 @@ class WaveStyle { this.gradient, this.scaleFactor = 20.0, this.waveformRenderMode = WaveformRenderMode.ltr, + this.maxDuration, }) : assert( waveThickness < spacing, "waveThickness can't be greater than spacing", @@ -133,4 +134,23 @@ class WaveStyle { /// to left. Older waves will be pushed to the left to make space for new /// waves. final WaveformRenderMode waveformRenderMode; + + /// Bounds the recording waveform to a fixed maximum duration. + /// + /// When provided, the waveform is no longer scrolled. Instead it fills only + /// the fraction of the available width equal to + /// `elapsedRecordingDuration / maxDuration`. e.g. with `maxDuration` of 10s, + /// stopping the recording at 5s draws the waveform across half of the width; + /// reaching `maxDuration` fills the full width. Recording past `maxDuration` + /// is clamped to the full width. + /// + /// Can only be used with [WaveformRenderMode.ltr] (ignored for + /// [WaveformRenderMode.rtl], like [extendWaveform]). When set, it takes + /// precedence over [extendWaveform]. + /// + /// A non-positive value (less than or equal to [Duration.zero]) is ignored + /// and falls back to the default scrolling behavior. + /// + /// Defaults to `null`, which keeps the default scrolling behavior. + final Duration? maxDuration; } diff --git a/lib/src/painters/recorder_wave_painter.dart b/lib/src/painters/recorder_wave_painter.dart index d0d99d2d..afbb0b77 100644 --- a/lib/src/painters/recorder_wave_painter.dart +++ b/lib/src/painters/recorder_wave_painter.dart @@ -48,6 +48,7 @@ class RecorderWavePainter extends CustomPainter { required this.currentlyRecordedDuration, required this.labels, required this.isRtl, + required this.maxDuration, }) : _wavePaint = Paint() ..color = waveColor ..strokeWidth = waveThickness @@ -98,6 +99,15 @@ class RecorderWavePainter extends CustomPainter { final List