PRINTFILM: AI short-video marketing and AI short-drama creation platform
"""FFmpeg compose: per-shot A/V mux → concat → soft/hard subtitles / image-text Ken Burns."""
from __future__ import annotations
import logging
import os
import re
import shutil
import subprocess
import tempfile
from dataclasses import dataclass
from pathlib import Path
from app.config import get_settings
logger = logging.getLogger(__name__)
# FFmpeg 被 SIGTERM 打断时的可读错误(部署重启 / 进程被杀等)
FFMPEG_INTERRUPTED_MSG = "FFmpeg 被系统中断(signal 15),将自动重试合成"
# Punctuation removed from on-screen captions (TTS narration keeps original)
_CAPTION_PUNCT_RE = re.compile(
r"[,。!?;:、,.!?;:…··〜~「」『』【】()\(\)\[\]\"'“”‘’《》〈〉"
r"—_\-/\\|@#$%^&*+=<>{}]+"
)
# Output sizes keyed by aspect ratio
_RATIO_SIZE = {
"16:9": (854, 480),
"9:16": (720, 1280),
"1:1": (720, 720),
"4:3": (640, 480),
"21:9": (1280, 540),
}
@dataclass
class ShotMedia:
shot_no: int
duration: float
narration: str
video_path: Path | None
audio_path: Path | None
image_path: Path | None = None
overlay_title: str = ""
overlay_subtitle: str = ""
@dataclass
class ComposeOptions:
ratio: str = "16:9"
mode: str = "full" # full | image_text
resolution_mode: str = "preview" # preview | hd
# One continuous TTS track for the whole film (preferred over per-shot audio)
full_audio_path: Path | None = None
# Overlay / caption sizing & layout (from template.subtitle_config)
subtitle_layout: str = "top" # top | split(标题在上;口播字幕始终底部)
title_scale: float = 1.35
sub_scale: float = 1.3
caption_scale: float = 1.25
# Optional continuous BGM under narration
bgm_path: Path | None = None
bgm_volume: float = 0.22
# 保留镜头视频里的操作音效,后期与 TTS 叠轨(科普 full 回退模式)
keep_video_sfx: bool = False
# Seedance 内置口播:直接保留视频音轨,不叠外部 TTS
prefer_video_audio: bool = False
sfx_volume: float = 0.22
def allocate_durations_by_narration(
narrations: list[str],
total_audio_dur: float,
*,
min_shot: float = 0.8,
) -> list[float]:
"""Split continuous TTS length across shots by narration character weight."""
n = len(narrations)
if n == 0:
return []
total = max(float(total_audio_dur), min_shot * n)
weights = [max(len((t or "").strip()), 1) for t in narrations]
wsum = float(sum(weights))
raw = [total * (w / wsum) for w in weights]
# Ensure minimums then renormalize
capped = [max(d, min_shot) for d in raw]
csum = sum(capped)
if csum > total + 1e-6:
# shrink proportionally above min
extra = csum - total
flexible = [max(0.0, d - min_shot) for d in capped]
fsum = sum(flexible) or 1.0
capped = [d - extra * (f / fsum) for d, f in zip(capped, flexible)]
# Fix float drift on last shot
head = [round(d, 3) for d in capped[:-1]]
last = max(min_shot, round(total - sum(head), 3))
return [*head, last]
def _probe_has_audio(path: Path) -> bool:
"""片源是否含音轨(操作音效/人声均算)。"""
ffprobe = shutil.which(get_settings().ffprobe_path) or shutil.which("ffprobe")
if not ffprobe or not path.exists():
return False
try:
proc = subprocess.run(
[
ffprobe,
"-v",
"error",
"-select_streams",
"a",
"-show_entries",
"stream=codec_type",
"-of",
"csv=p=0",
str(path),
],
capture_output=True,
text=True,
check=False,
)
return bool((proc.stdout or "").strip())
except Exception: # noqa: BLE001
return False
def probe_duration(path: Path) -> float | None:
"""Return media duration in seconds via ffprobe, or None."""
ffprobe = shutil.which(get_settings().ffprobe_path) or shutil.which("ffprobe")
if not ffprobe or not path.exists():
return None
try:
proc = subprocess.run(
[
ffprobe,
"-v",
"error",
"-show_entries",
"format=duration",
"-of",
"default=noprint_wrappers=1:nokey=1",
str(path),
],
capture_output=True,
text=True,
check=False,
)
if proc.returncode != 0:
return None
return float(proc.stdout.strip())
except Exception: # noqa: BLE001
return None
def probe_video_dimensions(path: Path) -> tuple[int, int] | None:
"""读取视频宽高像素(ffprobe),失败返回 None。"""
ffprobe = shutil.which(get_settings().ffprobe_path) or shutil.which("ffprobe")
if not ffprobe or not path.exists():
return None
try:
proc = subprocess.run(
[
ffprobe,
"-v",
"error",
"-select_streams",
"v:0",
"-show_entries",
"stream=width,height",
"-of",
"csv=p=0:s=x",
str(path),
],
capture_output=True,
text=True,
check=False,
)
if proc.returncode != 0:
return None
raw = (proc.stdout or "").strip()
if "x" not in raw:
return None
w_str, h_str = raw.split("x", 1)
width, height = int(w_str), int(h_str)
if width <= 0 or height <= 0:
return None
return width, height
except Exception: # noqa: BLE001
return None
def is_near_silent_audio(path: Path, *, max_db: float = -70.0) -> bool:
"""True when file missing/tiny or peak volume is below max_db (e.g. anullsrc)."""
if not path.exists() or path.stat().st_size < 2000:
return True
ffmpeg = shutil.which(get_settings().ffmpeg_path) or shutil.which("ffmpeg")
if not ffmpeg:
return False
try:
proc = subprocess.run(
[ffmpeg, "-i", str(path), "-af", "volumedetect", "-f", "null", "-"],
capture_output=True,
text=True,
check=False,
)
text = (proc.stderr or "") + (proc.stdout or "")
peak: float | None = None
for line in text.splitlines():
if "max_volume:" in line:
# e.g. max_volume: -91.0 dB
part = line.split("max_volume:", 1)[1].strip().split()[0]
peak = float(part)
break
if peak is None:
return False
return peak <= max_db
except Exception: # noqa: BLE001
return False
def is_ffmpeg_interrupted_error(exc_or_text: BaseException | str | None) -> bool:
"""判断是否为 FFmpeg SIGTERM / signal 15 打断(可自动重试)。"""
text = str(exc_or_text or "")
if not text:
return False
if FFMPEG_INTERRUPTED_MSG in text:
return True
low = text.lower()
if "signal 15" in low or "sigterm" in low:
return True
if "exiting normally, received signal 15" in low:
return True
return False
class FfmpegInterrupted(RuntimeError):
"""FFmpeg 进程被 SIGTERM 打断,合成可自动重试。"""
def _run(cmd: list[str]) -> None:
logger.info("ffmpeg: %s", " ".join(cmd))
proc = subprocess.run(cmd, capture_output=True, text=True)
if proc.returncode == 0:
return
stderr = proc.stderr or ""
stdout = proc.stdout or ""
combined = f"{stderr}\n{stdout}"
# -15 / 143(128+15) / Windows 等价:进程被 SIGTERM
if proc.returncode in (-15, 143) or is_ffmpeg_interrupted_error(combined):
logger.warning(
"ffmpeg interrupted by SIGTERM returncode=%s cmd=%s",
proc.returncode,
" ".join(cmd[:6]),
)
raise FfmpegInterrupted(FFMPEG_INTERRUPTED_MSG)
raise RuntimeError(stderr[-2000:] or stdout[-2000:] or "ffmpeg failed")
def _which(bin_name: str) -> str:
settings = get_settings()
configured = settings.ffmpeg_path if bin_name == "ffmpeg" else settings.ffprobe_path
path = shutil.which(configured) or shutil.which(bin_name)
if not path:
raise RuntimeError(f"{bin_name} not found in PATH")
return path
def extract_video_poster_frame(
video: str | Path,
dest: Path,
*,
at_sec: float = 0.05,
) -> bool:
"""从视频抽取封面帧(默认接近首帧),成功返回 True。"""
src = Path(video)
if not src.exists():
logger.warning("抽封面失败:视频不存在 path=%s", src)
return False
try:
ffmpeg = _which("ffmpeg")
except RuntimeError:
logger.warning("抽封面失败:未找到 ffmpeg")
return False
dest.parent.mkdir(parents=True, exist_ok=True)
cmd = [
ffmpeg,
"-y",
"-ss",
f"{max(0.0, float(at_sec)):.3f}",
"-i",
str(src),
"-frames:v",
"1",
"-q:v",
"2",
str(dest),
]
proc = subprocess.run(cmd, capture_output=True, text=True)
if proc.returncode != 0 or not dest.exists() or dest.stat().st_size <= 0:
logger.warning(
"抽封面失败 path=%s stderr=%s",
src,
(proc.stderr or "")[-500:],
)
return False
return True
def extract_video_last_frame(video: str | Path, dest: Path) -> bool:
"""从视频抽取接近尾帧的静帧,供镜间衔接;成功返回 True。"""
src = Path(video)
if not src.exists():
logger.warning("抽尾帧失败:视频不存在 path=%s", src)
return False
duration = probe_duration(src)
if duration is not None and duration > 0.1:
# 距片尾约 0.08s,避免精确 seek 到 EOF 抽空帧
return extract_video_poster_frame(src, dest, at_sec=max(0.0, float(duration) - 0.08))
try:
ffmpeg = _which("ffmpeg")
except RuntimeError:
logger.warning("抽尾帧失败:未找到 ffmpeg")
return False
dest.parent.mkdir(parents=True, exist_ok=True)
# 时长未知时用 sseof 从末尾回退
cmd = [
ffmpeg,
"-y",
"-sseof",
"-0.1",
"-i",
str(src),
"-frames:v",
"1",
"-q:v",
"2",
str(dest),
]
proc = subprocess.run(cmd, capture_output=True, text=True)
if proc.returncode != 0 or not dest.exists() or dest.stat().st_size <= 0:
logger.warning(
"抽尾帧失败 path=%s stderr=%s",
src,
(proc.stderr or "")[-500:],
)
return False
return True
def _canvas(opts: ComposeOptions) -> tuple[int, int]:
w, h = _RATIO_SIZE.get(opts.ratio, _RATIO_SIZE["16:9"])
if opts.resolution_mode == "hd":
# Scale up ~1.5x for HD preview of image_text / compose
return int(w * 1.5) // 2 * 2, int(h * 1.5) // 2 * 2
return w, h
def _find_cjk_font() -> str | None:
"""Return a path usable by drawtext fontfile=…(优先环境变量与仓库内置字体)。"""
bundled_dir = Path(__file__).resolve().parents[1] / "assets" / "fonts"
bundled = [
bundled_dir / "NotoSansSC-Regular.ttf",
bundled_dir / "NotoSansSC-Regular.otf",
]
candidates = [
os.environ.get("FRAMECUT_FONT"),
# 仓库内置(部署时随代码带走,服务器不必再安装字体)
*[str(path) for path in bundled if path.is_file()],
r"C:\Windows\Fonts\msyhbd.ttc",
r"C:\Windows\Fonts\msyh.ttc",
r"C:\Windows\Fonts\simhei.ttf",
r"C:\Windows\Fonts\simkai.ttf",
# Ubuntu / Debian 常见路径
"/usr/share/fonts/truetype/wqy/wqy-zenhei.ttc",
"/usr/share/fonts/truetype/wqy/wqy-microhei.ttc",
"/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc",
"/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.otf",
"/usr/share/fonts/truetype/noto/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/truetype/noto/NotoSansCJK-Bold.ttc",
"/usr/share/fonts/truetype/noto/NotoSansCJKsc-Regular.otf",
"/usr/share/fonts/noto-cjk/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/google-noto-cjk/NotoSansCJK-Regular.ttc",
"/usr/share/fonts/truetype/droid/DroidSansFallbackFull.ttf",
"/usr/share/fonts/truetype/arphic/uming.ttc",
"/System/Library/Fonts/PingFang.ttc",
"/System/Library/Fonts/STHeiti Light.ttc",
]
for c in candidates:
if c and Path(c).exists():
return c
# fontconfig 兜底:解析中文字体文件路径
try:
import subprocess
out = subprocess.check_output(
["fc-match", "-f", "%{file}", ":lang=zh-cn"],
text=True,
stderr=subprocess.DEVNULL,
timeout=3,
).strip()
if out and Path(out).exists():
return out
except Exception: # noqa: BLE001
pass
return None
def _escape_drawtext(text: str) -> str:
"""Escape text for ffmpeg drawtext filter."""
t = (text or "").replace("\n", " ").replace("\r", " ").strip()
t = t.replace("\\", "\\\\")
t = t.replace(":", "\\:")
t = t.replace("'", "\\'")
t = t.replace("%", "\\%")
return t
def _strip_caption_punct(text: str) -> str:
"""Remove punctuation/symbols from on-screen subtitle text."""
t = _CAPTION_PUNCT_RE.sub("", text or "")
return re.sub(r"\s+", " ", t).strip()
def _escape_fontfile(path: str) -> str:
# Windows paths need escaping for filtergraph: C\:/Windows/Fonts/msyh.ttc
p = Path(path).resolve().as_posix()
return p.replace(":", "\\:")
def _one_line_caption(text: str, *, max_chars: int = 22) -> str:
"""Single-line bottom caption; truncate if too long (no ellipsis punctuation)."""
raw = _strip_caption_punct((text or "").replace("\n", " ").replace("\r", " "))
if not raw:
return ""
if len(raw) <= max_chars:
return raw
return raw[:max_chars]
def _split_caption_chunks(text: str, *, max_chars: int = 18) -> list[str]:
"""Split narration into timed bottom-caption cues (one line each)."""
raw = (text or "").replace("\n", " ").replace("\r", " ").strip()
if not raw:
return []
# Prefer clause breaks on Chinese/English punctuation
pieces: list[str] = []
buf = ""
for ch in raw:
buf += ch
if ch in ",。!?;、,.!?;:":
piece = _strip_caption_punct(buf)
if piece:
pieces.append(piece)
buf = ""
if buf.strip():
piece = _strip_caption_punct(buf)
if piece:
pieces.append(piece)
if not pieces:
pieces = [_strip_caption_punct(raw)]
if not pieces[0]:
return []
# Further split long pieces so each cue stays one readable line
chunks: list[str] = []
for piece in pieces:
body = _strip_caption_punct(piece)
if not body:
continue
if len(body) <= max_chars:
chunks.append(body)
continue
cur = ""
for ch in body:
cur += ch
if len(cur) >= max_chars:
chunks.append(cur.strip())
cur = ""
if cur.strip():
chunks.append(cur.strip())
# Merge tiny leftovers into previous cue
merged: list[str] = []
for c in chunks:
if merged and len(c) <= 2:
merged[-1] = merged[-1] + c
else:
merged.append(c)
clean = [_strip_caption_punct(c) for c in merged if _strip_caption_punct(c)]
return clean or [_strip_caption_punct(raw)[:max_chars]]
def _timed_caption_windows(
text: str,
*,
start: float,
duration: float,
max_chars: int = 18,
) -> list[tuple[float, float, str]]:
"""Allocate each caption chunk a time window proportional to character length."""
chunks = _split_caption_chunks(text, max_chars=max_chars)
if not chunks:
return []
total = max(duration, 0.5)
weights = [max(len(c), 1) for c in chunks]
weight_sum = float(sum(weights))
cursor = start
windows: list[tuple[float, float, str]] = []
for i, (chunk, w) in enumerate(zip(chunks, weights)):
if i == len(chunks) - 1:
end = start + total
else:
end = start + total * (sum(weights[: i + 1]) / weight_sum)
end = max(end, cursor + 0.5)
end = min(end, start + total)
if end <= cursor:
continue
windows.append((cursor, end, chunk))
cursor = end
if windows:
s0, _, t0 = windows[-1]
windows[-1] = (s0, start + total, t0)
return windows
def _make_silent_audio(path: Path, duration: float) -> None:
ffmpeg = _which("ffmpeg")
_run(
[
ffmpeg,
"-y",
"-f",
"lavfi",
"-i",
"anullsrc=channel_layout=stereo:sample_rate=44100",
"-t",
f"{max(duration, 0.5):.3f}",
"-c:a",
"aac",
str(path),
]
)
def _scale_pad(w: int, h: int) -> str:
return (
f"scale={w}:{h}:force_original_aspect_ratio=decrease,"
f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2,format=yuv420p"
)
def _ken_burns_filter(w: int, h: int, duration: float, shot_no: int) -> str:
"""Ken Burns zoom / pan — stronger push-in / pull-out with directional drift."""
frames = max(int(round(duration * 24)), 12)
last = max(frames - 1, 1)
# ~32% scale change (was ~12%) so motion reads clearly on short clips
amp = 0.32
z_max = f"{1.0 + amp:.2f}"
pattern = shot_no % 4
if pattern == 0:
# Push in, centered
z = f"min(1.0+{amp}*on/{last},{z_max})"
x = "iw/2-(iw/zoom/2)"
y = "ih/2-(ih/zoom/2)"
elif pattern == 1:
# Pull out + drift upward
z = f"max({z_max}-{amp}*on/{last},1.0)"
x = "iw/2-(iw/zoom/2)"
y = f"ih/2-(ih/zoom/2)-ih*0.08*on/{last}"
elif pattern == 2:
# Push in + pan right
z = f"min(1.0+{amp}*on/{last},{z_max})"
x = f"(iw-iw/zoom)*on/{last}"
y = "ih/2-(ih/zoom/2)"
else:
# Push in + pan left / slight down
z = f"min(1.0+{amp}*on/{last},{z_max})"
x = f"(iw-iw/zoom)*(1-on/{last})"
y = f"(ih-ih/zoom)*0.4*on/{last}"
return (
f"scale=8000:-1,"
f"zoompan=z='{z}':x='{x}':y='{y}':d={frames}:s={w}x{h}:fps=24,"
f"format=yuv420p"
)
def _bottom_caption_drawtext(
narration: str,
*,
duration: float,
w: int,
h: int,
font: str | None,
scale: float = 1.25,
) -> str:
"""Pixel-sized bottom captions via drawtext (avoids libass PlayRes blow-up)."""
portrait = (h / max(w, 1)) > 1.2
max_chars = 14 if portrait else 22
base = 32 if portrait else 28
font_size = max(24, min(44, int(base * max(0.8, scale))))
y = max(0, h - font_size - (64 if portrait else 48))
windows = _timed_caption_windows(
narration,
start=0.0,
duration=max(duration, 0.5),
max_chars=max_chars,
)
if not windows:
return ""
font_opt = f":fontfile='{_escape_fontfile(font)}'" if font else ""
parts: list[str] = []
for a, b, text in windows:
if b - a < 0.2:
continue
te = _escape_drawtext(text)
# Commas in enable= must be escaped for filtergraph
parts.append(
f"drawtext=text='{te}'{font_opt}:fontsize={font_size}:"
f"fontcolor=white:borderw=3:[email protected]:"
f"box=1:[email protected]:boxborderw=8:"
f"x=(w-text_w)/2:y={y}:"
f"enable='between(t\\,{a:.2f}\\,{b:.2f})'"
)
return ",".join(parts)
def _overlay_drawtext(
w: int,
h: int,
title: str,
subtitle: str,
font: str | None,
*,
layout: str = "top",
title_scale: float = 1.35,
sub_scale: float = 1.3,
) -> str:
"""顶部标题叠字。split 也把副标题放在标题下方,底部留给口播字幕。"""
title = _strip_caption_punct(title)
subtitle = _strip_caption_punct(subtitle)
title_cap = 14 if layout == "split" else 12
sub_cap = 24 if layout == "split" else 18
if len(title) > title_cap:
title = title[:title_cap]
if len(subtitle) > sub_cap:
subtitle = subtitle[:sub_cap]
title_e = _escape_drawtext(title)
sub_e = _escape_drawtext(subtitle)
# Portrait 720 base ~ larger than before so 叠字更醒目
title_size = max(34, min(52, int(w * 0.058 * max(0.8, title_scale))))
sub_size = max(24, min(36, int(w * 0.042 * max(0.8, sub_scale))))
title_y = int(h * 0.055)
sub_y = title_y + title_size + int(h * 0.014)
parts: list[str] = []
if not title_e and not sub_e:
return ""
# Soft vignette behind title block (bottom is reserved for narration captions)
bar_h = int(h * 0.22) if layout == "split" else int(h * 0.2)
parts.append(f"drawbox=x=0:y=0:w={w}:h={bar_h}:[email protected]:t=fill")
font_opt = f":fontfile='{_escape_fontfile(font)}'" if font else ""
if title_e:
parts.append(
f"drawtext=text='{title_e}'{font_opt}:fontsize={title_size}:"
f"fontcolor=white:borderw=4:[email protected]:"
f"x=(w-text_w)/2:y={title_y}"
)
if sub_e:
parts.append(
f"drawtext=text='{sub_e}'{font_opt}:fontsize={sub_size}:"
f"fontcolor=white:borderw=3:[email protected]:"
f"x=(w-text_w)/2:y={sub_y}"
)
return ",".join(parts)
def build_video_caption_vf(
*,
narration: str,
duration: float,
w: int,
h: int,
font: str | None,
title: str = "",
subtitle: str = "",
subtitle_layout: str = "top",
title_scale: float = 1.35,
sub_scale: float = 1.3,
caption_scale: float = 1.25,
) -> str:
"""合成阶段字幕滤镜:顶部标题 + 底部口播,始终烧录(含 split 布局)。"""
parts: list[str] = []
overlay = _overlay_drawtext(
w,
h,
title,
subtitle,
font,
layout=subtitle_layout,
title_scale=title_scale,
sub_scale=sub_scale,
)
if overlay:
parts.append(overlay)
captions = _bottom_caption_drawtext(
narration, duration=duration, w=w, h=h, font=font, scale=caption_scale
)
if captions:
parts.append(captions)
return ",".join(parts)
def _image_to_video_kenburns(
image: Path,
duration: float,
out: Path,
*,
w: int,
h: int,
shot_no: int,
title: str,
subtitle: str,
narration: str,
font: str | None,
subtitle_layout: str = "top",
title_scale: float = 1.35,
sub_scale: float = 1.3,
caption_scale: float = 1.25,
) -> None:
ffmpeg = _which("ffmpeg")
vf = _ken_burns_filter(w, h, duration, shot_no)
captions = build_video_caption_vf(
narration=narration,
duration=duration,
w=w,
h=h,
font=font,
title=title,
subtitle=subtitle,
subtitle_layout=subtitle_layout,
title_scale=title_scale,
sub_scale=sub_scale,
caption_scale=caption_scale,
)
if captions:
vf = f"{vf},{captions}"
_run(
[
ffmpeg,
"-y",
"-loop",
"1",
"-i",
str(image),
"-t",
f"{max(duration, 0.5):.3f}",
"-vf",
vf,
"-r",
"24",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
str(out),
]
)
def _burn_captions_on_video(
video_in: Path,
video_out: Path,
*,
narration: str,
duration: float,
w: int,
h: int,
font: str | None,
caption_scale: float = 1.25,
title: str = "",
subtitle: str = "",
subtitle_layout: str = "top",
title_scale: float = 1.35,
sub_scale: float = 1.3,
keep_audio: bool = False,
) -> None:
"""Burn title + timed bottom narration captions onto an existing video clip."""
vf = build_video_caption_vf(
narration=narration,
duration=duration,
w=w,
h=h,
font=font,
title=title,
subtitle=subtitle,
subtitle_layout=subtitle_layout,
title_scale=title_scale,
sub_scale=sub_scale,
caption_scale=caption_scale,
)
ffmpeg = _which("ffmpeg")
if not vf:
_run([ffmpeg, "-y", "-i", str(video_in), "-c", "copy", str(video_out)])
return
cmd = [
ffmpeg,
"-y",
"-i",
str(video_in),
"-vf",
vf,
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
]
if keep_audio and _probe_has_audio(video_in):
cmd.extend(["-c:a", "aac", "-ac", "2", "-ar", "44100"])
else:
cmd.append("-an")
cmd.append(str(video_out))
_run(cmd)
def _image_to_video(image: Path, duration: float, out: Path, *, w: int, h: int) -> None:
ffmpeg = _which("ffmpeg")
_run(
[
ffmpeg,
"-y",
"-loop",
"1",
"-i",
str(image),
"-t",
f"{max(duration, 0.5):.3f}",
"-vf",
_scale_pad(w, h),
"-r",
"24",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
str(out),
]
)
def _pad_or_trim_video(
src: Path,
dest: Path,
duration: float,
*,
w: int,
h: int,
keep_audio: bool = False,
) -> None:
"""Scale video to canvas and force exact duration: trim if longer, freeze-pad if shorter.
AI clips (Seedance) are often shorter than TTS-allocated shot length; without
padding, continuous mux -shortest truncates narration.
"""
ffmpeg = _which("ffmpeg")
target = max(float(duration), 0.5)
src_dur = probe_duration(src) or 0.0
# Reset PTS before fps/tpad. Seedance clips often have a wild timebase;
# tpad then writes 100h+ timestamps and OOM on trailer.
base_vf = f"{_scale_pad(w, h).replace(',format=yuv420p', '')},setpts=PTS-STARTPTS,fps=24"
if src_dur > 0.05 and src_dur + 0.08 < target:
pad = min(target - src_dur, 120.0)
vf = f"{base_vf},tpad=stop_mode=clone:stop_duration={pad:.3f},format=yuv420p"
else:
vf = f"{base_vf},format=yuv420p"
cmd = [
ffmpeg,
"-y",
"-i",
str(src),
"-t",
f"{target:.3f}",
"-vf",
vf,
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
]
if keep_audio and _probe_has_audio(src):
cmd.extend(["-af", "apad", "-c:a", "aac", "-ac", "2", "-ar", "44100"])
else:
cmd.append("-an")
cmd.append(str(dest))
_run(cmd)
def _mux_shot(
video: Path,
audio: Path,
duration: float,
out: Path,
*,
mix_video_sfx: bool = False,
sfx_volume: float = 0.22,
) -> None:
"""把镜头画面与配音封装;可选把视频里的操作音效压低叠在 TTS 下。"""
ffmpeg = _which("ffmpeg")
target = max(float(duration), 0.5)
if mix_video_sfx and _probe_has_audio(video):
vol = max(0.0, min(float(sfx_volume), 1.0))
_run(
[
ffmpeg,
"-y",
"-i",
str(video),
"-i",
str(audio),
"-filter_complex",
f"[0:a]volume={vol:.3f}[sfx];[1:a]volume=1.0[vo];"
"[sfx][vo]amix=inputs=2:duration=first:dropout_transition=0:normalize=0[a]",
"-map",
"0:v:0",
"-map",
"[a]",
"-t",
f"{target:.3f}",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
"-c:a",
"aac",
"-ac",
"2",
"-ar",
"44100",
str(out),
]
)
return
_run(
[
ffmpeg,
"-y",
"-i",
str(video),
"-i",
str(audio),
"-t",
f"{target:.3f}",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
"-c:a",
"aac",
# Video was already fitted to target; avoid -shortest cutting early
str(out),
]
)
def _copy_fitted_clip(video: Path, duration: float, out: Path) -> None:
"""把已对齐时长的镜头重封装成成片段,保留操作音效轨。"""
ffmpeg = _which("ffmpeg")
_run(
[
ffmpeg,
"-y",
"-i",
str(video),
"-t",
f"{max(duration, 0.5):.3f}",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
"-c:a",
"aac",
"-ac",
"2",
"-ar",
"44100",
str(out),
]
)
def _mux_continuous_narration(
merged: Path,
narration: Path,
output: Path,
*,
mix_video_sfx: bool = False,
sfx_volume: float = 0.22,
) -> None:
"""叠整片 TTS;可选把镜头操作音效压低混入。视频偏短时冻帧补齐,避免旁白被裁切。"""
ffmpeg = _which("ffmpeg")
vid_d = probe_duration(merged) or 0.0
aud_d = probe_duration(narration) or 0.0
video_in = merged
tmp_pad: Path | None = None
keep_sfx = bool(mix_video_sfx and _probe_has_audio(merged))
if aud_d > 0.5 and vid_d > 0.05 and aud_d > vid_d + 0.12:
tmp_pad = merged.with_name(merged.stem + "_pad.mp4")
pad = min(aud_d - vid_d, 120.0)
pad_cmd = [
ffmpeg,
"-y",
"-i",
str(merged),
"-vf",
f"setpts=PTS-STARTPTS,fps=24,tpad=stop_mode=clone:stop_duration={pad:.3f}",
"-t",
f"{aud_d:.3f}",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
]
if keep_sfx:
pad_cmd.extend(["-af", "apad", "-c:a", "aac", "-ac", "2", "-ar", "44100"])
else:
pad_cmd.append("-an")
pad_cmd.append(str(tmp_pad))
_run(pad_cmd)
video_in = tmp_pad
keep_sfx = bool(mix_video_sfx and _probe_has_audio(video_in))
out_t = max(aud_d, vid_d, 0.5)
if keep_sfx:
vol = max(0.0, min(float(sfx_volume), 1.0))
_run(
[
ffmpeg,
"-y",
"-i",
str(video_in),
"-i",
str(narration),
"-filter_complex",
f"[0:a]volume={vol:.3f}[sfx];[1:a]volume=1.0[vo];"
"[sfx][vo]amix=inputs=2:duration=longest:dropout_transition=2:normalize=0[a]",
"-map",
"0:v:0",
"-map",
"[a]",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
"-c:a",
"aac",
"-ac",
"2",
"-ar",
"44100",
"-t",
f"{out_t:.3f}",
"-movflags",
"+faststart",
str(output),
]
)
return
_run(
[
ffmpeg,
"-y",
"-i",
str(video_in),
"-i",
str(narration),
"-map",
"0:v:0",
"-map",
"1:a:0",
"-c:v",
"copy",
"-c:a",
"aac",
"-t",
f"{out_t:.3f}",
"-movflags",
"+faststart",
str(output),
]
)
def compose_project(
shots: list[ShotMedia],
output: Path,
opts: ComposeOptions | None = None,
) -> Path:
if not shots:
raise ValueError("no shots to compose")
opts = opts or ComposeOptions()
w, h = _canvas(opts)
ffmpeg = _which("ffmpeg")
output.parent.mkdir(parents=True, exist_ok=True)
font = _find_cjk_font()
if not font:
logger.error(
"未找到中文字体,叠字/口播字幕会显示为方框;"
"请安装 fonts-wqy-zenhei 或设置 FRAMECUT_FONT"
)
elif opts.mode == "image_text":
logger.info("compose CJK font=%s", font)
with tempfile.TemporaryDirectory(prefix="framecut_") as tmp:
tmp_path = Path(tmp)
segment_paths: list[Path] = []
continuous = bool(opts.full_audio_path and opts.full_audio_path.exists())
keep_sfx = bool(opts.keep_video_sfx)
prefer_va = bool(opts.prefer_video_audio)
# 内置口播或叠音效时,垫片/烧字幕需保留视频音轨
keep_clip_audio = keep_sfx or prefer_va
sfx_vol = float(opts.sfx_volume or 0.22)
for shot in shots:
seg = tmp_path / f"shot_{shot.shot_no:03d}.mp4"
audio = tmp_path / f"shot_{shot.shot_no:03d}.m4a"
video = tmp_path / f"shot_{shot.shot_no:03d}_v.mp4"
if continuous:
# Visual-only segments; continuous narration muxed after concat
_make_silent_audio(audio, shot.duration)
elif shot.audio_path and shot.audio_path.exists():
# Keep full narration; do not truncate to planned duration when audio is longer
audio_dur = probe_duration(shot.audio_path) or shot.duration
use_dur = max(shot.duration, audio_dur)
shot.duration = use_dur
_run(
[
ffmpeg,
"-y",
"-i",
str(shot.audio_path),
"-c:a",
"aac",
str(audio),
]
)
else:
_make_silent_audio(audio, shot.duration)
if opts.mode == "image_text" and shot.image_path and shot.image_path.exists():
title = (shot.overlay_title or "").strip()
subtitle = (shot.overlay_subtitle or "").strip()
_image_to_video_kenburns(
shot.image_path,
shot.duration,
video,
w=w,
h=h,
shot_no=shot.shot_no,
title=title,
subtitle=subtitle,
narration=shot.narration or "",
font=font,
subtitle_layout=opts.subtitle_layout or "top",
title_scale=opts.title_scale,
sub_scale=opts.sub_scale,
caption_scale=opts.caption_scale,
)
elif shot.video_path and shot.video_path.exists() and shot.video_path.suffix.lower() in {
".mp4",
".mov",
".webm",
".mkv",
}:
raw_v = tmp_path / f"shot_{shot.shot_no:03d}_raw.mp4"
_pad_or_trim_video(
shot.video_path,
raw_v,
shot.duration,
w=w,
h=h,
keep_audio=keep_clip_audio,
)
_burn_captions_on_video(
raw_v,
video,
narration=shot.narration or "",
duration=shot.duration,
w=w,
h=h,
font=font,
caption_scale=opts.caption_scale,
title=shot.overlay_title or "",
subtitle=shot.overlay_subtitle or "",
subtitle_layout=opts.subtitle_layout or "top",
title_scale=opts.title_scale,
sub_scale=opts.sub_scale,
keep_audio=keep_clip_audio,
)
elif shot.image_path and shot.image_path.exists():
_image_to_video(shot.image_path, shot.duration, video, w=w, h=h)
capped = tmp_path / f"shot_{shot.shot_no:03d}_cap.mp4"
_burn_captions_on_video(
video,
capped,
narration=shot.narration or "",
duration=shot.duration,
w=w,
h=h,
font=font,
caption_scale=opts.caption_scale,
title=shot.overlay_title or "",
subtitle=shot.overlay_subtitle or "",
subtitle_layout=opts.subtitle_layout or "top",
title_scale=opts.title_scale,
sub_scale=opts.sub_scale,
)
video = capped
else:
_run(
[
ffmpeg,
"-y",
"-f",
"lavfi",
"-i",
f"color=c=0x1a1714:s={w}x{h}:d={max(shot.duration, 0.5):.3f}",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
str(video),
]
)
if prefer_va and _probe_has_audio(video):
# Seedance 内置口播:直接保留视频音轨
_copy_fitted_clip(video, shot.duration, seg)
elif prefer_va and shot.audio_path and shot.audio_path.exists():
# 隐私跳过/无 a 轨:回退单镜 TTS(若有)
logger.warning(
"compose shot %s: no video audio, falling back to shot TTS",
shot.shot_no,
)
_mux_shot(
video,
audio,
shot.duration,
seg,
mix_video_sfx=False,
sfx_volume=sfx_vol,
)
elif prefer_va:
logger.warning(
"compose shot %s: no video audio and no shot TTS; silent segment",
shot.shot_no,
)
_mux_shot(
video,
audio,
shot.duration,
seg,
mix_video_sfx=False,
sfx_volume=sfx_vol,
)
elif continuous and keep_sfx and _probe_has_audio(video):
_copy_fitted_clip(video, shot.duration, seg)
else:
_mux_shot(
video,
audio,
shot.duration,
seg,
mix_video_sfx=keep_sfx and not continuous and not prefer_va,
sfx_volume=sfx_vol,
)
segment_paths.append(seg)
concat_list = tmp_path / "concat.txt"
concat_list.write_text(
"\n".join(f"file '{p.resolve().as_posix()}'" for p in segment_paths),
encoding="utf-8",
)
merged = tmp_path / "merged.mp4"
_run(
[
ffmpeg,
"-y",
"-f",
"concat",
"-safe",
"0",
"-fflags",
"+genpts",
"-i",
str(concat_list),
"-vf",
"setpts=PTS-STARTPTS,fps=24",
"-c:v",
"libx264",
"-pix_fmt",
"yuv420p",
"-c:a",
"aac",
"-ac",
"2",
"-ar",
"44100",
str(merged),
]
)
if continuous and opts.full_audio_path:
# 整片 TTS 叠在镜头操作音效上(无音效则只保留旁白)
voiced = tmp_path / "voiced.mp4"
_mux_continuous_narration(
merged,
opts.full_audio_path,
voiced,
mix_video_sfx=keep_sfx,
sfx_volume=sfx_vol,
)
staged = voiced
else:
staged = merged
if opts.bgm_path and Path(opts.bgm_path).is_file():
mixed = tmp_path / "with_bgm.mp4"
try:
_mix_bgm(staged, Path(opts.bgm_path), mixed, volume=float(opts.bgm_volume or 0.22))
shutil.copy2(mixed, output)
except Exception: # noqa: BLE001
logger.exception("BGM mix failed; exporting without BGM")
if staged == merged and not continuous:
_run(
[
ffmpeg,
"-y",
"-i",
str(merged),
"-c",
"copy",
"-movflags",
"+faststart",
str(output),
]
)
else:
shutil.copy2(staged, output)
elif continuous and opts.full_audio_path:
shutil.copy2(staged, output)
else:
# Captions already burned per-shot via drawtext — remux only.
_run(
[
ffmpeg,
"-y",
"-i",
str(merged),
"-c",
"copy",
"-movflags",
"+faststart",
str(output),
]
)
return output
def _mix_bgm(video: Path, bgm: Path, output: Path, *, volume: float = 0.22) -> None:
"""Loop/trim BGM under existing audio; duck volume below narration."""
ffmpeg = _which("ffmpeg")
vol = max(0.05, min(float(volume), 0.5))
# amix: original audio + quieter looped BGM, duration = first (video)
_run(
[
ffmpeg,
"-y",
"-i",
str(video),
"-stream_loop",
"-1",
"-i",
str(bgm),
"-filter_complex",
f"[1:a]volume={vol:.3f}[bg];[0:a][bg]amix=inputs=2:duration=first:dropout_transition=2[a]",
"-map",
"0:v:0",
"-map",
"[a]",
"-c:v",
"copy",
"-c:a",
"aac",
"-shortest",
"-movflags",
"+faststart",
str(output),
]
)