Package com.xuggle.mediatool

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

See:
Description

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.

Examples

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("output.mov", reader));
 while (reader.readPacket() == null)
   ;
 

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

Tutorials

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());
 reader.setBufferedImageTypeToGenerate(BufferedImage.TYPE_3BYTE_BGR);
 
 // 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
 
 reader.addListener(addTimeStamp);
 addTimeStamp.addListener(reduceVolume);
 reduceVolume.addListener(writer);
 
 // add a viewer to the writer, to see the modified media
 
 writer.addListener(ToolFactory.makeViewer(AUDIO_VIDEO));
 
 // 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:

• All interfaces begin with the letter "I". For example: IMediaListener.
• All abstract classes begin with the latter "A". For example: AMediaListenerMixin.
• Event interfaces and classes can be found in com.xuggle.mediatool.event and end with "Event;". For example: AddStreamEvent.
• Mixin classes will implement all methods suggested by their name, but will not declare the corresponding interface. For example: AMediaListenerMixin.
• Adapter classes will provide an implementation of all methods suggested by their name, and also will declare the corresponding interface. For example: MediaListenerAdapter.