FFmpeg 서버사이드 영상 합성

ffmpeg -i input.mp4 -vf "scale=1280:720" output.mp4

npm install fluent-ffmpeg
npm install -D @types/fluent-ffmpeg  # TypeScript 타입
npm install -D ffmpeg-static         # 시스템에 FFmpeg 없을 때

import Ffmpeg from 'fluent-ffmpeg';

// 단순 변환
Ffmpeg('input.mp4')
  .outputOptions(['-c:v libx264', '-crf 23'])
  .output('output.mp4')
  .on('end', () => console.log('완료'))
  .on('error', (err) => console.error(err))
  .run();

// 1. 환경 변수로 지정
if (process.env.FFMPEG_PATH) {
  Ffmpeg.setFfmpegPath(process.env.FFMPEG_PATH);
}

// 2. ffmpeg-static 패키지 사용 (개발 환경)
const ffmpegStatic = require('ffmpeg-static');
Ffmpeg.setFfmpegPath(ffmpegStatic);

// 3. 시스템 PATH에 있으면 별도 설정 불필요

interface VideoInfo {
  duration: number;  // 초
  width: number;
  height: number;
  fps: number;
  codec: string;
  bitrate?: number;
}

async function getVideoInfo(filePath: string): Promise<VideoInfo> {
  return new Promise((resolve, reject) => {
    Ffmpeg.ffprobe(filePath, (err, metadata) => {
      if (err) {
        reject(new Error(`Failed to probe video: ${err.message}`));
        return;
      }

      const videoStream = metadata.streams.find(
        (s) => s.codec_type === 'video'
      );
      if (!videoStream) {
        reject(new Error('No video stream found'));
        return;
      }

      // 프레임 레이트 파싱: "30/1" 형태로 올 수 있음
      let fps = 30;
      if (videoStream.r_frame_rate) {
        const [num, den] = videoStream.r_frame_rate.split('/').map(Number);
        fps = den ? num / den : num;
      }

      resolve({
        duration: metadata.format.duration || 0,
        width: videoStream.width || 0,
        height: videoStream.height || 0,
        fps: Math.round(fps),
        codec: videoStream.codec_name || 'unknown',
        bitrate: metadata.format.bit_rate
          ? parseInt(String(metadata.format.bit_rate), 10)
          : undefined,
      });
    });
  });
}

input0 ──→ [scale] ──→ [overlay] ──→ output
input1 ──→ [scale] ──┘
background ──────────┘

[영상0] [영상1]     프레임 이미지
[영상2] [영상3]  +  (투명 PNG)  = 최종 결과

[0:v]scale=320:240,hflip[p0];        # 입력0: 크기 조절 + 좌우 반전
[1:v]scale=320:240,hflip[p1];        # 입력1
[2:v]scale=320:240,hflip[p2];        # 입력2
[3:v]scale=320:240,hflip[p3];        # 입력3
[4:v]scale=640:480[frame];           # 프레임 이미지
color=black:640x480:d=1:r=30,format=yuv420p[bg];  # 검정 배경
[bg][p0]overlay=0:0[v0];             # 배경에 영상0 배치
[v0][p1]overlay=320:0[v1];           # 영상1 배치
[v1][p2]overlay=0:240[v2];           # 영상2 배치
[v2][p3]overlay=320:240[v_final];    # 영상3 배치
[v_final][frame]overlay=0:0[out]     # 프레임 오버레이

[0:v]scale=320:240,hflip[p0]

color=black:640x480:d=1:r=30,format=yuv420p[bg]

[bg][p0]overlay=0:0[v0];
[v0][p1]overlay=320:0[v1];

[v_final][frame]overlay=0:0[out]

interface CompositionInput {
  videoPath: string;
  x: number;        // overlay x 좌표
  y: number;        // overlay y 좌표
  width: number;    // 스케일 후 너비
  height: number;   // 스케일 후 높이
  flipHorizontal?: boolean;
}

