Class VideoReader

java.lang.Object
com.codename1.media.VideoReader
public abstract class VideoReader extends Object

Decodes an existing video clip into individual RGBA frames and PCM audio. This is the read side that com.codename1.media.Media deliberately does not provide: Media is a player whose Media#setTime(int) snaps to key frames and gives no exact frame guarantee, whereas VideoReader decodes to precise frames.

Two access patterns are offered:

  • #frameAt(long) returns the single frame at (or nearest before) a given millisecond offset. This is frame accurate, unlike seeking a Media player.
  • #readFrames(float, FrameCallback) walks the whole clip emitting frames at a fixed target frame rate. Source clips are frequently variable frame rate (VFR), for example screen recordings; this resamples them to a constant frame rate (CFR) so the caller receives an evenly spaced sequence it can re-encode or process.

The audio track, when present, is exposed as interleaved PCM through #readAudio().

Obtain an instance from VideoIO#openReader(String). Always #close() it when done.

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static interface 
    VideoReader.FrameCallback
    Callback used by VideoReader#readFrames(float, FrameCallback) to receive frames as they are decoded.

  • Constructor Summary

    Constructors
    Constructor
    Description
    VideoReader()
     

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract void
    close()
    Releases the decoder and any native resources.
    abstract VideoFrame
    frameAt(long millis)
    Returns the frame at (or nearest at/before) the given timestamp, decoded to RGBA.
    abstract int
    getAudioChannels()
    The number of channels in the audio track, or -1 if there is no audio.
    abstract int
    getAudioSampleRate()
    The sample rate of the audio track in Hz, or -1 if there is no audio.
    abstract long
    getDurationMillis()
    The total duration of the clip in milliseconds, or -1 if unknown.
    abstract float
    getFrameRate()
    The average/nominal frame rate of the source video track.
    abstract int
    getHeight()
    The height of the video track in pixels, or -1 if there is no video.
    abstract int
    getWidth()
    The width of the video track in pixels, or -1 if there is no video.
    abstract boolean
    hasAudio()
    True if the clip has a decodable audio track.
    abstract boolean
    hasVideo()
    True if the clip has a decodable video track.
    abstract AudioBuffer
    readAudio()
    Reads the entire audio track and returns it as a single AudioBuffer of interleaved floating point samples.
    abstract void
    readFrames(float fps, VideoReader.FrameCallback callback)
    Walks the entire clip, decoding and resampling it to the requested constant frame rate, invoking the callback once per output frame in increasing timestamp order.

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Constructor Details

    • VideoReader

      public VideoReader()

  • Method Details

    • getWidth

      public abstract int getWidth()
      The width of the video track in pixels, or -1 if there is no video.

    • getHeight

      public abstract int getHeight()
      The height of the video track in pixels, or -1 if there is no video.

    • getDurationMillis

      public abstract long getDurationMillis()
      The total duration of the clip in milliseconds, or -1 if unknown.

    • getFrameRate

      public abstract float getFrameRate()
      The average/nominal frame rate of the source video track. For variable frame rate sources this is an average; use #readFrames(float, FrameCallback) to obtain an evenly spaced sequence.

    • hasVideo

      public abstract boolean hasVideo()
      True if the clip has a decodable video track.

    • hasAudio

      public abstract boolean hasAudio()
      True if the clip has a decodable audio track.

    • getAudioSampleRate

      public abstract int getAudioSampleRate()
      The sample rate of the audio track in Hz, or -1 if there is no audio.

    • getAudioChannels

      public abstract int getAudioChannels()
      The number of channels in the audio track, or -1 if there is no audio.

    • frameAt

      public abstract VideoFrame frameAt(long millis) throws IOException

      Returns the frame at (or nearest at/before) the given timestamp, decoded to RGBA. Unlike seeking a Media player, the returned frame corresponds exactly to the requested position rather than the closest key frame.

      Parameters
      • millis: the timestamp to seek to in milliseconds
      Returns

      the decoded VideoFrame, or null if the position is past the end of the clip

      Throws
      • IOException: if decoding fails
      Throws:
      IOException

    • readFrames

      public abstract void readFrames(float fps, VideoReader.FrameCallback callback) throws IOException

      Walks the entire clip, decoding and resampling it to the requested constant frame rate, invoking the callback once per output frame in increasing timestamp order. This converts a variable frame rate source to a constant frame rate sequence by duplicating or dropping source frames as needed.

      Parameters

      • fps: the target constant output frame rate in frames per second

      • callback: receives each decoded frame; return false from it to stop early

      Throws
      • IOException: if decoding fails
      Throws:
      IOException

    • readAudio

      public abstract AudioBuffer readAudio() throws IOException

      Reads the entire audio track and returns it as a single AudioBuffer of interleaved floating point samples. For very long clips consider using the audio only at a reduced rate or processing the clip in segments, as the whole track is held in memory.

      Returns

      the decoded audio, or null if the clip has no audio track

      Throws
      • IOException: if decoding fails
      Throws:
      IOException

    • close

      public abstract void close() throws IOException

      Releases the decoder and any native resources. The reader cannot be used after this call.

      Throws
      • IOException: if releasing resources fails
      Throws:
      IOException