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(pptx): add native enhancement workflow
hugohe3c9d1556a4d64
diff --git a/AGENTS.md b/AGENTS.mdindex 22c71322..3bbd08c9 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -24,6 +24,8 @@ PPT Master is an AI-driven presentation generation system. Multi-role collaborat>> Recorded narration / video export: run the standalone [`generate-audio`](skills/ppt-master/workflows/generate-audio.md) workflow after post-processing.>+> Existing PPTX native enhancement without regeneration: when the user provides a finished `.pptx` and asks to optimize it while keeping existing content / layout / format stable — for example adding speaker notes, narration audio, automatic slide advance, or page transitions — run the standalone [`native-enhance-pptx`](skills/ppt-master/workflows/native-enhance-pptx.md) workflow. This route archives the source PPTX into the project (`projects/` sources are moved; external sources are copied), then patches it directly at the OOXML zip layer and must not enter the SVG generation pipeline.+>> Object-level animation tuning: when the user asks to change animation order, effect, timing, or a specific object's reveal behavior, run the standalone [`customize-animations`](skills/ppt-master/workflows/customize-animations.md) workflow. Default export applies page transitions but no per-element entrance animation (element builds are opt-in); create `animations.json` or pass `-a auto` only when the user asks for element animation or object-level customization.>> Live preview: any time the user mentions "live preview", "preview", "看效果", or wants to click/select a slide element, run [`live-preview`](skills/ppt-master/workflows/live-preview.md). Step 6 auto-starts it during generation; the workflow covers post-export re-entry and applying submitted annotations.@@ -85,6 +87,11 @@ python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>python3 skills/ppt-master/scripts/animation_config.py scaffold <project_path> # optional, only for custom object-level animationpython3 skills/ppt-master/scripts/animation_config.py validate <project_path> # optional, before re-export+# Existing PPTX native enhancement workflow — direct OOXML patch, no SVG conversion+python3 skills/ppt-master/scripts/native_enhance_pptx.py init <PPTX_file> --name <project_slug>+python3 skills/ppt-master/scripts/native_enhance_pptx.py validate <project_path>+python3 skills/ppt-master/scripts/native_enhance_pptx.py apply <project_path>+# Post-processing pipeline: run sequentially, one command at a timepython3 skills/ppt-master/scripts/total_md_split.py <project_path>python3 skills/ppt-master/scripts/finalize_svg.py <project_path>diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex db0b35b3..d47de051 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -60,6 +60,8 @@ description: >| `${SKILL_DIR}/scripts/total_md_split.py` | Speaker notes splitting || `${SKILL_DIR}/scripts/finalize_svg.py` | SVG post-processing (unified entry) || `${SKILL_DIR}/scripts/svg_to_pptx.py` | Export to PPTX |+| `${SKILL_DIR}/scripts/native_enhance_pptx.py` | Existing PPTX enhancement project init / validation / direct OOXML patch export |+| `${SKILL_DIR}/scripts/native_narration_pptx.py` | Backward-compatible entrypoint for existing PPTX notes / narration enhancement || `${SKILL_DIR}/scripts/update_spec.py` | Propagate a `spec_lock.md` color / font_family change across all generated SVGs |For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.@@ -87,6 +89,8 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.| `resume-execute` | `workflows/resume-execute.md` | Phase B entry — resume execution in a fresh chat after Phase A (Step 1–5) completed in another session (split mode) || `verify-charts` | `workflows/verify-charts.md` | Chart coordinate calibration — run after SVG generation if the deck contains data charts || `customize-animations` | `workflows/customize-animations.md` | Object-level PPTX animation customization — run only when the user explicitly asks to tune animation order/effects/timing |+| `native-enhance-pptx` | `workflows/native-enhance-pptx.md` | Existing PPTX native enhancement — optimize a finished deck by appending notes / audio / auto-advance / page transitions without changing existing content or layout |+| `native-narration-pptx` | `workflows/native-narration-pptx.md` | Compatibility reference for the notes / narration subset of `native-enhance-pptx` || `live-preview` | `workflows/live-preview.md` | Browser-based live preview — auto-started during generation and re-enterable any time the user mentions "live preview", "preview", "看效果", or wants to click/select a slide element || `visual-review` | `workflows/visual-review.md` | Per-page rubric-based visual self-check — run only when the user explicitly asks for a visual re-pass on the generated SVGs (between Executor and post-processing). Opt-in only; never invoked by the main pipeline. |@@ -100,6 +104,7 @@ When the user provides an existing `.pptx`, route by the role of the source deck| Treat the deck as source material; rethink the story, merge / split / drop / reorder pages, or change page count | Main pipeline | `ppt_to_md` + PPTX intake provide content facts and candidates; Strategist may re-architect freely || Reuse the deck's native design with new material | `template-fill` | Clone selected source slides and replace text / table / chart data directly in OOXML; no SVG generation || Harvest the deck as a reusable future template | `create-template` | Build a template package, not a one-off generated deck |+| Keep the finished deck visually stable and append native optimizations such as notes / narration audio / automatic playback | `native-enhance-pptx` | Archive the source PPTX into the project (`projects/` sources move; external sources copy) and patch enhancement metadata/media directly in OOXML; no SVG generation |**Deciding axis (beautify vs main pipeline) — one question, one discriminator**: is the source's page split a finished artifact to preserve, or a draft structure to overturn? The concrete discriminator is **page count / order**: if it changes at all — any split, merge, drop, or reorder — it is the **main pipeline**, never beautify. Beautify is **strictly 1:1**: same page count, same order, text verbatim, only layout / hierarchy / whitespace redone. Edge case made explicit: "keep all the content but split a crowded page so it reads better" still changes page count, so it is the **main pipeline** (re-pagination is re-architecture), not beautify.diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex 604910e2..7bf9d498 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -41,7 +41,7 @@ python3 scripts/update_repo.py| Area | Primary scripts | Documentation ||------|-----------------|---------------|| Conversion | `source_to_md/pdf_to_md.py`, `source_to_md/doc_to_md.py`, `source_to_md/excel_to_md.py`, `source_to_md/ppt_to_md.py`, `source_to_md/web_to_md.py`, `pptx_intake.py` | [docs/conversion.md](./docs/conversion.md) |-| Project management | `project_manager.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py`, `template_fill_pptx.py` | [docs/project.md](./docs/project.md) |+| Project management | `project_manager.py`, `batch_validate.py`, `generate_examples_index.py`, `error_helper.py`, `pptx_template_import.py`, `template_fill_pptx.py`, `native_enhance_pptx.py` | [docs/project.md](./docs/project.md) || SVG pipeline | `finalize_svg.py`, `svg_to_pptx.py`, `total_md_split.py`, `svg_quality_checker.py`, `extract_svg_assets.py`, `animation_config.py`, `notes_to_audio.py` | [docs/svg-pipeline.md](./docs/svg-pipeline.md) || Spec maintenance | `update_spec.py` | [docs/update_spec.md](./docs/update_spec.md) || Image tools | `image_gen.py`, `latex_render.py`, `analyze_images.py`, `gemini_watermark_remover.py` | [docs/image.md](./docs/image.md) |@@ -88,6 +88,15 @@ python3 scripts/template_fill_pptx.py apply <project_path>/sources/<source.pptx>`apply` automatically writes `filled_YYYYMMDD_HHMMSS.pptx` unless the output stem already ends with a timestamp. It applies a `fade` page transition by default; `--transition <effect>` (fade/push/wipe/split/strips/cover/random, `--transition-duration` in seconds) changes it, `--transition none` removes it, `--transition keep` preserves the source transitions, and a per-slide `transition` field in the plan overrides whatever the CLI selects.+Native existing-PPTX enhancement (direct PPTX, no SVG conversion):++```bash+python3 scripts/native_enhance_pptx.py init <source.pptx> --name <project_slug>+python3 scripts/native_enhance_pptx.py plan <project_path>+python3 scripts/native_enhance_pptx.py validate <project_path>+python3 scripts/native_enhance_pptx.py apply <project_path>+```+Post-processing and export:```bashdiff --git a/skills/ppt-master/scripts/native_enhance_pptx.py b/skills/ppt-master/scripts/native_enhance_pptx.pynew file mode 100644index 00000000..9f9bfc75--- /dev/null+++ b/skills/ppt-master/scripts/native_enhance_pptx.py@@ -0,0 +1,37 @@+#!/usr/bin/env python3+"""+PPT Master - Native Enhance PPTX Entrypoint++Public CLI wrapper for native enhancement of existing PPTX decks. V1 delegates+to the narration/timings implementation while keeping the stable command name+aligned with the native-enhance workflow.++Usage:+ python3 scripts/native_enhance_pptx.py init <source.pptx> [--name project_name]+ python3 scripts/native_enhance_pptx.py plan <project_path>+ python3 scripts/native_enhance_pptx.py validate <project_path>+ python3 scripts/native_enhance_pptx.py apply <project_path>++Examples:+ python3 scripts/native_enhance_pptx.py init projects/source.pptx --name fire_station+ python3 scripts/native_enhance_pptx.py plan projects/fire_station_native_enhance_20260626+ python3 scripts/native_enhance_pptx.py apply projects/fire_station_native_enhance_20260626++Dependencies:+ Same as native_narration_pptx.py.+"""++from __future__ import annotations++import sys+from pathlib import Path++_SCRIPTS_DIR = Path(__file__).resolve().parent+if str(_SCRIPTS_DIR) not in sys.path:+ sys.path.insert(0, str(_SCRIPTS_DIR))++from native_narration_pptx import main # noqa: E402+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/native_narration_pptx.py b/skills/ppt-master/scripts/native_narration_pptx.pynew file mode 100644index 00000000..a6a22a5d--- /dev/null+++ b/skills/ppt-master/scripts/native_narration_pptx.py@@ -0,0 +1,862 @@+#!/usr/bin/env python3+"""+PPT Master - Native Existing PPTX Enhancer++Create and apply a lightweight project for enhancing an existing PPTX without+entering the SVG generation pipeline or modifying the original file.++V1 enhancement modules: speaker notes, narration audio, slide auto-advance+timings, and optional page transitions.++Usage:+ python3 scripts/native_enhance_pptx.py init <source.pptx> [--name project_name]+ python3 scripts/native_enhance_pptx.py apply <project_path> [--output output.pptx]+ python3 scripts/native_enhance_pptx.py validate <project_path>++Examples:+ python3 scripts/native_enhance_pptx.py init projects/source.pptx --name fire_station+ python3 scripts/native_enhance_pptx.py apply projects/fire_station_native_enhance_20260626+ python3 scripts/native_enhance_pptx.py validate projects/fire_station_native_enhance_20260626++Dependencies:+ ffprobe for audio-duration-based auto-advance timings.+"""++from __future__ import annotations++import argparse+import json+import re+import shutil+import subprocess+import sys+import tempfile+import zipfile+from dataclasses import dataclass+from datetime import datetime+from pathlib import Path+from xml.etree import ElementTree as ET++_SCRIPTS_DIR = Path(__file__).resolve().parent+if str(_SCRIPTS_DIR) not in sys.path:+ sys.path.insert(0, str(_SCRIPTS_DIR))++from pptx_animations import TRANSITIONS, create_transition_xml # noqa: E402+from svg_to_pptx.pptx_builder import ( # noqa: E402+ _add_default_content_type,+ _append_relationship,+ _ensure_notes_master,+)+from svg_to_pptx.pptx_narration import ( # noqa: E402+ AUDIO_CONTENT_TYPES,+ AUDIO_REL_TYPE,+ IMAGE_REL_TYPE,+ MEDIA_REL_TYPE,+ NARRATION_EXTENSIONS,+ TRANSPARENT_PNG_BYTES,+ apply_recorded_timing,+ inject_narration,+ next_shape_id,+ probe_audio_duration,+)+from svg_to_pptx.pptx_notes import ( # noqa: E402+ create_notes_slide_rels_xml,+ create_notes_slide_xml,+ markdown_to_plain_text,+)+++PROJECT_SCHEMA = "native_pptx_enhancement_project.v1"+LEGACY_PROJECT_SCHEMAS = {"native_narration_pptx_project.v1"}+NOTES_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/notesSlide"+PACKAGE_REL_NS = "http://schemas.openxmlformats.org/package/2006/relationships"+PRESENTATION_NS = "http://schemas.openxmlformats.org/presentationml/2006/main"+REL_NS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships"+CONTENT_TYPE_NOTES_SLIDE = (+ "application/vnd.openxmlformats-officedocument.presentationml.notesSlide+xml"+)+CONTENT_TYPE_NOTES_MASTER = (+ "application/vnd.openxmlformats-officedocument.presentationml.notesMaster+xml"+)+CONTENT_TYPE_THEME = "application/vnd.openxmlformats-officedocument.theme+xml"+++@dataclass(frozen=True)+class SlidePart:+ index: int+ part_name: str+ slide_number: int+++def _sanitize_slug(value: str) -> str:+ slug = re.sub(r"[^0-9A-Za-z_-]+", "_", value).strip("_")+ return slug or "native_enhance"+++def _read_json(path: Path) -> dict:+ return json.loads(path.read_text(encoding="utf-8"))+++def _write_json(path: Path, data: dict) -> None:+ path.write_text(+ json.dumps(data, ensure_ascii=False, indent=2) + "\n",+ encoding="utf-8",+ )+++def _is_relative_to(path: Path, parent: Path) -> bool:+ try:+ path.resolve().relative_to(parent.resolve())+ return True+ except ValueError:+ return False+++def _archive_source_pptx(source_pptx: Path, archived_pptx: Path, projects_root: Path) -> str:+ """Move project-local sources into the project; copy external sources."""+ archived_pptx.parent.mkdir(parents=True, exist_ok=True)+ if source_pptx.resolve() == archived_pptx.resolve():+ return "reuse"+ if _is_relative_to(source_pptx, projects_root):+ shutil.move(str(source_pptx), str(archived_pptx))+ return "move"+ shutil.copy2(source_pptx, archived_pptx)+ return "copy"+++def _relationship_file_for_part(extract_dir: Path, part_name: str) -> Path:+ part = Path(part_name)+ return extract_dir / part.parent / "_rels" / f"{part.name}.rels"+++def _ensure_rels_file(path: Path) -> None:+ if path.exists():+ return+ path.parent.mkdir(parents=True, exist_ok=True)+ path.write_text(+ '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n'+ f'<Relationships xmlns="{PACKAGE_REL_NS}">\n</Relationships>',+ encoding="utf-8",+ )+++def _remove_relationships_by_type(rels_path: Path, rel_type: str) -> None:+ if not rels_path.exists():+ return+ content = rels_path.read_text(encoding="utf-8")+ content = re.sub(+ rf'\s*<Relationship\b[^>]*\bType="{re.escape(rel_type)}"[^>]*/>',+ "",+ content,+ )+ rels_path.write_text(content, encoding="utf-8")+++def _target_to_part(target: str) -> str:+ target = target.lstrip("/")+ if target.startswith("ppt/"):+ return target+ return f"ppt/{target}"+++def _slide_number_from_part(part_name: str) -> int:+ match = re.search(r"slide(\d+)\.xml$", part_name)+ if not match:+ raise ValueError(f"Unsupported slide part name: {part_name}")+ return int(match.group(1))+++def read_slide_parts(extract_dir: Path) -> list[SlidePart]:+ presentation_path = extract_dir / "ppt" / "presentation.xml"+ rels_path = extract_dir / "ppt" / "_rels" / "presentation.xml.rels"+ if not presentation_path.exists() or not rels_path.exists():+ raise RuntimeError("PPTX package is missing presentation.xml or its relationships")++ rels_root = ET.parse(rels_path).getroot()+ rels: dict[str, str] = {}+ for rel in rels_root.findall(f"{{{PACKAGE_REL_NS}}}Relationship"):+ rel_id = rel.attrib.get("Id")+ target = rel.attrib.get("Target")+ if rel_id and target:+ rels[rel_id] = target++ presentation_root = ET.parse(presentation_path).getroot()+ slide_parts: list[SlidePart] = []+ for index, slide_id in enumerate(+ presentation_root.findall(f".//{{{PRESENTATION_NS}}}sldId"),+ 1,+ ):+ rel_id = slide_id.attrib.get(f"{{{REL_NS}}}id")+ if not rel_id or rel_id not in rels:+ continue+ part_name = _target_to_part(rels[rel_id])+ slide_parts.append(+ SlidePart(+ index=index,+ part_name=part_name,+ slide_number=_slide_number_from_part(part_name),+ )+ )+ if not slide_parts:+ raise RuntimeError("No slides found in presentation.xml")+ return slide_parts+++def _zip_dir(source_dir: Path, output_path: Path) -> None:+ output_path.parent.mkdir(parents=True, exist_ok=True)+ with zipfile.ZipFile(output_path, "w", zipfile.ZIP_DEFLATED) as zf:+ for path in sorted(source_dir.rglob("*")):+ if path.is_file():+ zf.write(path, path.relative_to(source_dir).as_posix())+++def _extract_pptx(source_pptx: Path, extract_dir: Path) -> None:+ with zipfile.ZipFile(source_pptx, "r") as zf:+ zf.extractall(extract_dir)+++def _note_path(notes_dir: Path, index: int) -> Path | None:+ candidates = [+ notes_dir / f"{index:03d}.md",+ notes_dir / f"{index:02d}.md",+ notes_dir / f"{index}.md",+ notes_dir / f"slide{index:03d}.md",+ notes_dir / f"slide{index:02d}.md",+ notes_dir / f"slide{index}.md",+ ]+ for candidate in candidates:+ if candidate.exists():+ return candidate+ return None+++def _audio_path(audio_dir: Path, index: int) -> Path | None:+ stems = [+ f"{index:03d}",+ f"{index:02d}",+ str(index),+ f"slide{index:03d}",+ f"slide{index:02d}",+ f"slide{index}",+ ]+ for stem in stems:+ for ext in NARRATION_EXTENSIONS:+ candidate = audio_dir / f"{stem}{ext}"+ if candidate.exists():+ return candidate+ return None+++def _add_override(content_types: str, part_name: str, content_type: str) -> str:+ if re.search(+ rf'<Override\b[^>]*\bPartName="/{re.escape(part_name)}"[^>]*/>',+ content_types,+ ):+ return content_types+ override = f' <Override PartName="/{part_name}" ContentType="{content_type}"/>'+ return content_types.replace("</Types>", override + "\n</Types>")+++def _add_notes_content_types(content_types: str, note_indices: set[int]) -> str:+ content_types = _add_override(content_types, "ppt/theme/theme2.xml", CONTENT_TYPE_THEME)+ content_types = _add_override(+ content_types,+ "ppt/notesMasters/notesMaster1.xml",+ CONTENT_TYPE_NOTES_MASTER,+ )+ for index in sorted(note_indices):+ content_types = _add_override(+ content_types,+ f"ppt/notesSlides/notesSlide{index}.xml",+ CONTENT_TYPE_NOTES_SLIDE,+ )+ return content_types+++def _set_transition_only(slide_xml: str, effect: str, duration: float) -> str:+ transition_xml = create_transition_xml(effect=effect, duration=duration)+ if re.search(r"<p:transition\b[^>]*/>", slide_xml):+ return re.sub(r"\s*<p:transition\b[^>]*/>", "\n" + transition_xml, slide_xml, count=1)+ if re.search(r"<p:transition\b[^>]*>.*?</p:transition>", slide_xml, re.S):+ return re.sub(+ r"\s*<p:transition\b[^>]*>.*?</p:transition>",+ "\n" + transition_xml,+ slide_xml,+ count=1,+ flags=re.S,+ )+ if "<p:timing>" in slide_xml:+ return slide_xml.replace("<p:timing>", transition_xml + "\n <p:timing>", 1)+ return slide_xml.replace("</p:sld>", transition_xml + "\n</p:sld>", 1)+++def _apply_recorded_timing_without_transition(slide_xml: str, advance_after: float) -> str:+ adv_ms = max(1, int(advance_after * 1000))+ transition_xml = f' <p:transition advTm="{adv_ms}"/>'+ slide_xml = re.sub(r"\s*<p:transition\b[^>]*/>", "", slide_xml, count=1)+ slide_xml = re.sub(+ r"\s*<p:transition\b[^>]*>.*?</p:transition>",+ "",+ slide_xml,+ count=1,+ flags=re.S,+ )+ if "<p:timing>" in slide_xml:+ return slide_xml.replace("<p:timing>", transition_xml + "\n <p:timing>", 1)+ return slide_xml.replace("</p:sld>", transition_xml + "\n</p:sld>", 1)+++def _apply_notes(extract_dir: Path, slide: SlidePart, note_md: Path) -> None:+ notes_text = markdown_to_plain_text(note_md.read_text(encoding="utf-8"))+ if not notes_text:+ return++ _ensure_notes_master(extract_dir)+ notes_dir = extract_dir / "ppt" / "notesSlides"+ notes_dir.mkdir(parents=True, exist_ok=True)+ notes_xml_path = notes_dir / f"notesSlide{slide.index}.xml"+ notes_xml_path.write_text(+ create_notes_slide_xml(slide.slide_number, notes_text),+ encoding="utf-8",+ )++ notes_rels_dir = notes_dir / "_rels"+ notes_rels_dir.mkdir(parents=True, exist_ok=True)+ notes_rels_path = notes_rels_dir / f"notesSlide{slide.index}.xml.rels"+ notes_rels_path.write_text(+ create_notes_slide_rels_xml(slide.slide_number),+ encoding="utf-8",+ )++ slide_rels = _relationship_file_for_part(extract_dir, slide.part_name)+ _ensure_rels_file(slide_rels)+ _remove_relationships_by_type(slide_rels, NOTES_REL_TYPE)+ _append_relationship(+ slide_rels,+ NOTES_REL_TYPE,+ f"../notesSlides/notesSlide{slide.index}.xml",+ )+++def _apply_audio(+ extract_dir: Path,+ slide: SlidePart,+ audio_path: Path,+ *,+ transition: str,+ transition_duration: float,+ narration_padding: float,+) -> None:+ media_dir = extract_dir / "ppt" / "media"+ media_dir.mkdir(parents=True, exist_ok=True)++ ext = audio_path.suffix.lower()+ media_name = f"native_enhance_audio_{slide.index:03d}{ext}"+ shutil.copy2(audio_path, media_dir / media_name)++ poster_name = "native_enhance_audio_poster.png"+ poster_path = media_dir / poster_name+ if not poster_path.exists():+ poster_path.write_bytes(TRANSPARENT_PNG_BYTES)++ slide_rels = _relationship_file_for_part(extract_dir, slide.part_name)+ _ensure_rels_file(slide_rels)+ media_rid = _append_relationship(slide_rels, MEDIA_REL_TYPE, f"../media/{media_name}")+ audio_rid = _append_relationship(slide_rels, AUDIO_REL_TYPE, f"../media/{media_name}")+ poster_rid = _append_relationship(slide_rels, IMAGE_REL_TYPE, f"../media/{poster_name}")++ slide_xml_path = extract_dir / slide.part_name+ slide_xml = slide_xml_path.read_text(encoding="utf-8")+ shape_id = next_shape_id(slide_xml)+ slide_xml = inject_narration(+ slide_xml,+ shape_id=shape_id,+ shape_name=media_name,+ audio_rid=audio_rid,+ media_rid=media_rid,+ poster_rid=poster_rid,+ )++ duration = probe_audio_duration(audio_path)+ if duration is None:+ raise RuntimeError(f"Unable to read narration duration with ffprobe: {audio_path}")+ advance_after = duration + narration_padding+ if transition == "none":+ slide_xml = _apply_recorded_timing_without_transition(slide_xml, advance_after)+ else:+ slide_xml = apply_recorded_timing(+ slide_xml,+ advance_after=advance_after,+ transition_duration=transition_duration,+ transition_effect=transition,+ )+ slide_xml_path.write_text(slide_xml, encoding="utf-8")+++def _update_content_types(extract_dir: Path, note_indices: set[int], audio_exts: set[str]) -> None:+ content_types_path = extract_dir / "[Content_Types].xml"+ content_types = content_types_path.read_text(encoding="utf-8")+ if note_indices:+ content_types = _add_notes_content_types(content_types, note_indices)+ for ext in sorted(audio_exts):+ content_type = AUDIO_CONTENT_TYPES.get(ext)+ if content_type:+ content_types = _add_default_content_type(content_types, ext, content_type)+ if audio_exts:+ content_types = _add_default_content_type(content_types, "png", "image/png")+ content_types_path.write_text(content_types, encoding="utf-8")+++def _project_paths(project_path: Path) -> tuple[Path, Path, Path, Path]:+ project = _read_json(project_path / "project.json")+ source_pptx = project_path / project["source_pptx"]+ notes_dir = project_path / project["notes_dir"]+ audio_dir = project_path / project["audio_dir"]+ exports_dir = project_path / project["exports_dir"]+ return source_pptx, notes_dir, audio_dir, exports_dir+++def _plan_path(project_path: Path) -> Path:+ return project_path / "analysis" / "enhancement_plan.json"+++def _load_enhancement_plan(project_path: Path) -> dict:+ path = _plan_path(project_path)+ if not path.exists():+ return {}+ return _read_json(path)+++def _enabled_modules(plan: dict) -> set[str]:+ modules = plan.get("modules")+ if not isinstance(modules, dict):+ return {"notes", "audio", "timings", "transitions"}+ enabled: set[str] = set()+ for name, config in modules.items():+ if isinstance(config, dict) and config.get("enabled") is True:+ enabled.add(str(name))+ return enabled+++def _plan_confirmed(plan: dict) -> bool:+ return plan.get("status") == "confirmed"+++def _build_enhancement_plan(+ project: dict,+ *,+ slide_count: int,+ notes_count: int,+ audio_count: int,+ transition: str,+ transition_duration: float,+ narration_padding: float,+ apply_transition_without_audio: bool,+) -> dict:+ return {+ "schema": "native_pptx_enhancement_plan.v1",+ "status": "draft",+ "source_pptx": project.get("source_pptx"),+ "slide_count": slide_count,+ "modules": {+ "notes": {+ "enabled": True,+ "requires_confirmation": True,+ "status": "ready" if notes_count == slide_count else "needs_notes",+ "coverage": {"ready": notes_count, "total": slide_count},+ },+ "audio": {+ "enabled": True,+ "requires_confirmation": True,+ "status": "ready" if audio_count == slide_count else "needs_audio",+ "coverage": {"ready": audio_count, "total": slide_count},+ },+ "timings": {+ "enabled": True,+ "requires_confirmation": True,+ "status": "ready" if audio_count == slide_count else "blocked_until_audio",+ "source": "audio_duration",+ "narration_padding": narration_padding,+ },+ "transitions": {+ "enabled": transition != "none",+ "requires_confirmation": True,+ "status": "ready",+ "effect": transition,+ "duration": transition_duration,+ "apply_without_audio": apply_transition_without_audio,+ },+ },+ "not_in_v1": [+ "object_animation",+ "visible_watermark",+ "footer_or_logo_insertion",+ "background_music",+ "media_compression",+ ],+ }+++def init_project(args: argparse.Namespace) -> int:+ source_pptx = Path(args.source_pptx).expanduser().resolve()+ if not source_pptx.exists() or source_pptx.suffix.lower() != ".pptx":+ print(f"error: expected an existing .pptx file: {source_pptx}", file=sys.stderr)+ return 1++ stem = _sanitize_slug(args.name or source_pptx.stem)+ date = datetime.now().strftime("%Y%m%d")+ project_path = (+ Path(args.project_dir).expanduser().resolve()+ if args.project_dir+ else Path(args.projects_root).expanduser().resolve() / f"{stem}_native_enhance_{date}"+ )+ if project_path.exists() and any(project_path.iterdir()):+ print(f"error: project directory already exists and is not empty: {project_path}", file=sys.stderr)+ return 1++ for dirname in ("sources", "analysis", "notes", "audio", "exports", "validation"):+ (project_path / dirname).mkdir(parents=True, exist_ok=True)++ archived_pptx = project_path / "sources" / source_pptx.name+ projects_root = Path(args.projects_root).expanduser().resolve()+ source_import_mode = _archive_source_pptx(source_pptx, archived_pptx, projects_root)++ source_md = project_path / "sources" / f"{source_pptx.stem}.md"+ ppt_to_md = _SCRIPTS_DIR / "source_to_md" / "ppt_to_md.py"+ result = subprocess.run(+ [sys.executable, str(ppt_to_md), str(archived_pptx), "-o", str(source_md)],+ check=False,+ text=True,+ capture_output=True,+ )+ if result.returncode != 0:+ print(result.stderr or result.stdout, file=sys.stderr)+ return result.returncode++ with tempfile.TemporaryDirectory(prefix="native-enhance-intake-") as tmp:+ extract_dir = Path(tmp) / "pptx"+ _extract_pptx(archived_pptx, extract_dir)+ slide_parts = read_slide_parts(extract_dir)++ slide_index = {+ "schema": "native_pptx_enhancement_slide_index.v1",+ "source_pptx": f"sources/{source_pptx.name}",+ "slide_count": len(slide_parts),+ "slides": [+ {+ "index": slide.index,+ "note_file": f"notes/{slide.index:03d}.md",+ "audio_stem": f"{slide.index:03d}",+ "part_name": slide.part_name,+ "slide_number": slide.slide_number,+ }+ for slide in slide_parts+ ],+ }+ _write_json(project_path / "analysis" / "slide_index.json", slide_index)++ project = {+ "schema": PROJECT_SCHEMA,+ "kind": "native_pptx_enhancement",+ "modules": ["notes", "audio", "timings", "transitions"],+ "source_pptx": f"sources/{source_pptx.name}",+ "source_markdown": f"sources/{source_pptx.stem}.md",+ "source_import": {+ "mode": source_import_mode,+ "original_path": str(source_pptx),+ },+ "slide_count": len(slide_parts),+ "notes_dir": "notes",+ "audio_dir": "audio",+ "exports_dir": "exports",+ "transition": {+ "effect": args.transition,+ "duration": args.transition_duration,+ },+ "audio": {+ "provider": "",+ "voice": "",+ "rate": "",+ },+ }+ _write_json(project_path / "project.json", project)+ plan = _build_enhancement_plan(+ project,+ slide_count=len(slide_parts),+ notes_count=0,+ audio_count=0,+ transition=args.transition,+ transition_duration=args.transition_duration,+ narration_padding=args.narration_padding,+ apply_transition_without_audio=args.apply_transition_without_audio,+ )+ _write_json(_plan_path(project_path), plan)++ print(f"Project: {project_path}", file=sys.stderr)+ print(f"Slides: {len(slide_parts)}", file=sys.stderr)+ print(f"Source import: {source_import_mode}", file=sys.stderr)+ print(f"Source markdown: {source_md}", file=sys.stderr)+ print(f"Draft enhancement plan: {_plan_path(project_path)}", file=sys.stderr)+ print(+ "Review the plan with the user and set status to \"confirmed\" before generating notes/audio/applying.",+ file=sys.stderr,+ )+ return 0+++def plan_project(args: argparse.Namespace) -> int:+ project_path = Path(args.project_path).expanduser().resolve()+ project = _read_json(project_path / "project.json")+ if project.get("schema") not in {PROJECT_SCHEMA, *LEGACY_PROJECT_SCHEMAS}:+ print(f"error: not a native PPTX enhancement project: {project_path}", file=sys.stderr)+ return 1++ source_pptx, notes_dir, audio_dir, _exports_dir = _project_paths(project_path)+ with tempfile.TemporaryDirectory(prefix="native-enhance-plan-") as tmp:+ extract_dir = Path(tmp) / "pptx"+ _extract_pptx(source_pptx, extract_dir)+ slides = read_slide_parts(extract_dir)++ notes_count = sum(1 for slide in slides if _note_path(notes_dir, slide.index) is not None)+ audio_count = sum(1 for slide in slides if _audio_path(audio_dir, slide.index) is not None)+ plan = _build_enhancement_plan(+ project,+ slide_count=len(slides),+ notes_count=notes_count,+ audio_count=audio_count,+ transition=args.transition,+ transition_duration=args.transition_duration,+ narration_padding=args.narration_padding,+ apply_transition_without_audio=args.apply_transition_without_audio,+ )+ _write_json(_plan_path(project_path), plan)+ print(json.dumps(plan, ensure_ascii=False, indent=2))+ print(f"Plan written: {_plan_path(project_path)}", file=sys.stderr)+ print(+ "Confirm by editing status to \"confirmed\" after user approval, then run apply.",+ file=sys.stderr,+ )+ return 0+++def apply_project(args: argparse.Namespace) -> int:+ project_path = Path(args.project_path).expanduser().resolve()+ project = _read_json(project_path / "project.json")+ if project.get("schema") not in {PROJECT_SCHEMA, *LEGACY_PROJECT_SCHEMAS}:+ print(f"error: not a native PPTX enhancement project: {project_path}", file=sys.stderr)+ return 1++ source_pptx, notes_dir, audio_dir, exports_dir = _project_paths(project_path)+ transition_cfg = project.get("transition", {}) if isinstance(project.get("transition"), dict) else {}+ plan = _load_enhancement_plan(project_path)+ if not _plan_confirmed(plan) and not args.force:+ print(+ f"error: enhancement plan is not confirmed: {_plan_path(project_path)} "+ "(run plan, get user confirmation, set status to \"confirmed\", or pass --force)",+ file=sys.stderr,+ )+ return 1++ modules = _enabled_modules(plan)+ transitions_cfg = (+ plan.get("modules", {}).get("transitions", {})+ if isinstance(plan.get("modules"), dict)+ else {}+ )+ timings_cfg = (+ plan.get("modules", {}).get("timings", {})+ if isinstance(plan.get("modules"), dict)+ else {}+ )+ transition = (+ args.transition+ or transitions_cfg.get("effect")+ or transition_cfg.get("effect")+ or "fade"+ )+ transition_duration = (+ args.transition_duration+ or transitions_cfg.get("duration")+ or float(transition_cfg.get("duration") or 0.5)+ )+ narration_padding = (+ args.narration_padding+ if args.narration_padding is not None+ else float(timings_cfg.get("narration_padding") or 0.4)+ )+ apply_transition_without_audio = (+ args.apply_transition_without_audio+ or bool(transitions_cfg.get("apply_without_audio"))+ )++ output_path = (+ Path(args.output).expanduser().resolve()+ if args.output+ else exports_dir / f"{source_pptx.stem}_enhanced.pptx"+ )+ if output_path.exists() and not args.overwrite:+ print(f"error: output already exists, pass --overwrite: {output_path}", file=sys.stderr)+ return 1++ with tempfile.TemporaryDirectory(prefix="native-enhance-pptx-") as tmp:+ extract_dir = Path(tmp) / "pptx"+ _extract_pptx(source_pptx, extract_dir)+ slides = read_slide_parts(extract_dir)++ note_indices: set[int] = set()+ audio_exts: set[str] = set()+ audio_count = 0+ transition_only_count = 0+ for slide in slides:+ note = _note_path(notes_dir, slide.index)+ if "notes" in modules and note:+ _apply_notes(extract_dir, slide, note)+ note_indices.add(slide.index)++ audio = _audio_path(audio_dir, slide.index)+ if "audio" in modules and audio:+ _apply_audio(+ extract_dir,+ slide,+ audio,+ transition=transition if "transitions" in modules else "none",+ transition_duration=transition_duration,+ narration_padding=narration_padding if "timings" in modules else 0,+ )+ audio_exts.add(audio.suffix.lower())+ audio_count += 1+ continue++ if (+ "transitions" in modules+ and apply_transition_without_audio+ and transition != "none"+ ):+ slide_xml_path = extract_dir / slide.part_name+ slide_xml = slide_xml_path.read_text(encoding="utf-8")+ slide_xml_path.write_text(+ _set_transition_only(slide_xml, transition, transition_duration),+ encoding="utf-8",+ )+ transition_only_count += 1++ _update_content_types(extract_dir, note_indices, audio_exts)+ _zip_dir(extract_dir, output_path)++ print(f"Output: {output_path}", file=sys.stderr)+ print(f"Notes applied: {len(note_indices)}", file=sys.stderr)+ print(f"Audio embedded: {audio_count}", file=sys.stderr)+ if transition_only_count:+ print(f"Transition-only slides: {transition_only_count}", file=sys.stderr)+ return 0+++def validate_project(args: argparse.Namespace) -> int:+ project_path = Path(args.project_path).expanduser().resolve()+ project = _read_json(project_path / "project.json")+ if project.get("schema") not in {PROJECT_SCHEMA, *LEGACY_PROJECT_SCHEMAS}:+ print(f"error: not a native PPTX enhancement project: {project_path}", file=sys.stderr)+ return 1++ source_pptx, notes_dir, audio_dir, _exports_dir = _project_paths(project_path)+ with tempfile.TemporaryDirectory(prefix="native-enhance-validate-") as tmp:+ extract_dir = Path(tmp) / "pptx"+ _extract_pptx(source_pptx, extract_dir)+ slides = read_slide_parts(extract_dir)++ plan = _load_enhancement_plan(project_path)+ modules = _enabled_modules(plan)+ notes_count = sum(1 for slide in slides if _note_path(notes_dir, slide.index) is not None)+ audio_count = sum(1 for slide in slides if _audio_path(audio_dir, slide.index) is not None)+ missing_notes = (+ [slide.index for slide in slides if _note_path(notes_dir, slide.index) is None]+ if "notes" in modules+ else []+ )+ missing_audio = (+ [slide.index for slide in slides if _audio_path(audio_dir, slide.index) is None]+ if "audio" in modules+ else []+ )+ report = {+ "schema": "native_pptx_enhancement_validation.v1",+ "slide_count": len(slides),+ "plan_status": plan.get("status") or "missing",+ "enabled_modules": sorted(modules),+ "notes_required": "notes" in modules,+ "audio_required": "audio" in modules,+ "notes_count": notes_count,+ "audio_count": audio_count,+ "missing_notes": missing_notes,+ "missing_audio": missing_audio,+ }+ validation_dir = project_path / "validation"+ validation_dir.mkdir(exist_ok=True)+ _write_json(validation_dir / "report.json", report)+ print(json.dumps(report, ensure_ascii=False, indent=2))+ return 0 if not missing_notes and not missing_audio else 2+++def build_parser() -> argparse.ArgumentParser:+ parser = argparse.ArgumentParser(+ description="Create/apply a native existing-PPTX enhancement project without SVG conversion.",+ formatter_class=argparse.RawDescriptionHelpFormatter,+ )+ subparsers = parser.add_subparsers(dest="command", required=True)++ init = subparsers.add_parser("init", help="create a native PPTX enhancement project")+ init.add_argument("source_pptx", help="source .pptx file")+ init.add_argument("--name", default=None, help="ASCII project name slug")+ init.add_argument("--project-dir", default=None, help="explicit project directory")+ init.add_argument("--projects-root", default="projects", help="projects root (default: projects)")+ init.add_argument("--transition", default="fade", choices=sorted(TRANSITIONS.keys()))+ init.add_argument("--transition-duration", type=float, default=0.5)+ init.add_argument("--narration-padding", type=float, default=0.4)+ init.add_argument(+ "--apply-transition-without-audio",+ action="store_true",+ help="draft the plan with page transitions for slides without audio",+ )+ init.set_defaults(func=init_project)++ plan = subparsers.add_parser("plan", help="draft an enhancement module plan")+ plan.add_argument("project_path", help="native enhancement project directory")+ plan.add_argument("--transition", default="fade", choices=sorted(TRANSITIONS.keys()) + ["none"])+ plan.add_argument("--transition-duration", type=float, default=0.5)+ plan.add_argument("--narration-padding", type=float, default=0.4)+ plan.add_argument(+ "--apply-transition-without-audio",+ action="store_true",+ help="include page transitions for slides without audio",+ )+ plan.set_defaults(func=plan_project)++ apply = subparsers.add_parser("apply", help="patch notes/audio/timings into a copied PPTX")+ apply.add_argument("project_path", help="native narration project directory")+ apply.add_argument("-o", "--output", default=None, help="output .pptx path")+ apply.add_argument("--overwrite", action="store_true", help="overwrite output if it exists")+ apply.add_argument("--transition", default=None, choices=sorted(TRANSITIONS.keys()) + ["none"])+ apply.add_argument("--transition-duration", type=float, default=None)+ apply.add_argument("--narration-padding", type=float, default=None)+ apply.add_argument("--force", action="store_true", help="apply without a confirmed enhancement plan")+ apply.add_argument(+ "--apply-transition-without-audio",+ action="store_true",+ help="also write page transitions on slides that do not have audio",+ )+ apply.set_defaults(func=apply_project)++ validate = subparsers.add_parser("validate", help="check notes/audio coverage")+ validate.add_argument("project_path", help="native narration project directory")+ validate.set_defaults(func=validate_project)+ return parser+++def main(argv: list[str] | None = None) -> int:+ parser = build_parser()+ args = parser.parse_args(argv)+ return args.func(args)+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_narration.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_narration.pyindex 38f05314..c85efb29 100644--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_narration.py+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_narration.py@@ -206,10 +206,16 @@ def apply_recorded_timing(transition_match = re.search(r"<p:transition\b[^>]*>", slide_xml)if transition_match:tag = transition_match.group(0)- if "advTm=" in tag:- new_tag = re.sub(r'\sadvTm="[^"]*"', f' advTm="{adv_ms}"', tag, count=1)+ is_self_closing = tag.rstrip().endswith("/>")+ base_tag = tag.rstrip()+ if is_self_closing:+ base_tag = re.sub(r"\s*/>$", ">", base_tag, count=1)+ if "advTm=" in base_tag:+ new_tag = re.sub(r'\sadvTm="[^"]*"', f' advTm="{adv_ms}"', base_tag, count=1)else:- new_tag = tag[:-1] + f' advTm="{adv_ms}">'+ new_tag = base_tag[:-1] + f' advTm="{adv_ms}">'+ if is_self_closing:+ new_tag = new_tag[:-1] + "/>"return slide_xml[:transition_match.start()] + new_tag + slide_xml[transition_match.end():]effect = transition_effect or "fade"diff --git a/skills/ppt-master/workflows/native-enhance-pptx.md b/skills/ppt-master/workflows/native-enhance-pptx.mdnew file mode 100644index 00000000..f6fb3f04--- /dev/null+++ b/skills/ppt-master/workflows/native-enhance-pptx.md@@ -0,0 +1,303 @@+---+description: Native enhancement platform for existing PPTX files, starting with notes/audio/timings/transitions without SVG conversion+---++# Native Enhance PPTX Workflow++> Standalone workflow for enhancing an existing PowerPoint deck without regenerating it. V1 implements the `narration` module: speaker notes, narration audio, slide auto-advance timings, and page transitions.++This workflow treats a `.pptx` as the artifact to preserve. It archives the source file into a lightweight project, uses `ppt_to_md.py` only to understand slide content, then patches the archived PPTX package directly through OOXML zip operations.++---++## 1. Platform Contract++| Rule | Contract |+|---|---|+| Source file | If already under `projects/`, move it into the enhancement project; otherwise copy it |+| Visible slides | Do not rewrite existing text, shapes, images, charts, tables, masters, or layouts |+| Route | Direct PPTX package patching; no SVG conversion |+| Output | A new `.pptx` under `<project>/exports/` |+| Project kind | `native_pptx_enhancement` |++**Hard rule**: Native enhancement is append-oriented. It may add notes, media, timings, transitions, relationships, and content-type records. It must not regenerate slides.++**Forbidden — SVG pipeline**:+- Do not run `pptx_template_import.py`+- Do not create `svg_output/`+- Do not run `finalize_svg.py`+- Do not run `svg_to_pptx.py`++**OOXML execution model**:++```text+source.pptx+→ unzip to temporary work directory+→ patch only required package parts+→ rezip to exports/<source>_enhanced.pptx+```++---++## 2. Module Scope++| Module | V1 status | Behavior |+|---|---:|---|+| `narration.notes` | Enabled | Add or replace speaker notes generated from slide content |+| `narration.audio` | Enabled | Embed one audio file per slide |+| `narration.timings` | Enabled | Set narrated slides to auto-advance by audio duration |+| `narration.transitions` | Enabled | Add page-level transitions for narrated/selected slides |+| `delivery.check` | Planned | Font/media/hidden-slide/file-size validation |+| `media` | Planned | Background music, video, media compression |+| `presenter` | Planned | Q&A notes, speaker cues, rehearsal artifacts |+| `animation` | Planned | Explicit object-level animation only |+| `visible-stamp` | Planned | Watermark/footer/logo; requires explicit confirmation |++**Default — V1 only**: Do not implement planned modules inside this workflow yet. Keep V1 focused on the narration module.++**Object animation boundary**: Object-level animation is not part of V1. If the user asks for it, treat it as a future module or a separate explicitly confirmed task.++---++## 3. When to Run++| Condition | Action |+|---|---|+| Existing `.pptx` + wants notes / narration / voiceover / auto-play / page transitions while keeping format stable | Run this workflow |+| Existing `.pptx` + asks to optimize it but says not to change existing content or layout | Run this workflow only for V1 narration enhancements; clarify any visible-slide request |+| Existing `.pptx` + asks to beautify or re-layout | Use [`beautify-pptx`](./beautify-pptx.md) |+| Existing `.pptx` + asks to fill new content into the design | Use [`template-fill-pptx`](./template-fill-pptx.md) |+| PPT Master generated project with `svg_output/` | Use [`generate-audio`](./generate-audio.md) for narration |++---++## 4. Create the Project and Draft Plan++🚧 **GATE**: User provided an existing `.pptx`.++Run:++```bash+python3 skills/ppt-master/scripts/native_enhance_pptx.py init "<source.pptx>" --name "<project_slug>"+```++Project layout:++| Path | Purpose |+|---|---|+| `<project>/project.json` | Project schema, kind, enabled modules, source paths, defaults |+| `<project>/sources/<source>.pptx` | Archived source PPTX used for package patching |+| `<project>/sources/<source>.md` | `ppt_to_md.py` output for slide understanding |+| `<project>/analysis/slide_index.json` | Slide order and PPTX slide part mapping |+| `<project>/notes/` | Per-slide spoken notes, named `001.md`, `002.md`, ... |+| `<project>/audio/` | Per-slide narration media, named `001.mp3`, `002.mp3`, ... |+| `<project>/exports/` | Enhanced PPTX copies |+| `<project>/validation/` | Coverage reports and read-back artifacts |++**Validation**: `project.json` contains `schema: native_pptx_enhancement_project.v1`, `kind: native_pptx_enhancement`, and `modules` containing `notes`, `audio`, `timings`, `transitions`.++**Source import rule**: When `<source.pptx>` is inside the repo's `projects/` tree, `init` moves it into `<project>/sources/`. When it is outside `projects/`, `init` copies it into `<project>/sources/`. The mode is recorded in `project.json` as `source_import.mode`.++The `init` command also writes:++```text+<project>/analysis/enhancement_plan.json+```++**Hard rule**: Treat this draft plan as the first user-facing artifact. Do not generate notes, list voices, generate audio, or apply package patches before the user confirms which enhancements to add.++---++## 5. Enhancement Plan Confirmation++🚧 **GATE**: Step 4 complete; `<project>/analysis/enhancement_plan.json` exists.++If the project already existed or notes/audio coverage changed, refresh the draft:++```bash+python3 skills/ppt-master/scripts/native_enhance_pptx.py plan "<project>"+```++Present the plan to the user before generating notes or audio:++| Module | Recommended default | Confirmation question |+|---|---|---|+| `notes` | Enabled | Add/replace speaker notes generated from slide content? |+| `audio` | Enabled when user wants narration/video/autoplay | Generate one narration audio file per slide? |+| `timings` | Enabled with audio | Set slide auto-advance from audio duration? |+| `transitions` | Enabled, `fade` 0.5s | Add page transitions? Which effect/duration? |++**⛔ BLOCKING**: Stop here and wait for explicit user confirmation. Do not generate notes, generate audio, or patch the PPTX until the user confirms the module plan.++After confirmation, update `<project>/analysis/enhancement_plan.json`:++```json+{+ "status": "confirmed"+}+```++Also set each confirmed module's `enabled` value. Disabled modules must stay in the file with `enabled: false`, not be deleted.++---++## 6. Generate Notes From Existing Slides++🚧 **GATE**: Step 5 confirmed; `notes.enabled` is true; `<project>/sources/<source>.md` exists.++Read:++| File | Use |+|---|---|+| `<project>/sources/<source>.md` | Visible slide text, tables, extracted notes, image references |+| `<project>/analysis/slide_index.json` | Exact slide count and target note filenames |++Write:++```text+<project>/notes/001.md+<project>/notes/002.md+...+```++**Hard rule**: Notes are spoken narration only. Do not include stage directions, implementation comments, timing labels, markdown tables, or visible-slide rewrite instructions.++**Hard rule**: Notes must be faithful to the slide. They may explain visible content, but must not add unsupported facts.++| Slide type | Notes length |+|---|---|+| Cover / section divider | 1-2 short sentences |+| Dense content page | 2-4 sentences |+| Chart / table page | Explain the reading path, then state the takeaway |+| Ending page | One concise close |++Run coverage check:++```bash+python3 skills/ppt-master/scripts/native_enhance_pptx.py validate "<project>"+```++> Note: before audio generation, missing audio returns exit code `2` only when `audio.enabled` is true. Missing notes are not acceptable once this step is complete.++---++## 7. Audio Voice Confirmation++🚧 **GATE**: Step 6 complete; `audio.enabled` is true.++Follow the same one-shot interaction standard as [`generate-audio`](./generate-audio.md):++1. Determine the notes' primary language.+2. List available voices for the selected backend.+3. Recommend backend, voice, rate/settings, and whether to embed audio back into the PPTX.+4. Ask the user to accept all recommendations or override any field.++For edge voices:++```bash+python3 skills/ppt-master/scripts/notes_to_audio.py --list-voices --locale <locale>+```++**⛔ BLOCKING**: Stop here and wait for explicit user confirmation of audio backend, voice, rate/settings, and embedding. Do not run `notes_to_audio.py` before this confirmation.++Record the confirmed audio config into `project.json`:++```json+{+ "audio": {+ "provider": "edge",+ "voice": "zh-CN-YunjianNeural",+ "rate": "+0%"+ }+}+```++---++## 8. Generate Audio++🚧 **GATE**: Step 7 confirmed; notes files exist under `<project>/notes/`.++Run with the confirmed values:++```bash+python3 skills/ppt-master/scripts/notes_to_audio.py "<project>" \+ --voice <chosen-ShortName> --rate <chosen-rate>+```++**Default — edge (may override)**: Use `edge` unless the user requests a cloud provider or supplies a cloned voice ID.++**Naming contract**: Audio stems match note stems: `001.md` → `001.mp3`.++Validate:++```bash+python3 skills/ppt-master/scripts/native_enhance_pptx.py validate "<project>"+```++---++## 9. Apply V1 Enhancements++🚧 **GATE**: Enhancement plan is confirmed; notes are ready if requested; audio is ready if requested.++Run:++```bash+python3 skills/ppt-master/scripts/native_enhance_pptx.py apply "<project>"+```++Optional:++```bash+python3 skills/ppt-master/scripts/native_enhance_pptx.py apply "<project>" \+ --transition fade \+ --transition-duration 0.5 \+ --narration-padding 0.4 \+ --overwrite+```++Patch scope:++| Package area | Append/update |+|---|---|+| `ppt/notesSlides/` | Notes slide parts |+| `ppt/notesMasters/` | Notes master only when needed |+| `ppt/slides/_rels/slideN.xml.rels` | Relationships for notes/audio/media/poster |+| `ppt/media/` | Narration audio and transparent poster |+| `ppt/slides/slideN.xml` | Hidden autoplay audio shape and page timing |+| `[Content_Types].xml` | Required content types |++**Hard rule**: Do not modify existing slide shapes, text bodies, images, chart data, master/layout parts, or existing non-target relationships.++---++## 10. Validate Output++Run read-back:++```bash+python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py \+ "<project>/exports/<source>_enhanced.pptx" \+ -o "<project>/validation/readback.md"+```++Check:++| Check | Expected |+|---|---|+| Slide count | Same as source |+| Visible content | No intentional changes |+| Notes | Present on intended slides |+| Audio media | Present under `ppt/media/` when generated |+| Auto-play | Narrated slides advance by audio duration |++```markdown+## ✅ Native PPTX Enhancement V1 Complete++- [x] Project initialized at `<project>`+- [x] Source PPTX archived into `<project>/sources/`+- [x] V1 narration module applied+- [x] Enhanced PPTX exported to `<project>/exports/<file>.pptx`+- [x] Read-back validation written to `<project>/validation/readback.md`+```diff --git a/skills/ppt-master/workflows/native-narration-pptx.md b/skills/ppt-master/workflows/native-narration-pptx.mdnew file mode 100644index 00000000..71008466--- /dev/null+++ b/skills/ppt-master/workflows/native-narration-pptx.md@@ -0,0 +1,35 @@+---+description: Compatibility reference for existing-PPTX narration enhancement+---++# Native Narration PPTX Workflow++> Superseded routing: use [`native-enhance-pptx`](./native-enhance-pptx.md) for all existing-PPTX native enhancement work.++This file remains only as a compatibility reference for older agents and links. Do not maintain a separate narration workflow here.++## 1. Routing++| Need | Action |+|---|---|+| Existing `.pptx` + add speaker notes, narration audio, auto-advance, or page transitions while preserving visible slides | Run [`native-enhance-pptx`](./native-enhance-pptx.md) |+| PPT Master generated project with `svg_output/` / `svg_final/` | Use [`generate-audio`](./generate-audio.md) |+| Existing `.pptx` + beautify or re-layout visible slides | Use [`beautify-pptx`](./beautify-pptx.md) |+| Existing `.pptx` + fill new content into a native design | Use [`template-fill-pptx`](./template-fill-pptx.md) |++**Hard rule**: Do not follow the retired `native_narration_pptx.py` workflow steps directly. Use the stable `native_enhance_pptx.py` entry point documented in [`native-enhance-pptx`](./native-enhance-pptx.md).++## 2. Compatibility Boundary++`native_narration_pptx.py` may remain as a backward-compatible implementation entry point, but user-facing workflow execution must use:++```bash+python3 skills/ppt-master/scripts/native_enhance_pptx.py init "<source.pptx>" --name "<project_slug>"+python3 skills/ppt-master/scripts/native_enhance_pptx.py plan "<project>"+python3 skills/ppt-master/scripts/native_enhance_pptx.py validate "<project>"+python3 skills/ppt-master/scripts/native_enhance_pptx.py apply "<project>"+```++**Source import rule**: The active workflow archives the source PPTX into `<project>/sources/`; sources already under the repo's `projects/` tree are moved, and external sources are copied.++**Output rule**: Enhanced decks are written under `<project>/exports/` with the `_enhanced.pptx` suffix unless the caller passes an explicit `--output`.