Package com.xuggle.mediatool

Package class diagram package com.xuggle.mediatool
A simple API for to decoding, viewing and encoding media: tutorial here; start with ToolFactory.


Interface Summary
IMediaCoder An IMediaGenerator that manages reading or writing to an IContainer.
IMediaDebugListener An IMediaListener that logs counts of different events to a log file.
IMediaGenerator Generates events that IMediaListener objects can subscribe to and react to.
IMediaListener Called by IMediaGenerator in response to defined events.
IMediaReader An IMediaCoder that reads and decodes media from an IContainer.
IMediaTool An IMediaGenerator that does work in reaction to other IMediaGenerator objects.
IMediaViewer EXPERIMENTAL ONLY: An IMediaListener that plays audio, video or both, while listening to a IMediaGenerator that produces raw media.
IMediaWriter An IMediaCoder that encodes and decodes media to an IContainer, and can optionally read data for encoding from other IMediaGenerator objects.

Class Summary
AMediaCoderMixin An abstract implementation of all IMediaCoder methods, but does not declare IMediaCoder.
AMediaGeneratorMixin An abstract implementation of all IMediaGenerator methods, but does not declare IMediaGenerator.
AMediaListenerMixin An abstract empty implementation of all IMediaListener methods, but does not declare IMediaListener.
AMediaToolMixin An abstract implementation of all IMediaTool methods, but does not declare IMediaTool.
MediaGeneratorAdapter An implementation of IMediaGenerator.
MediaListenerAdapter An implementation of IMediaListener that implements all methods as empty methods.
MediaToolAdapter An implementation of IMediaTool that forwards all IMediaListener events to listeners registered with MediaToolAdapter.addListener(IMediaListener).
ToolFactory Start Here -- A Factory for MediaTools, and global settings for the API.

Enum Summary
IMediaDebugListener.Event The different type of events you'd like to print data for.
IMediaDebugListener.Mode How much detail on each event you want to log.
IMediaViewer.Mode The mode you want to view media in.

Package com.xuggle.mediatool Description

A simple API for to decoding, viewing and encoding media: tutorial here; start with ToolFactory.


The following code snippet is all that is required to decode a FLV file and encode it as a Quicktime file.

 IMediaReader reader = ToolFactory.makeReader("input.flv");
 reader.addListener(ToolFactory.makeWriter("", reader));
 while (reader.readPacket() == null)

For more examples of using the mediatools see the com.xuggle.mediatool.demos demonstration package.


Using MediaTool to Decode & Encode

Using MediaTool to Change & Create Media

Text Version of Tutorials

Check out the MediaTool Tutorial on our Wiki site.

How To Use

To create IMediaReader, IMediaWriter, IMediaViewer or IMediaDebugListener objects, see the ToolFactory class.

The IMediaReader and IMediaWriter objects are the workhorses of this package. They read and write to IContainer objects, but hide the the complexity of encoding and decoding audio. Instead, they generate events that they notify intertested IMediaListener objects about. Interested IMediaListener objects are registered through the IMediaGenerator interface, which both IMediaReader and IMediaWriter extend.

IMediaCoder objects (which both IMediaReader and IMediaWriter are) will make intelligent guesses about the parameters to decode and encode with based on the URLs or file names you create the objects with, but you can change and override everything if you want. To do that use the IMediaCoder.getContainer() interface to get the underlying IContainer object where they can then query all other information. If your code is executing inside a IMediaListener method, you can get the object that generated that event by calling IEvent.getSource() of an IMediaListener event, and from there you can query the IContainer if needed.

An IMediaViewer object is an experimental interface that can be added to a IMediaGenerator to display audio and video data that the IMediaReader is generating in real time. This Tool is currently alpha and pretty buggy, but can be helpful for debugging video.

An IMediaDebugListener object can be attached to IMediaGenerator objects and will log the events they generate to a log file. See the logback logging project for information on how to logback.

Lastly if you want to provide your own implementations of any of the interfaces in this package, a series of Adaptors and Mixin classes are provided.

Adapter classes are used when you want to implement one of the interfaces, but want a lot of the implementation provided for you. For example, MediaListenerAdapter provides an implementation of IMediaListener with all methods implemented as empty (no-op) methods. This means you can create your own IMediaListener objects that only override some methods.

Mixin classes are similar to Adapter classes, but do not declare the interfaces they implement formally. In this way they can be included in-sub-classes without forcing the sub-class to declare they implement a method. For example, the AMediaToolMixin class can be useful to help implement IMediaReader (and in fact, we use it for exactly that internally).

How To Make a Media Pipeline

Sometimes it can be useful to chain together a series of objects to filter media and provide lots of effects. See the ModifyAudioAndVideo demo for an example of that, but here's the basic structure of the code to make a pipeline:

 IMediaReader reader = ToolFactory.makeReader(inputFile.toString());
 // create a writer and configure it's parameters from the reader
 IMediaWriter writer = ToolFactory.makeWriter(outputFile.toString(), reader);
 // create a tool which paints a time stamp onto the video
 IMediaTool addTimeStamp = new TimeStampTool();
 // create a tool which reduces audio volume to 1/10th original
 IMediaTool reduceVolume = new VolumeAdjustTool(0.1);
 // create a tool chain:
 //   reader -> addTimeStamp -> reduceVolume -> writer
 // add a viewer to the writer, to see the modified media
 // read and decode packets from the source file and
 // then encode and write out data to the output file
 while (reader.readPacket() == null)

Package Use Conventions

When using this package you should be aware of the following code conventions:

Copyright © 2008, 2010 Xuggle