Skip to content

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

fix(workflows): close narration and confirmation false-success gaps

hugohe336f6eeb23d07
diff --git a/skills/ppt-master/references/animations.md b/skills/ppt-master/references/animations.md
index def1a9cb..a7580c2c 100644
--- a/skills/ppt-master/references/animations.md
+++ b/skills/ppt-master/references/animations.md
@@ -357,7 +357,7 @@ Flags: `-a/--animation` selects effect/mode; `--animation-trigger` selects Start
`--animation-config` selects a sidecar; `--no-animations` disables page/object
motion but preserves narration audio and recorded advance timing.
-> Note: `--recorded-narration` rejects `on-click` and `trigger_shape`. When either animation sidecar exists, narrated export selects `narration_animations.json`; canonical `animations.json` without that derived file remains a synchronization error. When both are absent, export creates no sidecar and keeps `fade` / no per-element builds. Pass `--animation-config animations.json` to use the canonical presentation animation, or `--no-animations` to remove both page and object motion explicitly.
+> Note: `--recorded-narration` rejects `on-click` and `trigger_shape`. When either animation sidecar exists, narrated export selects `narration_animations.json`; canonical `animations.json` without that derived file remains a synchronization error. Without sidecars, pass `--inherit-motion-from <base_postflight_report>` for the base deck motion. Pass `--animation-config animations.json` for canonical animation, or `--no-animations` to remove page and object motion.
### 4.1 Slow ambient motion — the page that breathes
diff --git a/skills/ppt-master/scripts/confirm_ui/server.py b/skills/ppt-master/scripts/confirm_ui/server.py
index a2d9a57f..2f447298 100644
--- a/skills/ppt-master/scripts/confirm_ui/server.py
+++ b/skills/ppt-master/scripts/confirm_ui/server.py
@@ -1104,6 +1104,8 @@ def _apply_locked_recommendations(
previous_locks = previous.get(_LOCKED_RECOMMENDATIONS_KEY)
if isinstance(previous_locks, dict):
locked_values.update(previous_locks)
+ for key in _PROACTIVE_EXECUTION_DEFAULTS:
+ locked_values.pop(key, None)
try:
recommendations = _read_json_object(recommendations_file)
@@ -1120,10 +1122,12 @@ def _apply_locked_recommendations(
):
locked_values = {}
for key, field in recommendations.items():
+ if key in _PROACTIVE_EXECUTION_DEFAULTS:
+ continue
if not isinstance(field, dict) or field.get('locked') is not True:
continue
if 'value' in field:
- locked_values[key] = field.get('value') or ''
+ locked_values[key] = field['value']
for key, value in locked_values.items():
result[key] = value
return locked_values
@@ -1579,6 +1583,13 @@ def create_app(
rec_file,
result_file,
)
+ if stage not in {'stage1', 'stage2'}:
+ proactive_result_error = _normalize_proactive_execution_result(
+ result,
+ proactive_defaults,
+ )
+ if proactive_result_error:
+ return jsonify({'error': proactive_result_error}), 400
result.pop('template_reuse_scope', None)
result.pop('template_adherence', None)
# Staged flow: Stage 1 / Stage 2 submits record intermediate choices but do
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index ad953b8f..d672b8a2 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -621,7 +621,7 @@ Behavior:
- `--recorded-narration audio` prepares PowerPoint's "recorded timings and narrations": every slide must have matching `m4a` / `mp3` / `wav` audio, `ffprobe` must read every duration, and `--animation-trigger on-click` is rejected
- `--recorded-narration audio` keeps speaker notes, embeds each matching audio file, and writes slide auto-advance timings from audio duration
- When either animation sidecar exists, narrated export defaults to `<project>/narration_animations.json`; a canonical `animations.json` without that derived file remains a blocking synchronization error
- - When both animation sidecars are absent, narrated export creates no sidecar and keeps the exporter defaults (`fade` page transition, no per-element animation); pass `--animation-config animations.json` for canonical animation, or `--no-animations` only to explicitly remove both object and page-transition motion while retaining narration and slide timings
+ - Without animation sidecars, Generate narration reads base-report deck motion via `--inherit-motion-from`; direct low-level omission keeps legacy `fade` / no object builds. Use `--animation-config animations.json` for canonical animation, or `--no-animations` to remove object/page motion while retaining narration timings
- Non-narrated export keeps the existing optional `<project>/animations.json` default
- Narration timing is merged into the existing slide timing DOM; object-animation rows and the resolved page transition are preserved rather than regenerated
- `--narration-audio-dir audio` is the lower-level embedding path: it embeds whatever files match and allows partial audio coverage
diff --git a/skills/ppt-master/scripts/native_enhance_pptx.py b/skills/ppt-master/scripts/native_enhance_pptx.py
index 6aaa5cbe..42a2e23f 100644
--- a/skills/ppt-master/scripts/native_enhance_pptx.py
+++ b/skills/ppt-master/scripts/native_enhance_pptx.py
@@ -9,7 +9,7 @@ global or per-slide transitions while keeping the stable workflow command.
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 validate <project_path> [--materials {all,notes}]
python3 scripts/native_enhance_pptx.py apply <project_path>
Examples:
diff --git a/skills/ppt-master/scripts/native_enhance_pptx_core.py b/skills/ppt-master/scripts/native_enhance_pptx_core.py
index 26e52960..bc97f6f5 100644
--- a/skills/ppt-master/scripts/native_enhance_pptx_core.py
+++ b/skills/ppt-master/scripts/native_enhance_pptx_core.py
@@ -12,7 +12,7 @@ slide auto-advance timings, and optional global or per-slide 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>
+ python3 scripts/native_enhance_pptx.py validate <project_path> [--materials {all,notes}]
Examples:
python3 scripts/native_enhance_pptx.py init projects/source.pptx --name fire_station
@@ -624,10 +624,19 @@ def _audio_path(audio_dir: Path, index: int) -> Path | None:
f"slide{index}",
]
for stem in stems:
- for ext in NARRATION_EXTENSIONS:
- candidate = audio_dir / f"{stem}{ext}"
- if candidate.exists():
- return candidate
+ matches = [
+ audio_dir / f"{stem}{ext}"
+ for ext in NARRATION_EXTENSIONS
+ if (audio_dir / f"{stem}{ext}").exists()
+ ]
+ if len(matches) > 1:
+ names = ", ".join(path.name for path in matches)
+ raise ValueError(
+ f"ambiguous audio stem {stem!r}: {names}; "
+ "keep exactly one supported extension"
+ )
+ if matches:
+ return matches[0]
return None
@@ -636,11 +645,16 @@ def _collect_material_readiness(
notes_dir: Path,
audio_dir: Path,
modules: set[str],
+ *,
+ required_modules: set[str] | None = None,
) -> MaterialReadiness:
"""Inspect enabled-module inputs once for both validation and application."""
- notes_required = "notes" in modules
- audio_required = "audio" in modules or "timings" in modules
- timings_enabled = "timings" in modules
+ material_modules = modules if required_modules is None else required_modules
+ notes_required = "notes" in material_modules
+ audio_required = (
+ "audio" in material_modules or "timings" in material_modules
+ )
+ timings_enabled = "timings" in material_modules
note_paths: dict[int, Path] = {}
audio_paths: dict[int, Path] = {}
audio_durations: dict[int, float] = {}
@@ -668,7 +682,12 @@ def _collect_material_readiness(
elif notes_required:
invalid_notes[slide.index] = f"{note.name} has no spoken text"
- audio = _audio_path(audio_dir, slide.index)
+ try:
+ audio = _audio_path(audio_dir, slide.index)
+ except ValueError as exc:
+ if audio_required:
+ invalid_audio[slide.index] = str(exc)
+ continue
if audio is None:
if audio_required:
missing_audio.append(slide.index)
@@ -2153,6 +2172,7 @@ def validate_project(args: argparse.Namespace) -> int:
source_pptx, notes_dir, audio_dir, _exports_dir = _project_paths(project_path)
plan = _load_enhancement_plan(project_path)
modules = _enabled_modules(plan)
+ material_modules = {"notes"} if args.materials == "notes" else modules
source_delivery = audit_pptx_delivery(source_pptx)
validation_dir = project_path / "validation"
validation_dir.mkdir(exist_ok=True)
@@ -2163,6 +2183,7 @@ def validate_project(args: argparse.Namespace) -> int:
plan,
modules,
status="failed",
+ material_scope=args.materials,
fatal_delivery_errors=fatal_delivery_messages,
delivery_check=source_delivery,
)
@@ -2229,6 +2250,7 @@ def validate_project(args: argparse.Namespace) -> int:
notes_dir,
audio_dir,
modules,
+ required_modules=material_modules,
)
hard_failure = bool(
source_errors
@@ -2252,9 +2274,12 @@ def validate_project(args: argparse.Namespace) -> int:
plan,
modules,
status=status,
+ material_scope=args.materials,
slide_count=len(slides),
- notes_required="notes" in modules,
- audio_required="audio" in modules or "timings" in modules,
+ notes_required="notes" in material_modules,
+ audio_required=(
+ "audio" in material_modules or "timings" in material_modules
+ ),
plan_errors=plan_errors,
transition_errors=transition_errors,
transition_override_count=transition_slide_count,
@@ -2364,6 +2389,15 @@ def build_parser() -> argparse.ArgumentParser:
help="check source integrity, plan semantics, and material readiness",
)
validate.add_argument("project_path", help="native enhancement project directory")
+ validate.add_argument(
+ "--materials",
+ choices=("all", "notes"),
+ default="all",
+ help=(
+ "required material scope: all enabled modules, or notes only "
+ "before narration audio exists (default: all)"
+ ),
+ )
validate.set_defaults(func=validate_project)
return parser
diff --git a/skills/ppt-master/scripts/notes_to_audio.py b/skills/ppt-master/scripts/notes_to_audio.py
index ec73dd0a..790dc2b3 100644
--- a/skills/ppt-master/scripts/notes_to_audio.py
+++ b/skills/ppt-master/scripts/notes_to_audio.py
@@ -46,6 +46,7 @@ from tts_backends import (
configure_utf8_stdio()
DEFAULT_EDGE_CONCURRENCY = 3
+SUPPORTED_AUDIO_EXTENSIONS = frozenset({".m4a", ".mp3", ".wav"})
@dataclass(frozen=True)
@@ -56,6 +57,12 @@ class AudioBackend:
voice_id: str = ""
+@dataclass(frozen=True)
+class NoteRosterEntry:
+ note_path: Path
+ output_stem: str
+
+
@dataclass(frozen=True)
class AudioJob:
note_path: Path
@@ -90,14 +97,15 @@ def spoken_text(markdown: str) -> str:
def _prepare_audio_jobs(
- note_files: list[Path],
+ note_roster: list[NoteRosterEntry],
output_dir: Path,
extension: str,
) -> list[AudioJob]:
"""Read a complete per-slide notes roster into ordered audio jobs."""
jobs: list[AudioJob] = []
invalid: list[str] = []
- for note_path in note_files:
+ for entry in note_roster:
+ note_path = entry.note_path
if not note_path.is_file():
invalid.append(f"{note_path.name} is missing")
continue
@@ -112,7 +120,7 @@ def _prepare_audio_jobs(
jobs.append(AudioJob(
note_path=note_path,
text=text,
- output_path=output_dir / f"{note_path.stem}{extension}",
+ output_path=output_dir / f"{entry.output_stem}{extension}",
))
if invalid:
raise ValueError(
@@ -121,7 +129,7 @@ def _prepare_audio_jobs(
return jobs
-def _expected_note_files(project: Path) -> list[Path]:
+def _expected_note_roster(project: Path) -> list[NoteRosterEntry]:
"""Resolve the owning route's complete per-slide notes roster."""
notes_dir = project / "notes"
svg_files = sorted((project / "svg_output").glob("*.svg"))
@@ -131,11 +139,14 @@ def _expected_note_files(project: Path) -> list[Path]:
match = re.search(r"slide[_]?(\d+)", path.stem)
if match:
aliases.setdefault(int(match.group(1)), []).append(path)
- note_files: list[Path] = []
+ note_roster: list[NoteRosterEntry] = []
for index, svg_path in enumerate(svg_files, 1):
exact = notes_dir / f"{svg_path.stem}.md"
if exact.exists():
- note_files.append(exact)
+ note_roster.append(NoteRosterEntry(
+ note_path=exact,
+ output_stem=svg_path.stem,
+ ))
continue
matches = aliases.get(index, [])
if len(matches) > 1:
@@ -143,8 +154,13 @@ def _expected_note_files(project: Path) -> list[Path]:
f"multiple notes files match slide {index}: "
+ ", ".join(path.name for path in matches)
)
- note_files.append(matches[0] if matches else exact)
- return note_files
+ note_roster.append(
+ NoteRosterEntry(
+ note_path=matches[0] if matches else exact,
+ output_stem=svg_path.stem,
+ )
+ )
+ return note_roster
slide_index_path = project / "analysis" / "slide_index.json"
if slide_index_path.is_file():
@@ -165,22 +181,44 @@ def _expected_note_files(project: Path) -> list[Path]:
or slide_count != len(slides)
):
raise ValueError("invalid slide index notes roster")
- note_files: list[Path] = []
+ note_roster: list[NoteRosterEntry] = []
for index, slide in enumerate(slides, 1):
note_file = slide.get("note_file") if isinstance(slide, dict) else None
if not isinstance(note_file, str) or Path(note_file).suffix != ".md":
raise ValueError(
f"invalid slide index note_file for slide {index}"
)
- note_files.append(notes_dir / Path(note_file).name)
- return note_files
+ note_name = Path(note_file).name
+ note_roster.append(
+ NoteRosterEntry(
+ note_path=notes_dir / note_name,
+ output_stem=Path(note_name).stem,
+ )
+ )
+ return note_roster
return [
- path for path in sorted(notes_dir.glob("*.md"))
+ NoteRosterEntry(
+ note_path=path,
+ output_stem=path.stem,
+ )
+ for path in sorted(notes_dir.glob("*.md"))
if path.name != "total.md"
]
+def _remove_stale_audio_variants(output_path: Path) -> None:
+ """Remove other supported formats only after the target audio is published."""
+ for candidate in output_path.parent.iterdir():
+ if (
+ candidate.name != output_path.name
+ and candidate.is_file()
+ and candidate.stem == output_path.stem
+ and candidate.suffix.lower() in SUPPORTED_AUDIO_EXTENSIONS
+ ):
+ candidate.unlink()
+
+
async def _generate_edge_jobs(
jobs: list[AudioJob],
subtitle_dir: Path,
@@ -200,7 +238,7 @@ async def _generate_edge_jobs(
job.output_path,
voice=voice,
rate=rate,
- subtitle_path=subtitle_dir / f"{job.note_path.stem}.srt",
+ subtitle_path=subtitle_dir / f"{job.output_path.stem}.srt",
subtitle_max_chars=subtitle_max_chars,
)
@@ -450,11 +488,11 @@ def main() -> int:
subtitle_dir = notes_dir / "subtitles"
try:
- note_files = _expected_note_files(project)
- if not note_files:
+ note_roster = _expected_note_roster(project)
+ if not note_roster:
raise ValueError(f"no per-slide notes found in {notes_dir}")
jobs = _prepare_audio_jobs(
- note_files,
+ note_roster,
output_dir,
backend.extension,
)
@@ -487,7 +525,7 @@ def main() -> int:
failed = False
for job, result in zip(jobs, results):
- subtitle_path = subtitle_dir / f"{job.note_path.stem}.srt"
+ subtitle_path = subtitle_dir / f"{job.output_path.stem}.srt"
if result is not None:
print(
f"error: failed to generate {job.output_path}: {result}",
@@ -495,6 +533,16 @@ def main() -> int:
)
failed = True
continue
+ try:
+ _remove_stale_audio_variants(job.output_path)
+ except OSError as exc:
+ print(
+ f"error: failed to remove stale audio for "
+ f"{job.output_path.stem}: {exc}",
+ file=sys.stderr,
+ )
+ failed = True
+ continue
generated += 1
print(f"[OK] {job.output_path}")
print(f" {subtitle_path}")
@@ -563,6 +611,7 @@ def main() -> int:
language_hint=args.cosyvoice_language_hint,
base_url=args.cosyvoice_base_url,
)
+ _remove_stale_audio_variants(output_path)
except Exception as exc:
print(f"error: failed to generate {output_path}: {exc}", file=sys.stderr)
return 1
@@ -571,11 +620,11 @@ def main() -> int:
if backend.provider == "edge":
print(
- f"[Done] Generated {generated}/{len(note_files)} audio/SRT pair(s): "
+ f"[Done] Generated {generated}/{len(note_roster)} audio/SRT pair(s): "
f"{output_dir} + {subtitle_dir}"
)
else:
- print(f"[Done] Generated {generated}/{len(note_files)} audio file(s): {output_dir}")
+ print(f"[Done] Generated {generated}/{len(note_roster)} audio file(s): {output_dir}")
return 0
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
index 8d60d992..661f3d9e 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/cli.py
@@ -337,6 +337,7 @@ def _write_postflight_report(
pptx_structure: str,
backup_path: Path | None,
conversion_trace_path: Path | None,
+ deck_motion: dict[str, object],
) -> _PostflightReceipt:
"""Write the unified package/resource audit for a successful PPTX."""
try:
@@ -443,6 +444,7 @@ def _write_postflight_report(
},
'quality': quality,
'resources': source_audit,
+ 'deck_motion': deck_motion,
'backup_path': str(backup_path.resolve()) if backup_path else None,
'conversion_trace_path': (
str(conversion_trace_path.resolve())
@@ -473,6 +475,58 @@ def _write_postflight_report(
)
+def _load_deck_motion_handoff(
+ project_path: Path,
+ report_arg: str,
+ svg_files: list[Path],
+) -> dict[str, object]:
+ """Load source-bound deck motion from a successful base export report."""
+ report_path = Path(report_arg).expanduser()
+ if not report_path.is_absolute() and not report_path.is_file():
+ report_path = project_path / report_path
+ try:
+ report = json.loads(report_path.read_text(encoding='utf-8'))
+ except FileNotFoundError as exc:
+ raise ValueError(
+ f'deck-motion handoff report does not exist: {report_path}'
+ ) from exc
+ except (OSError, json.JSONDecodeError) as exc:
+ raise ValueError(
+ f'deck-motion handoff report is unreadable: {report_path}: {exc}'
+ ) from exc
+ if not isinstance(report, dict):
+ raise ValueError('deck-motion handoff report must be a JSON object')
+ if report.get('schema') != 'ppt-master.pptx-postflight-report.v1':
+ raise ValueError(
+ 'deck-motion handoff requires a ppt-master postflight report'
+ )
+ if report.get('status') not in {'passed', 'passed-with-warnings'}:
+ raise ValueError('deck-motion handoff report is not a successful export')
+ source = _as_dict(report.get('source'))
+ if source.get('fingerprint') != _svg_source_fingerprint(svg_files):
+ raise ValueError(
+ 'deck-motion handoff does not match the current svg_output; '
+ 'run the base export again'
+ )
+ motion = report.get('deck_motion')
+ if not isinstance(motion, dict):
+ raise ValueError(
+ 'deck-motion handoff is missing from the base export report; '
+ 'run the base export again'
+ )
+ if motion.get('narration_timings') is True:
+ raise ValueError(
+ 'deck-motion handoff must reference a base non-narrated export report'
+ )
+ if not isinstance(motion.get('transition'), dict):
+ raise ValueError('deck-motion handoff transition must be an object')
+ if not isinstance(motion.get('animation'), dict):
+ raise ValueError('deck-motion handoff animation must be an object')
+ if not isinstance(motion.get('cli_overrides'), dict):
+ raise ValueError('deck-motion handoff cli_overrides must be an object')
+ return motion
+
+
def _print_postflight_receipt(receipt: _PostflightReceipt) -> None:
"""Print the compact completion evidence; keep the full JSON on disk."""
print(
@@ -776,13 +830,13 @@ Speaker notes (enabled by default):
- Use --no-notes to disable
Recorded narration:
- %(prog)s examples/ppt169_demo --recorded-narration audio
+ %(prog)s examples/ppt169_demo --recorded-narration audio \\
+ --inherit-motion-from validation/<base>.report.json
- Keeps speaker notes when enabled
- Prepares PowerPoint recorded timings and narrations
- Requires one m4a/mp3/wav file per slide
- Uses narration_animations.json when animation sidecars exist
- - With no animation sidecars, keeps the default fade transition and no
- per-element builds
+ - Inherits source-bound deck motion from the base postflight report
- Use --animation-config animations.json for the canonical animation
- Use --no-animations for narration and timings without animation motion
- Embeds per-slide audio matched by SVG filename / slide number
@@ -951,8 +1005,8 @@ Recorded narration:
help=(
'Per-slide/per-object animation config. Recorded narration uses '
'<project>/narration_animations.json when an animation sidecar exists, '
- 'or keeps exporter defaults when neither sidecar exists. Other exports '
- 'default to <project>/animations.json when present.'
+ 'or may inherit base postflight motion with --inherit-motion-from. '
+ 'Other exports default to <project>/animations.json when present.'
),
)
animation_source.add_argument(
@@ -977,6 +1031,16 @@ Recorded narration:
'(<project>_<ts>_narrated.pptx) to tell them apart from silent exports.')
parser.add_argument('--narration-padding', type=non_negative_float, default=0.5,
help='Seconds to add after each narration before auto-advance (default: 0.5)')
+ parser.add_argument(
+ '--inherit-motion-from',
+ type=str,
+ default=None,
+ metavar='BASE_POSTFLIGHT_REPORT',
+ help=(
+ 'For recorded narration, inherit source-bound deck-wide transition, '
+ 'animation, and advance settings from a successful base export report'
+ ),
+ )
raw_argv = list(argv) if argv is not None else sys.argv[1:]
legacy_native_objects = '--native-objects' in raw_argv
@@ -993,6 +1057,18 @@ Recorded narration:
file=sys.stderr,
)
return 1
+ if args.inherit_motion_from and not args.recorded_narration:
+ print(
+ 'Error: --inherit-motion-from requires --recorded-narration',
+ file=sys.stderr,
+ )
+ return 1
+ if args.inherit_motion_from and args.no_animations:
+ print(
+ 'Error: --inherit-motion-from cannot be combined with --no-animations',
+ file=sys.stderr,
+ )
+ return 1
if args.quick_test:
conflicts: list[str] = []
@@ -1320,7 +1396,14 @@ Recorded narration:
file=sys.stderr,
)
return 1
- narration_audio = find_narration_files(narration_audio_dir, ref_files)
+ try:
+ narration_audio = find_narration_files(
+ narration_audio_dir,
+ ref_files,
+ )
+ except ValueError as exc:
+ print(f"Error: {exc}", file=sys.stderr)
+ return 1
if verbose:
print(f" Narration audio directory: {narration_audio_dir}")
print(f" Narration audio matched: {len(narration_audio)}/{len(ref_files)} slide(s)")
@@ -1462,9 +1545,26 @@ Recorded narration:
elif args.no_animations and verbose:
print(" Animations: disabled")
+ inherited_motion: dict[str, object] = {}
+ if args.inherit_motion_from:
+ try:
+ inherited_motion = _load_deck_motion_handoff(
+ project_path,
+ args.inherit_motion_from,
+ native_files,
+ )
+ except ValueError as exc:
+ print(f"Error: {exc}", file=sys.stderr)
+ return 1
+ if verbose:
+ print(f" Deck motion handoff: {args.inherit_motion_from}")
+
defaults = animation_config.get('defaults', {}) if animation_config else {}
transition_defaults = _as_dict(defaults.get('transition')) if isinstance(defaults, dict) else {}
animation_defaults = _as_dict(defaults.get('animation')) if isinstance(defaults, dict) else {}
+ inherited_transition = _as_dict(inherited_motion.get('transition'))
+ inherited_animation = _as_dict(inherited_motion.get('animation'))
+ inherited_overrides = _as_dict(inherited_motion.get('cli_overrides'))
transition_arg = args.transition
transition_effect = (
@@ -1473,7 +1573,11 @@ Recorded narration:
else (
transition_arg
if transition_arg is not None
- else transition_defaults.get('effect', 'fade')
+ else (
+ inherited_transition['effect']
+ if 'effect' in inherited_transition
+ else transition_defaults.get('effect', 'fade')
+ )
)
)
try:
@@ -1483,7 +1587,11 @@ Recorded narration:
(
None
if transition_arg is not None or args.no_animations
- else transition_defaults.get('effect_options')
+ else (
+ inherited_transition.get('effect_options')
+ if 'effect' in inherited_transition
+ else transition_defaults.get('effect_options')
+ )
),
)
)
@@ -1491,7 +1599,11 @@ Recorded narration:
(
args.transition_duration
if args.transition_duration is not None
- else transition_defaults.get('duration', 0.4)
+ else (
+ inherited_transition['duration']
+ if 'duration' in inherited_transition
+ else transition_defaults.get('duration', 0.4)
+ )
),
"transition duration",
allow_zero=transition is None,
@@ -1499,7 +1611,11 @@ Recorded narration:
auto_advance = (
args.auto_advance
if args.auto_advance is not None
- else transition_defaults.get('auto_advance')
+ else (
+ inherited_transition['auto_advance']
+ if 'auto_advance' in inherited_transition
+ else transition_defaults.get('auto_advance')
+ )
)
if auto_advance is not None:
auto_advance = validate_seconds(
@@ -1521,7 +1637,11 @@ Recorded narration:
# Per-element object motion is opt-in by default: unsolicited
# auto-firing builds read as the "AI deck" tell. Page transitions
# stay on; enable objects with -a or animations.json.
- else animation_defaults.get('effect', 'none')
+ else (
+ inherited_animation['effect_request']
+ if 'effect_request' in inherited_animation
+ else animation_defaults.get('effect', 'none')
+ )
)
)
normalized_animation = normalize_animation_effect(animation_effect)
@@ -1537,7 +1657,11 @@ Recorded narration:
(
args.animation_duration
if args.animation_duration is not None
- else animation_defaults.get('duration', 0.4)
+ else (
+ inherited_animation['duration']
+ if 'duration' in inherited_animation
+ else animation_defaults.get('duration', 0.4)
+ )
),
"animation duration",
allow_zero=False,
@@ -1551,7 +1675,11 @@ Recorded narration:
(
args.animation_stagger
if args.animation_stagger is not None
- else animation_defaults.get('stagger', 0.5)
+ else (
+ inherited_animation['stagger']
+ if 'stagger' in inherited_animation
+ else animation_defaults.get('stagger', 0.5)
+ )
),
"animation stagger",
allow_zero=True,
@@ -1564,20 +1692,63 @@ Recorded narration:
animation_trigger = normalize_animation_trigger(
args.animation_trigger
if args.animation_trigger is not None
- else animation_defaults.get('trigger', 'after-previous')
+ else (
+ inherited_animation['trigger']
+ if 'trigger' in inherited_animation
+ else animation_defaults.get('trigger', 'after-previous')
+ )
)
except ValueError as exc:
print(f"Error: {exc}", file=sys.stderr)
return 1
animation_cli_overrides = {
- 'transition': args.transition is not None,
- 'transition_duration': args.transition_duration is not None,
- 'auto_advance': args.auto_advance is not None,
- 'animation': args.animation is not None,
- 'animation_duration': args.animation_duration is not None,
- 'animation_stagger': args.animation_stagger is not None,
- 'animation_trigger': args.animation_trigger is not None,
+ 'transition': (
+ args.transition is not None
+ or inherited_overrides.get('transition') is True
+ ),
+ 'transition_duration': (
+ args.transition_duration is not None
+ or inherited_overrides.get('transition_duration') is True
+ ),
+ 'auto_advance': (
+ args.auto_advance is not None
+ or inherited_overrides.get('auto_advance') is True
+ ),
+ 'animation': (
+ args.animation is not None
+ or inherited_overrides.get('animation') is True
+ ),
+ 'animation_duration': (
+ args.animation_duration is not None
+ or inherited_overrides.get('animation_duration') is True
+ ),
+ 'animation_stagger': (
+ args.animation_stagger is not None
+ or inherited_overrides.get('animation_stagger') is True
+ ),
+ 'animation_trigger': (
+ args.animation_trigger is not None
+ or inherited_overrides.get('animation_trigger') is True
+ ),
+ }
+
+ deck_motion: dict[str, object] = {
+ 'transition': {
+ 'effect': transition,
+ 'effect_options': transition_effect_options,
+ 'duration': transition_duration,
+ 'auto_advance': auto_advance,
+ },
+ 'animation': {
+ 'effect': normalized_animation or 'none',
+ 'effect_request': animation,
+ 'duration': animation_duration,
+ 'stagger': animation_stagger,
+ 'trigger': animation_trigger,
+ },
+ 'cli_overrides': animation_cli_overrides,
+ 'narration_timings': use_narration_timings,
}
if args.recorded_narration:
@@ -1762,6 +1933,7 @@ Recorded narration:
pptx_structure=pptx_structure,
backup_path=backup_path,
conversion_trace_path=conversion_trace_path,
+ deck_motion=deck_motion,
)
except PptxPostflightValidationError as exc:
print(
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/narration.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/narration.py
index 29c010b9..e9e0503f 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/narration.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/narration.py
@@ -92,27 +92,33 @@ def find_narration_files(audio_dir: Path, svg_files: list[Path]) -> dict[str, Pa
path for path in sorted(audio_dir.iterdir())
if path.is_file() and path.suffix.lower() in NARRATION_EXTENSIONS
]
- exact = {path.stem: path for path in audio_files}
- normalized: dict[str, Path] = {}
- numbered: dict[int, Path] = {}
+ exact: dict[str, list[Path]] = {}
+ normalized: dict[str, list[Path]] = {}
+ numbered: dict[int, list[Path]] = {}
for path in audio_files:
- normalized.setdefault(_normalize_title(path.stem), path)
+ exact.setdefault(path.stem, []).append(path)
+ normalized.setdefault(_normalize_title(path.stem), []).append(path)
number = _leading_number(path.stem)
if number is not None:
- numbered.setdefault(number, path)
+ numbered.setdefault(number, []).append(path)
matched: dict[str, Path] = {}
for index, svg in enumerate(svg_files, 1):
stem = svg.stem
- if stem in exact:
- matched[stem] = exact[stem]
+ candidates = exact.get(stem)
+ if not candidates:
+ candidates = normalized.get(_normalize_title(stem))
+ if not candidates:
+ candidates = numbered.get(index)
+ if not candidates:
continue
- norm = _normalize_title(stem)
- if norm in normalized:
- matched[stem] = normalized[norm]
- continue
- if index in numbered:
- matched[stem] = numbered[index]
+ if len(candidates) > 1:
+ names = ", ".join(path.name for path in candidates)
+ raise ValueError(
+ f"multiple narration audio files match slide {stem!r}: "
+ f"{names}; keep exactly one supported file for this slide"
+ )
+ matched[stem] = candidates[0]
return matched
diff --git a/skills/ppt-master/scripts/tts_backends/backend_common.py b/skills/ppt-master/scripts/tts_backends/backend_common.py
index cf012d8c..190d684a 100644
--- a/skills/ppt-master/scripts/tts_backends/backend_common.py
+++ b/skills/ppt-master/scripts/tts_backends/backend_common.py
@@ -4,6 +4,7 @@ from __future__ import annotations
import json
import os
+import tempfile
from pathlib import Path
from urllib import error, request
@@ -57,7 +58,34 @@ def get_bytes(url: str, *, timeout: int = 180) -> bytes:
def download_audio(url: str, output_path: Path) -> None:
- output_path.write_bytes(get_bytes(url))
+ publish_audio_bytes(get_bytes(url), output_path)
+
+
+def publish_audio_bytes(audio: bytes, output_path: Path) -> None:
+ """Publish non-empty provider audio without exposing a partial target."""
+ if not audio:
+ raise RuntimeError("TTS provider returned empty audio data")
+
+ output_path.parent.mkdir(parents=True, exist_ok=True)
+ descriptor, raw_path = tempfile.mkstemp(
+ prefix=f".{output_path.name}.",
+ suffix=".tmp",
+ dir=output_path.parent,
+ )
+ staged_path = Path(raw_path)
+ try:
+ with os.fdopen(descriptor, "wb") as stream:
+ descriptor = -1
+ stream.write(audio)
+ stream.flush()
+ os.fsync(stream.fileno())
+ if staged_path.stat().st_size <= 0:
+ raise RuntimeError("TTS provider returned empty audio data")
+ os.replace(staged_path, output_path)
+ finally:
+ if descriptor >= 0:
+ os.close(descriptor)
+ staged_path.unlink(missing_ok=True)
def extension_from_format(audio_format: str) -> str:
diff --git a/skills/ppt-master/scripts/tts_backends/backend_elevenlabs.py b/skills/ppt-master/scripts/tts_backends/backend_elevenlabs.py
index f0d61343..111c7e62 100644
--- a/skills/ppt-master/scripts/tts_backends/backend_elevenlabs.py
+++ b/skills/ppt-master/scripts/tts_backends/backend_elevenlabs.py
@@ -6,7 +6,7 @@ import json
from pathlib import Path
from urllib import error, request
-from tts_backends.backend_common import read_api_key
+from tts_backends.backend_common import publish_audio_bytes, read_api_key
API_BASE = "https://api.elevenlabs.io/v1"
@@ -77,7 +77,7 @@ def generate(
)
try:
with request.urlopen(req, timeout=120) as response:
- output_path.write_bytes(response.read())
+ publish_audio_bytes(response.read(), output_path)
except error.HTTPError as exc:
raise RuntimeError(_read_http_error(exc)) from exc
except error.URLError as exc:
diff --git a/skills/ppt-master/scripts/tts_backends/backend_minimax.py b/skills/ppt-master/scripts/tts_backends/backend_minimax.py
index 6c4f1350..99d2b6d2 100644
--- a/skills/ppt-master/scripts/tts_backends/backend_minimax.py
+++ b/skills/ppt-master/scripts/tts_backends/backend_minimax.py
@@ -6,7 +6,12 @@ import binascii
import os
from pathlib import Path
-from tts_backends.backend_common import extension_from_format, post_json, read_api_key
+from tts_backends.backend_common import (
+ extension_from_format,
+ post_json,
+ publish_audio_bytes,
+ read_api_key,
+)
DEFAULT_ENDPOINT = "https://api.minimaxi.com/v1/t2a_v2"
@@ -82,9 +87,10 @@ def generate(
if not audio_hex:
raise RuntimeError(f"MiniMax response missing audio data: {data}")
try:
- output_path.write_bytes(binascii.unhexlify(audio_hex))
+ audio = binascii.unhexlify(audio_hex)
except (binascii.Error, ValueError) as exc:
raise RuntimeError("MiniMax response audio is not valid hex data") from exc
+ publish_audio_bytes(audio, output_path)
def print_voices() -> None:
diff --git a/skills/ppt-master/workflows/generate-pptx.md b/skills/ppt-master/workflows/generate-pptx.md
index ad1fc2f5..c2840505 100644
--- a/skills/ppt-master/workflows/generate-pptx.md
+++ b/skills/ppt-master/workflows/generate-pptx.md
@@ -570,7 +570,7 @@ existing sidecar, preserve the normal `fade` / `none` defaults.
- `validation/<project_name>_<timestamp>.report.json` with `passed` or `passed-with-warnings` package/resource postflight status
- `validation/<project_name>_<timestamp>.trace.json` when bare `--conversion-trace` is enabled; an explicit `--conversion-trace <path>` uses that destination instead
-The command prints a compact `[POSTFLIGHT]` receipt containing `status`, `quality_gate`, Slide count, warning-category counts, and the PPTX/report paths. Use that receipt as completion evidence and disclose its material warnings to the user. Do not open or `cat` the complete report on routine success; use targeted field extraction only for failure investigation, an explicit audit request, or information absent from the receipt. A failed report or missing PPTX is not success.
+The compact `[POSTFLIGHT]` receipt prints `status`, `quality_gate`, Slide count, warning-category counts, and PPTX/report paths. Disclose material warnings. Do not open or `cat` the complete report on routine success; use targeted field extraction only for failure investigation, an explicit audit request, or information absent from the receipt. A failed report or missing PPTX is not success. Retain its report path for later Generate narration (`deck_motion` handoff).
## ✅ Generate PPTX Complete
diff --git a/skills/ppt-master/workflows/native-enhance-pptx.md b/skills/ppt-master/workflows/native-enhance-pptx.md
index ca194f6f..d2f8c3ed 100644
--- a/skills/ppt-master/workflows/native-enhance-pptx.md
+++ b/skills/ppt-master/workflows/native-enhance-pptx.md
@@ -248,10 +248,12 @@ Write:
Run coverage check:
```bash
-python3 skills/ppt-master/scripts/native_enhance_pptx.py validate "<project>"
+python3 skills/ppt-master/scripts/native_enhance_pptx.py validate "<project>" --materials notes
```
-> Note: missing, empty, unreadable, or undecodable requested material returns exit code `2`. Package, source-drift, plan/module, or duplicate native-enhance narration-carrier errors return `1`.
+> Note: This keeps source/plan/transition/carrier checks but does not require
+> audio. Missing/invalid notes return `2`; structural/semantic errors return
+> `1`. Step 8 runs full validation after audio.
---
diff --git a/skills/ppt-master/workflows/stages/generate-audio.md b/skills/ppt-master/workflows/stages/generate-audio.md
index 48d5941f..26fedae6 100644
--- a/skills/ppt-master/workflows/stages/generate-audio.md
+++ b/skills/ppt-master/workflows/stages/generate-audio.md
@@ -183,15 +183,16 @@ python3 skills/ppt-master/scripts/narration_sync.py animations <project_path> \
--narration-padding 0.5 --force
# 2B. Re-export with audio embedded
-# When both animation sidecars are absent, skip 2A: this command keeps the
-# normal fade page transition and no per-element builds.
+# Use the base export's [REPORT] path to preserve source-bound deck motion.
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
- --no-merge --recorded-narration audio --narration-padding 0.5
+ --no-merge --recorded-narration audio --narration-padding 0.5 \
+ --inherit-motion-from "<base_postflight_report>"
# Optional: use the canonical presentation animation instead
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
--no-merge --recorded-narration audio --narration-padding 0.5 \
- --animation-config animations.json
+ --animation-config animations.json \
+ --inherit-motion-from "<base_postflight_report>"
# Optional: export narration with no object or page-transition animation
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> \
@@ -234,13 +235,11 @@ The edge command writes each MP3 and its internal page SRT from the same `edge-t
|---|---|
| `narration_animations.json` exists | Use it by default |
| Only canonical `animations.json` exists | Block until narration synchronization creates the derived sidecar |
-| Both are absent | Create no sidecar; keep the exporter defaults (`fade` page transition, `none` per-element animation) |
+| Both are absent | Create no sidecar; inherit the base report's deck motion |
-Pass `--animation-config animations.json` to keep the canonical presentation
-animation, or `--no-animations` only when the user explicitly wants to disable
-both object animations and page-transition motion while preserving narration
-audio and recorded slide-advance timings. Non-narrated export keeps its
-existing optional `<project_path>/animations.json` default.
+Except for explicit `--no-animations`, every Generate narration re-export
+passes the exact base report through `--inherit-motion-from`; missing, stale,
+or narrated reports block. Audio duration plus padding owns final slide advance.
When canonical custom animation is synchronized,
`<project_path>/narration_timing.json` is the explicit semantic mapping for