@node-media-library/video

Video-backed ImageGenerator using ffmpeg to extract frames at specified timestamps, then applying conversions through the sharp pipeline.

Installation

pnpm add @node-media-library/video sharp

sharp is a required optional peer. This package rasterizes into core's sharpImageGenerator(), so sharp must be installed even though it is declared optional. It is marked optional only because core declares it that way.

System Requirements

Requires the ffmpeg binary:

• macOS: brew install ffmpeg
• Linux (Debian/Ubuntu): apt install ffmpeg
• Linux (Fedora/RHEL): dnf install ffmpeg
• Windows: Download from ffmpeg.org or choco install ffmpeg

Usage

Append the video generator to your imageGenerators array alongside sharpImageGenerator:

import { createMediaLibrary, sharpImageGenerator } from '@node-media-library/core'
import { videoImageGenerator } from '@node-media-library/video'

createMediaLibrary({
  // ...
  imageGenerators: [sharpImageGenerator(), videoImageGenerator()],
})

Configuration

videoImageGenerator(options?)

Options

• ffmpegPath (string): Path to the ffmpeg binary. Default: 'ffmpeg' (assumes it's on PATH)

Example

videoImageGenerator({
  ffmpegPath: '/usr/local/bin/ffmpeg',
})

Selecting Frames

Use conversion().videoFrameAtSecond(n) to select which frame to extract (default is frame at 0 seconds):

import { collection, conversion } from '@node-media-library/core'

collection().conversions({
  // Extract the frame at 2.5 seconds, at 800px wide
  poster: conversion().videoFrameAtSecond(2.5).width(800),
})

conversions() takes the builders themselves — don't call .toDefinition(), which is applied for you.

Testing

Tests include binary-gated suites that skip when ffmpeg is not available. Pure tests (those not requiring the binary) always run:

pnpm --filter @node-media-library/video test

• ✓ Pure tests (MIME type support) run without ffmpeg
• ⊘ Binary-gated tests skip if ffmpeg not found
• Install ffmpeg to run all tests