screenkite-clean-cut

screenkite-clean-cut

一次性移除 ScreenKite 录制中的静音间隙和填充词（um、uh、ah、er、hmm）——一次转录、一次试运行、一次剪切。

前提条件

• screenkite CLI，位于 /usr/local/bin/screenkite-alpha（或 screenkite）。
• 在 bundle 目录或其上级目录的任意位置的 .env 中设置 ELEVEN_LABS_API_KEY（带下划线），或在 shell 环境中导出该变量。
• PATH 中有 ffmpeg。
• python3 + requests — 使用 uv run --with requests 避免安装问题。

阶段 1 — 打开项目

'/usr/local/bin/screenkite-alpha' agent project open \
  --path '<absolute-path-to.skbundle>' --json

确认项目为当前版本：

'/usr/local/bin/screenkite-alpha' agent project current --json

阶段 2 — 转录麦克风音频

麦克风音频位于 <bundle>/media/microphone_*.m4a。

# Source .env first if key is not in the shell
set -a && source /path/to/workspace/.env && set +a

uv run --with requests \
  .agents/skills/screenkite-clean-cut/scripts/transcribe_mic.py \
  '<bundle>/media/microphone_<name>.m4a' \
  --edit-dir '<bundle-parent>/<slug>-edit' \
  --language en \
  --num-speakers 1
# Output: <edit-dir>/transcripts/<stem>.json  (word-level, cached)

如果转录 JSON 已存在，重新运行不会执行任何操作。

阶段 3 — 试运行（必需 — 应用前展示给用户）

uv run --with requests \
  .agents/skills/screenkite-clean-cut/scripts/compute_all_cuts.py \
  '<edit-dir>/transcripts/<stem>.json' \
  --min-silence 0.8 \
  --silence-pad 0.15 \
  --filler-pad 0.03 \
  --dry-run

输出包含两个部分：静音间隙和填充词，然后是合并摘要。向用户展示完整表格。未经用户确认，不要应用剪切。

调节参数：

标志	默认值	说明
--min-silence	0.8	短于此时长的间隙会保留
--silence-pad	0.15	静音间隙的两端各保留的时长
--filler-pad	0.03	填充词两端各保留的时长
--fillers	um,uh,ah,er,hmm,hm	用于覆盖默认值的逗号分隔列表

阶段 4 — 应用剪切

所有静音和填充词区间会先合并并排序，再调用一次 editTimeline，因此不会与现有时间线编辑产生顺序问题。

'/usr/local/bin/screenkite-alpha' agent tool call \
  --name editTimeline \
  --input-json "$(uv run --with requests \
      .agents/skills/screenkite-clean-cut/scripts/compute_all_cuts.py \
      '<edit-dir>/transcripts/<stem>.json' \
      --min-silence 0.8 --silence-pad 0.15 --filler-pad 0.03 \
      --emit-tool-input)" \
  --json

或者先保存剪切项，再单独应用：

# Save
uv run --with requests \
  .agents/skills/screenkite-clean-cut/scripts/compute_all_cuts.py \
  '<edit-dir>/transcripts/<stem>.json' \
  --min-silence 0.8 --silence-pad 0.15 --filler-pad 0.03 \
  --output '<edit-dir>/all_cuts.json'

# Apply
python3 .agents/skills/screenkite-clean-cut/scripts/apply_cuts.py \
  '<edit-dir>/all_cuts.json'

阶段 5 — 验证

'/usr/local/bin/screenkite-alpha' agent tool call \
  --name getProjectState --input-json '{"scope":"summary"}' --json

检查 duration 是否大致缩短了移除内容的总秒数。

撤销：editTimeline action=undo — 每次剪切调用一次，按后进先出顺序撤销。

与 screenkite-transcription-cut 的主要区别

	screenkite-transcription-cut	screenkite-clean-cut
移除静音	✅	✅
移除填充词	❌	✅
脚本	compute_silence_cuts.py	compute_all_cuts.py
每轮剪切	仅静音	合并静音和填充词

反模式

• **绝不要跳过试运行。**剪切具有破坏性；撤销时一次只能撤销一步。
• **不要将 --min-silence 设为低于 0.3s。**听起来会很不连贯。
• **不要将 --filler-pad 设为低于 0.02s。**音频在剪接点会出现咔嗒声。
• **不要在未打开项目的情况下运行。**CLI 调用会静默失败。
• 未经审核，不要将 “like”、“right”、“so” 等词添加到 --fillers。 依赖语境判断的词会导致许多误报。只保留犹豫语气词。