@@ -414,15 +414,22 @@ the ordinary BLOB entry header, length trailer, or per-entry CRC:
 +----------------------------+
 | ...                        |
 +----------------------------+
+| Keyframe Index 1           |  Optional compressed keyframe indices and PTS values
++----------------------------+
+| Keyframe Index 2           |
++----------------------------+
 | Physical Length Index      |  Delta-Varint video lengths
 +----------------------------+
+| Keyframe-Index Length Index |  Delta-Varint keyframe-index lengths
++----------------------------+
 | Run Length Index           |  Delta-Varint logical row counts
 +----------------------------+
 | Run Reference Index        |  Delta-Varint physical video ordinals
 +----------------------------+
 | Run First-Frame Index      |  Delta-Varint frame ordinals
 +----------------------------+
 | Physical Index Length      |  4 bytes (Little Endian)
+| Keyframe Length-Index Size |  4 bytes (Little Endian)
 | Run-Length Index Length    |  4 bytes (Little Endian)
 | Run-Reference Index Length |  4 bytes (Little Endian)
 | First-Frame Index Length   |  4 bytes (Little Endian)
@@ -435,20 +442,32 @@ The run arrays have equal element counts. A non-negative run reference is an ord
 physical length index. For logical row `r` in a run beginning at logical row `s`, the returned
 `VideoFrameDescriptor` identifies the referenced raw video range and frame ordinal
 `run_first_frame + (r - s)`. `-1` is a NULL run and `-2` is a data-evolution placeholder run.
-Non-negative runs have fixed frame stride one in version 1; a discontinuity starts another run.
+Non-negative runs have fixed frame stride one; a discontinuity starts another run. Version 2 may
+store one sparse keyframe index per physical video. Version 1 remains readable and omits the
+keyframe-index blocks and their length index.
+
+A keyframe-index block has a 13-byte little-endian header: version (`1`, uint8), magic
+(`0x564944454F4B4649`, uint64), and entry count (uint32).
+It is followed by zlib-compressed pairs of displayed frame ordinal and PTS (two int64 values).
+The index always describes the first video stream. PTS uses that stream's time base,
+read from the original container rather than stored again.
+Only keyframes have entries. The reader identifies an indexed decode start and counts decoded
+frames in presentation order to reach the target; it does not infer ordinals from average FPS.
 
 The serialized `VideoFrameDescriptor` stored in an Arrow/data-file cell has its own versioned
 wire layout. All numeric values are little endian:
 
 | Field | Size | Description |
 | --- | ---: | --- |
-| Version | 1 byte | Descriptor version, currently `1` |
+| Version | 1 byte | Descriptor version, currently `2` |
 | Magic | 8 bytes | `0x564944454F46524D` (`VIDEOFRM`) |
 | URI length | 4 bytes | UTF-8 URI byte length |
 | URI | variable | URI of the containing `.video` file |
 | Offset | 8 bytes | Start of the complete encoded-video payload |
 | Length | 8 bytes | Encoded-video payload length |
 | Frame index | 8 bytes | Zero-based presentation-order frame ordinal |
+| Keyframe-index offset | 8 bytes | Version 2 only: index offset in the `.video` file |
+| Keyframe-index length | 8 bytes | Version 2 only: index length |
 
 Descriptor bytes are independently versioned from the `.video` container. Java and Python share
 canonical descriptor and container fixtures to keep both implementations byte-compatible.
 
@@ -83,10 +83,32 @@ to write complete videos and their logical frame rows.
 
 Each logical value is a `VideoFrameDescriptor`: its URI range identifies one complete encoded
 video and its frame ordinal selects a frame inside that video. On write, a `.video` data region
-concatenates raw video payloads without ordinary BLOB entry wrappers. Four embedded delta-varint
-indexes record physical video lengths, logical run lengths, run-to-video references, and the first
-frame ordinal of each run. Consecutive frames therefore need one run entry rather than one index
-entry per row. NULL and data-evolution placeholders use negative run references.
+concatenates raw video payloads without ordinary BLOB entry wrappers. Compact indexes map rows to
+videos and frame ordinals. Version 2 additionally stores compressed keyframe indices and PTS values
+once per physical video, not per-frame mappings. Consecutive frames share one run entry; NULL and data-evolution
+placeholders use negative run references.
+
+<pre>
+.video (version 2, in file order)
+├─ Complete encoded videos A, B, ...
+├─ <strong>NEW: Keyframe index blocks A, B, ...</strong>
+│  └─ Compressed keyframe indices and PTS values
+├─ Video payload lengths
+├─ <strong>NEW: Keyframe index block lengths</strong>
+├─ Consecutive-row counts
+├─ Video references for those rows
+├─ Starting frame ordinals for those rows
+└─ Footer
+   ├─ Byte lengths of the five index arrays above
+   │  └─ <strong>NEW: Length of the keyframe-block-length index</strong>
+   └─ Magic and format version
+</pre>
+
+Each video has its own index block; blocks follow payload order. Their lengths locate individual
+blocks without reading the other videos' indexes. The footer locates the index arrays, not individual
+frames. Row indexes select a video and target frame; keyframe indexes select where decoding starts.
+Index generation and indexed reads use the first video stream. Its stream index and PTS time base
+are obtained from the original container, not stored in the index.
 
 ## Reuse, Rolling, and Compaction
 
