3 files changed, 598 insertions, 0 deletions
diff --git a/src/java/com/jogamp/common/av/AudioSink.java b/src/java/com/jogamp/common/av/AudioSink.java
new file mode 100644
index 0000000..3973d33
--- /dev/null
+++ b/src/java/com/jogamp/common/av/AudioSink.java
@@ -0,0 +1,448 @@
+/**
+ * Copyright 2013-2023 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+package com.jogamp.common.av;
+
+import java.nio.ByteBuffer;
+
+import jogamp.common.Debug;
+
+public interface AudioSink {
+    public static final boolean DEBUG = Debug.debug("AudioSink");
+
+    /** Default frame duration in millisecond, i.e. 1 frame per {@value} ms. */
+    public static final int DefaultFrameDuration = 32;
+
+    /** Initial audio queue size in milliseconds. {@value} ms, i.e. 16 frames per 32 ms. See {@link #init(AudioFormat, float, int, int, int)}.*/
+    public static final int DefaultInitialQueueSize = 16 * 32; // 512 ms
+    /** Audio queue grow size in milliseconds. {@value} ms, i.e. 16 frames per 32 ms. See {@link #init(AudioFormat, float, int, int, int)}.*/
+    public static final int DefaultQueueGrowAmount = 16 * 32; // 512 ms
+    /** Audio queue limit w/ video in milliseconds. {@value} ms, i.e. 96 frames per 32 ms. See {@link #init(AudioFormat, float, int, int, int)}.*/
+    public static final int DefaultQueueLimitWithVideo =  96 * 32; // 3072 ms
+    /** Audio queue limit w/o video in milliseconds. {@value} ms, i.e. 32 frames per 32 ms. See {@link #init(AudioFormat, float, int, int, int)}.*/
+    public static final int DefaultQueueLimitAudioOnly =  32 * 32; // 1024 ms
+
+    /**
+     * Specifies the linear audio PCM format.
+     */
+    public static class AudioFormat {
+        /**
+         * @param sampleRate sample rate in Hz (1/s)
+         * @param sampleSize sample size in bits
+         * @param channelCount number of channels
+         * @param signed true if signed number, false for unsigned
+         * @param fixedP true for fixed point value, false for unsigned floating point value with a sampleSize of 32 (float) or 64 (double)
+         * @param planar true for planar data package (each channel in own data buffer), false for packed data channels interleaved in one buffer.
+         * @param littleEndian true for little-endian, false for big endian
+         */
+        public AudioFormat(final int sampleRate, final int sampleSize, final int channelCount, final boolean signed, final boolean fixedP, final boolean planar, final boolean littleEndian) {
+            this.sampleRate = sampleRate;
+            this.sampleSize = sampleSize;
+            this.channelCount = channelCount;
+            this.signed = signed;
+            this.fixedP = fixedP;
+            this.planar = planar;
+            this.littleEndian = littleEndian;
+            if( !fixedP ) {
+                if( sampleSize != 32 && sampleSize != 64 ) {
+                    throw new IllegalArgumentException("Floating point: sampleSize "+sampleSize+" bits");
+                }
+                if( !signed ) {
+                    throw new IllegalArgumentException("Floating point: unsigned");
+                }
+            }
+        }
+
+        /** Sample rate in Hz (1/s). */
+        public final int sampleRate;
+        /** Sample size in bits. */
+        public final int sampleSize;
+        /** Number of channels. */
+        public final int channelCount;
+        public final boolean signed;
+        /** Fixed or floating point values. Floating point 'float' has {@link #sampleSize} 32, 'double' has {@link #sampleSize} 64. */
+        public final boolean fixedP;
+        /** Planar or packed samples. If planar, each channel has their own data buffer. If packed, channel data is interleaved in one buffer. */
+        public final boolean planar;
+        public final boolean littleEndian;
+
+
+        //
+        // Time <-> Bytes
+        //
+
+        /**
+         * Returns the byte size of the given milliseconds
+         * according to {@link #sampleSize}, {@link #channelCount} and {@link #sampleRate}.
+         * <p>
+         * Time -> Byte Count
+         * </p>
+         */
+        public final int getDurationsByteSize(final int millisecs) {
+            final int bytesPerSample = sampleSize >>> 3; // /8
+            return millisecs * ( channelCount * bytesPerSample * ( sampleRate / 1000 ) );
+        }
+
+        /**
+         * Returns the duration in milliseconds of the given byte count
+         * according to {@link #sampleSize}, {@link #channelCount} and {@link #sampleRate}.
+         * <p>
+         * Byte Count -> Time
+         * </p>
+         */
+        public final int getBytesDuration(final int byteCount) {
+            final int bytesPerSample = sampleSize >>> 3; // /8
+            return byteCount / ( channelCount * bytesPerSample * ( sampleRate / 1000 ) );
+        }
+
+        /**
+         * Returns the duration in milliseconds of the given sample count per frame and channel
+         * according to the {@link #sampleRate}, i.e.
+         * <pre>
+         *    ( 1000f * sampleCount ) / sampleRate
+         * </pre>
+         * <p>
+         * Sample Count -> Time
+         * </p>
+         * @param sampleCount sample count per frame and channel
+         */
+        public final float getSamplesDuration(final int sampleCount) {
+            return ( 1000f * sampleCount ) / sampleRate;
+        }
+
+        /**
+         * Returns the rounded frame count of the given milliseconds and frame duration.
+         * <pre>
+         *     Math.max( 1, millisecs / frameDuration + 0.5f )
+         * </pre>
+         * <p>
+         * Note: <code>frameDuration</code> can be derived by <i>sample count per frame and channel</i>
+         * via {@link #getSamplesDuration(int)}.
+         * </p>
+         * <p>
+         * Frame Time -> Frame Count
+         * </p>
+         * @param millisecs time in milliseconds
+         * @param frameDuration duration per frame in milliseconds.
+         */
+        public final int getFrameCount(final int millisecs, final float frameDuration) {
+            return Math.max(1, (int) ( millisecs / frameDuration + 0.5f ));
+        }
+
+        /**
+         * Returns the byte size of given sample count
+         * according to the {@link #sampleSize}, i.e.:
+         * <pre>
+         *  sampleCount * ( sampleSize / 8 )
+         * </pre>
+         * <p>
+         * Note: To retrieve the byte size for all channels,
+         * you need to pre-multiply <code>sampleCount</code> with {@link #channelCount}.
+         * </p>
+         * <p>
+         * Sample Count -> Byte Count
+         * </p>
+         * @param sampleCount sample count
+         */
+        public final int getSamplesByteCount(final int sampleCount) {
+            return sampleCount * ( sampleSize >>> 3 );
+        }
+
+        /**
+         * Returns the sample count of given byte count
+         * according to the {@link #sampleSize}, i.e.:
+         * <pre>
+         *  ( byteCount * 8 ) / sampleSize
+         * </pre>
+         * <p>
+         * Note: If <code>byteCount</code> covers all channels and you request the sample size per channel,
+         * you need to divide the result by <code>sampleCount</code> by {@link #channelCount}.
+         * </p>
+         * <p>
+         * Byte Count -> Sample Count
+         * </p>
+         * @param byteCount number of bytes
+         */
+        public final int getBytesSampleCount(final int byteCount) {
+            return ( byteCount << 3 ) / sampleSize;
+        }
+
+        @Override
+        public String toString() {
+            return "AudioDataFormat[sampleRate "+sampleRate+", sampleSize "+sampleSize+", channelCount "+channelCount+
+                   ", signed "+signed+", fixedP "+fixedP+", "+(planar?"planar":"packed")+", "+(littleEndian?"little":"big")+"-endian]"; }
+    }
+    /** Default {@link AudioFormat}, [type PCM, sampleRate 44100, sampleSize 16, channelCount 2, signed, fixedP, !planar, littleEndian]. */
+    public static final AudioFormat DefaultFormat = new AudioFormat(44100, 16, 2, true /* signed */,
+                                          true /* fixed point */, false /* planar */, true /* littleEndian */);
+
+    public static abstract class AudioFrame extends TimeFrameI {
+        protected int byteSize;
+
+        public AudioFrame() {
+            this.byteSize = 0;
+        }
+        public AudioFrame(final int pts, final int duration, final int byteCount) {
+            super(pts, duration);
+            this.byteSize=byteCount;
+        }
+
+        /** Get this frame's size in bytes. */
+        public final int getByteSize() { return byteSize; }
+        /** Set this frame's size in bytes. */
+        public final void setByteSize(final int size) { this.byteSize=size; }
+
+        @Override
+        public String toString() {
+            return "AudioFrame[pts " + pts + " ms, l " + duration + " ms, "+byteSize + " bytes]";
+        }
+    }
+    public static class AudioDataFrame extends AudioFrame {
+        protected final ByteBuffer data;
+
+        public AudioDataFrame(final int pts, final int duration, final ByteBuffer bytes, final int byteCount) {
+            super(pts, duration, byteCount);
+            if( byteCount > bytes.remaining() ) {
+                throw new IllegalArgumentException("Give size "+byteCount+" exceeds remaining bytes in ls "+bytes+". "+this);
+            }
+            this.data=bytes;
+        }
+
+        /** Get this frame's data. */
+        public final ByteBuffer getData() { return data; }
+
+        @Override
+        public String toString() {
+            return "AudioDataFrame[pts " + pts + " ms, l " + duration + " ms, "+byteSize + " bytes, " + data + "]";
+        }
+    }
+
+    /**
+     * Returns the <code>available state</code> of this instance.
+     * <p>
+     * The <code>available state</code> is affected by this instance
+     * overall availability, i.e. after instantiation,
+     * as well as by {@link #destroy()}.
+     * </p>
+     */
+    public boolean isAvailable();
+
+    /** Returns the playback speed. */
+    public float getPlaySpeed();
+
+    /**
+     * Sets the playback speed.
+     * <p>
+     * To simplify test, play speed is  <i>normalized</i>, i.e.
+     * <ul>
+     *   <li><code>1.0f</code>: if <code> Math.abs(1.0f - rate) < 0.01f </code></li>
+     * </ul>
+     * </p>
+     * @return true if successful, otherwise false, i.e. due to unsupported value range of implementation.
+     */
+    public boolean setPlaySpeed(float s);
+
+    /** Returns the volume. */
+    public float getVolume();
+
+    /**
+     * Sets the volume [0f..1f].
+     * <p>
+     * To simplify test, volume is <i>normalized</i>, i.e.
+     * <ul>
+     *   <li><code>0.0f</code>: if <code> Math.abs(v) < 0.01f </code></li>
+     *   <li><code>1.0f</code>: if <code> Math.abs(1.0f - v) < 0.01f </code></li>
+     * </ul>
+     * </p>
+     * @return true if successful, otherwise false, i.e. due to unsupported value range of implementation.
+     */
+    public boolean setVolume(float v);
+
+    /**
+     * Returns the preferred sample-rate of this sink.
+     * <p>
+     * The preferred sample-rate is guaranteed to be supported
+     * and shall reflect this sinks most native format,
+     * i.e. best performance w/o data conversion.
+     * </p>
+     * @see #initSink(AudioFormat)
+     * @see #isSupported(AudioFormat)
+     * @see #getPreferredSampleRate()
+     */
+    public int getPreferredSampleRate();
+
+    /**
+     * Returns the preferred {@link AudioFormat} by this sink.
+     * <p>
+     * The preferred format is guaranteed to be supported
+     * and shall reflect this sinks most native format,
+     * i.e. best performance w/o data conversion.
+     * </p>
+     * <p>
+     * Known {@link #AudioFormat} attributes considered by implementations:
+     * <ul>
+     *   <li>ALAudioSink: {@link AudioFormat#sampleRate}.
+     * </ul>
+     * </p>
+     * @see #initSink(AudioFormat)
+     * @see #isSupported(AudioFormat)
+     * @see #getPreferredSampleRate()
+     */
+    public AudioFormat getPreferredFormat();
+
+    /** Return the maximum number of supported channels. */
+    public int getMaxSupportedChannels();
+
+    /**
+     * Returns true if the given format is supported by the sink, otherwise false.
+     * @see #initSink(AudioFormat)
+     * @see #getPreferredFormat()
+     */
+    public boolean isSupported(AudioFormat format);
+
+    /**
+     * Initializes the sink.
+     * <p>
+     * Implementation must match the given <code>requestedFormat</code> {@link AudioFormat}.
+     * </p>
+     * <p>
+     * Caller shall validate <code>requestedFormat</code> via {@link #isSupported(AudioFormat)}
+     * beforehand and try to find a suitable supported one.
+     * {@link #getPreferredFormat()} and {@link #getMaxSupportedChannels()} may help.
+     * </p>
+     * @param requestedFormat the requested {@link AudioFormat}.
+     * @param frameDuration average or fixed frame duration in milliseconds
+     *                      helping a caching {@link AudioFrame} based implementation to determine the frame count in the queue.
+     *                      See {@link #DefaultFrameDuration}.
+     * @param initialQueueSize initial time in milliseconds to queue in this sink, see {@link #DefaultInitialQueueSize}.
+     * @param queueGrowAmount time in milliseconds to grow queue if full, see {@link #DefaultQueueGrowAmount}.
+     * @param queueLimit maximum time in milliseconds the queue can hold (and grow), see {@link #DefaultQueueLimitWithVideo} and {@link #DefaultQueueLimitAudioOnly}.
+     * @return true if successful, otherwise false
+     */
+    public boolean init(AudioFormat requestedFormat, float frameDuration,
+                        int initialQueueSize, int queueGrowAmount, int queueLimit);
+
+    /**
+     * Returns the {@link AudioFormat} as chosen by {@link #init(AudioFormat, float, int, int, int)},
+     * i.e. it shall match the <i>requestedFormat</i>.
+     */
+    public AudioFormat getChosenFormat();
+
+    /**
+     * Returns true, if {@link #play()} has been requested <i>and</i> the sink is still playing,
+     * otherwise false.
+     */
+    public boolean isPlaying();
+
+    /**
+     * Play buffers queued via {@link #enqueueData(AudioFrame)} from current internal position.
+     * If no buffers are yet queued or the queue runs empty, playback is being continued when buffers are enqueued later on.
+     * @see #enqueueData(AudioFrame)
+     * @see #pause()
+     */
+    public void play();
+
+    /**
+     * Pause playing buffers while keeping enqueued data incl. it's internal position.
+     * @see #play()
+     * @see #flush()
+     * @see #enqueueData(AudioFrame)
+     */
+    public void pause();
+
+    /**
+     * Flush all queued buffers, implies {@link #pause()}.
+     * <p>
+     * {@link #init(AudioFormat, float, int, int, int)} must be called first.
+     * </p>
+     * @see #play()
+     * @see #pause()
+     * @see #enqueueData(AudioFrame)
+     */
+    public void flush();
+
+    /** Destroys this instance, i.e. closes all streams and devices allocated. */
+    public void destroy();
+
+    /**
+     * Returns the number of allocated buffers as requested by
+     * {@link #init(AudioFormat, float, int, int, int)}.
+     */
+    public int getFrameCount();
+
+    /** @return the current enqueued frames count since {@link #init(AudioFormat, float, int, int, int)}. */
+    public int getEnqueuedFrameCount();
+
+    /**
+     * Returns the current number of frames queued for playing.
+     * <p>
+     * {@link #init(AudioFormat, float, int, int, int)} must be called first.
+     * </p>
+     */
+    public int getQueuedFrameCount();
+
+    /**
+     * Returns the current number of bytes queued for playing.
+     * <p>
+     * {@link #init(AudioFormat, float, int, int, int)} must be called first.
+     * </p>
+     */
+    public int getQueuedByteCount();
+
+    /**
+     * Returns the current queued frame time in milliseconds for playing.
+     * <p>
+     * {@link #init(AudioFormat, float, int, int, int)} must be called first.
+     * </p>
+     */
+    public int getQueuedTime();
+
+    /**
+     * Return the current audio presentation timestamp (PTS) in milliseconds.
+     */
+    public int getPTS();
+
+    /**
+     * Returns the current number of frames in the sink available for writing.
+     * <p>
+     * {@link #init(AudioFormat, float, int, int, int)} must be called first.
+     * </p>
+     */
+    public int getFreeFrameCount();
+
+    /**
+     * Enqueue <code>byteCount</code> bytes of the remaining bytes of the given NIO {@link ByteBuffer} to this sink.
+     * <p>
+     * The data must comply with the chosen {@link AudioFormat} as returned by {@link #initSink(AudioFormat)}.
+     * </p>
+     * <p>
+     * {@link #init(AudioFormat, float, int, int, int)} must be called first.
+     * </p>
+     * @returns the enqueued internal {@link AudioFrame}.
+     */
+    public AudioFrame enqueueData(int pts, ByteBuffer bytes, int byteCount);
+}
diff --git a/src/java/com/jogamp/common/av/AudioSinkFactory.java b/src/java/com/jogamp/common/av/AudioSinkFactory.java
new file mode 100644
index 0000000..70e6229
--- /dev/null
+++ b/src/java/com/jogamp/common/av/AudioSinkFactory.java
@@ -0,0 +1,69 @@
+/**
+ * Copyright 2013-2023 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+package com.jogamp.common.av;
+
+import com.jogamp.common.util.ReflectionUtil;
+
+import jogamp.common.av.NullAudioSink;
+
+public class AudioSinkFactory {
+    private static final String ALAudioSinkClazzName = "jogamp.openal.util.ALAudioSink";
+    private static final String JavaAudioSinkClazzName = "jogamp.common.av.JavaSoundAudioSink";
+
+    public static AudioSink createDefault(final ClassLoader cl) {
+        AudioSink sink = create(cl, ALAudioSinkClazzName);
+        if( null == sink ) {
+            sink = create(cl, JavaAudioSinkClazzName);
+        }
+        if( null == sink ) {
+            sink = createNull();
+        }
+        return sink;
+    }
+    public static AudioSink createNull() {
+        return new NullAudioSink();
+    }
+
+    public static AudioSink create(final ClassLoader cl, final String implName) {
+        final AudioSink audioSink;
+        if(ReflectionUtil.isClassAvailable(implName, cl)){
+            try {
+                audioSink = (AudioSink) ReflectionUtil.createInstance(implName, cl);
+                if( audioSink.isAvailable() ) {
+                    return audioSink;
+                } else if(AudioSink.DEBUG) {
+                    System.err.println("AudioSinkFactory: Couldn't instantiate AudioSink '"+implName+"'");
+                }
+            } catch (final Throwable t) {
+                if(AudioSink.DEBUG) { System.err.println("Caught "+t.getClass().getName()+": "+t.getMessage()); t.printStackTrace(); }
+            }
+        }
+        return null;
+    }
+
+}
diff --git a/src/java/com/jogamp/common/av/TimeFrameI.java b/src/java/com/jogamp/common/av/TimeFrameI.java
new file mode 100644
index 0000000..a528c09
--- /dev/null
+++ b/src/java/com/jogamp/common/av/TimeFrameI.java
@@ -0,0 +1,81 @@
+/**
+ * Copyright 2013-2023 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+package com.jogamp.common.av;
+
+/**
+ * Integer time frame in milliseconds, maybe specialized for texture/video, audio, .. animated content.
+ * <p>
+ * Type and value range has been chosen to suit embedded CPUs
+ * and characteristics of audio / video streaming and animations.
+ * Milliseconds of type integer with a maximum value of {@link Integer#MAX_VALUE}
+ * will allow tracking time up 2,147,483.647 seconds or
+ * 24 days 20 hours 31 minutes and 23 seconds.
+ * </p>
+ * <p>
+ * Milliseconds granularity is also more than enough to deal with A-V synchronization,
+ * where the threshold usually lies within 22ms.
+ * </p>
+ * <p>
+ * Milliseconds granularity for displaying video frames might seem inaccurate
+ * for each single frame, i.e. 60Hz != 16ms, however, accumulated values diminish
+ * this error and vertical sync is achieved by build-in V-Sync of the video drivers.
+ * </p>
+ */
+public class TimeFrameI {
+    /** Constant marking an invalid PTS, i.e. Integer.MIN_VALUE == 0x80000000 == {@value}. Sync w/ native code. */
+    public static final int INVALID_PTS = 0x80000000;
+
+    /** Constant marking the end of the stream PTS, i.e. Integer.MIN_VALUE - 1 == 0x7FFFFFFF == {@value}. Sync w/ native code. */
+    public static final int END_OF_STREAM_PTS = 0x7FFFFFFF;
+
+    protected int pts;
+    protected int duration;
+
+    public TimeFrameI() {
+        pts = INVALID_PTS;
+        duration = 0;
+    }
+    public TimeFrameI(final int pts, final int duration) {
+        this.pts = pts;
+        this.duration = duration;
+    }
+
+    /** Get this frame's presentation timestamp (PTS) in milliseconds. */
+    public final int getPTS() { return pts; }
+    /** Set this frame's presentation timestamp (PTS) in milliseconds. */
+    public final void setPTS(final int pts) { this.pts = pts; }
+    /** Get this frame's duration in milliseconds. */
+    public final int getDuration() { return duration; }
+    /** Set this frame's duration in milliseconds. */
+    public final void setDuration(final int duration) { this.duration = duration; }
+
+    @Override
+    public String toString() {
+        return "TimeFrame[pts " + pts + " ms, l " + duration + " ms]";
+    }
+}