nodejs-audio-visualizer 4.5.1 → 5.1.0

package/src/image.ts

@@ -593,6 +593,104 @@ export const getVideoFrameColor = (bgrBuffer: Buffer, width: number, height: num
 export const invertColor = (color: Color) =>
   ({ red: 255 - color.red, green: 255 - color.green, blue: 255 - color.blue });
 
+/** Pixel shift strength for the cut frame and the frames after it. */
+export const CUT_SHAKE_AMPLITUDE_BY_OFFSET = [14, 9, 5, 3, 1] as const;
+export const CUT_SHAKE_PEAK_AMPLITUDE = 14;
+export const MIN_CUT_SHAKE_FRAMES = 3;
+export const SHAKE_DURATION_BEAT_FRACTION = 1 / 3;
+/** Camera shake fires on every Nth beat of the tempo grid (half a bar of 4/4). */
+export const CAMERA_SHAKE_EVERY_BEATS = 2;
+
+export const buildCutShakeAmplitudes = (periodFrames: number): number[] => {
+  if (!(periodFrames > 0)) {
+    return Array.from(CUT_SHAKE_AMPLITUDE_BY_OFFSET);
+  }
+  const frameCount = Math.max(
+    MIN_CUT_SHAKE_FRAMES,
+    Math.round(periodFrames * SHAKE_DURATION_BEAT_FRACTION),
+  );
+  if (frameCount === 1) {
+    return [CUT_SHAKE_PEAK_AMPLITUDE];
+  }
+  const decayTo = 1 / CUT_SHAKE_PEAK_AMPLITUDE;
+  const amplitudes: number[] = [];
+  for (let i = 0; i < frameCount; i++) {
+    const t = i / (frameCount - 1);
+    amplitudes.push(Math.max(1, Math.round(CUT_SHAKE_PEAK_AMPLITUDE * Math.pow(decayTo, t))));
+  }
+  return amplitudes;
+};
+
+const clampInt = (value: number, min: number, max: number) => {
+  if (value < min) {
+    return min;
+  }
+  if (value > max) {
+    return max;
+  }
+  return value;
+};
+
+export const getCutShakeOffset = (
+  frameIndex: number,
+  cutFrames: ReadonlySet<number>,
+  amplitudes: ReadonlyArray<number> = CUT_SHAKE_AMPLITUDE_BY_OFFSET,
+): { x: number; y: number } => {
+  if (amplitudes.length === 0) {
+    return { x: 0, y: 0 };
+  }
+  let framesAfterCut = -1;
+  let originCut = -1;
+  for (let offset = 0; offset < amplitudes.length; offset++) {
+    const cut = frameIndex - offset;
+    if (cutFrames.has(cut) && (framesAfterCut === -1 || offset < framesAfterCut)) {
+      framesAfterCut = offset;
+      originCut = cut;
+    }
+  }
+  if (framesAfterCut === -1) {
+    return { x: 0, y: 0 };
+  }
+  const amplitude = amplitudes[framesAfterCut];
+  const angle = originCut * 2.399 + framesAfterCut * 2.1;
+  return {
+    x: Math.round(Math.cos(angle) * amplitude),
+    y: Math.round(Math.sin(angle) * amplitude),
+  };
+};
+
+export const applyCameraShake = (
+  imageDstBuffer: EncodedBmp,
+  width: number,
+  height: number,
+  offsetX: number,
+  offsetY: number,
+) => {
+  const ox = Math.round(offsetX);
+  const oy = Math.round(offsetY);
+  if (ox === 0 && oy === 0) {
+    return;
+  }
+  const { shiftPos, rowBytes, data } = imageDstBuffer;
+  const pixelBytes = height * rowBytes;
+  const sourcePixels = Buffer.allocUnsafe(pixelBytes);
+  data.copy(sourcePixels, 0, shiftPos, shiftPos + pixelBytes);
+
+  for (let y = 0; y < height; y++) {
+    const srcY = clampInt(y - oy, 0, height - 1);
+    const dstRow = shiftPos + y * rowBytes;
+    const srcRow = srcY * rowBytes;
+    for (let x = 0; x < width; x++) {
+      const srcX = clampInt(x - ox, 0, width - 1);
+      const dstIndex = dstRow + x * 3;
+      const srcIndex = srcRow + srcX * 3;
+      data[dstIndex] = sourcePixels[srcIndex];
+      data[dstIndex + 1] = sourcePixels[srcIndex + 1];
+      data[dstIndex + 2] = sourcePixels[srcIndex + 2];
+    }
+  }
+};
+
 const hexToRgb = (hex: String) => {
   const red = parseInt(hex.substring(1, 3), 16);
   const green = parseInt(hex.substring(3, 5), 16);

package/src/index.ts

@@ -36,13 +36,13 @@ import {
   getAudioAutoHighlight,
   getAudioAutoHighlightCount,
 } from './config';
-import { createAudioBuffer, bufferToUInt8, createSpectrumsProcessor } from './audio';
-import { parseImage, getImageColor, getVideoFrameColor, invertColor, Color, convertToBmp, createSpectrumVisualizerFrameGenerator, createPolarVisualizerFrameGenerator, CreatePolarVisualizerFrameProps, CreateVisualizerFrameProps, CommonVisualizerFrameProps } from './image';
+import { createAudioBuffer, bufferToUInt8, createSpectrumsProcessor, pcmU8ToFloatSamples } from './audio';
+import { parseImage, getImageColor, getVideoFrameColor, invertColor, Color, convertToBmp, createSpectrumVisualizerFrameGenerator, createPolarVisualizerFrameGenerator, CreatePolarVisualizerFrameProps, CreateVisualizerFrameProps, CommonVisualizerFrameProps, applyCameraShake, getCutShakeOffset, buildCutShakeAmplitudes, CAMERA_SHAKE_EVERY_BEATS } from './image';
 import { normalizeInlineSubtitlesToSrt, lrcToSrt } from './subtitleConvert';
-import { spawnFfmpegVideoWriter, waitDrain, waitForProcessExit, getVideoInfo, spawnVideoFrameReader, readVideoFrame, detectSceneChanges, buildBeatSyncedSegments, writeConcatFile, writeSubtitlesFile, spawnConcatVideoFrameReader, cleanupConcatFile, cleanupTempFile } from './video';
+import { spawnFfmpegVideoWriter, waitDrain, waitForProcessExit, getVideoInfo, spawnVideoFrameReader, readVideoFrame, detectSceneChanges, buildBeatSyncedSegments, getCutFrameIndices, writeConcatFile, writeSubtitlesFile, spawnConcatVideoFrameReader, cleanupConcatFile, cleanupTempFile } from './video';
 import { createBpmEncoder, createBgrFrameEncoder, EncodedBmp } from './bpmEncoder';
-import { createBeatDetector } from './beats';
-export { BeatInfo, BeatDetectorOptions } from './beats';
+import { createBeatDetector, estimateTempo, TempoEstimate, beatGridFrameIndices, tempoForWindow, MAX_TEMPO_ANALYSIS_SECONDS } from './beats';
+export { BeatInfo, BeatDetectorOptions, TempoEstimate, estimateTempo, beatGridFrameIndices, shiftTempoPhase, tempoForWindow } from './beats';
 import { computeHighlightSlice, HIGHLIGHT_DURATION_SEC } from './highlight';
 import { waitForEventLoop } from './waitForEventLoop';
 export { computeHighlightSlice, HIGHLIGHT_DURATION_SEC, BeatFrameEvent, HighlightAudioSegment, HighlightRun } from './highlight';
@@ -138,7 +138,32 @@ const createVisualizerFrameGenerator = (
   defaultColor: Color,
   spectrumBusMargin: number
 ): (params: CommonVisualizerFrameProps) => EncodedBmp => {
-  if (!config.outVideo.spectrum) {
+  if (config.outVideo.spectrum) {
+    const createSpectrumVisualizerFrame = createSpectrumVisualizerFrameGenerator();
+    const spectrumWidth = getSpectrumWidthAbsolute(config, backgroundWidth);
+    const spectrumHeight = getSpectrumHeightAbsolute(config, backgroundHeight);
+    const spectrumX = getSpectrumXAbsolute(config, spectrumWidth, backgroundWidth);
+    const spectrumY = getSpectrumYAbsolute(config, spectrumHeight, backgroundHeight);
+    const spectrumRotation = getSpectrumRotation(config);
+    const spectrumColor = getSpectrumColor(config) || invertColor(defaultColor);
+    const spectrumEffect = getSpectrumEffect(config);
+    const spectrumOpacity = getSpectrumOpacityParsed(config);
+
+    return (params: CommonVisualizerFrameProps) => {
+      return createSpectrumVisualizerFrame({
+        ...params,
+        size: { width: spectrumWidth, height: spectrumHeight },
+        position: { x: spectrumX, y: spectrumY },
+        rotation: spectrumRotation,
+        margin: spectrumBusMargin,
+        color: spectrumColor,
+        opacity: spectrumOpacity,
+        spectrumEffect,
+      });
+    };
+  }
+
+  if (config.outVideo.polar) {
     const createPolarVisualizerFrame = createPolarVisualizerFrameGenerator();
     const polarX = getPolarXAbsolute(config, backgroundWidth);
     const polarY = getPolarYAbsolute(config, backgroundHeight);
@@ -163,28 +188,8 @@ const createVisualizerFrameGenerator = (
       });
     };
   }
-  const createSpectrumVisualizerFrame = createSpectrumVisualizerFrameGenerator();
-  const spectrumWidth = getSpectrumWidthAbsolute(config, backgroundWidth);
-  const spectrumHeight = getSpectrumHeightAbsolute(config, backgroundHeight);
-  const spectrumX = getSpectrumXAbsolute(config, spectrumWidth, backgroundWidth);
-  const spectrumY = getSpectrumYAbsolute(config, spectrumHeight, backgroundHeight);
-  const spectrumRotation = getSpectrumRotation(config);
-  const spectrumColor = getSpectrumColor(config) || invertColor(defaultColor);
-  const spectrumEffect = getSpectrumEffect(config);
-  const spectrumOpacity = getSpectrumOpacityParsed(config);
-
-  return (params: CommonVisualizerFrameProps) => {
-    return createSpectrumVisualizerFrame({
-      ...params,
-      size: { width: spectrumWidth, height: spectrumHeight },
-      position: { x: spectrumX, y: spectrumY },
-      rotation: spectrumRotation,
-      margin: spectrumBusMargin,
-      color: spectrumColor,
-      opacity: spectrumOpacity,
-      spectrumEffect,
-    });
-  };
+
+  return (params: CommonVisualizerFrameProps) => params.backgroundImageBuffer;
 };
 
 interface PreProcessedAudio {
@@ -261,11 +266,13 @@ async function prepareBackgroundForRender(params: {
   backgroundVideoPath: string | undefined;
   backgroundImagePath: string | undefined;
   beatFrameIndices: number[];
+  beatIntensities?: number[];
   framesCount: number;
   outputResolution: ReturnType<typeof getOutputResolution>;
   fps: number;
   autoEditVideo: boolean;
   readVideoFrameTimeout: number;
+  tempo?: TempoEstimate | null;
 }): Promise<{
   backgroundWidth: number;
   backgroundHeight: number;
@@ -275,17 +282,20 @@ async function prepareBackgroundForRender(params: {
   videoFrameSize: number;
   encodeVideoFrame?: (bgrBuffer: Buffer) => EncodedBmp;
   concatFilePath?: string;
+  cutFrameIndices: number[];
 }> {
   const {
     useVideoBackground,
     backgroundVideoPath,
     backgroundImagePath,
     beatFrameIndices,
+    beatIntensities,
     framesCount,
     outputResolution,
     fps,
     autoEditVideo,
     readVideoFrameTimeout,
+    tempo,
   } = params;
 
   if (useVideoBackground && backgroundVideoPath) {
@@ -304,9 +314,15 @@ async function prepareBackgroundForRender(params: {
       framesCount,
       sceneChanges,
       videoInfo.duration,
+      fps,
+      {
+        beatIntensities,
+        ...(autoEditVideo && tempo ? { tempo } : {}),
+      },
     );
 
     const concatFilePath = writeConcatFile(segments, backgroundVideoPath, videoInfo.duration, fps);
+    const cutFrameIndices = autoEditVideo ? getCutFrameIndices(segments) : [];
 
     const videoFrameReader = spawnConcatVideoFrameReader({
       concatFilePath,
@@ -339,6 +355,7 @@ async function prepareBackgroundForRender(params: {
       videoFrameSize,
       encodeVideoFrame,
       concatFilePath,
+      cutFrameIndices,
     };
   }
 
@@ -363,6 +380,7 @@ async function prepareBackgroundForRender(params: {
     defaultColor,
     staticBackgroundBuffer,
     videoFrameSize: 0,
+    cutFrameIndices: [],
   };
 }
 
@@ -497,6 +515,7 @@ export const renderAudioVisualizer = (config: Config, onProgress?: (progress: nu
     const autoHighlight = getAudioAutoHighlight(config);
     let spectrumsForRender = preprocessed.spectrums;
     let beatIndicesForRender = preprocessed.beatFrameIndices;
+    let beatIntensitiesForRender = preprocessed.beatEvents.map(event => event.intensity);
     let framesCountForRender = framesCount;
     type HighlightSliceResult = ReturnType<typeof computeHighlightSlice> extends Promise<
       infer R
@@ -516,12 +535,24 @@ export const renderAudioVisualizer = (config: Config, onProgress?: (progress: nu
       );
       spectrumsForRender = highlightSlice.spectrums;
       beatIndicesForRender = highlightSlice.beatFrameIndices;
+      beatIntensitiesForRender = highlightSlice.beatIntensities;
       framesCountForRender = highlightSlice.highlightFrames;
       reportProgress(PRE_PROCESS_PROGRESS_SHARE + POST_AUDIO_PROGRESS_SHARE);
     } else {
       reportProgress(PRE_PROCESS_PROGRESS_SHARE + POST_AUDIO_PROGRESS_SHARE);
     }
 
+    const autoEditVideo = getAutoEditVideo(config);
+    let trackTempo: TempoEstimate | null = null;
+    if (autoEditVideo) {
+      const sampleRateNum = Number(sampleRate);
+      const maxSamples = Math.floor(sampleRateNum * MAX_TEMPO_ANALYSIS_SECONDS);
+      const tempoBuffer = audioBuffer.length > maxSamples
+        ? audioBuffer.slice(0, maxSamples)
+        : audioBuffer;
+      trackTempo = estimateTempo(pcmU8ToFloatSamples(tempoBuffer), sampleRateNum, FPS);
+    }
+
     const separateHighlightFiles =
       autoHighlight &&
       highlightSlice &&
@@ -531,7 +562,9 @@ export const renderAudioVisualizer = (config: Config, onProgress?: (progress: nu
       outPath: string;
       spectrums: number[][];
       beatIndices: number[];
+      beatIntensities: number[];
       frameCount: number;
+      startFrame: number;
       audioSegment: import('./highlight').HighlightAudioSegment | undefined;
     };
 
@@ -546,7 +579,9 @@ export const renderAudioVisualizer = (config: Config, onProgress?: (progress: nu
             outPath: numberedPath,
             spectrums: run.spectrums,
             beatIndices: run.beatFrameIndices,
+            beatIntensities: run.beatIntensities,
             frameCount: run.highlightFrames,
+            startFrame: run.startFrame,
             audioSegment: run.audioSegment,
           };
         })
@@ -555,7 +590,9 @@ export const renderAudioVisualizer = (config: Config, onProgress?: (progress: nu
             outPath: outVideoPath,
             spectrums: spectrumsForRender,
             beatIndices: beatIndicesForRender,
+            beatIntensities: beatIntensitiesForRender,
             frameCount: framesCountForRender,
+            startFrame: highlightSlice?.startFrame ?? 0,
             audioSegment:
               autoHighlight &&
               highlightSlice &&
@@ -582,6 +619,12 @@ export const renderAudioVisualizer = (config: Config, onProgress?: (progress: nu
     const outputVideoFiles: string[] = [];
     try {
       passLoop: for (const pass of passes) {
+        const tempo = trackTempo
+          ? tempoForWindow(trackTempo, pass.startFrame, FPS, pass.frameCount, pass.beatIndices)
+          : null;
+        const shakeAmplitudes = tempo
+          ? buildCutShakeAmplitudes(tempo.periodFrames)
+          : undefined;
         const {
           backgroundWidth,
           backgroundHeight,
@@ -596,14 +639,23 @@ export const renderAudioVisualizer = (config: Config, onProgress?: (progress: nu
           backgroundVideoPath,
           backgroundImagePath,
           beatFrameIndices: pass.beatIndices,
+          beatIntensities: pass.beatIntensities,
           framesCount: pass.frameCount,
           outputResolution,
           fps: FPS,
-          autoEditVideo: getAutoEditVideo(config),
+          autoEditVideo,
           readVideoFrameTimeout: videoTimeouts.readVideoFrame,
+          ...(tempo ? { tempo } : {}),
         });
         reportRenderProgress();
 
+        const shakeFrames = new Set(
+          autoEditVideo
+            ? (tempo
+              ? beatGridFrameIndices(tempo, pass.frameCount, CAMERA_SHAKE_EVERY_BEATS)
+              : pass.beatIndices.filter(frameIndex => frameIndex > 0).filter((_, i) => i % CAMERA_SHAKE_EVERY_BEATS === 0))
+            : [],
+        );
         const createVisualizerFrame = createVisualizerFrameGenerator(
           config, backgroundWidth, backgroundHeight, defaultColor, spectrumBusMargin
         );
@@ -643,6 +695,10 @@ export const renderAudioVisualizer = (config: Config, onProgress?: (progress: nu
             spectrum,
           };
           const frameImage = createVisualizerFrame(commonVisualizerFrameProps);
+          const shakeOffset = getCutShakeOffset(i, shakeFrames, shakeAmplitudes);
+          if (shakeOffset.x !== 0 || shakeOffset.y !== 0) {
+            applyCameraShake(frameImage, backgroundWidth, backgroundHeight, shakeOffset.x, shakeOffset.y);
+          }
           const isFrameProcessed = ffmpegVideoWriter.stdin.write(frameImage.data);
           if (!isFrameProcessed) {
             const isDrained = await waitDrain(

package/src/tests/audio.test.ts

@@ -4,6 +4,7 @@ import child_process, { ChildProcessWithoutNullStreams } from 'child_process';
 import {
   bufferToUInt8,
   normalizeAudioData,
+  pcmU8ToFloatSamples,
   spawnFfmpegAudioReader,
   skipEvery,
   getPeaks,
@@ -42,6 +43,11 @@ describe('audio', function () {
     expect(result).deep.equal(expected);
   });
 
+  it('pcmU8ToFloatSamples', function () {
+    const buffer = Buffer.from([128, 255, 0]);
+    expect(pcmU8ToFloatSamples(buffer)).deep.equal([0, 127 / 128, -1]);
+  });
+
   it('spawnFfmpegAudioReader', function (done) {
     const childProcessReadableStream = new Readable();
     const childProcessWritableStream = new Writable();

package/src/tests/beats.test.ts

@@ -0,0 +1,134 @@
+import { expect } from 'chai';
+import { estimateTempo, beatGridFrameIndices, shiftTempoPhase, tempoForWindow } from '../beats';
+
+const clickTrain = (
+  sampleRate: number,
+  bpm: number,
+  durationSec: number,
+  phaseSec = 0,
+  halfPeriodGhost = 0,
+): number[] => {
+  const n = Math.round(sampleRate * durationSec);
+  const samples = new Array<number>(n).fill(0);
+  const period = 60 / bpm;
+  const clickLen = Math.round(sampleRate * 0.01);
+  const addClick = (timeSec: number, amplitude: number) => {
+    const start = Math.round(timeSec * sampleRate);
+    for (let i = 0; i < clickLen && start + i < n; i++) {
+      const env = Math.exp(-i / (clickLen * 0.25));
+      samples[start + i] += amplitude * env * (i % 2 === 0 ? 1 : -0.7);
+    }
+  };
+  for (let t = phaseSec; t < durationSec; t += period) {
+    addClick(t, 1);
+    if (halfPeriodGhost > 0) {
+      addClick(t + period / 2, halfPeriodGhost);
+    }
+  }
+  return samples;
+};
+
+describe('beats', function () {
+  this.timeout(10000);
+
+  it('estimateTempo detects 128 BPM from a click train', function () {
+    const sampleRate = 22050;
+    const fps = 30;
+    const tempo = estimateTempo(clickTrain(sampleRate, 128, 8), sampleRate, fps);
+    expect(tempo).not.equal(null);
+    expect(tempo!.bpm).closeTo(128, 8);
+    expect(tempo!.periodFrames).closeTo(fps * 60 / 128, 1);
+  });
+
+  it('estimateTempo recovers phase of the click train', function () {
+    const sampleRate = 22050;
+    const fps = 30;
+    const phaseSec = 0.1;
+    const tempo = estimateTempo(clickTrain(sampleRate, 128, 8, phaseSec), sampleRate, fps);
+    expect(tempo).not.equal(null);
+    expect(tempo!.phaseFrame).closeTo(phaseSec * fps, 2);
+  });
+
+  it('estimateTempo prefers ~128 BPM when half-period ghosts are present', function () {
+    const sampleRate = 22050;
+    const fps = 30;
+    const tempo = estimateTempo(clickTrain(sampleRate, 128, 8, 0, 0.35), sampleRate, fps);
+    expect(tempo).not.equal(null);
+    expect(tempo!.bpm).closeTo(128, 8);
+  });
+
+  it('estimateTempo returns null for silence', function () {
+    const sampleRate = 22050;
+    const samples = new Array<number>(sampleRate * 2).fill(0);
+    expect(estimateTempo(samples, sampleRate, 30)).equal(null);
+  });
+
+  it('estimateTempo returns null for empty or invalid input', function () {
+    expect(estimateTempo([], 22050, 30)).equal(null);
+    expect(estimateTempo(clickTrain(22050, 128, 8), 0, 30)).equal(null);
+    expect(estimateTempo(clickTrain(22050, 128, 8), 22050, 0)).equal(null);
+  });
+
+  it('shiftTempoPhase wraps the beat grid into a later window', function () {
+    expect(shiftTempoPhase({ bpm: 120, periodFrames: 15, phaseFrame: 3 }, 0)).deep.equal({
+      bpm: 120,
+      periodFrames: 15,
+      phaseFrame: 3,
+    });
+    expect(shiftTempoPhase({ bpm: 120, periodFrames: 15, phaseFrame: 3 }, 3).phaseFrame).equal(0);
+    expect(shiftTempoPhase({ bpm: 120, periodFrames: 15, phaseFrame: 3 }, 18).phaseFrame).equal(0);
+  });
+
+  it('shiftTempoPhase keeps a non-integer period aligned in a late window', function () {
+    const tempo = { bpm: 128, periodFrames: 14.0625, phaseFrame: 3 };
+    const startFrame = 2000;
+    const shifted = shiftTempoPhase(tempo, startFrame);
+    const expected: number[] = [];
+    for (let n = 0; n < 400; n++) {
+      const local = Math.round(tempo.phaseFrame + n * tempo.periodFrames) - startFrame;
+      if (local > 0 && local < 60) {
+        expected.push(local);
+      }
+    }
+    expect(beatGridFrameIndices(shifted, 60)).deep.equal(expected);
+  });
+
+  it('tempoForWindow locks phase to beat times inside the edited window', function () {
+    const fps = 30;
+    const periodFrames = 15;
+    const startFrame = 90;
+    const tempo = {
+      bpm: 120,
+      periodFrames,
+      phaseFrame: 1,
+      beatsSec: [0.1, 3.2, 3.7, 4.2, 4.7],
+    };
+    const windowed = tempoForWindow(tempo, startFrame, fps, 60);
+    expect(windowed.phaseFrame).closeTo(6, 1);
+    expect(shiftTempoPhase(tempo, startFrame).phaseFrame).closeTo(1, 0.001);
+    expect(beatGridFrameIndices(windowed, 50)[0]).closeTo(6, 1);
+    expect(tempoForWindow(tempo, startFrame, fps, 60, [1, 16, 31]).phaseFrame).closeTo(6, 1);
+  });
+
+  it('tempoForWindow falls back to local onsets when beat times are outside the window', function () {
+    const tempo = {
+      bpm: 120,
+      periodFrames: 15,
+      phaseFrame: 1,
+      beatsSec: [0.1, 0.6, 1.1],
+    };
+    const windowed = tempoForWindow(tempo, 90, 30, 60, [7, 22, 37]);
+    expect(windowed.phaseFrame).closeTo(7, 1);
+  });
+
+  it('beatGridFrameIndices emits every beat and skips frame 0', function () {
+    expect(beatGridFrameIndices({ periodFrames: 14, phaseFrame: 0 }, 50)).deep.equal([14, 28, 42]);
+    expect(beatGridFrameIndices({ periodFrames: 14, phaseFrame: 3 }, 32)).deep.equal([3, 17, 31]);
+    expect(beatGridFrameIndices({ periodFrames: 14, phaseFrame: 0 }, 14)).deep.equal([]);
+  });
+
+  it('beatGridFrameIndices stride emits every Nth beat', function () {
+    expect(beatGridFrameIndices({ periodFrames: 14, phaseFrame: 0 }, 200, 4)).deep.equal([14, 70, 126, 182]);
+    expect(beatGridFrameIndices({ periodFrames: 14, phaseFrame: 3 }, 200, 4)).deep.equal([3, 59, 115, 171]);
+  });
+});

package/src/tests/image.test.ts

@@ -9,6 +9,9 @@ import {
   convertToBmp,
   mixValues,
   mixColors,
+  applyCameraShake,
+  getCutShakeOffset,
+  buildCutShakeAmplitudes,
 } from '../image';
 import { createBpmEncoder } from '../bpmEncoder';
 
@@ -77,6 +80,89 @@ describe('image', function () {
     expect(imageDstBuffer.data).deep.equal(expectedImageData);
   });
 
+  it('getCutShakeOffset peaks on the cut and decays on the next frames', function () {
+    const cutFrames = new Set([10, 20]);
+    const magnitude = (offset: { x: number; y: number }) => Math.hypot(offset.x, offset.y);
+    expect(getCutShakeOffset(9, cutFrames)).deep.equal({ x: 0, y: 0 });
+    expect(magnitude(getCutShakeOffset(10, cutFrames))).greaterThan(magnitude(getCutShakeOffset(11, cutFrames)));
+    expect(magnitude(getCutShakeOffset(11, cutFrames))).greaterThan(magnitude(getCutShakeOffset(12, cutFrames)));
+    expect(magnitude(getCutShakeOffset(12, cutFrames))).greaterThan(magnitude(getCutShakeOffset(13, cutFrames)));
+    expect(getCutShakeOffset(15, cutFrames)).deep.equal({ x: 0, y: 0 });
+    expect(magnitude(getCutShakeOffset(20, cutFrames))).greaterThan(0);
+  });
+
+  it('getCutShakeOffset uses the closer overlapping cut', function () {
+    const cutFrames = new Set([10, 11]);
+    expect(getCutShakeOffset(11, cutFrames)).deep.equal(getCutShakeOffset(11, new Set([11])));
+  });
+
+  it('buildCutShakeAmplitudes lasts about one-third of a beat', function () {
+    const at128 = buildCutShakeAmplitudes(14);
+    expect(at128.length).equal(5);
+    expect(at128[0]).equal(14);
+    expect(at128[at128.length - 1]).equal(1);
+    expect(buildCutShakeAmplitudes(30).length).equal(10);
+    expect(buildCutShakeAmplitudes(6).length).equal(3);
+  });
+
+  it('getCutShakeOffset uses a longer envelope when amplitudes are passed', function () {
+    const cutFrames = new Set([10]);
+    const longAmp = buildCutShakeAmplitudes(30);
+    const magnitude = (offset: { x: number; y: number }) => Math.hypot(offset.x, offset.y);
+    expect(getCutShakeOffset(15, cutFrames)).deep.equal({ x: 0, y: 0 });
+    expect(magnitude(getCutShakeOffset(15, cutFrames, longAmp))).greaterThan(0);
+    expect(getCutShakeOffset(10 + longAmp.length, cutFrames, longAmp)).deep.equal({ x: 0, y: 0 });
+    expect(magnitude(getCutShakeOffset(10, cutFrames, longAmp))).greaterThan(
+      magnitude(getCutShakeOffset(12, cutFrames, longAmp)),
+    );
+  });
+
+  it('applyCameraShake shifts pixels and clamps edges', function () {
+    const width = 3;
+    const height = 2;
+    const extraBytes = width % 4;
+    const rowBytes = 3 * width + extraBytes;
+    const shiftPos = 4;
+    const data = Buffer.alloc(shiftPos + height * rowBytes, 0);
+    data[0] = 9;
+    data[1] = 8;
+    data[2] = 7;
+    data[3] = 6;
+    let value = 1;
+    for (let y = 0; y < height; y++) {
+      for (let x = 0; x < width; x++) {
+        const pixelIndex = shiftPos + y * rowBytes + x * 3;
+        data[pixelIndex] = value;
+        data[pixelIndex + 1] = value + 1;
+        data[pixelIndex + 2] = value + 2;
+        value += 3;
+      }
+    }
+
+    applyCameraShake({ shiftPos, rowBytes, data }, width, height, 1, 0);
+
+    expect(data[0]).equal(9);
+    expect(data[1]).equal(8);
+    expect(data[2]).equal(7);
+    expect(data[3]).equal(6);
+    const pixelAt = (x: number, y: number) => {
+      const pixelIndex = shiftPos + y * rowBytes + x * 3;
+      return [data[pixelIndex], data[pixelIndex + 1], data[pixelIndex + 2]];
+    };
+    expect(pixelAt(0, 0)).deep.equal([1, 2, 3]);
+    expect(pixelAt(1, 0)).deep.equal([1, 2, 3]);
+    expect(pixelAt(2, 0)).deep.equal([4, 5, 6]);
+    expect(pixelAt(0, 1)).deep.equal([10, 11, 12]);
+    expect(pixelAt(1, 1)).deep.equal([10, 11, 12]);
+    expect(pixelAt(2, 1)).deep.equal([13, 14, 15]);
+  });
+
+  it('applyCameraShake is a no-op at zero offset', function () {
+    const data = Buffer.from([1, 2, 3, 10, 20, 30]);
+    applyCameraShake({ shiftPos: 3, rowBytes: 3, data }, 1, 1, 0, 0);
+    expect(Array.from(data)).deep.equal([1, 2, 3, 10, 20, 30]);
+  });
+
   it('createSpectrumVisualizerFrameGenerator', async function () {
     const expectedImageLength = 6220854;
     const backgroundImagePath = path.resolve('example/media/horses.png');

package/src/tests/index.test.ts

@@ -77,6 +77,74 @@ describe('index', function () {
     expect(outputVideoFiles).deep.equal([path.resolve('outVideoPath')]);
   });
 
+  it('does not render a visualizer when neither spectrum nor polar is specified', async function () {
+    const polarSpy = sandbox.spy(image, 'createPolarVisualizerFrameGenerator');
+    const spectrumSpy = sandbox.spy(image, 'createSpectrumVisualizerFrameGenerator');
+    const config: Config = {
+      audio: {
+        path: 'audioPath'
+      },
+      image: {
+        path: 'example/media/horses.png'
+      },
+      outVideo: {
+        path: 'outVideoPath',
+        fps: 1
+      }
+    };
+
+    const { exitCode } = await renderAudioVisualizer(config);
+    expect(exitCode).equal(EXIT_CODE);
+    expect(polarSpy.called).equal(false);
+    expect(spectrumSpy.called).equal(false);
+  });
+
+  it('renders a polar visualizer when polar is specified', async function () {
+    const polarSpy = sandbox.spy(image, 'createPolarVisualizerFrameGenerator');
+    const spectrumSpy = sandbox.spy(image, 'createSpectrumVisualizerFrameGenerator');
+    const config: Config = {
+      audio: {
+        path: 'audioPath'
+      },
+      image: {
+        path: 'example/media/horses.png'
+      },
+      outVideo: {
+        path: 'outVideoPath',
+        fps: 1,
+        polar: {}
+      }
+    };
+
+    const { exitCode } = await renderAudioVisualizer(config);
+    expect(exitCode).equal(EXIT_CODE);
+    expect(polarSpy.calledOnce).equal(true);
+    expect(spectrumSpy.called).equal(false);
+  });
+
+  it('renders a spectrum visualizer when spectrum is specified', async function () {
+    const polarSpy = sandbox.spy(image, 'createPolarVisualizerFrameGenerator');
+    const spectrumSpy = sandbox.spy(image, 'createSpectrumVisualizerFrameGenerator');
+    const config: Config = {
+      audio: {
+        path: 'audioPath'
+      },
+      image: {
+        path: 'example/media/horses.png'
+      },
+      outVideo: {
+        path: 'outVideoPath',
+        fps: 1,
+        spectrum: {}
+      }
+    };
+
+    const { exitCode } = await renderAudioVisualizer(config);
+    expect(exitCode).equal(EXIT_CODE);
+    expect(spectrumSpy.calledOnce).equal(true);
+    expect(polarSpy.called).equal(false);
+  });
+
   it('resolves and does not report 100 when process completion times out', async function () {
     (this as any).setMockWriter(false);
     sandbox.stub(video, 'waitForProcessExit').callsFake(