[Bugfix] Align OpenCV video metadata timeline

[VectorPeak]

Purpose

Fixes #46988.

video_get_metadata() should describe the same source-video timeline that video_to_ndarrays() uses when it samples frames.

Previously, video_to_ndarrays() sampled requested frames with:

np.linspace(0, total_frames - 1, num_frames, dtype=int)

but video_get_metadata() reported fps as duration / num_frames and frames_indices as list(range(num_frames)).

For sampled videos, this made metadata describe post-sampling positions instead of source-video frame positions. A 10-frame, 5 FPS video sampled down to 4 frames should report source frame indices [0, 3, 6, 9], not [0, 1, 2, 3]. Downstream Gemma4 video prompt expansion uses idx / fps for timestamps, so this mismatch can produce incorrect timestamp tokens compared with the original video timeline.

This PR adds a shared _sample_frame_indices() helper so frame loading and metadata use the same sampled frame indices, and preserves the source video's real OpenCV FPS in metadata.

Duplicate check: I checked #46988, open PRs mentioning #46988, and open PRs for video_get_metadata, frames_indices, video metadata fps, video_to_ndarrays, and vllm/assets/video.py. I did not find an open PR that already fixes sampled metadata FPS or frame-index alignment. Same-file PRs #36396 and #40764 are related to VideoCapture cleanup / OpenCV optional dependency handling, not this metadata timeline bug.

AI assistance was used to inspect the code path, check related open PRs/issues, implement the focused fix, and draft this description. The submitter reviewed the changed lines and validation before submission.

Test Plan

• Add a focused OpenCV regression test that creates a 10-frame, 5 FPS video and requests 4 sampled frames.
• Verify video_get_metadata() keeps the source FPS and duration, and reports linspace source-frame indices [0, 3, 6, 9].
• Run formatting/lint checks on the changed files.
• Attempt the targeted pytest for the new regression test.

Test Result

• git diff --check - passed.
• .venv\Scripts\python.exe -m ruff check vllm\assets\video.py tests\multimodal\media\test_video.py - passed.
• .venv\Scripts\python.exe -m ruff format --check vllm\assets\video.py tests\multimodal\media\test_video.py - passed.
• Isolated metadata reproduction - passed; video_get_metadata() returned fps: 5.0, duration: 2.0, and frames_indices: [0, 3, 6, 9].
• .venv\Scripts\python.exe -m pytest tests\multimodal\media\test_video.py::test_opencv_video_metadata_matches_sampled_frame_timeline -q - not completed locally; collection failed in this sparse checkout because vllm.v1 is not present in the local working tree.

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

PRs do not trigger a full CI run by default. Once the PR is approved and ready to go, your PR reviewer(s) can run CI to test the changes comprehensively before merging.

To run CI, PR reviewers can either: Add ready label to the PR or enable auto-merge.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

Agent Guidelines

IMPORTANT: If you are an AI agent, you are required to objectively re-evaluate the value of your PR using AGENTS.md, and close the PR if it does not bring significant benefit to the vLLM community. Failure to do so may result in an immediate ban.

🚀

[VectorPeak]

I also re-checked this against vLLM's AGENTS.md guidance. This is not a duplicate or cleanup-only PR: it addresses #46988 by fixing incorrect OpenCV video metadata that affects sampled-frame timestamps in Gemma4 video prompt expansion.

[Isotr0py]

Thanks for catching this!