Skip to content

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

feat: add clip layout controls (#182)

Nika Siradze9623b3534e3b
diff --git a/backend/cli.py b/backend/cli.py
index e028aea..4b9af34 100644
--- a/backend/cli.py
+++ b/backend/cli.py
@@ -466,8 +466,12 @@ def cmd_studio(args):
env["ASSEMBLYAI_API_KEY"] = args.assemblyai_api_key
cmd += [
"--caption-style", args.caption_style,
+ "--caption-position", getattr(args, "caption_position", "auto"),
+ "--caption-scale", str(getattr(args, "caption_scale", 1.0)),
"--crop", args.crop,
"--format", getattr(args, "format", None) or "vertical",
+ "--logo-position", getattr(args, "logo_position", "top-left"),
+ "--logo-scale", str(getattr(args, "logo_scale", 1.0)),
"--intro-seconds", str(args.intro_seconds),
"--outro-seconds", str(args.outro_seconds),
]
@@ -483,6 +487,12 @@ def cmd_studio(args):
cmd += ["--intro-title", args.intro_title]
if args.handle:
cmd += ["--handle", args.handle]
+ if getattr(args, "logo", None):
+ cmd += ["--logo", args.logo]
+ if getattr(args, "intro", None):
+ cmd += ["--intro", args.intro]
+ if getattr(args, "outro", None):
+ cmd += ["--outro", args.outro]
if args.output:
cmd += ["--output", os.path.abspath(args.output)]
if args.no_intro:
@@ -619,6 +629,10 @@ def cmd_process(args):
os.environ["ASSEMBLYAI_API_KEY"] = args.assemblyai_api_key
if args.caption_style:
config["caption_style"] = args.caption_style
+ if getattr(args, "caption_position", None):
+ config["caption_position"] = args.caption_position
+ if getattr(args, "caption_scale", None) is not None:
+ config["caption_font_scale"] = round(args.caption_scale * 100)
if args.crop:
config["crop_strategy"] = args.crop
if getattr(args, "format", None):
@@ -658,6 +672,10 @@ def cmd_process(args):
else:
print(f" Warning: Logo '{args.logo}' not found (checked assets and filesystem)", file=sys.stderr)
config["logo_path"] = args.logo # pass through anyway
+ if getattr(args, "logo_position", None):
+ config["logo_position"] = args.logo_position
+ if getattr(args, "logo_scale", None) is not None:
+ config["logo_scale"] = args.logo_scale
if getattr(args, "no_outro", False):
config["outro_path"] = ""
elif args.outro:
@@ -1156,6 +1174,10 @@ def cmd_process(args):
start_second=clip["start_second"],
end_second=clip["end_second"],
caption_style=config.get("caption_style", "branded"),
+ caption_position=config.get("caption_position", "auto"),
+ caption_font_scale=config.get("caption_font_scale", 100),
+ logo_position=config.get("logo_position", "top-left"),
+ logo_scale=config.get("logo_scale", 1.0),
crop_strategy=config.get("crop_strategy", "face"),
format=config.get("format", "vertical"),
transcript_words=words,
@@ -1377,6 +1399,10 @@ def cmd_process(args):
start_second=clip["start_second"],
end_second=clip["end_second"],
caption_style=config.get("caption_style", "branded"),
+ caption_position=config.get("caption_position", "auto"),
+ caption_font_scale=config.get("caption_font_scale", 100),
+ logo_position=config.get("logo_position", "top-left"),
+ logo_scale=config.get("logo_scale", 1.0),
crop_strategy=config.get("crop_strategy", "face"),
format=config.get("format", "vertical"),
transcript_words=words,
@@ -4213,10 +4239,18 @@ def main():
"off keeps the pictures and leaves the video alone (default: start)")
proc.add_argument("--template", help="Cut in a saved look (podcli Pro). Name or id.")
proc.add_argument("--caption-style", choices=["branded", "hormozi", "karaoke", "subtle"])
+ proc.add_argument("--caption-position", choices=["auto", "upper", "center", "lower"],
+ help="Caption placement (default: follows the chosen style)")
+ proc.add_argument("--caption-scale", type=float, choices=[0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 1.0, 1.05, 1.1, 1.15, 1.2, 1.25, 1.3, 1.35, 1.4, 1.45, 1.5],
+ help="Caption size multiplier (default: 1)")
proc.add_argument("--crop", choices=["center", "face", "speaker", "speaker-hardcut"])
proc.add_argument("--format", choices=["vertical", "horizontal", "square"], help="Output aspect ratio (default: vertical)")
proc.add_argument("--profile", choices=["podcast", "party", "action"], help="Detection profile: podcast (transcript-first, default), party/action (laughter/energy highlights)")
proc.add_argument("--logo", help="Logo image (asset name or path)")
+ proc.add_argument("--logo-position", choices=["top-left", "top-center", "top-right", "bottom-left", "bottom-center", "bottom-right"],
+ help="Logo placement (default: top-left)")
+ proc.add_argument("--logo-scale", type=float, choices=[0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95, 1.0, 1.05, 1.1, 1.15, 1.2, 1.25, 1.3, 1.35, 1.4, 1.45, 1.5],
+ help="Logo size multiplier (default: 1)")
proc.add_argument("--outro", help="Outro video (asset name or path)")
proc.add_argument("--name-card", dest="name_card",
help="Lower third naming the speaker, shown for the first seconds")
@@ -4280,11 +4314,17 @@ def main():
studio.add_argument("--engine", choices=["whisper-py", "whispercpp", "assemblyai"], help="Transcription engine")
studio.add_argument("--assemblyai-api-key", help="AssemblyAI API key for --engine assemblyai. Prefer ASSEMBLYAI_API_KEY; command-line secrets can appear in process listings.")
studio.add_argument("--caption-style", choices=["hormozi", "karaoke", "subtle", "branded"], default="hormozi")
+ studio.add_argument("--caption-position", choices=["auto", "upper", "center", "lower"], default="auto")
+ studio.add_argument("--caption-scale", type=float, default=1.0)
studio.add_argument("--crop", choices=["center", "face", "speaker", "speaker-hardcut"], default="face")
studio.add_argument("--format", choices=["vertical", "horizontal", "square"], default="vertical",
help="Output aspect ratio (default: vertical)")
studio.add_argument("--template", help="Cut in a saved look (podcli Pro). Name or id.")
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("--intro", help="Intro video (asset name or path)")
+ studio.add_argument("--outro", help="Outro video (asset name or path)")
studio.add_argument("--name-card", dest="name_card",
help="Lower third naming the speaker, shown for the first seconds")
studio.add_argument("--name-card-sub", dest="name_card_sub",
diff --git a/backend/clip_studio.py b/backend/clip_studio.py
index 86b30e5..0e19e75 100644
--- a/backend/clip_studio.py
+++ b/backend/clip_studio.py
@@ -120,13 +120,17 @@ def _find_paragraph(words: list, phrase: str) -> tuple[float, float]:
def _render_fragment(video, start, end, words, style, crop, title, out_dir, fmt="vertical",
- logo=None, name_card=None, motion=None):
+ logo=None, name_card=None, motion=None, caption_position="auto",
+ caption_scale=1.0, logo_position="top-left", logo_scale=1.0):
"""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)
res = generate_clip(
video_path=video, start_second=start, end_second=end,
- caption_style=style, crop_strategy=crop, format=fmt,
+ caption_style=style, caption_position=caption_position,
+ caption_font_scale=round(caption_scale * 100),
+ logo_position=logo_position, logo_scale=logo_scale,
+ crop_strategy=crop, format=fmt,
transcript_words=words, title=title, output_dir=out_dir,
logo_path=logo, name_card=name_card, motion=motion,
clean_fillers=True, allow_ass_fallback=True,
@@ -216,10 +220,17 @@ def main():
ap.add_argument("--language", default=None, help="Transcription language (e.g. es). Auto-detect if omitted.")
ap.add_argument("--engine", choices=["whisper-py", "whispercpp", "assemblyai"], default=None, help="Transcription engine")
ap.add_argument("--caption-style", default="hormozi", choices=["hormozi", "karaoke", "subtle", "branded"])
+ ap.add_argument("--caption-position", default="auto", choices=["auto", "upper", "center", "lower"])
+ ap.add_argument("--caption-scale", type=float, default=1.0)
ap.add_argument("--crop", default="face", choices=["center", "face", "speaker", "speaker-hardcut"])
ap.add_argument("--format", default="vertical", choices=["vertical", "horizontal", "square"],
help="Output aspect ratio (default: vertical)")
ap.add_argument("--output", default=None, help="Final output path")
+ 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("--intro", default=None, help="Intro video (asset name or path)")
+ ap.add_argument("--outro", default=None, help="Outro video (asset name or path)")
# bookends (defaults are None so we can tell what the user explicitly set;
# unset values fall back to the saved brand config, then BRAND_DEFAULTS)
ap.add_argument("--intro-title", default=None, help="Intro headline (default: derived from first words)")
@@ -277,7 +288,17 @@ def main():
spec = get_format(args.format)
# 1. Fragment
- from services.asset_store import resolve_logo
+ from services.asset_store import resolve, resolve_logo
+
+ def media_path(value: str | None, kind: str) -> str | None:
+ if not value:
+ return None
+ found = resolve(value) or value
+ found = found if os.path.isabs(found) else os.path.join(_INVOKE_CWD, found)
+ found = os.path.abspath(found)
+ if not os.path.exists(found):
+ raise SystemExit(f"{kind.capitalize()} not found: {value}")
+ return found
name_card = None
if getattr(args, "name_card", None):
@@ -302,13 +323,20 @@ def main():
logo=resolve_logo(getattr(args, "logo", None)),
name_card=name_card,
motion=motion,
+ caption_position=args.caption_position,
+ caption_scale=max(0.7, min(1.5, args.caption_scale)),
+ logo_position=args.logo_position,
+ logo_scale=max(0.5, min(1.5, args.logo_scale)),
)
platforms = [p.strip() for p in platforms_str.split(",") if p.strip()]
parts = []
# 2. Intro (optional)
- if not args.no_intro:
+ external_intro = media_path(args.intro, "intro")
+ if external_intro and not args.no_intro:
+ parts.append(external_intro)
+ elif not args.no_intro:
intro_title = args.intro_title
if not intro_title:
# derive a short headline from the first ~4 words of the fragment
@@ -324,7 +352,10 @@ def main():
parts.append(fragment)
# 3. Outro (optional)
- if not args.no_outro:
+ external_outro = media_path(args.outro, "outro")
+ if external_outro and not args.no_outro:
+ parts.append(external_outro)
+ elif not args.no_outro:
outro = _render_bookend(
"outro", outro_title, handle, platforms,
args.outro_seconds, os.path.join(out_dir, "_outro.mp4"), accent, bg,
diff --git a/backend/services/clip_generator.py b/backend/services/clip_generator.py
index b302e2a..cfc1c8e 100644
--- a/backend/services/clip_generator.py
+++ b/backend/services/clip_generator.py
@@ -495,6 +495,7 @@ def _render_with_remotion(
caption_position: str = "auto",
caption_font_scale: int = 100,
logo_position: str = "top-left",
+ logo_scale: float = 1.0,
) -> tuple[bool, Optional[str]]:
"""
Render captions using Remotion. Returns (success, optional_prores_overlay_path).
@@ -622,6 +623,7 @@ def _render_with_remotion(
"--caption-position", caption_position,
"--caption-font-scale", str(caption_font_scale),
"--logo-position", logo_position,
+ "--logo-scale", str(logo_scale),
]
if logo_path and os.path.exists(logo_path):
cmd.extend(["--logo", os.path.abspath(logo_path)])
@@ -692,6 +694,7 @@ def generate_clip(
caption_position: str = "auto",
caption_font_scale: int = 100,
logo_position: str = "top-left",
+ logo_scale: float = 1.0,
crop_strategy: str = "face",
format: str = "vertical",
crop_keyframes: list[dict] = None,
@@ -1028,6 +1031,7 @@ def generate_clip(
caption_position=caption_position,
caption_font_scale=caption_font_scale,
logo_position=logo_position,
+ logo_scale=logo_scale,
)
if not remotion_ok and not allow_ass_fallback:
diff --git a/cli/VERSION b/cli/VERSION
index 6a81b4c..3e65160 100644
--- a/cli/VERSION
+++ b/cli/VERSION
@@ -1 +1 @@
-2.7.8
+2.7.9
diff --git a/package-lock.json b/package-lock.json
index 6c2db97..e23877f 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "podcli",
- "version": "2.6.0",
+ "version": "2.7.9",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "podcli",
- "version": "2.6.0",
+ "version": "2.7.9",
"license": "AGPL-3.0-only",
"dependencies": {
"@fontsource/dm-sans": "^5.3.0",
diff --git a/package.json b/package.json
index 1744071..b7bd1cc 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "podcli",
- "version": "2.7.8",
+ "version": "2.7.9",
"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/remotion/render.mjs b/remotion/render.mjs
index 50de9f2..a9ebe9a 100644
--- a/remotion/render.mjs
+++ b/remotion/render.mjs
@@ -51,6 +51,11 @@ function clampCaptionFontScale(raw) {
return Number.isFinite(value) ? Math.min(160, Math.max(60, value)) : 100;
}
+function clampLogoScale(raw) {
+ const value = Number(raw);
+ return Number.isFinite(value) ? Math.min(1.5, Math.max(0.5, value)) : 1;
+}
+
// Remotion's 30s default is measured against the font delayRender in Root.tsx,
// which competes with evaluating the whole bundle. That bundle has three
@@ -190,6 +195,7 @@ async function main() {
captionPosition: opts["caption-position"] || "auto",
captionFontScale: clampCaptionFontScale(opts["caption-font-scale"]),
logoPosition: opts["logo-position"] || "top-left",
+ logoScale: clampLogoScale(opts["logo-scale"]),
};
console.log(
diff --git a/remotion/src/CaptionedClip.tsx b/remotion/src/CaptionedClip.tsx
index 8b77c0d..40f84d6 100644
--- a/remotion/src/CaptionedClip.tsx
+++ b/remotion/src/CaptionedClip.tsx
@@ -21,6 +21,7 @@ export interface CaptionedClipProps {
nameCard?: NameCardProps | null;
captionPosition?: CaptionPosition;
logoPosition?: LogoPosition;
+ logoScale?: number;
singleLine?: boolean;
/** Per-part overrides; each part falls back to its style's own motion. */
motion?: { captions?: Partial<Motion>; nameCard?: Partial<Motion> } | null;
@@ -34,6 +35,7 @@ export const CaptionedClip: React.FC<CaptionedClipProps> = ({
nameCard,
captionPosition = "auto",
logoPosition = "top-left",
+ logoScale = 1,
singleLine = false,
motion,
}) => {
@@ -51,10 +53,10 @@ export const CaptionedClip: React.FC<CaptionedClipProps> = ({
return (
<AbsoluteFill style={{ backgroundColor: "transparent" }}>
- <Watermark src={logoSrc} height={height} position={logoPosition} />
+ <Watermark src={logoSrc} height={height} position={logoPosition} scale={logoScale} />
{style.name === "branded" ? (
<BrandedCaptions words={words} style={style} logoSrc={logoSrc} faceY={faceY}
- captionPosition={captionPosition} logoPosition={logoPosition} singleLine={singleLine} />
+ captionPosition={captionPosition} logoPosition={logoPosition} logoScale={logoScale} singleLine={singleLine} />
) : (
<CaptionComponent words={words} style={style} singleLine={singleLine} motion={captionMotion} />
)}
diff --git a/remotion/src/Root.tsx b/remotion/src/Root.tsx
index 2e785f7..31a028e 100644
--- a/remotion/src/Root.tsx
+++ b/remotion/src/Root.tsx
@@ -38,6 +38,7 @@ const inputProps = getInputProps() as {
captionPosition?: CaptionPosition;
captionFontScale?: number;
logoPosition?: LogoPosition;
+ logoScale?: number;
singleLine?: boolean;
levels?: number[][];
coverSrc?: string;
@@ -101,6 +102,7 @@ export const RemotionRoot: React.FC = () => {
nameCard: inputProps.nameCard ?? null,
captionPosition,
logoPosition: inputProps.logoPosition || "top-left",
+ logoScale: Math.max(0.5, Math.min(1.5, inputProps.logoScale || 1)),
singleLine: inputProps.singleLine === true,
motion: inputProps.motion ?? null,
}}
diff --git a/remotion/src/components/BrandedCaptions.tsx b/remotion/src/components/BrandedCaptions.tsx
index ef412e5..8cd70c1 100644
--- a/remotion/src/components/BrandedCaptions.tsx
+++ b/remotion/src/components/BrandedCaptions.tsx
@@ -18,6 +18,7 @@ interface Props {
faceY?: number | null; // normalized 0-1 (0=top, 1=bottom)
captionPosition?: CaptionPosition;
logoPosition?: LogoPosition;
+ logoScale?: number;
singleLine?: boolean;
}
@@ -120,6 +121,7 @@ export const BrandedCaptions: React.FC<Props> = ({
faceY,
captionPosition = "auto",
logoPosition = "top-left",
+ logoScale = 1,
singleLine = false,
}) => {
const frame = useCurrentFrame();
@@ -151,7 +153,7 @@ export const BrandedCaptions: React.FC<Props> = ({
// A bottom-anchored logo spans 180-306 scaled units. Captions sitting inside
// that band (captionPosition "lower" starts at 220) would render over it.
if (logoSrc && logoPosition.startsWith("bottom-")) {
- dynamicMargin = Math.max(dynamicMargin, (LOGO_INSET + LOGO_HEIGHT + LOGO_CAPTION_GAP) * s);
+ dynamicMargin = Math.max(dynamicMargin, (LOGO_INSET + LOGO_HEIGHT * logoScale + LOGO_CAPTION_GAP) * s);
}
return (
diff --git a/remotion/src/components/Watermark.tsx b/remotion/src/components/Watermark.tsx
index 53af0ea..c4c9ba4 100644
--- a/remotion/src/components/Watermark.tsx
+++ b/remotion/src/components/Watermark.tsx
@@ -22,7 +22,9 @@ export const Watermark: React.FC<{
src?: string;
height: number;
position?: LogoPosition;
-}> = ({ src, height, position = "top-left" }) => {
+ /** Multiplier supplied by a template. 1 preserves the original mark. */
+ scale?: number;
+}> = ({ src, height, position = "top-left", scale = 1 }) => {
if (!src) return null;
const s = captionScale(height);
@@ -37,8 +39,8 @@ export const Watermark: React.FC<{
: position.endsWith("-right")
? { right: 108 * s }
: { left: "50%", transform: "translateX(-50%)" }),
- width: 255 * s,
- height: LOGO_HEIGHT * s,
+ width: 255 * s * scale,
+ height: LOGO_HEIGHT * s * scale,
objectFit: "contain",
}}
/>
diff --git a/tests/test_clip_generator.py b/tests/test_clip_generator.py
index ba03eeb..7711ca8 100644
--- a/tests/test_clip_generator.py
+++ b/tests/test_clip_generator.py
@@ -116,6 +116,16 @@ class ClipGeneratorTests(unittest.TestCase):
payload = json.loads(argv[argv.index("--motion") + 1])
self.assertEqual(payload["captions"]["enter"], "pop")
+ def test_layout_values_reach_remotion_unchanged(self):
+ argv = self._render_args(
+ caption_style="branded", caption_position="center", caption_font_scale=125,
+ logo_position="bottom-right", logo_scale=0.75,
+ )
+ self.assertEqual(argv[argv.index("--caption-position") + 1], "center")
+ self.assertEqual(argv[argv.index("--caption-font-scale") + 1], "125")
+ self.assertEqual(argv[argv.index("--logo-position") + 1], "bottom-right")
+ self.assertEqual(argv[argv.index("--logo-scale") + 1], "0.75")
+
def test_remotion_runtime_failure_does_not_disable_future_clips(self):
real_exists = os.path.exists
fail_result = subprocess.CompletedProcess(
diff --git a/tests/test_studio_format.py b/tests/test_studio_format.py
index 3d2a876..ead0a18 100644
--- a/tests/test_studio_format.py
+++ b/tests/test_studio_format.py
@@ -77,6 +77,13 @@ class StudioFormatTests(unittest.TestCase):
cmd = _run_studio(args)
self.assertEqual(cmd[cmd.index("--format") + 1], "vertical")
+ def test_old_callers_keep_the_original_layout_defaults(self):
+ cmd = _run_studio(_studio_args())
+ self.assertEqual(cmd[cmd.index("--caption-position") + 1], "auto")
+ self.assertEqual(cmd[cmd.index("--caption-scale") + 1], "1.0")
+ self.assertEqual(cmd[cmd.index("--logo-position") + 1], "top-left")
+ self.assertEqual(cmd[cmd.index("--logo-scale") + 1], "1.0")
+
class StudioCanvasTests(unittest.TestCase):
"""Each stage must be handed the canvas, and it must be the spec's."""