Skip to content

Handle secondary and recursive SeekHead elements in MatroskaExtractor - #3479

Open
rashidekbal wants to merge 5 commits into
androidx:mainfrom
rashidekbal:fix/recursive-seekhead-mkv
Open

rashidekbal wants to merge 5 commits into
androidx:mainfrom
rashidekbal:fix/recursive-seekhead-mkv

Conversation

@rashidekbal

@rashidekbal rashidekbal commented Oct 21, 2026 •

Copy link
Copy Markdown

Issue: #1143

Problem

Certain Matroska (.mkv) files, especially large WEB-DL and high-definition encodes created by mkvmerge, place their Cues element reference inside a secondary (chained/recursive) SeekHead rather than the primary SeekHead at the beginning of the file.

When reading these files, MatroskaExtractor only recorded ID_CUES and ID_TRACKS seek entries from the primary SeekHead. It ignored ID_SEEK_HEAD entries. Consequently, cuesContentPosition remained unset (C.INDEX_UNSET). When buildSeekMap() was invoked, MatroskaExtractor concluded that the file lacked cues and initialized an unseekable SeekMap.Unseekable(durationUs), rendering the media non-seekable despite valid cues existing in the container.

Solution

  1. Detect Chained SeekHead: In MatroskaExtractor.endMasterElement(), check for seekEntryId == ID_SEEK_HEAD. When cuesContentPosition == C.INDEX_UNSET, record secondarySeekHeadPosition = seekEntryPosition.
  2. Execute Secondary SeekHead Read: If cuesContentPosition has not been located but secondarySeekHeadPosition is known, initiate a seek via maybeSeekForSecondarySeekHead() to parse the secondary SeekHead and discover the true cuesContentPosition.
  3. Defer SeekMap Fallback: Update buildSeekMap() and early format emission guards so that seeking is not prematurely disabled as unseekable before attempting to parse the secondary SeekHead.
  4. Position Restoration: After reading the secondary SeekHead, restore the input position back to the previous track reading offset.

Testing

  • Verified with Matroska WEB-DL files (1080p / 4K) containing secondary SeekHead pointing to Cues.
  • Confirmed that cuesContentPosition is successfully resolved, Cues are parsed, seek map entries are built, and seeking functions accurately without regression.

@google-cla

google-cla Bot commented Oct 21, 2026

Copy link
Copy Markdown

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@rashidekbal
rashidekbal marked this pull request as draft October 21, 2026 13:33
@rashidekbal rashidekbal reopened this Oct 21, 2026
@rashidekbal
rashidekbal marked this pull request as ready for review October 21, 2026 13:34
@FongMi

FongMi commented Oct 24, 2026

Copy link
Copy Markdown

I reviewed e71404db588a and tested the extractor in isolation with the Media3 test utilities and a modified media/mkv/sample.mkv. I found two issues worth addressing before merging:

  1. Samples can be emitted before their track format. When the primary SeekHead references a secondary SeekHead, the new maybeSendFormatsEarly condition suppresses format output at the end of Tracks. After reading the secondary SeekHead, maybeSeekForSecondarySeekHead() returns directly to the saved Cluster position, without scheduling the newly discovered Cues first. Extraction then reaches a sample while its format is still pending. With FakeExtractorOutput, a single-hop SeekHead → SeekHead → Cues fixture fails with:

    IllegalStateException: TrackOutput must receive format before sampleMetadata
    

    A secondary SeekHead containing only Cluster entries also reproduces this. Could the index-resolution flow schedule Cues parsing, or finish the no-Cues fallback and emit the required formats, before resuming sample output?

  2. Traversal stops after one secondary SeekHead. readSecondarySeekHead becomes true when the first secondary SeekHead ends. For A → B → C → Cues, the reference to C is recorded, but !readSecondarySeekHead prevents following it. In a fixture with B at byte 100000 and C at byte 100100, the extractor requested only [100000, 5569] (B, then the saved Cluster position), never C. Tracking pending and visited index positions would allow multiple hops while terminating cycles; traversal should also have a bound and handle explicit seek/reset correctly.

For regression coverage, the existing sample.mkv can be modified by replacing its primary Cues seek entry with a reference to an added SeekHead, while keeping Cues at its original location. It would help to cover:

  • One secondary SeekHead, asserting format-before-sample ordering and a seekable final map.
  • Multiple hops to Cues.
  • A secondary SeekHead with only Cluster entries and no Cues reference, preserving playback.
  • Cycles and interrupted/repeated seeks.

These were focused extractor probes, not a run of the full PR test suite.

@rashidekbal

Copy link
Copy Markdown
Author

Thanks for the detailed review and test findings!

I have updated the implementation to address both issues and added regression coverage in MatroskaExtractorNonParameterizedTest:

