---
name: chatcut-property-merge
description: This skill should be used when the user supplies multiple local real-estate walkthrough or property-showcase video clips (e.g. 实探视频, 带看视频, 探盘视频) and asks to merge them into one edited video with accurate subtitles, keyword highlights, on-screen overlay cards, background music, and POI (point-of-interest such as 商场 / 学校 / 医院 / 公园 / 地铁) callouts. Trigger phrases include 合并剪辑, 批量合并, 实探视频剪辑, 字幕高亮, 重点标注, POI 叠加, 背景音乐, 删除卡顿/语气词, applied to a batch of numbered local video files. The workflow is built on the ChatCut MCP (chatcut-*) toolchain plus local Python helper scripts for overlay cards and royalty-free BGM synthesis.
agent_created: true
---

# ChatCut 实探视频批量合并剪辑

## Overview

将多条本地房产实探 / 带看视频按序号合并为一段结构清晰、重点突出的成片，自动完成：转写字幕 → 清理口播（卡顿 / 语气词）→ 关键词高亮 → 贴图文字说明 → 低音量氛围 BGM → 周边配套（POI）识别叠加 → 导出。

整套流程基于 **ChatCut MCP（`chatcut-*` 工具）** 的可编辑时间线，叠加层由本地 Python 脚本（`scripts/`）生成，渲染既可在浏览器本地完成，也可走云端。

## When To Use

- 用户提供 `1.mp4 2.mp4 3.mp4 ...` 等多条本地素材并说「按序号合并剪辑」。
- 要求中同时出现：字幕、重点高亮、贴图/文字说明、BGM、POI（商场/学校/医院/公园等）叠加、删卡顿/语气词。
- 房产 / 探盘 / 带看类视频的批量粗剪与精修。

若用户只给**单条**视频、或不要字幕 / POI 等部分环节，仍可用本流程，跳过对应步骤即可。

## Prerequisites（环境）

ChatCut 本地上传助手 `chatcut-upload-media` 依赖 `ffmpeg` / `ffprobe` / `node`。本机已确认可用路径：

- `C:/Users/Administrator/.workbuddy/binaries/ffmpeg/ffmpeg-9.0.1-essentials_build/bin`（含 `ffmpeg.exe` + `ffprobe.exe`）
- `C:/Users/Administrator/.workbuddy/binaries/node/versions/24.14.0`（node）

执行上传命令前，先把它们加入 PATH：

```bash
export PATH="/c/Users/Administrator/.workbuddy/binaries/ffmpeg/ffmpeg-9.0.1-essentials_build/bin:/c/Users/Administrator/.workbuddy/binaries/node/versions/24.14.0:$PATH"
```

中文字体（贴图与字幕）：`C:/Windows/Fonts/msyh.ttc`（常规）、`msyhbd.ttc`（粗体）——ChatCut 字幕经 libass/DirectWrite 可直接用「Microsoft YaHei」。

## Workflow

### Step 1 — 建项目
`chatcut__create_project`：`compositionWidth=1920, compositionHeight=1080, fps=30`。返回 `projectId` 与 `timelineId`，后续所有调用都要带上。

### Step 2 — 上传素材
1. `chatcut__import_media`（`action: create_session`）拿到 `token` + `endpoint`。
2. 用上传助手批量上传，**每批最多 4 个文件**：
   ```bash
   chatcut-upload-media --token <token> --endpoint <endpoint> \
     "1.mp4" "2.mp4" "3.mp4" "4.mp4" --json-out "$TEMP/imports.json"
   ```
3. 解析 JSON：`result.assetId` 即为素材 ID（`assetType` 区分 video / image / audio）。

### Step 3 — 转写
- 上传助手已自动抽音轨；逐条 `chatcut__trigger_transcript`（`asset` + `timelineId` + `projectId`）。多数情况下后端已 `complete`，无需等待。
- `chatcut__read_script`（`timelineId` + `projectId`）读取整段时间线口播（markdown，含 `[sN]` 段落编号）。

### Step 4 — 按序号拼接
`chatcut__edit_item` 的 `adds` 数组，按素材序号顺序，每段 `type:"video", assetId, alignTo:"track-end", trackId:"V1"` 链式拼接。

### Step 5 — 清理口播（删卡顿 / 语气词）
1. `chatcut__clean_script`（`longSilence: 800`）压缩超过 0.8s 的长停顿（即「卡顿」），保留自然呼吸节奏。
2. `chatcut__read_script` 重读，用 `chatcut__apply_script` 提交编辑后的 markdown：删除「啊 / 呢 / 呃」等语气词与冗余过渡句（如「就是一点」）。**务必保留顶部 4 行标记**（`script-stamp` / `script-lib-stamp` / `script-timeline` / `script-track`）与原始 `[sN]` 身份，只改正文。

