Merge branch 'develop' into docs/improve-detect-and-annotate-tutorial

Borda · web-flow · commit ed13d64e39cf · 2026-05-19T14:18:06.000+02:00
diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml
@@ -64,13 +64,29 @@ jobs:
         run: |
           mike deploy --push latest
 
+      - name: 🏷️ Determine release deployment metadata
+        id: release_metadata
+        run: |
+          is_rc=false
+          release_tag=""
+          if [[ "$GITHUB_EVENT_NAME" == "release" ]]; then
+            release_tag="${GITHUB_REF_NAME#v}"
+            release_tag="${release_tag%.post*}"
+            release_tag_lower="${release_tag,,}"
+            # Match RC suffixes with separators (1.0-rc1, 1.0.rc1) or compact form (1.0rc1).
+            if [[ "$release_tag_lower" =~ (^|[._-])rc[0-9]+$ ]] || [[ "$release_tag_lower" =~ [0-9]rc[0-9]+$ ]]; then
+              is_rc=true
+            fi
+          fi
+          echo "is_rc=$is_rc" >> "$GITHUB_OUTPUT"
+          echo "release_tag=$release_tag" >> "$GITHUB_OUTPUT"
+
       - name: 🚀 Deploy Release Docs
-        if: github.event_name == 'release' && github.event.action == 'published'
+        if: github.event_name == 'release' && github.event.action == 'published' && steps.release_metadata.outputs.is_rc != 'true'
         env:
           MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          release_tag="${GITHUB_REF_NAME#v}"
-          mike deploy --push "$release_tag"
+          mike deploy --push "${{ steps.release_metadata.outputs.release_tag }}"
 
       # IndexNow key: 0d5d9799b1cc4a39825146388c6781eb
       # This key must stay in sync across three files:
@@ -84,7 +100,7 @@ jobs:
           (github.event_name == 'push' && github.ref == 'refs/heads/develop') ||
           github.event_name == 'workflow_dispatch' ||
           (github.event_name == 'push' && github.ref == 'refs/heads/release/latest') ||
-          (github.event_name == 'release' && github.event.action == 'published')
+          (github.event_name == 'release' && github.event.action == 'published' && steps.release_metadata.outputs.is_rc != 'true')
         run: |
           cp docs/robots.txt /tmp/robots.txt
           cp docs/llms.txt /tmp/llms.txt
diff --git a/src/supervision/utils/video.py b/src/supervision/utils/video.py
@@ -1,5 +1,9 @@
 from __future__ import annotations
 
+import os
+import shutil
+import subprocess
+import tempfile
 import threading
 import time
 from collections import deque
