# 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`