[docs] Fix some migration guide errors

Author: Breakthrough

docs/api/migration_guide.rst

@@ -80,7 +80,7 @@ The ``frame_num`` parameter (``int``) has been replaced with ``timecode`` (:clas
         def process_frame(self, timecode: FrameTimecode, frame_img) -> List[FrameTimecode]:
             ...
 
-The same change applies to ``post_process()``. If you need the frame number, use ``timecode.frame_num``.
+The same change applies to ``post_process()``. Using units of time instead of frame numbers is critical for temporal accuracy. If you need the frame number, use ``timecode.frame_num`` to the timecode to an integer.
 
 ``SceneDetector`` is Now Abstract
 -----------------------------------------------------------------------
@@ -104,20 +104,19 @@ The following have been removed from the ``SceneDetector`` interface:
 Read-Only Properties
 -----------------------------------------------------------------------
 
-``frame_num`` and ``framerate`` are now read-only properties. To change them, construct a new ``FrameTimecode``:
+:attr:`~scenedetect.common.FrameTimecode.frame_num` and :attr:`~scenedetect.common.FrameTimecode.framerate` are now read-only properties. To change them, construct a new ``FrameTimecode``:
 
 .. code:: python
 
-    # v0.6 - direct assignment
-    tc.frame_num = 100  # No longer works
-
-    # v0.7 - construct new instance
-    tc = FrameTimecode(100, tc.framerate)
+    tc = FrameTimecode(0, 24.0)
+    # Can no longer reassign frame_num, must create a new FrameTimecode instead:
+    #tc.frame_num = 100
+    tc = FrameTimecode(100, tc)
 
 New Properties
 -----------------------------------------------------------------------
 
-Access ``frame_num``, ``framerate``, and ``seconds`` as properties instead of getter methods:
+Access :attr:`~scenedetect.common.FrameTimecode.frame_num`, :attr:`~scenedetect.common.FrameTimecode.framerate`, and :attr:`~scenedetect.common.FrameTimecode.seconds` as properties instead of getter methods:
 
 .. code:: python
 
@@ -139,7 +138,7 @@ Framerate and Timestamp Changes
 Rational Framerates
 -----------------------------------------------------------------------
 
-``VideoStream.frame_rate`` now returns a ``Fraction`` instead of ``float``. Common NTSC rates (23.976, 29.97, 59.94) are automatically detected from float values:
+:attr:`~scenedetect.video_stream.VideoStream.frame_rate` now returns a ``Fraction`` instead of ``float``. Common NTSC rates (23.976, 29.97, 59.94) are automatically detected from float values:
 
 .. code:: python
 
@@ -151,16 +150,16 @@ Rational Framerates
 PTS-Backed Timestamps
 -----------------------------------------------------------------------
 
-All backends now return presentation timestamp (PTS) backed values from ``VideoStream.position``. This enables correct handling of VFR videos.
+All backends now return presentation timestamp (PTS) backed values from :attr:`~scenedetect.video_stream.VideoStream.position`. This enables correct handling of VFR videos.
 
-``FrameTimecode`` has new ``time_base`` and ``pts`` properties for accessing the underlying timing information. For VFR videos, ``frame_num`` is now an approximation based on PTS-derived time rather than a sequential count.
+``FrameTimecode`` has new :attr:`~scenedetect.common.FrameTimecode.time_base` and :attr:`~scenedetect.common.FrameTimecode.pts` properties for accessing the underlying timing information. For VFR videos, :attr:`~scenedetect.common.FrameTimecode.frame_num` is now an approximation based on PTS-derived time rather than a sequential count.
 
 
 =======================================================================
 ``StatsManager`` Changes
 =======================================================================
 
-The ``StatsManager`` methods ``get_metrics()``, ``set_metrics()``, and ``metrics_exist()`` now formally accept either a ``FrameTimecode`` or a plain ``int`` frame number for the timecode argument. Passing a ``FrameTimecode`` is preferred and matches the detector interface; the ``int`` form is retained for compatibility with the deprecated ``load_from_csv()`` path, which keys metrics by integer frame number.
+The ``StatsManager`` methods :meth:`~scenedetect.stats_manager.StatsManager.get_metrics`, :meth:`~scenedetect.stats_manager.StatsManager.set_metrics`, and :meth:`~scenedetect.stats_manager.StatsManager.metrics_exist` now formally accept either a ``FrameTimecode`` or a plain ``int`` frame number for the timecode argument. Passing a ``FrameTimecode`` is preferred and matches the detector interface; the ``int`` form is retained for compatibility with the deprecated ``load_from_csv()`` path, which keys metrics by integer frame number.
 
 ``StatsManager.load_from_csv()`` also accepts ``os.PathLike`` (e.g. ``pathlib.Path``) in addition to ``str`` / ``bytes`` / file handles.
 
@@ -169,21 +168,21 @@ The ``StatsManager`` methods ``get_metrics()``, ``set_metrics()``, and ``metrics
 ``SceneDetector`` Annotation Fixes
 =======================================================================
 
-``SceneDetector.post_process()`` now declares its parameter as ``timecode: FrameTimecode`` (previously typed as ``int``). The method already received a ``FrameTimecode`` at runtime and concrete detectors (e.g. ``ThresholdDetector``, ``ContentDetector``) already used the ``FrameTimecode`` type - only the abstract-base-class annotation was inconsistent. No call-site changes are needed; this just brings the signature into agreement with the documented and actual behavior.
+:meth:`~scenedetect.detector.SceneDetector.post_process` now declares its parameter as ``timecode: FrameTimecode`` (previously typed as ``int``). The method already received a ``FrameTimecode`` at runtime and concrete detectors (e.g. ``ThresholdDetector``, ``ContentDetector``) already used the ``FrameTimecode`` type - only the abstract-base-class annotation was inconsistent. No call-site changes are needed; this just brings the signature into agreement with the documented and actual behavior.
 
 
 =======================================================================
 ``SceneManager.detect_scenes()`` Time Arguments
 =======================================================================
 
-The ``duration`` and ``end_time`` arguments now formally accept ``int`` (frames), ``float`` (seconds), ``str`` (timecode string, e.g. ``"00:00:05.000"``), or ``FrameTimecode``. The internal code already validated these forms; the annotation was previously narrower than the documented behavior.
+The ``duration`` and ``end_time`` arguments of :meth:`~scenedetect.scene_manager.SceneManager.detect_scenes` now formally accept ``int`` (frames), ``float`` (seconds), ``str`` (timecode string, e.g. ``"00:00:05.000"``), or ``FrameTimecode``. The internal code already validated these forms; the annotation was previously narrower than the documented behavior.
 
 .. code:: python
 
     # All of these were always supported at runtime; now they type-check too:
-    scene_manager.detect_scenes(video=video, end_time=15.0)         # seconds
-    scene_manager.detect_scenes(video=video, end_time=1500)         # frames
-    scene_manager.detect_scenes(video=video, end_time="00:01:00")   # timecode
+    scene_manager.detect_scenes(video, end_time=15.0)         # seconds
+    scene_manager.detect_scenes(video, end_time=1500)         # frames
+    scene_manager.detect_scenes(video, end_time="00:01:00")   # timecode
 
 
 =======================================================================
@@ -212,7 +211,7 @@ The following deprecated APIs have been fully removed in v0.7:
    * - ``video_manager`` parameter (various functions)
      - Use ``video`` parameter instead
    * - ``SceneManager.get_event_list()``
-     - Use ``SceneManager.get_cut_list()`` or ``SceneManager.get_scene_list()``
+     - Use :meth:`~scenedetect.scene_manager.SceneManager.get_cut_list` or :meth:`~scenedetect.scene_manager.SceneManager.get_scene_list`
    * - ``AdaptiveDetector.get_content_val()``
      - Use ``StatsManager`` to query metrics
    * - ``AdaptiveDetector(min_delta_hsv=...)``

docs/conf.py

@@ -37,6 +37,7 @@
 extensions = [
     "sphinx.ext.napoleon",
     "sphinx.ext.autodoc",
+    "sphinx_copybutton",
 ]
 
 autoclass_content = "both"

pyproject.toml

@@ -52,7 +52,7 @@ dependencies = [
 pyav = ["av>=9.2"]
 moviepy = ["moviepy"]
 dev = ["av>=9.2", "moviepy", "pytest>=7.0"]
-docs = ["Sphinx==7.0.1"]
+docs = ["Sphinx==7.0.1", "sphinx-copybutton==0.5.2"]
 website = ["mkdocs==1.5.2", "jinja2>=3.1.6"]
 
 [project.urls]

website/pages/changelog.md

@@ -669,16 +669,16 @@ Development
 
 ### Release Notes
 
-PySceneDetect is a major breaking release which overhauls how timestamps are handled throughout the API. This allows PySceneDetect to properly process variable framerate (VFR) videos. A significant amount of technical debt has been addressed, including removal of deprecated or overly complicated APIs.
+PySceneDetect 0.7 is a **major breaking release** which overhauls how timestamps are handled. This allows PySceneDetect to properly process variable framerate (VFR) videos. A significant amount of technical debt has been addressed, including removal of deprecated or overly complicated APIs.
 
 Care was taken to minimize changes for most common API uses, however more advanced use cases may run into breaking changes. Please review [the Migration Guide](https://www.scenedetect.com/docs/0.7/api/migration_guide.html) when updating from v0.6. Minimum supported Python version is now **Python 3.10**.
 
 ### CLI Changes
 
 - [feature] VFR videos are handled correctly by the OpenCV and PyAV backends, and should work correctly with default parameters
+- [feature] All CLI options which used to accept frame numbers only now accept seconds (e.g. `0.6s`) and timecodes (e.g. `00:00:00.600`) [#531](https://github.com/Breakthrough/PySceneDetect/issues/531)
 - [feature] New `save-fcp` command allows exporting in Final Cut Pro format (FCP7/FCPX) [#156](https://github.com/Breakthrough/PySceneDetect/issues/156)
-- [feature] `--min-scene-len`/`-m` and `save-images --frame-margin`/`-m` now accept seconds (e.g. `0.6s`) and timecodes (e.g. `00:00:00.600`) in addition to a frame count [#531](https://github.com/Breakthrough/PySceneDetect/issues/531)
-- [feature] `save-edl` accepts a new `--start-timecode`/`-s` flag (SMPTE `HH:MM:SS:FF` or 8-digit `HHMMSSFF`) to stamp every event with a custom start timecode so generated EDLs align with the source media's on-screen timecode [#515](https://github.com/Breakthrough/PySceneDetect/issues/515)
+- [feature] Add `save-edl` option  `--start-timecode`/`-s` to providde a custom start timecode for generated EDLs, supports SMPTE `HH:MM:SS:FF` or 8-digit `HHMMSSFF` input [#515](https://github.com/Breakthrough/PySceneDetect/issues/515)
 - [bugfix] Fix floating-point precision error in `save-otio` output where frame values near integer boundaries (e.g. `90.00000000000001`) were serialized with spurious precision
 - [bugfix] Add mitigation for transient `OSError` in the MoviePy backend as it is susceptible to subprocess pipe races on slow or heavily loaded systems [#496](https://github.com/Breakthrough/PySceneDetect/issues/496)
 - [bugfix] `detect-threshold` cut frame numbers are now backend-deterministic; previously the cut could differ by 1 frame between PyAV and OpenCV when the fade midpoint landed on a `.5` rounding boundary (PyAV uses sub-microsecond PTS, OpenCV uses millisecond-truncated `CAP_PROP_POS_MSEC`)