Open-source AI podcast clipper. Generate vertical clips with face tracking and burned-in captions. CLI, MCP server, web app.
Python ai-toolsauto-captionscaptionscliffmpegmcpmcp-serveropusclip-alternativepodcast-clipspodcastsshortform-videovertical-videowhisper
"""FFmpeg / ffprobe utility helpers.
Extracted from video_processor.py so small probing functions can be
reused (and unit-tested) without pulling in the 3600+ lines of the
rendering pipeline. The rendering module re-exports these to keep the
historical import surface stable.
All functions here route subprocess calls through utils.proc.run so
they inherit the mandatory timeout + structured logging.
"""
from __future__ import annotations
import json
import math
import os
from utils.log import warn as log_warn
import sys
from typing import Optional
from services.encoder import get_video_encode_flags
from utils.proc import run as proc_run
# Max time for a short probe. Encode timeouts scale with duration via
# ffmpeg_timeout(); a 40s 1080x1920 libx264 slower pass on CPU can exceed 300s.
FFMPEG_TIMEOUT = 300
# Quality presets: name → (crf, preset) for libx264.
# Lower CRF = higher quality = larger file. 18 is visually lossless.
QUALITY_PRESETS = {
"low": {"crf": "28", "preset": "fast"}, # ~2-4 MB/min, fast encode
"medium": {"crf": "23", "preset": "medium"}, # ~4-8 MB/min, balanced
"high": {"crf": "18", "preset": "slow"}, # ~8-15 MB/min, great quality
"max": {"crf": "14", "preset": "slower"}, # ~15-30 MB/min, near-lossless
}
def cpu_flags() -> list:
"""libx264 flags for the current PODCLI_QUALITY. Read at call time so a
`process --quality` set after import is what actually encodes."""
quality = os.environ.get("PODCLI_QUALITY", "high")
qp = QUALITY_PRESETS.get(quality, QUALITY_PRESETS["high"])
return [
"-c:v", "libx264",
"-crf", qp["crf"],
"-preset", qp["preset"],
"-profile:v", "high",
"-pix_fmt", "yuv420p",
]
CPU_FLAGS = cpu_flags()
def ffmpeg_timeout(duration_s: float | None = None) -> float:
"""Seconds allowed for one encode. Probes keep using FFMPEG_TIMEOUT."""
base = float(FFMPEG_TIMEOUT)
if duration_s and duration_s > 0:
return min(1800.0, max(base, duration_s * 20.0 + 120.0))
return base
def run_ffmpeg_with_fallback(
cmd_parts_before_enc: list,
cmd_parts_after_enc: list,
output_path: str,
label: str = "encode",
duration_s: float | None = None,
) -> str:
"""Run an FFmpeg command with the best encoder; retry libx264 on failure.
Final command shape:
cmd_parts_before_enc + <encoder_flags> + cmd_parts_after_enc + [output_path]
If the preferred hardware encoder fails, the function automatically
retries with libx264 before raising.
"""
enc_flags = get_video_encode_flags()
fallback_flags = cpu_flags()
cmd = cmd_parts_before_enc + enc_flags + cmd_parts_after_enc + [output_path]
timeout = ffmpeg_timeout(duration_s)
result = proc_run(cmd, timeout=timeout, check=False)
if result.returncode == 0:
return output_path
if enc_flags != fallback_flags:
print(
f"Warning: HW encoder failed for {label}, falling back to libx264",
file=sys.stderr,
)
cmd_fallback = cmd_parts_before_enc + fallback_flags + cmd_parts_after_enc + [output_path]
result2 = proc_run(cmd_fallback, timeout=timeout, check=False)
if result2.returncode == 0:
return output_path
raise RuntimeError(
f"FFmpeg {label} failed (both HW and CPU): {result2.stderr[-500:]}"
)
raise RuntimeError(f"FFmpeg {label} failed: {result.stderr[-500:]}")
def get_video_info(video_path: str) -> dict:
"""Probe a media file and return the full ffprobe JSON payload."""
cmd = [
"ffprobe",
"-v", "quiet",
"-print_format", "json",
"-show_format",
"-show_streams",
video_path,
]
result = proc_run(cmd, timeout=FFMPEG_TIMEOUT, check=False)
if result.returncode != 0:
raise RuntimeError(f"ffprobe failed: {result.stderr}")
return json.loads(result.stdout)
def has_audio_stream(video_path: str) -> bool:
"""Return True if the file has any audio stream (best-effort)."""
try:
info = get_video_info(video_path)
return any(s.get("codec_type") == "audio" for s in info.get("streams", []))
except Exception:
# Assume yes if we can't check. Missing audio is reasonably rare
# and downstream concat filters will surface the real error.
return True
def parse_duration_seconds(value: object) -> Optional[float]:
"""Parse a duration-like value, rejecting non-finite / non-positive numbers."""
try:
parsed = float(str(value).strip())
except Exception:
return None
if not math.isfinite(parsed) or parsed <= 0:
return None
return parsed
def get_media_duration_seconds(video_path: str, default: float = 0.0) -> float:
"""Best-effort media duration in seconds.
Prefers the max valid duration from the format block and per-stream
durations; falls back to `default` if nothing parseable is found.
"""
try:
info = get_video_info(video_path)
except Exception:
return default
candidates: list[float] = []
fmt_duration = parse_duration_seconds(info.get("format", {}).get("duration"))
if fmt_duration is not None:
candidates.append(fmt_duration)
for stream in info.get("streams", []):
stream_duration = parse_duration_seconds(stream.get("duration"))
if stream_duration is not None:
candidates.append(stream_duration)
return max(candidates) if candidates else default
def get_dimensions(video_path: str) -> tuple[int, int]:
"""Return the (width, height) of the first video stream."""
info = get_video_info(video_path)
for stream in info.get("streams", []):
if stream.get("codec_type") == "video":
return int(stream["width"]), int(stream["height"])
raise ValueError(f"No video stream found in {video_path}")
def stream_durations(video_path: str) -> tuple[float | None, float | None]:
"""Return (video_stream_duration, audio_stream_duration) in seconds."""
try:
info = get_video_info(video_path)
except Exception:
return None, None
video_d = None
audio_d = None
for stream in info.get("streams", []):
dur = parse_duration_seconds(stream.get("duration"))
if dur is None:
continue
kind = stream.get("codec_type")
if kind == "video" and video_d is None:
video_d = dur
elif kind == "audio" and audio_d is None:
audio_d = dur
return video_d, audio_d
def align_av_duration(path: str, slack: float = 0.2) -> str:
"""Trim a frozen video tail (or pad a short picture) so A/V durations match.
Thumbnail prepend and a timed-out re-encode can leave video longer than
audio. Trim to the shorter stream; keep the original if they already agree
or if the rewrite fails.
"""
video_d, audio_d = stream_durations(path)
if video_d is None or audio_d is None:
return path
gap = abs(video_d - audio_d)
if gap <= slack:
return path
target = min(video_d, audio_d)
tmp = path + ".avalign.mp4"
cmd = [
"ffmpeg", "-y",
"-i", path,
"-t", f"{target:.3f}",
"-c:v", "copy",
"-c:a", "copy",
"-movflags", "+faststart",
tmp,
]
try:
result = proc_run(cmd, timeout=FFMPEG_TIMEOUT, check=False)
if result.returncode == 0 and os.path.exists(tmp) and os.path.getsize(tmp) > 0:
os.replace(tmp, path)
return path
except Exception as exc:
log_warn("media-probe", "proxy encode failed", error=exc)
if os.path.exists(tmp):
try:
os.remove(tmp)
except OSError:
pass
return path