ffmpeg-static

FFmpeg operations via the ffmpeg-static npm package (bundled binary) with automatic fallback to a native system FFmpeg installation. Use for: video/audio tra...

Security Scan

The skill's files, requirements, and instructions match its stated purpose (providing a Node-friendly FFmpeg binary and usage patterns); nothing requested is disproportionate or unrelated to FFmpeg usage.

Purpose & Capability

Name/description, required binaries (node, npm), templates, and the resolve script all align with packaging and exposing ffmpeg-static to Node projects. Minor note: the SKILL.md language says it "wires ... into every assistant interaction," which suggests broad integration, but the skill metadata shows always:false (it is user-invocable). This is a wording mismatch rather than a functional inconsistency.

Instruction Scope

SKILL.md contains explicit instructions for resolving and invoking FFmpeg from Node and shell; it recommends spawning child_process and provides many FFmpeg command templates. These instructions stay on-topic for media processing. Two security-relevant points are called out by the skill itself: (1) npm install of ffmpeg-static causes pre-built binaries to be downloaded from GitHub Releases, and (2) FFmpeg can read from URLs/protocols so running it against untrusted inputs may reach network resources or other protocols. Those are expected for this capability but worth awareness.

Install Mechanism

There is no platform-specific installer in the manifest, but SKILL.md recommends npm install ffmpeg-static (and optionally ffprobe-static). Using npm is expected; ffmpeg-static performs post-install binary retrieval from GitHub Releases (pre-built FFmpeg). This is moderate-risk in general (network download of binaries) but is the standard distribution method for this package and not an unexpected arbitrary URL or custom server.

Credentials

The skill declares no secrets and only documents benign, proportional environment variables (FFMPEG_PATH, FFPROBE_PATH, FFMPEG_STATIC_SKIP_BINARY_DOWNLOAD). No unrelated credentials or config paths are requested.

Persistence & Privilege

always is false, and the skill does not request permanent/invisible presence or system-wide config modifications. disable-model-invocation is false (normal); the skill can be invoked by agents but that is expected for user-invocable skills.

Assessment

This skill is coherent for bundling and using an FFmpeg binary in Node projects. Before installing: (1) confirm you trust the npm package and its GitHub releases (ffmpeg-static downloads pre-built binaries during npm install); (2) if you operate in a locked environment, consider using system FFmpeg and set FFMPEG_STATIC_SKIP_BINARY_DOWNLOAD=1; (3) never run FFmpeg on untrusted filenames or URLs without validation—FFmpeg can read network resources and many protocols; (4) prefer system FFmpeg for hardware-accelerated encoders and to avoid unexpected binary downloads; (5) verify the package on npmjs/github and inspect hashes or CI reproducible builds if you need high assurance.

FFmpeg Static Skill

This skill wires ffmpeg-static — a self-contained FFmpeg binary distributed as an npm package — into every assistant interaction. When a native system FFmpeg is also installed, the skill prefers the system binary (usually newer and GPU-capable); otherwise it falls back to the bundled one. All FFmpeg capabilities are available in both paths.

No PATH manipulation needed. require('ffmpeg-static') returns the absolute path to the binary; scripts pass it directly to child_process.spawn.

---

Security Notice

• ffmpeg-static downloads pre-built binaries from GitHub Releases during npm install. Verify the package on npmjs.com/package/ffmpeg-static.
• Never pipe untrusted filenames or URLs into FFmpeg commands without validation — FFmpeg can read from URLs and arbitrary protocols.
• The bundled binary does not include GPU-accelerated encoders (nvenc, vaapi, videotoolbox). For hardware acceleration, use the system FFmpeg.

---

Installation

Minimum install (bundled FFmpeg binary only)

npm install ffmpeg-static

Project install with ffprobe (recommended)

npm install ffmpeg-static ffprobe-static

Verify the binary path

node -e "console.log(require('ffmpeg-static'))"
# e.g. /path/to/node_modules/ffmpeg-static/ffmpeg

Check resolved binary (bundled vs. system)

node scripts/resolve_ffmpeg.js

---

Binary Resolution Logic

The skill resolves the FFmpeg binary in this priority order:

1. FFMPEG_PATH env var — explicit override, always wins
2. System FFmpeg — found by walking PATH directories with fs.accessSync; preferred when present (newer codecs, hardware acceleration)
3. Bundled binary — require('ffmpeg-static') absolute path; guaranteed to exist after npm install

// Canonical resolution — use this pattern in all scripts
const { resolveFfmpeg } = require('./scripts/resolve_ffmpeg');
const ffmpegPath = resolveFfmpeg(); // throws if none found

---

Common Operations

Transcode video to H.264/AAC MP4

$(node -e "process.stdout.write(require('ffmpeg-static'))") \
  -i input.mkv -c:v libx264 -crf 23 -preset fast \
  -c:a aac -b:a 128k output.mp4

Extract thumbnail at timestamp

