Add FFmpeg N-API bindings research and extract implementation tasks

[Copilot]

Captures research finding that production-ready FFmpeg N-API bindings already exist (node-av, @mmomtchev/ffmpeg), enabling a faster WebCodecs implementation path by building an adapter layer rather than raw N-API from scratch.

New Research

• research/ffmpeg-napi.md — Analysis of 4 existing FFmpeg N-API libraries with comparison matrix and recommendation to use node-av as backend

New Tasks

• tasks/evaluate-ffmpeg-napi-bindings.md — Evaluate node-av vs @mmomtchev/ffmpeg with defined criteria
• tasks/videodecoder-shim-node-av.md — Implementation sketch for VideoDecoder on node-av:

// Wrap existing N-API binding with WebCodecs-compliant interface
import { Decoder } from 'node-av';

export class VideoDecoder {
  configure(config: VideoDecoderConfig): void {
    const parsed = parseCodecString(config.codec);
    this._decoder = new Decoder({ codec: parsed.ffmpegCodecId });
  }
  // Map decode() → node-av, wrap output as VideoFrame
}

Updated Docs

• research/options.md — Added Option 1b (N-API bindings + shim) as recommended fastest path
• research/README.md, nodejs-implementation.md, nodejs-linux-napi-ffmpeg.md — Cross-references to new research
• tasks/README.md — Added new tasks to Week 1 table
• tasks/napi-poc-addon.md — Note about alternative path via existing bindings

Original prompt

Capture this research finding in all the appropriate places and extract from it task md files to put into tasks folder. Update any existing tasks and documents as appropriate.

Outcome | Yes, there are existing N-API FFmpeg bindings you can stand on.
Obstacles | None of them are WebCodecs-shaped; you still need an adapter layer.
Plan | Reuse an FFmpeg N-API library as the “engine” and build WebCodecs on top.

⸻

Short answer: yes — there are already serious FFmpeg bindings built on Node-API, so you don’t have to start from raw C FFmpeg + N-API.

1. Strong candidates

node-av (SeydX)
	•	Native FFmpeg v8 bindings for Node.js.
	•	Uses a compiled addon (Node-API) with:
	•	Low-level API: FormatContext, CodecContext, Frame, Packet, etc., very close to libav* C API.  
	•	High-level API: Demuxer, Decoder, Encoder, Muxer, plus a “pipeline” API that already models decode/encode chains.  
	•	Supports hardware acceleration (CUDA, VAAPI, auto-detect) and exposes HardwareContext.  
	•	Ships prebuilt binaries for all major platforms; on Linux you can just npm install node-av.  
	•	Fully typed for TypeScript, modern async/await patterns.  

This is probably the best “drop-in engine” for a Linux-only WebCodecs implementation right now.

⸻

@mmomtchev/ffmpeg / node-ffmpeg (avcpp + nobind17)
	•	GitHub: mmomtchev/ffmpeg (library name often referred to as node-ffmpeg).  
	•	Wraps avcpp (a C++ wrapper around FFmpeg’s C API) and exposes it to Node via nobind17, which itself sits on Node-API / node-addon-api.  
	•	Provides:
	•	A fairly complete mapping of FFmpeg (demuxers, decoders, encoders, filters).
	•	A Node.js Streams API: Demuxer, AudioDecoder, VideoDecoder, Filter, VideoTransform, AudioTransform, VideoEncoder, AudioEncoder, Muxer, etc.  
	•	Designed to allow safe-ish async use and multi-threading, with some explicit caveats around misconfigured streams.  

Good fit if you like the streams model and don’t mind the extra avcpp layer.

⸻

libav (Astronaut Labs)
	•	Package libav / repo astronautlabs/libav.  
	•	Node.js bindings to ffmpeg’s libav* libraries, adapted to be “comfortable and efficient” in TypeScript.
	•	Uses Node-API as well, but:
	•	Marked “Pre-Alpha Quality; incomplete, broken, heavy development”.  
	•	Requires system FFmpeg 5.x and dev headers installed on Linux.  

Probably better as inspiration/reference than a solid base for a WebCodecs project right now.

⸻

ff-helper (napi-rs-based helper)
	•	ff-helper is a napi-rs binding wrapping a few FFmpeg features, like getting video info and generating screenshots.  
	•	Explicitly not a full FFmpeg binding; just a helper.  

Useful as a tiny example of napi-rs + FFmpeg, but not enough for WebCodecs.

⸻

2. How this helps your WebCodecs plan (Linux-only)

You can absolutely avoid writing raw C++/Node-API around FFmpeg from scratch:
	•	Pick one of the full bindings as your “FFmpegService”:
	•	If you want modern TS + pipelines + prebuilt binaries → node-av.
	•	If you want streams + avcpp and don’t mind extra C++ layer → node-ffmpeg.
	•	Implement WebCodecs classes (VideoDecoder, VideoEncoder, VideoFrame, etc.) in TypeScript, and internally:
	•	Use node-av’s Decoder / Encoder or node-ffmpeg’s VideoDecoder / VideoEncoder to do the actual work.
	•	Map WebCodecs configure() → underlying codec/stream setup.
	•	Map decode()/encode() → feed frames/packets into the N-API binding.
	•	Use their existing thread/memory/resource management instead of building your own.

You’d still need to:
	•	Reproduce WebCodecs semantics (state machine, reset, close, isConfigSupported, error types).
	•	Possibly wrap/normalize timestamps, formats, and pixel layouts to match spec.

…but you avoid the largest yak: raw FFmpeg + Node-API integration.

⸻

3. Concrete recommendation

For a Linux-first WebCodecs-in-Node prototype:
	1.	Start with node-av as the backend:
	•	Use its high-level Decoder/Encoder for quick progress; drop to low-level CodecContext/Frame when you need more control.  
	2.	Wrap it in TS classes that exactly match the WebCodecs IDL.
	3.	Only reach for your own N-API code if you discover a semantic gap you cannot bridge cleanly via node-av.

next step: sketch a VideoDecoder shim that sits on top of node-av.Decoder and shows how the mapping would look.

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.