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
refactor(native-enhance): consolidate the native enhancement workflow
hugohe3fd85a5d84a92
diff --git a/docs/technical-design.md b/docs/technical-design.mdindex e09b46cc..d657704b 100644--- a/docs/technical-design.md+++ b/docs/technical-design.md@@ -491,7 +491,7 @@ Not every PPTX-related request should regenerate slides. PPT Master now has dire`template_fill_pptx.py` is a thin CLI wrapper over `scripts/template_fill_pptx/`. Its analyzer extracts a slide library with text slots, tables, charts, and geometry; the fill plan selects source slides, confirms replacements, then the applier clones slides and patches XML parts directly. This route deliberately avoids SVG: a user who supplies a PowerPoint template usually wants those native slide masters, placeholders, tables, and charts to remain PowerPoint-native.-`native_enhance_pptx.py` is the stable entry point for finished-deck enhancement. It delegates to the native narration/timing implementation and patches the PPTX package in place from a project copy: notes, page transitions, recorded narration media, slide timings, and related metadata. The contract is preservation: existing content, layout, and formatting are not regenerated.+`native_enhance_pptx.py` is the stable entry point for finished-deck enhancement. It delegates to `native_enhance_pptx_core.py` and patches the PPTX package in place from a project copy: notes, page transitions, recorded narration media, slide timings, and related metadata. The retired `native_narration_pptx.py` name remains only as a thin CLI compatibility shim. The contract is preservation: existing content, layout, and formatting are not regenerated.These direct routes share some analysis primitives with the main pipeline, especially PPTX intake, but they do not share the SVG authoring or post-processing stages. That separation is intentional: SVG generation is a design synthesis path; direct OOXML editing is a preservation path.diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.mdindex 42beaedb..72ff49dd 100644--- a/docs/zh/technical-design.md+++ b/docs/zh/technical-design.md@@ -493,7 +493,7 @@ PowerPoint 的 DrawingML 是 SVG 表达力的严格子集,因此主编译路`template_fill_pptx.py` 是 `scripts/template_fill_pptx/` 包的薄 CLI 入口。analyzer 抽取带文本槽位、表格、图表和几何信息的 slide library;fill plan 选择源页面并确认替换内容;applier 克隆幻灯片并直接 patch XML parts。这条路线故意绕开 SVG:用户提供 PowerPoint 模板时,通常期望原生母版、占位符、表格和图表继续保持 PowerPoint-native。-`native_enhance_pptx.py` 是已完成 deck 原生增强的稳定入口。它委托 native narration / timing 实现,在项目归档副本上直接 patch PPTX package:讲稿、页面转场、录制旁白媒体、页面计时和相关元数据。它的契约是保留:已有内容、布局和格式不重新生成。+`native_enhance_pptx.py` 是已完成 deck 原生增强的稳定入口。它委托 `native_enhance_pptx_core.py`,在项目归档副本上直接 patch PPTX package:讲稿、页面转场、录制旁白媒体、页面计时和相关元数据。旧名称 `native_narration_pptx.py` 仅保留为精简的 CLI 兼容包装器。它的契约是保留:已有内容、布局和格式不重新生成。这些直接路线会和主流水线共享部分分析原语,尤其是 PPTX intake,但不共享 SVG 作者阶段和后处理阶段。这个分离是有意的:SVG 生成是设计合成路径;直接 OOXML 编辑是保留路径。diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex b8776d5f..a6c0b3f0 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -97,7 +97,6 @@ description: >| `${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`.diff --git a/skills/ppt-master/scripts/docs/pptx-transitions.md b/skills/ppt-master/scripts/docs/pptx-transitions.mdindex cab55402..a1e9602e 100644--- a/skills/ppt-master/scripts/docs/pptx-transitions.md+++ b/skills/ppt-master/scripts/docs/pptx-transitions.md@@ -12,7 +12,7 @@ read-back validation for every PPTX route.| In-slide object animation | scripts/pptx_animations.py || Generated PPTX adapter | svg_to_pptx/pptx_package/builder.py || Template Fill adapter | template_fill_pptx/transitions.py |-| Native Enhance adapter | native_narration_pptx.py |+| Native Enhance adapter | native_enhance_pptx_core.py || Public workflow | references/animations.md |**Hard rule**: adapters resolve route policy, then call the shared core. Theydiff --git a/skills/ppt-master/scripts/native_enhance_pptx.py b/skills/ppt-master/scripts/native_enhance_pptx.pyindex 4e748f35..51bc779d 100644--- a/skills/ppt-master/scripts/native_enhance_pptx.py+++ b/skills/ppt-master/scripts/native_enhance_pptx.py@@ -18,7 +18,7 @@ Examples:python3 scripts/native_enhance_pptx.py apply projects/fire_station_native_enhance_20260626Dependencies:- Same as native_narration_pptx.py.+ Same as native_enhance_pptx_core.py."""from __future__ import annotations@@ -31,7 +31,7 @@ if str(_SCRIPTS_DIR) not in sys.path:sys.path.insert(0, str(_SCRIPTS_DIR))from console_encoding import configure_utf8_stdio # noqa: E402-from native_narration_pptx import main # noqa: E402+from native_enhance_pptx_core import main # noqa: E402configure_utf8_stdio()diff --git a/skills/ppt-master/scripts/native_enhance_pptx_core.py b/skills/ppt-master/scripts/native_enhance_pptx_core.pynew file mode 100644index 00000000..041c2f51--- /dev/null+++ b/skills/ppt-master/scripts/native_enhance_pptx_core.py@@ -0,0 +1,969 @@+#!/usr/bin/env python3+"""+PPT Master - Native Existing PPTX Enhancer++Implementation core for the public native enhancement CLI and its legacy+narration compatibility entrypoint. It enhances 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 console_encoding import configure_utf8_stdio # noqa: E402+from pptx_animations import ( # noqa: E402+ object_animation_fingerprint,+ validate_pptx_animation_package,+)+from pptx_transitions import ( # noqa: E402+ AdvanceUpdate,+ EnterUpdate,+ TRANSITIONS,+ apply_slide_motion_xml,+ set_directory_use_timings,+ validate_pptx_transition_package,+ validate_seconds,+)+from svg_to_pptx.pptx_package.builder import ( # noqa: E402+ _add_default_content_type,+ _append_relationship,+ _ensure_notes_master,+)+from svg_to_pptx.pptx_package.narration import ( # noqa: E402+ AUDIO_CONTENT_TYPES,+ AUDIO_MARKER_PNG_BYTES,+ AUDIO_REL_TYPE,+ IMAGE_REL_TYPE,+ MEDIA_REL_TYPE,+ NARRATION_EXTENSIONS,+ inject_narration,+ next_shape_id,+ probe_audio_duration,+)+from svg_to_pptx.pptx_package.notes import ( # noqa: E402+ create_notes_slide_rels_xml,+ create_notes_slide_xml,+ markdown_to_plain_text,+)++configure_utf8_stdio()+++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 _positive_seconds_arg(value: str) -> float:+ try:+ return validate_seconds(value, "transition duration", allow_zero=False)+ except ValueError as exc:+ raise argparse.ArgumentTypeError(str(exc)) from exc+++def _non_negative_seconds_arg(value: str) -> float:+ try:+ return validate_seconds(value, "narration padding", allow_zero=True)+ except ValueError as exc:+ raise argparse.ArgumentTypeError(str(exc)) from exc+++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 _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,+ *,+ enter: EnterUpdate,+ timings_enabled: bool,+ narration_padding: float,+) -> bool:+ 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(AUDIO_MARKER_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")+ source_animation_fingerprint = object_animation_fingerprint(slide_xml)+ 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,+ )++ advance = AdvanceUpdate(mode="preserve")+ if timings_enabled:+ duration = probe_audio_duration(audio_path)+ if duration is None:+ raise RuntimeError(f"Unable to read narration duration with ffprobe: {audio_path}")+ advance = AdvanceUpdate(+ mode="narration",+ after=duration + narration_padding,+ )++ wrote_advance = False+ if enter.policy != "preserve" or timings_enabled:+ slide_xml, wrote_advance = apply_slide_motion_xml(+ slide_xml,+ enter=enter,+ advance=advance,+ )+ if object_animation_fingerprint(slide_xml) != source_animation_fingerprint:+ raise RuntimeError(+ f"Slide {slide.index} object animations changed while adding narration"+ )+ slide_xml_path.write_text(slide_xml, encoding="utf-8")+ return timings_enabled and wrote_advance+++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 _resolve_enter_update(+ *,+ cli_effect: str | None,+ configured_effect: object,+ transitions_enabled: bool,+ duration: float,+) -> EnterUpdate:+ if cli_effect is None and not transitions_enabled:+ if configured_effect == "none":+ return EnterUpdate(policy="none", effect=None, duration=duration)+ return EnterUpdate(policy="preserve", duration=duration)++ effect = cli_effect if cli_effect is not None else configured_effect+ if not isinstance(effect, str):+ raise ValueError(f"transition effect must be a string: {effect!r}")+ if effect == "none":+ return EnterUpdate(policy="none", effect=None, duration=duration)+ if effect not in TRANSITIONS:+ valid = ", ".join(sorted(TRANSITIONS))+ raise ValueError(+ f"unknown transition effect {effect!r}; valid effects: {valid}, none"+ )++ return EnterUpdate(policy="replace", effect=effect, duration=duration)+++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)+ modules_cfg = plan.get("modules") if isinstance(plan.get("modules"), dict) else {}+ transitions_cfg = modules_cfg.get("transitions", {})+ if not isinstance(transitions_cfg, dict):+ transitions_cfg = {}+ timings_cfg = modules_cfg.get("timings", {})+ if not isinstance(timings_cfg, dict):+ timings_cfg = {}++ if "effect" in transitions_cfg:+ configured_effect = transitions_cfg["effect"]+ elif "effect" in transition_cfg:+ configured_effect = transition_cfg["effect"]+ else:+ configured_effect = "fade"++ if args.transition_duration is not None:+ raw_transition_duration = args.transition_duration+ elif "duration" in transitions_cfg:+ raw_transition_duration = transitions_cfg["duration"]+ elif "duration" in transition_cfg:+ raw_transition_duration = transition_cfg["duration"]+ else:+ raw_transition_duration = 0.5++ if args.narration_padding is not None:+ raw_narration_padding = args.narration_padding+ elif "narration_padding" in timings_cfg:+ raw_narration_padding = timings_cfg["narration_padding"]+ else:+ raw_narration_padding = 0.4++ try:+ if args.transition is not None or "transitions" in modules:+ transition_duration = validate_seconds(+ raw_transition_duration,+ "transition duration",+ allow_zero=False,+ )+ else:+ transition_duration = 0.5+ if "timings" in modules:+ narration_padding = validate_seconds(+ raw_narration_padding,+ "narration padding",+ allow_zero=True,+ )+ else:+ narration_padding = 0.4+ enter_update = _resolve_enter_update(+ cli_effect=args.transition,+ configured_effect=configured_effect,+ transitions_enabled="transitions" in modules,+ duration=transition_duration,+ )+ except ValueError as exc:+ print(f"error: {exc}", file=sys.stderr)+ return 1++ 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+ wrote_auto_advance = False+ 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:+ wrote_auto_advance = _apply_audio(+ extract_dir,+ slide,+ audio,+ enter=enter_update,+ timings_enabled="timings" in modules,+ narration_padding=narration_padding,+ ) or wrote_auto_advance+ audio_exts.add(audio.suffix.lower())+ audio_count += 1+ continue++ if (+ apply_transition_without_audio+ and enter_update.policy != "preserve"+ ):+ slide_xml_path = extract_dir / slide.part_name+ slide_xml = slide_xml_path.read_text(encoding="utf-8")+ source_animation_fingerprint = object_animation_fingerprint(+ slide_xml+ )+ slide_xml, _uses_timings = apply_slide_motion_xml(+ slide_xml,+ enter=enter_update,+ advance=AdvanceUpdate(mode="preserve"),+ )+ if (+ object_animation_fingerprint(slide_xml)+ != source_animation_fingerprint+ ):+ raise RuntimeError(+ f"Slide {slide.index} object animations changed while "+ "updating the transition"+ )+ slide_xml_path.write_text(+ slide_xml,+ encoding="utf-8",+ )+ transition_only_count += 1++ _update_content_types(extract_dir, note_indices, audio_exts)+ if wrote_auto_advance:+ set_directory_use_timings(extract_dir)+ output_path.parent.mkdir(parents=True, exist_ok=True)+ with tempfile.TemporaryDirectory(+ prefix="native-enhance-output-",+ dir=output_path.parent,+ ) as output_tmp:+ candidate_path = Path(output_tmp) / output_path.name+ _zip_dir(extract_dir, candidate_path)+ try:+ validate_pptx_transition_package(+ candidate_path,+ require_use_timings=wrote_auto_advance,+ )+ except ValueError as exc:+ raise RuntimeError(+ f"PPTX transition package validation failed: {exc}"+ ) from exc+ try:+ validate_pptx_animation_package(+ candidate_path,+ require_supported_effects=False,+ )+ except ValueError as exc:+ raise RuntimeError(+ f"PPTX animation/timing package validation failed: {exc}"+ ) from exc+ candidate_path.replace(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=_positive_seconds_arg, default=0.5)+ init.add_argument("--narration-padding", type=_non_negative_seconds_arg, 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=_positive_seconds_arg, default=0.5)+ plan.add_argument("--narration-padding", type=_non_negative_seconds_arg, 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 enhancement 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=_positive_seconds_arg, default=None)+ apply.add_argument("--narration-padding", type=_non_negative_seconds_arg, 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 enhancement 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/native_narration_pptx.py b/skills/ppt-master/scripts/native_narration_pptx.pyindex 914820e5..e9d0c604 100644--- a/skills/ppt-master/scripts/native_narration_pptx.py+++ b/skills/ppt-master/scripts/native_narration_pptx.py@@ -1,968 +1,37 @@#!/usr/bin/env python3"""-PPT Master - Native Existing PPTX Enhancer+PPT Master - Native Narration PPTX Compatibility Entrypoint-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.+Backward-compatible CLI for callers that still use the retired narration+script name. New calls use native_enhance_pptx.py.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>+ python3 scripts/native_narration_pptx.py init <source.pptx> [--name project_name]+ python3 scripts/native_narration_pptx.py plan <project_path>+ python3 scripts/native_narration_pptx.py validate <project_path>+ python3 scripts/native_narration_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 apply projects/fire_station_native_enhance_20260626- python3 scripts/native_enhance_pptx.py validate projects/fire_station_native_enhance_20260626+ python3 scripts/native_narration_pptx.py validate projects/native_enhance_projectDependencies:- ffprobe for audio-duration-based auto-advance timings.+ Same as native_enhance_pptx_core.py."""from __future__ import annotations-import argparse-import json-import re-import shutil-import subprocessimport sys-import tempfile-import zipfile-from dataclasses import dataclass-from datetime import datetimefrom pathlib import Path-from xml.etree import ElementTree as ET_SCRIPTS_DIR = Path(__file__).resolve().parentif str(_SCRIPTS_DIR) not in sys.path:sys.path.insert(0, str(_SCRIPTS_DIR))from console_encoding import configure_utf8_stdio # noqa: E402-from pptx_animations import ( # noqa: E402- object_animation_fingerprint,- validate_pptx_animation_package,-)-from pptx_transitions import ( # noqa: E402- AdvanceUpdate,- EnterUpdate,- TRANSITIONS,- apply_slide_motion_xml,- set_directory_use_timings,- validate_pptx_transition_package,- validate_seconds,-)-from svg_to_pptx.pptx_package.builder import ( # noqa: E402- _add_default_content_type,- _append_relationship,- _ensure_notes_master,-)-from svg_to_pptx.pptx_package.narration import ( # noqa: E402- AUDIO_CONTENT_TYPES,- AUDIO_MARKER_PNG_BYTES,- AUDIO_REL_TYPE,- IMAGE_REL_TYPE,- MEDIA_REL_TYPE,- NARRATION_EXTENSIONS,- inject_narration,- next_shape_id,- probe_audio_duration,-)-from svg_to_pptx.pptx_package.notes import ( # noqa: E402- create_notes_slide_rels_xml,- create_notes_slide_xml,- markdown_to_plain_text,-)+from native_enhance_pptx_core import main # noqa: E402configure_utf8_stdio()-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 _positive_seconds_arg(value: str) -> float:- try:- return validate_seconds(value, "transition duration", allow_zero=False)- except ValueError as exc:- raise argparse.ArgumentTypeError(str(exc)) from exc---def _non_negative_seconds_arg(value: str) -> float:- try:- return validate_seconds(value, "narration padding", allow_zero=True)- except ValueError as exc:- raise argparse.ArgumentTypeError(str(exc)) from exc---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 _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,- *,- enter: EnterUpdate,- timings_enabled: bool,- narration_padding: float,-) -> bool:- 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(AUDIO_MARKER_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")- source_animation_fingerprint = object_animation_fingerprint(slide_xml)- 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,- )-- advance = AdvanceUpdate(mode="preserve")- if timings_enabled:- duration = probe_audio_duration(audio_path)- if duration is None:- raise RuntimeError(f"Unable to read narration duration with ffprobe: {audio_path}")- advance = AdvanceUpdate(- mode="narration",- after=duration + narration_padding,- )-- wrote_advance = False- if enter.policy != "preserve" or timings_enabled:- slide_xml, wrote_advance = apply_slide_motion_xml(- slide_xml,- enter=enter,- advance=advance,- )- if object_animation_fingerprint(slide_xml) != source_animation_fingerprint:- raise RuntimeError(- f"Slide {slide.index} object animations changed while adding narration"- )- slide_xml_path.write_text(slide_xml, encoding="utf-8")- return timings_enabled and wrote_advance---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 _resolve_enter_update(- *,- cli_effect: str | None,- configured_effect: object,- transitions_enabled: bool,- duration: float,-) -> EnterUpdate:- if cli_effect is None and not transitions_enabled:- if configured_effect == "none":- return EnterUpdate(policy="none", effect=None, duration=duration)- return EnterUpdate(policy="preserve", duration=duration)-- effect = cli_effect if cli_effect is not None else configured_effect- if not isinstance(effect, str):- raise ValueError(f"transition effect must be a string: {effect!r}")- if effect == "none":- return EnterUpdate(policy="none", effect=None, duration=duration)- if effect not in TRANSITIONS:- valid = ", ".join(sorted(TRANSITIONS))- raise ValueError(- f"unknown transition effect {effect!r}; valid effects: {valid}, none"- )-- return EnterUpdate(policy="replace", effect=effect, duration=duration)---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)- modules_cfg = plan.get("modules") if isinstance(plan.get("modules"), dict) else {}- transitions_cfg = modules_cfg.get("transitions", {})- if not isinstance(transitions_cfg, dict):- transitions_cfg = {}- timings_cfg = modules_cfg.get("timings", {})- if not isinstance(timings_cfg, dict):- timings_cfg = {}-- if "effect" in transitions_cfg:- configured_effect = transitions_cfg["effect"]- elif "effect" in transition_cfg:- configured_effect = transition_cfg["effect"]- else:- configured_effect = "fade"-- if args.transition_duration is not None:- raw_transition_duration = args.transition_duration- elif "duration" in transitions_cfg:- raw_transition_duration = transitions_cfg["duration"]- elif "duration" in transition_cfg:- raw_transition_duration = transition_cfg["duration"]- else:- raw_transition_duration = 0.5-- if args.narration_padding is not None:- raw_narration_padding = args.narration_padding- elif "narration_padding" in timings_cfg:- raw_narration_padding = timings_cfg["narration_padding"]- else:- raw_narration_padding = 0.4-- try:- if args.transition is not None or "transitions" in modules:- transition_duration = validate_seconds(- raw_transition_duration,- "transition duration",- allow_zero=False,- )- else:- transition_duration = 0.5- if "timings" in modules:- narration_padding = validate_seconds(- raw_narration_padding,- "narration padding",- allow_zero=True,- )- else:- narration_padding = 0.4- enter_update = _resolve_enter_update(- cli_effect=args.transition,- configured_effect=configured_effect,- transitions_enabled="transitions" in modules,- duration=transition_duration,- )- except ValueError as exc:- print(f"error: {exc}", file=sys.stderr)- return 1-- 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- wrote_auto_advance = False- 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:- wrote_auto_advance = _apply_audio(- extract_dir,- slide,- audio,- enter=enter_update,- timings_enabled="timings" in modules,- narration_padding=narration_padding,- ) or wrote_auto_advance- audio_exts.add(audio.suffix.lower())- audio_count += 1- continue-- if (- apply_transition_without_audio- and enter_update.policy != "preserve"- ):- slide_xml_path = extract_dir / slide.part_name- slide_xml = slide_xml_path.read_text(encoding="utf-8")- source_animation_fingerprint = object_animation_fingerprint(- slide_xml- )- slide_xml, _uses_timings = apply_slide_motion_xml(- slide_xml,- enter=enter_update,- advance=AdvanceUpdate(mode="preserve"),- )- if (- object_animation_fingerprint(slide_xml)- != source_animation_fingerprint- ):- raise RuntimeError(- f"Slide {slide.index} object animations changed while "- "updating the transition"- )- slide_xml_path.write_text(- slide_xml,- encoding="utf-8",- )- transition_only_count += 1-- _update_content_types(extract_dir, note_indices, audio_exts)- if wrote_auto_advance:- set_directory_use_timings(extract_dir)- output_path.parent.mkdir(parents=True, exist_ok=True)- with tempfile.TemporaryDirectory(- prefix="native-enhance-output-",- dir=output_path.parent,- ) as output_tmp:- candidate_path = Path(output_tmp) / output_path.name- _zip_dir(extract_dir, candidate_path)- try:- validate_pptx_transition_package(- candidate_path,- require_use_timings=wrote_auto_advance,- )- except ValueError as exc:- raise RuntimeError(- f"PPTX transition package validation failed: {exc}"- ) from exc- try:- validate_pptx_animation_package(- candidate_path,- require_supported_effects=False,- )- except ValueError as exc:- raise RuntimeError(- f"PPTX animation/timing package validation failed: {exc}"- ) from exc- candidate_path.replace(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=_positive_seconds_arg, default=0.5)- init.add_argument("--narration-padding", type=_non_negative_seconds_arg, 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=_positive_seconds_arg, default=0.5)- plan.add_argument("--narration-padding", type=_non_negative_seconds_arg, 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=_positive_seconds_arg, default=None)- apply.add_argument("--narration-padding", type=_non_negative_seconds_arg, 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/workflows/index.md b/skills/ppt-master/workflows/index.mdindex 1cff0045..29acc13a 100644--- a/skills/ppt-master/workflows/index.md+++ b/skills/ppt-master/workflows/index.md@@ -25,7 +25,6 @@ Registry for standalone workflows referenced by `SKILL.md` and [`routing.md`](./| `verify-charts` | [`verify-charts.md`](./verify-charts.md) | Deck contains data charts that require coordinate calibration | SVG pages exist | Not needed for decks without data charts | Between Step 6 and Step 7 | Verified/fixed chart geometry | Blocks on chart coordinate errors || `customize-animations` | [`customize-animations.md`](./customize-animations.md) | User asks for object-level animation order/effect/timing | Target deck/SVG groups exist | Do not add per-element builds by default | Before or during export configuration | `animations.json` or equivalent validated config | Blocks if target objects cannot be identified || `native-enhance-pptx` | [`native-enhance-pptx.md`](./native-enhance-pptx.md) | Finished PPTX should keep content/layout stable while adding notes/audio/timing/transitions | Source PPTX exists | No SVG regeneration | Workflow Step 1 | Patched PPTX through OOXML | Blocks on source archive/validation failures |-| `native-narration-pptx` | [`native-narration-pptx.md`](./native-narration-pptx.md) | Compatibility reference for the narration subset of native enhancement | Existing PPTX exists | Prefer `native-enhance-pptx` for new requests | Compatibility entry | Narration-enhanced PPTX | Follow compatibility doc || `live-preview` | [`live-preview.md`](./live-preview.md) | User asks for preview, element selection, browser annotations, or re-entry to the editor | Project exists; SVGs required only for annotation apply/export | Do not apply annotations during active generation | Step 6 auto-start or workflow Step 1/2 | Running preview or applied browser edits/annotations | Blocks only when project/SVG target is missing || `visual-review` | [`visual-review.md`](./visual-review.md) | User explicitly asks for per-page visual review or visual rubric | Generated SVG pages exist | Never inferred from deck size/model identity | Between Step 6 and Step 7 | Findings and fixed SVGs | Blocks on selected severe findings if the workflow says to fix || `generate-audio` | [`generate-audio.md`](./generate-audio.md) | User asks for recorded narration, voiceover, audio, or video-style export | Post-processing/export context exists; notes available | Do not call `notes_to_audio.py` directly | After Step 7 | Audio files and optional narration-embedded PPTX | Single backend/voice/settings confirmation |diff --git a/skills/ppt-master/workflows/native-enhance-pptx.md b/skills/ppt-master/workflows/native-enhance-pptx.mdindex 4f06ea00..c3130e4e 100644--- a/skills/ppt-master/workflows/native-enhance-pptx.md+++ b/skills/ppt-master/workflows/native-enhance-pptx.md@@ -28,6 +28,11 @@ This workflow treats a `.pptx` as the artifact to preserve. It archives the sour- Do not run `finalize_svg.py`- Do not run `svg_to_pptx.py`+**Hard rule — public entrypoint**: Route and document all new work through+`native_enhance_pptx.py`. The legacy `native_narration_pptx.py` command remains+only as a thin CLI compatibility shim; it is not a separate workflow. The core+continues to accept the legacy `native_narration_pptx_project.v1` project schema.+**OOXML execution model**:```textdiff --git a/skills/ppt-master/workflows/native-narration-pptx.md b/skills/ppt-master/workflows/native-narration-pptx.mddeleted file mode 100644index 71008466..00000000--- a/skills/ppt-master/workflows/native-narration-pptx.md+++ /dev/null@@ -1,35 +0,0 @@-----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`.