@@ -133,6 +137,73 @@ def __exit__(
             self.__writer.release()
 
 
+def _mux_audio(source_path: str, video_path: str) -> None:
+    """Mux audio from `source_path` into `video_path` in-place using ffmpeg.
+
+    Args:
+        source_path: Path to the original video file containing the audio stream.
+        video_path: Path to the video-only file to be updated with audio.
+    """
+    ffmpeg_path = shutil.which("ffmpeg")
+    if ffmpeg_path is None:
+        logger.warning(
+            "ffmpeg not found on PATH. Audio will not be preserved. "
+            "Install ffmpeg to enable audio preservation."
+        )
+        return
+
+    tmp_path = None
+    try:
+        tmp_fd, tmp_path = tempfile.mkstemp(
+            suffix=os.path.splitext(video_path)[1],
+            dir=os.path.dirname(os.path.abspath(video_path)),
+        )
+        os.close(tmp_fd)
+        result = subprocess.run(  # noqa: S603
+            [
+                ffmpeg_path,
+                "-y",
+                "-loglevel",
+                "error",
+                "-nostats",
+                "-i",
+                video_path,
+                "-i",
+                source_path,
+                "-c:v",
+                "copy",
+                "-c:a",
+                "copy",
+                "-map",
+                "0:v:0",
+                "-map",
+                "1:a:0?",
+                "-shortest",
+                tmp_path,
+            ],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.PIPE,
+            timeout=300,
+        )
+        if result.returncode != 0:
+            stderr_msg = result.stderr.decode(errors="replace").strip()
+            logger.warning(
+                "ffmpeg failed to mux audio (return code %d)%s. "
+                "The output video will not have audio.",
+                result.returncode,
+                f": {stderr_msg}" if stderr_msg else "",
+            )
+            return
+        os.replace(tmp_path, video_path)
+    except Exception as exc:
+        logger.warning(
+            "Audio muxing failed: %s. Output video will not have audio.", exc
+        )
+    finally:
+        if tmp_path is not None and os.path.exists(tmp_path):
+            os.remove(tmp_path)
+
+
 def _validate_and_setup_video(
     source_path: str, start: int, end: int | None, iterative_seek: bool = False
 ) -> tuple[cv2.VideoCapture, int, int]:
@@ -219,6 +290,7 @@ def process_video(
     writer_buffer: int = 32,
     show_progress: bool = False,
     progress_message: str = "Processing video",
+    preserve_audio: bool = False,
 ) -> None:
     """
     Process video frames asynchronously using a threaded pipeline.
@@ -252,13 +324,18 @@ def process_video(
         show_progress: Whether to display a tqdm progress bar during processing.
             Default is False.
         progress_message: Description shown in the progress bar.
+        preserve_audio: If True, copy the audio stream from `source_path` into
+            `target_path` after frame processing. Requires `ffmpeg` on PATH
+            (e.g. `apt install ffmpeg`, `brew install ffmpeg`). If ffmpeg is
+            not found or the mux step fails, a warning is logged and the output
+            video is saved without audio — no exception is raised. Audio is
+            truncated to match the processed video duration. Default is False.
 
     Returns:
         None
 
     Example:
         ```python
-        import cv2
         import supervision as sv
         from rfdetr import RFDETRMedium
 
@@ -267,10 +344,11 @@ def process_video(
         def callback(frame, frame_index):
             return model.predict(frame)
 
-        process_video(
+        sv.process_video(
             source_path="source.mp4",
             target_path="target.mp4",
             callback=callback,
+            preserve_audio=True,
         )
         ```
     """
@@ -368,6 +446,15 @@ def writer_thread(video_sink: VideoSink) -> None:
             if exception_in_worker is not None:
                 raise exception_in_worker
 
+    if preserve_audio:
+        if writer_worker.is_alive():
+            logger.warning(
+                "Writer thread did not finish in time; skipping audio mux "
+                "to avoid reading an incomplete output file."
+            )
+        else:
+            _mux_audio(source_path=source_path, video_path=target_path)
+
 
 class FPSMonitor:
     """
diff --git a/tests/utils/test_video.py b/tests/utils/test_video.py
@@ -1,10 +1,17 @@
 import os
+import shutil
+from unittest.mock import MagicMock, patch
 
 import cv2
 import numpy as np
 import pytest
 
-from supervision.utils.video import VideoInfo, get_video_frames_generator, process_video
+from supervision.utils.video import (
+    VideoInfo,
+    _mux_audio,
+    get_video_frames_generator,
+    process_video,
+)
 
 
 @pytest.fixture
@@ -206,6 +213,100 @@ def test_get_video_frames_generator_with_stride(dummy_video_path):
     assert len(frames) == 5
 
 
+def test_process_video_preserve_audio_calls_mux(dummy_video_path, tmp_path):
+    """
+    Verify that process_video calls _mux_audio when preserve_audio=True.
+
+    Scenario: Processing a video with preserve_audio=True and ffmpeg available.
+    Expected: _mux_audio is called exactly once with the correct source and target
+    paths, confirming the audio muxing step is triggered after frame writing completes.
+    """
+    target_path = str(tmp_path / "target_audio.mp4")
+
+    with patch("supervision.utils.video._mux_audio") as mock_mux:
+        process_video(
+            source_path=dummy_video_path,
+            target_path=target_path,
+            callback=lambda frame, idx: frame,
+            preserve_audio=True,
+        )
+        mock_mux.assert_called_once_with(
+            source_path=dummy_video_path, video_path=target_path
+        )
+
+
+def test_process_video_no_audio_by_default(dummy_video_path, tmp_path):
+    """
+    Verify that process_video does not call _mux_audio when preserve_audio=False.
+
+    Scenario: Default process_video call without setting preserve_audio.
+    Expected: _mux_audio is never called, preserving existing behavior for callers
+    that do not need audio.
+    """
+    target_path = str(tmp_path / "target_no_audio.mp4")
+
+    with patch("supervision.utils.video._mux_audio") as mock_mux:
+        process_video(
+            source_path=dummy_video_path,
+            target_path=target_path,
+            callback=lambda frame, idx: frame,
+        )
+        mock_mux.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    ("which_rv", "run_kwargs"),
+    [
+        pytest.param(None, {}, id="ffmpeg_missing"),
+        pytest.param(
+            "/usr/bin/ffmpeg",
+            {"return_value": MagicMock(returncode=1, stderr=b"")},
+            id="ffmpeg_fails",
+        ),
+        pytest.param(
+            "/usr/bin/ffmpeg",
+            {"side_effect": OSError("mux failed")},
+            id="subprocess_raises",
+        ),
+    ],
+)
+def test_mux_audio_file_unchanged_on_failure(
+    dummy_video_path, tmp_path, which_rv, run_kwargs
+):
+    """_mux_audio leaves the output file unchanged when muxing cannot complete."""
+    target_path = str(tmp_path / "video.mp4")
+    shutil.copy(dummy_video_path, target_path)
+    original_size = os.path.getsize(target_path)
+
+    with (
+        patch("supervision.utils.video.shutil.which", return_value=which_rv),
+        patch("supervision.utils.video.subprocess.run", **run_kwargs),
+    ):
+        _mux_audio(source_path=dummy_video_path, video_path=target_path)
+
+    assert os.path.getsize(target_path) == original_size
+
+
+def test_mux_audio_replaces_file_on_success(dummy_video_path, tmp_path):
+    """_mux_audio calls os.replace with video_path as destination on success."""
+    target_path = str(tmp_path / "video.mp4")
+    shutil.copy(dummy_video_path, target_path)
+
+    success_result = MagicMock()
+    success_result.returncode = 0
+    success_result.stderr = b""
+
+    with (
+        patch("supervision.utils.video.shutil.which", return_value="/usr/bin/ffmpeg"),
+        patch("supervision.utils.video.subprocess.run", return_value=success_result),
+        patch("supervision.utils.video.os.replace") as mock_replace,
+    ):
+        _mux_audio(source_path=dummy_video_path, video_path=target_path)
+
+    mock_replace.assert_called_once()
+    assert mock_replace.call_args[0][1] == target_path
+
+
 def test_get_video_frames_generator_with_start_end(dummy_video_path):
     """
     Verify that get_video_frames_generator respects start and end frame indices.
