Expose text_overlay controls on the Annotate Video tab

The optional caption from ffmpret.extract_frames is now reachable from
the app: annotate_video_interface gains a Text overlay textbox (default
empty = off) plus font-size slider and top/middle/bottom position
dropdown, passed through app.py -> vidbox.annotate_video ->
ffmpret.extract_frames. The caption is burned in at extraction time, so
it renders beneath the box/mask annotations. The annotate-video-file
CLI gains the matching --text-overlay/--text-font-size/
--text-y-position options, and the dropdown choices come from a new
ffmpret.TEXT_Y_POSITIONS constant.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CLAUDE.md

@@ -75,7 +75,10 @@ commit the JSON.
     four `boxer.BBOX_FORMATS` (default `coco_normalized`), a comma-separated `coord_keys`
     textbox (default `"x,y,w,h"`), then `label_key` / `color_key` / `mask_key` (default
     `"mask_b64"`, matching the SAM2 example data) / `mask_alpha` / `width` / `font_size`
-    mirroring the image Annotate tab. Output is a silent annotated video at source
+    mirroring the image Annotate tab, plus an optional `text_overlay` caption (a `gr.Textbox`,
+    default empty = off) with its own `text_font_size` slider and `text_y_position` dropdown
+    (`ffmpret.TEXT_Y_POSITIONS`, default `bottom`) — burned into every frame beneath the
+    annotations. Output is a silent annotated video at source
     resolution/fps. Each distinct `color_key` value keeps one stable color across all frames.
   - **Crop** tab: `crop_image(...)` → `pilbox.crop` (`api_name="crop"`). Inputs are an image
     plus manual `gr.Number` fields `x0/y0/x1/y1` (pascal_voc box); output is the cropped
@@ -193,13 +196,15 @@ video and encoding frames back into one, via `ffmpeg-python`. Depends on `ffmpeg
   Raises (does not return `None`) when there's no video stream, so failures are legible to
   the callers that subscript the result.
 - `extract_frames(input_path, fps=8, max_short_edge=1080, write_timestamp=True,
-  write_frame_num=True, output_dir=None, out_vid_path=None, text_font_size=20,
-  text_y_position="bottom") -> list[PIL.Image]` decodes frames by piping ffmpeg `rawvideo`
+  write_frame_num=True, output_dir=None, out_vid_path=None, text_overlay=None,
+  text_font_size=20, text_y_position="bottom") -> list[PIL.Image]` decodes frames by piping
+  ffmpeg `rawvideo`
   to stdout. Requested `fps` is capped to source fps; **`fps=None` skips resampling and
   extracts every native frame** (so output index i == source frame i — what `vidbox` needs
   for frame-accurate annotation). Frames may be scaled down so the short edge ≤
   `max_short_edge`. An optional `drawtext` overlay stamps timestamp/frame-number
