@checksub_team/peaks_timeline 2.3.1 → 2.4.0-alpha.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checksub_team/peaks_timeline",
-  "version": "2.3.1",
+  "version": "2.4.0-alpha.0",
   "description": "JavaScript UI component for displaying audio waveforms",
   "main": "./peaks.js",
   "types": "./peaks.js.d.ts",

package/peaks.js

@@ -14573,7 +14573,9 @@ module.exports = function (Data, Utils) {
     }
     DataRetriever.prototype.retrieveData = function (source) {
         this._retrieveDataByUrl(source, source.previewUrl);
-        this._retrieveDataByUrl(source, source.binaryUrl);
+        if (!source.waveformData) {
+            this._retrieveDataByUrl(source, source.binaryUrl);
+        }
     };
     DataRetriever.prototype._retrieveDataByUrl = function (source, url) {
         if (url && url !== '') {
@@ -18833,6 +18835,92 @@ module.exports = function (WaveformBuilder, WaveformShape, Loader, Invoker, Util
             this._createAudioPreview(preview, redraw);
         }
     };
+    SourceGroup.prototype._getWaveformData = function () {
+        return this._source && this._source.waveformData ? this._source.waveformData : null;
+    };
+    SourceGroup.prototype._hasWaveformData = function () {
+        return Boolean(this._getWaveformData());
+    };
+    SourceGroup.prototype._removeWaveformDataPreview = function () {
+        if (!this._previewList || this._previewList.length === 0) {
+            return;
+        }
+        var removed = false;
+        this._previewList = this._previewList.filter(function (preview) {
+            if (preview && preview.type === 'waveformData') {
+                if (preview.group && typeof preview.group.destroy === 'function') {
+                    preview.group.destroy();
+                }
+                removed = true;
+                return false;
+            }
+            return true;
+        });
+        if (removed) {
+            this._scheduleBatchDraw();
+        }
+    };
+    SourceGroup.prototype.addWaveformDataPreview = function (redraw) {
+        if (!this._hasWaveformData()) {
+            return;
+        }
+        if (!this._unwrap) {
+            this._unwrap = this._createUnwrap();
+        }
+        var existing = this._previewList.filter(function (preview) {
+            return preview && preview.type === 'waveformData';
+        });
+        if (existing.length > 0) {
+            if (redraw) {
+                this._scheduleBatchDraw();
+            }
+            return;
+        }
+        var preview = {
+            type: 'waveformData',
+            group: new Konva.Group({
+                height: this._source.previewUrl ? this._source.binaryHeight : this._unwrappedHeight,
+                listening: false
+            })
+        };
+        var self = this;
+        var waveform = new WaveformShape({
+            view: this._view,
+            color: this._source.color,
+            height: preview.group.height(),
+            waveformDataFunc: function () {
+                return self._createWaveformDataPointsIterator();
+            }
+        });
+        preview.group.add(waveform);
+        this._addToUnwrap(preview.group);
+        if (redraw) {
+            this._scheduleBatchDraw();
+        }
+        this._previewList.push(preview);
+    };
+    SourceGroup.prototype.updateWaveformDataPreview = function (redraw) {
+        if (!this._hasWaveformData()) {
+            this._removeWaveformDataPreview();
+            return;
+        }
+        var existing = this._previewList.filter(function (preview) {
+            return preview && preview.type === 'waveformData';
+        });
+        if (existing.length === 0) {
+            this.addWaveformDataPreview(redraw);
+            return;
+        }
+        var expectedHeight = this._source.previewUrl ? this._source.binaryHeight : this._unwrappedHeight;
+        existing.forEach(function (preview) {
+            if (preview.group && typeof preview.group.height === 'function') {
+                preview.group.height(expectedHeight);
+            }
+        });
+        if (redraw) {
+            this._scheduleBatchDraw();
+        }
+    };
     SourceGroup.prototype._createAudioPreview = function (preview, redraw) {
         var url = preview.url;
         var scaledData = this._layer.getLoadedData(url + '-scaled');
@@ -18925,6 +19013,131 @@ module.exports = function (WaveformBuilder, WaveformShape, Loader, Invoker, Util
             }
         };
     };
