@remotion/timeline-utils 4.0.522 → 4.0.523

package/dist/audio-waveform/audio-waveform-worker-types.d.ts

@@ -10,6 +10,7 @@ export type AudioWaveformWorkerPeaksMessage = {
     readonly requestId: number;
     readonly peaks: Float32Array;
     readonly final: boolean;
+    readonly averageVolume: number | null;
 };
 export type AudioWaveformWorkerErrorMessage = {
     readonly type: 'error';

package/dist/audio-waveform/draw-peaks.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.drawBars = void 0;
 const parse_color_1 = require("./parse-color");
 const CLIPPING_COLOR = '#FF7F50';
+const WAVEFORM_HEIGHT_SCALE = 0.8;
 const getVolumeAtBar = ({ barIndex, numBars, volume, }) => {
     var _a;
     if (typeof volume === 'number') {
@@ -37,6 +38,7 @@ const drawBars = ({ canvas, color, peaks, volume, width, }) => {
     const imageData = ctx.createImageData(w, height);
     const { data } = imageData;
     const numBars = width;
+    const fullScaleHalfBar = (height * WAVEFORM_HEIGHT_SCALE) / 2;
     for (let barIndex = 0; barIndex < numBars; barIndex++) {
         const x = barIndex;
         if (x >= w)
@@ -45,15 +47,20 @@ const drawBars = ({ canvas, color, peaks, volume, width, }) => {
         const peak = peaks[peakIndex] || 0;
         const barVolume = getVolumeAtBar({ barIndex, numBars, volume });
         const scaledPeak = peak * barVolume;
-        const halfBar = Math.max(0, Math.min(height / 2, (scaledPeak * height) / 2));
+        const halfBar = Math.max(0, Math.min(height / 2, scaledPeak * fullScaleHalfBar));
         if (halfBar === 0)
             continue;
         const mid = height / 2;
         const barY = Math.round(mid - halfBar);
         const barEnd = Math.round(mid + halfBar);
         const isClipping = scaledPeak > 1;
-        const clipTopEnd = isClipping ? Math.min(barY + 2, barEnd) : barY;
-        const clipBotStart = isClipping ? Math.max(barEnd - 2, barY) : barEnd;
+        // Color the overflow above full scale, keeping tiny overshoots visible.
+        const clipTopEnd = isClipping
+            ? Math.min(Math.max(barY + 2, Math.round(mid - fullScaleHalfBar)), barEnd)
+            : barY;
+        const clipBotStart = isClipping
+            ? Math.max(Math.min(barEnd - 2, Math.round(mid + fullScaleHalfBar)), barY)
+            : barEnd;
         for (let y = barY; y < clipTopEnd; y++) {
             const idx = (y * w + x) * 4;
             data[idx] = cr;

package/dist/audio-waveform/get-waveform-cache-key.d.ts

@@ -0,0 +1,2 @@
+import type { InputAudioTrack } from 'mediabunny';
+export declare const getWaveformCacheKey: (src: string | InputAudioTrack, waveformSampleRate: number) => string;

package/dist/audio-waveform/get-waveform-cache-key.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWaveformCacheKey = void 0;
+const trackIds = new WeakMap();
+let nextTrackId = 0;
+const getWaveformCacheKey = (src, waveformSampleRate) => {
+    if (typeof src === 'string') {
+        return `${waveformSampleRate}:url:${src}`;
+    }
+    let id = trackIds.get(src);
+    if (id === undefined) {
+        id = nextTrackId++;
+        trackIds.set(src, id);
+    }
+    return `${waveformSampleRate}:track:${id}`;
+};
+exports.getWaveformCacheKey = getWaveformCacheKey;

package/dist/audio-waveform/load-waveform-peaks.d.ts

@@ -1,6 +1,12 @@
+import type { InputAudioTrack } from 'mediabunny';
 import { TARGET_SAMPLE_RATE } from './constants';
+export type WaveformResult = {
+    readonly peaks: Float32Array;
+    readonly averageVolume: number | null;
+};
 export { TARGET_SAMPLE_RATE };
 type Progress = {
+    readonly averageVolume: number | null;
     readonly peaks: Float32Array;
     readonly completedPeaks: number;
     readonly totalPeaks: number;
@@ -11,4 +17,4 @@ type LoadWaveformPeaksOptions = {
     readonly progressIntervalInMs?: number;
     readonly waveformSampleRate?: number;
 };
-export declare function loadWaveformPeaks(url: string, signal: AbortSignal, options?: LoadWaveformPeaksOptions): Promise<Float32Array>;
+export declare function loadWaveformPeaks(src: string | InputAudioTrack, signal: AbortSignal, options?: LoadWaveformPeaksOptions): Promise<WaveformResult>;

package/dist/audio-waveform/load-waveform-peaks.js

@@ -5,44 +5,45 @@ exports.loadWaveformPeaks = loadWaveformPeaks;
 const mediabunny_1 = require("mediabunny");
 const constants_1 = require("./constants");
 Object.defineProperty(exports, "TARGET_SAMPLE_RATE", { enumerable: true, get: function () { return constants_1.TARGET_SAMPLE_RATE; } });
+const get_waveform_cache_key_1 = require("./get-waveform-cache-key");
 const trim_audio_sample_before_zero_1 = require("./trim-audio-sample-before-zero");
 const waveform_peak_processor_1 = require("./waveform-peak-processor");
 const DEFAULT_PROGRESS_INTERVAL_IN_MS = 50;
 const peaksCache = new Map();
-async function loadWaveformPeaks(url, signal, options) {
+async function loadWaveformPeaks(src, signal, options) {
     var _a, _b, _c;
     const waveformSampleRate = (_a = options === null || options === void 0 ? void 0 : options.waveformSampleRate) !== null && _a !== void 0 ? _a : constants_1.TARGET_SAMPLE_RATE;
     if (!Number.isFinite(waveformSampleRate) || waveformSampleRate <= 0) {
         throw new Error('The waveform sample rate must be a positive number.');
     }
-    const cacheKey = `${waveformSampleRate}:${url}`;
+    const cacheKey = (0, get_waveform_cache_key_1.getWaveformCacheKey)(src, waveformSampleRate);
     const cached = peaksCache.get(cacheKey);
     if (cached) {
         (0, waveform_peak_processor_1.emitWaveformProgress)({
-            peaks: cached,
-            completedPeaks: cached.length,
-            totalPeaks: cached.length,
+            peaks: cached.peaks,
+            averageVolume: cached.averageVolume,
+            completedPeaks: cached.peaks.length,
+            totalPeaks: cached.peaks.length,
             final: true,
             onProgress: options === null || options === void 0 ? void 0 : options.onProgress,
         });
         return cached;
     }
-    const input = new mediabunny_1.Input({
-        formats: mediabunny_1.ALL_FORMATS,
-        source: new mediabunny_1.UrlSource(url),
-    });
+    const input = typeof src === 'string'
+        ? new mediabunny_1.Input({ formats: mediabunny_1.ALL_FORMATS, source: new mediabunny_1.UrlSource(src) })
+        : null;
     try {
-        const audioTrack = await input.getPrimaryAudioTrack();
+        const audioTrack = typeof src === 'string' ? await input.getPrimaryAudioTrack() : src;
         if (!audioTrack) {
-            return new Float32Array(0);
+            return { peaks: new Float32Array(0), averageVolume: null };
         }
         if (await audioTrack.isLive()) {
             throw new Error('Live streams are not currently supported by Remotion. Sorry! Source: ' +
-                url);
+                (typeof src === 'string' ? src : `audio track ${src.id}`));
         }
         if (await audioTrack.isRelativeToUnixEpoch()) {
             throw new Error('Streams with UNIX timestamps are not currently supported by Remotion. Sorry! Source: ' +
-                url);
+                (typeof src === 'string' ? src : `audio track ${src.id}`));
         }
         const audioSampleRate = await audioTrack.getSampleRate();
         const durationInSeconds = (_b = (await audioTrack.getDurationFromMetadata({ skipLiveWait: true }))) !== null && _b !== void 0 ? _b : (await audioTrack.computeDuration({ skipLiveWait: true }));
@@ -60,7 +61,7 @@ async function loadWaveformPeaks(url, signal, options) {
         for await (const sample of sink.samples()) {
             if (signal.aborted) {
                 sample.close();
-                return new Float32Array(0);
+                return { peaks: new Float32Array(0), averageVolume: null };
             }
             const startFrame = (0, trim_audio_sample_before_zero_1.getAudioSampleStartFrameAtTimelineZero)(sample);
             if (startFrame === null) {
@@ -86,15 +87,19 @@ async function loadWaveformPeaks(url, signal, options) {
                 frameCount,
             });
             const channels = Math.max(1, sample.numberOfChannels);
+            const { sampleRate } = sample;
             sample.close();
-            processor.processSampleChunk(floats, channels);
+            processor.processSampleChunk(floats, channels, sampleRate);
         }
         processor.finalize();
-        const { peaks } = processor;
-        peaksCache.set(cacheKey, peaks);
-        return peaks;
+        const result = {
+            peaks: processor.peaks,
+            averageVolume: processor.averageVolume,
+        };
+        peaksCache.set(cacheKey, result);
+        return result;
     }
     finally {
-        input.dispose();
+        input === null || input === void 0 ? void 0 : input.dispose();
     }
 }

package/dist/audio-waveform/subscribe-to-waveform-peaks.d.ts

@@ -1,6 +1,7 @@
+import type { InputAudioTrack } from 'mediabunny';
 export declare const subscribeToWaveformPeaks: ({ src, waveformSampleRate, onPeaks, onError, }: {
-    readonly src: string;
+    readonly src: string | InputAudioTrack;
     readonly waveformSampleRate?: number | undefined;
-    readonly onPeaks: (peaks: Float32Array<ArrayBufferLike>, final: boolean) => void;
+    readonly onPeaks: (peaks: Float32Array<ArrayBufferLike>, final: boolean, averageVolume: number | null) => void;
     readonly onError: (error: Error) => void;
 }) => () => void;

package/dist/audio-waveform/subscribe-to-waveform-peaks.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.subscribeToWaveformPeaks = void 0;
 const constants_1 = require("./constants");
+const get_waveform_cache_key_1 = require("./get-waveform-cache-key");
 const load_waveform_peaks_1 = require("./load-waveform-peaks");
 const make_audio_waveform_worker_1 = require("./make-audio-waveform-worker");
 // All AudioWaveform instances share one decode worker and one peaks cache,
@@ -13,9 +14,9 @@ const inFlightByRequestId = new Map();
 let worker = null;
 let workerFailed = false;
 let nextRequestId = 0;
-const emitPeaks = (load, peaks, final) => {
+const emitPeaks = (load, peaks, final, averageVolume) => {
     if (final) {
-        peaksCache.set(load.cacheKey, peaks);
+        peaksCache.set(load.cacheKey, { peaks, averageVolume });
         load.latestPeaks = null;
         inFlightByCacheKey.delete(load.cacheKey);
         if (load.requestId !== null) {
@@ -26,7 +27,7 @@ const emitPeaks = (load, peaks, final) => {
         load.latestPeaks = peaks;
     }
     for (const listener of load.listeners) {
-        listener.onPeaks(peaks, final);
+        listener.onPeaks(peaks, final, averageVolume);
     }
 };
 const emitError = (load, error) => {
@@ -51,11 +52,11 @@ const startMainThreadLoad = (load) => {
             }
             // The processor mutates the same array in place; snapshot it so
             // React state updates see a new reference.
-            emitPeaks(load, peaks.slice(), false);
+            emitPeaks(load, peaks.slice(), false, null);
         },
     })
-        .then((peaks) => {
-        emitPeaks(load, peaks, true);
+        .then(({ peaks, averageVolume }) => {
+        emitPeaks(load, peaks, true, averageVolume);
     })
         .catch((error) => {
         emitError(load, error instanceof Error
@@ -97,7 +98,7 @@ const getOrCreateWorker = () => {
             emitError(load, new Error(message.message));
             return;
         }
-        emitPeaks(load, message.peaks, message.final);
+        emitPeaks(load, message.peaks, message.final, message.averageVolume);
     });
     worker.addEventListener('error', (event) => {
         event.preventDefault();
@@ -106,10 +107,10 @@ const getOrCreateWorker = () => {
     return worker;
 };
 const subscribeToWaveformPeaks = ({ src, waveformSampleRate = constants_1.TARGET_SAMPLE_RATE, onPeaks, onError, }) => {
-    const cacheKey = `${waveformSampleRate}:${src}`;
+    const cacheKey = (0, get_waveform_cache_key_1.getWaveformCacheKey)(src, waveformSampleRate);
     const cached = peaksCache.get(cacheKey);
     if (cached) {
-        onPeaks(cached, true);
+        onPeaks(cached.peaks, true, cached.averageVolume);
         return () => undefined;
     }
     const listener = { onPeaks, onError };
@@ -117,7 +118,7 @@ const subscribeToWaveformPeaks = ({ src, waveformSampleRate = constants_1.TARGET
     if (existing) {
         existing.listeners.add(listener);
         if (existing.latestPeaks) {
-            onPeaks(existing.latestPeaks, false);
+            onPeaks(existing.latestPeaks, false, null);
         }
         return () => {
             existing.listeners.delete(listener);
@@ -132,8 +133,8 @@ const subscribeToWaveformPeaks = ({ src, waveformSampleRate = constants_1.TARGET
         requestId: null,
     };
     inFlightByCacheKey.set(cacheKey, load);
-    const workerInstance = getOrCreateWorker();
-    if (workerInstance) {
+    const workerInstance = typeof src === 'string' ? getOrCreateWorker() : null;
+    if (workerInstance && typeof src === 'string') {
         const requestId = nextRequestId++;
         load.requestId = requestId;
         inFlightByRequestId.set(requestId, load);

package/dist/audio-waveform/waveform-peak-processor.d.ts

@@ -1,5 +1,6 @@
 type Progress = {
     readonly peaks: Float32Array;
+    readonly averageVolume: number | null;
     readonly completedPeaks: number;
     readonly totalPeaks: number;
     readonly final: boolean;
@@ -13,10 +14,11 @@ type WaveformPeakProcessorOptions = {
 };
 type WaveformPeakProcessor = {
     readonly peaks: Float32Array;
-    processSampleChunk: (floats: Float32Array, channels: number) => void;
+    readonly averageVolume: number | null;
+    processSampleChunk: (floats: Float32Array, channels: number, sampleRate: number) => void;
     finalize: () => void;
 };
-export declare const emitWaveformProgress: ({ completedPeaks, final, onProgress, peaks, totalPeaks, }: Progress & {
+export declare const emitWaveformProgress: ({ averageVolume, completedPeaks, final, onProgress, peaks, totalPeaks, }: Progress & {
     readonly onProgress?: ((progress: Progress) => void) | undefined;
 }) => void;
 export declare const createWaveformPeakProcessor: ({ totalPeaks, samplesPerPeak, onProgress, progressIntervalInMs, now, }: WaveformPeakProcessorOptions) => WaveformPeakProcessor;

package/dist/audio-waveform/waveform-peak-processor.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWaveformPeakProcessor = exports.emitWaveformProgress = void 0;
-const emitWaveformProgress = ({ completedPeaks, final, onProgress, peaks, totalPeaks, }) => {
+const emitWaveformProgress = ({ averageVolume, completedPeaks, final, onProgress, peaks, totalPeaks, }) => {
     onProgress === null || onProgress === void 0 ? void 0 : onProgress({
+        averageVolume,
         peaks,
         completedPeaks,
         totalPeaks,
@@ -12,6 +13,8 @@ const emitWaveformProgress = ({ completedPeaks, final, onProgress, peaks, totalP
 exports.emitWaveformProgress = emitWaveformProgress;
 const createWaveformPeakProcessor = ({ totalPeaks, samplesPerPeak, onProgress, progressIntervalInMs, now, }) => {
     const peaks = new Float32Array(totalPeaks);
+    let energy = 0;
+    let duration = 0;
     let peakIndex = 0;
     let peakMax = 0;
     let sampleInPeak = 0;
@@ -28,6 +31,7 @@ const createWaveformPeakProcessor = ({ totalPeaks, samplesPerPeak, onProgress, p
         lastProgressAt = timestamp;
         lastProgressPeak = peakIndex;
         (0, exports.emitWaveformProgress)({
+            averageVolume: force && duration > 0 ? 10 * Math.log10(energy / duration) : null,
             peaks,
             completedPeaks: peakIndex,
             totalPeaks,
@@ -37,19 +41,26 @@ const createWaveformPeakProcessor = ({ totalPeaks, samplesPerPeak, onProgress, p
     };
     return {
         peaks,
-        processSampleChunk: (floats, channels) => {
+        get averageVolume() {
+            return duration > 0 ? 10 * Math.log10(energy / duration) : null;
+        },
+        processSampleChunk: (floats, channels, sampleRate) => {
             var _a;
             const frameCount = Math.floor(floats.length / Math.max(1, channels));
             for (let frame = 0; frame < frameCount; frame++) {
                 // `f32` copies are interleaved, so timing advances per frame.
                 let framePeak = 0;
+                let frameEnergy = 0;
                 for (let channel = 0; channel < channels; channel++) {
                     const sampleIndex = frame * channels + channel;
                     const abs = Math.abs((_a = floats[sampleIndex]) !== null && _a !== void 0 ? _a : 0);
+                    frameEnergy += abs * abs;
                     if (abs > framePeak) {
                         framePeak = abs;
                     }
                 }
+                energy += frameEnergy / channels / sampleRate;
+                duration += 1 / sampleRate;
                 if (framePeak > peakMax) {
                     peakMax = framePeak;
                 }

package/dist/audio-waveform-worker.js

@@ -2,11 +2,12 @@
 /// <reference lib="webworker" />
 Object.defineProperty(exports, "__esModule", { value: true });
 const load_waveform_peaks_1 = require("./audio-waveform/load-waveform-peaks");
-const postPeaks = (requestId, peaks, final) => {
+const postPeaks = (requestId, peaks, final, averageVolume) => {
     // Structured cloning copies the array, so the decoder can keep
     // mutating its buffer while the main thread reads the snapshot.
     const payload = {
         type: 'peaks',
+        averageVolume,
         requestId,
         peaks,
         final,
@@ -29,12 +30,12 @@ self.addEventListener('message', (event) => {
         waveformSampleRate: message.waveformSampleRate,
         onProgress: ({ peaks, final }) => {
             if (!final) {
-                postPeaks(message.requestId, peaks, false);
+                postPeaks(message.requestId, peaks, false, null);
             }
         },
     })
-        .then((peaks) => {
-        postPeaks(message.requestId, peaks, true);
+        .then(({ peaks, averageVolume }) => {
+        postPeaks(message.requestId, peaks, true, averageVolume);
     })
         .catch((error) => {
         postError(message.requestId, error);

package/dist/esm/audio-waveform-worker.mjs

@@ -4,6 +4,21 @@ import { ALL_FORMATS, AudioSampleSink, Input, UrlSource } from "mediabunny";
 // src/audio-waveform/constants.ts
 var TARGET_SAMPLE_RATE = 100;
 
+// src/audio-waveform/get-waveform-cache-key.ts
+var trackIds = new WeakMap;
+var nextTrackId = 0;
+var getWaveformCacheKey = (src, waveformSampleRate) => {
+  if (typeof src === "string") {
+    return `${waveformSampleRate}:url:${src}`;
+  }
+  let id = trackIds.get(src);
+  if (id === undefined) {
+    id = nextTrackId++;
+    trackIds.set(src, id);
+  }
+  return `${waveformSampleRate}:track:${id}`;
+};
+
 // src/audio-waveform/trim-audio-sample-before-zero.ts
 var getAudioSampleStartFrameAtTimelineZero = (sample) => {
   if (sample.timestamp + sample.duration <= 0) {
@@ -17,6 +32,7 @@ var getAudioSampleStartFrameAtTimelineZero = (sample) => {
 
 // src/audio-waveform/waveform-peak-processor.ts
 var emitWaveformProgress = ({
+  averageVolume,
   completedPeaks,
   final,
   onProgress,
@@ -24,6 +40,7 @@ var emitWaveformProgress = ({
   totalPeaks
 }) => {
   onProgress?.({
+    averageVolume,
     peaks,
     completedPeaks,
     totalPeaks,
@@ -38,6 +55,8 @@ var createWaveformPeakProcessor = ({
   now
 }) => {
   const peaks = new Float32Array(totalPeaks);
+  let energy = 0;
+  let duration = 0;
   let peakIndex = 0;
   let peakMax = 0;
   let sampleInPeak = 0;
@@ -54,6 +73,7 @@ var createWaveformPeakProcessor = ({
     lastProgressAt = timestamp;
     lastProgressPeak = peakIndex;
     emitWaveformProgress({
+      averageVolume: force && duration > 0 ? 10 * Math.log10(energy / duration) : null,
       peaks,
       completedPeaks: peakIndex,
       totalPeaks,
@@ -63,17 +83,24 @@ var createWaveformPeakProcessor = ({
   };
   return {
     peaks,
-    processSampleChunk: (floats, channels) => {
+    get averageVolume() {
+      return duration > 0 ? 10 * Math.log10(energy / duration) : null;
+    },
+    processSampleChunk: (floats, channels, sampleRate) => {
       const frameCount = Math.floor(floats.length / Math.max(1, channels));
       for (let frame = 0;frame < frameCount; frame++) {
         let framePeak = 0;
+        let frameEnergy = 0;
         for (let channel = 0;channel < channels; channel++) {
           const sampleIndex = frame * channels + channel;
           const abs = Math.abs(floats[sampleIndex] ?? 0);
+          frameEnergy += abs * abs;
           if (abs > framePeak) {
             framePeak = abs;
           }
         }
+        energy += frameEnergy / channels / sampleRate;
+        duration += 1 / sampleRate;
         if (framePeak > peakMax) {
           peakMax = framePeak;
         }
@@ -102,37 +129,35 @@ var createWaveformPeakProcessor = ({
 // src/audio-waveform/load-waveform-peaks.ts
 var DEFAULT_PROGRESS_INTERVAL_IN_MS = 50;
 var peaksCache = new Map;
-async function loadWaveformPeaks(url, signal, options) {
+async function loadWaveformPeaks(src, signal, options) {
   const waveformSampleRate = options?.waveformSampleRate ?? TARGET_SAMPLE_RATE;
   if (!Number.isFinite(waveformSampleRate) || waveformSampleRate <= 0) {
     throw new Error("The waveform sample rate must be a positive number.");
   }
-  const cacheKey = `${waveformSampleRate}:${url}`;
+  const cacheKey = getWaveformCacheKey(src, waveformSampleRate);
   const cached = peaksCache.get(cacheKey);
   if (cached) {
     emitWaveformProgress({
-      peaks: cached,
-      completedPeaks: cached.length,
-      totalPeaks: cached.length,
+      peaks: cached.peaks,
+      averageVolume: cached.averageVolume,
+      completedPeaks: cached.peaks.length,
+      totalPeaks: cached.peaks.length,
       final: true,
       onProgress: options?.onProgress
     });
     return cached;
   }
-  const input = new Input({
-    formats: ALL_FORMATS,
-    source: new UrlSource(url)
-  });
+  const input = typeof src === "string" ? new Input({ formats: ALL_FORMATS, source: new UrlSource(src) }) : null;
   try {
-    const audioTrack = await input.getPrimaryAudioTrack();
+    const audioTrack = typeof src === "string" ? await input.getPrimaryAudioTrack() : src;
     if (!audioTrack) {
-      return new Float32Array(0);
+      return { peaks: new Float32Array(0), averageVolume: null };
     }
     if (await audioTrack.isLive()) {
-      throw new Error("Live streams are not currently supported by Remotion. Sorry! Source: " + url);
+      throw new Error("Live streams are not currently supported by Remotion. Sorry! Source: " + (typeof src === "string" ? src : `audio track ${src.id}`));
     }
     if (await audioTrack.isRelativeToUnixEpoch()) {
-      throw new Error("Streams with UNIX timestamps are not currently supported by Remotion. Sorry! Source: " + url);
+      throw new Error("Streams with UNIX timestamps are not currently supported by Remotion. Sorry! Source: " + (typeof src === "string" ? src : `audio track ${src.id}`));
     }
     const audioSampleRate = await audioTrack.getSampleRate();
     const durationInSeconds = await audioTrack.getDurationFromMetadata({ skipLiveWait: true }) ?? await audioTrack.computeDuration({ skipLiveWait: true });
@@ -149,7 +174,7 @@ async function loadWaveformPeaks(url, signal, options) {
     for await (const sample of sink.samples()) {
       if (signal.aborted) {
         sample.close();
-        return new Float32Array(0);
+        return { peaks: new Float32Array(0), averageVolume: null };
       }
       const startFrame = getAudioSampleStartFrameAtTimelineZero(sample);
       if (startFrame === null) {
@@ -175,22 +200,27 @@ async function loadWaveformPeaks(url, signal, options) {
         frameCount
       });
       const channels = Math.max(1, sample.numberOfChannels);
+      const { sampleRate } = sample;
       sample.close();
-      processor.processSampleChunk(floats, channels);
+      processor.processSampleChunk(floats, channels, sampleRate);
     }
     processor.finalize();
-    const { peaks } = processor;
-    peaksCache.set(cacheKey, peaks);
-    return peaks;
+    const result = {
+      peaks: processor.peaks,
+      averageVolume: processor.averageVolume
+    };
+    peaksCache.set(cacheKey, result);
+    return result;
   } finally {
-    input.dispose();
+    input?.dispose();
   }
 }
 
 // src/audio-waveform-worker.ts
-var postPeaks = (requestId, peaks, final) => {
+var postPeaks = (requestId, peaks, final, averageVolume) => {
   const payload = {
     type: "peaks",
+    averageVolume,
     requestId,
     peaks,
     final
@@ -213,11 +243,11 @@ self.addEventListener("message", (event) => {
     waveformSampleRate: message.waveformSampleRate,
     onProgress: ({ peaks, final }) => {
       if (!final) {
-        postPeaks(message.requestId, peaks, false);
+        postPeaks(message.requestId, peaks, false, null);
       }
     }
-  }).then((peaks) => {
-    postPeaks(message.requestId, peaks, true);
+  }).then(({ peaks, averageVolume }) => {
+    postPeaks(message.requestId, peaks, true, averageVolume);
   }).catch((error) => {
     postError(message.requestId, error);
   });

package/dist/esm/index.mjs

@@ -17,6 +17,7 @@ var parseColor = (color) => {
 
 // src/audio-waveform/draw-peaks.ts
 var CLIPPING_COLOR = "#FF7F50";
+var WAVEFORM_HEIGHT_SCALE = 0.8;
 var getVolumeAtBar = ({
   barIndex,
   numBars,
@@ -56,6 +57,7 @@ var drawBars = ({
   const imageData = ctx.createImageData(w, height);
   const { data } = imageData;
   const numBars = width;
+  const fullScaleHalfBar = height * WAVEFORM_HEIGHT_SCALE / 2;
   for (let barIndex = 0;barIndex < numBars; barIndex++) {
     const x = barIndex;
     if (x >= w)
@@ -64,15 +66,15 @@ var drawBars = ({
     const peak = peaks[peakIndex] || 0;
     const barVolume = getVolumeAtBar({ barIndex, numBars, volume });
     const scaledPeak = peak * barVolume;
-    const halfBar = Math.max(0, Math.min(height / 2, scaledPeak * height / 2));
+    const halfBar = Math.max(0, Math.min(height / 2, scaledPeak * fullScaleHalfBar));
     if (halfBar === 0)
       continue;
     const mid = height / 2;
     const barY = Math.round(mid - halfBar);
     const barEnd = Math.round(mid + halfBar);
     const isClipping = scaledPeak > 1;
-    const clipTopEnd = isClipping ? Math.min(barY + 2, barEnd) : barY;
-    const clipBotStart = isClipping ? Math.max(barEnd - 2, barY) : barEnd;
+    const clipTopEnd = isClipping ? Math.min(Math.max(barY + 2, Math.round(mid - fullScaleHalfBar)), barEnd) : barY;
+    const clipBotStart = isClipping ? Math.max(Math.min(barEnd - 2, Math.round(mid + fullScaleHalfBar)), barY) : barEnd;
     for (let y = barY;y < clipTopEnd; y++) {
       const idx = (y * w + x) * 4;
       data[idx] = cr;
@@ -176,6 +178,21 @@ var getVisibleWaveformVolume = ({
 // src/audio-waveform/load-waveform-peaks.ts
 import { ALL_FORMATS, AudioSampleSink, Input, UrlSource } from "mediabunny";
 
+// src/audio-waveform/get-waveform-cache-key.ts
+var trackIds = new WeakMap;
+var nextTrackId = 0;
+var getWaveformCacheKey = (src, waveformSampleRate) => {
+  if (typeof src === "string") {
+    return `${waveformSampleRate}:url:${src}`;
+  }
+  let id = trackIds.get(src);
+  if (id === undefined) {
+    id = nextTrackId++;
+    trackIds.set(src, id);
+  }
+  return `${waveformSampleRate}:track:${id}`;
+};
+
 // src/audio-waveform/trim-audio-sample-before-zero.ts
 var getAudioSampleStartFrameAtTimelineZero = (sample) => {
   if (sample.timestamp + sample.duration <= 0) {
@@ -189,6 +206,7 @@ var getAudioSampleStartFrameAtTimelineZero = (sample) => {
 
 // src/audio-waveform/waveform-peak-processor.ts
 var emitWaveformProgress = ({
+  averageVolume,
   completedPeaks,
   final,
   onProgress,
@@ -196,6 +214,7 @@ var emitWaveformProgress = ({
   totalPeaks
 }) => {
   onProgress?.({
+    averageVolume,
     peaks,
     completedPeaks,
     totalPeaks,
@@ -210,6 +229,8 @@ var createWaveformPeakProcessor = ({
   now
 }) => {
   const peaks = new Float32Array(totalPeaks);
+  let energy = 0;
+  let duration = 0;
   let peakIndex = 0;
   let peakMax = 0;
   let sampleInPeak = 0;
@@ -226,6 +247,7 @@ var createWaveformPeakProcessor = ({
     lastProgressAt = timestamp;
     lastProgressPeak = peakIndex;
     emitWaveformProgress({
+      averageVolume: force && duration > 0 ? 10 * Math.log10(energy / duration) : null,
       peaks,
       completedPeaks: peakIndex,
       totalPeaks,
@@ -235,17 +257,24 @@ var createWaveformPeakProcessor = ({
   };
   return {
     peaks,
-    processSampleChunk: (floats, channels) => {
+    get averageVolume() {
+      return duration > 0 ? 10 * Math.log10(energy / duration) : null;
+    },
+    processSampleChunk: (floats, channels, sampleRate) => {
       const frameCount = Math.floor(floats.length / Math.max(1, channels));
       for (let frame = 0;frame < frameCount; frame++) {
         let framePeak = 0;
+        let frameEnergy = 0;
         for (let channel = 0;channel < channels; channel++) {
           const sampleIndex = frame * channels + channel;
           const abs = Math.abs(floats[sampleIndex] ?? 0);
+          frameEnergy += abs * abs;
           if (abs > framePeak) {
             framePeak = abs;
           }
         }
+        energy += frameEnergy / channels / sampleRate;
+        duration += 1 / sampleRate;
         if (framePeak > peakMax) {
           peakMax = framePeak;
         }
@@ -274,37 +303,35 @@ var createWaveformPeakProcessor = ({
 // src/audio-waveform/load-waveform-peaks.ts
 var DEFAULT_PROGRESS_INTERVAL_IN_MS = 50;
 var peaksCache = new Map;
-async function loadWaveformPeaks(url, signal, options) {
+async function loadWaveformPeaks(src, signal, options) {
   const waveformSampleRate = options?.waveformSampleRate ?? TARGET_SAMPLE_RATE;
   if (!Number.isFinite(waveformSampleRate) || waveformSampleRate <= 0) {
     throw new Error("The waveform sample rate must be a positive number.");
   }
-  const cacheKey = `${waveformSampleRate}:${url}`;
+  const cacheKey = getWaveformCacheKey(src, waveformSampleRate);
   const cached = peaksCache.get(cacheKey);
   if (cached) {
     emitWaveformProgress({
-      peaks: cached,
-      completedPeaks: cached.length,
-      totalPeaks: cached.length,
+      peaks: cached.peaks,
+      averageVolume: cached.averageVolume,
+      completedPeaks: cached.peaks.length,
+      totalPeaks: cached.peaks.length,
       final: true,
       onProgress: options?.onProgress
     });
     return cached;
   }
-  const input = new Input({
-    formats: ALL_FORMATS,
-    source: new UrlSource(url)
-  });
+  const input = typeof src === "string" ? new Input({ formats: ALL_FORMATS, source: new UrlSource(src) }) : null;
   try {
-    const audioTrack = await input.getPrimaryAudioTrack();
+    const audioTrack = typeof src === "string" ? await input.getPrimaryAudioTrack() : src;
     if (!audioTrack) {
-      return new Float32Array(0);
+      return { peaks: new Float32Array(0), averageVolume: null };
     }
     if (await audioTrack.isLive()) {
-      throw new Error("Live streams are not currently supported by Remotion. Sorry! Source: " + url);
+      throw new Error("Live streams are not currently supported by Remotion. Sorry! Source: " + (typeof src === "string" ? src : `audio track ${src.id}`));
     }
     if (await audioTrack.isRelativeToUnixEpoch()) {
-      throw new Error("Streams with UNIX timestamps are not currently supported by Remotion. Sorry! Source: " + url);
+      throw new Error("Streams with UNIX timestamps are not currently supported by Remotion. Sorry! Source: " + (typeof src === "string" ? src : `audio track ${src.id}`));
     }
     const audioSampleRate = await audioTrack.getSampleRate();
     const durationInSeconds = await audioTrack.getDurationFromMetadata({ skipLiveWait: true }) ?? await audioTrack.computeDuration({ skipLiveWait: true });
@@ -321,7 +348,7 @@ async function loadWaveformPeaks(url, signal, options) {
     for await (const sample of sink.samples()) {
       if (signal.aborted) {
         sample.close();
-        return new Float32Array(0);
+        return { peaks: new Float32Array(0), averageVolume: null };
       }
       const startFrame = getAudioSampleStartFrameAtTimelineZero(sample);
       if (startFrame === null) {
@@ -347,15 +374,19 @@ async function loadWaveformPeaks(url, signal, options) {
         frameCount
       });
       const channels = Math.max(1, sample.numberOfChannels);
+      const { sampleRate } = sample;
       sample.close();
-      processor.processSampleChunk(floats, channels);
+      processor.processSampleChunk(floats, channels, sampleRate);
     }
     processor.finalize();
-    const { peaks } = processor;
-    peaksCache.set(cacheKey, peaks);
-    return peaks;
+    const result = {
+      peaks: processor.peaks,
+      averageVolume: processor.averageVolume
+    };
+    peaksCache.set(cacheKey, result);
+    return result;
   } finally {
-    input.dispose();
+    input?.dispose();
   }
 }
 // src/audio-waveform/slice-waveform-peaks.ts
@@ -455,9 +486,9 @@ var inFlightByRequestId = new Map;
 var worker = null;
 var workerFailed = false;
 var nextRequestId = 0;
-var emitPeaks = (load, peaks, final) => {
+var emitPeaks = (load, peaks, final, averageVolume) => {
   if (final) {
-    peaksCache2.set(load.cacheKey, peaks);
+    peaksCache2.set(load.cacheKey, { peaks, averageVolume });
     load.latestPeaks = null;
     inFlightByCacheKey.delete(load.cacheKey);
     if (load.requestId !== null) {
@@ -467,7 +498,7 @@ var emitPeaks = (load, peaks, final) => {
     load.latestPeaks = peaks;
   }
   for (const listener of load.listeners) {
-    listener.onPeaks(peaks, final);
+    listener.onPeaks(peaks, final, averageVolume);
   }
 };
 var emitError = (load, error) => {
@@ -488,10 +519,10 @@ var startMainThreadLoad = (load) => {
       if (final) {
         return;
       }
-      emitPeaks(load, peaks.slice(), false);
+      emitPeaks(load, peaks.slice(), false, null);
     }
-  }).then((peaks) => {
-    emitPeaks(load, peaks, true);
+  }).then(({ peaks, averageVolume }) => {
+    emitPeaks(load, peaks, true, averageVolume);
   }).catch((error) => {
     emitError(load, error instanceof Error ? error : new Error("Failed to load waveform peaks"));
   });
@@ -529,7 +560,7 @@ var getOrCreateWorker = () => {
       emitError(load, new Error(message.message));
       return;
     }
-    emitPeaks(load, message.peaks, message.final);
+    emitPeaks(load, message.peaks, message.final, message.averageVolume);
   });
   worker.addEventListener("error", (event) => {
     event.preventDefault();
@@ -543,10 +574,10 @@ var subscribeToWaveformPeaks = ({
   onPeaks,
   onError
 }) => {
-  const cacheKey = `${waveformSampleRate}:${src}`;
+  const cacheKey = getWaveformCacheKey(src, waveformSampleRate);
   const cached = peaksCache2.get(cacheKey);
   if (cached) {
-    onPeaks(cached, true);
+    onPeaks(cached.peaks, true, cached.averageVolume);
     return () => {
       return;
     };
@@ -556,7 +587,7 @@ var subscribeToWaveformPeaks = ({
   if (existing) {
     existing.listeners.add(listener);
     if (existing.latestPeaks) {
-      onPeaks(existing.latestPeaks, false);
+      onPeaks(existing.latestPeaks, false, null);
     }
     return () => {
       existing.listeners.delete(listener);
@@ -571,8 +602,8 @@ var subscribeToWaveformPeaks = ({
     requestId: null
   };
   inFlightByCacheKey.set(cacheKey, load);
-  const workerInstance = getOrCreateWorker();
-  if (workerInstance) {
+  const workerInstance = typeof src === "string" ? getOrCreateWorker() : null;
+  if (workerInstance && typeof src === "string") {
     const requestId = nextRequestId++;
     load.requestId = requestId;
     inFlightByRequestId.set(requestId, load);
@@ -1099,6 +1130,13 @@ var renderFrameStripToCanvas = async ({
     frameHeight
   });
 };
+// src/format-average-audio-volume.ts
+var formatAverageAudioVolume = (volume) => {
+  if (volume === null) {
+    return "Unavailable";
+  }
+  return volume === -Infinity ? "−∞ dBFS (silent)" : `${volume.toFixed(1)} dBFS`;
+};
 export {
   subscribeToWaveformPeaks,
   sliceWaveformPeaks,
@@ -1116,6 +1154,7 @@ export {
   getDurationOfOneFrame,
   getAspectRatioFromCache,
   frameDatabase,
+  formatAverageAudioVolume,
   fillWithCachedFrames,
   fillFrameWhereItFits,
   extractFrames,

package/dist/format-average-audio-volume.d.ts

@@ -0,0 +1 @@
+export declare const formatAverageAudioVolume: (volume: number | null) => string;

package/dist/format-average-audio-volume.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatAverageAudioVolume = void 0;
+const formatAverageAudioVolume = (volume) => {
+    if (volume === null) {
+        return 'Unavailable';
+    }
+    return volume === -Infinity
+        ? '−∞ dBFS (silent)'
+        : `${volume.toFixed(1)} dBFS`;
+};
+exports.formatAverageAudioVolume = formatAverageAudioVolume;

package/dist/index.d.ts

@@ -18,3 +18,4 @@ export { WEBCODECS_TIMESCALE, calculateTimestampSlots, drawSlot, ensureSlots, fi
 export { renderFrameStripToCanvas } from './render-frame-strip-to-canvas';
 export type { RenderFrameStripToCanvasOptions } from './render-frame-strip-to-canvas';
 export { resizeVideoFrame } from './resize-video-frame';
+export { formatAverageAudioVolume } from './format-average-audio-volume';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.resizeVideoFrame = exports.renderFrameStripToCanvas = exports.getDurationOfOneFrame = exports.fillWithCachedFrames = exports.fillFrameWhereItFits = exports.ensureSlots = exports.drawSlot = exports.calculateTimestampSlots = exports.WEBCODECS_TIMESCALE = exports.shouldTileLoopDisplay = exports.getLoopDisplayWidth = exports.getLoopDisplaySegments = exports.makeFrameDatabaseKey = exports.getTimestampFromFrameDatabaseKey = exports.getFrameDatabaseKeyPrefix = exports.getAspectRatioFromCache = exports.frameDatabase = exports.aspectRatioCache = exports.addFrameToCache = exports.extractFrames = exports.clampTimestampsToDuration = exports.emitWaveformProgress = exports.createWaveformPeakProcessor = exports.sliceWaveformPeaks = exports.subscribeToWaveformPeaks = exports.sliceVisibleWaveformPeaks = exports.loadWaveformPeaks = exports.getVisibleWaveformVolume = exports.drawBars = exports.TARGET_SAMPLE_RATE = void 0;
+exports.formatAverageAudioVolume = exports.resizeVideoFrame = exports.renderFrameStripToCanvas = exports.getDurationOfOneFrame = exports.fillWithCachedFrames = exports.fillFrameWhereItFits = exports.ensureSlots = exports.drawSlot = exports.calculateTimestampSlots = exports.WEBCODECS_TIMESCALE = exports.shouldTileLoopDisplay = exports.getLoopDisplayWidth = exports.getLoopDisplaySegments = exports.makeFrameDatabaseKey = exports.getTimestampFromFrameDatabaseKey = exports.getFrameDatabaseKeyPrefix = exports.getAspectRatioFromCache = exports.frameDatabase = exports.aspectRatioCache = exports.addFrameToCache = exports.extractFrames = exports.clampTimestampsToDuration = exports.emitWaveformProgress = exports.createWaveformPeakProcessor = exports.sliceWaveformPeaks = exports.subscribeToWaveformPeaks = exports.sliceVisibleWaveformPeaks = exports.loadWaveformPeaks = exports.getVisibleWaveformVolume = exports.drawBars = exports.TARGET_SAMPLE_RATE = void 0;
 const constants_1 = require("./audio-waveform/constants");
 Object.defineProperty(exports, "TARGET_SAMPLE_RATE", { enumerable: true, get: function () { return constants_1.TARGET_SAMPLE_RATE; } });
 const draw_peaks_1 = require("./audio-waveform/draw-peaks");
@@ -46,3 +46,5 @@ const render_frame_strip_to_canvas_1 = require("./render-frame-strip-to-canvas")
 Object.defineProperty(exports, "renderFrameStripToCanvas", { enumerable: true, get: function () { return render_frame_strip_to_canvas_1.renderFrameStripToCanvas; } });
 const resize_video_frame_1 = require("./resize-video-frame");
 Object.defineProperty(exports, "resizeVideoFrame", { enumerable: true, get: function () { return resize_video_frame_1.resizeVideoFrame; } });
+const format_average_audio_volume_1 = require("./format-average-audio-volume");
+Object.defineProperty(exports, "formatAverageAudioVolume", { enumerable: true, get: function () { return format_average_audio_volume_1.formatAverageAudioVolume; } });

package/package.json

@@ -3,7 +3,7 @@
 		"url": "https://github.com/remotion-dev/remotion/tree/main/packages/timeline-utils"
 	},
 	"name": "@remotion/timeline-utils",
-	"version": "4.0.522",
+	"version": "4.0.523",
 	"description": "Internal utilities for rendering Remotion timelines",
 	"main": "dist/index.js",
 	"scripts": {
@@ -22,11 +22,11 @@
 	},
 	"dependencies": {
 		"mediabunny": "1.55.5",
-		"remotion": "4.0.522"
+		"remotion": "4.0.523"
 	},
 	"devDependencies": {
 		"@mediabunny/server": "1.55.5",
-		"@remotion/eslint-config-internal": "4.0.522",
+		"@remotion/eslint-config-internal": "4.0.523",
 		"eslint": "9.19.0",
 		"@typescript/native-preview": "7.0.0-dev.20260217.1"
 	},