Repository: huggingface/transformers
Pull request: add an option to disable Sam3VideoModel progress bar

# What does this PR do?

Avoids flooding the tty when using Sam3VideoModel ( when using propagate_in_video_iterator() )

harmonize argument with other propagate_in_video_iterator in other similar classes (EdgeTamVideoModel, Sam2VideoModel, Sam3TrackerVideoModel). (⚠️ breaking change: disables progress by default contrary to current behavior)

\+ docs mention of the option to enable a progress bar


## Before submitting
- [x] This PR fixes a typo or improves the docs (you can dismiss the other checks if that's the case).
- [x] Did you read the [contributor guideline](https://github.com/huggingface/transformers/blob/main/CONTRIBUTING.md#create-a-pull-request),
      Pull Request section?
- [ ] Was this discussed/approved via a Github issue or the [forum](https://discuss.huggingface.co/)? Please add a link
      to it if that's the case.
- [x] Did you make sure to update the documentation with your changes? Here are the
      [documentation guidelines](https://github.com/huggingface/transformers/tree/main/docs), and
      [here are tips on formatting docstrings](https://github.com/huggingface/transformers/tree/main/docs#writing-source-documentation).
- [ ] Did you write any new necessary tests?


## Who can review?

Anyone in the community is free to review the PR once the tests have passed. Feel free to tag
members/contributors who may be interested in your PR.

@yonigozlan

Changed files:
filename: docs/source/en/model_doc/sam3_video.md
patch: @@ -79,6 +79,7 @@ Process a video with all frames already available using text prompts:
 
 >>> # Process all frames in the video
 >>> outputs_per_frame = {}
+>>> # Pass show_progress_bar=True to display a tqdm progress bar.
 >>> for model_outputs in model.propagate_in_video_iterator(
 ...     inference_session=inference_session, max_frame_num_to_track=50
 ... ):
@@ -114,6 +115,7 @@ You can also track multiple object categories simultaneously by providing multip
 >>>
 >>> # Process video - detects objects from ALL prompts in a single pass
 >>> multi_outputs_per_frame = {}
+>>> # Pass show_progress_bar=True to display a tqdm progress bar.
 >>> for model_outputs in model.propagate_in_video_iterator(
 ...     inference_session=multi_prompt_session, max_frame_num_to_track=50
 ... ):

filename: src/transformers/models/sam3_video/modeling_sam3_video.py
patch: @@ -14,6 +14,7 @@
 
 
 from collections import OrderedDict, defaultdict
+from collections.abc import Iterator
 from copy import deepcopy
 from dataclasses import dataclass
 from typing import Any
@@ -1781,20 +1782,31 @@ def _get_processing_order(
         return processing_order, end_frame_idx
 
     @torch.inference_mode()
+    @auto_docstring(
+        custom_intro="""
+        Propagate the prompts to get grounding results for the entire video. Used when initializing an inference session with a whole video.
+        Yields Sam3VideoSegmentationOutput for each frame.
+        """
+    )
     def propagate_in_video_iterator(
         self,
         inference_session: Sam3VideoInferenceSession,
-        start_frame_idx=0,
-        max_frame_num_to_track=None,
-        reverse=False,
-    ):
-        """
-        Propagate the prompts to get grounding results for the entire video. This method
-        is a generator and yields inference outputs for all frames in the range specified
-        by `start_frame_idx`, `max_frame_num_to_track`, and `reverse`.
-
-        Yields:
-            `Sam3VideoSegmentationOutput`: The segmentation output for each frame.
+        start_frame_idx: int = 0,
+        max_frame_num_to_track: int | None = None,
+        reverse: bool = False,
+        show_progress_bar: bool = False,
+    ) -> Iterator[Sam3VideoSegmentationOutput]:
+        r"""
+        inference_session (`Sam3VideoInferenceSession`):
+            The video inference session object.
+        start_frame_idx (`int`, *optional*, defaults to `0`):
+            The starting frame index for propagation.
+        max_frame_num_to_track (`int`, *optional*):
+            The maximum number of frames to track. If not provided, all frames in the video will be tracked.
+        reverse (`bool`, *optional*, defaults to `False`):
+            Whether to propagate in reverse.
+        show_progress_bar (`bool`, *optional*, defaults to `False`):
+            Whether to show a progress bar during propagation.
         """
         processing_order, end_frame_idx = self._get_processing_order(
             inference_session,
@@ -1804,7 +1816,7 @@ def propagate_in_video_iterator(
         )
 
         hotstart_buffer = []
-        for frame_idx in tqdm(processing_order):
+        for frame_idx in tqdm(processing_order, desc="propagate in video", disable=not show_progress_bar):
             out = self(inference_session=inference_session, frame_idx=frame_idx, reverse=reverse)
 
             if self.hotstart_delay > 0: