Xuggler 3.2: "Dalton"

Announcing Xuggler 3.2: Get It Here.

Table of Contents

Summary

Introducing Xuggler 3.2, "Dalton". Dalton was a focused effort on our part to further improve performance, especially in multi-threaded servers that want to manipulate raw data before re-encoding it. With that, here's the new features (and see below for defects fixed):

  • Getting and retrieving IBuffer objects from Xuggler audio, video or packet data is now much faster.
  • More memory allocation speed ups, especially in multi-threaded scenarios.
  • Xuggler now uses much less memory for IAudioSamples objects when you're just encoding data.
  • IBuffer objects now have meta-data telling you what type of bytes (e.g. int, short, long) the IBuffer thinks it's pointing to.
  • As usual, this release comes integrated with the very latest FFmpeg release.

As usual, read on for the details.

Release Notes

Faster IBuffer access

Previously, any call to IMediaData.getData(...) would have to pass from Java code to C code and back, and would create a new Java IBuffer object. In many cases though, you want to "borrow" the reference the IMediaData object already has, and so this is wasteful. Now you can use IMediaData.getDataCached() to "borrow" the IBuffer object without having to cross into C code (except for the first call), and without creating a new reference.

Faster Memory Allocation

With Xuggler 3.2 we've introduced a new "collect and sweep" garbage collection scheme for Native C objects managed from Xuggler. The result is Xuggler 3.2 replaces a global lock on allocation and a global lock on deletion with an atomic increment on most allocations, a global lock every 4096 (configurable) allocations, and no global locks on deletion. The result: allocation is up to 30% faster in highly thread-contentious applications.

Less Memory Used with IAudioSamples

Previous versions of Xuggler would always allocate about 192K for each IAudioSamples object, even if you told us you only needed room for 1 sample. As of Xuggler 3.2, this is no longer the case -- we'll allocate just what you ask us to (unless we discover later that we need more). See the backwards compatibility notes in this document for some more background.

IBuffer Type Information

This is a minor feature with quite powerful consequences if you know what you're doing, but now each IBuffer object has a IBuffer.getType() method that tells you what underlying native data type Xuggler thinks is in the buffer.

If you want to directly manipulate the raw data in Xuggler, this meta data can be quite handy. It's left as an exercise for the programmer to make use of this.

Change in Version Naming Scheme

Minor update here, but versions numbers for Xuggle Jar Files now have a forth component -- the data and time the jar was packaged on. This was added mostly for our internal use, but we thought we'd let you know it's not accidental.

Warnings

You must uninstall prior versions of Xuggler before installing this version.

This release of Xuggler is backwards compatible with the last release with the following exceptions:

  • In previous versions of Xuggler, any attempt to allocate IAudioSamples objects, no matter how many samples you requested, would always allocate 192K of data. This was because in order to decode data from a IPacket into an IAudioSamples object using IStreamCoder, FFmpeg required that much data.

    In high performance applications doing audio mixing, especially in real-time chat applications, this would result in 192K of memory being allocated, even if (for example MP3) you were only mixing 572 samples of audio data, and could lead to server overloading. Although 192K was required to decode, it can be useful to then split the audio up and send elsewhere, and use in systems that don't require 192K.

    In Xuggler 3.2, a call to IAudioSamples.make(int, int) will now only allocate the number of bytes required to hold that audio.

    In theory this is 100% backwards compatible, but old programs may have (erroneously) relied on the old behaviour and passed in invalid values for numSamples. That code will break with 3.2. Also, should you pass in an IAudioSamples object to IStreamCoder.decodeAudio(...) or IAudioResampler.resample that is too small (i.e. must have enough space for at least 48,000 samples when used with IStreamCoder.decodeAudio(...)), Xuggler will reallocate the correct amount of memory into the passed in object, potentially releasing the memory you have initialized the IAudioSamples object with.

    In short, if you ensure that you always specify the correct size for IAudioSamples objects on creation, you should be fine. Otherwise you may have some issues to work through.

    See Issue #191 for background.

Known Issues

Critical

There are no known critical issues in this release.

Major

