agentleFS
dotacloverdotaclover/clover-skills/douyin-pip-shorts/SKILL.md

douyin-pip-shorts

Skill0 starsChanged 3 days agoMITView on GitHub

抖音竖屏教学短视频合成:成片打底+操作浮窗(画中画)、逐拍口播、ASS烧字幕、底板编排与时长卡点、抽帧验收。按10/15/30/60秒四档预算出片,片头片尾可选。适用于「拿一段成片教人怎么做」「录屏教程压在成片上方」这类竖屏短片。触发词:画中画、浮窗、操作演示视频、录屏教程、成片打底、烧字幕、竖屏合成、抖音教学视频、15秒视频、一分钟视频。不生成视频、不写脚本、不操作网页。

The file

Files
SKILL.md

抖音竖屏教学短片(画中画)

一句话结构:[片头卡] → 停顿看片 → 口播交代 → 逐拍浮窗 → 出片收尾 → [片尾卡]。 方括号为可选节点;是否启用由任务决定。当前构建器不支持独立首拍标题层,不自动添加钩子。

本技能只解决「合成」这一段。脚本与标题走 douyin-script-studio,出片走 doubao-web-video,通用剪辑重排走 video-post-production。

零、先定档,再动手

以下档位是初始预算参考,各列区间不能任意组合保证可行,也不是平台规范。改时长时同时检查拍数、每拍停留、旁白和可选节点;最终以配置规划及实际可读性为准。

档总时长拍数每拍停留停顿片头片尾交代旁白出片收尾
10秒9.4—10.03—51.5—2.80(可省)1.0—1.4通常不要≈2.00.5
15秒14.4—15.03—51.8—2.61.2—1.81.5—2.0与停顿二选一≈2.60.6
30秒29.4—30.05—72.6—3.02.5—3.02.2—2.81.8—2.24.5—5.00.9
60秒59.0—60.010—142.8—3.42.5—3.02.6—3.22.2—2.6≈7.01.2

预算不足时按内容优先级讨论删步骤、缩短旁白或减少可选节点。每拍阅读时间取决于录屏信息密度;当前构建器最低窗口为1.4秒,不代表所有画面都可读。底板需求由总时长减去片头片尾计算,不固定要求某个秒数。

一、开剪前先规划

assets/plan_timeline.py 可供粗排。正式流程使用配置驱动构建器的 --dry-run,再结合真实旁白时长和画面验收,不要求复制规划器常量。

# SKILL_DIR由本次技能加载结果的Base directory设置为实际安装绝对路径。
P="$SKILL_DIR/assets/plan_timeline.py"
python "$P" --target 30 --beats 6                           # 粗排
python "$P" --target 15 --beats 4 --source 12.4             # 估算底板
python "$P" --target 60 --beats 13 --chapters 2 --source 55  # 两章

规划器仅供预算参考,不把 --emit 常量粘入构建脚本。正式合成使用下面的JSON配置,避免修改已安装技能。

配置驱动合成

  1. 将 assets/example_config.json 复制到用户项目的配置目录,按实际素材调整。示例不包含媒体文件,不能直接生成。
  2. 将 base[].src、recording、所有 voice 和可选卡片 src 设置为本地文件;相对路径统一相对JSON所在目录,与工作目录、技能安装目录无关,也可使用绝对路径。只使用受信任的本地媒体,不接受网络URL。
  3. 实测音频后填 voice_duration;dry-run按声明值预算,不调用ffprobe。真实生成会用ffprobe校验,差异超过0.08秒时拒绝生成并要求更新配置。
  4. 指定独立且不存在的输出目录,其父目录必须已存在;不能位于任何输入文件(包括配置)所在目录及其子目录,也不能包含输入。推荐项目下并列的 inputs/ 和 exports/,配置放在 inputs/,结果放在 exports/run-001/。不要把配置直接放项目根后再把输出放其内部。
python "$SKILL_DIR/assets/build_pip_shorts.py" --help
python "$SKILL_DIR/assets/build_pip_shorts.py" --config "$PROJECT/inputs/config.json" --output-dir "$PROJECT/exports/run-001" --dry-run
python "$SKILL_DIR/assets/build_pip_shorts.py" --config "$PROJECT/inputs/config.json" --output-dir "$PROJECT/exports/run-001"
# 仅字幕同样必须使用新目录;不运行任何媒体子进程
python "$SKILL_DIR/assets/build_pip_shorts.py" --config "$PROJECT/inputs/config.json" --output-dir "$PROJECT/exports/subs-001" --subs-only

配置字段:

  • layout:画布宽高、帧率、浮窗宽、底边距和透明度;宽高须正偶数。
  • timing:目标上限、开头停顿、满屏收尾、浮窗/旁白提前量、章节数和章节过渡时长,全部以秒计。
  • base:有序底板片段,每段 src/start/duration;总可用时长必须够铺满中段。
  • recording:浮窗录屏;beats 每拍的 crop 为原分辨率 [宽,高,x,y],t_in/t_out 为源秒数。录屏取段调整速度以覆盖该拍。
  • background:背景交代 voice/voice_duration/subs;subs 为 [文本,相对旁白起点,相对终点或null]。
  • beats:各拍 voice/voice_duration/sub/tag;字幕支持 {高亮},标签与口播共享规划。
  • subtitles:实际已安装的字体名称、标签字号、口播字号、满屏/浮窗字幕边距及停留秒数。字体由本机libass解析,不下载字体。
  • intro/outro:null 表示省略;启用时为 {"kind":"card或anim","src":"本地素材","dur":2},可附加 voice/voice_duration。静图循环或动效截取,旁白统一混音。