+    SourceGroup.prototype._createWaveformDataPointsIterator = function () {
+        var custom = this._getWaveformData();
+        if (!custom || typeof custom !== 'object') {
+            return {
+                next: function () {
+                    return { done: true };
+                }
+            };
+        }
+        var bucketSizeSec = custom.bucketSizeSec;
+        var startTimeSec = custom.startTimeSec;
+        var minRaw = custom.min;
+        var maxRaw = custom.max;
+        if (!Utils.isValidTime(bucketSizeSec) || bucketSizeSec <= 0) {
+            return {
+                next: function () {
+                    return { done: true };
+                }
+            };
+        }
+        if (!Utils.isValidTime(startTimeSec)) {
+            startTimeSec = this._source && Utils.isValidTime(this._source.mediaStartTime) ? this._source.mediaStartTime : 0;
+        }
+        var minByChannel;
+        var maxByChannel;
+        var channels = 1;
+        if (Array.isArray(minRaw) && minRaw.length > 0 && Array.isArray(minRaw[0])) {
+            minByChannel = minRaw;
+            channels = minRaw.length;
+        } else {
+            minByChannel = [Array.isArray(minRaw) ? minRaw : []];
+            channels = 1;
+        }
+        if (Array.isArray(maxRaw) && maxRaw.length > 0 && Array.isArray(maxRaw[0])) {
+            maxByChannel = maxRaw;
+            channels = Math.max(channels, maxRaw.length);
+        } else {
+            maxByChannel = [Array.isArray(maxRaw) ? maxRaw : []];
+        }
+        for (var c = 0; c < channels; c++) {
+            if (!minByChannel[c]) {
+                minByChannel[c] = [];
+            }
+            if (!maxByChannel[c]) {
+                maxByChannel[c] = [];
+            }
+        }
+        var view = this._view;
+        var source = this._source;
+        var groupX = this._group && typeof this._group.x === 'function' ? this._group.x() : 0;
+        var groupWidth = this._width;
+        var viewWidth = view.getWidth();
+        var hiddenLeftPixels = Math.max(-groupX, 0);
+        var hiddenRightPixels = Math.max(groupX + groupWidth - viewWidth, 0);
+        var baseMediaStartTime = source && Utils.isValidTime(source.mediaStartTime) ? source.mediaStartTime : startTimeSec;
+        var visibleMediaStartTime = baseMediaStartTime;
+        var visibleMediaEndTime = source && Utils.isValidTime(source.mediaEndTime) ? source.mediaEndTime : baseMediaStartTime + (source.endTime - source.startTime);
+        visibleMediaStartTime += view.pixelsToTime(hiddenLeftPixels);
+        visibleMediaEndTime -= view.pixelsToTime(hiddenRightPixels);
+        if (visibleMediaEndTime < visibleMediaStartTime) {
+            visibleMediaEndTime = visibleMediaStartTime;
+        }
+        var startIndex = Math.max(0, Math.floor((visibleMediaStartTime - startTimeSec) / bucketSizeSec));
+        var endIndex = Math.max(startIndex, Math.ceil((visibleMediaEndTime - startTimeSec) / bucketSizeSec));
+        var maxLen = 0;
+        for (var cc = 0; cc < channels; cc++) {
+            maxLen = Math.max(maxLen, minByChannel[cc].length, maxByChannel[cc].length);
+        }
+        endIndex = Math.min(endIndex, maxLen);
+        function toInt8Amplitude(v) {
+            if (!Utils.isNumber(v) || !Number.isFinite(v)) {
+                return null;
+            }
+            if (v <= -1) {
+                return -128;
+            }
+            if (v >= 1) {
+                return 127;
+            }
+            return Math.round(v * 127);
+        }
+        var startOffsetPx = view.timeToPixels(baseMediaStartTime);
+        var xBucket = startIndex;
+        return {
+            next: function () {
+                while (xBucket < endIndex) {
+                    var min = new Array(channels);
+                    var max = new Array(channels);
+                    var hasAny = false;
+                    for (var i = 0; i < channels; i++) {
+                        var minV = toInt8Amplitude(minByChannel[i][xBucket]);
+                        var maxV = toInt8Amplitude(maxByChannel[i][xBucket]);
+                        if (minV === null && maxV !== null) {
+                            minV = maxV;
+                        }
+                        if (maxV === null && minV !== null) {
+                            maxV = minV;
+                        }
+                        if (minV === null && maxV === null) {
+                            min[i] = 0;
+                            max[i] = 0;
+                        } else {
+                            min[i] = minV;
+                            max[i] = maxV;
+                            hasAny = true;
+                        }
+                    }
+                    var bucketTime = startTimeSec + xBucket * bucketSizeSec;
+                    var xPx = view.timeToPixels(bucketTime) - startOffsetPx + 0.5;
+                    xBucket++;
+                    if (hasAny) {
+                        return {
+                            done: false,
+                            value: {
+                                x: xPx,
+                                min: min,
+                                max: max
+                            }
+                        };
+                    }
+                }
+                return { done: true };
+            }
+        };
+    };
     SourceGroup.prototype.getAudioPreview = function () {
         return this._previewList.filter(function (preview) {
             return preview.type === 'audio';
@@ -19719,7 +19932,7 @@ module.exports = function (SourceGroup, LineGroups, DataRetriever, Invoker, Util
         var width = this._view.getWidth();
         this.updateSources(this._view.pixelsToTime(frameOffset), this._view.pixelsToTime(frameOffset + width));
     };
-    SourcesLayer.prototype._onSourceUpdate = function (source) {
+    SourcesLayer.prototype._onSourceUpdate = function (source, meta) {
         const sourceGroup = this._sourcesGroup[source.id];
         const frameOffset = this._view.getFrameOffset();
         const width = this._view.getWidth();
@@ -19731,6 +19944,10 @@ module.exports = function (SourceGroup, LineGroups, DataRetriever, Invoker, Util
         var isActiveDraggedSource = false;
         var draggedAbsPos = null;
         var pointerPos = null;
+        if (sourceGroup && meta && meta.onlyWaveformData) {
+            sourceGroup.updateWaveformDataPreview(true);
+            return;
+        }
         if (sourceGroup) {
             isSourceGroupHovered = sourceGroup.isHovered();
             isSourceGroupDragged = sourceGroup.isDragged();
@@ -19857,6 +20074,9 @@ module.exports = function (SourceGroup, LineGroups, DataRetriever, Invoker, Util
         var sourceGroup = this._createSourceGroup(source);
         this._sourcesGroup[source.id] = sourceGroup;
         this._lineGroups.addSource(source, sourceGroup);
+        if (source && source.waveformData) {
+            sourceGroup.addWaveformDataPreview(false);
+        }
         if (startDataRetrieval) {
             this._dataRetriever.retrieveData(source);
         }
@@ -21779,14 +21999,20 @@ module.exports = function (Utils) {
         } else if (!Utils.isNumber(options.binaryHeight)) {
             throw new TypeError('peaks.sources.' + context + ': binaryHeight must be a number');
         }
+        var hasWaveformData = !Utils.isNullOrUndefined(options.waveformData);
+        var hasWaveformArea = Boolean(options.binaryUrl) || hasWaveformData;
         if (options.previewUrl && !options.previewHeight) {
-            if (options.binaryHeight) {
-                options.previewHeight = Math.max(peaks.options.lineHeight - options.binaryHeight, 0);
+            if (hasWaveformArea) {
+                if (options.binaryHeight) {
+                    options.previewHeight = Math.max(peaks.options.lineHeight - options.binaryHeight, 0);
+                } else {
+                    options.previewHeight = peaks.options.lineHeight / 2;
+                }
             } else {
-                options.previewHeight = peaks.options.lineHeight / 2;
+                options.previewHeight = peaks.options.lineHeight;
             }
         }
-        if (options.binaryUrl && !options.binaryHeight) {
+        if (hasWaveformArea && !options.binaryHeight) {
             options.binaryHeight = Math.max(peaks.options.lineHeight - options.previewHeight, 0);
         }
         if (options.wrapping === 'reduced') {
@@ -21836,7 +22062,7 @@ module.exports = function (Utils) {
             throw new TypeError('peaks.sources.' + context + ': targetSpeed must be a positive number');
         }
     }
-    function Source(peaks, id, lineId, originId, elementId, title, titleAlignments, url, previewUrl, binaryUrl, kind, subkind, duration, startTime, endTime, mediaStartTime, mediaEndTime, color, backgroundColor, hoverBackgroundColor, selectedBackgroundColor, borderColor, selectedBorderColor, warningColor, warningWidth, volumeSliderColor, volumeSliderWidth, volumeSliderDraggingWidth, textFont, textFontSize, textColor, textBackgroundColor, textPosition, textAutoScroll, borderWidth, borderRadius, wrapped, draggable, orderable, resizable, cuttable, deletable, wrapping, previewHeight, binaryHeight, indicators, markers, buttons, markerColor, markerWidth, volume, volumeRange, loading, targetSpeed, ...customParams) {
+    function Source(peaks, id, lineId, originId, elementId, title, titleAlignments, url, previewUrl, binaryUrl, kind, subkind, duration, startTime, endTime, mediaStartTime, mediaEndTime, color, backgroundColor, hoverBackgroundColor, selectedBackgroundColor, borderColor, selectedBorderColor, warningColor, warningWidth, volumeSliderColor, volumeSliderWidth, volumeSliderDraggingWidth, textFont, textFontSize, textColor, textBackgroundColor, textPosition, textAutoScroll, borderWidth, borderRadius, wrapped, draggable, orderable, resizable, cuttable, deletable, wrapping, previewHeight, binaryHeight, indicators, markers, buttons, markerColor, markerWidth, volume, volumeRange, loading, targetSpeed, waveformData, ...customParams) {
         var opts = {
             title: title,
             titleAlignments: titleAlignments,
@@ -21886,7 +22112,8 @@ module.exports = function (Utils) {
             volume: volume,
             volumeRange: volumeRange,
             loading: loading,
-            targetSpeed: targetSpeed
+            targetSpeed: targetSpeed,
+            waveformData: waveformData
         };
         validateSource(peaks, opts, 'add()');
         this._peaks = peaks;
@@ -21943,6 +22170,7 @@ module.exports = function (Utils) {
         this._volumeRange = opts.volumeRange;
         this._loading = opts.loading;
         this._targetSpeed = opts.targetSpeed;
+        this._waveformData = opts.waveformData;
         this._minSize = peaks.options.minSourceSize;
         this._selected = false;
         for (var i = 0; i < customParams.length; i += 2) {
@@ -22014,6 +22242,15 @@ module.exports = function (Utils) {
                 return this._binaryUrl;
             }
         },
+        waveformData: {
+            enumerable: true,
+            get: function () {
+                return this._waveformData;
+            },
+            set: function (waveformData) {
+                this._waveformData = waveformData;
+            }
+        },
         kind: {
             enumerable: true,
             get: function () {
@@ -22560,6 +22797,7 @@ module.exports = function (Utils) {
         this._volumeRange = opts.volumeRange;
         this._loading = opts.loading;
         this._targetSpeed = opts.targetSpeed;
+        this._waveformData = opts.waveformData;
         if (options && typeof options === 'object') {
             for (var key in options) {
                 if (Object.prototype.hasOwnProperty.call(options, key) && key.startsWith('custom_')) {
@@ -22567,7 +22805,14 @@ module.exports = function (Utils) {
                 }
             }
         }
-        this._peaks.emit('model.source.update', this);
+        var updatedKeys = [];
+        if (options && typeof options === 'object') {
+            updatedKeys = Object.keys(options);
+        }
+        this._peaks.emit('model.source.update', this, {
+            updatedKeys: updatedKeys,
+            onlyWaveformData: updatedKeys.length === 1 && updatedKeys[0] === 'waveformData'
+        });
     };
     Source.prototype.isVisible = function (startTime, endTime) {
         return this._startTime < endTime && startTime < this._endTime;
@@ -22874,7 +23119,8 @@ module.exports = function (Source, Utils) {
             volume: sourceToCut.volume,
             volumeRange: sourceToCut.volumeRange,
             loading: sourceToCut.loading,
-            targetSpeed: sourceToCut.targetSpeed
+            targetSpeed: sourceToCut.targetSpeed,
+            waveformData: sourceToCut.waveformData
         };
         for (var key in sourceToCut) {
             if (key.startsWith('custom_')) {
@@ -22904,7 +23150,7 @@ module.exports = function (Source, Utils) {
                 customParams.push(key, value);
             }
         });
-        var source = new Source(this._peaks, options.id || this._getNextSourceId(), options.lineId, options.originId, options.elementId, options.title, options.titleAlignments, options.url, options.previewUrl, options.binaryUrl, options.kind, options.subkind, options.duration, options.startTime, options.endTime, options.mediaStartTime, options.mediaEndTime, options.color, options.backgroundColor, options.hoverBackgroundColor, options.selectedBackgroundColor, options.borderColor, options.selectedBorderColor, options.warningColor, options.warningWidth, options.volumeSliderColor, options.volumeSliderWidth, options.volumeSliderDraggingWidth, options.textFont, options.textFontSize, options.textColor, options.textBackgroundColor, options.textPosition, options.textAutoScroll, options.borderWidth, options.borderRadius, options.wrapped, options.draggable, options.orderable, options.resizable, options.cuttable, options.deletable, options.wrapping, options.previewHeight, options.binaryHeight, options.indicators, options.markers, options.buttons, options.markerColor, options.markerWidth, options.volume, options.volumeRange, options.loading, options.targetSpeed, ...customParams);
+        var source = new Source(this._peaks, options.id || this._getNextSourceId(), options.lineId, options.originId, options.elementId, options.title, options.titleAlignments, options.url, options.previewUrl, options.binaryUrl, options.kind, options.subkind, options.duration, options.startTime, options.endTime, options.mediaStartTime, options.mediaEndTime, options.color, options.backgroundColor, options.hoverBackgroundColor, options.selectedBackgroundColor, options.borderColor, options.selectedBorderColor, options.warningColor, options.warningWidth, options.volumeSliderColor, options.volumeSliderWidth, options.volumeSliderDraggingWidth, options.textFont, options.textFontSize, options.textColor, options.textBackgroundColor, options.textPosition, options.textAutoScroll, options.borderWidth, options.borderRadius, options.wrapped, options.draggable, options.orderable, options.resizable, options.cuttable, options.deletable, options.wrapping, options.previewHeight, options.binaryHeight, options.indicators, options.markers, options.buttons, options.markerColor, options.markerWidth, options.volume, options.volumeRange, options.loading, options.targetSpeed, options.waveformData, ...customParams);
         return source;
     };
     SourceHandler.prototype.getSources = function () {

package/src/components/data-retriever.js

@@ -35,7 +35,11 @@ define([
 
     DataRetriever.prototype.retrieveData = function(source) {
         this._retrieveDataByUrl(source, source.previewUrl);
-        this._retrieveDataByUrl(source, source.binaryUrl);
+        // If waveformData is supplied on the source, prefer it over
+        // remote/binary waveform retrieval.
+        if (!source.waveformData) {
+            this._retrieveDataByUrl(source, source.binaryUrl);
+        }
     };
 
     DataRetriever.prototype._retrieveDataByUrl = function(source, url) {

package/src/components/source-group.js

@@ -980,6 +980,119 @@ define([
     }
   };
 
+  SourceGroup.prototype._getWaveformData = function() {
+    return this._source && this._source.waveformData ? this._source.waveformData : null;
+  };
+
+  SourceGroup.prototype._hasWaveformData = function() {
+    return Boolean(this._getWaveformData());
+  };
+
+  SourceGroup.prototype._removeWaveformDataPreview = function() {
+    if (!this._previewList || this._previewList.length === 0) {
+      return;
+    }
+
+    var removed = false;
+
+    this._previewList = this._previewList.filter(function(preview) {
+      if (preview && preview.type === 'waveformData') {
+        if (preview.group && typeof preview.group.destroy === 'function') {
+          preview.group.destroy();
+        }
+        removed = true;
+        return false;
+      }
+      return true;
+    });
+
+    if (removed) {
+      this._scheduleBatchDraw();
+    }
+  };
+
+  SourceGroup.prototype.addWaveformDataPreview = function(redraw) {
+    if (!this._hasWaveformData()) {
+      return;
+    }
+
+    // If the source starts wrapped, _unwrap may not exist yet. We still build
+    // previews into the unwrap container so they appear when the source is
+    // expanded later.
+    if (!this._unwrap) {
+      this._unwrap = this._createUnwrap();
+    }
+
+    // Avoid duplicates.
+    var existing = this._previewList.filter(function(preview) {
+      return preview && preview.type === 'waveformData';
+    });
+
+    if (existing.length > 0) {
+      if (redraw) {
+        this._scheduleBatchDraw();
+      }
+      return;
+    }
+
+    var preview = {
+      type: 'waveformData',
+      group: new Konva.Group({
+        height: (this._source.previewUrl ? this._source.binaryHeight : this._unwrappedHeight),
+        listening: false
+      })
+    };
+
+    var self = this;
+
+    var waveform = new WaveformShape({
+      view: this._view,
+      color: this._source.color,
+      height: preview.group.height(),
+      waveformDataFunc: function() {
+        return self._createWaveformDataPointsIterator();
+      }
+    });
+
+    preview.group.add(waveform);
+    this._addToUnwrap(preview.group);
+
+    if (redraw) {
+      this._scheduleBatchDraw();
+    }
+
+    this._previewList.push(preview);
+  };
+
+  SourceGroup.prototype.updateWaveformDataPreview = function(redraw) {
+    if (!this._hasWaveformData()) {
+      this._removeWaveformDataPreview();
+      return;
+    }
+
+    var existing = this._previewList.filter(function(preview) {
+      return preview && preview.type === 'waveformData';
+    });
+
+    if (existing.length === 0) {
+      this.addWaveformDataPreview(redraw);
+      return;
+    }
+
+    // Height may depend on previewUrl presence.
+    var expectedHeight = (this._source.previewUrl ? this._source.binaryHeight : this._unwrappedHeight);
+
+    existing.forEach(function(preview) {
+      if (preview.group && typeof preview.group.height === 'function') {
+        preview.group.height(expectedHeight);
+      }
+    });
+
+    if (redraw) {
+      this._scheduleBatchDraw();
+    }
+  };
+
   SourceGroup.prototype._createAudioPreview = function(preview, redraw) {
     var url = preview.url;
 
@@ -1116,6 +1229,178 @@ define([
     };
   };
 
+  SourceGroup.prototype._createWaveformDataPointsIterator = function() {
+    var custom = this._getWaveformData();
+
+    if (!custom || typeof custom !== 'object') {
+      return {
+        next: function() {
+          return { done: true };
+        }
+      };
+    }
+
+    var bucketSizeSec = custom.bucketSizeSec;
+    var startTimeSec = custom.startTimeSec;
+    var minRaw = custom.min;
+    var maxRaw = custom.max;
+
+    if (!Utils.isValidTime(bucketSizeSec) || bucketSizeSec <= 0) {
+      return {
+        next: function() {
+          return { done: true };
+        }
+      };
+    }
+
+    if (!Utils.isValidTime(startTimeSec)) {
+      // Fallback to current model mediaStartTime if missing.
+      startTimeSec = this._source && Utils.isValidTime(this._source.mediaStartTime) ? this._source.mediaStartTime : 0;
+    }
+
+    // Normalize to channel arrays.
+    var minByChannel;
+    var maxByChannel;
+    var channels = 1;
+
+    if (Array.isArray(minRaw) && minRaw.length > 0 && Array.isArray(minRaw[0])) {
+      minByChannel = minRaw;
+      channels = minRaw.length;
+    }
+    else {
+      minByChannel = [Array.isArray(minRaw) ? minRaw : []];
+      channels = 1;
+    }
+
+    if (Array.isArray(maxRaw) && maxRaw.length > 0 && Array.isArray(maxRaw[0])) {
+      maxByChannel = maxRaw;
+      channels = Math.max(channels, maxRaw.length);
+    }
+    else {
+      maxByChannel = [Array.isArray(maxRaw) ? maxRaw : []];
+    }
+
+    // Ensure arrays exist for all channels.
+    for (var c = 0; c < channels; c++) {
+      if (!minByChannel[c]) {
+        minByChannel[c] = [];
+      }
+      if (!maxByChannel[c]) {
+        maxByChannel[c] = [];
+      }
+    }
+
+    // Determine visible time range for this source, including drag offsets.
+    var view = this._view;
+    var source = this._source;
+    var groupX = this._group && typeof this._group.x === 'function' ? this._group.x() : 0;
+    var groupWidth = this._width;
+    var viewWidth = view.getWidth();
+
+    var hiddenLeftPixels = Math.max(-groupX, 0);
+    var hiddenRightPixels = Math.max(groupX + groupWidth - viewWidth, 0);
+
+    // Base media start time for x-axis alignment.
+    var baseMediaStartTime = (source && Utils.isValidTime(source.mediaStartTime))
+      ? source.mediaStartTime
+      : startTimeSec;
+
+    // Translate pixel visibility into time range in the media timeline.
+    var visibleMediaStartTime = baseMediaStartTime;
+    var visibleMediaEndTime = (source && Utils.isValidTime(source.mediaEndTime))
+      ? source.mediaEndTime
+      : (baseMediaStartTime + (source.endTime - source.startTime));
+
+    // Account for the portion hidden outside the viewport (during dragging/scrolling).
+    visibleMediaStartTime += view.pixelsToTime(hiddenLeftPixels);
+    visibleMediaEndTime -= view.pixelsToTime(hiddenRightPixels);
+
+    if (visibleMediaEndTime < visibleMediaStartTime) {
+      visibleMediaEndTime = visibleMediaStartTime;
+    }
+
+    // Map time range to bucket indices.
+    var startIndex = Math.max(0, Math.floor((visibleMediaStartTime - startTimeSec) / bucketSizeSec));
+    var endIndex = Math.max(startIndex, Math.ceil((visibleMediaEndTime - startTimeSec) / bucketSizeSec));
+
+    // Clamp endIndex to available data.
+    var maxLen = 0;
+
+    for (var cc = 0; cc < channels; cc++) {
+      maxLen = Math.max(maxLen, minByChannel[cc].length, maxByChannel[cc].length);
+    }
+    endIndex = Math.min(endIndex, maxLen);
+
+    // Convert float amplitudes (-1..1) to signed 8-bit-ish range (-128..127).
+    function toInt8Amplitude(v) {
+      if (!Utils.isNumber(v) || !Number.isFinite(v)) {
+        return null;
+      }
+      if (v <= -1) {
+        return -128;
+      }
+      if (v >= 1) {
+        return 127;
+      }
+      // Use 127 as positive peak to match common signed 8-bit scaling.
+      return Math.round(v * 127);
+    }
+
+    var startOffsetPx = view.timeToPixels(baseMediaStartTime);
+    var xBucket = startIndex;
+
+    return {
+      next: function() {
+        while (xBucket < endIndex) {
+          var min = new Array(channels);
+          var max = new Array(channels);
+          var hasAny = false;
+
+          for (var i = 0; i < channels; i++) {
+            var minV = toInt8Amplitude(minByChannel[i][xBucket]);
+            var maxV = toInt8Amplitude(maxByChannel[i][xBucket]);
+
+            // Draw what we have: if one side is missing, fall back to the other.
+            if (minV === null && maxV !== null) {
+              minV = maxV;
+            }
+            if (maxV === null && minV !== null) {
+              maxV = minV;
+            }
+
+            if (minV === null && maxV === null) {
+              min[i] = 0;
+              max[i] = 0;
+            }
+            else {
+              min[i] = minV;
+              max[i] = maxV;
+              hasAny = true;
+            }
+          }
+
+          var bucketTime = startTimeSec + xBucket * bucketSizeSec;
+          var xPx = view.timeToPixels(bucketTime) - startOffsetPx + 0.5;
+
+          xBucket++;
+
+          if (hasAny) {
+            return {
+              done: false,
+              value: {
+                x: xPx,
+                min: min,
+                max: max
+              }
+            };
+          }
+        }
+
+        return { done: true };
+      }
+    };
+  };
+
   SourceGroup.prototype.getAudioPreview = function() {
     return this._previewList.filter(function(preview) {
       return preview.type === 'audio';

package/src/components/sources-layer.js

@@ -151,7 +151,7 @@ define([
     );
   };
 
-  SourcesLayer.prototype._onSourceUpdate = function(source) {
+  SourcesLayer.prototype._onSourceUpdate = function(source, meta) {
     const sourceGroup = this._sourcesGroup[source.id];
     const frameOffset = this._view.getFrameOffset();
     const width = this._view.getWidth();
@@ -168,6 +168,13 @@ define([
     var draggedAbsPos = null;
     var pointerPos = null;
 
+    // Fast-path: if only the custom waveform changed, update the existing
+    // preview in-place and redraw without rebuilding the entire group.
+    if (sourceGroup && meta && meta.onlyWaveformData) {
+      sourceGroup.updateWaveformDataPreview(true);
+      return;
+    }
+
     if (sourceGroup) {
       isSourceGroupHovered = sourceGroup.isHovered();
       isSourceGroupDragged = sourceGroup.isDragged();
@@ -366,6 +373,12 @@ define([
     this._sourcesGroup[source.id] = sourceGroup;
     this._lineGroups.addSource(source, sourceGroup);
 
+    // If a custom waveform is provided on the source, render it immediately.
+    // This is local data, so no network retrieval is needed for the waveform.
+    if (source && source.waveformData) {
+      sourceGroup.addWaveformDataPreview(false);
+    }
+
     // After creating and referencing the new group, we can start data retrieval
     if (startDataRetrieval) {
       this._dataRetriever.retrieveData(source);

package/src/models/source.js

@@ -298,16 +298,26 @@ define([
       throw new TypeError('peaks.sources.' + context + ': binaryHeight must be a number');
     }
 
+    // Treat waveformData as a waveform source, similar to binaryUrl.
+    var hasWaveformData = !Utils.isNullOrUndefined(options.waveformData);
+    var hasWaveformArea = Boolean(options.binaryUrl) || hasWaveformData;
+
     if (options.previewUrl && !options.previewHeight) {
-      if (options.binaryHeight) {
-        options.previewHeight = Math.max(peaks.options.lineHeight - options.binaryHeight, 0);
+      if (hasWaveformArea) {
+        if (options.binaryHeight) {
+          options.previewHeight = Math.max(peaks.options.lineHeight - options.binaryHeight, 0);
+        }
+        else {
+          options.previewHeight = peaks.options.lineHeight / 2;
+        }
       }
       else {
-        options.previewHeight = peaks.options.lineHeight / 2;
+        // If only a preview is shown, default it to the full available height.
+        options.previewHeight = peaks.options.lineHeight;
       }
     }
 
-    if (options.binaryUrl && !options.binaryHeight) {
+    if (hasWaveformArea && !options.binaryHeight) {
       options.binaryHeight = Math.max(peaks.options.lineHeight - options.previewHeight, 0);
     }
 
@@ -444,7 +454,7 @@ define([
     volumeSliderWidth, volumeSliderDraggingWidth, textFont, textFontSize, textColor, textBackgroundColor, textPosition,
     textAutoScroll, borderWidth, borderRadius, wrapped, draggable, orderable, resizable,
     cuttable, deletable, wrapping, previewHeight, binaryHeight, indicators, markers, buttons, markerColor,
-    markerWidth, volume, volumeRange, loading, targetSpeed, ...customParams) {
+    markerWidth, volume, volumeRange, loading, targetSpeed, waveformData, ...customParams) {
     var opts = {
       title: title,
       titleAlignments: titleAlignments,
@@ -494,7 +504,8 @@ define([
       volume: volume,
       volumeRange: volumeRange,
       loading: loading,
-      targetSpeed: targetSpeed
+      targetSpeed: targetSpeed,
+      waveformData: waveformData
     };
 
     validateSource(peaks, opts, 'add()');
@@ -553,6 +564,7 @@ define([
     this._volumeRange = opts.volumeRange;
     this._loading = opts.loading;
     this._targetSpeed = opts.targetSpeed;
+    this._waveformData = opts.waveformData;
     this._minSize = peaks.options.minSourceSize;
     this._selected = false;
 
@@ -629,6 +641,16 @@ define([
         return this._binaryUrl;
       }
     },
+    waveformData: {
+      enumerable: true,
+      get: function() {
+        return this._waveformData;
+      },
+
+      set: function(waveformData) {
+        this._waveformData = waveformData;
+      }
+    },
     kind: {
       enumerable: true,
       get: function() {
@@ -1236,6 +1258,7 @@ define([
     this._volumeRange = opts.volumeRange;
     this._loading = opts.loading;
     this._targetSpeed = opts.targetSpeed;
+    this._waveformData = opts.waveformData;
 
     if (options && typeof options === 'object') {
       for (var key in options) {
@@ -1245,7 +1268,16 @@ define([
       }
     }
 
-    this._peaks.emit('model.source.update', this);
+    var updatedKeys = [];
+
+    if (options && typeof options === 'object') {
+      updatedKeys = Object.keys(options);
+    }
+
+    this._peaks.emit('model.source.update', this, {
+      updatedKeys: updatedKeys,
+      onlyWaveformData: updatedKeys.length === 1 && updatedKeys[0] === 'waveformData'
+    });
   };
 
   /**

package/src/source-handler.js

@@ -110,7 +110,8 @@ define([
       volume: sourceToCut.volume,
       volumeRange: sourceToCut.volumeRange,
       loading: sourceToCut.loading,
-      targetSpeed: sourceToCut.targetSpeed
+      targetSpeed: sourceToCut.targetSpeed,
+      waveformData: sourceToCut.waveformData
     };
 
     for (var key in sourceToCut) {
@@ -225,6 +226,7 @@ define([
       options.volumeRange,
       options.loading,
       options.targetSpeed,
+      options.waveformData,
       ...customParams
     );