nodejs-audio-visualizer 4.0.0 → 4.1.0

package/src/index.ts

@@ -1,6 +1,7 @@
 import {
   getAudioFilePath,
   getBackgroundImagePath,
+  getBackgroundVideoPath,
   getOutVideoPath,
   getFPS,
   getSpectrumBusMargin,
@@ -13,6 +14,7 @@ import {
   getFfmpeg_cfr,
   getFfmpeg_preset,
   getFrame_processing_delay,
+  getOutputResolution,
   rotationAliasValues,
   getSpectrumRotation,
   getSpectrumEffect,
@@ -25,12 +27,14 @@ import {
   getPolarEffect,
   getPolarColor,
   getPolarOpacityParsed,
+  getAutoEditVideo,
 } from './config';
 import { createAudioBuffer, bufferToUInt8, createSpectrumsProcessor } from './audio';
-import { parseImage, getImageColor, invertColor, Color, convertToBmp, createSpectrumVisualizerFrameGenerator, createPolarVisualizerFrameGenerator, CreatePolarVisualizerFrameProps, CreateVisualizerFrameProps, CommonVisualizerFrameProps } from './image';
-import { spawnFfmpegVideoWriter, getProgress, calculateProgress, waitDrain } from './video';
-import { createBpmEncoder, EncodedBmp } from './bpmEncoder';
-import { BmpDecoder } from 'bmp-js';
+import { parseImage, getImageColor, getVideoFrameColor, invertColor, Color, convertToBmp, createSpectrumVisualizerFrameGenerator, createPolarVisualizerFrameGenerator, CreatePolarVisualizerFrameProps, CreateVisualizerFrameProps, CommonVisualizerFrameProps } from './image';
+import { spawnFfmpegVideoWriter, getProgress, calculateProgress, waitDrain, getVideoInfo, spawnVideoFrameReader, readVideoFrame, detectSceneChanges, buildBeatSyncedSegments, writeConcatFile, spawnConcatVideoFrameReader, cleanupConcatFile } from './video';
+import { createBpmEncoder, createBgrFrameEncoder, EncodedBmp } from './bpmEncoder';
+import { createBeatDetector } from './beats';
+export { BeatInfo, BeatDetectorOptions } from './beats';
 
 export const PCM_FORMAT = {
   bit: 8,
@@ -44,12 +48,20 @@ export interface Config {
   audio: {
     path: string
   };
-  image: {
+  image?: {
     path: string;
   };
+  video?: {
+    path: string;
+    autoEdit?: boolean;
+  };
   outVideo: {
     path: string;
     fps?: number;
+    resolution?: {
+      width: number;
+      height: number;
+    };
     spectrum?: {
       width?: SpectrumSizeValue;
       height?: SpectrumSizeValue;
@@ -95,17 +107,19 @@ const sleep = (timeout: number) =>
 
 const createVisualizerFrameGenerator = (
   config: Config,
-  backgroundImage: BmpDecoder,
+  backgroundWidth: number,
+  backgroundHeight: number,
+  defaultColor: Color,
   spectrumBusMargin: number
 ): (params: CommonVisualizerFrameProps) => EncodedBmp => {
   if (!config.outVideo.spectrum) {
     const createPolarVisualizerFrame = createPolarVisualizerFrameGenerator();
-    const polarX = getPolarXAbsolute(config, backgroundImage.width);
-    const polarY = getPolarYAbsolute(config, backgroundImage.height);
+    const polarX = getPolarXAbsolute(config, backgroundWidth);
+    const polarY = getPolarYAbsolute(config, backgroundHeight);
     const polarInnerRadius = getPolarInnerRadius(config);
     const polarMaxBarLength = getPolarMaxBarLength(config);
     const polarBarWidth = getPolarBarWidth(config);
-    const polarColor = getPolarColor(config) || invertColor(getImageColor(backgroundImage));
+    const polarColor = getPolarColor(config) || invertColor(defaultColor);
     const polarEffect = getPolarEffect(config);
     const polarOpacity = getPolarOpacityParsed(config);
 
@@ -123,18 +137,18 @@ const createVisualizerFrameGenerator = (
       });
     };
   }
-  const createPolarVisualizerFrame = createSpectrumVisualizerFrameGenerator();
-  const spectrumWidth = getSpectrumWidthAbsolute(config, backgroundImage.width);
-  const spectrumHeight = getSpectrumHeightAbsolute(config, backgroundImage.height);
-  const spectrumX = getSpectrumXAbsolute(config, spectrumWidth, backgroundImage.width);
-  const spectrumY = getSpectrumYAbsolute(config, spectrumHeight, backgroundImage.height);
+  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(getImageColor(backgroundImage));
+  const spectrumColor = getSpectrumColor(config) || invertColor(defaultColor);
   const spectrumEffect = getSpectrumEffect(config);
   const spectrumOpacity = getSpectrumOpacityParsed(config);
 
   return (params: CommonVisualizerFrameProps) => {
-    return createPolarVisualizerFrame({
+    return createSpectrumVisualizerFrame({
       ...params,
       size: { width: spectrumWidth, height: spectrumHeight },
       position: { x: spectrumX, y: spectrumY },
@@ -147,19 +161,195 @@ const createVisualizerFrameGenerator = (
   };
 };
 
+interface PreProcessedAudio {
+  spectrums: number[][];
+  beatFrameIndices: number[];
+}
+
+const preProcessAudio = (
+  audioBuffer: Buffer,
+  sampleRate: number,
+  fps: number,
+  framesCount: number,
+): PreProcessedAudio => {
+  const audioDataStep = Math.trunc(audioBuffer.length / framesCount);
+  const processingBuffer = new Float32Array(PROCESSING_BUFFER_SIZE).fill(0);
+  const skipFramesCount = fps < 45 ? 1 : 2;
+  const processSpectrum = createSpectrumsProcessor(sampleRate, skipFramesCount);
+  const detectBeat = createBeatDetector(fps);
+
+  const spectrums: number[][] = [];
+  const beatFrameIndices: number[] = [];
+
+  for (let i = 0; i < framesCount; i++) {
+    const currentFrameData = PCM_FORMAT.parseFunction(audioBuffer, i * audioDataStep, i * audioDataStep + audioDataStep);
+    processingBuffer.copyWithin(0, currentFrameData.length);
+    processingBuffer.set(currentFrameData, PROCESSING_BUFFER_SIZE - currentFrameData.length);
+
+    const audioDataParser = () => Array.from(processingBuffer);
+    const spectrum = processSpectrum(audioDataParser);
+    const beat = detectBeat(spectrum);
+
+    spectrums.push(spectrum);
+    if (beat.isBeat) {
+      beatFrameIndices.push(i);
+    }
+  }
+
+  return { spectrums, beatFrameIndices };
+};
+
+async function prepareBackgroundForRender(params: {
+  useVideoBackground: boolean;
+  backgroundVideoPath: string | undefined;
+  backgroundImagePath: string | undefined;
+  beatFrameIndices: number[];
+  framesCount: number;
+  outputResolution: ReturnType<typeof getOutputResolution>;
+  fps: number;
+  autoEditVideo: boolean;
+}): Promise<{
+  backgroundWidth: number;
+  backgroundHeight: number;
+  defaultColor: Color;
+  staticBackgroundBuffer: EncodedBmp;
+  videoFrameReader?: ReturnType<typeof spawnVideoFrameReader>;
+  videoFrameSize: number;
+  encodeVideoFrame?: (bgrBuffer: Buffer) => EncodedBmp;
+  concatFilePath?: string;
+}> {
+  const {
+    useVideoBackground,
+    backgroundVideoPath,
+    backgroundImagePath,
+    beatFrameIndices,
+    framesCount,
+    outputResolution,
+    fps,
+    autoEditVideo,
+  } = params;
+
+  if (useVideoBackground && backgroundVideoPath) {
+    const videoInfo = await getVideoInfo(backgroundVideoPath);
+    const sceneChanges = autoEditVideo
+      ? await detectSceneChanges(backgroundVideoPath)
+      : [];
+    const backgroundWidth = outputResolution?.width ?? videoInfo.width;
+    const backgroundHeight = outputResolution?.height ?? videoInfo.height;
+
+    const videoFrameSize = backgroundWidth * backgroundHeight * 3;
+    const encodeVideoFrame = createBgrFrameEncoder({ width: backgroundWidth, height: backgroundHeight });
+
+    const segments = buildBeatSyncedSegments(
+      beatFrameIndices,
+      framesCount,
+      sceneChanges,
+      videoInfo.duration,
+    );
+
+    const concatFilePath = writeConcatFile(segments, backgroundVideoPath, videoInfo.duration, fps);
+
+    const videoFrameReader = spawnConcatVideoFrameReader({
+      concatFilePath,
+      fps,
+      totalFrames: framesCount,
+      ...(outputResolution && {
+        width: backgroundWidth,
+        height: backgroundHeight,
+        sourceWidth: videoInfo.width,
+        sourceHeight: videoInfo.height,
+      }),
+    });
+
+    const firstFrame = await readVideoFrame(videoFrameReader.stdout, videoFrameSize);
+    if (!firstFrame) {
+      throw new Error(`Could not read frames from video: ${backgroundVideoPath}`);
+    }
+    const defaultColor = getVideoFrameColor(firstFrame, backgroundWidth, backgroundHeight);
+    const staticBackgroundBuffer = encodeVideoFrame(firstFrame);
+    return {
+      backgroundWidth,
+      backgroundHeight,
+      defaultColor,
+      staticBackgroundBuffer,
+      videoFrameReader,
+      videoFrameSize,
+      encodeVideoFrame,
+      concatFilePath,
+    };
+  }
+
+  if (!backgroundImagePath) {
+    throw new Error('Background image path is required when not using video background.');
+  }
+  const backgroundImageBmpBuffer = await convertToBmp(
+    backgroundImagePath,
+    outputResolution?.width,
+    outputResolution?.height,
+  );
+  const backgroundImage = parseImage(backgroundImageBmpBuffer);
+  const backgroundWidth = backgroundImage.width;
+  const backgroundHeight = backgroundImage.height;
+  const defaultColor = getImageColor(backgroundImage);
+
+  const bpmEncoder = createBpmEncoder({ width: backgroundWidth, height: backgroundHeight });
+  const staticBackgroundBuffer = bpmEncoder(backgroundImage.data);
+  return {
+    backgroundWidth,
+    backgroundHeight,
+    defaultColor,
+    staticBackgroundBuffer,
+    videoFrameSize: 0,
+  };
+}
+
+async function resolveBackgroundFrameBuffer(params: {
+  frameIndex: number;
+  useVideoBackground: boolean;
+  videoFrameReader?: ReturnType<typeof spawnVideoFrameReader>;
+  videoFrameSize: number;
+  encodeVideoFrame?: (bgrBuffer: Buffer) => EncodedBmp;
+  staticBackgroundBuffer: EncodedBmp;
+}): Promise<EncodedBmp> {
+  const {
+    frameIndex,
+    useVideoBackground,
+    videoFrameReader,
+    videoFrameSize,
+    encodeVideoFrame,
+    staticBackgroundBuffer,
+  } = params;
+
+  if (useVideoBackground && videoFrameReader && encodeVideoFrame) {
+    if (frameIndex === 0) {
+      return staticBackgroundBuffer;
+    }
+    const videoFrame = await readVideoFrame(videoFrameReader.stdout, videoFrameSize);
+    return videoFrame
+      ? encodeVideoFrame(videoFrame)
+      : staticBackgroundBuffer;
+  }
+  return staticBackgroundBuffer;
+}
+
 export const renderAudioVisualizer = (config: Config, onProgress?: (progress: number) => any, shouldStop?: () => boolean) =>
   new Promise<number>(async (resolve) => {
-    // Validate that only one visualizer type is specified
     if (config.outVideo.spectrum && config.outVideo.polar) {
       throw new Error('Cannot use both "spectrum" and "polar" options. Please specify only one visualizer type.');
     }
+    if (!config.image && !config.video) {
+      throw new Error('Either "image" or "video" must be specified as the background source.');
+    }
+    if (config.image && config.video) {
+      throw new Error('Cannot use both "image" and "video" options. Please specify only one background source.');
+    }
 
     const audioFilePath = getAudioFilePath(config);
-    const backgroundImagePath = getBackgroundImagePath(config);
     const outVideoPath = getOutVideoPath(config);
+    const backgroundVideoPath = getBackgroundVideoPath(config);
+    const backgroundImagePath = getBackgroundImagePath(config);
+    const useVideoBackground = !!backgroundVideoPath;
 
-    const backgroundImageBmpBuffer = await convertToBmp(backgroundImagePath);
-    const backgroundImage = parseImage(backgroundImageBmpBuffer);
     const audioReader = await createAudioBuffer(audioFilePath, FFMPEG_FORMAT);
     const audioBuffer = audioReader.audioBuffer;
     const sampleRate = audioReader.sampleRate;
@@ -173,12 +363,35 @@ export const renderAudioVisualizer = (config: Config, onProgress?: (progress: nu
     const ffmpeg_preset = getFfmpeg_preset(config);
     const frame_processing_delay = getFrame_processing_delay(config);
 
-    const createVisualizerFrame = createVisualizerFrameGenerator(config, backgroundImage, spectrumBusMargin);
-
     const audioDuration = audioBuffer.length / sampleRate;
     const framesCount = Math.trunc(audioDuration * FPS);
-    const audioDataStep = Math.trunc(audioBuffer.length / framesCount);
-    const processingBuffer = new Float32Array(PROCESSING_BUFFER_SIZE).fill(0);
+    const outputResolution = getOutputResolution(config);
+
+    const preprocessed = preProcessAudio(audioBuffer, sampleRate, FPS, framesCount);
+
+    const {
+      backgroundWidth,
+      backgroundHeight,
+      defaultColor,
+      staticBackgroundBuffer,
+      videoFrameReader,
+      videoFrameSize,
+      encodeVideoFrame,
+      concatFilePath,
+    } = await prepareBackgroundForRender({
+      useVideoBackground,
+      backgroundVideoPath,
+      backgroundImagePath,
+      beatFrameIndices: preprocessed.beatFrameIndices,
+      framesCount,
+      outputResolution,
+      fps: FPS,
+      autoEditVideo: getAutoEditVideo(config),
+    });
+
+    const createVisualizerFrame = createVisualizerFrameGenerator(
+      config, backgroundWidth, backgroundHeight, defaultColor, spectrumBusMargin
+    );
 
     const ffmpegVideoWriter = spawnFfmpegVideoWriter({
       audioFilename: audioFilePath,
@@ -190,18 +403,18 @@ export const renderAudioVisualizer = (config: Config, onProgress?: (progress: nu
     });
     ffmpegVideoWriter.on('exit', (code: number) => resolve(code));
 
-    const bpmEncoder = createBpmEncoder({ width: backgroundImage.width, height: backgroundImage.height });
-    const backgroundImageBuffer = bpmEncoder(backgroundImage.data);
-    const skipFramesCount = FPS < 45 ? 1 : 2;
-    const processSpectrum = createSpectrumsProcessor(sampleRate, skipFramesCount);
-
     for (let i = 0; i < framesCount; i++) {
-      const currentFrameData = PCM_FORMAT.parseFunction(audioBuffer, i * audioDataStep, i * audioDataStep + audioDataStep);
-      processingBuffer.copyWithin(0, currentFrameData.length);
-      processingBuffer.set(currentFrameData, PROCESSING_BUFFER_SIZE - currentFrameData.length);
+      const spectrum = preprocessed.spectrums[i];
+
+      const backgroundImageBuffer = await resolveBackgroundFrameBuffer({
+        frameIndex: i,
+        useVideoBackground,
+        videoFrameReader,
+        videoFrameSize,
+        encodeVideoFrame,
+        staticBackgroundBuffer,
+      });
 
-      const audioDataParser = () => Array.from(processingBuffer);
-      const spectrum = processSpectrum(audioDataParser);
       const commonVisualizerFrameProps: CommonVisualizerFrameProps = {
         backgroundImageBuffer,
         spectrum,
@@ -219,5 +432,11 @@ export const renderAudioVisualizer = (config: Config, onProgress?: (progress: nu
       }
     }
 
+    if (videoFrameReader) {
+      videoFrameReader.kill();
+    }
+    if (concatFilePath) {
+      cleanupConcatFile(concatFilePath);
+    }
     ffmpegVideoWriter.stdin.end();
   });

package/src/video.ts

@@ -1,5 +1,8 @@
-import { Writable } from 'stream';
+import { Readable, Writable } from 'stream';
 import { spawn } from 'child_process';
+import { writeFileSync, unlinkSync } from 'fs';
+import { resolve as resolvePath, join as joinPath } from 'path';
+import { tmpdir } from 'os';
 import ffmpegPath from 'ffmpeg-static';
 
 interface FfmpegVideoWriterConfig {
@@ -34,6 +37,170 @@ export const spawnFfmpegVideoWriter = (config: FfmpegVideoWriterConfig) => {
   return ffmpeg;
 };
 
+export interface VideoInfo {
+  width: number;
+  height: number;
+  duration: number;
+}
+
+export interface SceneChange {
+  frameNumber: number;
+  pts: number;
+  ptsTime: number;
+}
+
+export const detectSceneChanges = (videoPath: string, threshold = 0.4): Promise<SceneChange[]> =>
+  new Promise((resolve, reject) => {
+    if (!ffmpegPath) {
+      reject(new Error('ffmpeg path not found'));
+      return;
+    }
+    const ffmpeg = spawn(ffmpegPath, [
+      '-i', videoPath,
+      '-filter:v', `select='gt(scene,${threshold})',showinfo`,
+      '-f', 'null',
+      '-'
+    ]);
+    let stderr = '';
+    ffmpeg.stderr.on('data', (data: Buffer) => { stderr += data.toString(); });
+    ffmpeg.on('close', () => {
+      const sceneChanges: SceneChange[] = [];
+      for (const line of stderr.split('\n')) {
+        if (!line.includes('Parsed_showinfo')) continue;
+        const nMatch = line.match(/n:\s*(\d+)/);
+        const ptsMatch = line.match(/pts:\s*(\d+)/);
+        const ptsTimeMatch = line.match(/pts_time:\s*([\d.]+)/);
+        if (nMatch && ptsTimeMatch) {
+          sceneChanges.push({
+            frameNumber: parseInt(nMatch[1]),
+            pts: ptsMatch ? parseInt(ptsMatch[1]) : 0,
+            ptsTime: parseFloat(ptsTimeMatch[1]),
+          });
+        }
+      }
+      resolve(sceneChanges);
+    });
+    ffmpeg.on('error', reject);
+  });
+
+export const getVideoInfo = (videoPath: string): Promise<VideoInfo> =>
+  new Promise((resolvePromise, reject) => {
+    if (!ffmpegPath) {
+      reject(new Error('ffmpeg path not found'));
+      return;
+    }
+    const ffmpeg = spawn(ffmpegPath, ['-i', videoPath, '-hide_banner']);
+    let stderr = '';
+    ffmpeg.stderr.on('data', (data: Buffer) => { stderr += data.toString(); });
+    ffmpeg.on('close', () => {
+      const dimMatch = stderr.match(/Stream.*Video:.*?(\d{2,5})x(\d{2,5})/);
+      if (!dimMatch) {
+        reject(new Error(`Could not determine video dimensions for: ${videoPath}`));
+        return;
+      }
+      const durMatch = stderr.match(/Duration:\s*(\d+):(\d+):([\d.]+)/);
+      const duration = durMatch
+        ? parseInt(durMatch[1]) * 3600 + parseInt(durMatch[2]) * 60 + parseFloat(durMatch[3])
+        : 0;
+      resolvePromise({
+        width: parseInt(dimMatch[1]),
+        height: parseInt(dimMatch[2]),
+        duration,
+      });
+    });
+  });
+
+const isOrientationMismatch = (sw: number, sh: number, tw: number, th: number): boolean =>
+  (sw > sh && tw < th) || (sw < sh && tw > th);
+
+export const buildVideoFilter = (
+  sourceWidth: number,
+  sourceHeight: number,
+  targetWidth: number,
+  targetHeight: number,
+): string => {
+  if (!isOrientationMismatch(sourceWidth, sourceHeight, targetWidth, targetHeight)) {
+    return `scale=${targetWidth}:${targetHeight}`;
+  }
+
+  const targetAspect = targetWidth / targetHeight;
+  const makeEven = (n: number) => Math.floor(n / 2) * 2;
+  let cropW: number, cropH: number, cropX: number, cropY: number;
+
+  if (sourceWidth / sourceHeight > targetAspect) {
+    cropW = makeEven(Math.round(sourceHeight * targetAspect));
+    cropH = makeEven(sourceHeight);
+    cropX = Math.floor((sourceWidth - cropW) / 2);
+    cropY = Math.floor((sourceHeight - cropH) / 2);
+  } else {
+    cropW = makeEven(sourceWidth);
+    cropH = makeEven(Math.round(sourceWidth / targetAspect));
+    cropX = Math.floor((sourceWidth - cropW) / 2);
+    cropY = Math.floor((sourceHeight - cropH) / 2);
+  }
+
+  return `crop=${cropW}:${cropH}:${cropX}:${cropY},scale=${targetWidth}:${targetHeight}`;
+};
+
+export const spawnVideoFrameReader = (config: {
+  videoPath: string;
+  fps: number;
+  totalFrames: number;
+  width?: number;
+  height?: number;
+  sourceWidth?: number;
+  sourceHeight?: number;
+}) => {
+  if (!ffmpegPath) {
+    throw new Error('ffmpeg path not found');
+  }
+  const args = [
+    '-stream_loop', '-1',
+    '-i', config.videoPath,
+    '-r', `${config.fps}`,
+    '-frames:v', `${config.totalFrames}`,
+  ];
+  if (config.width && config.height) {
+    const filter = config.sourceWidth && config.sourceHeight
+      ? buildVideoFilter(config.sourceWidth, config.sourceHeight, config.width, config.height)
+      : `scale=${config.width}:${config.height}`;
+    args.push('-vf', filter);
+  }
+  args.push(
+    '-f', 'rawvideo',
+    '-pix_fmt', 'bgr24',
+    '-v', 'quiet',
+    'pipe:1'
+  );
+  return spawn(ffmpegPath, args);
+};
+
+export const readVideoFrame = (stream: Readable, frameSize: number): Promise<Buffer | null> =>
+  new Promise((resolve) => {
+    const tryRead = () => {
+      const data = stream.read(frameSize) as Buffer | null;
+      if (data !== null) {
+        resolve(data.length === frameSize ? data : null);
+        return;
+      }
+      const onReadable = () => {
+        cleanup();
+        tryRead();
+      };
+      const onEnd = () => {
+        cleanup();
+        resolve(null);
+      };
+      const cleanup = () => {
+        stream.removeListener('readable', onReadable);
+        stream.removeListener('end', onEnd);
+      };
+      stream.once('readable', onReadable);
+      stream.once('end', onEnd);
+    };
+    tryRead();
+  });
+
 export const getProgress = (onProgress: (currentFrame: number) => any) =>
   (stderrOutput: Buffer) => {
     const matchResult = stderrOutput.toString().match(/frame=[ ]+(\d+)/);
@@ -55,3 +222,137 @@ export const calculateProgress = (framesCount: number, callback: (progress: numb
 
 export const waitDrain = (stream: Writable) =>
   new Promise<void>(resolve => stream.once('drain', resolve));
+
+export interface VideoSegment {
+  outputStartFrame: number;
+  videoSeekSeconds: number;
+  frameCount: number;
+}
+
+const mergeSmallScenes = (sceneChanges: SceneChange[], videoDuration: number, minDuration = 2): SceneChange[] => {
+  if (sceneChanges.length === 0) return [];
+  const merged: SceneChange[] = [sceneChanges[0]];
+  for (let i = 1; i < sceneChanges.length; i++) {
+    const lastKept = merged[merged.length - 1];
+    const gap = sceneChanges[i].ptsTime - lastKept.ptsTime;
+    if (gap >= minDuration) {
+      merged.push(sceneChanges[i]);
+    }
+  }
+  const lastScene = merged[merged.length - 1];
+  if (videoDuration - lastScene.ptsTime < minDuration && merged.length > 1) {
+    merged.pop();
+  }
+  return merged;
+};
+
+export const buildBeatSyncedSegments = (
+  beatFrameIndices: number[],
+  totalFrames: number,
+  sceneChanges: SceneChange[],
+  videoDuration: number,
+): VideoSegment[] => {
+  if (sceneChanges.length === 0) {
+    return [
+      {
+        outputStartFrame: 0,
+        videoSeekSeconds: 0,
+        frameCount: totalFrames,
+      },
+    ];
+  }
+
+  const consolidated = mergeSmallScenes(sceneChanges, videoDuration);
+  let seekPositions: number[];
+  if (consolidated.length >= 2) {
+    seekPositions = consolidated.map(sc => sc.ptsTime);
+  } else {
+    const count = Math.max(10, Math.ceil(videoDuration / 3));
+    seekPositions = Array.from({ length: count }, (_, i) => (i * videoDuration) / count);
+  }
+
+  const boundaries = [0, ...beatFrameIndices];
+  if (boundaries[boundaries.length - 1] !== totalFrames) {
+    boundaries.push(totalFrames);
+  }
+  const unique = Array.from(new Set(boundaries)).sort((a, b) => a - b);
+
+  const segments: VideoSegment[] = [];
+  for (let i = 0; i < unique.length - 1; i++) {
+    segments.push({
+      outputStartFrame: unique[i],
+      videoSeekSeconds: seekPositions[i % seekPositions.length],
+      frameCount: unique[i + 1] - unique[i],
+    });
+  }
+  return segments;
+};
+
+export const writeConcatFile = (
+  segments: VideoSegment[],
+  videoPath: string,
+  videoDuration: number,
+  fps: number,
+): string => {
+  const absVideoPath = resolvePath(videoPath).replace(/\\/g, '/');
+  const escaped = absVideoPath.replace(/'/g, "'\\''");
+  let content = '';
+
+  for (const seg of segments) {
+    const segDuration = seg.frameCount / fps;
+    let remaining = segDuration;
+    let pos = seg.videoSeekSeconds % videoDuration;
+
+    while (remaining > 0.001) {
+      const available = videoDuration - pos;
+      const take = Math.min(remaining, available);
+      content += `file '${escaped}'\n`;
+      content += `inpoint ${pos.toFixed(6)}\n`;
+      content += `outpoint ${(pos + take).toFixed(6)}\n\n`;
+      remaining -= take;
+      pos = 0;
+    }
+  }
+
+  const concatPath = joinPath(tmpdir(), `av-concat-${Date.now()}.txt`);
+  writeFileSync(concatPath, content, 'utf-8');
+  return concatPath;
+};
+
+export const spawnConcatVideoFrameReader = (config: {
+  concatFilePath: string;
+  fps: number;
+  totalFrames: number;
+  width?: number;
+  height?: number;
+  sourceWidth?: number;
+  sourceHeight?: number;
+}) => {
+  if (!ffmpegPath) {
+    throw new Error('ffmpeg path not found');
+  }
+  const args = [
+    '-f', 'concat',
+    '-safe', '0',
+    '-i', config.concatFilePath,
+    '-r', `${config.fps}`,
+    '-frames:v', `${config.totalFrames}`,
+  ];
+  if (config.width && config.height) {
+    const filter = config.sourceWidth && config.sourceHeight
+      ? buildVideoFilter(config.sourceWidth, config.sourceHeight, config.width, config.height)
+      : `scale=${config.width}:${config.height}`;
+    args.push('-vf', filter);
+  }
+  args.push(
+    '-f', 'rawvideo',
+    '-pix_fmt', 'bgr24',
+    '-v', 'quiet',
+    'pipe:1'
+  );
+  return spawn(ffmpegPath, args);
+};
+
+export const cleanupConcatFile = (filePath: string) => {
+  try { unlinkSync(filePath); } catch {}
+};