ffmpeg-ffm
Panama FFM (jextract) bindings for FFmpeg with bundled, from-source LGPL
natives. One Maven coordinate, batteries included — no user-installed FFmpeg,
no JNI.
| Artifact |
Contents |
License |
io.github.ghosthack:ffmpeg-ffm |
jextract-generated stubs + runtime loader (pure Java, JDK ≥ 22) |
MIT |
io.github.ghosthack:ffmpeg-ffm-natives (classifier macos-arm64, windows-x64, linux-x64) |
FFmpeg 8.1.2 shared libraries, built from unmodified source, LGPL-only configuration |
LGPL v2.1+ (see THIRD-PARTY.md) |
Status: decode plus packet-remux surface (demux + decode + swscale and curated
MP4/MOV, Matroska/WebM, AVI, Ogg, still-image, MP3, FLAC, and WAV muxers; no
encoders or network), curated to the API listed in jextract/gen-bindings.sh.
Platforms: macos-arm64, windows-x64, and linux-x64. AV1 decodes in software
via a statically linked dav1d (BSD-2) — FFmpeg has no native AV1 software
decoder, only a hwaccel shim. JPEG XL decodes via a statically linked libjxl
0.11 (BSD-3, with highway/brotli/skcms; since 0.3.0) — FFmpeg has only a JXL
parser natively.
Software decode by design. All decoding runs on the CPU (with full SIMD:
dav1d and FFmpeg ship hand-written NEON/AVX kernels selected at runtime). The
natives do compile the hardware-accel hooks (VideoToolbox on macOS,
D3D11VA/D3D12VA/DXVA2 on Windows), but the curated binding surface omits the
hw-device API (av_hwdevice_ctx_create, get_format, av_hwframe_transfer_data),
so nothing routes through them. Hardware decode would be a purely additive
binding release — regenerated stubs, byte-identical natives.
Use
<dependency>
<groupId>io.github.ghosthack</groupId>
<artifactId>ffmpeg-ffm</artifactId>
<version>8.1.2-0.3.8</version>
</dependency>
<dependency>
<groupId>io.github.ghosthack</groupId>
<artifactId>ffmpeg-ffm-natives</artifactId>
<version>8.1.2-0.3.8</version>
<classifier>macos-arm64</classifier> <!-- or windows-x64 / linux-x64 -->
<scope>runtime</scope>
</dependency>
When using the module path, declare requires ffmpeg.ffm; and run with
--enable-native-access=ffmpeg.ffm. When using the class path, run with
--enable-native-access=ALL-UNNAMED. Then:
import io.github.ghosthack.ffmpegffm.ffmpeg.FFmpeg;
int version = FFmpeg.avformat_version(); // natives extract + load on first use
core/src/test/java/.../SmokeTest.java is a complete open→decode→scale example.
Decoder send/receive loop
Demuxers may return zero-sized packets (Ogg/Theora does this for duplicate
frames). Do not pass those packets to avcodec_send_packet: libavcodec treats
an empty packet like a decoder drain, so a later data packet can fail with
EINVAL. DecoderSupport.hasPayload(packet) distinguishes packets that are
safe to send.
The send/receive API also requires callers to retain and resend the same packet
when avcodec_send_packet returns EAGAIN; reading a replacement packet loses
input. Use DecoderSupport.averrorEagain() for the platform-specific native
error value. ThreadedTheoraSmokeTest is the complete buffered example,
including empty-packet filtering, packet retention, and final draining.
Packet remuxing
The native bundle includes the MP4/MOV family (mov, mp4, ipod, 3gp,
3g2), Matroska/WebM, AVI, Ogg, single-image (image2/image2pipe), APNG,
GIF, WebP, MP3, FLAC, and WAV muxers. The single-image muxers cover JPEG, PNG,
WebP, and JPEG XL packet output. Encoders remain disabled: callers create an
output context and streams, copy codec parameters, rescale packet timestamps,
and pass the original encoded packets to av_interleaved_write_frame.
RemuxSmokeTest verifies that the curated muxers are present and that
same-container remuxing preserves encoded packet payloads.
Muxer availability alone does not prove that remuxing removes metadata carried
inside an encoded packet or a format-required header. Applications must verify
that property per format rather than treating this bundle as a metadata policy.
The binding deliberately exposes raw libavformat policy rather than deciding
which container or stream metadata an application should retain. Callers own
that allowlist and should preserve presentation-critical stream parameters and
side data when constructing the output.
YUV→RGB colourspace
A bare sws_getContext decodes YUV with the BT.601 matrix and, for non-yuvj
formats, limited range. BT.709 (HD) content then comes out colour-shifted
(e.g. 220,40,40 red renders as 204,21,42). Tell the context the source matrix
and range from the frame (since 0.3.8):
sws_getColorspaceDetails(...) to read the current tables and settings;
sws_setColorspaceDetails(ctx, sws_getCoefficients(AVFrame.colorspace(f)), AVFrame.color_range(f) == AVCOL_RANGE_JPEG() ? 1 : 0, <table, dstRange, brightness, contrast, saturation as read>).
sws_getCoefficients takes AVColorSpace values directly. AVCOL_SPC_UNSPECIFIED
falls back to BT.601, so pick your own default (commonly BT.709 for HD) when the
frame is untagged. SwscaleColorspaceTest is the worked example.
Library resolution order
-Dffmpegffm.libdir=<dir> or FFMPEG_FFM_LIBDIR — use an existing FFmpeg
install (also the LGPL relinking hook);
- the bundled natives jar for the current platform, extracted once to
~/.cache/ffmpeg-ffm/<version>-<platform>/;
- libraries already loaded by the host application.
Gotcha: generated indexed accessors
jextract 22 generates indexed array-field accessors (e.g.
AVFrame.linesize(frame, 0)) whose VarHandle is built from the field's own
layout, so they read relative to the struct start, not the field offset —
wrong for every array field not at offset 0. Use the field-slice form instead:
int linesize0 = AVFrame.linesize(frame).getAtIndex(ValueLayout.JAVA_INT, 0);
Building
Each platform's natives are built on that platform; stub generation runs once,
on macOS (layouts are portable across platforms for FFmpeg's public API).
macOS (arm64):
mkdir -p build/ffmpeg-8.1.2
curl -sfL https://github.com/FFmpeg/FFmpeg/archive/refs/tags/n8.1.2.tar.gz \
| tar xz --strip-components=1 -C build/ffmpeg-8.1.2
build-natives/macos-arm64.sh # configure/make, stage dylibs + manifest
jextract/gen-bindings.sh # regenerate stubs (needs tools/jextract-22, see tools/README.md)
mvn install # installs ffmpeg-ffm + natives:macos-arm64, runs smoke tests
Windows (x64), from an MSYS2 MINGW64 shell: see build-natives/windows-x64.sh
header for prerequisites, then the same flow with windows-x64.sh.
Staged natives (natives/src/main/resources/natives/) are build outputs and
not committed; the scripts verify every shipped library resolves its
dependencies only against the staged set and the OS.