Skip to content

Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.

Draw the overlay on a clip that wants no captions (#190)

Nika Siradze3fd532d312b3
diff --git a/backend/cli.py b/backend/cli.py
index 37d1dc8..afdf698 100644
--- a/backend/cli.py
+++ b/backend/cli.py
@@ -477,6 +477,8 @@ def cmd_studio(args):
]
# Only when asked for, so a studio cut that names none of these is the
# same command it was before they existed.
+ if getattr(args, "no_captions", False):
+ cmd += ["--no-captions"]
if getattr(args, "topic", None):
cmd += ["--topic", args.topic,
"--topic-position", getattr(args, "topic_position", "top-left") or "top-left"]
@@ -4379,6 +4381,9 @@ def main():
studio.add_argument("--logo", help="Logo image (asset name or path)")
studio.add_argument("--logo-position", choices=["top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right"], default="top-left")
studio.add_argument("--logo-scale", type=float, default=1.0)
+ studio.add_argument("--no-captions", dest="no_captions", action="store_true",
+ help="Draw the logo, chip, bar and cards, and burn no words. "
+ "For footage that already carries its own captions.")
studio.add_argument("--topic", help="Standing label saying what the clip is about")
studio.add_argument("--topic-position", dest="topic_position", choices=["top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right"],
default="top-left")
diff --git a/backend/clip_studio.py b/backend/clip_studio.py
index 6056b2f..f30907e 100644
--- a/backend/clip_studio.py
+++ b/backend/clip_studio.py
@@ -133,7 +133,8 @@ def _json_arg(raw, name):
def _render_fragment(video, start, end, words, style, crop, title, out_dir, fmt="vertical",
logo=None, name_card=None, motion=None, caption_position="auto",
caption_scale=1.0, logo_position="top-left", logo_scale=1.0,
- topic=None, progress=None, cards=None, brand=None, font_family=None):
+ topic=None, progress=None, cards=None, brand=None, font_family=None,
+ captions=True):
"""Render the fragment with face-crop + captions via the existing engine."""
from services.clip_generator import generate_clip
print(f" [fragment] rendering {start:.1f}s–{end:.1f}s ({style}, crop={crop}, {fmt})", flush=True)
@@ -146,6 +147,7 @@ def _render_fragment(video, start, end, words, style, crop, title, out_dir, fmt=
transcript_words=words, title=title, output_dir=out_dir,
logo_path=logo, name_card=name_card, motion=motion,
topic=topic, progress=progress, cards=cards, brand=brand, font_family=font_family,
+ captions=captions,
clean_fillers=True, allow_ass_fallback=True,
progress_callback=lambda p, m: print(f" {p}% {m}", flush=True),
)
@@ -242,6 +244,8 @@ def main():
ap.add_argument("--logo", default=None, help="Logo image (asset name or path)")
ap.add_argument("--logo-position", default="top-left", choices=["top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right"])
ap.add_argument("--logo-scale", type=float, default=1.0)
+ ap.add_argument("--no-captions", dest="no_captions", action="store_true",
+ help="Draw the overlay and burn no words")
ap.add_argument("--topic", default=None,
help="Standing label saying what the clip is about")
ap.add_argument("--topic-position", default="top-left",
@@ -362,6 +366,7 @@ def main():
cards=_json_arg(args.cards, "--cards"),
brand=_json_arg(args.brand, "--brand"),
font_family=args.font_family,
+ captions=not args.no_captions,
)
platforms = [p.strip() for p in platforms_str.split(",") if p.strip()]
diff --git a/backend/services/clip_generator.py b/backend/services/clip_generator.py
index a9a0b87..017eaeb 100644
--- a/backend/services/clip_generator.py
+++ b/backend/services/clip_generator.py
@@ -529,6 +529,7 @@ def _render_with_remotion(
cards: Optional[list] = None,
brand: Optional[dict] = None,
font_family: Optional[str] = None,
+ captions: bool = True,
) -> tuple[bool, Optional[str]]:
"""
Render captions using Remotion. Returns (success, optional_prores_overlay_path).
@@ -585,8 +586,13 @@ def _render_with_remotion(
return False, None
# Prepare words JSON (adjust timestamps by offset)
+ #
+ # Captions off draws every other part and none of the words. The logo, the
+ # topic chip, the progress bar and the cards are all drawn by this one pass,
+ # so the alternative to an empty list here is skipping the pass and losing
+ # them with it, which is what "captions off" used to quietly mean.
adjusted_words = []
- for w in words:
+ for w in (words if captions else []):
adjusted = {
"word": w.get("word", ""),
"start": round(w["start"] - time_offset, 3),
@@ -773,6 +779,7 @@ def generate_clip(
cards: Optional[list] = None,
brand: Optional[dict] = None,
font_family: Optional[str] = None,
+ captions: bool = True,
progress_callback: Optional[Callable[[int, str], None]] = None,
) -> dict:
"""
@@ -1031,14 +1038,28 @@ def generate_clip(
)
# Step 3: Render captions (Remotion-first; ASS fallback optional)
- if not transcript_words:
+ #
+ # The drawn layer is not only the words. The logo, topic chip, progress
+ # bar and cards are drawn by the same Remotion pass, so a clip that
+ # wants any of them needs that pass to run whether or not it is being
+ # captioned. Without this, "captions off" silently meant "nothing on
+ # screen at all", and a clip that had cards to draw ran the pass and
+ # burned the default caption style over a file that had asked for none.
+ wants_overlay = bool(
+ logo_path or topic or progress or cards
+ or (name_card and name_card.get("title"))
+ )
+ if not captions and wants_overlay:
+ print(" drawing the overlay without captions", flush=True)
+
+ if not transcript_words and not wants_overlay:
caption_warning = (
f"rendered without captions: no transcript words were passed, so the "
f"{caption_style} style had nothing to draw"
)
print(f" {caption_warning}", file=sys.stderr, flush=True)
- if transcript_words:
+ if transcript_words or wants_overlay:
if progress_callback:
progress_callback(50, f"Adding {caption_style} captions (3/{total_steps})")
@@ -1046,7 +1067,7 @@ def generate_clip(
clip_words = remapped_words
else:
clip_words = [
- w for w in transcript_words
+ w for w in (transcript_words or [])
if w["end"] > start_second and w["start"] < end_second
]
@@ -1068,7 +1089,7 @@ def generate_clip(
)
print(f" {caption_warning}", file=sys.stderr, flush=True)
- if clip_words:
+ if (clip_words and captions) or wants_overlay:
if progress_callback:
progress_callback(65, f"Rendering captions into video (3/{total_steps})")
@@ -1096,15 +1117,32 @@ def generate_clip(
cards=cards,
brand=brand,
font_family=font_family,
+ captions=captions,
)
- if not remotion_ok and not allow_ass_fallback:
+ if not remotion_ok and not captions:
+ # Nothing else can draw a chip, a bar or a card: the ASS
+ # path burns words and an overlay is not words. Handing
+ # back the bare cut here would report success for a clip
+ # missing everything it was asked for, which is the failure
+ # this whole switch exists to stop being silent.
+ if wants_overlay:
+ raise RuntimeError(
+ "The overlay could not be drawn: the Remotion renderer "
+ "failed and nothing else draws a logo, chip, bar or card. "
+ "The clip is not being delivered without them."
+ )
+ # Only a trim and a reframe were asked for, and both are
+ # already in the cut.
+ captioned_path = cropped_path
+
+ if not remotion_ok and captions and not allow_ass_fallback:
raise RuntimeError(
"Remotion caption render failed. ASS fallback is disabled "
"(set allow_ass_fallback=true to permit fallback)."
)
- if not remotion_ok and allow_ass_fallback:
+ if not remotion_ok and captions and allow_ass_fallback:
# Optional fallback: ASS subtitle burn-in
ass_path = os.path.join(work_dir, "captions.ass")
render_captions(
diff --git a/cli/VERSION b/cli/VERSION
index 43c4dbe..a616492 100644
--- a/cli/VERSION
+++ b/cli/VERSION
@@ -1 +1 @@
-2.7.17
+2.7.18
diff --git a/package-lock.json b/package-lock.json
index d5f661a..5b6d245 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "podcli",
- "version": "2.7.17",
+ "version": "2.7.18",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "podcli",
- "version": "2.7.17",
+ "version": "2.7.18",
"license": "AGPL-3.0-only",
"dependencies": {
"@fontsource/dm-sans": "^5.3.0",
diff --git a/package.json b/package.json
index ace545f..4d2141d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "podcli",
- "version": "2.7.17",
+ "version": "2.7.18",
"private": true,
"description": "AI-powered podcast clip generator for TikTok/YouTube Shorts. Transcribe, find viral moments, export vertical clips with burned captions.",
"type": "module",
diff --git a/tests/test_clip_generator.py b/tests/test_clip_generator.py
index 88db064..bc1e593 100644
--- a/tests/test_clip_generator.py
+++ b/tests/test_clip_generator.py
@@ -83,6 +83,94 @@ class ClipGeneratorTests(unittest.TestCase):
argv = self._render_args(caption_style=style)
self.assertIn("--logo", argv, f"{style} lost the logo")
+ def _render_words(self, **kwargs):
+ """The words payload one Remotion render was handed.
+
+ Read inside the call: the file is written next to the output and the
+ temporary directory holding it is gone by the time the helper returns.
+ """
+ real_exists = os.path.exists
+ seen = {}
+
+ def capture(argv, *a, **kw):
+ args = [str(part) for part in argv]
+ if "--words" in args:
+ with open(args[args.index("--words") + 1]) as fh:
+ seen.update(json.load(fh))
+ return subprocess.CompletedProcess(args=args, returncode=0, stdout="", stderr="")
+
+ with tempfile.TemporaryDirectory() as td:
+ video_path = os.path.join(td, "video.mp4")
+ logo_path = os.path.join(td, "logo.png")
+ for path in (video_path, logo_path):
+ with open(path, "wb"):
+ pass
+
+ with mock.patch.object(cg.os.path, "exists", side_effect=self._fake_exists(real_exists)), \
+ mock.patch.object(cg.shutil, "which", return_value="/usr/bin/node"), \
+ mock.patch("subprocess.run", side_effect=capture):
+ cg._render_with_remotion(
+ video_path=video_path,
+ words=[{"word": "hello", "start": 0.0, "end": 0.5}],
+ output_path=os.path.join(td, "captioned.mp4"),
+ logo_path=logo_path,
+ **kwargs,
+ )
+ return seen.get("words")
+
+ def test_captions_off_still_draws_the_rest(self):
+ """Captions off is not "draw nothing".
+
+ The logo, the chip, the bar and the cards are drawn by the same pass
+ the captions ride on. Turning the words off used to take every one of
+ them with it, which is what an uploaded clip asks for by default: the
+ clip came back bare and nothing said why.
+ """
+ argv = self._render_args(caption_style="hormozi", captions=False,
+ topic={"label": "Fitness"})
+
+ self.assertIn("--logo", argv, "the logo went with the captions")
+ self.assertIn("--topic", argv, "the chip went with the captions")
+
+ # The pass runs; it is handed no words to draw.
+ self.assertEqual(
+ self._render_words(caption_style="hormozi", captions=False), [])
+
+ def test_a_failed_overlay_is_not_delivered_as_a_finished_clip(self):
+ """Silence is the failure mode this switch exists to stop.
+
+ Nothing but Remotion draws a chip, a bar or a card, so when it fails
+ there is no degraded version to hand back. Returning the bare cut would
+ report success for a clip missing everything it was asked for.
+ """
+ real_exists = os.path.exists
+ failed = subprocess.CompletedProcess(
+ args=["node"], returncode=1, stdout="", stderr="boom")
+
+ with tempfile.TemporaryDirectory() as td:
+ video_path = os.path.join(td, "video.mp4")
+ with open(video_path, "wb"):
+ pass
+
+ with mock.patch.object(cg.os.path, "exists",
+ side_effect=self._fake_exists(real_exists)), \
+ mock.patch.object(cg.shutil, "which", return_value="/usr/bin/node"), \
+ mock.patch("subprocess.run", return_value=failed):
+ ok, _ = cg._render_with_remotion(
+ video_path=video_path,
+ words=[],
+ caption_style="hormozi",
+ output_path=os.path.join(td, "captioned.mp4"),
+ topic={"label": "Fitness"},
+ captions=False,
+ )
+ self.assertFalse(ok, "a failed overlay render must not report success")
+
+ def test_captions_on_is_unchanged(self):
+ """The ordinary render must not have moved."""
+ words = self._render_words(caption_style="hormozi", captions=True)
+ self.assertEqual([w["word"] for w in words], ["hello"])
+
def test_no_caption_style_gates_the_logo(self):
"""The gate that dropped it lived in the style config, so guard that.