interface CompositionOptions {
  outputWidth: number;
  outputHeight: number;
  fps: number;
  backgroundColor: string;
  framePath?: string;
}

function buildCompositionFilter(
  inputs: CompositionInput[],
  options: CompositionOptions,
  hasFrame: boolean,
): { filters: string[]; outputLabel: string } {
  const { outputWidth, outputHeight, fps } = options;
  const filters: string[] = [];

  // 1. 각 비디오 스케일 + 반전
  inputs.forEach((input, i) => {
    const flip = input.flipHorizontal ? ',hflip' : '';
    filters.push(
      `[${i}:v]scale=${input.width}:${input.height}${flip}[p${i}]`
    );
  });

  // 2. 프레임 이미지 스케일
  if (hasFrame) {
    const frameIndex = inputs.length;
    filters.push(
      `[${frameIndex}:v]scale=${outputWidth}:${outputHeight}[frame]`
    );
  }

  // 3. 배경 생성
  filters.push(
    `color=black:${outputWidth}x${outputHeight}:d=1:r=${fps},format=yuv420p[bg]`
  );

  // 4. 순차 오버레이
  let prev = '[bg]';
  inputs.forEach((input, i) => {
    const isLast = i === inputs.length - 1;
    const nextLabel = isLast
      ? (hasFrame ? '[v_final]' : '[out]')
      : `[v${i}]`;
    filters.push(
      `${prev}[p${i}]overlay=${input.x}:${input.y}${nextLabel}`
    );
    prev = `[v${i}]`;
  });

  // 5. 프레임 오버레이
  if (hasFrame) {
    filters.push(`[v_final][frame]overlay=0:0[out]`);
  }

  return { filters, outputLabel: 'out' };
}

async function composeVideos(
  inputs: CompositionInput[],
  options: CompositionOptions,
  outputPath: string,
): Promise<void> {
  return new Promise((resolve, reject) => {
    const command = Ffmpeg();

    // 모든 비디오 입력 추가
    inputs.forEach((input) => {
      command.input(input.videoPath);
    });

    // 프레임 이미지 입력 추가
    if (options.framePath) {
      command.input(options.framePath);
    }

    // filter_complex 빌드
    const filter = buildCompositionFilter(
      inputs, options, !!options.framePath
    );

    command
      .complexFilter(filter.filters, filter.outputLabel)
      .outputOptions([
        '-c:v libx264',       // H.264 코덱
        '-preset medium',     // 인코딩 속도/품질 균형
        '-crf 23',            // 품질 (낮을수록 고품질)
        '-pix_fmt yuv420p',   // 브라우저 호환 포맷
        `-r ${options.fps}`,  // 출력 FPS
        '-movflags +faststart', // 웹 스트리밍 최적화
        '-an',                // 오디오 제거
      ])
      .output(outputPath)
      .on('start', (cmd) => {
        console.log(`FFmpeg command: ${cmd}`);
      })
      .on('progress', (progress) => {
        if (progress.percent) {
          console.log(`Processing: ${progress.percent.toFixed(1)}%`);
        }
      })
      .on('error', (err) => {
        reject(new Error(`Video composition failed: ${err.message}`));
      })
      .on('end', () => resolve())
      .run();
  });
}

import { promises as fs } from 'fs';
import * as path from 'path';
import { randomUUID } from 'crypto';

class TempFileUtil {
  private readonly tempDir: string;
  private readonly createdFiles = new Set<string>();
  private readonly createdDirs = new Set<string>();

  constructor(tempDir: string) {
    this.tempDir = tempDir;
  }

  async ensureDir(): Promise<void> {
    await fs.mkdir(this.tempDir, { recursive: true });
  }

  // 세션별 독립된 디렉토리
  async createSessionDir(sessionId: string): Promise<string> {
    const dir = path.join(this.tempDir, sessionId);
    await fs.mkdir(dir, { recursive: true });
    this.createdDirs.add(dir);
    return dir;
  }