@@ -102,9 +124,10 @@ together. The resulting file group remains row-aligned and a single large episod
 configured target.
 
 When BLOB compaction is enabled, it byte-copies the complete encoded-video ranges into a new self-contained `.video` pack
-and rebuilds the embedded indexes; it does not decode or re-encode frames. The aligned normal data
+and rebuilds the embedded indexes; it does not decode or re-encode frames. Persisted keyframe indexes
+are copied into the new pack. The aligned normal data
 file contains only application columns such as `episode_id`, state, and action. Paimon stores the
-frame mapping in the `.video` descriptor/index path.
+keyframe index in the `.video` descriptor/index path.
 `blob-compaction.enabled` defaults to `false`; ordinary normal-file compaction can
 leave the video packs unchanged. See [Data Evolution Maintenance](./data-evolution-maintenance#ordinary-compaction).
 
@@ -115,8 +138,7 @@ leave the video packs unchanged. See [Data Evolution Maintenance](./data-evoluti
   `.blob`.
 - Non-null writes must be exact descriptor-backed `BlobRef` values containing a
   `VideoFrameDescriptor`. Inline bytes and ordinary `BlobDescriptor` values are rejected.
-- Version 1 addresses frames by zero-based presentation-order ordinal with stride one. It does not
-  store PTS values or parse codec/container metadata.
+- Version 1 remains readable but has no persisted keyframe index.
 - A `BlobConsumer` callback is not supported for the video field.
 
 ## Read Frames
@@ -130,6 +152,27 @@ not contain decoded image pixels. Read behavior differs by API:
 | PyPaimon reads of `.video` fields | Return serialized `VideoFrameDescriptor` values even when `blob-as-descriptor=false`. |
 | Java internal-row API | `row.getBlob(position)` returns a descriptor-backed `BlobRef`; call `toDescriptor()` to access the frame descriptor. `toData()` reads the complete video payload. |
 
+PyPaimon decodes supported videos once during ingestion to record accurate keyframe ordinals.
+PyAV reuses this sparse index: seek to an indexed start, verify its timestamp, and count decoded
+frames to the target. Missing indexes use the existing scan path. Explicitly selecting TorchCodec
+keeps its exact mode, including its initialization scan; it does not consume the sparse index.
+Indexed TorchCodec reads also require PyAV to resolve the first video stream from the container header.
+
+```text
+Table row
+  → Video A, target frame 1003
+  → A's keyframe index: preceding keyframe 1000, PTS t
+  → Seek and verify the decoded start against the index
+  → Decode in presentation order: 1000 → 1001 → 1002 → 1003
+  → Return frame 1003
+```
+
+Frame ordinals come from ingestion-time decoding, not timestamp × average frame rate.
+If seeking skips the selected start, PyAV retries an earlier indexed start; an unidentifiable
+start fails rather than returning a guessed frame. This avoids rebuilding the frame index on
+first access, but still decodes the target's dependencies. Index storage grows with keyframe count,
+not total frame count. Unsupported index generation falls back to unindexed storage.
+
 After ingesting data, query descriptors without loading a complete video for every row:
 
 <Tabs groupId="video-read">
 
@@ -223,9 +223,12 @@ loader = DataLoader(dataset, batch_size=32, shuffle=True, num_workers=4)
 ```
 
 Without `tag_name`, the latest snapshots are used. Frame lookups use the BTree
-on `index`; payloads remain lazy. Video decoding prefers TorchCodec, falls back
-to PyAV, and reuses a bounded decoder cache. Set `video_backend` to force
-either decoder.
+on `index`; payloads remain lazy. With a persisted keyframe index, automatic video
+decoding prefers PyAV to seek and count frames without an initialization scan.
+Without an index, it prefers TorchCodec and falls back to PyAV. Both reuse a bounded
+decoder cache. If PyAV is unavailable, or `video_backend="torchcodec"` is explicit,
+TorchCodec retains exact mode and its
+initialization scan; `video_backend="pyav"` uses the sparse index when available.
 
 Subclass `PaimonDatasetReader` for a custom logical frame layout:
 
 
@@ -35,17 +35,58 @@ public class VideoFrameDescriptor extends BlobDescriptor {
 
     private static final long serialVersionUID = 1L;
     private static final long MAGIC = 0x564944454F46524DL; // "VIDEOFRM"
-    private static final byte CURRENT_VERSION = 1;
-    private static final int FIXED_LENGTH =
+    private static final byte CURRENT_VERSION = 2;
+    private static final int V1_FIXED_LENGTH =
             Byte.BYTES + Long.BYTES + Integer.BYTES + 3 * Long.BYTES;
+    private static final int V2_FIXED_LENGTH = V1_FIXED_LENGTH + 2 * Long.BYTES;
 
     private final long frameIndex;
+    private final long keyframeIndexOffset;
+    private final long keyframeIndexLength;
+    private final byte version;
 
     public VideoFrameDescriptor(String uri, long offset, long length, long frameIndex) {
+        this(uri, offset, length, frameIndex, -1, 0, (byte) 1);
+    }
+
+    public VideoFrameDescriptor(
+            String uri,
+            long offset,
+            long length,
+            long frameIndex,
+            long keyframeIndexOffset,
+            long keyframeIndexLength) {
+        this(
+                uri,
+                offset,
+                length,
+                frameIndex,
+                keyframeIndexOffset,
+                keyframeIndexLength,
+                keyframeIndexLength == 0 ? (byte) 1 : CURRENT_VERSION);
+    }
+
+    private VideoFrameDescriptor(
+            String uri,
+            long offset,
+            long length,
+            long frameIndex,
+            long keyframeIndexOffset,
+            long keyframeIndexLength,
+            byte version) {
         super(uri, offset, length);
         checkArgument(
                 frameIndex >= 0, "Video frame index must be non-negative, but was %s.", frameIndex);
+        checkArgument(
+                keyframeIndexLength >= 0, "Video keyframe index length must be non-negative.");
+        checkArgument(
+                (keyframeIndexLength == 0 && keyframeIndexOffset == -1)
+                        || (keyframeIndexLength > 0 && keyframeIndexOffset >= 0),
+                "Invalid video keyframe index range.");
         this.frameIndex = frameIndex;
+        this.keyframeIndexOffset = keyframeIndexOffset;
+        this.keyframeIndexLength = keyframeIndexLength;
+        this.version = version;
     }
 
     public long frameIndex() {
@@ -57,6 +98,22 @@ public BlobDescriptor payloadDescriptor() {
         return new BlobDescriptor(uri(), offset(), length());
     }
 
+    public @Nullable BlobDescriptor keyframeIndexDescriptor() {
+        return keyframeIndexLength == 0
+                ? null
+                : new BlobDescriptor(uri(), keyframeIndexOffset, keyframeIndexLength);
+    }
+
+    /** Returns the persisted keyframe index carried by an exact frame reference. */
+    public static @Nullable Blob keyframeIndexBlob(Blob blob) {
+        VideoFrameDescriptor frame = fromBlob(blob);
+        BlobDescriptor mapping = frame == null ? null : frame.keyframeIndexDescriptor();
+        if (mapping == null) {
+            return null;
+        }
+        return Blob.fromDescriptor(((BlobRef) blob).uriReader(), mapping);
+    }
+
     /** Returns the video frame carried by an exact lazy blob reference, or {@code null}. */
     public static @Nullable VideoFrameDescriptor fromBlob(@Nullable Blob blob) {
         if (blob == null || blob.getClass() != BlobRef.class) {
@@ -77,30 +134,35 @@ public BlobDescriptor payloadDescriptor() {
     @Override
     public byte[] serialize() {
         byte[] uriBytes = uri().getBytes(StandardCharsets.UTF_8);
+        int fixedLength = version == 1 ? V1_FIXED_LENGTH : V2_FIXED_LENGTH;
         ByteBuffer buffer =
-                ByteBuffer.allocate(FIXED_LENGTH + uriBytes.length).order(ByteOrder.LITTLE_ENDIAN);
-        buffer.put(CURRENT_VERSION);
+                ByteBuffer.allocate(fixedLength + uriBytes.length).order(ByteOrder.LITTLE_ENDIAN);
+        buffer.put(version);
         buffer.putLong(MAGIC);
         buffer.putInt(uriBytes.length);
         buffer.put(uriBytes);
         buffer.putLong(offset());
         buffer.putLong(length());
         buffer.putLong(frameIndex);
+        if (version >= 2) {
+            buffer.putLong(keyframeIndexOffset);
+            buffer.putLong(keyframeIndexLength);
+        }
         return buffer.array();
     }
 
     public static VideoFrameDescriptor deserialize(byte[] bytes) {
-        if (bytes == null || bytes.length < FIXED_LENGTH) {
+        if (bytes == null || bytes.length < V1_FIXED_LENGTH) {
             throw invalidPayload("too short");
         }
 
         ByteBuffer buffer = ByteBuffer.wrap(bytes).order(ByteOrder.LITTLE_ENDIAN);
         byte version = buffer.get();
-        if (version != CURRENT_VERSION) {
+        if (version < 1 || version > CURRENT_VERSION) {
             throw new UnsupportedOperationException(
-                    "Expecting VideoFrameDescriptor version to be "
+                    "Expecting VideoFrameDescriptor version in [1, "
                             + CURRENT_VERSION
-                            + ", but found "
+                            + "], but found "
                             + version
                             + ".");
         }
@@ -117,7 +179,8 @@ public static VideoFrameDescriptor deserialize(byte[] bytes) {
         if (uriLength > buffer.remaining()) {
             throw invalidPayload("URI length exceeds data size");
         }
-        if (buffer.remaining() - uriLength < 3 * Long.BYTES) {
+        int trailingLength = version == 1 ? 3 * Long.BYTES : 5 * Long.BYTES;
+        if (buffer.remaining() - uriLength < trailingLength) {
             throw invalidPayload("missing offset/length/frame index");
         }
 
@@ -127,21 +190,29 @@ public static VideoFrameDescriptor deserialize(byte[] bytes) {
         long offset = buffer.getLong();
         long length = buffer.getLong();
         long frameIndex = buffer.getLong();
+        long keyframeIndexOffset = -1;
+        long keyframeIndexLength = 0;
+        if (version >= 2) {
+            keyframeIndexOffset = buffer.getLong();
+            keyframeIndexLength = buffer.getLong();
+        }
         if (buffer.hasRemaining()) {
             throw invalidPayload("trailing bytes");
         }
         if (frameIndex < 0) {
             throw invalidPayload("negative frame index: " + frameIndex);
         }
-        return new VideoFrameDescriptor(uri, offset, length, frameIndex);
+        return new VideoFrameDescriptor(
+                uri, offset, length, frameIndex, keyframeIndexOffset, keyframeIndexLength, version);
     }
 
     public static boolean isVideoFrameDescriptor(byte[] bytes) {
         if (bytes == null || bytes.length < Byte.BYTES + Long.BYTES) {
             return false;
         }
         ByteBuffer buffer = ByteBuffer.wrap(bytes).order(ByteOrder.LITTLE_ENDIAN);
-        return buffer.get() == CURRENT_VERSION && buffer.getLong() == MAGIC;
+        byte version = buffer.get();
+        return version >= 1 && version <= CURRENT_VERSION && buffer.getLong() == MAGIC;
     }
 
     @Override
@@ -154,12 +225,13 @@ public boolean equals(Object o) {
         }
         VideoFrameDescriptor that = (VideoFrameDescriptor) o;
         return frameIndex == that.frameIndex
-                && payloadDescriptor().equals(that.payloadDescriptor());
+                && payloadDescriptor().equals(that.payloadDescriptor())
+                && Objects.equals(keyframeIndexDescriptor(), that.keyframeIndexDescriptor());
     }
 
     @Override
     public int hashCode() {
-        return Objects.hash(payloadDescriptor(), frameIndex);
+        return Objects.hash(payloadDescriptor(), frameIndex, keyframeIndexDescriptor());
     }
 
     @Override
 
@@ -49,6 +49,12 @@ public void testRoundTripAndPayloadIdentity() {
                 new VideoFrameDescriptor("oss://bucket/source.mp4", 17, 103, 43);
         assertThat(next).isNotEqualTo(frame);
         assertThat(next.payloadDescriptor()).isEqualTo(frame.payloadDescriptor());
+
+        VideoFrameDescriptor indexed =
+                new VideoFrameDescriptor("oss://bucket/source.mp4", 17, 103, 42, 120, 8);
+        assertThat(VideoFrameDescriptor.deserialize(indexed.serialize())).isEqualTo(indexed);
+        assertThat(indexed.keyframeIndexDescriptor())
+                .isEqualTo(new BlobDescriptor("oss://bucket/source.mp4", 120, 8));
     }
 
     @Test