feat(encoder): add preserveFramePictType to allow forced keyframes

[Pradhumn115]

Fixes #314.

Problem

The high-level Encoder clears frame.pictType on every frame in prepareFrameForEncoding:

// Clear pict_type - encoder will determine frame types based on its own settings
// Input stream's frame type hints are irrelevant when re-encoding
frame.pictType = AV_PICTURE_TYPE_NONE;

That makes it impossible to force a keyframe on demand. Setting frame.pictType = AV_PICTURE_TYPE_I (with forced-idr on encoders that support it) is the standard FFmpeg way to request an IDR for a specific frame, but it is erased before avcodec_send_frame, so the encoder never emits the forced keyframe.

For live streaming this matters: a decoder produces nothing before its first keyframe, and on a lossy or late-joining connection the client needs to request a fresh IDR (packet-loss recovery, a new viewer, a resized encode). Through the high-level API there was no way to honour that.

Change

Clearing pictType is still correct for transcoding, where decoded input frames carry frame-type hints that should not drive the output GOP. So this is an opt-in option rather than a default change:

if (!this.options.preserveFramePictType) {
  frame.pictType = AV_PICTURE_TYPE_NONE;
}

• New EncoderOptions.preserveFramePictType?: boolean (default false).
• When false (default), behaviour is unchanged.
• When true, the frame's pictType is passed through, so AV_PICTURE_TYPE_I forces an IDR.

Verification

Tested against libx264 with a long GOP (so the only keyframes are the initial IDR and any forced one), encoding 10 frames and requesting a forced keyframe on frame 5:

	forced keyframe at frame 5
default (no flag)	not present — unchanged behaviour
preserveFramePictType: true	present

Both cases are covered by new tests in test/encoder.test.ts. Confirmed non-vacuous: reverting the guard makes the "forces a keyframe" test fail while the default-behaviour test still passes.

Happy to adjust — e.g. a dedicated encoder.requestKeyframe()-style API instead of a flag — if you'd prefer a different shape.

[seydx]

Thanks!

[Pradhumn115]

Thanks a lot for the quick review and merge! 🙏

node-av has been great to build a live H.264 streamer on — the low-level sendFrame() path is what let me work around this cleanly in the meantime, and it's nice to have the high-level API cover the case now too. Looking forward to switching over to preserveFramePictType once it lands in a release.