damianociarla/node-ffmpeg

소개

node-ffmpeg은 코드에서 명령줄 도구인 ffmpeg와 ffprobe를 제어할 수 있게 해주는 JavaScript/TypeScript 라이브러리입니다. 셸 명령을 직접 입력하는 대신 setVideoCodec('libx264') 또는 save('/output.mp4')와 같은 메서드를 호출합니다. 널리 사용되는 기존 ffmpeg 패키지의 API를 래핑하면서도 네이티브 Promise, TypeScript 타입 지원, ESM 및 CommonJS 호환성 등 현대적인 기능을 추가했습니다.

요구 사항

Node.js 24 이상.
ffmpeg와 ffprobe가 시스템에 설치되어 있고 PATH에 있어야 합니다. 또는 정확한 경로를 제공해야 합니다.
이 라이브러리는 의도적으로 자체 FFmpeg 바이너리를 다운로드하지 않습니다. 이는 패키지 크기를 작게 유지하고 필요한 FFmpeg 빌드와 코덱을 직접 선택할 수 있게 합니다.

설치

npm install ffmpeg

빠른 시작 (TypeScript)

import ffmpeg from 'ffmpeg';

const video = await ffmpeg('/media/input.mp4');

video.on('progress', ({ percent, time }) => {
  console.log(percent === undefined ? `${time}s` : `${percent.toFixed(1)}% (${time}s)`);
});

await video
  .setVideoCodec('libx264')
  .setVideoBitRate(2_000)
  .setAudioCodec('aac')
  .setAudioBitRate(192)
  .setVideoSize('1280x?', true, true, 'black')
  .save('/media/output.mp4');

메서드는 체인 가능하며, 연속해서 호출할 수 있습니다. 작업은 save()와 같은 터미널 메서드를 호출할 때 시작됩니다. 기존 패키지의 콜백 스타일 API도 지원하며, timeout 및 overwrite와 같은 옵션을 지원하는 명명된 팩토리 create()도 제공합니다.

많은 파일을 처리하는 서비스의 경우 createClient()를 사용하여 클라이언트를 한 번 생성하고 FFmpeg 설정을 재사용할 수 있습니다.

실행 파일 경로

ffmpeg와 ffprobe의 경로를 전역(레거시 앱용) 또는 작업별로 설정할 수 있습니다. 절대 경로인 ffmpegPath를 제공하고 ffprobePath를 제공하지 않으면, 라이브러리는 ffprobe가 해당 경로 옆에 있다고 가정합니다.

설정 (README의 표)

설정	기본값	의미
`encoding`	`utf8`	프로세스 출력 인코딩
`timeout`	`0`	최대 작업 시간(ms); `0` = 타임아웃 없음
`maxBuffer`	16 MiB	유지할 변환 출력량; 프로브 출력의 최대치이기도 함
`overwrite`	`false`	`-y`를 사용하여 덮어쓰기; 그렇지 않으면 `-n`으로 대화형 프롬프트 방지
`ffmpegPath`	`ffmpeg`	FFmpeg 실행 파일
`ffprobePath`	`ffprobe`	ffprobe 실행 파일
`signal`	—	작업을 취소하기 위한 `AbortSignal`
`cwd`, `env`	상속	자식 프로세스 작업 디렉토리 및 환경 변수

장시간 실행되는 변환은 출력의 마지막 maxBuffer 바이트만 유지합니다. 프로브 출력은 maxBuffer 내에 완전히 맞아야 하며, 그렇지 않으면 작업이 오류 119와 함께 실패합니다.

API 하이라이트

세터(모두 체인 가능): setDisableVideo, setVideoCodec, setVideoBitRate 등의 비디오 세터; setDisableAudio, setAudioCodec, setAudioBitRate 등의 오디오 세터; setMetadata, setThreads, setWatermark, addInput, addCommand, addOutputOption, addFilterComplex, getCommand(빌드된 명령 반환) 등의 일반 세터.
터미널 메서드: save, fnExtractSoundToMP3, fnExtractFrameToJPG, fnAddWatermark. 이 메서드들이 실제 프로세스를 시작합니다.
copy는 코덱 값으로 허용되며, "재인코딩 없이 스트림 복사"를 의미합니다.
사용자 지정 옵션 반복(예: 여러 -map 또는 -metadata 항목)이 허용됩니다.

터미널 메서드 내의 유효성 검사는 Promise 거부 또는 선택적 콜백을 통해 오류를 반환합니다. 세터 유효성 검사는 동기적으로 유지됩니다. 동일한 비디오 객체에 대한 동시 작업은 격리된 옵션 스냅샷을 사용합니다.

메타데이터 및 이벤트

video.metadata는 원래 형태(duration, video, audio, 태그)를 유지하며 video.metadata.raw에서 전체 ffprobe 응답을 노출합니다.
수명 주기 이벤트를 수신할 수 있습니다: 'start', 'progress'(백분율/시간 포함), 'stderr', 'end', 'error'.
'error' 리스너는 선택 사항입니다. 실패한 Promise는 리스너 없이도 정상적으로 거부됩니다.

프레임 추출

const files = await video.fnExtractFrameToJPG('/media/frames', {
  start_time: '00:00:10',
  every_n_seconds: 5,
  number: 10,
  size: '640x?',
  quality: 2,
  file_name: 'preview_%s',
});

every_n_frames, every_n_seconds, every_n_percentage 중 하나만 설정할 수 있습니다. 반환된 경로에는 추출 패턴과 일치하는 파일만 포함됩니다.

사용자 지정 FFmpeg 옵션

addCommand를 사용하여 원시 인수를 전달합니다. 이 인수는 셸 해석 없이 spawn으로 직접 전달되므로 셸 따옴표를 추가하지 마십시오. 이 메서드들은 신뢰할 수 있는 탈출구이므로 검증되지 않은 사용자 입력을 절대 전달하지 마십시오. -로 시작하는 출력 대상은 거부됩니다. 대신 ./-name.ext를 사용하십시오.

0.0.4 버전에서의 마이그레이션

Node.js 24+ 및 ffprobe가 필수입니다.
네이티브 Promise가 이전 when 라이브러리를 대체했습니다. await는 이전과 동일하게 작동합니다.
오류는 이제 과거의 숫자 code 및 msg 필드를 가진 FfmpegError 인스턴스입니다.
워터마크 나침반 위치는 이제 일반적인 의미를 따릅니다(NE = 오른쪽 상단, 이전 반전 문제 수정).
비트레이트는 -b:v / -b:a를 사용하며, 숫자 값은 kbit/s로 처리됩니다.
기존 출력은 -n으로 보호됩니다. 덮어쓰려면 overwrite: true를 설정하여 -y를 사용하십시오.
패키지에 TypeScript 선언이 포함되어 있으므로 @types/ffmpeg는 필요하지 않습니다.

보안

FFmpeg는 신뢰할 수 없고 복잡한 미디어를 처리합니다. 시스템 FFmpeg에 패치를 적용하고, 리소스 제한을 적용하며, 신뢰할 수 없는 입력을 수락하기 전에 SECURITY.md를 읽으십시오.