-  (`text_y_position` ∈ {top, middle, bottom}); it uses ffmpeg's default font. A
+  (`text_y_position` ∈ module constant `TEXT_Y_POSITIONS` = {top, middle, bottom}); it uses
+  ffmpeg's default font. A
   `text_overlay` string (default `None`) is prefixed to that overlay line, and is drawn even
   when `write_timestamp=False`, so it works standalone. The overlay text is built by
   `_build_drawtext_text` and passed to drawtext via a temp **`textfile=`** (removed in a
@@ -242,8 +247,12 @@ the three existing modules). Keeps `pilbox` lite by living in its own module.
 
 - `annotate_video(video_path, detections, out_path, *, bbox_format="coco_normalized",
   coord_keys=("x","y","w","h"), frame_key="frame", label_key="track_id",
-  color_key="track_id", mask_key="mask_b64", mask_alpha=0.5, width=3, font_size=20) ->
-  out_path`. `detections` is a **flat** list of per-frame dicts (frame index under
+  color_key="track_id", mask_key="mask_b64", mask_alpha=0.5, width=3, font_size=20,
+  text_overlay=None, text_font_size=20, text_y_position="bottom") ->
+  out_path`. The three `text_*` params pass through to `ffmpret.extract_frames` — an
+  optional caption burned into every frame at extraction time, i.e. beneath the box/mask
+  annotations (`font_size` is the pilbox label font; `text_font_size` the ffmpeg overlay
+  font). `detections` is a **flat** list of per-frame dicts (frame index under
   `frame_key`, box values under `coord_keys` read positionally per `bbox_format`, optional
   `label_key`/`color_key`/`mask_key`). It: probes metadata → extracts **every native frame**
   (`ffmpret.extract_frames(fps=None)`) → groups detections by frame → converts each box via

app.py

@@ -13,6 +13,7 @@ from loguru import logger
 from PIL import ImageColor
 
 import boxer
+import ffmpret
 import pilbox
 import vidbox
 
@@ -261,6 +262,9 @@ def annotate_video(
     mask_alpha,
     width,
     font_size,
+    text_overlay=None,
+    text_font_size=20,
+    text_y_position="bottom",
 ) -> str:
     """Draw per-frame bounding boxes (and optional masks) onto every frame of a video and return the annotated video.
 
@@ -271,7 +275,10 @@ def annotate_video(
     drawn on its frame; each distinct color_key value keeps ONE stable color across the whole video (so
     a track id is one consistent color), and any mask is drawn as a translucent overlay beneath the box
     in that same color. The output is a new silent video at the source resolution and frame rate with
-    all boxes, labels, and masks burned in. The box coordinates are interpreted per bbox_format, one of:
+    all boxes, labels, and masks burned in. An optional text_overlay caption (e.g. a clip name or
+    camera id) can additionally be burned into every frame, horizontally centered at a chosen
+    vertical position and font size, drawn beneath the boxes/masks. The box coordinates are
+    interpreted per bbox_format, one of:
     "pascal_voc" = [x0, y0, x1, y1] absolute pixels; "albumentations" = [x0, y0, x1, y1] normalized 0-1;
     "coco" = [x0, y0, width, height] absolute pixels; "coco_normalized" = [x0, y0, width, height]
     normalized 0-1 — as documented at
@@ -288,6 +295,9 @@ def annotate_video(
         mask_alpha: Mask overlay opacity from 0.0 (invisible) to 1.0 (solid color).
         width: Box outline width in pixels.
         font_size: Label font size in points.
+        text_overlay: Optional literal caption text burned into every frame of the output video; leave empty for no caption.
+        text_font_size: Font size of the text_overlay caption in points (independent of the box-label font_size).
+        text_y_position: Vertical placement of the text_overlay caption: "top", "middle", or "bottom".
     """
     if video_path is None:
         raise gr.Error("Please provide an input video.")
@@ -313,6 +323,9 @@ def annotate_video(
             mask_alpha=float(mask_alpha),
             width=int(width),
             font_size=int(font_size),
+            text_overlay=(text_overlay or "").strip() or None,
+            text_font_size=int(text_font_size),
+            text_y_position=text_y_position,
         )
     except (ValueError, KeyError) as e:
         raise gr.Error(str(e))
@@ -480,6 +493,13 @@ annotate_video_interface = gr.Interface(
         gr.Slider(0, 1, value=0.5, step=0.05, label="Mask opacity"),
         gr.Slider(1, 10, value=3, step=1, label="Box width"),
         gr.Slider(8, 60, value=20, step=1, label="Font size"),
+        gr.Textbox(value=None, label="Text overlay (optional)"),
+        gr.Slider(8, 60, value=20, step=1, label="Text overlay font size"),
+        gr.Dropdown(
+            choices=list(ffmpret.TEXT_Y_POSITIONS),
+            value="bottom",
+            label="Text overlay position",
+        ),
     ],
     outputs=gr.Video(label="Annotated Video"),
     examples=(
@@ -495,6 +515,9 @@ annotate_video_interface = gr.Interface(
                 0.5,
                 3,
                 20,
+                None,
+                20,
+                "bottom",
             ]
         ]
         if EXAMPLE_VIDEO and EXAMPLE_VIDEO_JSON

ffmpret.py

@@ -17,6 +17,9 @@ logger.add(
 )
 app = typer.Typer(pretty_exceptions_show_locals=False)
 
+# Vertical placements accepted by extract_frames' text_y_position.
+TEXT_Y_POSITIONS = ("top", "middle", "bottom")
+
 
 def parse_frame_name(fname: str):
     """return a tuple of frame_type and frame_index
@@ -229,8 +232,8 @@ def extract_frames(
         "bottom": "h-(2*lh)",
     }
     assert (
-        text_y_position in y_position_map
-    ), f"text_y_position must be one of {list(y_position_map)}, got {text_y_position!r}"
+        text_y_position in TEXT_Y_POSITIONS
+    ), f"text_y_position must be one of {list(TEXT_Y_POSITIONS)}, got {text_y_position!r}"
     text_y_expr = y_position_map[text_y_position]
 
     if output_dir:

tests/test_vidbox.py

@@ -88,6 +88,24 @@ def test_annotate_video_synthetic_coco_normalized(tiny_video, tmp_path):
     assert 8 <= int(meta["nb_frames"]) <= 12
 
 
+def test_annotate_video_with_text_overlay(tiny_video, tmp_path):
+    # the overlay params pass through to ffmpret.extract_frames (drawtext via
+    # textfile); output must still encode at source dims/frames.
+    detections = [
+        {"frame": 0, "track_id": 0, "x": 0.1, "y": 0.1, "w": 0.3, "h": 0.3},
+    ]
+    out = tmp_path / "overlaid.mp4"
+    result = vidbox.annotate_video(
+        tiny_video, detections, str(out), bbox_format="coco_normalized",
+        mask_key="",
+        text_overlay="cam-1", text_font_size=12, text_y_position="top",
+    )
+    assert Path(result).is_file()
+    meta = _probe(result)
+    assert meta["width"] == "64" and meta["height"] == "48"
+    assert 8 <= int(meta["nb_frames"]) <= 12
+
+
 def test_crop_video_rejects_conflicting_boxes():
     # same frame, two DIFFERENT boxes -> conflict error (needs no ffmpeg: raises
     # during grouping, before extraction).

vidbox.py

@@ -26,7 +26,7 @@ from collections import defaultdict
 import typer
 from loguru import logger
 from PIL import Image, ImageColor
-from typing import Literal
+from typing import Literal, Optional
 
 import boxer
 import ffmpret
@@ -63,12 +63,17 @@ def annotate_video(
     mask_alpha: float = 0.5,
     width: int = 3,
     font_size: int = 20,
+    text_overlay: Optional[str] = None,
+    text_font_size: int = 20,
+    text_y_position: str = "bottom",
 ) -> str:
     """Draw per-frame boxes and masks over a video and write the annotated result.
 
     Frames are extracted at native fps/resolution (so frame index ``i`` matches a
     detection's ``frame_key`` value, and full-frame masks line up), annotated with
     :func:`pilbox.annotate`, then re-encoded to a silent video at the source fps.
+    An optional ``text_overlay`` label is burned in at extraction time, so it
+    renders beneath the box/mask annotations.
 
     Args:
         video_path: Path to the input video.
@@ -86,7 +91,15 @@ def annotate_video(
             pass ``""`` to disable masks.
         mask_alpha: Mask overlay opacity in ``[0, 1]``.
         width: Box outline width in pixels.
-        font_size: Label font size in points.
+        font_size: Label font size in points (the pilbox box-label font).
+        text_overlay: Optional literal text burned into every frame (beneath
+            the annotations); ``None``/empty disables it.
+        text_font_size: Font size of the ``text_overlay`` (the ffmpeg drawtext
+            font, distinct from ``font_size``). Only used when ``text_overlay``
+            is set.
+        text_y_position: Vertical placement of the ``text_overlay``; one of
+            :data:`ffmpret.TEXT_Y_POSITIONS` (``top``/``middle``/``bottom``).
+            Only used when ``text_overlay`` is set.
 
     Returns:
         ``out_path``.
@@ -103,7 +116,14 @@ def annotate_video(
     org_w, org_h, fps = vmeta["width"], vmeta["height"], vmeta["fps"]
 
     # Extract every native frame so frame indices align with the detections.
-    frames = ffmpret.extract_frames(video_path, fps=None, write_timestamp=False)
+    frames = ffmpret.extract_frames(
+        video_path,
+        fps=None,
+        write_timestamp=False,
+        text_overlay=text_overlay,
+        text_font_size=text_font_size,
+        text_y_position=text_y_position,
+    )
     if not frames:
         raise ValueError(f"no frames decoded from {video_path}")
 
@@ -437,6 +457,9 @@ def annotate_video_file(
     mask_alpha: float = 0.5,
     width: int = 3,
     font_size: int = 20,
+    text_overlay: Optional[str] = None,
+    text_font_size: int = 20,
+    text_y_position: str = "bottom",
 ) -> str:
     """Annotate ``video_path`` using detections from a JSON file; save to ``out_path``.
 
@@ -458,6 +481,9 @@ def annotate_video_file(
         mask_alpha=mask_alpha,
         width=width,
         font_size=font_size,
+        text_overlay=text_overlay,
+        text_font_size=text_font_size,
+        text_y_position=text_y_position,
     )