com.xuggle.mediatool
Interface IMediaReader

Package class diagram package IMediaReader
All Superinterfaces:
IMediaCoder, IMediaGenerator

public interface IMediaReader
extends IMediaCoder

An IMediaCoder that reads and decodes media from an IContainer.

An IMediaReader opens up a media container, reads packets from it, decodes the data, and then dispatches information about the data to any registered IMediaListener objects. The main method of interest is readPacket().

Here's an example of a very simple program that prints out a line when the IMediaReader decides to open a container.

  IMediaDebugListener myListener = new MediaListenerAdapter(){
    public void onOpen(IMediaGenerator pipe) {
      System.out.println("opened: " + ((IMediaReader)pipe).getUrl());
    }
  };
  IMediaReader reader = ToolFactory.makeReader("myinputfile.flv");
  reader.addListener(myListener);
  while(reader.readPacket() == null)
    ;
  

And here's a slightly more involved example where we read a file and display it on screen in real-time:

  IMediaReader reader = ToolFactory.makeReader("myinputfile.flv");
  reader.addListener(ToolFactory.makeViewer());
  while(reader.readPacket() == null)
    ;
  

For examples of this class in action, see the com.xuggle.mediatool.demos package.


Method Summary
 boolean canAddDynamicStreams()
          Report if the underlying media container supports adding dynamic streams.
 void close()
          Close this IMediaCoder.
 int getBufferedImageTypeToGenerate()
          Get the BufferedImage type this IMediaReader will generate.
 IContainer getContainer()
          Get the underlying media IContainer that the IMediaCoder is reading from or writing to.
 String getUrl()
          The URL from which the IContainer is being read or written to.
 void open()
          Open this IMediaCoder.
 IError readPacket()
          Decodes the next packet and calls all registered IMediaListener objects.
 void setAddDynamicStreams(boolean streamsCanBeAddedDynamically)
          Set if the underlying media container supports adding dynamic streams.
 void setBufferedImageTypeToGenerate(int bufferedImageType)
          Asks the IMediaReader to generate BufferedImage images when calling IMediaListener.onVideoPicture(IVideoPictureEvent) .
 void setCloseOnEofOnly(boolean closeOnEofOnly)
          Should IMediaReader automatically call close(), only if ERROR_EOF is returned from readPacket().
 void setQueryMetaData(boolean queryStreamMetaData)
          Set if the underlying media container will attempt to establish all meta data when the container is opened, which will potentially block until it has ready enough data to find all streams in a container.
 boolean willCloseOnEofOnly()
          Report if close will called only if ERROR_EOF is returned from readPacket().
 boolean willQueryMetaData()
          Report if the underlying media container will attempt to establish all meta data when the container is opened, which will potentially block until it has ready enough data to find all streams in a container.
 
Methods inherited from interface com.xuggle.mediatool.IMediaCoder
isOpen
 
Methods inherited from interface com.xuggle.mediatool.IMediaGenerator
addListener, getListeners, removeListener
 

Method Detail

setAddDynamicStreams

void setAddDynamicStreams(boolean streamsCanBeAddedDynamically)
Set if the underlying media container supports adding dynamic streams. See IContainer.open(String, IContainer.Type, IContainerFormat, boolean, boolean) . The default value for this is false.

If set to false, the IMediaReader can assume no new streams will be added after open() has been called, and may decide to query the entire media file to find all meta data. If true then IMediaReader will not read ahead; instead it will only query meta data for a stream when a readPacket() returns the first packet in a new stream. Note that a IMediaWriter can only initialize itself from a IMediaReader that has this parameter set to false.

To have an effect, the MediaReader must not have been created with an already open IContainer, and this method must be called before the first call to readPacket().

Parameters:
streamsCanBeAddedDynamically - true if new streams may appear at any time during a readPacket() call
Throws:
RuntimeException - if the media container is already open

canAddDynamicStreams

boolean canAddDynamicStreams()
Report if the underlying media container supports adding dynamic streams. See IContainer.open(String, IContainer.Type, IContainerFormat, boolean, boolean).

Returns:
true if new streams can may appear at any time during a readPacket() call
See Also:
setAddDynamicStreams(boolean)

setQueryMetaData

void setQueryMetaData(boolean queryStreamMetaData)
Set if the underlying media container will attempt to establish all meta data when the container is opened, which will potentially block until it has ready enough data to find all streams in a container. If false, it will only block to read a minimal header for this container format. See IContainer.open(String, IContainer.Type, IContainerFormat, boolean, boolean). The default value for this is true.

To have an effect, the MediaReader must not have been created with an already open IContainer, and this method must be called before the first call to readPacket().

Parameters:
queryStreamMetaData - true if meta data is to be queried
Throws:
RuntimeException - if the media container is already open

willQueryMetaData

boolean willQueryMetaData()
Report if the underlying media container will attempt to establish all meta data when the container is opened, which will potentially block until it has ready enough data to find all streams in a container. If false, it will only block to read a minimal header for this container format. See IContainer.open(String, IContainer.Type, IContainerFormat, boolean, boolean).

Returns:
true meta data will be queried
See Also:
setQueryMetaData(boolean)

setCloseOnEofOnly

void setCloseOnEofOnly(boolean closeOnEofOnly)
Should IMediaReader automatically call close(), only if ERROR_EOF is returned from readPacket(). Otherwise close() is automatically called when any error value is returned. The default value for this is false.

Parameters:
closeOnEofOnly - true if meta data is to be queried
Throws:
RuntimeException - if the media container is already open

willCloseOnEofOnly

boolean willCloseOnEofOnly()
Report if close will called only if ERROR_EOF is returned from readPacket(). Otherwise close is called when any error value is returned. The default value for this is false.

Returns:
true if will close on ERROR_EOF only
See Also:
setCloseOnEofOnly(boolean)

readPacket

IError readPacket()
Decodes the next packet and calls all registered IMediaListener objects.

If a complete IVideoPicture or IAudioSamples set are decoded, it will be dispatched to the listeners added to the media reader.

This method will automatically call open() if it has not already been called, and will automatically call close() when it reads an error or end of file from the file. The default close behavior can be changed with setCloseOnEofOnly(boolean).

Returns:
null if there are more packets to read, otherwise return an IError instance. If IError.getType() == IError.Type.ERROR_EOF then end of file has been reached.

setBufferedImageTypeToGenerate

void setBufferedImageTypeToGenerate(int bufferedImageType)
Asks the IMediaReader to generate BufferedImage images when calling IMediaListener.onVideoPicture(IVideoPictureEvent) .

NOTE: Only BufferedImage.TYPE_3BYTE_BGR is supported today.

If set to a non-negative value, IMediaReader will resample any video data it has decoded into the right colorspace for the BufferedImage, and generate a new BufferedImage to pass in on each IMediaListener.onVideoPicture(IVideoPictureEvent) call.

Parameters:
bufferedImageType - The buffered image type (e.g. BufferedImage.TYPE_3BYTE_BGR) you want IMediaReader to generate. Set to -1 to disable this feature.
See Also:
BufferedImage

getBufferedImageTypeToGenerate

int getBufferedImageTypeToGenerate()
Get the BufferedImage type this IMediaReader will generate.

Returns:
the type, or -1 if disabled.
See Also:
getBufferedImageTypeToGenerate()

getContainer

IContainer getContainer()
Get the underlying media IContainer that the IMediaCoder is reading from or writing to. The returned IContainer can be further interrogated for media stream details.

Specified by:
getContainer in interface IMediaCoder
Returns:
the media container.

getUrl

String getUrl()
The URL from which the IContainer is being read or written to.

Specified by:
getUrl in interface IMediaCoder
Returns:
the source or destination URL.

open

void open()
Open this IMediaCoder. This will open the internal IContainer. Typically the tool will open itself at the right time, but there may exist rare cases where the calling context may need to open the tool.

Specified by:
open in interface IMediaCoder

close

void close()
Close this IMediaCoder. This will close all IStreamCoders explicitly opened by tool, then close the internal IContainer, again only if it was explicitly opened by tool.

Typically the tool will close itself at the right time, but there are instances where the calling context may need to close the tool.

Specified by:
close in interface IMediaCoder


Copyright © 2008, 2010 Xuggle