Users of this version of Xuggler should be aware of the following limitations (which will be addressed in a future Xuggler release):

  • MediaWriter does not resample audio. To work around ensure the audio sample rate and channels you ask MediaWriter to encode is the same as what you set up your audio streams with. Tracking issue.
  • MediaViewer is experimental and not very robust. It's included only to get feedback, but you should not use it in production environments. Tracking issue.

Minor

There are two bugs in the current version of FFmpeg that may impact you. Both have simple workarounds:

  • Issue #92: Doing resize and changing color space from YUV to either BGR24 or ARGB AT THE SAME TIME produces erroneous black pixels. Workaround: do resize operations separately from colorspace conversions.
  • Issue #93: YUV to ARGB Converter causes every 2nd line of pixels to be offset by one. Work around: use BGR24 converter.

Issues Fixed

  • Defect #193: Audio breaks down while playing OGV videos
  • Defect #189: Performance concerns in xuggler-red5 adapter
  • Defect #174: Random crashes occur on the MacOS JVM
  • Defect #183: xuggler 3.1 force dependency on cli-common for EVERY xuggler call
  • Defect #181: Red5 0.8.0 & Xuggler 3.0.660 with videotranscoder 3.0.757 not working

Enhancements Added

What's Next?

We're going to add small features and fix bugs while we work on something using Xuggler internally, so don't expect a major release soon. We'll keep current with FFmpeg of course.

Warning: At some point the FFmpeg is going to move to GIT for source control. If you're in the habit of building Xuggler from our tip of tree, you'll want to install GIT. We'll likely be forced to require GIT and SVN to build Xuggler once FFmpeg makes the move. No ETA on this yet, but there is a lot of chatter on the FFmpeg lists about it. By the way, the advantage of this is we should also then be able to auto-integrate the latest libx264 as well.

Warning: We will likely have to move our SVN repository from Googlecode to some other site (still TBD). We'll try to keep disruption to a minimum if we need to do that.

Build Information

Tests

  • Java Tests: 605 (+8)

Fine Print

By reading these release notes, you acknowledge that while you may have had impure thoughts, you've never acted upon them. You also acknowledge you just lied.

Source Control Versions

Xuggler 3.2.879.FINAL

Hudson Good Build http://build.xuggle.com/job/xuggler_jdk5_stable/49/

Dynamic Revisions
* http://xuggle-ffmpeg.googlecode.com/svn/trunk : 814
  * svn://svn.mplayerhq.hu/ffmpeg/trunk : 19668
  * svn://svn.ffmpeg.org/mplayer/trunk/libswscale : 29538
* http://theyard.googlecode.com/svn/theyard/code/trunk/share/gnu/
    cxxtest/cxxtest-3.10.1 : 170
* http://xuggle.googlecode.com/svn/trunk/java/xuggle-xuggler : 879
* http://xuggle.googlecode.com/svn/trunk/build/java : 859

- Static Dependencies
* http://xuggle-ffmpeg.googlecode.com/svn/trunk/
  * libx264: ftp://ftp.videolan.org/pub/videolan/x264/snapshots/
        x264-snapshot-20090125-2245.tar.bz2
  * libmp3lame: http://downloads.sourceforge.net/lame/lame-398.tar.gz: 3.98
  * libspeex: http://downloads.xiph.org/releases/speex/speex-1.2rc1.tar.gz: 1.2 RC1
  * libfaac: http://downloads.sourceforge.net/faac/faac-1.28.zip: 1.28
  * libogg: http://downloads.xiph.org/releases/ogg/libogg-1.1.3.tar.gz
  * libvorbis: http://downloads.xiph.org/releases/vorbis/libvorbis-1.2.0.tar.gz
  * libtheora: http://downloads.xiph.org/releases/theora/libtheora-1.0.tar.bz2

On Windows, here's what we built our installer with:
 * Mingw gcc/g++ 4.2.4: http://www.tdragon.net/recentgcc/
 * Msys 1.0.11
 * mingw-runtime 3.15.1
 * w32api 3.13
 * gmake 3.81
 * binutils 2.91
 * yasm 0.7.2.2153
 * Msys Perl 5.6
 * Ant 1.7
 * Java JDK 1.5
 * MSFT C++ Visual Studio 2008
 * NullSoft NSIS Installer  2.42
 * Subversion 1.5