Index-Resolution & Format Emission Ordering:
maybeSeekForSecondarySeekHead() now retains the initial cluster position in seekPositionAfterBuildingCues.
When secondary SeekHead parsing concludes, if a Cues element was discovered, seekForCues is scheduled before resuming sample output.
If no Cues element is discovered across secondary SeekHead elements (or the SeekHead only references Cluster elements), the extractor finishes the fallback flow by setting SeekMap.Unseekable(durationUs) and emitting track formats (outputTrackFormats()) prior to seeking back to the cluster offset.
Bounded Multi-Hop Traversal & Cycle Handling:
Replaced the single-hop fields with a bounded queue (pendingSeekHeadPositions) and a visited history (visitedSeekHeadPositions).
Traversal terminates cycles using visited and pending checks, and is bounded by MAX_SEEK_HEAD_HOPS = 16.
Once Cues is discovered, pending seek head references are discarded to avoid redundant hops.
Explicit seek() resets index resolution state if called before the seek map is sent.
Regression Tests:
Added 5 non-parameterized tests covering:
Single-hop SeekHead → SeekHead → Cues with FakeExtractorOutput, asserting format-before-sample ordering and seekable SeekMap.
Multi-hop traversal (SeekHead → A → B → C → Cues).
Secondary SeekHead containing only Cluster entries (verifying unseekable playback without throwing IllegalStateException).
Circular SeekHead references (A → B → A), verifying graceful termination.
Interrupted seek at position 0 resetting traversal state and allowing re-extraction.

@FongMi

FongMi commented Oct 27, 2026

Copy link
Copy Markdown

Thanks for the update! I rechecked 5c43ea874506. The two issues from my earlier comment are addressed, and all six tests in MatroskaExtractorNonParameterizedTest (including the five new tests) pass in my focused setup.

I found two remaining cases involving malformed Cues references:

  1. A Cues reference pointing to a Cluster causes repeated seeks to the same position. With the primary SeekHead pointing to a secondary SeekHead, and the secondary entry using SeekID = Cues but a position of 5562 (the first Cluster), the probe recorded:

    [108536, 5562, 5562, 5562, 5562, ...]
    

    I stopped the probe after 1,000 RESULT_SEEK requests. On encountering that Cluster, maybePrepareSeekMap() schedules the same Cues position again. The SeekHead hop bound does not cover this path. This differs from a secondary SeekHead containing a correctly identified Cluster entry, which your new test already covers.

  2. Reaching EOF while resolving the index ends extraction without returning to the saved Cluster. If the secondary Cues reference points to an empty Void element at the end of the Segment, read() reaches RESULT_END_OF_INPUT with output.seekMap == null and no media samples emitted. The unresolved index load needs a terminal path before normal end-of-input handling.

For reproduction, I used media/mkv/sample.mkv, preserved its media bytes, replaced the primary Cues entry with a reference to a 21-byte secondary SeekHead appended at offset 108536, and extended the Segment size to include the appended data. The secondary entry identifies Cues but points either to Cluster offset 5562, or to an appended empty Void (EC 80) at offset 108557.

Could these paths finish index resolution by publishing an unseekable map, emitting the required formats, and restoring the saved media position? Regression tests should also assert that samples are emitted after fallback and that index seek requests terminate.

These are focused extractor checks: I used the PR extractor source with only its class name changed to coexist with the local extractor, and local dependency modules. I have not run the full upstream suite or device playback tests.

@rashidekbal

Copy link
Copy Markdown
Author

Thanks for testing those edge cases! Both issues—along with additional hardening against cyclic and malformed Cues references—have been addressed in b4b9d3dc78 and 582e6fa4d0:

  1. Cues reference pointing to a Cluster:

    • In maybePrepareSeekMap(), when seekPositionAfterBuildingCues != C.INDEX_UNSET and ID_CLUSTER is encountered, the extractor completes fallback by setting sentSeekMap = true, publishing an unseekable SeekMap, emitting track formats, and clearing cues/seekhead traversal state instead of re-scheduling a seek for cues.
    • In maybeSeekForCues(), we check seekPositionAfterBuildingCues != currentPosition before requesting a seek to avoid issuing redundant seek requests when already positioned at the saved Cluster.
  2. Reaching EOF while resolving the index:

    • In read(), if EOF (!continueReading) is encountered while seekPositionAfterBuildingCues != C.INDEX_UNSET, the terminal fallback path is triggered: an unseekable SeekMap and track formats are emitted, and seekPosition.position is restored to seekPositionAfterBuildingCues, returning RESULT_SEEK so sample reading from the saved Cluster resumes seamlessly.
    • Also ensured that if EOF is reached before a SeekMap was ever sent (e.g. truncated header-only input), fallback track formats and an unseekable SeekMap are published so output.seekMap is never left null.
  3. Additional Cues Traversal & Cycle Hardening:

    • In maybeSeekForCues(), cuesContentPosition is consumed (C.INDEX_UNSET) upon dispatching the seek, and its target is tracked in visitedSeekHeadPositions. This prevents infinite seek loops if a Cues reference points to another SeekHead that lacks Cues.
    • In endMasterElement(ID_SEEK), entries with SeekID == ID_CUES pointing to already-visited SeekHead positions are rejected, closing mutual/cyclic Cues paths under the same traversal bounds.
    • Validated seekEntryPosition against negative overflow and guarded visitedSeekHeadPositions bounds against MAX_SEEK_HEAD_HOPS.
  4. Unit Tests:

    • Extended MatroskaExtractorNonParameterizedTest with tests covering:
      • read_withCuesReferencePointingToCluster_terminatesSeeksAndOutputsSamples
      • read_withCuesReferenceReachingEof_terminatesFallbackAndOutputsSamples
      • read_withCuesReferencePointingToSecondarySeekHeadWithoutCues_terminatesAndOutputsSamples
      • read_withCyclicCuesReferences_terminatesSafelyAndOutputsSamples

