AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
feat(video): expose native PowerPoint video export
hugohe3280d3bee4452
diff --git a/docs/audio-narration.md b/docs/audio-narration.mdindex cd31aecb..ff1e568b 100644--- a/docs/audio-narration.md+++ b/docs/audio-narration.md@@ -12,16 +12,17 @@ PPT Master can turn the speaker notes into per-slide narration via [`edge-tts`](- With edge, one matching subtitle file per slide under `<project_path>/notes/subtitles/` (`01_cover.srt`, `02_market_landscape.srt`, …). Each file uses a page-local timeline with a `00:00:00,000` origin and edge's word-boundary timing.- With an SVG-to-SRT timing plan, a rebuilt `animations.json` whose click-free entrance animations wait for the relevant subtitle cue, plus a deck-wide `<project_path>/notes/subtitles/total.srt` aligned to the final PPTX timeline. After PowerPoint exports a video, the same command can calibrate the page starts against its audio track for frame-accurate sidecar subtitles.- Optional re-export: a new PPTX in `exports/` with each `m4a` / `mp3` / `wav` file embedded into the matching slide and slide auto-advance timings set to the audio length, so kiosk/auto-play and video export work without manual timing.+- Optional native video export on Windows: `powerpoint_video.py` delegates the final narrated PPTX to PowerPoint 2016+ and waits until its native MP4 encoder succeeds or fails.- The original speaker notes are preserved.## How it works1. **Speaker notes are written as pure spoken narration.** PPT Master's notes spec deliberately produces TTS-friendly prose — no bracketed stage markers, no `Key points:` / `Duration:` meta-lines — so what is read aloud is exactly what's on the page.2. **AI picks the voice for you.** When you ask for narration, the AI checks the deck's primary language (`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …), pulls the selected provider's voice catalog, and recommends 3–6 candidates with a one-line tone description for each (e.g. "steady male voice for financial reporting"). It also recommends a speaking rate or provider defaults based on notes density.-3. **One question, one answer.** You are asked once — voice, rate, and "embed audio back into PPTX (yes/no)" — all with a recommended default. Reply "ok" to accept everything, or just call out the part you want to change.-4. **Generation runs.** With edge, the script writes each page's MP3 and SRT from the same stream to `audio/` and `notes/subtitles/`; cloud providers currently write audio only. For Generate PPTX, the AI maps current SVG content groups to numbered SRT cues, rebuilds click-free animations, and re-exports the deck with audio attached. It then merges the local SRT files using timing values read from that final PPTX. If a PowerPoint-exported video is available, an optional final pass measures each page narration in the video audio and corrects only the page offsets. Long-audio import and automatic long-audio splitting are not supported.+3. **One question, one answer.** You are asked once — provider, voice, rate, "embed audio back into PPTX", and "continue to video" — all with a recommended default. Reply "ok" to accept everything, or just call out the part you want to change.+4. **Generation runs.** With edge, the script writes each page's MP3 and SRT from the same stream to `audio/` and `notes/subtitles/`; cloud providers currently write audio only. For Generate PPTX, the AI maps current SVG content groups to numbered SRT cues, rebuilds click-free animations, and re-exports the deck with audio attached. It then merges the local SRT files using timing values read from that final PPTX. When automatic video export was selected and compatible Windows PowerPoint is available, it continues through PowerPoint's native encoder and waits for the MP4 before aligning the delivery SRT. Long-audio import and automatic long-audio splitting are not supported.-Subtitles remain external artifacts: PPT Master does not embed them into the PPTX or export MP4 directly. Use PowerPoint's native video export with the generated `total.srt`.+Subtitles remain external artifacts: PPT Master does not embed them into the PPTX or burn them into the MP4. Automatic video export delegates to installed Windows PowerPoint; it is not a separate renderer.The shared stage is documented in [`workflows/stages/generate-audio.md`](../skills/ppt-master/workflows/stages/generate-audio.md).@@ -113,8 +114,13 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \--pptx <final_narrated_pptx> --force-# 7. Optional after PowerPoint creates the video: calibrate page starts against-# the exported audio track and write a same-stem sidecar SRT+# 7. Optional on Windows: export through PowerPoint and wait for completion+python3 skills/ppt-master/scripts/powerpoint_video.py --check+python3 skills/ppt-master/scripts/powerpoint_video.py \+ <final_narrated_pptx> -o exports/<final_video>.mp4++# 8. Calibrate page starts against the exported audio track and write a+# same-stem sidecar SRTpython3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \--pptx <final_narrated_pptx> --video <powerpoint_exported_video> \-o exports/<powerpoint_exported_video_stem>.srt --force@@ -129,7 +135,7 @@ The edge command creates `audio/<stem>.mp3` and `notes/subtitles/<stem>.srt` fro`narration_timing.json` is deliberately separate from `animations.json`. It records the ordered SRT-set SHA-256, narration padding, ordered SVG group IDs, and optional 1-based cue numbers. `narration_sync.py animations` rejects a stale fingerprint, validates the group IDs against the current SVGs, and replaces the animation sidecar with only supported PowerPoint fields. `narration_sync.py subtitles` reads the final PPTX's actual presentation order plus millisecond slide-advance and transition values, so `total.srt` follows the native PPTX timeline. A relative `--pptx` path is resolved under `<project_path>`.-PowerPoint's video encoder can quantize each slide/media segment to its output frame clock. Those small per-page differences may accumulate even when the PPTX timing values are correct. Passing the finished `.mp4` / `.wmv` / `.mov` with `--video` uses normalized audio correlation to locate each original page narration in the exported audio track. It changes only the page-level offsets: edge's cue text and page-local `WordBoundary` timing remain untouched. This is a post-export subtitle calibration step; PPT Master still does not create or rewrite the video.+PowerPoint's video encoder can quantize each slide/media segment to its output frame clock. Those small per-page differences may accumulate even when the PPTX timing values are correct. Passing the finished `.mp4` / `.wmv` / `.mov` with `--video` uses normalized audio correlation to locate each original page narration in the exported audio track. It changes only the page-level offsets: edge's cue text and page-local `WordBoundary` timing remain untouched. This is a post-export subtitle calibration step and does not rewrite the video.Use `--no-merge` for the final narrated SVG export. Keeping each SVG line in its own text frame preserves the authored coordinates; paragraph merging lets PowerPoint recalculate multiline text geometry and can introduce visible offsets.@@ -206,6 +212,8 @@ Already listed in `skills/ppt-master/requirements.txt`. `edge-tts` calls MicrosoCloud TTS providers do not require extra Python packages; they use HTTPS directly. Configure the relevant API key in the current shell or in `.env` based on `.env.example`.+Automatic MP4 export adds no Python package. It requires Windows PowerPoint 2016+ and Windows PowerShell; macOS and systems without compatible PowerPoint keep the narrated PPTX and use manual export.+## Tips- **Pacing**: On the Generate PPTX route, speaker notes scale with the independent information groups in the final SVG; 2–5 sentences is a typical rhythm, not a cap. Start with `+0%`; for a dense, deliberately detailed script, try `-5%`.@@ -214,21 +222,32 @@ Cloud TTS providers do not require extra Python packages; they use HTTPS directl## Export as video-Once the narrated PPTX is in `exports/`, PowerPoint exports it as a video natively — no third-party tool needed. The embedded audio plays as each slide's narration, and the per-slide auto-advance timings (set from audio length when you let the AI re-export with `--recorded-narration audio`) drive the video's pacing. `--recorded-narration` rejects `on-click` object animation because it does not generate object-level click timings.+Once the narrated PPTX is in `exports/`, Windows PowerPoint 2016+ can export it automatically through:-**PowerPoint (Windows / Mac, Office 2016+)**:+```bash+python3 skills/ppt-master/scripts/powerpoint_video.py \+ <final_narrated_pptx> -o <final_video.mp4>+```++The command uses recorded timings and narrations, defaults to 1080p/30 fps, and returns only after PowerPoint reports success or failure. The embedded audio plays as each slide's narration, while the per-slide auto-advance timings drive the video's pacing. `--recorded-narration` rejects `on-click` object animation because it does not generate object-level click timings.++**Manual PowerPoint fallback (Windows / Mac, Office 2016+)**:1. Open the narrated `.pptx` from `exports/`.2. **File → Export → Create a Video**.-3. Pick a quality (4K / Full HD / HD / Standard) and "Use Recorded Timings and Narrations" — PPT Master has already set both for you.-4. **Create Video** → save as `.mp4` (or `.wmv` on Windows).-5. For the closest external-subtitle sync, run the optional `narration_sync.py subtitles --video ...` command above and use its same-stem SRT beside the exported video.+3. Pick a quality and "Use Recorded Timings and Narrations".+4. Save as `.mp4` (`.wmv` is also available on Windows).+5. Run the optional subtitle calibration command above and place its same-stem SRT beside the video.++PowerPoint for Mac can export MP4/MOV manually, but Microsoft documents that+animation effects do not play in its movie export. Use the Windows automation+path when animation fidelity matters.**Keynote (Mac)**: open the deck → **File → Export To → Movie…** — Keynote also honors embedded audio and per-slide timings, output `.m4v` / `.mov`.**Tips**:- **No mic, no recording session needed** — the audio is generated, not recorded, so re-runs are deterministic.-- **Animations are preserved** — page transitions and click-free per-element entrance animations from PPT Master are real OOXML and play correctly in the exported video. See [Animations & Transitions](./animations.md).+- **Animation fidelity on Windows** — PowerPoint's Windows video export preserves PPT Master's native page transitions and click-free object animation. Mac movie export has the limitation noted above. See [Animations & Transitions](./animations.md).- **Want to tweak just one slide's audio?** Edit `notes/<page>.md`, re-run `notes_to_audio.py` and the embedding step, then re-export the video — total turnaround is usually under a minute per slide.- **File size**: a 20-page deck at Full HD typically lands at 30–80 MB depending on imagery. Drop to HD if you need a smaller file for sharing.diff --git a/docs/technical-design.md b/docs/technical-design.mdindex fdc0ef5a..a43763e1 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -523,6 +523,7 @@ The post-processing and export stages keep authoring, validation, preview, deliv| `validation/<output_stem>.report.json` | published-PPTX postflight and resource audit | records actual ZIP/package part counts; reruns ZIP and Slide-count checks; labels relationship, structured-package, transition, and animation validation as build-time enforcement; accepts quality-report linkage only when its SHA-256 fingerprint matches the export inputs; and surfaces unresolved tokens, external images, and generic-only font stacks || `exports/<name>_<ts>_native_charts_tables.pptx` (opt-in via `--native-charts-and-tables`) | when `data-pptx-replace-with` markers should replace SVG-derived, shape-based charts/tables with PowerPoint-native Chart/Table objects | data-backed objects with chart/table-specific controls; the default DrawingML shapes remain independently editable || `exports/<name>_<ts>_narrated.pptx` (via `--recorded-narration` or `--narration-audio-dir`) | embeds matched narration audio; complete recorded mode directly supports auto-play and PowerPoint video export | `--recorded-narration` requires matching audio for every slide and writes duration-plus-padding auto-advance; low-level `--narration-audio-dir` permits partial or zero coverage and writes auto-advance only with `--use-narration-timings` |+| `exports/<narrated_stem>.mp4` (optional via `powerpoint_video.py`) | animation-faithful narrated video on Windows PowerPoint 2016+ | delegates to PowerPoint's native encoder and waits for completion; it is a post-PPTX integration, not a second deck renderer || `backup/<ts>/svg_output/` (default output path only; copy is best-effort after directory creation) | re-export from frozen SVG sources without rerunning the LLM | after successful conversion the exporter creates the backup directory and attempts the copy; explicit `-o` creates none, copy failure does not block export, prints a warning outside quiet mode, and leaves postflight `backup_path` empty, while directory-creation failure remains fatal |Validation JSON files are cold audit artifacts, not routine model inputs. The exporter reads the SVG quality report programmatically and, in the default non-quiet flow, prints a compact `[POSTFLIGHT]` receipt with the status, quality-gate result, Slide count, warning-category counts, and artifact paths. Successful agents consume that receipt instead of loading either complete JSON; only failure investigation or an explicit audit extracts targeted report fields.@@ -620,6 +621,12 @@ The interesting design choice is the animation **anchor**, not the effect list.**Why recorded narration rejects on-click object animation.** PowerPoint can record click timings during a real rehearsal, but PPT Master does not synthesize object-level click events. The recorded narration path writes page-level audio and slide auto-advance timings only, so click-driven object reveals would leave the export dependent on extra manual PowerPoint rehearsal. Decks exported with `--recorded-narration` must therefore use click-free object entrances (`after-previous` or `with-previous`).+**Why native video export is a separate command.** Audio synthesis and PPTX+packaging are cross-platform project operations; PowerPoint video encoding is a+Windows desktop integration. `powerpoint_video.py` therefore accepts the final+narrated PPTX, invokes `CreateVideo`, and polls `CreateVideoStatus` to present a+synchronous CLI result without coupling Office automation to the TTS backends.+---## Maintenance Boundaries: What Not To Collapsediff --git a/docs/zh/audio-narration.md b/docs/zh/audio-narration.mdindex 0e9f2aaf..ec4f69ee 100644--- a/docs/zh/audio-narration.md+++ b/docs/zh/audio-narration.md@@ -12,16 +12,17 @@ PPT Master 可以把演讲者备注转成逐页音频旁白(默认基于 [`edg- 使用 Edge 时,每页还有一个同名字幕文件,存放于 `<project_path>/notes/subtitles/`(`01_cover.srt`、`02_market_landscape.srt` …)。每个文件使用以 `00:00:00,000` 为原点的页内时间轴,时间来自 Edge 的词边界。- 提供 SVG 到 SRT 的计时计划后,还会重建 `animations.json`:无点击入场动画会等待相关字幕 cue;同时生成与最终 PPTX 时间轴一致的 `<project_path>/notes/subtitles/total.srt`。PowerPoint 导出视频后,还可用同一命令根据视频音轨校准每页起点,得到帧级对齐的外挂字幕。- 可选重新导出:在 `exports/` 生成新版 PPTX,每页对应的 `m4a` / `mp3` / `wav` 音频已嵌入到该页,且页面切换时间按音频长度自动设置——无人值守自动播放和视频导出都不用再手动调时间。+- Windows 下可选原生视频导出:`powerpoint_video.py` 把最终带旁白 PPTX 交给 PowerPoint 2016+,并等待其原生 MP4 编码成功或失败。- 演讲者备注原样保留。## 它是怎么做到的1. **备注本身就是为 TTS 写的口播稿**。PPT Master 的 notes 规范刻意产出适合朗读的散文——没有 `[过渡]` / `[停顿]` 这种舞台标记,也没有 `要点:` / `时长:` 这种 meta 行——念出来的内容就是页面上的内容。2. **AI 替你选音色**。当你提出生成旁白时,AI 根据 deck 的主语言(`zh-CN` / `en-US` / `ja-JP` / `ko-KR` / …)和所选 provider 拉取或解释可用音色,挑出候选并给每个写一句中文调性说明(如"稳重男声·适合财报")。语速/风格也会基于 notes 信息密度给出推荐值。-3. **一次问完,一次回答**。AI 在一条消息里同时问三件事——生成模式、音色、是否把音频嵌入回 PPTX——每项都标了推荐值。回"好"接受全部默认,或者只说要改的部分(如"音色 2,语速 -5%")。-4. **执行**。使用 Edge 时,脚本从同一次流中把每页 MP3 和 SRT 分别写到 `audio/` 与 `notes/subtitles/`;云端 provider 目前仍只写音频。对于 Generate PPTX,AI 将当前 SVG 内容组映射到编号后的 SRT cue,重建无点击动画,再导出带音频的 PPTX;最后从该 PPTX 读回实际计时并合并逐页 SRT。如果已有 PowerPoint 导出的视频,可再根据视频音轨测出每页旁白的真实起点,只修正分页偏移。不支持长音频导入或自动拆分。+3. **一次问完,一次回答**。AI 在一条消息里同时确认 provider、音色、语速、是否嵌入 PPTX,以及是否继续导出视频;每项都标推荐值。回"好"接受全部默认,或者只说要改的部分(如"音色 2,语速 -5%")。+4. **执行**。使用 Edge 时,脚本从同一次流中把每页 MP3 和 SRT 分别写到 `audio/` 与 `notes/subtitles/`;云端 provider 目前仍只写音频。对于 Generate PPTX,AI 将当前 SVG 内容组映射到编号后的 SRT cue,重建无点击动画,再导出带音频的 PPTX;最后从该 PPTX 读回实际计时并合并逐页 SRT。若用户选择自动视频导出且本机 Windows PowerPoint 兼容,则继续调用 PowerPoint 原生编码器,等 MP4 完成后再校准交付字幕。不支持长音频导入或自动拆分。-字幕保持为外部 SRT 文件:PPT Master 不把字幕嵌入 PPTX,也不直接导出 MP4。请使用 PowerPoint 原生视频导出,并配套使用生成的 `total.srt`。+字幕保持为外部 SRT 文件:PPT Master 不把字幕嵌入 PPTX,也不烧录进 MP4。自动视频导出委托给本机 Windows PowerPoint,并不是另一套渲染器。共享阶段见 [`workflows/stages/generate-audio.md`](../../skills/ppt-master/workflows/stages/generate-audio.md)。@@ -112,8 +113,12 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \--pptx <final_narrated_pptx> --force-# 7. 可选:PowerPoint 创建视频后,根据导出音轨校准每页起点,-# 生成与视频同名的外挂 SRT+# 7. Windows 可选:通过 PowerPoint 导出视频并等待完成+python3 skills/ppt-master/scripts/powerpoint_video.py --check+python3 skills/ppt-master/scripts/powerpoint_video.py \+ <final_narrated_pptx> -o exports/<final_video>.mp4++# 8. 根据导出音轨校准每页起点,生成与视频同名的外挂 SRTpython3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \--pptx <final_narrated_pptx> --video <powerpoint_exported_video> \-o exports/<powerpoint_exported_video_stem>.srt --force@@ -127,7 +132,7 @@ Edge 命令会从同一次流式请求中生成 `audio/<stem>.mp3` 与 `notes/su`narration_timing.json` 与 `animations.json` 刻意分离:前者记录整套有序 SRT 的 SHA-256、旁白 padding、有序 SVG 组 ID 和可选的 1-based cue 编号。`narration_sync.py animations` 会拒绝过期的 SRT 指纹,用当前 SVG 校验组 ID,并用 PowerPoint 支持的字段完整替换动画 sidecar。`narration_sync.py subtitles` 从最终 PPTX 读取真实页面关系顺序、毫秒级页面推进与转场时间,因此 `total.srt` 使用原生 PPTX 时间轴。相对 `--pptx` 路径按 `<project_path>` 解析。-PowerPoint 的视频编码器可能把每个页面 / 媒体段落量化到输出帧时钟;即使 PPTX 计时值正确,这些很小的分页误差仍可能逐页累积。把最终 `.mp4` / `.wmv` / `.mov` 通过 `--video` 传入后,脚本会用归一化音频相关性在视频音轨中定位每页原始旁白。它只改页级偏移,Edge 的字幕文本和页内 `WordBoundary` 时间保持不变。这是视频导出后的字幕校准步骤;PPT Master 仍不创建或改写视频。+PowerPoint 的视频编码器可能把每个页面 / 媒体段落量化到输出帧时钟;即使 PPTX 计时值正确,这些很小的分页误差仍可能逐页累积。把最终 `.mp4` / `.wmv` / `.mov` 通过 `--video` 传入后,脚本会用归一化音频相关性在视频音轨中定位每页原始旁白。它只改页级偏移,Edge 的字幕文本和页内 `WordBoundary` 时间保持不变;这是视频导出后的字幕校准步骤,不会改写视频。最终带旁白的 SVG 导出固定使用 `--no-merge`。让每条 SVG 文本行保持独立文本框,可以保留作者坐标;合并段落会让 PowerPoint 重新计算多行文本几何,可能造成肉眼可见的偏移。@@ -202,6 +207,8 @@ python3 -m pip install edge-tts已写入 `skills/ppt-master/requirements.txt`。`edge-tts` 调用微软的在线 TTS 服务,**生成时**需要联网;生成后的音频是本地文件,PowerPoint 播放和视频导出都不依赖网络。云端 TTS provider 不需要额外 Python 包,直接通过 HTTPS 调用;按 `.env.example` 配置对应 API Key 即可。+自动 MP4 导出不增加 Python 依赖,但要求 Windows PowerPoint 2016+ 与 Windows PowerShell;macOS 或没有兼容 PowerPoint 的机器保留带旁白 PPTX,改用手动导出。+## 经验值- **语速**:在 Generate PPTX 路线上,PPT Master 会根据最终 SVG 中的独立信息组调整讲稿长度;每页 2–5 句只是常见节奏,并非上限。可先使用 `+0%`,较密且刻意保留细节的讲稿可尝试 `-5%`。@@ -212,21 +219,30 @@ python3 -m pip install edge-tts## 导出为视频-带旁白的 PPTX 在 `exports/` 里就绪后,PowerPoint 自带"创建视频"功能可以直接把它导出成 MP4——不需要任何第三方工具。嵌入的音频会作为每页旁白播放;页间切换时间已经由 PPT Master 在嵌入时按音频长度自动设好(用 `--recorded-narration audio` 重新导出时),所以视频节奏和旁白完全同步。`--recorded-narration` 会拒绝 `on-click` 对象动画,因为 PPT Master 不生成对象级点击计时。+带旁白的 PPTX 在 `exports/` 里就绪后,Windows PowerPoint 2016+ 可通过下面的接口自动导出:-**PowerPoint(Windows / Mac,Office 2016+)**:+```bash+python3 skills/ppt-master/scripts/powerpoint_video.py \+ <final_narrated_pptx> -o <final_video.mp4>+```++命令使用录制的计时和旁白,默认输出 1080p/30fps,并在 PowerPoint 明确成功或失败后才返回。嵌入音频作为逐页旁白播放,页面自动推进时间控制视频节奏。`--recorded-narration` 会拒绝 `on-click` 对象动画,因为 PPT Master 不生成对象级点击计时。++**PowerPoint 手动回退(Windows / Mac,Office 2016+)**:1. 打开 `exports/` 里那份带旁白的 `.pptx`。2. **文件 → 导出 → 创建视频**。-3. 选清晰度(4K / 全高清 / 高清 / 标准)以及"使用录制的计时和旁白"——PPT Master 已经替你录好了。+3. 选清晰度以及"使用录制的计时和旁白"。4. **创建视频** → 保存为 `.mp4`(Windows 也支持 `.wmv`)。5. 若要让外挂字幕最贴合最终视频,再执行上面的 `narration_sync.py subtitles --video ...`,把生成的同名 SRT 与视频放在一起。+PowerPoint for Mac 可以手动导出 MP4/MOV,但微软明确说明其影片导出不会播放动画效果。需要动画保真时,应使用 Windows 自动导出路径。+**Keynote(Mac)**:打开 deck → **文件 → 导出到 → 影片…** ——Keynote 同样会读取嵌入的音频和分页计时,输出 `.m4v` / `.mov`。**经验值**:- **不需要麦克风、不需要录制环节**——音频是合成的,重跑可重现。-- **动画保留**:PPT Master 的页间转场和无点击页内元素入场动画是真正的 OOXML 动画,导出视频后正常播放。详见 [转场与动画](./animations.md)。+- **Windows 动画保真**:PowerPoint 的 Windows 视频导出会保留 PPT Master 的原生页间转场和无点击对象动画;Mac 影片导出存在上面的限制。详见 [转场与动画](./animations.md)。- **单页改音频**:改对应 `notes/<page>.md`,再跑一遍 `notes_to_audio.py` + 嵌入步骤,再重新导出视频——单页迭代通常不到一分钟。- **文件大小**:20 页全高清 deck 通常是 30–80 MB,取决于图片量。需要小文件分享时降到高清就行。diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex 61acb093..7a03a6f0 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -517,6 +517,7 @@ SVG 与 DrawingML 的表达模型并不等价,因此主编译路径不把“| `validation/<output_stem>.report.json` | 已发布 PPTX 的 postflight 与资源审计 | 记录实际 ZIP/package part 数量;重新检查 ZIP 与正式页数;把内部关系、结构化包、转场和动画如实标为构建期强制校验;只有 SHA-256 指纹与导出输入一致时才接受质量报告关联,同时暴露未解析变量、外部图片和纯通用字体栈 || `exports/<name>_<ts>_native_charts_tables.pptx`(需 `--native-charts-and-tables` 显式开启) | 让带 `data-pptx-replace-with` 标记的 SVG 派生形状图表/表格替换为 PowerPoint 原生 Chart/Table 对象 | 带数据源和图表/表格专属控制的对象;默认 DrawingML shape 本身仍可独立编辑 || `exports/<name>_<ts>_narrated.pptx`(经 `--recorded-narration` 或 `--narration-audio-dir` 生成) | 嵌入匹配到的旁白音频;完整录制模式可直接服务自动放映与 PowerPoint 视频导出 | `--recorded-narration` 要求每页匹配音频,并写入“时长 + padding”的自动推进;低层 `--narration-audio-dir` 允许部分或零覆盖,只有另加 `--use-narration-timings` 才写自动推进 |+| `exports/<narrated_stem>.mp4`(可选,经 `powerpoint_video.py`) | Windows PowerPoint 2016+ 下保留动画与旁白的视频交付物 | 委托 PowerPoint 原生编码器并等待完成;它是 PPTX 后处理集成,不是第二套 deck 渲染器 || `backup/<ts>/svg_output/`(仅默认输出路径;目录创建后复制为 best-effort) | 在不重跑 LLM 的前提下从冻结 SVG 源重建 pptx | 转换成功后先创建备份目录再尝试复制;显式 `-o` 不创建,复制失败不阻断导出,非 quiet 模式打印 warning,postflight 的 `backup_path` 为空,但目录创建失败仍会中断 |校验 JSON 是冷审计产物,不是常规模型输入。导出器在程序内部读取 SVG 质量报告,并在默认非 quiet 流程打印紧凑的 `[POSTFLIGHT]` 回执,包含状态、质量门结果、Slide 数量、warning 类别计数和产物路径。成功流程只消费该回执,不加载两份完整 JSON;只有失败排查或用户明确要求审计时才定向提取报告字段。@@ -614,6 +615,8 @@ ChartEx 导入被有意限制为 7 个已验证数据模型:`treemap`、`sunbu**为什么录制旁白拒绝 on-click 对象动画。** PowerPoint 可以在真实排练时记录点击计时,但 PPT Master 不合成对象级点击事件。录制旁白路径只写页面级音频和页面自动推进计时,所以单击触发的对象入场会让导出依赖额外的 PowerPoint 人工排练。使用 `--recorded-narration` 导出的 deck 必须采用无点击入场(`after-previous` 或 `with-previous`)。+**为什么原生视频导出保持独立命令。** 音频合成和 PPTX 打包属于跨平台项目操作;PowerPoint 视频编码则是 Windows 桌面集成。`powerpoint_video.py` 接收最终带旁白 PPTX,调用 `CreateVideo` 并轮询 `CreateVideoStatus`,对调用方呈现同步结果,同时避免把 Office 自动化耦合进 TTS backend。+---## 维护边界:不要合并什么diff --git a/skills/ppt-master/scripts/powerpoint_video.py b/skills/ppt-master/scripts/powerpoint_video.pynew file mode 100644index 00000000..f5991dde--- /dev/null+++ b/skills/ppt-master/scripts/powerpoint_video.py@@ -0,0 +1,407 @@+#!/usr/bin/env python3+"""+PPT Master - PowerPoint Video Export++Export a narrated PPTX through the installed Windows PowerPoint application and+wait until its native video encoder finishes.++See workflows/stages/generate-audio.md for the narration handoff.++Usage:+ python3 scripts/powerpoint_video.py <pptx> [-o <video>]+ python3 scripts/powerpoint_video.py --check++Examples:+ python3 scripts/powerpoint_video.py projects/demo/exports/demo_narrated.pptx+ python3 scripts/powerpoint_video.py deck.pptx -o deck.mp4 --resolution 1080++Dependencies:+ Windows PowerPoint with the CreateVideo automation API+"""++from __future__ import annotations++import argparse+import base64+import os+import shutil+import subprocess+import sys+from pathlib import Path++from console_encoding import configure_utf8_stdio++configure_utf8_stdio()+++_CHECK_SCRIPT = r"""+$ErrorActionPreference = "Stop"+$ProgressPreference = "SilentlyContinue"+$powerPoint = $null+$ownsApplication = $false++try {+ try {+ $powerPoint = [Runtime.InteropServices.Marshal]::GetActiveObject(+ "PowerPoint.Application"+ )+ }+ catch {+ $powerPoint = New-Object -ComObject PowerPoint.Application+ $ownsApplication = $true+ }++ $version = [version]$powerPoint.Version+ if ($version.Major -lt 16) {+ throw "PowerPoint $version is older than the supported Office 2016 baseline."+ }+ [Console]::Out.WriteLine(+ "PowerPoint video export available (version {0})." -f $version+ )+}+catch {+ [Console]::Error.WriteLine(+ "PowerPoint video export is unavailable: {0}" -f $_.Exception.Message+ )+ exit 1+}+finally {+ if ($null -ne $powerPoint) {+ if ($ownsApplication) {+ try { $powerPoint.Quit() } catch {}+ }+ try {+ [void][Runtime.InteropServices.Marshal]::FinalReleaseComObject(+ $powerPoint+ )+ }+ catch {}+ }+ [GC]::Collect()+ [GC]::WaitForPendingFinalizers()+}+"""+++_EXPORT_SCRIPT = r"""+$ErrorActionPreference = "Stop"+$ProgressPreference = "SilentlyContinue"+$inputPath = [Environment]::GetEnvironmentVariable("PPT_MASTER_VIDEO_INPUT")+$outputPath = [Environment]::GetEnvironmentVariable("PPT_MASTER_VIDEO_OUTPUT")+$resolution = [int][Environment]::GetEnvironmentVariable(+ "PPT_MASTER_VIDEO_RESOLUTION"+)+$framesPerSecond = [int][Environment]::GetEnvironmentVariable(+ "PPT_MASTER_VIDEO_FPS"+)+$quality = [int][Environment]::GetEnvironmentVariable("PPT_MASTER_VIDEO_QUALITY")+$defaultSlideDuration = [int][Environment]::GetEnvironmentVariable(+ "PPT_MASTER_VIDEO_DEFAULT_SLIDE_DURATION"+)+$timeoutSeconds = [int][Environment]::GetEnvironmentVariable(+ "PPT_MASTER_VIDEO_TIMEOUT"+)++$powerPoint = $null+$presentation = $null+$ownsApplication = $false++try {+ try {+ $powerPoint = [Runtime.InteropServices.Marshal]::GetActiveObject(+ "PowerPoint.Application"+ )+ }+ catch {+ $powerPoint = New-Object -ComObject PowerPoint.Application+ $ownsApplication = $true+ }++ $version = [version]$powerPoint.Version+ if ($version.Major -lt 16) {+ throw "PowerPoint $version is older than the supported Office 2016 baseline."+ }++ # ReadOnly=-1, Untitled=0, WithWindow=0.+ $presentation = $powerPoint.Presentations.Open($inputPath, -1, 0, 0)+ $startMessage = "PowerPoint video export started: {0}p, {1} fps." -f @(+ $resolution,+ $framesPerSecond+ )+ [Console]::Error.WriteLine($startMessage)+ $presentation.CreateVideo(+ $outputPath,+ $true,+ $defaultSlideDuration,+ $resolution,+ $framesPerSecond,+ $quality+ )++ $deadline = [DateTime]::UtcNow.AddSeconds($timeoutSeconds)+ $nextProgress = [DateTime]::UtcNow.AddSeconds(15)+ while ($true) {+ $status = [int]$presentation.CreateVideoStatus+ if ($status -eq 3) {+ break+ }+ if ($status -eq 4) {+ throw "PowerPoint reported that video creation failed."+ }+ if ([DateTime]::UtcNow -ge $deadline) {+ throw "PowerPoint video creation exceeded the ${timeoutSeconds}-second timeout."+ }+ if ([DateTime]::UtcNow -ge $nextProgress) {+ [Console]::Error.WriteLine("PowerPoint video export is still running.")+ $nextProgress = [DateTime]::UtcNow.AddSeconds(15)+ }+ Start-Sleep -Milliseconds 1000+ }++ if (-not (Test-Path -LiteralPath $outputPath)) {+ throw "PowerPoint reported success but did not create the output file."+ }+ $outputFile = Get-Item -LiteralPath $outputPath+ if ($outputFile.Length -le 0) {+ throw "PowerPoint created an empty video file."+ }++ [Console]::Out.WriteLine($outputFile.FullName)+}+catch {+ $errorMessage = (+ "PowerPoint video export failed: {0} " ++ "Close any PowerPoint dialog and retry."+ ) -f $_.Exception.Message+ [Console]::Error.WriteLine($errorMessage)+ exit 1+}+finally {+ if ($null -ne $presentation) {+ try { $presentation.Close() } catch {}+ try {+ [void][Runtime.InteropServices.Marshal]::FinalReleaseComObject(+ $presentation+ )+ }+ catch {}+ }+ if ($null -ne $powerPoint) {+ if ($ownsApplication) {+ try { $powerPoint.Quit() } catch {}+ }+ try {+ [void][Runtime.InteropServices.Marshal]::FinalReleaseComObject(+ $powerPoint+ )+ }+ catch {}+ }+ [GC]::Collect()+ [GC]::WaitForPendingFinalizers()+}+"""+++def build_parser() -> argparse.ArgumentParser:+ parser = argparse.ArgumentParser(+ description=(+ "Export a PPTX with Windows PowerPoint's native video encoder and "+ "wait for completion."+ ),+ formatter_class=argparse.RawDescriptionHelpFormatter,+ )+ parser.add_argument("pptx", nargs="?", help="Input PPTX file.")+ parser.add_argument(+ "-o",+ "--output",+ help="Output .mp4 or .wmv path. Default: beside the PPTX as .mp4.",+ )+ parser.add_argument(+ "--resolution",+ type=int,+ default=1080,+ help="Vertical video resolution in pixels (default: 1080).",+ )+ parser.add_argument(+ "--fps",+ type=int,+ default=30,+ help="Frames per second, from 1 to 60 (default: 30).",+ )+ parser.add_argument(+ "--quality",+ type=int,+ default=85,+ help="PowerPoint encoder quality, from 1 to 100 (default: 85).",+ )+ parser.add_argument(+ "--default-slide-duration",+ type=int,+ default=5,+ help="Fallback seconds for slides without recorded timings (default: 5).",+ )+ parser.add_argument(+ "--timeout",+ type=int,+ default=7200,+ help="Maximum seconds to wait for PowerPoint (default: 7200).",+ )+ parser.add_argument(+ "--force",+ action="store_true",+ help="Replace an existing output video.",+ )+ parser.add_argument(+ "--check",+ action="store_true",+ help="Check whether compatible Windows PowerPoint automation is available.",+ )+ return parser+++def _find_powershell() -> str | None:+ """Return the local Windows PowerShell executable."""+ return shutil.which("powershell.exe") or shutil.which("powershell")+++def _run_powershell(script: str, *, env: dict[str, str], timeout: int) -> int:+ """Run an encoded PowerShell automation script."""+ executable = _find_powershell()+ if executable is None:+ print(+ "PowerPoint video export requires Windows PowerShell. "+ "Install or restore powershell.exe, then retry.",+ file=sys.stderr,+ )+ return 1++ encoded = base64.b64encode(script.encode("utf-16-le")).decode("ascii")+ try:+ completed = subprocess.run(+ [+ executable,+ "-NoLogo",+ "-NoProfile",+ "-NonInteractive",+ "-STA",+ "-OutputFormat",+ "Text",+ "-EncodedCommand",+ encoded,+ ],+ check=False,+ env=env,+ timeout=timeout,+ )+ except subprocess.TimeoutExpired:+ print(+ "PowerPoint automation exceeded the command timeout. "+ "Close any PowerPoint dialog and retry.",+ file=sys.stderr,+ )+ return 1+ return completed.returncode+++def _validate_positive(+ parser: argparse.ArgumentParser,+ *,+ name: str,+ value: int,+ maximum: int | None = None,+) -> None:+ if value <= 0 or (maximum is not None and value > maximum):+ suffix = f" and no greater than {maximum}" if maximum is not None else ""+ parser.error(f"{name} must be greater than 0{suffix}")+++def main(argv: list[str] | None = None) -> int:+ parser = build_parser()+ args = parser.parse_args(argv)++ if sys.platform != "win32":+ print(+ "PowerPoint video export currently requires Windows PowerPoint. "+ "Keep the narrated PPTX and export it manually on another platform.",+ file=sys.stderr,+ )+ return 1++ if args.check:+ return _run_powershell(+ _CHECK_SCRIPT,+ env=os.environ.copy(),+ timeout=60,+ )++ if not args.pptx:+ parser.error("pptx is required unless --check is used")++ _validate_positive(parser, name="resolution", value=args.resolution)+ _validate_positive(parser, name="fps", value=args.fps, maximum=60)+ _validate_positive(parser, name="quality", value=args.quality, maximum=100)+ _validate_positive(+ parser,+ name="default-slide-duration",+ value=args.default_slide_duration,+ )+ _validate_positive(parser, name="timeout", value=args.timeout)++ input_path = Path(args.pptx).expanduser().resolve()+ if not input_path.is_file():+ print(f"Input PPTX does not exist: {input_path}", file=sys.stderr)+ return 1+ if input_path.suffix.lower() != ".pptx":+ print(f"Input must be a .pptx file: {input_path}", file=sys.stderr)+ return 1++ output_path = (+ Path(args.output).expanduser().resolve()+ if args.output+ else input_path.with_suffix(".mp4")+ )+ if output_path.suffix.lower() not in {".mp4", ".wmv"}:+ print(+ f"Output must use the .mp4 or .wmv extension: {output_path}",+ file=sys.stderr,+ )+ return 1+ if output_path == input_path:+ print("Input PPTX and output video paths must differ.", file=sys.stderr)+ return 1+ if output_path.exists() and not args.force:+ print(+ f"Output already exists: {output_path}. "+ "Use --force to replace it.",+ file=sys.stderr,+ )+ return 1++ output_path.parent.mkdir(parents=True, exist_ok=True)+ if output_path.exists():+ output_path.unlink()++ env = os.environ.copy()+ env.update(+ {+ "PPT_MASTER_VIDEO_INPUT": str(input_path),+ "PPT_MASTER_VIDEO_OUTPUT": str(output_path),+ "PPT_MASTER_VIDEO_RESOLUTION": str(args.resolution),+ "PPT_MASTER_VIDEO_FPS": str(args.fps),+ "PPT_MASTER_VIDEO_QUALITY": str(args.quality),+ "PPT_MASTER_VIDEO_DEFAULT_SLIDE_DURATION": str(+ args.default_slide_duration+ ),+ "PPT_MASTER_VIDEO_TIMEOUT": str(args.timeout),+ }+ )+ return _run_powershell(+ _EXPORT_SCRIPT,+ env=env,+ timeout=args.timeout + 60,+ )+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/skills/ppt-master/workflows/stages/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.mdindex e7825383..c61f6baf 100644--- a/skills/ppt-master/workflows/stages/generate-audio.md+++ b/skills/ppt-master/workflows/stages/generate-audio.md@@ -1,5 +1,5 @@----description: Shared post-processing stage for per-slide narration audio and optional embedding.+description: Shared post-processing stage for narration audio, PPTX embedding, and optional native video export.---# Generate Audio Stage@@ -15,7 +15,13 @@ This stage is **context-independent**: it reads `notes/*.md` and queries the sel- The stage is page-level only: with edge, one notes file becomes `audio/<stem>.mp3` plus `notes/subtitles/<stem>.srt`; with a cloud provider, it becomes one audio file. Do not use a single long audio track or attempt automatic long-audio splitting.- PPT narration assets must be PowerPoint-reliable audio: `m4a` (AAC), `mp3`, or `wav`. The built-in TTS path defaults to `mp3`; provider formats such as `pcm`, `opus`, or `flac` must be transcoded before embedding.- PowerPoint recorded narration export requires `ffprobe` so slide timings can be written from actual audio duration.-- Optional post-export video calibration requires `ffmpeg` plus `numpy`; it runs only when the caller supplies the finished PowerPoint video.+- Optional automatic video export requires Windows PowerPoint 2016+ and runs+ through `powerpoint_video.py`; the command waits for PowerPoint's native+ encoder to finish before returning.+- macOS PowerPoint may export MP4/MOV manually, but it has no equivalent+ `CreateVideo` automation contract and its movie export does not preserve+ animation effects. Do not replace the missing API with UI scripting.+- Optional post-export video calibration requires `ffmpeg` plus `numpy`; it runs only after a finished PowerPoint video is supplied or created.- High-quality cloud mode: provider API key is set before use:- ElevenLabs: `ELEVENLABS_API_KEY`- MiniMax: `MINIMAX_API_KEY`@@ -81,9 +87,9 @@ For each candidate, write a **one-line Chinese description** covering: 性别 ·## Step 3: One-shot user interaction (mandatory)-Send a single message to the user that asks all three questions at once and provides a recommended value for each. Do NOT split into multiple rounds.+Send a single message to the user that resolves all five configuration decisions at once and provides a recommended value for each. Before offering automatic video export, run `python3 skills/ppt-master/scripts/powerpoint_video.py --check`; do not present an unavailable local capability as executable. Do NOT split into multiple rounds.-**Cloned-voice fast path**: if the user mentioned a cloned voice / 克隆音色 / 复刻音色 / "my own voice" along with a `voice_id`, skip the voice-recommendation list — set the provider to whichever the user named (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`), pin the `voice_id` they gave you, and only confirm rate + embed-or-not.+**Cloned-voice fast path**: if the user mentioned a cloned voice / 克隆音色 / 复刻音色 / "my own voice" along with a `voice_id`, skip the voice-recommendation list — set the provider to whichever the user named (`elevenlabs` / `minimax` / `qwen` / `cosyvoice`), pin the `voice_id` they gave you, and only confirm rate + embed + video.**Message template** (Chinese; translate to user's chat language if different). “Embed” means caller-specific integration: SVG re-export for Generate PPTX, or native OOXML application for Enhance Native PPTX.@@ -103,6 +109,8 @@ Send a single message to the user that asks all three questions at once and prov>> **生成完是否重新导出嵌入音频的 PPTX**:⭐ 推荐 **是**(一次到位,自动按音频时长设页面停留)。>+> **带音频 PPTX 完成后是否继续导出视频**:⭐ 推荐 **是**(仅在本机 Windows PowerPoint 2016+ 可用时;将等待原生视频导出完成)。+>> 直接回"好"用全部推荐值,或告诉我想改的部分(如"音色 2,语速 -5%"或"用 MiniMax 的 voice_id xxx")。**Recommended-value rules**:@@ -110,6 +118,7 @@ Send a single message to the user that asks all three questions at once and prov- 音色:从 Step 2 候选里挑最贴合 deck 调性的那一个。- 语速:edge 默认 `+0%`;notes 字数密集(页均 >4 句长句)建议 `-5%`;notes 简短紧凑建议 `+5%`;超出此范围需说明理由。Cloud providers 默认用 provider defaults,除非用户明确要调速或改风格。- 嵌入:默认推荐"是";除非用户已有定制 PPTX 不希望覆盖。+- 视频:`powerpoint_video.py --check` 成功时默认推荐"是";不可用时说明只能交付带音频 PPTX,不自动改用第三方渲染器。---@@ -168,10 +177,13 @@ python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \python3 skills/ppt-master/scripts/narration_sync.py subtitles <project_path> \--pptx <final_narrated_pptx> --force-# 2D. After PowerPoint exports the video, align the frozen narration text-# against the finished video's actual audio track+# 2D. Optional: export through installed Windows PowerPoint and wait for completion+python3 skills/ppt-master/scripts/powerpoint_video.py \+ <final_narrated_pptx> -o <final_video.mp4>++# 2E. Align the frozen narration text against the finished video's audio trackpython3 skills/ppt-master/scripts/video_subtitles.py <project_path> \- --video <powerpoint_exported_video> --language <language> --force+ --video <final_video.mp4> --language <language> --force```**Default — bounded Edge concurrency (may override)**: Generate up to three@@ -219,16 +231,22 @@ python3 skills/ppt-master/scripts/narration_sync.py fingerprint <project_path>`narration_sync.py subtitles` may still write `<project_path>/notes/subtitles/total.srt` as a PPTX-timeline diagnostic. It is not the delivery subtitle for a finished video.-After PowerPoint exports the video, `video_subtitles.py` takes the exact narration text frozen in the page SRT set and force-aligns it against the finished video's actual audio track with `stable-ts`. Long delivery cues may be split for display at this final stage. This writes a same-stem external SRT without changing the MP4, notes, page SRT, or animation files.+When video export was selected, `powerpoint_video.py` opens the final narrated PPTX through local Windows PowerPoint, requests its native video encoder with recorded timings and narrations enabled, and polls `CreateVideoStatus` until the MP4 succeeds, fails, or times out. The interface is synchronous to its caller even though PowerPoint performs encoding asynchronously. It preserves PowerPoint's own animation and media behavior rather than re-rendering the deck.++If native video export fails, keep the narrated PPTX as a successful upstream+artifact and report the video failure separately. Do not regenerate audio or+the PPTX unless their own validation failed.++After the MP4 exists, `video_subtitles.py` takes the exact narration text frozen in the page SRT set and force-aligns it against the finished video's actual audio track with `stable-ts`. Long delivery cues may be split for display at this final stage. This writes a same-stem external SRT without changing the MP4, notes, page SRT, or animation files.-This stage keeps subtitles as external SRT files. It does not embed subtitles into PPTX or export MP4 directly.+This stage keeps subtitles as external SRT files. It does not burn subtitles into the video. Automatic MP4 export is an optional Windows PowerPoint integration, not an independent renderer; when PowerPoint automation is unavailable, stop after the narrated PPTX instead of claiming a downgraded video.**Caller integration**:| Caller | After audio generation ||---|---|-| Generate PPTX | With Edge SRT and an existing `animations.json`, derive `narration_animations.json`, export with `--recorded-narration audio` (derived animation by default; canonical or no-animation modes remain explicit), and generate the delivery SRT only after PowerPoint exports the video. |-| Enhance Native PPTX | Return to [`native-enhance-pptx`](../native-enhance-pptx.md) Step 9; its `apply` command owns audio relationships, timings, transitions, and the enhanced export |+| Generate PPTX | With Edge SRT and an existing `animations.json`, derive `narration_animations.json`, export with `--recorded-narration audio` (derived animation by default; canonical or no-animation modes remain explicit), optionally continue through `powerpoint_video.py`, then generate the delivery SRT from the finished video. |+| Enhance Native PPTX | Return to [`native-enhance-pptx`](../native-enhance-pptx.md) Step 9; its `apply` command owns audio relationships, timings, transitions, and the enhanced export. If video was selected, pass that final PPTX to `powerpoint_video.py`. |For Generate PPTX, `--recorded-narration audio` prepares PowerPoint's recorded timings and narrations: every slide must have a matching supported audio file, every duration must be readable by `ffprobe`, and object animations must not use `--animation-trigger on-click`. Use `after-previous` or `with-previous` for narrated/video export. Narration changes the slide-advance layer only: the resolved page-transition effect remains unchanged, `-t none` remains visually transition-free, and narration advance disables click while using audio duration plus padding. The re-export is saved as `exports/<project_name>_<timestamp>_narrated.pptx`, telling it apart from silent exports.@@ -244,7 +262,8 @@ Output one summary block listing:- For edge, number of matching page-local SRT files and their location (`<project_path>/notes/subtitles/*`).- For narrated object animation, whether current SVG semantics were reused or which missing/stale pages were reread, plus semantic mapping coverage and fallback count.- For Generate PPTX with Edge SRT, derived narration animation group count and `narration_animations.json` path.-- When a finished video was supplied, the final aligned sidecar SRT path.+- When video export was selected, the final MP4 path and native PowerPoint export status.+- When a finished video exists, the final aligned sidecar SRT path.- The provider, voice, and rate/settings actually used.- The caller-owned integration result: narrated SVG export path, enhanced native PPTX path, or “audio only”.- For Generate PPTX when embedding was skipped, one-line hint: `python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --recorded-narration audio`.