Package com.avpkit.core

Class IContainer

  • All Implemented Interfaces:
    IConfigurable
    public class IContainer
extends RefCounted
implements IConfigurable
    A file (or network data source) that contains one or more {IStream}
    objects of
    audio and video data.


    Typical usage for reading looks like this:


    
 IContainer container = IContainer.make();
    
 
    
 if (container.open("myfile.flv", IContainer.Type.READ, null) <0)
    
   throw new RuntimeException("failed to open");
    
 
    
 int numStreams = container.getNumStreams();
    
 for(i = 0; i < numStreams; i++) {
    
   IStream stream = container.getStream(i);
    
   ...query IStream for stream information...
    
 }
    
 
    
 IPacket packet = IPacket.make();
    
 while(container.readNextPacket(packet) >= 0)
    
 {
    
     ... Do something with the packet...
    
 }
    
 container.close();


    Typical usage for writing looks like this (makes an FLV file
    with one audio track encoded as mp3 data):



    
 IContainer container = IContainer.make();
    
 
    
 if (container.open("myfile.flv", IContainer.Type.WRITE, null) <0)
    
   throw new RuntimeException("failed to open");
    
 
    
 IStream stream = container.addNewStream(0);
    
 
    
 IStreamCoder coder = stream.getStreamCoder();
    
 
    
 coder.setCodec(ICodec.ID.AV_CODEC_ID_MP3);
    
 coder.setSampleRate(22050);
    
 coder.setChannels(2);
    
 coder.setBitRate(64000);
    
 
    
 if (coder.open()<0) throw new RuntimeException("could not open coder");
    
 
    
 if (container.writeHeader() < 0) throw new RuntimeException();
    
 
    
 IPacket packet = IPacket.make();
    
 
    
 while( ... have more data to process ... ) {
    
   ... Use the coder to encode audio data into packets
    
   then assuming it generated an IPacket for you...
    
   if (container.writePacket(packet)<0)
    
     throw new RuntimeException("could not write packet");
    
 }
    
 
    
 if (container.writeTrailer() <0) throw new RuntimeException();
    
 
    
 container.close();

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  IContainer.Flags  
      static class  IContainer.Type
      The different types of Containers AVPKit supports.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected IContainer​(long cPtr, boolean cMemoryOwn)
      Internal Only.
      protected IContainer​(long cPtr, boolean cMemoryOwn, java.util.concurrent.atomic.AtomicLong ref)
      Internal Only.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      IStream addNewStream​(int id)
      Deprecated.
      Use {#addNewStream(ICodec.ID)} instead.

      Creates a new stream in this container and returns it.
      IStream addNewStream​(ICodec codec)
      Add a new stream that will use the given codec.
      IStream addNewStream​(ICodec.ID id)
      Add a new stream that will use the given codec.
      IStream addNewStream​(IStreamCoder coder)
      Add a new stream that will use the given StreamCoder.
      boolean canStreamsBeAddedDynamically()
      Can streams be added dynamically to this container?
      int close()
      Close the container.
      int close​(boolean dangling)
      Close the container.
      IContainer copyReference()
      Create a new IContainer object that is actually referring to the exact same underlying native object.
      java.lang.String createSDPData()
      Gets the SDP data as a Java string.
      int createSDPData​(IBuffer buffer)
      Fills the given buffer with a null-terminated ASCII
      set of bytes representing SDP data that
      is suitable for use with an RTSP-based system.
      boolean equals​(java.lang.Object obj)
      Compares two values, returning true if the underlying objects in native code are the same object.
      int flushPackets()
      Flush all packets to output.
      int getBitRate()
      Get the calculated overall bit rate of this file.
      IContainerFormat getContainerFormat()
      Returns the IContainerFormat object being used for this IContainer,
      or null if the {IContainer} doesn't yet know.
      static long getCPtr​(IContainer obj)
      Internal Only.
      long getDuration()
      Gets the duration, if known, of this container.

      This will only work for non-streamable containers where IContainer
      can calculate the container size.
      long getFileSize()
      Get the file size in bytes of this container.

      This will only return a valid value if the container is non-streamed and supports seek.
      boolean getFlag​(IContainer.Flags flag)
      Get the setting for the specified flag
      int getFlags()
      Get the flags associated with this object.
      IContainerFormat getFormat()
      Get the {IContainerFormat} that is used by this {IContainer}.
      int getInputBufferLength()
      Return the input buffer length.
      int getMaxDelay()
      Gets the AVFormatContext.max_delay property if possible.
      IMetaData getMetaData()
      Get the {IMetaData} for this object,
      or null if none.
      long getMyCPtr()
      Internal Only.
      int getNumProperties()
      Returns the total number of settable properties on this object
      int getNumStreams()
      The number of streams in this container.
      int getPreload()
      Deprecated.
      use {#getPropertyAsLong} instead.
      The amount container will attemtp to preload.
      boolean getPropertyAsBoolean​(java.lang.String name)
      Gets the value of this property, and returns as a boolean
      double getPropertyAsDouble​(java.lang.String name)
      Gets the value of this property, and returns as a double;
      long getPropertyAsLong​(java.lang.String name)
      Gets the value of this property, and returns as an long;
      IRational getPropertyAsRational​(java.lang.String name)
      Gets the value of this property, and returns as an IRational;
      java.lang.String getPropertyAsString​(java.lang.String name)
      Gets a property on this Object.
      IProperty getPropertyMetaData​(int propertyNo)
      Returns the name of the numbered property.
      IProperty getPropertyMetaData​(java.lang.String name)
      Returns the name of the numbered property.
      java.util.Collection<java.lang.String> getPropertyNames()
      Gets a collection of all properties settable on this object.
      int getReadRetryCount()
      Get the number of times {IContainer#readNextPacket(IPacket)}
      will retry a read if it gets a {IError.Type#ERROR_AGAIN}
      value back.

      Defaults to 1 times.
      IStreamCoder.CodecStandardsCompliance getStandardsCompliance()
      Gets the current level of standards compliance.
      long getStartTime()
      Get the starting timestamp in microseconds of the first packet of the earliest stream in this container.
      IStream getStream​(int streamIndex)
      Get the stream at the given position.
      IContainer.Type getType()
      Find out the type of this container.
      java.lang.String getURL()
      Get the URL the IContainer was opened with.
      May return null if unknown.
      int hashCode()
      Get a hashable value for this object.
      boolean isHeaderWritten()
      Has a header been successfully written?
      boolean isOpened()
      Is this container opened?
      static IContainer make()
      Create a new container object.
      static IContainer make​(IContainerFormat format)
      Create a new {IContainer} and call {#setFormat(IContainerFormat)} on it immediately.
      int open​(IURLProtocolHandler handler, IContainer.Type type, IContainerFormat format)
      Open this container and make it ready for reading or writing.
      int open​(IURLProtocolHandler handler, IContainer.Type type, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
      Open this container and make it ready for reading or writing, optionally reading as far into the container as necessary to find all streams.
      int open​(java.io.DataInput input, IContainerFormat format)
      Open this container and make it ready for reading.
      int open​(java.io.DataInput input, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
      Open this container and make it ready for reading.
      int open​(java.io.DataInputStream input, IContainerFormat format)
      Open this container and make it ready for reading.
      int open​(java.io.DataInputStream input, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
      Open this container and make it ready for reading.
      int open​(java.io.DataOutput output, IContainerFormat format)
      Open this container and make it ready for writing.
      int open​(java.io.DataOutput output, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
      Open this container and make it ready for writing.
      int open​(java.io.DataOutputStream output, IContainerFormat format)
      Open this container and make it ready for writing.
      int open​(java.io.DataOutputStream output, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
      Open this container and make it ready for writing.
      int open​(java.io.InputStream input, IContainerFormat format)
      Open this container and make it ready for reading.
      int open​(java.io.InputStream input, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
      Open this container and make it ready for reading.
      int open​(java.io.OutputStream output, IContainerFormat format)
      Open this container and make it ready for writing.
      int open​(java.io.OutputStream output, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
      Open this container and make it ready for writing.
      int open​(java.io.RandomAccessFile file, IContainer.Type type, IContainerFormat format)
      Open this container and make it ready for reading or writing.
      int open​(java.io.RandomAccessFile file, IContainer.Type type, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
      Open this container and make it ready for reading or writing.
      int open​(java.lang.String url, IContainer.Type type, IContainerFormat pContainerFormat)
      Open this container and make it ready for reading or writing.
      int open​(java.lang.String url, IContainer.Type type, IContainerFormat pContainerFormat, boolean aStreamsCanBeAddedDynamically, boolean aQueryStreamMetaData)
      Open this container and make it ready for reading or writing, optionally
      reading as far into the container as necessary to find all streams.
      int open​(java.lang.String url, IContainer.Type type, IContainerFormat containerFormat, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData, IMetaData options, IMetaData optionsNotSet)
      Open this container and make it ready for reading or writing, optionally
      reading as far into the container as necessary to find all streams.
      int open​(java.nio.channels.ByteChannel channel, IContainer.Type type, IContainerFormat format)
      Open this container and make it ready for reading or writing.
      int open​(java.nio.channels.ByteChannel channel, IContainer.Type type, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
      Open this container and make it ready for reading or writing.
      int open​(java.nio.channels.ReadableByteChannel input, IContainerFormat format)
      Open this container and make it ready for reading.
      int open​(java.nio.channels.ReadableByteChannel input, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
      Open this container and make it ready for reading.
      int open​(java.nio.channels.WritableByteChannel output, IContainerFormat format)
      Open this container and make it ready for writing.
      int open​(java.nio.channels.WritableByteChannel output, IContainerFormat format, boolean streamsCanBeAddedDynamically, boolean queryStreamMetaData)
      Open this container and make it ready for writing.
      int queryStreamMetaData()
      Attempts to read all the meta data in this stream, potentially by reading ahead
      and decoding packets.
      int readNextPacket​(IPacket packet)
      Reads the next packet into the IPacket.
      int seekKeyFrame​(int streamIndex, long timestamp, int flags)
      Seeks to the key frame at (or the first one after) the given timestamp.
      int seekKeyFrame​(int streamIndex, long minTimeStamp, long targetTimeStamp, long maxTimeStamp, int flags)
      EXPERIMENTAL - Seeks to timestamp in the container.
      int setCustomURLHandlerFactory​(IURLProtocolHandlerFactory factory)  
      void setFlag​(IContainer.Flags flag, boolean value)
      Set the flag.
      void setFlags​(int newFlags)
      Set the flags to use with this object.
      int setForcedAudioCodec​(ICodec.ID id)
      Forces the {IContainer} to assume all audio streams are
      encoded with the given audio codec when demuxing.
      int setForcedSubtitleCodec​(ICodec.ID id)
      Forces the {IContainer} to assume all subtitle streams are
      encoded with the given subtitle codec when demuxing.
      int setForcedVideoCodec​(ICodec.ID id)
      Forces the {IContainer} to assume all video streams are
      encoded with the given video codec when demuxing.
      int setFormat​(IContainerFormat format)
      Set the {IContainerFormat} to use with this {IContainer}.
      int setInputBufferLength​(int size)
      Set the buffer length AVPKit will suggest to FFMPEG for reading inputs.

      If called when a IContainer is open, the call is ignored and -1 is returned.
      int setMaxDelay​(int maxdelay)
      Sets the max delay for the AVFormatContext.max_delay property.
      void setMetaData​(IMetaData data)
      Set the {IMetaData} on this object, overriding
      any previous meta data.
      int setPreload​(int preload)
      Deprecated.
      use {#setProperty} instead.

      If the container has not already been opened, sets the AVFormatContext.preload property
      which can be useful in some circumstances such as when dealing with mpeg formats.
      int setProperty​(IMetaData valuesToSet, IMetaData valuesNotFound)
      {
      int setProperty​(java.lang.String name, boolean value)
      Looks up the property 'name' and sets the
      value of the property to 'value'.
      int setProperty​(java.lang.String name, double value)
      Looks up the property 'name' and sets the
      value of the property to 'value'.
      int setProperty​(java.lang.String name, long value)
      Looks up the property 'name' and sets the
      value of the property to 'value'.
      int setProperty​(java.lang.String name, IRational value)
      Looks up the property 'name' and sets the
      value of the property to 'value'.
      int setProperty​(java.lang.String name, java.lang.String value)
      Sets a property on this Object.

      All AVOptions supported by the underlying AVClass are supported.
      void setReadRetryCount​(int count)
      Sets the read retry count.
      int setStandardsCompliance​(IStreamCoder.CodecStandardsCompliance compliance)
      Set the level of standards compliance.
      java.lang.String toString()
      info about this container.
      int writeHeader()
      Adds a header, if needed, for this container.
      int writePacket​(IPacket packet)
      Writes the contents of the packet to the container, but make sure the
      packets are interleaved.
      int writePacket​(IPacket packet, boolean forceInterleave)
      Writes the contents of the packet to the container.
      int writeTrailer()
      Adds a trailer, if needed, for this container.

      Call this AFTER you've written all data you're going to write
      to this container but BEFORE you call
      {IStreamCoder#close()} on your {IStreamCoder}
      objects.

      • Methods inherited from class java.lang.Object

        clone, finalize, getClass, notify, notifyAll, wait, wait, wait

    • Field Detail

      • SEEK_FLAG_BYTE

        public static final int SEEK_FLAG_BYTE
        Flag; Use bytes instead of time stamps for seeking

      • SEEK_FLAG_ANY

        public static final int SEEK_FLAG_ANY
        Flag; Seek to any frame, even non-keyframes

      • SEEK_FLAG_FRAME

        public static final int SEEK_FLAG_FRAME
        Flag; Seek based on frame number instead of time stamps

    • Constructor Detail

      • IContainer

        protected IContainer​(long cPtr,
                     boolean cMemoryOwn)
        Internal Only.

      • IContainer

        protected IContainer​(long cPtr,
                     boolean cMemoryOwn,
                     java.util.concurrent.atomic.AtomicLong ref)
        Internal Only.

    • Method Detail

      • getCPtr

        public static long getCPtr​(IContainer obj)
        Internal Only. Not part of public API. Get the raw value of the native object that obj is proxying for.
        Parameters:
        obj - The java proxy object for a native object.
        Returns:
        The raw pointer obj is proxying for.

      • getMyCPtr

        public long getMyCPtr()
        Internal Only. Not part of public API. Get the raw value of the native object that we're proxying for.
        Overrides:
        getMyCPtr in class RefCounted
        Returns:
        The raw pointer we're proxying for.

      • copyReference

        public IContainer copyReference()
        Create a new IContainer object that is actually referring to the exact same underlying native object.
        Overrides:
        copyReference in class RefCounted
        Returns:
        the new Java object.

      • equals

        public boolean equals​(java.lang.Object obj)
        Compares two values, returning true if the underlying objects in native code are the same object. That means you can have two different Java objects, but when you do a comparison, you'll find out they are the EXACT same object.
        Overrides:
        equals in class java.lang.Object
        Returns:
        True if the underlying native object is the same. False otherwise.

      • hashCode

        public int hashCode()
        Get a hashable value for this object.
        Overrides:
        hashCode in class java.lang.Object
        Returns:
        the hashable value.

      • toString

        public java.lang.String toString()
        info about this container. We only print information that can be determined without reading data from the container.
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string representation of this object

      • setInputBufferLength

        public int setInputBufferLength​(int size)
        Set the buffer length AVPKit will suggest to FFMPEG for reading inputs.

        If called when a IContainer is open, the call is ignored and -1 is returned.

        Parameters:
        size - The suggested buffer size.
        Returns:
        size on success; <0 on error.

      • getInputBufferLength

        public int getInputBufferLength()
        Return the input buffer length.

        Returns:
        The input buffer length AVPKit's told FFMPEG to assume.
        0 means FFMPEG should choose it's own
        size (and it'll probably be 32768).

      • isOpened

        public boolean isOpened()
        Is this container opened?
        Returns:
        true if opened; false if not.

      • isHeaderWritten

        public boolean isHeaderWritten()
        Has a header been successfully written?
        Returns:
        true if yes, false if no.

      • open

        public int open​(java.lang.String url,
                IContainer.Type type,
                IContainerFormat pContainerFormat)
        Open this container and make it ready for reading or writing.


        The caller must call {#close()} when done, but if not, the
        {IContainer} will eventually close
        them later but warn to the logging system.



        This just forwards to {#open(String, Type, IContainerFormat, boolean, boolean)}
        passing false for aStreamsCanBeAddedDynamically, and true for aLookForAllStreams.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        Parameters:
        url - The resource to open; The format of this string is any
        url that FFMPEG supports (including additional protocols if added
        through the core.io library).
        type - The type of this container.
        pContainerFormat - A pointer to a ContainerFormat object specifying
        the format of this container, or 0 (NULL) if you want us to guess.

        Returns:
        >= 0 on success; < 0 on error.

      • open

        public int open​(java.lang.String url,
                IContainer.Type type,
                IContainerFormat pContainerFormat,
                boolean aStreamsCanBeAddedDynamically,
                boolean aQueryStreamMetaData)
        Open this container and make it ready for reading or writing, optionally
        reading as far into the container as necessary to find all streams.

        The caller must call {#close()} when done, but if not, the
        {IContainer} will eventually close
        them later but warn to the logging system.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        Parameters:
        url - The resource to open; The format of this string is any
        url that FFMPEG supports (including additional protocols if added
        through the core.io library).
        type - The type of this container.
        pContainerFormat - A pointer to a ContainerFormat object specifying
        the format of this container, or 0 (NULL) if you want us to guess.
        aStreamsCanBeAddedDynamically - If true, open() will expect that new
        streams can be added at any time, even after the format header has been read.
        aQueryStreamMetaData - If true, open() will call {#queryStreamMetaData()}
        on this container, 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.

        Returns:
        >= 0 on success; < 0 on error.

      • setStandardsCompliance

        public int setStandardsCompliance​(IStreamCoder.CodecStandardsCompliance compliance)
        Set the level of standards compliance. Only paid attention to
        before the code is opened.

        Parameters:
        compliance - The desired compliance level to set
        Returns:
        0 on success; non-zero on failure
        Since:
        5.7
        See Also:
        CodecStandardsCompliance

      • getContainerFormat

        public IContainerFormat getContainerFormat()
        Returns the IContainerFormat object being used for this IContainer,
        or null if the {IContainer} doesn't yet know.

        Returns:
        the IContainerFormat object, or null.

      • close

        public int close​(boolean dangling)
        Close the container. open() must have been called first, or
        else an error is returned.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        If this method exits because of an interruption,
        all resources will be closed anyway.



        Returns:
        >= 0 on success; < 0 on error.

      • close

        public int close()
        Close the container. open() must have been called first, or
        else an error is returned.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        If this method exits because of an interruption,
        all resources will be closed anyway.



        Returns:
        >= 0 on success; < 0 on error.

      • getType

        public IContainer.Type getType()
        Find out the type of this container.

        Returns:
        The Type of this container.
        {IContainer.Type#READ} if not yet opened.

      • getNumStreams

        public int getNumStreams()
        The number of streams in this container.

        If opened in {IContainer.Type#READ} mode, this will query the stream and find out
        how many streams are in it.

        If opened in
        {IContainer.Type#WRITE} mode, this will return the number of streams
        the caller has added to date.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        Returns:
        The number of streams in this container.

      • getStream

        public IStream getStream​(int streamIndex)
        Get the stream at the given position.

        Parameters:
        streamIndex - the index of this stream in the container
        Returns:
        The stream at that position in the container, or null if none there.

      • addNewStream

        @Deprecated
public IStream addNewStream​(int id)
        Deprecated.
        Use {#addNewStream(ICodec.ID)} instead.

        Creates a new stream in this container and returns it.

        Parameters:
        id - A format-dependent id for this stream.

        Returns:
        A new stream.

      • writeHeader

        public int writeHeader()
        Adds a header, if needed, for this container.


        Call this AFTER you've added all streams you want to add,
        opened all IStreamCoders for those streams (with proper
        configuration) and
        before you write the first frame. If you attempt to write
        a header but haven't opened all codecs, this method will log
        a warning, and your output file will likely be corrupt.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        Returns:
        0 if successful. < 0 if not. Always -1 if this is
        a READ container.

      • writeTrailer

        public int writeTrailer()
        Adds a trailer, if needed, for this container.

        Call this AFTER you've written all data you're going to write
        to this container but BEFORE you call
        {IStreamCoder#close()} on your {IStreamCoder}
        objects.


        You must call {#writeHeader()} before you call
        this (and if you don't, the {IContainer}
        will warn loudly and not
        actually write the trailer).



        If you have closed any of the {IStreamCoder} objects
        that were open when you called
        {#writeHeader()}, then this method will fail.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        Returns:
        0 if successful. < 0 if not. Always <0 if this is
        a READ container.

      • readNextPacket

        public int readNextPacket​(IPacket packet)
        Reads the next packet into the IPacket. This method will
        release any buffers currently held by this packet and allocate
        new ones.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        Parameters:
        packet - [In/Out] The packet the IContainer will read into.

        Returns:
        0 if successful, or <0 if not.

      • writePacket

        public int writePacket​(IPacket packet,
                       boolean forceInterleave)
        Writes the contents of the packet to the container.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        Parameters:
        packet - [In] The packet to write out.
        forceInterleave - [In] If true, then this {IContainer} will
        make sure all packets
        are interleaved by DTS (even across streams in a container).
        If false, the {IContainer} won't,
        and it's up to the caller to interleave if necessary.

        Returns:
        # of bytes written if successful, or <0 if not.

      • writePacket

        public int writePacket​(IPacket packet)
        Writes the contents of the packet to the container, but make sure the
        packets are interleaved.


        This means the {IContainer} may have to queue up packets from one
        stream while waiting for packets from another.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.


        Parameters:
        packet - [In] The packet to write out.

        Returns:
        # of bytes written if successful, or <0 if not.

      • make

        public static IContainer make()
        Create a new container object.

        Returns:
        a new container, or null on error.

      • queryStreamMetaData

        public int queryStreamMetaData()
        Attempts to read all the meta data in this stream, potentially by reading ahead
        and decoding packets.


        Any packets this method reads ahead will be cached and correctly returned when you
        read packets, but this method can be non-blocking potentially until end of container
        to get all meta data. Take care when you call it.

        After this method is called, other meta data methods like {#getDuration()} should
        work.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        Returns:
        >= 0 on success; <0 on failure.

      • seekKeyFrame

        public int seekKeyFrame​(int streamIndex,
                        long timestamp,
                        int flags)
        Seeks to the key frame at (or the first one after) the given timestamp. This method will
        always fail for any IContainer that is not seekable (e.g. is streamed). When successful
        the next call to {#readNextPacket(IPacket)} will get the next keyframe from the
        sought for stream.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        WARNING:: This method will be deprecated
        in a future AVPKit release and replaced with the new
        API {#seekKeyFrame(int, long, long, long, int)}.



        Parameters:
        streamIndex - The stream to search for the keyframe in; must be a
        stream the IContainer has either queried
        meta-data about or already ready a packet for.
        timestamp - The timestamp, in the timebase of the stream you're looking in (not necessarily Microseconds).
        flags - Flags to pass to com.avpkit.core.io.IURLProtocolHandler's seek method.

        Returns:
        >= 0 on success; <0 on failure.

      • getDuration

        public long getDuration()
        Gets the duration, if known, of this container.

        This will only work for non-streamable containers where IContainer
        can calculate the container size.

        Returns:
        The duration, or {Global#NO_PTS} if not known.

      • getStartTime

        public long getStartTime()
        Get the starting timestamp in microseconds of the first packet of the earliest stream in this container.


        This will only return value values either either (a) for non-streamable
        containers where IContainer can calculate the container size or
        (b) after IContainer has actually read the
        first packet from a streamable source.



        Returns:
        The starting timestamp in microseconds, or {Global#NO_PTS} if not known.

      • getFileSize

        public long getFileSize()
        Get the file size in bytes of this container.

        This will only return a valid value if the container is non-streamed and supports seek.

        Returns:
        The file size in bytes, or <0 on error.

      • getBitRate

        public int getBitRate()
        Get the calculated overall bit rate of this file.


        This will only return a valid value if the container is non-streamed and supports seek.


        Returns:
        The overall bit rate in bytes per second, or <0 on error.

      • getNumProperties

        public int getNumProperties()
        Returns the total number of settable properties on this object

        Specified by:
        getNumProperties in interface IConfigurable
        Returns:
        total number of options (not including constant definitions)

      • getPropertyMetaData

        public IProperty getPropertyMetaData​(int propertyNo)
        Returns the name of the numbered property.

        Specified by:
        getPropertyMetaData in interface IConfigurable
        Parameters:
        propertyNo - The property number in the options list.

        Returns:
        an IProperty value for this properties meta-data

      • setProperty

        public int setProperty​(java.lang.String name,
                       java.lang.String value)
        Sets a property on this Object.

        All AVOptions supported by the underlying AVClass are supported.

        Specified by:
        setProperty in interface IConfigurable
        Parameters:
        name - The property name. For example "b" for bit-rate.
        value - The value of the property.

        Returns:
        >= 0 if the property was successfully set; <0 on error

      • setProperty

        public int setProperty​(java.lang.String name,
                       double value)
        Looks up the property 'name' and sets the
        value of the property to 'value'.

        Specified by:
        setProperty in interface IConfigurable
        Parameters:
        name - name of option
        value - Value of option

        Returns:
        >= 0 on success; <0 on error.

      • setProperty

        public int setProperty​(java.lang.String name,
                       long value)
        Looks up the property 'name' and sets the
        value of the property to 'value'.

        Specified by:
        setProperty in interface IConfigurable
        Parameters:
        name - name of option
        value - Value of option

        Returns:
        >= 0 on success; <0 on error.

      • setProperty

        public int setProperty​(java.lang.String name,
                       boolean value)
        Looks up the property 'name' and sets the
        value of the property to 'value'.

        Specified by:
        setProperty in interface IConfigurable
        Parameters:
        name - name of option
        value - Value of option

        Returns:
        >= 0 on success; <0 on error.

      • setProperty

        public int setProperty​(java.lang.String name,
                       IRational value)
        Looks up the property 'name' and sets the
        value of the property to 'value'.

        Specified by:
        setProperty in interface IConfigurable
        Parameters:
        name - name of option
        value - Value of option

        Returns:
        >= 0 on success; <0 on error.

      • getPropertyAsString

        public java.lang.String getPropertyAsString​(java.lang.String name)
        Gets a property on this Object.


        Note for C++ callers; you must free the returned array with
        delete[] in order to avoid a memory leak. If you call
        from Java or any other language, you don't need to worry
        about this.



        Specified by:
        getPropertyAsString in interface IConfigurable
        Parameters:
        name - property name

        Returns:
        an string copy of the option value, or null if the option doesn't exist.

      • getPropertyAsDouble

        public double getPropertyAsDouble​(java.lang.String name)
        Gets the value of this property, and returns as a double;

        Specified by:
        getPropertyAsDouble in interface IConfigurable
        Parameters:
        name - name of option

        Returns:
        double value of property, or 0 on error.

      • getPropertyAsLong

        public long getPropertyAsLong​(java.lang.String name)
        Gets the value of this property, and returns as an long;

        Specified by:
        getPropertyAsLong in interface IConfigurable
        Parameters:
        name - name of option

        Returns:
        long value of property, or 0 on error.

      • getPropertyAsBoolean

        public boolean getPropertyAsBoolean​(java.lang.String name)
        Gets the value of this property, and returns as a boolean

        Specified by:
        getPropertyAsBoolean in interface IConfigurable
        Parameters:
        name - name of option

        Returns:
        boolean value of property, or false on error.

      • getFlags

        public int getFlags()
        Get the flags associated with this object.

        Returns:
        The (compacted) value of all flags set.

      • setFlags

        public void setFlags​(int newFlags)
        Set the flags to use with this object. All values
        must be ORed (|) together.

        Parameters:
        newFlags - The new set flags for this codec.
        See Also:
        Flags

      • getFlag

        public boolean getFlag​(IContainer.Flags flag)
        Get the setting for the specified flag

        Parameters:
        flag - The flag you want to find the setting for

        Returns:
        0 for false; non-zero for true

      • setFlag

        public void setFlag​(IContainer.Flags flag,
                    boolean value)
        Set the flag.

        Parameters:
        flag - The flag to set
        value - The value to set it to (true or false)

      • getURL

        public java.lang.String getURL()
        Get the URL the IContainer was opened with.
        May return null if unknown.
        Returns:
        the URL opened, or null.

      • flushPackets

        public int flushPackets()
        Flush all packets to output.


        Will only work on {IContainer.Type#WRITE} containers.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        Returns:
        >= 0 on success; <0 on error

      • getReadRetryCount

        public int getReadRetryCount()
        Get the number of times {IContainer#readNextPacket(IPacket)}
        will retry a read if it gets a {IError.Type#ERROR_AGAIN}
        value back.

        Defaults to 1 times. <0 means it will keep retrying indefinitely.

        Returns:
        the read retry count

      • setReadRetryCount

        public void setReadRetryCount​(int count)
        Sets the read retry count.

        Parameters:
        count - The read retry count. <0 means keep trying.

      • canStreamsBeAddedDynamically

        public boolean canStreamsBeAddedDynamically()
        Can streams be added dynamically to this container?

        Returns:
        true if streams can be added dynamically

      • getMetaData

        public IMetaData getMetaData()
        Get the {IMetaData} for this object,
        or null if none.


        If the {IContainer} or {IStream} object
        that this {IMetaData} came from was opened
        for reading, then changes via {IMetaData#setValue(String, String)}
        will have no effect on the underlying media.



        If the {IContainer} or {IStream} object
        that this {IMetaData} came from was opened
        for writing, then changes via {IMetaData#setValue(String, String)}
        will have no effect after {IContainer#writeHeader()}
        is called.


        Returns:
        the {IMetaData}.

      • setMetaData

        public void setMetaData​(IMetaData data)
        Set the {IMetaData} on this object, overriding
        any previous meta data. You should call this
        method on writable containers and
        before you call {IContainer#writeHeader}, as
        it probably won't do anything after that.

        See Also:
        getMetaData()

      • createSDPData

        public int createSDPData​(IBuffer buffer)
        Fills the given buffer with a null-terminated ASCII
        set of bytes representing SDP data that
        is suitable for use with an RTSP-based system.


        This method only works if AVPKit is linking
        against a version of FFmpeg that supports RTSP.


        Parameters:
        buffer - the {com.avpkit.ferry.IBuffer}
        object to fill with data.
        Returns:
        the number of bytes written, including the
        terminating 0 byte, or < 0 on error.

      • setForcedAudioCodec

        public int setForcedAudioCodec​(ICodec.ID id)
        Forces the {IContainer} to assume all audio streams are
        encoded with the given audio codec when demuxing.
        Parameters:
        id - The codec id
        Returns:
        < 0 on error (e.g. not an audio codec); >= 0 on success.
        Since:
        3.3

      • setForcedVideoCodec

        public int setForcedVideoCodec​(ICodec.ID id)
        Forces the {IContainer} to assume all video streams are
        encoded with the given video codec when demuxing.
        Parameters:
        id - The codec id
        Returns:
        < 0 on error (e.g. not an video codec); >= 0 on success.
        Since:
        3.3

      • setForcedSubtitleCodec

        public int setForcedSubtitleCodec​(ICodec.ID id)
        Forces the {IContainer} to assume all subtitle streams are
        encoded with the given subtitle codec when demuxing.
        Parameters:
        id - The codec id
        Returns:
        < 0 on error (e.g. not an subtitle codec); >= 0 on success.
        Since:
        3.3

      • seekKeyFrame

        public int seekKeyFrame​(int streamIndex,
                        long minTimeStamp,
                        long targetTimeStamp,
                        long maxTimeStamp,
                        int flags)
        EXPERIMENTAL - Seeks to timestamp in the container.


        Seeking will be done so that the point from which all active streams
        can be presented successfully will be closest to
        targetTimeStamp and within
        minTimeStamp/maxTimeStamp        .



        If flags contain {#SEEK_FLAG_BYTE}, then all time stamps are in bytes and
        are the file position (this may not be supported by all demuxers).
        If flags contain {#SEEK_FLAG_FRAME}, then all time stamps are in frames
        in the stream with streamIndex (this may not be supported by all demuxers).
        Otherwise all time stamps are in units of the stream selected by stream_index
        or if stream_index is -1, in microseconds.
        If flags contain {#SEEK_FLAG_ANY}, then non-keyframes are treated as
        keyframes (this may not be supported by all demuxers).
        If flags contain {#SEEK_FLAG_BACKWARDS}, then we will attempt to
        search backwards in the container (this may not be supported by all
        demuxers and file protocols).



        This is part of the new seek API which is still under construction.
        It may change in future AVPKit versions.


        Parameters:
        streamIndex - index of the stream which is used as time base reference
        minTimeStamp - smallest acceptable time stamp.
        targetTimeStamp - target time stamp.
        maxTimeStamp - largest acceptable time stamp.
        flags - A bitmask of the SEEK_FLAG_* flags, or 0 to turn
        all flags off.
        Returns:
        >=0 on success, error code otherwise
        Since:
        3.4

      • setPreload

        @Deprecated
public int setPreload​(int preload)
        Deprecated.
        use {#setProperty} instead.

        If the container has not already been opened, sets the AVFormatContext.preload property
        which can be useful in some circumstances such as when dealing with mpeg formats.

        Parameters:
        preload - amount to preload
        Returns:
        >= 0 on success, error code otherwise
        Since:
        4.0

      • getPreload

        @Deprecated
public int getPreload()
        Deprecated.
        use {#getPropertyAsLong} instead.
        The amount container will attemtp to preload.

        Returns:
        The amount to preload, error code otherwise.

      • setMaxDelay

        public int setMaxDelay​(int maxdelay)
        Sets the max delay for the AVFormatContext.max_delay property.

        Parameters:
        maxdelay - maximum delay for container
        Returns:
        >= 0 on success, error code otherwise
        Since:
        4.0

      • getMaxDelay

        public int getMaxDelay()
        Gets the AVFormatContext.max_delay property if possible.
        Returns:
        The max delay, error code otherwise.
        Since:
        4.0

      • addNewStream

        public IStream addNewStream​(ICodec.ID id)
        Add a new stream that will use the given codec.

        Parameters:
        id - The id for the codec used to insert packets. If you are adding an arbitrary data stream, use {ICodec.ID#AV_CODEC_ID_NONE}, otherwise
        use the ID of the code type you plan to use.

        Returns:
        An {IStream} for the new stream on success, or null on failure.
        Since:
        5.0

      • addNewStream

        public IStream addNewStream​(ICodec codec)
        Add a new stream that will use the given codec.

        Parameters:
        codec - The codec that will be used to insert packets.

        Returns:
        An {IStream} for the new stream on success, or null on failure.
        Since:
        5.0

      • addNewStream

        public IStream addNewStream​(IStreamCoder coder)
        Add a new stream that will use the given StreamCoder. The StreamCoder passed in MUST contain the {IStreamCoder#getExtraData} that
        was used to encode the packet.

        Parameters:
        coder - The {IStreamCoder} that contains the meta-information needed for decoding the packets that will be muexed into this stream.
        Returns:
        An {IStream} for the new stream on success, or null on failure.
        Since:
        5.0

      • setProperty

        public int setProperty​(IMetaData valuesToSet,
                       IMetaData valuesNotFound)
        {
        Specified by:
        setProperty in interface IConfigurable
        Parameters:
        valuesToSet - The set of key-value pairs to try to set
        valuesNotFound - If non null will contain all key-values pairs in valuesToSet that were not found in context.
        Returns:
        0 on success; <0 on failure

      • getFormat

        public IContainerFormat getFormat()
        Get the {IContainerFormat} that is used by this {IContainer}.

        Returns:
        The format, or null if none is set yet.
        Since:
        5.0

      • setFormat

        public int setFormat​(IContainerFormat format)
        Set the {IContainerFormat} to use with this {IContainer}. If called when the
        {IContainer} is opened, or if previously called with a non-null value,
        an error is returned and no action is taken.
        Parameters:
        format - The format to use
        return 0 on success; <0 on failure
        Since:
        5.0

      • make

        public static IContainer make​(IContainerFormat format)
        Create a new {IContainer} and call {#setFormat(IContainerFormat)} on it immediately.
        Parameters:
        format - The format to pass to {#setFormat(IContainerFormat)}
        Returns:
        An {IContainer} on success, or null on failure.
        Since:
        5.0

      • open

        public int open​(java.lang.String url,
                IContainer.Type type,
                IContainerFormat containerFormat,
                boolean streamsCanBeAddedDynamically,
                boolean queryStreamMetaData,
                IMetaData options,
                IMetaData optionsNotSet)
        Open this container and make it ready for reading or writing, optionally
        reading as far into the container as necessary to find all streams.

        The caller must call {#close()} when done, but if not, the
        {IContainer} will eventually close
        them later but warn to the logging system.

        If the current thread is interrupted while this blocking method
        is running the method will return with a negative value.
        To check if the method exited because of an interruption
        pass the return value to {IError#make(int)} and then
        check {IError#getType()} to see if it is
        {IError.Type#ERROR_INTERRUPTED}.



        Parameters:
        url - The resource to open; The format of this string is any
        url that FFMPEG supports (including additional protocols if added
        through the core.io library).
        type - The type of this container.
        containerFormat - A pointer to a ContainerFormat object specifying
        the format of this container, or 0 (NULL) if you want us to guess.
        streamsCanBeAddedDynamically - If true, open() will expect that new
        streams can be added at any time, even after the format header has been read.
        queryStreamMetaData - If true, open() will call {#queryStreamMetaData()}
        on this container, 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.
        options - If not null, a set of key-value pairs that will be set on the container immediately
        the format is determined. Some options cannot be set (especially for input containers) until the
        system has a chance to parse what data is in the file.
        optionsNotSet - If not null, on return this {IMetaData} object will be cleared out, and
        replace with any key/value pairs that were in options but could not be set on this
        {IContainer}.

        Returns:
        >= 0 on success; < 0 on error.
        Since:
        5.0