feat: add a native extension API and an FFmpeg-based media module

[devopvoid]

Closes #77.

Sends a media file over a peer connection in place of a camera and a microphone, and adds the native extension API that makes it possible without carrying every frame through Java.

The extension API

A small, versioned C function table in webrtc-jni (webrtc_java_api.h) that a native extension library calls directly. NativeApi.tableAddress() hands out its address and NativeApi.handleOf(source) the native handle of a CustomVideoSource or CustomAudioSource, with dev.onvoid.webrtc.internal qualified-exported to webrtc.java.media.

There is no link-time dependency between the two native libraries, which is the point: NativeLoader extracts to a temporary file with a generated name, so there is nothing an extension could link against. Any future extension — GStreamer, a capture SDK, a hardware encoder — can use the same table.

CustomVideoSource::PushFrame and CustomAudioSource::PushAudioData now take a capture time, exposed as pushFrame(VideoFrame, long) and pushAudio(..., long). Existing callers that pass no timestamp keep the old behaviour of being stamped with the source's own clock.

Reading VideoStreamEncoder::OnFrame changed one detail of the design worth recording: the encoder overwrites a frame's RTP timestamp with 90 * ntp_time_ms and drops any frame whose NTP capture time does not advance. The field that carries a caller's timing to the wire is therefore the NTP capture time, not rtp_timestamp.

The media module

webrtc-java-media, a JPMS module (webrtc.java.media) with its own native library, which decodes with FFmpeg and feeds the custom media sources through the table above. Nothing goes through Java: one thread demuxes and decodes, a pacer delivers in real time.

• Zero copy where it counts. A decoder that already produced yuv420p — almost all 8-bit H.264, VP8, VP9 and MPEG-4 — has its AVFrame handed on by reference and dropped again in the release callback once WebRTC lets go of the pixels. Anything else goes through swscale first.
• Audio in the only shape WebRTC takes. Resampled to interleaved 16-bit PCM at 48 kHz, mono or stereo, and re-cut into exact 10 ms chunks whose timestamps advance in exact 10 ms steps, so the audio is regular whatever the container's packet timing was.
• One clock mapping, kept. Presentation times are mapped onto the WebRTC clock once, so what reaches the receiver carries the timing of the file rather than of a thread, and audio stays lined up with video however much the pacing thread is jostled.
• Bounded queues. Decoding runs ahead only as far as they allow, so a whole file is never decoded into memory.
• Play, pause, seek and looping. Looping keeps the mapping and adds the source's duration to every timestamp, which hides the seam and keeps capture times rising as the encoder requires.

Java API: MediaReader, MediaInfo, MediaPlayer, MediaPlayerListener, MediaPlayerState, and MediaFileSource as the turnkey class the issue asked for.

MediaFileSource source = new MediaFileSource(Path.of("movie.mp4"));

VideoTrack videoTrack = factory.createVideoTrack("video", source.getVideoSource());
AudioTrack audioTrack = factory.createAudioTrack("audio", source.getAudioSource());

peerConnection.addTrack(videoTrack, List.of("stream"));
peerConnection.addTrack(audioTrack, List.of("stream"));

source.play();

Two departures from the original design

• One demux-and-decode thread, not a decode thread per stream. Four threads and four queues solve a problem this does not have: decoding one file runs far ahead of real time, and the pacer's bounded queues already absorb decode jitter. Splitting the decoders out later is a local change behind the same queues.
• Video and audio are paced independently rather than as one ordered stream. They go to different sources and need no ordering between them. It also removes a starvation the ordered version would have had: with one queue full and the other empty, a pacer waiting on the empty one would never drain the full one, and the decode thread blocked on the full one would never fill the empty one.

Verified

Measured on the committed test asset — three seconds of 320x240 VP8 at 15 fps and 48 kHz mono Opus — observed at the sinks of real tracks made from the custom sources:

• 45 video frames at 320x240, and 300 audio chunks of 480 frames at 48 kHz mono
• 3001 ms to play 3.008 s of media, so the real-time pacing is exact

19 tests in the media module cover the frame and chunk counts, the shape the media arrives in, real-time pacing, looping, pause, seek, a missing source, and the reader being spent once a player adopts it. They pass under -Xcheck:jni with no warnings at all — not just no fatal errors — including the observer callbacks, which run on the player's own thread and attach to the JVM to make a call. mvn verify on the webrtc module stays green at 168 tests.

FFmpeg build and licensing

Built from the third-party/ffmpeg submodule pinned to n7.1.1, LGPL only: no --enable-gpl, no --enable-nonfree, --disable-everything and then explicit lists of just what this module plays. FFmpeg is linked dynamically and ships as separate files inside the platform jar, so its libraries can be replaced, which is what the LGPL asks. The wrapper code stays Apache-2.0.

Bringing the build up on Windows corrected three things, all of which would have bitten anyone else trying it:

• find_program(bash) turns up Git for Windows' bash, which carries neither make nor nasm. MSYS2 is now looked for by path, with MSYS2_ROOT as an override.
• configure probes the compiler, so the shell has to be entered through vcvars, and inside it the MSVC toolchain has to precede /usr/bin: MSYS2 ships a coreutils link that otherwise shadows MSVC's linker and makes configure conclude the compiler cannot create executables. This is why configure, make and make install are one generated script run once rather than three execute_process calls.
• An MSVC build installs the import libraries into bin/ next to the DLLs, leaving only the .def files in lib/.

Docs and example

docs/guide/media/media-files.md with a sidebar entry and a section on the examples page, plus a runnable MediaFileExample. Writing the example is what turned up that webrtc-java-media declared no dependency on its own classifier artifact, so depending on the module got the Java classes and none of the native libraries.

Not done yet, deliberately

• FFmpeg has been built for windows-x86_64 only. The other six targets and the CI caching by FFmpeg tag and platform are next.
• The module is opt-in, behind the with-media-extension profile, and stays that way until every platform builds in CI.
• Only local files play: file and pipe protocols. Network sources need no new code, only the protocols turned on in the build.
• AdaptFrame on pushed video is deferred, because applying encoder resolution and frame-rate requests means cropping and scaling the buffer, which would change behaviour for existing pushFrame callers.

A factory fed by this module is sending pushed audio and cannot also send audio captured by its AudioDeviceModule, which is the same constraint as #289; the docs say so in both places.