Package com.avpkit.mediatool

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.avpkit.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.avpkit.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.