Provides FFmpegDecoder.
This plugin uses Java 22's new Foreign Function & Memory API ("Panama") to call into several of the underlying libraries (see below) of FFmpeg, in order to extract still frames from video files.
FFmpeg is not included with this plugin and must be provided separately. Most OS package managers should provide it, although the libraries that they link with it (which provide format/codec support) will vary. If the version provided by your package manager does not support the format(s) you need, you may have to compile FFmpeg yourself. See below for format compatibility information.
Once FFmpeg has been installed, its containing directory must be present on the Java library path. You can either change your library path to include it (by adding the -Djava.library.path VM argument to your config/jvm.options file), or move the library files to one of the directories on that path. Galia logs the Java library path at startup.
FFmpeg relies on several of its own native libraries to do its work, and this plugin interfaces with several of them. It was developed against FFmpeg 7.0, which includes the following library versions (ffmpeg -version):
Other library major versions (e.g. 6 or 8) are unlikely to work correctly, and may not work at all.
Galia's internal design maintains the concept of a "file format,” and assumes that such a format can be inferred reliably from some combination of filename extension, identifier extension, and file signature ("magic bytes”). This assumption works quite reliably for image files, but not so much for video files, which commonly have separate container and codec formats within the same file. This plugin therefore considers format compatibility on the basis of container format only, and assumes that FFmpeg will support the codecs contained within whatever containers it encounters—which, thanks to the broad codec support of FFmpeg, is probably actually the case most of the time. When FFmpegDecoder encounters a codec format that it doesn't support, it will produce an HTTP 500 ("internal server error") response.
The following container formats are recognized by this plugin:
Note that it's possible for a particular FFmpeg build to be missing support for some of these formats due to it not being compiled in. So, the list of "effectively supported” formats is the set intersection of these formats and the formats supported by the locally installed FFmpeg build (which can be viewed using the ffprobe -demuxers command).
FFmpeg itself supports many other formats than these, including many still image formats. It may be possible to support other formats in future plugin releases.
This decoder supports a meta-identifier-encoded second offset in order to request a frame at a particular second. For example, to request the frame closest to the 30-second offset using the StandardMetaIdentifierTransformer with default configuration:
http://example.org/iiif/3/video.mp4;30/full/max/0/default.jpg
When a second offset is not present, the first frame is returned.
Use the plugin installer:
bin/install_plugin.sh galia-plugin-ffmpegAlternatively, download the plugin directly and extract it into Galia's plugins directory.