v1.4.0

Key changes

• Rewritten Bus messaging.
  • Lazy creation of Message / Element source wrappers only when required (see below).
  • Fixed ability to add and remove a BusSyncHandler (for synchronous message handling) as required.
  • Messages can now be disposed explicitly within callbacks.
• Improved PlayBin API.
  • Support for source-setup and element-setup signals so that automatically added elements can be configured.
  • Added wrapper enum and methods for controlling the PlayBin flags property.
• Added Element::seekSimple, mapping gst_element_seek_simple, and moved implementation of various other seek and query methods to Element rather than Pipeline as per upstream.
• Added Version::of method (with some validation) for usage in Gst::init.
• Rewritten iteration used in Element::getPads and Bin::getElements etc. to not require GC for cleanup (see below).
• Fixed running with Windows MSVC build of GStreamer.
• Added ability to pass GStreamer path to Maven for running tests on Windows - eg. mvn -Dgstreamer.path=<PATH_TO_GSTREAMER_BIN> verify. NB. on macOS, passing the path via jna.library.path should work as well.

Bus message / iteration memory handling changes.

A key part of this release has been rewriting bus messaging and pad / element iteration. This was done as part of some work for a Codelerity client's project, to ensure some key areas of the bindings now support explicit disposal as well as via the garbage collector.

In the Bus, Messages objects are now created lazily, and only when a sync callback or Bus.MESSAGE listener are connected. It's also now possible to dispose of the Message in either of those callbacks. Wrapper Elements for message sources are also created lazily only when required. Previously, the Message and the source Element wrappers were created for every message on the Bus, whether a callback required them or not. And the native references could only be cleared by garbage collection (which is still the default).

Calling getElements(), getPads(), etc. should no longer keep an extra reference on the iterator, or the called object (via the iterator) until next garbage collection.

Obviously there is some potential for issue here, particularly if a project inadvertently relies on native objects staying alive for longer. Please report any issues found if things work with 1.3.0 but not 1.4.0.

v1.3.0

Key changes

• Added new API for generic Pad probes, allowing access to all features of underlying GStreamer, and supporting Query probes for the first time. The existing event and data probes (and possibly Pad::block) are scheduled for deprecation in 1.4.
• Added basic support for Meta types, as well as initial support specifically for VideoTimeCodeMeta. Other Meta types will follow, or can be defined externally.
• Added Sample::setBuffer and Sample::setCaps support.
• Added ability to pass a NativeEnum to GObject::set. This is a convenience, and the returned value from GObject::get will not be a NativeEnum.
• FIX added a new Clock::getCalibration method - the old method inherited from previous bindings is deprecated and cannot work.
• FIX added Structure to registered types, rather than relying on older fallback instantiation code - fixes extracting Structure results from various places.
• FIX fixed extended message types causing problems in Bus callbacks due to code still expecting flags.
• TESTS added GitHub Actions configuration to test on GStreamer 1.8, 1.16 and 1.18. Fixed concurrency issue in SampleTester, and added utility classes for testing with probes.

Also see https://github.com/gstreamer-java/gst1-java-core/milestone/6?closed=1

Thanks

Thanks to @aveco-devel and @lafoletc for contributions in this release.

v1.2.0

Key changes

• Added support for Context (GstContext) and need-context messages.
• Added support for setting and querying GstObject properties in their serialized String format (see GstObject::setAsString and GstObject::getAsString). See issues #182 and #166
• FIX ownership and refcount incorrect if previously cached unowned, causing memory issues and crashes. See #171
• FIX various issues around probes and Pad::block. See #184
• FIX various issues around Promise. See #175 #176 #178

See all changes at https://github.com/gstreamer-java/gst1-java-core/pulls?q=is:pr+milestone:1.2+is:closed

Thanks

Thanks to @MaZderMind @Chatanga and @kezhuw for their contributions to this release.

v1.1.0

This release brings full access to the GStreamer Controller API and a variety of other fixes and improvements.

Key changes

