Repository navigation
Transition CLI to 1-based Frame Numbers #265
Description
Problem:
In PySceneDetect v0.5, frame numbers started from frame 0 in the CLI output. This led to some inconsistencies when interfacing with other programs (e.g. ffmpeg) which assume 1-based indices.
Proposal:
The reported end time/frame # should include the presentation time. Thus for a single-frame scene that is the first frame of the video, it should have start/end frames of 1/1 and a start/end time, assuming 10 FPS, of 0.0/0.1 seconds.
The first frame of a video should be called frame 1 with a presentation time of 0.0 seconds (and presentation duration of 0.1s). If we have a video at 10 frames/sec, the second frame (frame 2) should have a presentation time of 0.1s and be displayed until 0.2s. See the frames extracted from counter.mp4 for an example of such a video.
Example:
Assume we have a video at 10 frames/second, which is 0.7 seconds long in total (including the display time of the last frame), and has 4 scenes of length 1, 2, 1, and 3 frames, respectively. We should have the following invariants on the timecodes/frame numbers's that are output for each scene via the CLI / list-scenes:
| Scene Number |
Start (sec) |
Start (frame) |
End (sec) |
End (frame) |
Duration (sec) |
Duration (frames) |
|---|---|---|---|---|---|---|
| 1 | 0.0 | 1 | 0.1 | 1 | 0.1 | 1 |
| 2 | 0.1 | 2 | 0.3 | 3 | 0.2 | 2 |
| 3 | 0.3 | 4 | 0.4 | 4 | 0.1 | 1 |
| 4 | 0.4 | 5 | 0.7 | 7 | 0.3 | 3 |
See original discussion in #264 for more details.
Internally, the scenedetect API uses 0-based frame indexing. Thus the above scene list when returned from calling detect_scenes on a SceneManager will yield the following FrameTimecode results (there is no change between 0.5 and 0.6):
| Scene | Start (timecode) |
Start (frame) |
End (timecode) |
End (frame) |
|---|---|---|---|---|
| 0 | 0.0 | 0 | 0.1 | 1 |
| 1 | 0.1 | 1 | 0.3 | 3 |
| 2 | 0.3 | 3 | 0.4 | 4 |
| 3 | 0.4 | 4 | 0.7 | 7 |
In the API, the first frame (PTS 0.0s) has a frame number of 0, and the end timecode object is reflective of the entire duration of the scene (thus end - start = duration).
Tasks:
- Ensure that end time is at least frame
1or> 0.0sif a timecode - Ensure that duration is at least one frame
1or> 0.0sif a timecode - Change frame numbers in statsfile to also start from 1
- Validate output against counter.mp4 and its frames
Activity
eksperimental commentedon Mar 14, 2022
Hi. Sorry, End frame from once scene cannot be the same start frame of the next scene.
the Example above should be:
scene 1 | start frame: 1 | end frame: 1 | duration frames: 1
scene 2 | start frame: 2 | end frame: 4 | duration frames: 3
eksperimental commentedon Mar 14, 2022
In short, a frame cannot belong to two different scenes.
Breakthrough commentedon Mar 14, 2022
@eksperimental Good point, thanks for the suggestion - that certainly helps the math work out easier as well. Just need to make sure that it's documented correctly. I had originally written that table in the form the internal API would see it, not the scene list output.
Edit: I've clarified by showing both tables.
[cli] Transition to 1-based frame numbers. #265
[-]Transition to 1-based Frame Numbers[/-][+]Transition CLI to 1-based Frame Numbers[/+]