Package com.avpkit.core

Class IStreamCoder

  • All Implemented Interfaces:
    IConfigurable
    public class IStreamCoder
extends RefCounted
implements IConfigurable
    The work horse of the AVPKit: Takes {IPacket} data from an {IContainer}
    (representing an {IStream}) and an {ICodec} and allows you to decode or encode
    that data.

    • Nested Class Summary

      Nested Classes 
      Modifier and Type Class Description
      static class  IStreamCoder.CodecStandardsCompliance
      An enumeration of how strictly Codecs may follow the spec.
      Not all settings follow these requirements, but some
      experimental codecs require this flag to be set to use.
      static class  IStreamCoder.Direction
      The Direction in which this StreamCoder will work.
      static class  IStreamCoder.Flags
      AVPKIT Flags that can be passed to the setFlag(Flags, bool) method

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected IStreamCoder​(long cPtr, boolean cMemoryOwn)
      Internal Only.
      protected IStreamCoder​(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
      int close()
      Close a Codec that was opened on this StreamCoder.
      IStreamCoder copyReference()
      Create a new IStreamCoder object that is actually referring to the exact same underlying native object.
      int decodeAudio​(IAudioSamples pOutSamples, IPacket packet, int byteOffset)
      Decode this packet into pOutSamples.
      int decodeVideo​(IVideoPicture pOutFrame, IPacket packet, int byteOffset)
      Decode this packet into pOutFrame.

      The caller is responsible for allocating the
      IVideoPicture object.
      int encodeAudio​(IPacket pOutPacket, IAudioSamples pSamples, int sampleToStartFrom)
      Encode the given samples using this StreamCoder.

      The VideoPicture will allocate a buffer to use internally for this, and
      will free it when the frame destroys itself.

      Callers should call this repeatedly on a set of samples until
      we consume all the samples.

      Also, when done in order to flush the encoder, caller should call
      this method passing in 0 (null) for pSamples to tell the encoder
      to flush any data it was keeping a hold of.
      int encodeVideo​(IPacket pOutPacket, IVideoPicture pFrame, int suggestedBufferSize)
      Encode the given frame using this StreamCoder.

      The VideoPicture will allocate a buffer to use internally for this, and
      will free it when the frame destroys itself.

      Also, when done in order to flush the encoder, caller should call
      this method passing in 0 (null) for pFrame to tell the encoder
      to flush any data it was keeping a hold of.
      boolean equals​(java.lang.Object obj)
      Compares two values, returning true if the underlying objects in native code are the same object.
      int getAudioFrameSize()
      For this stream, get the number of audio samples that are
      represented in a packet of information.
      boolean getAutomaticallyStampPacketsForStream()
      Does this {IStreamCoder} automatically adjust
      time stamps on output packets for the {IStream} it
      is ultimately destined for.
      int getBitRate()
      The bit rate.
      int getBitRateTolerance()
      The bit rate tolerance
      int getChannels()
      Get the number of channels in this audio stream
      ICodec getCodec()
      The Codec this StreamCoder will use.
      ICodec.ID getCodecID()
      A short hand for getCodec().getID().
      int getCodecTag()
      Returns the 4-byte FOURCC tag (Least Significant Byte first).

      This is really a packed 4-byte array so it's only useful if you use
      bit-wise operations on it.
      char[] getCodecTagArray()
      Returns the fourcc tag, in order of least significant byte to most significant byte.
      ICodec.Type getCodecType()
      A short hand for getCodec().getType().
      static long getCPtr​(IStreamCoder obj)
      Internal Only.
      int getDefaultAudioFrameSize()
      Get the default audio frame size (in samples).

      Some codecs, especially raw codecs, like PCM, don't have
      a standard frame size.
      IStreamCoder.Direction getDirection()
      Get the direction.
      IBuffer getExtraData()
      Returns a read-only copy of the extra data in this stream coder as a new IBuffer.
      int getExtraData​(IBuffer dest, int offset, int maxBytesToCopy)
      Copies the current content of the extra-data buffer maintained by this codec (e.g.
      int getExtraDataSize()
      Gets the current number of bytes of data maintained in the coder extra-data area.
      boolean getFlag​(IStreamCoder.Flags flag)
      Get the setting for the specified flag
      int getFlags()
      Get the flags associated with this codec.
      IRational getFrameRate()
      Get the frame-rate the attached stream claims to be using when
      DECODING, or the frame-rate we'll claim we're using when ENCODING.
      int getGlobalQuality()
      Get the Global Quality setting this codec uses for video if
      a VideoPicture doesn't have a quality set.
      int getHeight()
      The height, in pixels.
      long getMyCPtr()
      Internal Only.
      long getNextPredictedPts()
      For this stream, get the next Pts that we expect to decode.

      Note that this may not actually be the next Pts (for example
      due to transmission packet drops in the input source).
      long getNumDroppedFrames()
      Get the number of frames this StreamCoder had to drop to
      encode at the specified {#getTimeBase()}
      int getNumPicturesInGroupOfPictures()
      The the number of pictures in this Group of Pictures (GOP).
      int getNumProperties()
      Returns the total number of settable properties on this object
      IPixelFormat.Type getPixelType()
      For Video streams, get the Pixel Format in use by the stream.
      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.

      Note for C++ callers; you must free the returned array with
      delete[] in order to avoid a memory leak.
      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.
      IAudioSamples.Format getSampleFormat()
      Get the audio sample format.
      int getSampleRate()
      Get the sample rate we use for this stream.
      IStreamCoder.CodecStandardsCompliance getStandardsCompliance()
      Gets the current level of standards compliance.
      IStream getStream()
      The associated Stream we're working on.
      IRational getTimeBase()
      Get the time base this stream will ENCODE in, or the time base we
      detect while DECODING.

      Caller must call release() on the returned value.
      int getWidth()
      The width, in pixels.
      int hashCode()
      Get a hashable value for this object.
      boolean isOpen()
      Returns true if this IStreamCoder is currently open.
      static IStreamCoder make​(IStreamCoder.Direction direction)
      Deprecated.
      Use {#make(Direction, ICodec)} instead.
      Create a standalone StreamCoder that can decode data without regard to
      which IStream or IContainer it came from.
      static IStreamCoder make​(IStreamCoder.Direction direction, ICodec codec)
      Create a standalone StreamCoder that can encode or decode data independent
      of the stream it is attached to.
      static IStreamCoder make​(IStreamCoder.Direction direction, ICodec.ID id)
      Create a standalone StreamCoder that can encode or decode data independent
      of the stream it is attached to.
      static IStreamCoder make​(IStreamCoder.Direction direction, IStreamCoder copyCoder)
      Creates a new IStreamCoder object by copying all the settings in copyCoder.
      int open()
      Deprecated.
      Use {#open(IMetaData,IMetaData)} instead.
      Open the Codec associated with this StreamCoder.

      You can get the codec through getCodec(...) and
      set it with setCodec(...).
      int open​(IMetaData options, IMetaData unsetOptions)
      Open the codec with the given options.

      Callers must call {#setCodec} before calling this method.
      void setAutomaticallyStampPacketsForStream​(boolean value)
      Should the {IStreamCoder} automatically adjust
      time stamps on output packets for the {IStream}
      it is ultimately destined for.
      void setBitRate​(int rate)
      When ENCODING, sets the bit rate to use.
      void setBitRateTolerance​(int tolerance)
      When ENCODING set the bit rate tolerance.
      void setChannels​(int channels)
      Set the number of channels to use when ENCODING.
      void setCodec​(ICodec codec)
      Set the Codec to the passed in Codec, discarding the old
      Codec if set.
      void setCodec​(ICodec.ID id)
      Look up a Codec based on the passed in ID, and then set it.
      void setCodecID​(ICodec.ID id)
      Look up a Codec based on the passed in ID, and then set it.
      void setCodecTag​(char[] fourcc)
      Set the fourcc tag.
      void setCodecTag​(int fourcc)
      Set the 4-byte FOURCC tag for this coder.
      void setDefaultAudioFrameSize​(int aNewSize)
      Set the default audio frame size.
      int setExtraData​(IBuffer src, int offset, int length, boolean allocNew)
      Copies data from the given buffer into the extra-data area maintained
      by encoders.
      void setFlag​(IStreamCoder.Flags flag, boolean value)
      Set the flag.
      void setFlags​(int newFlags)
      Set the FFMPEG flags to use with this codec.
      void setFrameRate​(IRational newFrameRate)
      Set the frame rate we'll set in the headers of this stream while
      ENCODING.
      void setGlobalQuality​(int newQuality)
      Set the Global Quality to a new value.
      int setHardwareDecoding​(IPixelFormat.Type type)
      Try to change current decoder to an HW decoder compatible with
      pixel format
      void setHeight​(int height)
      Set the height, in pixels.
      void setNumPicturesInGroupOfPictures​(int gops)
      Set the GOPS on this stream.
      void setPixelType​(IPixelFormat.Type pixelFmt)
      Set the pixel format to ENCODE with.
      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 setSampleFormat​(IAudioSamples.Format aFormat)
      Set the sample format when ENCODING.
      void setSampleRate​(int sampleRate)
      Set the sample rate to use when ENCODING.
      int setStandardsCompliance​(IStreamCoder.CodecStandardsCompliance compliance)
      Set the level of standards compliance.
      void setTimeBase​(IRational newTimeBase)
      Set the time base we'll use to ENCODE with.
      void setWidth​(int width)
      Set the width, in pixels
      java.lang.String toString()
      Prints details on this IStreamCoder

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • IStreamCoder

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

      • IStreamCoder

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

    • Method Detail

      • getCPtr

        public static long getCPtr​(IStreamCoder 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.

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

      • getCodecTagArray

        public char[] getCodecTagArray()
        Returns the fourcc tag, in order of least significant byte to most significant byte.
        Returns:
        a 4 char array of the fourcc

      • setCodecTag

        public void setCodecTag​(char[] fourcc)
        Set the fourcc tag.
        Parameters:
        fourcc - A four char array, in order of least significant byte to most significant byte.
        Throws:
        java.lang.IllegalArgumentException - if the array passed in is not exactly 4 bytes.

      • toString

        public java.lang.String toString()
        Prints details on this IStreamCoder
        Overrides:
        toString in class java.lang.Object
        Returns:
        key details for this IStreamCoder

      • getExtraData

        public IBuffer getExtraData()
        Returns a read-only copy of the extra data in this stream coder as a new IBuffer.
        Returns:
        the extra data, or null if none or error.
        Since:
        3.3

      • getStream

        public IStream getStream()
        The associated Stream we're working on.

        Returns:
        The stream associated with this object.

      • getCodec

        public ICodec getCodec()
        The Codec this StreamCoder will use.

        Returns:
        The Codec used by this StreamCoder, or 0 (null) if none.

      • getCodecType

        public ICodec.Type getCodecType()
        A short hand for getCodec().getType().



        Note for Native (C++) users:


        If you actually write code like the above
        from Native code, you'd leak
        a Codec() since you didn't call release() on it.
        This method is a short hand way to avoid you having to
        worry about releasing in between.

        Returns:
        The Type of the Codec we'll use.

      • getCodecID

        public ICodec.ID getCodecID()
        A short hand for getCodec().getID().



        Note for Native (C++) users:


        If you actually write code like the above
        from Native code, you'd leak
        a Codec() since you didn't call release() on it.
        This method is a short hand way to avoid you having to
        worry about releasing in between.

        Returns:
        The ID of the Codec we'll use.

      • setCodec

        public void setCodec​(ICodec codec)
        Set the Codec to the passed in Codec, discarding the old
        Codec if set.


        Once you call setCodec, all settings on the IStreamCoder are
        reset to default values. So you probably want to call this
        first.



        Parameters:
        codec - Codec to set.

      • setCodec

        public void setCodec​(ICodec.ID id)
        Look up a Codec based on the passed in ID, and then set it.


        To see if you actually set the correct ID, call getCodec() and
        check for 0 (null).



        Once you call setCodec, all settings on the IStreamCoder are
        reset to default values. So you probably want to call this
        first.



        Parameters:
        id - ID of codec to set.

      • getBitRate

        public int getBitRate()
        The bit rate.

        Returns:
        The bit-rate the stream is, or will be, encoded in.

      • setBitRate

        public void setBitRate​(int rate)
        When ENCODING, sets the bit rate to use. No-op when DECODING.
        Parameters:
        rate - The bit rate to use.

      • getBitRateTolerance

        public int getBitRateTolerance()
        The bit rate tolerance

        Returns:
        The bit-rate tolerance

      • setBitRateTolerance

        public void setBitRateTolerance​(int tolerance)
        When ENCODING set the bit rate tolerance. No-op when DECODING.

        Parameters:
        tolerance - The bit rate tolerance

      • getHeight

        public int getHeight()
        The height, in pixels.

        Returns:
        The height of the video frames in the attached stream
        or -1 if an audio stream, or we cannot determine the height.

      • setHeight

        public void setHeight​(int height)
        Set the height, in pixels.

        Parameters:
        height - Sets the height of video frames we'll encode. No-op when DECODING.

      • getWidth

        public int getWidth()
        The width, in pixels.

        Returns:
        The width of the video frames in the attached stream
        or -1 if an audio stream, or we cannot determine the width.

      • setWidth

        public void setWidth​(int width)
        Set the width, in pixels

        Parameters:
        width - Sets the width of video frames we'll encode. No-op when DECODING.

      • getTimeBase

        public IRational getTimeBase()
        Get the time base this stream will ENCODE in, or the time base we
        detect while DECODING.

        Caller must call release() on the returned value.

        Returns:
        The time base this StreamCoder is using.

      • setTimeBase

        public void setTimeBase​(IRational newTimeBase)
        Set the time base we'll use to ENCODE with. A no-op when DECODING.

        As a convenience, we forward this call to the Stream#setTimeBase()
        method.

        Parameters:
        newTimeBase - The new time base to use.

      • getFrameRate

        public IRational getFrameRate()
        Get the frame-rate the attached stream claims to be using when
        DECODING, or the frame-rate we'll claim we're using when ENCODING.

        Returns:
        The frame rate.

      • setFrameRate

        public void setFrameRate​(IRational newFrameRate)
        Set the frame rate we'll set in the headers of this stream while
        ENCODING. Note that you can set whatever frame-rate you'd like,
        but the TimeBase and the PTS you set on the encoded audio
        and video frames can override this.

        As a convenience, we forward this call to the Stream::setFrameRate()
        method.

        Parameters:
        newFrameRate - The new frame rate to use.

      • getNumPicturesInGroupOfPictures

        public int getNumPicturesInGroupOfPictures()
        The the number of pictures in this Group of Pictures (GOP). See the
        MPEG specs for what a GOP is officially, but this is the minimum
        number of frames between key-frames (or Intra-Frames in MPEG speak).

        Returns:
        the GOPS for this stream.

      • setNumPicturesInGroupOfPictures

        public void setNumPicturesInGroupOfPictures​(int gops)
        Set the GOPS on this stream. Ignored if DECODING.

        Parameters:
        gops - The new GOPS for the stream we're encoding.

      • getPixelType

        public IPixelFormat.Type getPixelType()
        For Video streams, get the Pixel Format in use by the stream.

        Returns:
        the Pixel format, or IPixelFormat::NONE if audio.

      • setPixelType

        public void setPixelType​(IPixelFormat.Type pixelFmt)
        Set the pixel format to ENCODE with. Ignored if audio or
        DECODING.

        Parameters:
        pixelFmt - Pixel format to use.

      • getSampleRate

        public int getSampleRate()
        Get the sample rate we use for this stream.

        Returns:
        The sample rate (in Hz) we use for this stream, or -1 if unknown or video.

      • setSampleRate

        public void setSampleRate​(int sampleRate)
        Set the sample rate to use when ENCODING. Ignored if DECODING
        or a non-audio stream.

        Parameters:
        sampleRate - New sample rate (in Hz) to use.

      • setSampleFormat

        public void setSampleFormat​(IAudioSamples.Format aFormat)
        Set the sample format when ENCODING. Ignored if DECODING
        or if the coder is already open.

        Parameters:
        aFormat - The sample format.

      • getChannels

        public int getChannels()
        Get the number of channels in this audio stream

        Returns:
        The sample rate (in Hz) we use for this stream, or 0 if unknown.

      • setChannels

        public void setChannels​(int channels)
        Set the number of channels to use when ENCODING. Ignored if a
        non audio stream, or if DECODING.

        Parameters:
        channels - The number of channels we'll encode with.

      • getAudioFrameSize

        public int getAudioFrameSize()
        For this stream, get the number of audio samples that are
        represented in a packet of information.

        Returns:
        Number of samples per 'frame' of encoded audio

      • getGlobalQuality

        public int getGlobalQuality()
        Get the Global Quality setting this codec uses for video if
        a VideoPicture doesn't have a quality set.

        Returns:
        The global quality.

      • setGlobalQuality

        public void setGlobalQuality​(int newQuality)
        Set the Global Quality to a new value.

        Parameters:
        newQuality - The new global quality.

      • getFlags

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

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

      • setFlags

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

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

      • getFlag

        public boolean getFlag​(IStreamCoder.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​(IStreamCoder.Flags flag,
                    boolean value)
        Set the flag.

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

      • getNextPredictedPts

        public long getNextPredictedPts()
        For this stream, get the next Pts that we expect to decode.

        Note that this may not actually be the next Pts (for example
        due to transmission packet drops in the input source). Still
        it can be a useful tool.

        Returns:
        The next presentation time stamp we expect to decode
        on this stream. This is always in units of 1/1,000,000 seconds

      • open

        @Deprecated
public int open()
        Deprecated.
        Use {#open(IMetaData,IMetaData)} instead.
        Open the Codec associated with this StreamCoder.

        You can get the codec through getCodec(...) and
        set it with setCodec(...). You cannot call any
        set* methods after you've called open() on this StreamCoder
        until you close() it.

        You must call close() when you're done, but if you don't,
        the container will clean up after you (but yell at you)
        when it is closed.

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

      • close

        public int close()
        Close a Codec that was opened on this StreamCoder.

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

      • decodeAudio

        public int decodeAudio​(IAudioSamples pOutSamples,
                       IPacket packet,
                       int byteOffset)
        Decode this packet into pOutSamples. It will
        try to fill up the audio samples object, starting
        from the byteOffset inside this packet.


        The caller is responsible for allocating the
        IAudioSamples object. This function will overwrite
        any data in the samples object.



        Note that the IAudioSamples object passed in must have
        a {IAudioSamples#getMaxBufferSize()} of at least
        192kbytes. Sorry, but this requirement is imposed
        on us via FFmpeg. If the buffer is not large enough,
        this method will reallocate the underlying buffers to
        make them at least 192kbytes.


        Parameters:
        pOutSamples - The AudioSamples we decode to
        packet - The packet we're attempting to decode from.
        byteOffset - Where in the packet payload to start decoding

        Returns:
        number of bytes actually processed from the packet, or negative for error

      • decodeVideo

        public int decodeVideo​(IVideoPicture pOutFrame,
                       IPacket packet,
                       int byteOffset)
        Decode this packet into pOutFrame.

        The caller is responsible for allocating the
        IVideoPicture object. This function will potentially
        overwrite any data in the frame object, but
        you should pass the same IVideoPicture into this function
        repeatedly until IVideoPicture::isComplete() is true.

        Parameters:
        pOutFrame - The AudioSamples we decode.
        packet - The packet we're attempting to decode from.
        byteOffset - Where in the packet payload to start decoding

        Returns:
        number of bytes actually processed from the packet, or negative for error

      • encodeVideo

        public int encodeVideo​(IPacket pOutPacket,
                       IVideoPicture pFrame,
                       int suggestedBufferSize)
        Encode the given frame using this StreamCoder.

        The VideoPicture will allocate a buffer to use internally for this, and
        will free it when the frame destroys itself.

        Also, when done in order to flush the encoder, caller should call
        this method passing in 0 (null) for pFrame to tell the encoder
        to flush any data it was keeping a hold of.

        Parameters:
        pOutPacket - [out] The packet to encode into. It will point
        to a buffer allocated in the frame. Caller should check IPacket::isComplete()
        after call to find out if we had enough information to encode a full packet.
        pFrame - [in/out] The frame to encode
        suggestedBufferSize - The suggested buffer size to allocate or -1 for choose ourselves.
        If -1 we'll allocate a buffer exactly the same size (+1) as the decoded frame
        with the guess that you're encoding a frame because you want to use LESS space
        than that.

      • encodeAudio

        public int encodeAudio​(IPacket pOutPacket,
                       IAudioSamples pSamples,
                       int sampleToStartFrom)
        Encode the given samples using this StreamCoder.

        The VideoPicture will allocate a buffer to use internally for this, and
        will free it when the frame destroys itself.

        Callers should call this repeatedly on a set of samples until
        we consume all the samples.

        Also, when done in order to flush the encoder, caller should call
        this method passing in 0 (null) for pSamples to tell the encoder
        to flush any data it was keeping a hold of.

        Parameters:
        pOutPacket - [out] The packet to encode into. It will point
        to a buffer allocated in the frame. Caller should check IPacket::isComplete()
        after call to find out if we had enough information to encode a full packet.
        pSamples - [in] The samples to consume
        sampleToStartFrom - [in] Which sample you want to start with
        This is usually zero, but if you're using a codec that
        packetizes output with small number of samples, you may
        need to call encodeAudio repeatedly with different starting
        samples to consume all of your samples.

        Returns:
        number of samples we consumed when encoding, or negative for errors.

      • make

        @Deprecated
public static IStreamCoder make​(IStreamCoder.Direction direction)
        Deprecated.
        Use {#make(Direction, ICodec)} instead.
        Create a standalone StreamCoder that can decode data without regard to
        which IStream or IContainer it came from.


        If you're reading or writing to a AVPKIT file or URL you almost definitely
        don't want to use this method. Use the {IContainer#getStream(long)}
        and {IStream#getStreamCoder()} methods instead as it will set up the
        resulting IStreamCoder with sensible defaults. Use of a un-attached
        StreamCoder returned from this method is for advanced users only.


        Parameters:
        direction - The direction this StreamCoder will work in.
        Returns:
        a new stream coder, or null if error.

      • getCodecTag

        public int getCodecTag()
        Returns the 4-byte FOURCC tag (Least Significant Byte first).

        This is really a packed 4-byte array so it's only useful if you use
        bit-wise operations on it. Some language wrappings may provide more
        obvious ways of manipulating, but this is the safest way to do this that
        will work with all wrappers.

        Returns:
        the FOURCC tag.

      • setCodecTag

        public void setCodecTag​(int fourcc)
        Set the 4-byte FOURCC tag for this coder.
        Parameters:
        fourcc - The FOURCC to set, with Least Significant Byte first.

      • 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. Other language
        folks need not worry.

        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.

      • isOpen

        public boolean isOpen()
        Returns true if this IStreamCoder is currently open.

        Returns:
        true if open; false if not

      • getDefaultAudioFrameSize

        public int getDefaultAudioFrameSize()
        Get the default audio frame size (in samples).

        Some codecs, especially raw codecs, like PCM, don't have
        a standard frame size. In those cases, we use the value
        of this setting to determine how many samples to encode into
        a single packet.

        Returns:
        the number of samples in an audio frame size if the codec
        doesn't specify the size.
        Since:
        1.21

      • setDefaultAudioFrameSize

        public void setDefaultAudioFrameSize​(int aNewSize)
        Set the default audio frame size.

        Parameters:
        aNewSize - The new number of samples to use to encode
        samples into a packet. This setting is ignored if <= 0
        or if the codec requires it's own frame size (e.g. Nellymoser).

        Since:
        1.21

      • make

        public static IStreamCoder make​(IStreamCoder.Direction direction,
                                IStreamCoder copyCoder)
        Creates a new IStreamCoder object by copying all the settings in copyCoder.


        The new IStreamCoder is created by copying all the current properties on the
        passed in StreamCoder. If the passed in stream coder is in a different direction
        than the one you want, this method still set the same codec ID, and the
        IStreamCoder.open() method will check then to see if it can work in the
        specified direction.



        For example, imagine that direction is ENCODING and the copyCoder is a DECODING StreamCoder that is
        of the CODEC_ID_VP6 type. The resulting new IStreamCoder has it's code set to CODEC_ID_VP6. However
        (as of the writing of this comment) we don't support encoding to CODEC_ID_VP6, so when you
        try to open the codec we will fail.


        Parameters:
        direction - The direction you want the new IStreamCoder to work in.
        copyCoder - The coder to copy settings from.

        Returns:
        A new IStreamCoder, or null on error.
        Since:
        1.22

      • getNumDroppedFrames

        public long getNumDroppedFrames()
        Get the number of frames this StreamCoder had to drop to
        encode at the specified {#getTimeBase()}


        IStreamCoder objects can encode audio and video, but
        guarantee that every packet outputted has monotonically
        increasing timestamps (i.e. 0, 1, 2, 3, 4, 5, etc. without
        repeats). Sometimes data is passed too quickly into an
        IStreamCoder via {#encodeVideo} or {#encodeAudio},
        and the underlying codec can't handle it that quickly. In those
        cases the IStreamCoder must drop the most recent frame of data.



        If you're seeing a lot of dropped frames you can try either
        sending less frequent data to the IStreamCoder, or adjusting
        the {#getTimeBase()} to the highest possible resolution.
        Be warned though; some codecs (such as MPEG2) require fixed
        time-bases (like 1/25) and so setting a higher resolution
        time base might end up with the codec not able to encode
        any data.


        Returns:
        the number of frames dropped.
        Since:
        3.1

      • setAutomaticallyStampPacketsForStream

        public void setAutomaticallyStampPacketsForStream​(boolean value)
        Should the {IStreamCoder} automatically adjust
        time stamps on output packets for the {IStream}
        it is ultimately destined for.



        If this {IStreamCoder} does not know which {IStream}
        it is destined for, or this {IStreamCoder} isn't used
        with an {IStream} at all, then this setting is ignored.



        Parameters:
        value - true to automatically adjust.
        Since:
        3.2

      • getAutomaticallyStampPacketsForStream

        public boolean getAutomaticallyStampPacketsForStream()
        Does this {IStreamCoder} automatically adjust
        time stamps on output packets for the {IStream} it
        is ultimately destined for.
        Returns:
        true for yes; false for no
        Since:
        3.2

      • setCodecID

        public void setCodecID​(ICodec.ID id)
        Look up a Codec based on the passed in ID, and then set it.


        Forwards to {#setCodecID(com.avpkit.core.ICodec.ID)}



        To see if you actually set the correct ID, call getCodec() and
        check for 0 (null).



        Once you call setCodec, all settings on the IStreamCoder are
        reset to default values. So you probably want to call this
        first.



        Parameters:
        id - ID of codec to set.
        Since:
        3.2

      • setExtraData

        public int setExtraData​(IBuffer src,
                        int offset,
                        int length,
                        boolean allocNew)
        Copies data from the given buffer into the extra-data area maintained
        by encoders.


        This is an extremely advanced method, and incorrect usage can result
        in Java crashes so take care. In general people should not need to use this.



        For some codecs (e.g. for H264, this is global header information and
        for rv10 it is additional flags),
        AVPKit maintains extra information about
        the codec in a extra data buffer. In general AVPKit will allocate this
        data as needed and you never need to set it (or get it). But if you know what you're
        doing, you can ask AVPKit to replace the existing extra data for the
        given codec with a copy of the data in the given buffer.



        You should call this method after you call {#open()} but before
        you encode or decode any media.


        Parameters:
        src - The data to copy
        offset - The position, in bytes, to start copying data from src
        length - The number of bytes to copy from data
        allocNew - If true, and there is not enough space in the existing
        extra data buffer, then AVPKit will discard the old buffer and allocate a new buffer.
        If false, then AVPKit will attempt to copy the data into the existing buffer and if there
        is not enough space in the existing buffer, no bytes will be copied and an error will
        be returned. In general, you should set this to false if that works for you.
        Returns:
        The number of bytes copied, or < 0 on error.

        Since:
        3.3

      • getExtraData

        public int getExtraData​(IBuffer dest,
                        int offset,
                        int maxBytesToCopy)
        Copies the current content of the extra-data buffer maintained by this codec (e.g. header bytes)
        into the dest buffer.

        Parameters:
        dest - The buffer to copy to.
        offset - The position, in bytes, to start writing data to in dest.
        maxBytesToCopy - The maximum number of bytes to copy.
        Returns:
        The number of bytes copied, or < 0 on error.

        Since:
        3.3

      • getExtraDataSize

        public int getExtraDataSize()
        Gets the current number of bytes of data maintained in the coder extra-data area.
        Returns:
        The number of bytes. If 0, then no data is currently available.

        Since:
        3.3

      • 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.0
        See Also:
        CodecStandardsCompliance

      • open

        public int open​(IMetaData options,
                IMetaData unsetOptions)
        Open the codec with the given options.

        Callers must call {#setCodec} before calling this method.

        Parameters:
        options - If non-NULL, a dictionary of parameter options to set for this codec.
        unsetOptions - If non-NULL, on successful return the prior contents of this set
        of meta data will be replaced with any settings in 'options' that could not be set
        on this codec.

        Returns:
        0 on success; <0 on error

        Since:
        5.0

      • make

        public static IStreamCoder make​(IStreamCoder.Direction direction,
                                ICodec codec)
        Create a standalone StreamCoder that can encode or decode data independent
        of the stream it is attached to.


        If you're reading or writing to a AVPKIT file or URL you almost definitely
        don't want to use this method. Use the {IContainer#getStream(long)}
        and {IStream#getStreamCoder()} methods instead as it will set up the
        resulting IStreamCoder with sensible defaults. Use of a un-attached
        StreamCoder returned from this method is for advanced users only.


        Parameters:
        direction - The direction this StreamCoder will work in.
        codec - The codec you want to use (in lieu of calling {#setCodec}
        Returns:
        a new stream coder, or null if error.

        Since:
        5.0

      • make

        public static IStreamCoder make​(IStreamCoder.Direction direction,
                                ICodec.ID id)
        Create a standalone StreamCoder that can encode or decode data independent
        of the stream it is attached to.


        If you're reading or writing to a AVPKIT file or URL you almost definitely
        don't want to use this method. Use the {IContainer#getStream(long)}
        and {IStream#getStreamCoder()} methods instead as it will set up the
        resulting IStreamCoder with sensible defaults. Use of a un-attached
        StreamCoder returned from this method is for advanced users only.


        Parameters:
        direction - The direction this StreamCoder will work in.
        id - The codec id you want to use (in lieu of calling {#setCodec}
        Returns:
        a new stream coder, or null if error.

        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

      • setHardwareDecoding

        public int setHardwareDecoding​(IPixelFormat.Type type)
        Try to change current decoder to an HW decoder compatible with
        pixel format

        Parameters:
        type - an HW accelerated pixel format
        Returns:
        0 on success; non-zero on failure