Skip to content

利用 AI 大模型和自动化工作流,根据主题或关键词一键生成高清短视频。Generate HD short videos from a topic or keyword with an automated AI workflow.

feat(video): global clip speed multiplier from the UI

Paulo C. Benetti396b045cd7b6
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 0201bcc9..09a3b745 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -32,4 +32,4 @@ jobs:
run: uv run python -m compileall app cli.py main.py webui test
- name: Run deterministic unit tests
- run: uv run python -X utf8 -m unittest test.services.test_state test.services.test_task test.services.test_schema test.services.test_video_effects test.services.test_webui_i18n
+ run: uv run python -X utf8 -m unittest test.services.test_state test.services.test_task test.services.test_schema test.services.test_video_effects test.services.test_clip_speed test.services.test_webui_i18n
diff --git a/app/models/schema.py b/app/models/schema.py
index f1e84516..ab46c2bd 100644
--- a/app/models/schema.py
+++ b/app/models/schema.py
@@ -79,6 +79,7 @@ class VideoParams(BaseModel):
video_concat_mode: Optional[VideoConcatMode] = VideoConcatMode.random.value
video_transition_mode: Optional[VideoTransitionMode] = None
video_clip_duration: Optional[int] = 5
+ video_clip_speed: Optional[float] = 1.0
match_materials_to_script: bool = False
video_count: Optional[int] = 1
diff --git a/app/services/task.py b/app/services/task.py
index 8a38e6a5..68a113f6 100644
--- a/app/services/task.py
+++ b/app/services/task.py
@@ -304,6 +304,7 @@ def generate_final_videos(
video_transition_mode=video_transition_mode,
max_clip_duration=params.video_clip_duration,
threads=params.n_threads,
+ clip_speed=params.video_clip_speed,
)
_progress += 50 / params.video_count / 2
diff --git a/app/services/video.py b/app/services/video.py
index cf812d65..538a5435 100644
--- a/app/services/video.py
+++ b/app/services/video.py
@@ -565,6 +565,7 @@ def combine_videos(
video_transition_mode: VideoTransitionMode = None,
max_clip_duration: int = 5,
threads: int = 2,
+ clip_speed: float = 1.0,
) -> str:
audio_clip = AudioFileClip(audio_file)
try:
@@ -583,6 +584,17 @@ def combine_videos(
# 兼容 API 直接调用时未传转场模式的情况,避免后续访问 .value 时崩溃。
transition_value = getattr(video_transition_mode, "value", video_transition_mode)
+ normalized_clip_speed = utils.normalize_clip_speed(clip_speed)
+ if normalized_clip_speed != 1.0:
+ # 只记录一次最终生效值,既方便定位 API 越界参数被归一化的问题,
+ # 也避免在逐片段热路径中重复输出相同日志。
+ logger.info(f"clip playback speed: {normalized_clip_speed:.2f}x")
+ # max_clip_duration 约束的是成片里的最终播放时长,而不是源视频读取时长。
+ # MoviePy 以 0.5 倍速播放 1.5 秒源画面会得到 3 秒片段,以 2 倍速播放
+ # 6 秒源画面同样会得到 3 秒片段。因此切片前必须按速度反推源时长;如果
+ # 仍固定读取 3 秒再慢放、裁剪,下一段却从源视频第 3 秒开始,会跳过中间
+ # 1.5 秒画面。该计算同时保证不同速度下的源时间线连续且无重叠。
+ source_clip_duration = max_clip_duration * normalized_clip_speed
output_dir = os.path.dirname(combined_video_path)
aspect = VideoAspect(video_aspect)
@@ -600,7 +612,7 @@ def combine_videos(
start_time = 0
while start_time < clip_duration:
- end_time = min(start_time + max_clip_duration, clip_duration)
+ end_time = min(start_time + source_clip_duration, clip_duration)
# 保留所有有效分段。
# 这样既不会丢掉“整段视频本身就短于 max_clip_duration”的素材,
@@ -644,6 +656,11 @@ def combine_videos(
clip = _open_video_clip_quietly(subclipped_item.file_path).subclipped(
subclipped_item.start_time, subclipped_item.end_time
)
+ # 播放速度属于素材本身属性,应在转场前应用。这样 Fade/Slide 等一秒转场
+ # 不会跟随素材速度变成 0.5 秒或 2 秒;后续最大时长裁剪继续作为
+ # 浮点误差或异常素材时长的安全兜底,保证最终片段不突破配置上限。
+ if normalized_clip_speed != 1.0:
+ clip = clip.with_speed_scaled(normalized_clip_speed)
clip_duration = clip.duration
# Not all videos are same size, so we need to resize them
clip_w, clip_h = clip.size
diff --git a/app/utils/utils.py b/app/utils/utils.py
index 196bb968..f2d6b927 100644
--- a/app/utils/utils.py
+++ b/app/utils/utils.py
@@ -1,4 +1,5 @@
import json
+import math
import os
import re
import shutil
@@ -64,6 +65,26 @@ def get_uuid(remove_hyphen: bool = False):
return u
+_CLIP_SPEED_MIN = 0.5
+_CLIP_SPEED_MAX = 2.0
+
+
+def normalize_clip_speed(value, default: float = 1.0) -> float:
+ """将片段播放速度归一化到 WebUI 支持的安全范围。"""
+ try:
+ speed = float(value)
+ except (TypeError, ValueError):
+ return default
+
+ # NaN 会绕过普通的大小比较,并在 MoviePy 计算 duration 时传播;无穷值也不
+ # 是合法用户输入。两者统一回退默认值,保证 API 和内部直接调用都不会生成
+ # 无效时间线。零值和负值同样无法表示正常播放速度。
+ if not math.isfinite(speed) or speed <= 0:
+ return default
+
+ return min(max(speed, _CLIP_SPEED_MIN), _CLIP_SPEED_MAX)
+
+
def root_dir():
return os.path.dirname(os.path.dirname(os.path.dirname(os.path.realpath(__file__))))
diff --git a/test/services/test_clip_speed.py b/test/services/test_clip_speed.py
new file mode 100644
index 00000000..d1a92465
--- /dev/null
+++ b/test/services/test_clip_speed.py
@@ -0,0 +1,30 @@
+import math
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+
+from app.models.schema import VideoParams
+from app.utils import utils
+
+
+class TestClipSpeed(unittest.TestCase):
+ def test_video_params_uses_normal_speed_by_default(self):
+ params = VideoParams(video_subject="test")
+
+ self.assertEqual(params.video_clip_speed, 1.0)
+
+ def test_normalize_clip_speed_clamps_valid_numbers(self):
+ self.assertEqual(utils.normalize_clip_speed(0.1), 0.5)
+ self.assertEqual(utils.normalize_clip_speed(1.3), 1.3)
+ self.assertEqual(utils.normalize_clip_speed(5.0), 2.0)
+
+ def test_normalize_clip_speed_rejects_invalid_values(self):
+ for value in (None, "abc", 0, -2, math.nan, math.inf, -math.inf):
+ with self.subTest(value=value):
+ self.assertEqual(utils.normalize_clip_speed(value), 1.0)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/test/services/test_task.py b/test/services/test_task.py
index 624c5bfd..f783c6d0 100644
--- a/test/services/test_task.py
+++ b/test/services/test_task.py
@@ -53,6 +53,29 @@ class TestTaskService(unittest.TestCase):
custom_system_prompt="Only write short narration.",
)
+ def test_generate_final_videos_forwards_clip_speed(self):
+ """任务编排层必须把用户选择的画面速度传给视频合成服务。"""
+ params = VideoParams(
+ video_subject="test",
+ video_count=1,
+ video_clip_speed=1.25,
+ )
+
+ with (
+ patch.object(tm.video, "combine_videos") as combine_videos,
+ patch.object(tm.video, "generate_video"),
+ patch.object(tm.sm.state, "update_task"),
+ ):
+ tm.generate_final_videos(
+ task_id="clip-speed-task",
+ params=params,
+ downloaded_videos=["material.mp4"],
+ audio_file="audio.mp3",
+ subtitle_path="",
+ )
+
+ self.assertEqual(combine_videos.call_args.kwargs["clip_speed"], 1.25)
+
def test_generate_terms_uses_script_order_mode_when_enabled(self):
"""
默认模式不受影响;只有用户显式开启素材按文案顺序匹配时,任务层才
diff --git a/test/services/test_video.py b/test/services/test_video.py
index 3492be05..ba5da081 100644
--- a/test/services/test_video.py
+++ b/test/services/test_video.py
@@ -479,6 +479,111 @@ class TestVideoService(unittest.TestCase):
)
self.assertEqual(result, combined_video_path)
+ def _capture_source_ranges_for_clip_speed(
+ self,
+ *,
+ source_duration,
+ audio_duration,
+ clip_speed,
+ max_clip_duration=3,
+ ):
+ """使用轻量假视频记录 combine_videos 实际读取的源时间范围。"""
+
+ source_ranges = []
+ written_durations = []
+
+ class _FakeAudioClip:
+ duration = audio_duration
+
+ def close(self):
+ pass
+
+ class _FakeVideoClip:
+ def __init__(self, duration, records_source_range=False):
+ self.duration = duration
+ self.size = (1080, 1920)
+ self.w = 1080
+ self.h = 1920
+ self.records_source_range = records_source_range
+
+ def subclipped(self, start_time, end_time):
+ # 只记录直接从源文件读取的范围。变速后的安全裁剪也会调用
+ # subclipped,但它不代表新的源时间段,不能混入断层判断。
+ if self.records_source_range:
+ source_ranges.append((start_time, end_time))
+ return _FakeVideoClip(end_time - start_time)
+
+ def with_speed_scaled(self, factor):
+ return _FakeVideoClip(self.duration / factor)
+
+ def close(self):
+ pass
+
+ def _open_fake_video_clip(_video_path):
+ return _FakeVideoClip(source_duration, records_source_range=True)
+
+ def _capture_written_clip(clip, *_args, **_kwargs):
+ written_durations.append(clip.duration)
+
+ with tempfile.TemporaryDirectory() as temp_dir:
+ combined_video_path = os.path.join(temp_dir, "combined.mp4")
+ with (
+ patch.object(vd, "AudioFileClip", return_value=_FakeAudioClip()),
+ patch.object(
+ vd,
+ "_open_video_clip_quietly",
+ side_effect=_open_fake_video_clip,
+ ),
+ patch.object(
+ vd,
+ "_write_videofile_with_codec_fallback",
+ side_effect=_capture_written_clip,
+ ),
+ # random 模式默认会打乱同一源视频的切片。这里保持生成顺序,
+ # 才能精确验证相邻源时间段是否连续。
+ patch.object(
+ vd,
+ "_prioritize_unique_source_clips",
+ side_effect=lambda subclipped_items, concat_mode: subclipped_items,
+ ),
+ patch.object(vd, "concat_video_clips_with_ffmpeg"),
+ patch.object(vd, "delete_files"),
+ ):
+ vd.combine_videos(
+ combined_video_path=combined_video_path,
+ video_paths=["clip.mp4"],
+ audio_file="audio.mp3",
+ video_concat_mode=vd.VideoConcatMode.random,
+ max_clip_duration=max_clip_duration,
+ clip_speed=clip_speed,
+ )
+
+ return source_ranges, written_durations
+
+ def test_combine_videos_slow_speed_keeps_source_timeline_continuous(self):
+ """0.5 倍慢放应连续读取 1.5 秒源片段,不能跳过中间画面。"""
+
+ source_ranges, written_durations = self._capture_source_ranges_for_clip_speed(
+ source_duration=4.0,
+ audio_duration=5.9,
+ clip_speed=0.5,
+ )
+
+ self.assertEqual(source_ranges, [(0, 1.5), (1.5, 3.0)])
+ self.assertEqual(written_durations, [3.0, 3.0])
+
+ def test_combine_videos_fast_speed_reads_enough_source_content(self):
+ """2 倍快放应读取 6 秒源画面,使最终片段仍保持 3 秒。"""
+
+ source_ranges, written_durations = self._capture_source_ranges_for_clip_speed(
+ source_duration=8.0,
+ audio_duration=2.9,
+ clip_speed=2.0,
+ )
+
+ self.assertEqual(source_ranges, [(0, 6.0)])
+ self.assertEqual(written_durations, [3.0])
+
def test_combine_videos_keeps_small_duration_safety_margin(self):
"""
音频和素材累计时长刚好相等时,仍应继续追加一个短片段作为安全余量。
diff --git a/webui/Main.py b/webui/Main.py
index 91e4b449..acaf76be 100644
--- a/webui/Main.py
+++ b/webui/Main.py
@@ -906,6 +906,13 @@ def _apply_pending_task_restore():
_set_stable_widget_value(
"video_clip_duration_select", params.get("video_clip_duration", 3)
)
+ _set_stable_widget_value(
+ "video_clip_speed_slider",
+ # API 可以写入超过 WebUI 范围的速度,任务生成阶段会安全归一化,但
+ # 历史记录仍可能保留原值。恢复任务前再次归一化,避免给 Streamlit
+ # slider 注入越界值、NaN 或无穷值导致控件状态异常。
+ utils.normalize_clip_speed(params.get("video_clip_speed", 1.0)),
+ )
_set_stable_widget_value("video_count_select", params.get("video_count", 1))
st.session_state["match_materials_to_script"] = bool(
params.get("match_materials_to_script", False)
@@ -2186,6 +2193,22 @@ def _render_video_settings(panel, params):
key="video_clip_duration_select",
help=tr("Clip Duration Help"),
)
+ clip_speed_key = localized_widget_key("video_clip_speed_slider")
+ # session_state 可能来自旧任务、API 参数或旧版页面状态。控件创建前
+ # 统一归一化,既保留合法选择,也确保 slider 始终收到 0.5~2.0
+ # 范围内的有限浮点数。
+ st.session_state[clip_speed_key] = utils.normalize_clip_speed(
+ st.session_state.get(clip_speed_key, 1.0)
+ )
+ params.video_clip_speed = st.slider(
+ tr("Clip Speed"),
+ min_value=0.5,
+ max_value=2.0,
+ step=0.05,
+ format="%.2fx",
+ key=clip_speed_key,
+ help=tr("Clip Speed Help"),
+ )
params.video_count = stable_selectbox(
tr("Number of Videos Generated Simultaneously"),
options=[1, 2, 3, 4, 5],
diff --git a/webui/i18n/en.json b/webui/i18n/en.json
index b5da9a3d..9833e903 100644
--- a/webui/i18n/en.json
+++ b/webui/i18n/en.json
@@ -74,6 +74,8 @@
"Landscape": "Landscape 16:9",
"Clip Duration": "Maximum Clip Duration (seconds)",
"Clip Duration Help": "Controls the duration of each clip used in the composition, not the total video length.",
+ "Clip Speed": "Clip Speed",
+ "Clip Speed Help": "Adjusts visual material playback only. Voiceover, subtitles, and the maximum output duration of each clip are unchanged.",
"Number of Videos Generated Simultaneously": "Videos per Run",
"Match Materials to Script Order": "Match Visuals to Script Order",
"Match Materials to Script Order Help": "Generate keywords and match materials in script order so visuals follow the current voiceover.",
diff --git a/webui/i18n/ru.json b/webui/i18n/ru.json
index 4306abcd..770be311 100644
--- a/webui/i18n/ru.json
+++ b/webui/i18n/ru.json
@@ -76,6 +76,8 @@
"Landscape": "Горизонтальное 16:9",
"Clip Duration": "Макс. длительность фрагмента (сек.)",
"Clip Duration Help": "Определяет длительность каждого используемого фрагмента, а не общую длину видео.",
+ "Clip Speed": "Скорость фрагментов",
+ "Clip Speed Help": "Меняет только скорость видеоматериалов. Озвучка, субтитры и максимальная длительность каждого фрагмента не изменяются.",
"Number of Videos Generated Simultaneously": "Видео за запуск",
"Audio Settings": "**Настройки аудио**",
"Voiceover Mode": "Режим озвучки",
diff --git a/webui/i18n/zh.json b/webui/i18n/zh.json
index ad9397d0..5afe74bc 100644
--- a/webui/i18n/zh.json
+++ b/webui/i18n/zh.json
@@ -74,6 +74,8 @@
"Landscape": "横屏 16:9(西瓜视频)",
"Clip Duration": "单个片段最大时长(秒)",
"Clip Duration Help": "控制合成时使用的每个视频片段时长,不是视频总时长。",
+ "Clip Speed": "片段播放速度",
+ "Clip Speed Help": "仅调整画面素材的播放速度,不影响配音、字幕和单个片段的最大输出时长。",
"Number of Videos Generated Simultaneously": "同时生成视频数量",
"Match Materials to Script Order": "按文案顺序匹配画面",
"Match Materials to Script Order Help": "按文案顺序生成关键词并匹配素材,使画面更贴近当前旁白。",