Add deprecation warnings for legacy framerate aliases (#563)

Closes #548

## Summary

* Emit `DeprecationWarning` for deprecated `framerate` aliases across
`FrameTimecode`, `open_video()`, video backends, and the CLI.
* Preserve existing compatibility behavior, including `frame_rate`
taking precedence when both forms are provided.
* Add/update tests for the deprecated aliases, including
`VideoCaptureAdapter`.
* Update `get_framerate()` to direct users to `frame_rate` without
emitting duplicate warnings.

## Testing

* Added warning assertions for deprecated aliases.
* Verified canonical `frame_rate` usage remains warning-free.
* Verified legacy aliases continue to work while emitting
`DeprecationWarning`.

Author: Breakthrough

docs/cli.rst

@@ -67,7 +67,7 @@ Options
 
 .. option:: --framerate FPS
 
-  [DEPRECATED] Use :option:`-f/--frame-rate <-f>` instead.
+  Alias of :option:`-f/--frame-rate <-f>`.
 
 .. option:: -m TIMECODE, --min-scene-len TIMECODE
 

docs/cli/backends.rst

@@ -19,7 +19,7 @@ The `OpenCV <https://opencv.org/>`_ backend (usually `opencv-python <https://pyp
 
 It is mostly reliable and fast, although can occasionally run into issues processing videos with multiple audio tracks or small amounts of frame corruption. You can use a custom version of the ``cv2`` package, or install either the `opencv-python` or `opencv-python-headless` packages from `pip`.
 
-The OpenCV backend also supports image sequences as inputs (e.g. ``frame%02d.jpg`` if you want to load frame001.jpg, frame002.jpg, frame003.jpg...). Make sure to specify the framerate manually (``-f``/``--framerate``) to ensure accurate timing calculations.
+The OpenCV backend also supports image sequences as inputs (e.g. ``frame%02d.jpg`` if you want to load frame001.jpg, frame002.jpg, frame003.jpg...). Make sure to specify the framerate manually (``-f``/``--frame-rate``) to ensure accurate timing calculations.
 
 Variable framerate (VFR) video is supported. Scene detection uses PTS-derived timestamps from ``CAP_PROP_POS_MSEC`` for accurate timecodes. Seeking compensates for OpenCV's average-fps-based internal seek approximation, so output timecodes remain accurate across the full video.
 

scenedetect/__init__.py

@@ -15,6 +15,7 @@
 :class:`SceneManager <scenedetect.scene_manager.SceneManager>`.
 """
 
+import warnings
 from logging import getLogger
 
 # OpenCV is a required package, but we don't have it as an explicit dependency since we
@@ -115,8 +116,13 @@ def open_video(
         :class:`VideoOpenFailure`: Constructing the VideoStream fails. If multiple backends have
             been attempted, the error from the first backend will be returned.
     """
-    # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning when `framerate=` is
-    # used, once internal callers and downstream users have had a release to migrate.
+    if framerate is not None:
+        warnings.warn(
+            "`framerate` is deprecated and scheduled for removal in v0.9; "
+            "use `frame_rate` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
     if frame_rate is None:
         frame_rate = framerate
     # A list of paths is opened as a single concatenated stream. VideoStreamConcat handles

scenedetect/_cli/__init__.py

@@ -237,14 +237,15 @@ def print_command_help(ctx: click.Context, command: click.Command):
     default=None,
     help="Override frame rate with value as frames/sec.",
 )
+# Keep --framerate separate so Click can hide it while mapping both spellings to frame_rate.
 @click.option(
     "--framerate",
-    "framerate_legacy",
+    "frame_rate",
     metavar="FPS",
     type=click.FLOAT,
     default=None,
     hidden=True,
-    help="[DEPRECATED] Use -f/--frame-rate instead.",
+    help="Alias of -f/--frame-rate.",
 )
 @click.option(
     "--min-scene-len",
@@ -346,7 +347,6 @@ def scenedetect(
     stats: str | None,
     config: str | None,
     frame_rate: float | None,
-    framerate_legacy: float | None,
     min_scene_len: str | None,
     drop_short_scenes: bool | None,
     merge_last_scene: bool | None,
@@ -361,13 +361,6 @@ def scenedetect(
     ctx = ctx.obj
     assert isinstance(ctx, CliContext)
 
-    # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning when `--framerate`
-    # is used, once downstream users have had a release to migrate to `--frame-rate`.
-    if frame_rate is None:
-        frame_rate = framerate_legacy
-    elif framerate_legacy is not None:
-        logger.warning("Both --frame-rate and --framerate were specified; using --frame-rate.")
-
     ctx.handle_options(
         input_path=input,
         output=output,

scenedetect/backends/moviepy.py

@@ -19,6 +19,7 @@
 import os
 import time
 import typing as ty
+import warnings
 from fractions import Fraction
 from logging import getLogger
 
@@ -94,8 +95,13 @@ def __init__(
         """
         super().__init__()
 
-        # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning when `framerate=` is
-        # used, once internal callers and downstream users have had a release to migrate.
+        if framerate is not None:
+            warnings.warn(
+                "`framerate` is deprecated and scheduled for removal in v0.9; "
+                "use `frame_rate` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         if frame_rate is None:
             frame_rate = framerate
         # TODO: Investigate how MoviePy handles ffmpeg not being on PATH.

scenedetect/backends/opencv.py

@@ -101,8 +101,13 @@ def __init__(
             ValueError: specified frame rate is invalid
         """
         super().__init__()
-        # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning when `framerate=` is
-        # used, once internal callers and downstream users have had a release to migrate.
+        if framerate is not None:
+            warnings.warn(
+                "`framerate` is deprecated and scheduled for removal in v0.9; "
+                "use `frame_rate` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         if frame_rate is None:
             frame_rate = framerate
         if path_or_device is not None:
@@ -395,8 +400,13 @@ def __init__(
         """
         super().__init__()
 
-        # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning when `framerate=` is
-        # used, once internal callers and downstream users have had a release to migrate.
+        if framerate is not None:
+            warnings.warn(
+                "`framerate` is deprecated and scheduled for removal in v0.9; "
+                "use `frame_rate` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         if frame_rate is None:
             frame_rate = framerate
         if frame_rate is not None and frame_rate < MAX_FPS_DELTA:

scenedetect/backends/pyav.py

@@ -13,6 +13,7 @@
 
 import os
 import typing as ty
+import warnings
 from fractions import Fraction
 from logging import getLogger
 
@@ -89,8 +90,13 @@ def __init__(
         # refinement for frames FFmpeg flags as corrupt but still decodes.
         super().__init__()
 
-        # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning when `framerate=` is
-        # used, once internal callers and downstream users have had a release to migrate.
+        if framerate is not None:
+            warnings.warn(
+                "`framerate` is deprecated and scheduled for removal in v0.9; "
+                "use `frame_rate` instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         if frame_rate is None:
             frame_rate = framerate
         # Ensure specified frame rate is valid if set.

scenedetect/common.py

@@ -296,8 +296,12 @@ def framerate(self) -> float | None:
         property returns an exact :class:`fractions.Fraction` and matches the naming used by
         :attr:`scenedetect.video_stream.VideoStream.frame_rate`.
         """
-        # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning here once internal
-        # callers and downstream users have had a release to migrate to `frame_rate`.
+        warnings.warn(
+            "`framerate` is deprecated and scheduled for removal in v0.9; "
+            "use `frame_rate` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         if self._rate is None:
             return None
         return float(self._rate)
@@ -335,16 +339,18 @@ def get_frames(self) -> int:
     def get_framerate(self) -> float | None:
         """[DEPRECATED] Get Framerate: Returns the framerate used by the FrameTimecode object.
 
-        Use the `framerate` property instead.
+        Use the `frame_rate` property instead.
 
         :meta private:
         """
         warnings.warn(
-            "get_framerate() is deprecated, use the `framerate` property instead.",
+            "get_framerate() is deprecated, use the `frame_rate` property instead.",
             DeprecationWarning,
             stacklevel=2,
         )
-        return self.framerate
+        if self.frame_rate is None:
+            return None
+        return float(self.frame_rate)
 
     def equal_frame_rate(self, other: "float | Fraction | FrameTimecode") -> bool:
         """Determine whether the passed frame rate equals this object's frame rate.
@@ -368,8 +374,12 @@ def equal_frame_rate(self, other: "float | Fraction | FrameTimecode") -> bool:
 
     def equal_framerate(self, fps) -> bool:
         """[DEPRECATED] Use :meth:`equal_frame_rate` instead."""
-        # TODO(https://scenedetect.com/issue/548): emit DeprecationWarning here once internal
-        # callers and downstream users have had a release to migrate to `equal_frame_rate`.
+        warnings.warn(
+            "`equal_framerate()` is deprecated and scheduled for removal in v0.9; "
+            "use `equal_frame_rate()` instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
         return self.equal_frame_rate(fps)
 
     @property

scenedetect/video_stream.py

@@ -66,7 +66,7 @@ class FrameRateUnavailable(VideoOpenFailure):
 
     def __init__(self):
         super().__init__(
-            "Unable to obtain video framerate! Specify `framerate` manually, or"
+            "Unable to obtain video framerate! Specify `frame_rate` manually, or"
             " re-encode/re-mux the video and try again."
         )
 

tests/test_api.py

@@ -13,6 +13,8 @@
 
 These tests demonstrate common workflow patterns used when integrating the PySceneDetect API."""
 
+import pytest
+
 
 def test_api_detect(test_video_file: str):
     """Demonstrate usage of the `detect()` function to process a complete video."""
@@ -73,15 +75,17 @@ def test_api_scene_manager_start_end_time(test_video_file: str):
 
 
 def test_api_open_video_framerate_legacy_alias(test_video_file: str):
-    """`open_video(framerate=...)` is the soft-deprecated alias for `frame_rate=` (issue #548).
+    """`open_video(framerate=...)` is the deprecated alias for `frame_rate=` (issue #548).
     Both forms must produce equivalent streams; when both are provided, `frame_rate` wins."""
     from scenedetect import open_video
 
-    legacy = open_video(test_video_file, framerate=30.0)
+    with pytest.warns(DeprecationWarning, match="frame_rate"):
+        legacy = open_video(test_video_file, framerate=30.0)
     canonical = open_video(test_video_file, frame_rate=30.0)
     assert legacy.frame_rate == canonical.frame_rate
     # `frame_rate` takes precedence over `framerate` when both are provided.
-    both = open_video(test_video_file, frame_rate=30.0, framerate=24.0)
+    with pytest.warns(DeprecationWarning, match="frame_rate"):
+        both = open_video(test_video_file, frame_rate=30.0, framerate=24.0)
     assert both.frame_rate == canonical.frame_rate