  // 유니크한 임시 파일 경로 생성
  getTempFilePath(ext: string, prefix = 'temp'): string {
    const filename = `${prefix}-${randomUUID()}${ext}`;
    const filePath = path.join(this.tempDir, filename);
    this.createdFiles.add(filePath);
    return filePath;
  }

  // 추적된 모든 파일/디렉토리 정리
  async cleanup(): Promise<void> {
    for (const file of this.createdFiles) {
      try { await fs.unlink(file); } catch { /* 이미 삭제됨 */ }
    }
    for (const dir of this.createdDirs) {
      try { await fs.rm(dir, { recursive: true }); } catch { /* 무시 */ }
    }
    this.createdFiles.clear();
    this.createdDirs.clear();
  }
}

const tempUtil = new TempFileUtil('/tmp/video-processing');
try {
  await tempUtil.ensureDir();
  const outputPath = tempUtil.getTempFilePath('.mp4', 'composed');
  await composeVideos(inputs, options, outputPath);
  // outputPath를 S3에 업로드 등
} finally {
  await tempUtil.cleanup();
}

const TIMEOUT_MS = 600_000; // 10분

const command = Ffmpeg();
// ... 입력, 필터 설정 ...

const timer = setTimeout(() => {
  command.kill('SIGKILL');
  reject(new Error('Video composition timeout'));
}, TIMEOUT_MS);

command
  .on('end', () => {
    clearTimeout(timer);
    resolve();
  })
  .on('error', (err) => {
    clearTimeout(timer);
    reject(err);
  })
  .run();

command
  .on('start', (commandLine) => {
    // 실행될 FFmpeg 명령어 전체를 볼 수 있음
    // 디버깅에 매우 유용
    logger.debug(`FFmpeg: ${commandLine}`);
  })
  .on('progress', (progress) => {
    // progress.percent: 0~100
    // progress.currentFps: 현재 처리 FPS
    // progress.timemark: 처리된 시간 위치
    logger.debug(`${progress.percent?.toFixed(1)}%`);
  })
  .on('stderr', (line) => {
    // FFmpeg의 stderr 출력 (상세 로그)
  })
  .on('error', (err, stdout, stderr) => {
    // stderr에 에러 원인이 담겨 있는 경우가 많음
    logger.error(`FFmpeg error: ${err.message}`);
    logger.error(`stderr: ${stderr}`);
  })
  .on('end', () => {
    logger.log('Complete');
  });

// ffmpeg.config.ts
import { registerAs } from '@nestjs/config';

export default registerAs('ffmpeg', () => ({
  ffmpegPath: process.env.FFMPEG_PATH,
  ffprobePath: process.env.FFPROBE_PATH,
  tempDir: process.env.FFMPEG_TEMP_DIR || '/tmp/video-processing',
  timeout: parseInt(process.env.FFMPEG_TIMEOUT || '600000', 10),
}));

// ffmpeg.module.ts
@Module({
  imports: [ConfigModule.forFeature(ffmpegConfig)],
  providers: [FFmpegService],
  exports: [FFmpegService],
})
export class FFmpegModule {}

input0 → [scale,hflip] → [p0] ─────────────────┐
input1 → [scale,hflip] → [p1] ──────────────┐   │
input2 → [scale,hflip] → [p2] ───────────┐  │   │
input3 → [scale,hflip] → [p3] ────────┐  │  │   │
frame  → [scale]        → [frame] ──┐  │  │  │   │
                                     │  │  │  │   │
color=black → [bg] ──────────────────┼──┼──┼──┼───┤
                                     │  │  │  │   │
overlay(bg+p0) → [v0] ──────────────┼──┼──┼──┘   │
overlay(v0+p1) → [v1] ──────────────┼──┼──┘      │
overlay(v1+p2) → [v2] ──────────────┼──┘         │
overlay(v2+p3) → [v_final] ─────────┤            │
overlay(v_final+frame) → [out] ─────┘            │