• Full support for the GStreamer Controller API as defined at https://gstreamer.freedesktop.org/documentation/application-development/advanced/dparams.html This includes interpolated and LFO control of element parameters. NB. an element property must be defined as controllable for this to work - use gst-inspect to check as the bindings don't currently expose this information. Fixes #157
• Added Element::linkFiltered to link an element based on provided Caps. Fixes #150
• Added support for passing through null values in GObject::set for eg. resetting a PlayBin sink to default. Fixes #142
• Added support to Structure::getValues for extracting lists of values inside a native GstValueList. Fixes #161
• Added support for retrieving ICE state and various other fixes in WebRTC support. Fixes #152
• Errors thrown during Bus message delivery will be logged and no longer fail silently inside the ScheduledExecutorService. Fixes #99
• Added manifest entry for Automatic-Module-Name: org.freedesktop.gstreamer. This is for testing purposes only - please provide feedback if using the bindings on the module path.

Thanks

A big thank you to LivingAsOne for funding work on the Controller API.

Thanks to @MaZderMind and @PertsevRoman for their contributions to this release.

v1.0.0

This is the first full release of gst1-java-core v1. The bulk of the work leading up to this release has been finalising, stabilising and documenting the API outside of the lowlevel package, completing the work of porting the original 0.10 bindings.

Key changes

Changes in beta 1

• All classes have been audited, non-functional legacy methods removed or replaced, documentation updated and links added to upstream GStreamer documentation where appropriate. Any methods exposing lowlevel classes have been removed or rewritten.
• Minimum requirements have been updated to Java 8 and JNA 5.2.
• Version support has been added to Gst.init(). The minimum GStreamer requirement remains 1.8, although this is now enforced. If you require features that require a later version of GStreamer, you must use the version of Gst.init(...) that takes a Version or these mappings will be disabled. eg. Gst.init(new Version(1, 14)). There is also an annotation @Gst.Since(minor = 14) for use on classes, methods and constants that require later versions - this annotation is included in the JavaDoc.
• Non-functional legacy classes have been removed, including all of the controller package and various interface classes.
• GObject, GError and various GIO related classes have been moved into the GLib package. This is an initial step towards separating out GStreamer and GLib bindings into separate libraries in future.
• NativeObject and various other lowlevel classes have been moved out of lowlevel and into the GLib package as official API.
• Event, Message and Query, as well as related classes have been moved into their respective packages, partly to improve encapsulation.
• WebRTC classes have been moved into their own package.
• Enums have been rewritten around NativeEnum and NativeFlag interfaces (in GLib package). Methods accepting int flags (eg. SeekFlags) now take EnumSet and related int constants are now enum.
• Methods accepting or returning ClockTime now take or return a long. This is for efficiency and consistency - GLib does not give all type information required to be consistent here. NB. the value is an unsigned 64-bit integer value in nanoseconds. ClockTime remains as a collection of utility methods for working with these values. It still doesn't (yet) correctly handle "negative" values.
• New memory handling and removal of finalization. A new NativeObject.Handle type wraps all native pointers, and subclasses implement all ref, unref, free, etc. Handle subclasses should be used to call different native functions in these cases. Memory handling is a cleaner-like mechanism, but using the existing weak reference cache rather than additional phantom references. In the past, only GObject instances were cached to ensure the same NativeObject was returned for any pointer - this now applies to all NativeObject subclasses. All garbage collection tests pass with the new code, but there may be possibility for regressions caused by slightly different behaviour.
• A new Natives utility class provides access to methods required for translating to and from Java objects and native representations where required, including translation into a GPointer (see below) or raw Pointer. Natives.objectFor() methods replicate functionality previously in NativeObject to get the Java representation of a native reference. These should be used in all cases in favour of NativeObject.Initializer except where the native call is a constructor.
• New extension mechanism to register additional NativeObject subclasses (it was theoretically possible to achieve this before, but with major caveats and unsupported). See NativeObject.TypeRegistration and Natives.registration(..). Instances of NativeObject.TypeProvider should be made available by the standard Java ServiceLoader mechanism. Internal types use the same mechanism, reducing uses of reflection in the library.
• GPointer and subclasses have been added to the lowlevel package. These are subclasses of JNA's PointerType and will form the basis of native mapping in future. They are already required for Handle-related functionality. They may become part of the API in future. Using anything else in lowlevel will likely break from release to release. Lowlevel is no longer included in the JavaDoc.
• Travis CI configuration added. All future PR's must pass before integration, and should include tests where appropriate. The current CI only covers GStreamer 1.8 (baseline), but will be extended to include testing on later GStreamer as well. Tests may need to be version aware if they target features higher than 1.8.