@TharathielCB

Copy link
Copy Markdown

Hey what is the status on this PR? It would solve a lot of problems for clients like jellyfin etc.

@rashidekbal

rashidekbal commented Nov 15, 2026 •

Copy link
Copy Markdown
Author

@TharathielCB i am also waiting for response

@icbaker

icbaker commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator

@rohitjoins hasn't had a chance to review this PR yet - but before that can happen, please can you re-target it to the main branch, as that's where we merge contributions, so we can't review it while it still targets the release branch.

@rashidekbal
rashidekbal changed the base branch from release to main November 16, 2026 12:15
@rashidekbal
rashidekbal changed the base branch from main to release November 16, 2026 12:23
When resolving secondary SeekHead elements, format emission was delayed
until Cues were parsed. If the secondary SeekHead pointed directly to
Cues or contained only Cluster entries, the extractor returned directly
to the saved Cluster position without scheduling Cues or completing the
no-Cues fallback first, causing samples to be emitted before track formats.

This commit updates the index-resolution flow to:
- Properly schedule Cues parsing or complete the no-Cues fallback (emitting
  track formats and unseekable SeekMap) before returning to sample reading.
- Support multi-hop SeekHead traversal up to a bounded depth (16 hops).
- Detect and prevent cycles using visited and pending position tracking.
- Reset index traversal state when an explicit seek to position 0 occurs
  before the seek map is finalized.
- Add regression test coverage in MatroskaExtractorNonParameterizedTest
  for single-hop, multi-hop, Cluster-only secondary SeekHead, cycles, and
  seek resets.

Fixes androidx#1143
When resolving the index (via secondary SeekHead or Cues):
- If a Cues reference points to a Cluster, encountering ID_CLUSTER during
  index resolution could cause maybePrepareSeekMap() to repeatedly schedule
  seeks to the same position. Now, encountering ID_CLUSTER while
  seekPositionAfterBuildingCues is set completes index resolution fallback
  (emitting unseekable SeekMap, track formats, and clearing index flags),
  and avoids redundant seeks if already at the saved Cluster position.
- If EOF is reached while resolving the index (such as a Cues pointer
  referencing an element at or past the end of input), the extractor now
  executes terminal fallback by emitting an unseekable SeekMap and track
  formats, and restores position to the saved Cluster to resume media playback.
- Add regression tests in MatroskaExtractorNonParameterizedTest covering
  both cases.

Fixes androidx#1143
- Consume cuesContentPosition upon scheduling seek and record target
  position in visitedSeekHeadPositions to prevent repeated seeks and
  cyclic Cues references.
- Reject Cues entries pointing to already-visited SeekHead positions.
- Guard visitedSeekHeadPositions array bounds against MAX_SEEK_HEAD_HOPS.
- Ensure seekMap and track formats are emitted if EOF is reached before
  seek map is sent.
- Validate seekEntryPosition in integerElement against negative values.
- Add regression tests in MatroskaExtractorNonParameterizedTest for
  Cues pointing to non-Cues SeekHead and mutual cyclic Cues references.

Fixes androidx#1143
@rashidekbal
rashidekbal force-pushed the fix/recursive-seekhead-mkv branch from 582e6fa to 1d70c25 Compare November 16, 2026 12:37
@rashidekbal
rashidekbal changed the base branch from release to main November 16, 2026 12:38
@rashidekbal

Copy link
Copy Markdown
Author

Thanks for pointing that out! I've rebased the branch onto main and updated the PR target to main. It should be clean and ready for review now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants