From Xugglewiki

Installation Questions

This section is for questions and problems related to installing Xuggler.

Why do I need to install a DLL or Shared Library for a Java application?

Xuggler uses the excellent FFmpeg library for decoding and encoding video extremely quickly, and it is only available as a native library. We need to make sure it is available on your system. On top of that, Xuggler adds extra native code to quickly figure out left-out time stamps in audio and video, and to make it safe to access FFmpeg from Java. That's why it needs to be installed.

Can I use Xuggler with Java Webstart or as an Applet?

No, not today. We're interested in approaches to solving this problem, and if you have experience with making native libraries work in webstart (especially ones that have runtime dependencies you can't know in advance) we'd like to hear from you.

What's up with java.lang.UnsatisfiedLinkError?

It means that Java can't find the Xuggler native library. Check the following:

Did you install the Xuggler? If not, follow the instructions here
Is the environment variable XUGGLE_HOME defined and pointing to your Xuggler install directory (usually C:\Program Files\Xuggle on Windows or /usr/local on Linux/Mac)?
If you installed on Windows, did you reboot after you installed?
Does your PATH environment variable include %XUGGLE_HOME%\bin on Windows or $XUGGLE_HOME/bin on Linux/Mac?
Does your PATH environment variable include %XUGGLE_HOME%\lib on Windows?
Does your LD_LIBRARY_PATH environment variable include $XUGGLE_HOME/lib on Linux?
Does your DYLD_LIBRARY_PATH environmentvariable include $XUGGLE_HOME/lib on Mac OS-X?
Are you using a 32-bit Java JVM, but a 64-bit version of Xuggler? Or a 64-bit version of the Java JVM but a 32-bit version of Xuggler? Unfortunately that won't work. You need to make sure that you match the "bitness" of each release. Sorry.

If fixing those problems doesn't resolve the issue, please contact us via the Support options.

How do I set DYLD_LIBRARY_PATH in Eclipse on Mac OS?

Xuggler needs to have the DYLD_LIBRARY_PATH variable set and pointing to the location where Xuggler is installed ($XUGGLE_HOME/lib, or usually /usr/local/xuggler on Mac-OS). However when you launch applications like Eclipse, it doesn't get the environment variables you might have set in your terminal shell.

To work around that, you need to set DYLD_LIBRARY_PATH login-wide on Mac. This article describes how to configure ~/.MacOSX/environment.plist to define environment variables at log in time. Mac OS X .app applications will see environment variables defined in this way. Be sure to log out and log back in to see the changes.

Runtime Questions

I get an "UnsatisfiedLinkError" when I run Xuggler-based Applications

Make sure you have installed Xuggler correctly and your Java process has the correct environment variables set. See the UnsatisfiedLinkError section above.

I get an "UnsatisfiedLinkError" when I run Xuggler-based Applications in Tomcat

Tomcat does not deal well with JNI-based Java libraries in the WEB-INF/lib directory of your application. Instead, you must place the xuggle-xuggler.jar JNI files into $CATALINA_HOME/shared/lib (where it can be accessed by your, and any other installed application). Your Java code that uses Xuggler can still resize in WEB-INF. See this link for background on this issue.

What formats and codecs does Xuggler support

It depends on how you installed it, but to find out for your version run:

java -cp $XUGGLE_HOME/share/java/jars/xuggle-xuggler.jar com.xuggle.xuggler.Configuration

To find out what codecs you can encode into a given container, run the following (Xuggler 3.3 or later), passing in the short name for your container (the below example asks for all codecs Xuggler can put in a FLV file):

java -cp $XUGGLE_HOME/share/java/jars/xuggle-xuggler.jar com.xuggle.xuggler.GetSupportedCodecs flv

What runtime options can I change with Xuggler

Each Xuggler object has a variety of set and get methods for setting properties. See the Xuggler Documentation for details. For example, IContainer.setInputBufferLength(long) lets you set the buffer size Xuggler uses for reading from disk or network.

In addition, there are several dynamic properties that can be set by objects that implement the IConfigurable interface. To get the full set of what options are settable, and what types of values they take run this command:

java -cp $XUGGLE_HOME/share/java/jars/xuggle-xuggler.jar com.xuggle.xuggler.Configuration

And look at the options.

Can Xuggler read from a Network-Based Source?

Yes, but it's a little more complex than reading from a file.

The simple version of IContainer.open(String, Type, IContainerFormat) will always attempt to read meta-data from a media header, and find at least one packet of each stream in the file, before returning. This can be problematic when reading from network-based streams (as you don't want to block).

To change this behaviour, use the IContainer.open(String, Type, IContainerFormat, boolean, boolean) method, passing in "true" for the streamsCanBeAddedDynamically parameter and "false" for the queryStreamMetaData parameter. This instructs Xuggler to assume the number of streams the header of a stream communicates is not guaranteed to be complete (e.g. audio may not have shown up yet), and also tells open not to read through the stream to find a packet for each stream before it returns.

The last correct step here (if you want Xuggler to be able to fill in IStreamCoder settings correctly for you when decoding) is to ask Xuggler to IContainer.queryStreamMetaData() every time you see a packet on a stream you haven't seen before, and to only call IContainer.getStream(int) once you've gotten at least one packet from that stream index.

Provided you passed "true" for streamsCanBeAddedDynamically, IContainer.queryStreamMetaData() will only read the meta-data for packets received so far, and if your new packet hasn't been seen before, will cause Xuggler to set up the IStream and IStreamCoder contexts correctly for the new stream.

 IContainer container = ...
 IContainerFormat format = ...
 IPacket packet = ...
 Map<Integer, IStreamCoder> knownStreams = ...
 
 format.setOutputFormat("flv", null, null);
 container.open("yoururl.flv", Type.READ, format, true, false);
 
 while(container.readNextPacket(packet)>=0)
 {
   if (packet.isComplete()) {
     if (knownStreams.get(packet.getStreamIndex()) == null) {
        container.queryStreamMetaData();
        // stream should now be set up correct
        IStream stream = container.getStream(packet.getStreamIndex());
        knownStreams.put(packet.getStreamIndex(), stream.getStreamCoder());
     }
 
     IStreamCoder coder = knownStreams.get(packet.getStreamIndex());
       
     ... now you can use the stream coder ....
   }
 }

Does Xuggler support RTP

Xuggler uses FFmpeg for audio and video encoding, and FFmpeg has code for reading and writing RTP streams. But we (at Xuggle) have not fully tested this code, and there are messages on the community lists currently that suggest there are problems here. At the moment though, we're not actively working on RTP support, so we're reliant on patches if you want help.

See this link for background on why we're not currently working on RTP.

Building Xuggler From Source Questions

This section is for people who decide to build their own versions of Xuggler.

"ant run-tests" fails on Linux with a compiler error in Ferry.cpp about $self?

This is fixed in the latest Xuggler. Upgrade to 3.1 (or tip of tree).

"ant run-tests" fails on Mac-OS; what's up with that?

There are two common reasons for this:

Apple javac Compiler Bug

Turns out our build system can tickle a bug in Apple's version of Java's JDK (you can also tickle it using the Adobe Flex compiler on Macs), and compiling our test suite has caused some javac crashes on Mac's when *compiling!*.

Xuggler will have compiled fine (and in fact you can install it). It's just the tests that couldn't compile.

As weird as that is, the work around is even weirder. Just make sure you have at least 40 different environment variables defined before you run ant run-tests.

For example:

export VAR1=foo
export VAR2=foo
...
export VAR40=foo
ant run-tests

And no, we have no idea why that works. But it does.

Apple Java 1.5 Doesn't Work with 64-Bit Binaries

By default we build a 64-bit binary on Mac-OSX (works with Java 1.6). It appears to not work with Java 1.5, so to work around that you need to build the 32-bit version of Xuggler. Here's how:

 ant clobber
 ant -Dbuild.m64=no run-tests

How do you build the Windows Xuggler installer?

Ensure that NSIS is installed on your system, and then build Xuggler with 'ant dist'. The installer will show up in dist/bin.

Missing Feature Questions

This section is for commonly asked for "missing" features.

Why isn't XYZ feature of FFMPEG exposed in Xuggler

Frankly, because we didn't need it initially. That said, we love to expose more features, so if you need something, please ask. No guarantees we'll have time to add it, but we'll try.

To help us, please let us know what the feature is, why you need it, how you'd use it, and any thoughts/opinions you have on the best way to expose it.

Licensing Questions

If you have licensing questions, see our licensing section.

Useless Questions

There are no useless questions, although these come close:

What does "Xuggle" mean?

To freely encode, decode, and experience audio and video.

Why do you call the company "Xuggle"?

Why not? More specifically, our Xuggler software was born because we needed something that could "throw around" video inside our software and do cool stuff with it. We came to call this "juggling video" internally, and originally could only do this with C++ software. We added Java later, and suddenly we could "juggle video" in other languages (Java, C++, and some day any ("X") language you like). And with that, we came to call it "Xuggling".

Frequently Asked Questions