### Step 6 — 字幕 + 关键词高亮
1. `chatcut__edit_captions`（`action: enable`）开启字幕轨道。
2. `chatcut__read_captions` 读取全部字幕卡片与 `revision`。**分页参数必须放进 `json` 字段**：`{"limit":50,"offset":50,"revision":"fnv1a:..."}`。
3. `chatcut__edit_captions`（`action: batch`）批量 `set_card_span_style` 高亮重点词。样式模板见下（琥珀金卖点 / 蓝色交通 POI），朗读时带淡入动效。

### Step 7 — 生成叠加层 + BGM（本地脚本）
- `scripts/make_overlays.py`：JSON 配置驱动，生成 1920×1080 透明 PNG 卡片（置于顶部，避开底部字幕）。先 `cards.json` 定义各卡文案/配色/出现时机，再运行。
- `scripts/make_bgm.py <时长秒> [输出.wav]`：合成免版权轻氛围钢琴垫乐（I–vi–IV–V + 琶音），立体声，音量压低，后期再调。
- `scripts/poi_detect.py <转写文本或字幕.md>`：扫描口播，输出 POI 命中（分类 + 词 + 配色），据此绘制配套卡。

### Step 8 — 上传并铺叠加层
1. `chatcut__import_media` 分批（≤4）上传 8 张贴图 + 1 个 BGM，拿 `assetId`。
2. `chatcut__edit_item` 的 `adds`：
   - 贴图：`type:"image", assetId, from:"<起点s>", duration:"<时长s>"`（起点/时长来自转写时间轴）；自动落在非重叠轨道（V2+），全部置于顶部。
   - BGM：`type:"audio", assetId, from:"0s", duration, decibelAdjustment:-15, audioFadeIn:1, audioFadeOut:2.5`（压低到人声下，带淡入淡出）。

### Step 9 — 验证 + 导出
- `chatcut__preview_timeline`（`views:["timeline"]` 看结构；`views:["viewer"], viewerFrames:[...]` 取像素帧需已连接的浏览器执行器）。
- `chatcut__submit_export`（`format:"video", codec:"h264", resolution:"1080p", renderMode:"local"` 或 `"cloud"`，带 `idempotencyKey` 防重）。
- `chatcut__track_export`（`action:"status", renderIds`）跟踪进度。
- 本地渲染（`local`）依赖浏览器 lease：会话中断 / 上下文压缩会导致 `BrowserDisconnectedError`。**省心方案用 `renderMode:"cloud"`**（服务器渲染，不依赖本地浏览器，1080p 封顶）。

## Critical Gotchas（必看）

- **上传 PATH**：不在 PATH 时 `chatcut-upload-media` 直接失败，先 `export PATH=...ffmpeg bin...;...node...`。
- **`read_captions` 分页**：`limit/offset/revision` 必须包在 `json` 字符串字段里，否则参数被忽略、只读前 50 张。
- **`apply_script` 易错**：删词时别动顶部 4 行标记与 `[sN]`；改完务必回填原始 `script-stamp`。
- **BGM `add_pad` 广播**：numpy 切片累加要用 `L[i0:i0+n] += ...`，不能直接对整段 `L[:] += sig`（长度不一致会广播报错）。
- **本地渲染断连**：长会话下 `renderMode:"local"` 易因浏览器断开失败；重试即可，或直接改用 `"cloud"`。
- **POI 不硬编**：只叠加口播里**实际提到**的配套；未提及的类别不要编造卡片。

## POI 检测规则（`scripts/poi_detect.py`）

逐句扫描转写，命中即归类并配色（叠加卡用对应色）：

| 类别 | 关键词 | 配色 |
|---|---|---|
| 商场 | 商场、广场、mall、购物中心、万象城、万达 | 橙 `#F59E0B` |
| 学校 | 小学、中学、大学、学校、附小、附中、学院 | 蓝 `#3B82F6` |
| 医院 | 医院、三甲、卫生院、诊所 | 红 `#EF4444` |
| 公园 | 公园、绿地、湿地公园、市政公园 | 绿 `#22C55E` |
| 交通 | 地铁、地铁口、站、公交、轻轨、高铁 | 青 `#06B6D4` |
| 生活 | 超市、菜市场、银行、菜场 | 紫 `#A855F7` |

同一类别取首次出现时间作为卡片起点；可在 Step 8 与对应讲解片段对齐叠加。

## Resources

- `scripts/make_overlays.py` — JSON 驱动的透明贴图卡片生成器（含 `card()` 绘制函数 + 区域预设）。
- `scripts/make_bgm.py` — 免版权氛围 BGM 合成（参数化时长）。
- `scripts/poi_detect.py` — 转写文本 POI 分类检测。
- `references/chatcut_tools.md` — ChatCut MCP 工具契约、参数示例与全部坑点详版。