ffmpeg -ss 00:01:30 -i input.mp4 -frames:v 1 -q:v 2 thumb.jpg

Convert audio to MP3

ffmpeg -i input.flac -q:a 2 output.mp3

Extract audio stream only

ffmpeg -i input.mp4 -vn -c:a copy audio.aac

Trim without re-encoding

ffmpeg -ss 00:00:10 -to 00:01:00 -i input.mp4 -c copy trimmed.mp4

Concatenate files

ffmpeg -f concat -safe 0 -i filelist.txt -c copy output.mp4

filelist.txt format:

file '/abs/path/clip1.mp4'
file '/abs/path/clip2.mp4'

Scale video (maintain aspect ratio)

ffmpeg -i input.mp4 -vf "scale=1280:-2" -c:a copy scaled.mp4

Generate animated GIF

ffmpeg -i input.mp4 -vf "fps=10,scale=480:-1:flags=lanczos,split[s0][s1];[s0]palettegen[p];[s1][p]paletteuse" output.gif

HLS stream packaging

ffmpeg -i input.mp4 -codec: copy -start_number 0 \
  -hls_time 10 -hls_list_size 0 -f hls output.m3u8

---

Using From Node.js

Copy-paste patterns are in templates/node_patterns.txt. Key steps:

1. Resolve the binary using scripts/resolve_ffmpeg.js (pure fs, no shell calls)
2. Spawn FFmpeg in your own project code using Node's child_process.spawn
3. Or use fluent-ffmpeg — pass the resolved path via ffmpeg.setFfmpegPath()

// In YOUR project (not inside the skill)
const { resolveFfmpeg } = require('ffmpeg-static-skill/scripts/resolve_ffmpeg');
const ffmpegBin = resolveFfmpeg(); // absolute path, ready to pass to spawn or fluent-ffmpeg

See templates/node_patterns.txt for ready-to-copy spawn, progress, ffprobe, and fluent-ffmpeg snippets.

---

Environment Variables

Variable	Effect
FFMPEG_PATH	Override binary path; takes precedence over system and bundled
FFPROBE_PATH	Override ffprobe binary path
FFMPEG_STATIC_SKIP_BINARY_DOWNLOAD	Set to 1 to skip download during npm install (use with system FFmpeg)

---

Best Practices

1. Always resolve the binary once at startup

Call resolveFfmpeg() once and cache the result — don't call require('ffmpeg-static') inline in hot paths.

2. Prefer -c copy when no re-encoding is needed

Stream copy (-c copy) is instantaneous and lossless. Only decode/encode when you actually need to change the codec or apply filters.

3. Use -ss before -i for fast seeking

-ss 00:01:00 -i input.mp4 (before -i) uses keyframe seeking (fast). -i input.mp4 -ss 00:01:00 (after -i) decodes from the start (accurate but slow for large files).

4. Always pass -y in non-interactive scripts

-y overwrites output without prompting. Without it, FFmpeg hangs waiting for stdin in CI or background processes.

5. Validate inputs before building command arrays

Never interpolate user-supplied strings directly into FFmpeg args. Always validate paths exist and are the expected media type using ffprobe first.

6. For hardware encoding, require system FFmpeg

Check ffmpeg -hwaccels at startup and gate hardware-accelerated paths on the system binary being active.

7. Set -loglevel error in production

Reduces stderr noise. Re-enable verbose logging (-loglevel verbose) when debugging a failed transcode.

---

Supported Formats (Bundled Binary)

The bundled ffmpeg-static binary is compiled with a broad but fixed set of codecs. Key inclusions:

Video: H.264 (libx264), H.265 (libx265), VP8/VP9 (libvpx), AV1 (libaom-av1), MPEG-2/4, ProRes, DNxHD, Theora
Audio: AAC (native + libfdk-aac where licensed), MP3 (libmp3lame), Opus (libopus), Vorbis, FLAC, PCM
Containers: MP4, MKV, MOV, WebM, AVI, TS, HLS (m3u8), DASH, FLV, GIF, APNG
Images: MJPEG, PNG, WebP (via lavf)

Hardware encoders (nvenc, qsv, vaapi, videotoolbox) are not in the bundled binary. Use the system FFmpeg for GPU acceleration.

---

Troubleshooting

Symptom	Fix
Cannot find module 'ffmpeg-static'	Run npm install ffmpeg-static in the project root
Binary not executable on Linux/macOS	Run chmod +x $(node -e "process.stdout.write(require('ffmpeg-static'))")
Encoder libx264 not found	Bundled binary may lack the codec; install system FFmpeg (apt install ffmpeg / brew install ffmpeg)
No such file or directory on output	Ensure the output directory exists before running FFmpeg
Transcode hangs in CI	Add -y flag to overwrite without prompting
Progress not reported	Use -progress pipe:1 to write progress data to stdout
Slow GIF generation	Use the two-pass palettegen approach (see example above)
FFMPEG_STATIC_SKIP_BINARY_DOWNLOAD ignored	Set the env var before running npm install, not after