Additional changes from beta 2

• FIX make sure GObject subclasses can be GC'd after explicit call to dispose() - fixes #146
• Minor updates to NativeObject.Handle API and added documentation. The atomic reference and boolean fields are now correctly private (mistakenly left protected in beta-1). ownsHandle() renamed as ownsReference().
• Move GObject signal and Pad probe native management into Handle to ensure the callbacks are removed when GC'd as before.
  • Behavioural change - all callbacks are now disconnected on explicit calls to invalidate() and dispose(). In general make sure to keep references to objects with callbacks and dispose of them explicitly - relying on the GC for this is not recommended.
  • The Pad method for adding an event probe with an int mask has been removed from the API.
  • Event probe testing has been fixed.
• NativeObject now implements AutoCloseable. Defaults to calling dispose().
• FIX getting a GObject subclass from a GValue will now return a caller-owned reference (switched to g_value_dup_object). Iterating objects, eg. by calling getPads() would return and cache unowned objects whose lifecycle was not correctly tracked. This might cause regressions if code relied on the old behaviour.
• Bus disposal is now linked to Pipeline lifecycle. Bus instances will be GC'd even when not explicitly closed. Test for this no longer ignored.
• Added a system property to detach callback threads (workaround for #147 where JNA isn't clearing thread proxies on macOS) - use -Dglib.detachCallbackThreads=true

v1.0.0-beta-2

Updated beta for v1.0.0 - see v1.0.0-beta-1 for major changes.

• FIX make sure GObject subclasses can be GC'd after explicit call to dispose() - fixes #146
• Minor updates to NativeObject.Handle API and added documentation. The atomic reference and boolean fields are now correctly private (mistakenly left protected in beta-1). ownsHandle() renamed as ownsReference().
• Move GObject signal and Pad probe native management into Handle to ensure the callbacks are removed when GC'd as before.
  • Behavioural change - all callbacks are now disconnected on explicit calls to invalidate() and dispose(). In general make sure to keep references to objects with callbacks and dispose of them explicitly - relying on the GC for this is not recommended.
  • The Pad method for adding an event probe with an int mask has been removed from the API.
  • Event probe testing has been fixed.
• NativeObject now implements AutoCloseable. Defaults to calling dispose().
• FIX getting a GObject subclass from a GValue will now return a caller-owned reference (switched to g_value_dup_object). Iterating objects, eg. by calling getPads() would return and cache unowned objects whose lifecycle was not correctly tracked. This might cause regressions if code relied on the old behaviour.
• Bus disposal is now linked to Pipeline lifecycle. Bus instances will be GC'd even when not explicitly closed. Test for this no longer ignored.
• Added a system property to detach callback threads (workaround for #147 where JNA isn't clearing thread proxies on macOS) - use -Dglib.detachCallbackThreads=true

v1.0.0-beta-1

This is the first beta release of gst1-java-core v1. The bulk of the work leading up to this release has been finalising, stabilising and documenting the API outside of the lowlevel package, completing the work of porting the original 0.10 bindings.

Key changes

• All classes have been audited, non-functional legacy methods removed or replaced, documentation updated and links added to upstream GStreamer documentation where appropriate. Any methods exposing lowlevel classes have been removed or rewritten.
• Minimum requirements have been updated to Java 8 and JNA 5.2.
• Version support has been added to Gst.init(). The minimum GStreamer requirement remains 1.8, although this is now enforced. If you require features that require a later version of GStreamer, you must use the version of Gst.init(...) that takes a Version or these mappings will be disabled. eg. Gst.init(new Version(1, 14)). There is also an annotation @Gst.Since(minor = 14) for use on classes, methods and constants that require later versions - this annotation is included in the JavaDoc.
• Non-functional legacy classes have been removed, including all of the controller package and various interface classes.
• GObject, GError and various GIO related classes have been moved into the GLib package. This is an initial step towards separating out GStreamer and GLib bindings into separate libraries in future.
• NativeObject and various other lowlevel classes have been moved out of lowlevel and into the GLib package as official API.
• Event, Message and Query, as well as related classes have been moved into their respective packages, partly to improve encapsulation.
• WebRTC classes have been moved into their own package.
• Enums have been rewritten around NativeEnum and NativeFlag interfaces (in GLib package). Methods accepting int flags (eg. SeekFlags) now take EnumSet and related int constants are now enum.
• Methods accepting or returning ClockTime now take or return a long. This is for efficiency and consistency - GLib does not give all type information required to be consistent here. NB. the value is an unsigned 64-bit integer value in nanoseconds. ClockTime remains as a collection of utility methods for working with these values. It still doesn't (yet) correctly handle "negative" values.
• New memory handling and removal of finalization. A new NativeObject.Handle type wraps all native pointers, and subclasses implement all ref, unref, free, etc. Handle subclasses should be used to call different native functions in these cases. Memory handling is a cleaner-like mechanism, but using the existing weak reference cache rather than additional phantom references. In the past, only GObject instances were cached to ensure the same NativeObject was returned for any pointer - this now applies to all NativeObject subclasses. All garbage collection tests pass with the new code, but there may be possibility for regressions caused by slightly different behaviour.
• A new Natives utility class provides access to methods required for translating to and from Java objects and native representations where required, including translation into a GPointer (see below) or raw Pointer. Natives.objectFor() methods replicate functionality previously in NativeObject to get the Java representation of a native reference. These should be used in all cases in favour of NativeObject.Initializer except where the native call is a constructor.
• New extension mechanism to register additional NativeObject subclasses (it was theoretically possible to achieve this before, but with major caveats and unsupported). See NativeObject.TypeRegistration and Natives.registration(..). Instances of NativeObject.TypeProvider should be made available by the standard Java ServiceLoader mechanism. Internal types use the same mechanism, reducing uses of reflection in the library.
• GPointer and subclasses have been added to the lowlevel package. These are subclasses of JNA's PointerType and will form the basis of native mapping in future. They are already required for Handle-related functionality. They may become part of the API in future. Using anything else in lowlevel will likely break from release to release. Lowlevel is no longer included in the JavaDoc.
• Travis CI configuration added. All future PR's must pass before integration, and should include tests where appropriate. The current CI only covers GStreamer 1.8 (baseline), but will be extended to include testing on later GStreamer as well. Tests may need to be version aware if they target features higher than 1.8.

v0.9.4

• Add support for WebRTC (#117 #129 #135)
• Add Data Probe and Pad Template support to Pad (#103 #105)
• Replaced use of deprecated functions in JNA to support JNA 5.x (#102)
• Add Gst.parseLaunch() (with support for single Element) and Gst.parseBinFromDescription(), and deprecate Bin.launch() and Pipeline.launch(); add error logging - (#104 #113)
• Many low-level API and structure fixes (#111 #115)
• Added simple Travis CI integration (#134)

Thanks @i-n-g-o @matthiasblaesing @a-morales @vinicius-tona

v0.9.3

• Updated Buffer API, adding support for setting / getting timestamps, offsets, buffer flags, etc.
• Added new MessageType values from GStreamer 1.10
• Changed Pad::link to throw an exception rather than return PadLinkReturn - this is a breaking API change and may require code updates.
• FIX code inherited from 0.10 bindings that assumed NativeLong size and Native.SIZE_T_SIZE were the same - broke bindings on Java 9+ with Windows 10 x64.

Thanks for help and contributions from @mutantbob and @matthiasblaesing

v0.9.2

• Added support for extracting values from a Structure backed by a native GValueArray

public <T> List<T> getValues(Class<T> type, String fieldName); // type needed for validation
public int[] getIntegers(String fieldName);
public int[] getIntegers(String fieldName, int[] array); // allow caching of array
public double[] getDoubles(String fieldName);
public double[] getDoubles(String fieldName, double[] array);

• Added query() method to Element API to support arbitrary queries, check if the query could be performed, access underlying query Structure. Use eg. -

SeekingQuery q = new SeekingQuery(Format.TIME); 
if (pipe.query(q)) {
    System.out.println(q.getStart() + " | " + q.getEnd());
    //System.out.println(q.getStructure());
} else {
    System.out.println("Couldn't perform seeking query");
}

• Various fixes including making sure all registered classes triggered by Gst.init() now correctly extend NativeObject (blocker for above features). Some potential for regression if anything relies on class initialization order of the removed non-NativeObject classes - other mechanism might be required, but all tests OK.