--help 和 --dry-run 零写入、零子进程、零网络;dry-run不保证媒体解码或裁剪区域有效。真实执行需要本机ffmpeg/ffprobe和libass,输出 subtitles.ass、video.mp4 及 build/ 中间文件。已有目录一律拒绝,失败保留现场,不自动删除、重用或覆盖。不得自动移动用户旧版素材。

离线回归测试(所有临时测试文件限定在仓库 _local/,不调用真实ffmpeg或网络):

python -B "$SKILL_DIR/assets/test_build_pip_shorts.py" --test-root "$REPO/_local"

二、实现与验收原则

  1. 共用时间轴。 先拼连续底板,再切浮窗窗口;音轨、字幕和浮窗读同一规划。
  2. 以实测素材为准。 配置填写真实旁白时长;dry-run只检查声明值,不探测媒体。
  3. 按任务设计节奏。 当前每拍配置一条旁白,提前量可配置;静音、定格、重复或倒放是否合适由内容决定,当前构建器不自动生成这些效果。
  4. 渲染验证文字。 字数阈值不能替代实际字体、画布与换行检查。
  5. 隔离每次输出。 新目录避免覆盖源素材与旧版,也减少播放器缓存混淆;不自动搬移旧文件。
  6. 验证后再下结论。 抽取窗口中段与节点前后帧并实际打开;最终时长按本次任务上限检查。

三、可选布局预设

示例配置使用以下布局,可按画布、终端、字体和主体位置调整;它不是不随任务变化的固定规范。

项值
画布1080×1920 / 30fps / yuv420p
浮窗宽960,居中 x=60,高自适应 scale=960:-2
浮窗位置贴底,底边距40px:overlay=60:main_h-overlay_h-40
浮窗透明70%:format=yuva420p,colorchannelmixer=aa=0.70
浮窗描边当前实现固定2px黑描边:drawbox=...:color=black@0.30:t=2
分镜标签46号雅黑白字,压在浮窗上沿内30px
口播字幕58号雅黑白字黑边,浮窗段压在上沿外64px,满屏段 MarginV=380

当前浮窗仅支持居中贴底,标签内边距固定30px;其余已列配置项可调整。更复杂的逐拍位置、独立标题层或背景音乐不在当前CLI范围内。字号按实际可读性选取,不机械随档位缩放。

四、工作流

  1. 确认要求:确定时长上限、步骤数、画布、素材授权与验收重点。
  2. 准备配置:复制中性示例,按需要用规划器粗排;正式使用构建器dry-run。
  3. 量素材:用本地ffprobe检查成片、录屏、旁白,填入实测时长。
  4. 核验旁白:检查用户提供的音频与字幕,听验专有名词;配音生成不属于本技能。
  5. 排底板:配置 base 有序片段;收尾镜头依任务要求选择,见 references/背景填充.md。
  6. 切浮窗:每拍一个 crop 框,坐标在录屏原始分辨率上量,不靠目测;y 要避开表格残行。
  7. 写字幕:标签与口播分两层,MarginV 分别算;长句预拆。
  8. 合成:底板 → 各段编码 → concat copy → 混音 → 烧字幕 → 出片。
  9. 验收:时长、抽帧、静音带、跳点映射,见 references/验收清单.md。
  10. 交付:使用新输出目录,保留用户旧版文件;是否归档或更新项目文档由用户确认。

五、资源

  • assets/plan_timeline.py:可选预算规划器;正式执行前使用构建器dry-run。
  • assets/build_pip_shorts.py:配置驱动合成器,保留底板、浮窗、章节、可选片头片尾、混音和ASS烧字幕。
  • assets/example_config.json:中性配置示例;复制后替换本地素材及参数。
  • assets/test_build_pip_shorts.py:离线mock回归;临时文件限定在显式指定的仓库 _local/。
  • references/版式与时间轴.md:配置预算、可选布局、媒体链与实现边界。
  • references/背景填充.md:素材补充选择、片段序列与跳点验证。
  • references/字幕与叠字.md:字幕配置、高亮、换行和可选Pillow卡片制作。
  • references/坑清单.md:按本地环境核验的诊断线索与安全处理。
  • references/验收清单.md:按当前任务检查规格、抽帧、声音、内容与交付。

六、边界

  • 只合成本地素材,不调模型生成素材、不写口播稿与标题、不操作网页、不自动发布。
  • 发布前核对内容与画面、使用权和必要声明;平台规则需另行核验可靠来源,不以历史处罚个案作普遍承诺。
  • 精确文字优先用可控字幕或预制卡片;Pillow是可选制作工具,不是本构建器必需依赖。
  • 非标准时长可以配置;可读性以实际素材和用户要求验收,不强制套最近档位。
  • 当前不保留底板原声或背景音乐,不下载字体;mock未验证真实编码、声音或视觉质量。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.