clip-add-talking

给视频片段添加讲话人画中画。

安装

cd clip-add-talking
pip install -e .

命令行使用

# 基本用法（默认右下角、圆角矩形）
clip-add-talking background.mp4 talking.mp4 -o output.mp4

# 指定位置
clip-add-talking background.mp4 talking.mp4 -p TL  # 左上角
clip-add-talking background.mp4 talking.mp4 -p BR  # 右下角

# 指定样式
clip-add-talking background.mp4 talking.mp4 -s circle   # 圆形
clip-add-talking background.mp4 talking.mp4 -s rounded  # 圆角矩形
clip-add-talking background.mp4 talking.mp4 -s square   # 正方形

# 指定大小
clip-add-talking background.mp4 talking.mp4 --pip-width 400 --pip-height 400

位置选项

选项	说明
TL	左上角
TR	右上角
BL	左下角
BR	右下角（默认）
C	居中

外框样式

样式	说明
none	无边框
square	正方形
rounded	圆角矩形（默认）
circle	圆形

Python API

简化调用

from clip_add_talking import compose, Position, FrameStyle

result = compose(
    background="background.mp4",
    talking="talking.mp4",
    output="output.mp4",
    position=Position.BOTTOM_RIGHT,
    style=FrameStyle.ROUNDED,
    pip_width=320,
    pip_height=320,
    corner_radius=20,
)

完整配置（推荐用于 Web API）

from clip_add_talking import compose, PipConfig, PipPosition, PipStyle, PipSize

# 方式1：使用配置对象
config = PipConfig(
    position=PipPosition(
        preset="BR",           # 预设位置
        # x=100, y=200,        # 或自定义坐标
        # x_percent=0.9, y_percent=0.9,  # 或百分比位置
        margin=30,
    ),
    style=PipStyle(
        shape="rounded",
        corner_radius=25,
        border_width=0,
        border_color="white",
    ),
    size=PipSize(
        width=400,
        height=400,
        # width_percent=0.25,  # 或百分比大小
    ),
)

result = compose("bg.mp4", "talking.mp4", config=config)

从字典创建（Web API 推荐）

from clip_add_talking import compose_from_dict

# 直接传入字典配置（方便从前端 JSON 转换）
result = compose_from_dict(
    "bg.mp4",
    "talking.mp4",
    pip_config={
        "position": {
            "preset": "BR",
            "margin": 30
        },
        "style": {
            "shape": "rounded",
            "corner_radius": 25
        },
        "size": {
            "width": 400,
            "height": 400
        }
    }
)

配置参数说明

PipPosition（位置）

参数	类型	说明
preset	str	预设位置：TL/TR/BL/BR/C
x	int	自定义 X 坐标（像素）
y	int	自定义 Y 坐标（像素）
x_percent	float	X 位置百分比 (0.0-1.0)
y_percent	float	Y 位置百分比 (0.0-1.0)
margin	int	边距（预设位置时使用）

PipStyle（样式）

参数	类型	说明
shape	str	形状：none/square/rounded/circle
corner_radius	int	圆角半径
border_width	int	边框宽度
border_color	str	边框颜色
shadow	bool	是否有阴影
shadow_opacity	float	阴影透明度
shadow_offset	int	阴影偏移

PipSize（大小）

参数	类型	说明
width	int	宽度（像素）
height	int	高度（像素）
width_percent	float	相对背景宽度的百分比
height_percent	float	相对背景高度的百分比

依赖

• ffmpeg（系统安装）

License

MIT