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

feat(narration): delay narration until transitions settle

hugohe3e47dcfb7b697
diff --git a/skills/ppt-master/scripts/narration_sync.py b/skills/ppt-master/scripts/narration_sync.py
index a5c53fbd..b32b246e 100644
--- a/skills/ppt-master/scripts/narration_sync.py
+++ b/skills/ppt-master/scripts/narration_sync.py
@@ -57,7 +57,12 @@ from pptx_animations import ( # noqa: E402
normalize_animation_effect,
normalize_animation_trigger,
)
-from pptx_transitions import read_slide_transition_xml # noqa: E402
+from pptx_transitions import ( # noqa: E402
+ DEFAULT_TRANSITION_DURATION,
+ normalize_transition_effect_request,
+ read_slide_transition_xml,
+ validate_seconds,
+)
from svg_to_pptx.animation_config import ( # noqa: E402
animation_group_effect_entries,
scan_project_targets,
@@ -66,8 +71,11 @@ from svg_to_pptx.animation_config import ( # noqa: E402
validate_transition_config,
)
from svg_to_pptx.pptx_package.narration import ( # noqa: E402
+ DEFAULT_NARRATION_START_FLOOR,
NARRATION_EXTENSIONS,
+ narration_lead_in_seconds,
probe_audio_duration,
+ read_narration_start_delay_xml,
)
configure_utf8_stdio()
@@ -157,6 +165,15 @@ class SubtitleMergeResult:
minimum_video_correlation: float | None = None
+@dataclass(frozen=True)
+class PowerPointTiming:
+ """One slide's transition, narration, and advance timing in milliseconds."""
+
+ transition_ms: int
+ narration_delay_ms: int
+ advance_ms: int
+
+
def _timestamp_to_ms(value: str) -> int:
hours_text, minutes_text, remainder = value.split(":")
seconds_text, milliseconds_text = remainder.split(",")
@@ -301,9 +318,20 @@ def _subtitle_fingerprint(slide_names: list[str], subtitle_dir: Path) -> str:
return digest.hexdigest()
+def _finite_non_negative_seconds(value: object, field: str) -> float:
+ if (
+ isinstance(value, bool)
+ or not isinstance(value, (int, float))
+ or not math.isfinite(float(value))
+ or value < 0
+ ):
+ raise ValueError(f'{field} must be a finite non-negative number')
+ return float(value)
+
+
def _load_timing_plan(
path: Path,
-) -> tuple[str, float, dict[str, list[TimingPlanEntry]]]:
+) -> tuple[str, float, float | None, dict[str, list[TimingPlanEntry]]]:
raw = json.loads(path.read_text(encoding="utf-8"))
if not isinstance(raw, dict):
raise ValueError(f"Narration timing plan must be a JSON object: {path}")
@@ -311,6 +339,7 @@ def _load_timing_plan(
"version",
"srt_sha256",
"narration_padding",
+ "narration_start_floor",
"slides",
}
if unknown_top:
@@ -331,17 +360,18 @@ def _load_timing_plan(
'Narration timing plan field "srt_sha256" must be a lowercase '
"SHA-256 digest of the ordered page-local SRT files"
)
- narration_padding = raw.get("narration_padding")
- if (
- isinstance(narration_padding, bool)
- or not isinstance(narration_padding, (int, float))
- or not math.isfinite(float(narration_padding))
- or narration_padding < 0
- ):
- raise ValueError(
- 'Narration timing plan field "narration_padding" must be a '
- "finite non-negative number"
+ narration_padding = _finite_non_negative_seconds(
+ raw.get("narration_padding"),
+ 'Narration timing plan field "narration_padding"',
+ )
+ narration_start_floor = (
+ _finite_non_negative_seconds(
+ raw["narration_start_floor"],
+ 'Narration timing plan field "narration_start_floor"',
)
+ if "narration_start_floor" in raw
+ else None
+ )
slides = raw.get("slides")
if not isinstance(slides, dict):
raise ValueError('Narration timing plan field "slides" must be an object')
@@ -397,7 +427,7 @@ def _load_timing_plan(
entries.append(TimingPlanEntry(group_id, cue_number))
seen_groups.add(group_id)
result[slide_name] = entries
- return srt_sha256, float(narration_padding), result
+ return srt_sha256, narration_padding, narration_start_floor, result
def _load_canonical_animation_config(path: Path) -> dict[str, Any]:
@@ -497,6 +527,58 @@ def _animation_scope(
return value
+def _transition_scope(
+ scope: dict[str, Any],
+ *,
+ label: str,
+) -> dict[str, Any]:
+ value = scope.get("transition", {})
+ if not isinstance(value, dict):
+ raise ValueError(f'{label} field "transition" must be an object')
+ return value
+
+
+def _effective_transition_duration_ms(
+ config: dict[str, Any],
+ slide_cfg: dict[str, Any],
+) -> int:
+ """Resolve the destination slide's effective transition duration."""
+ defaults = config.get("defaults", {})
+ if not isinstance(defaults, dict):
+ raise ValueError('Canonical animations.json field "defaults" must be an object')
+ default_transition = _transition_scope(
+ defaults,
+ label="Canonical animations.json defaults",
+ )
+ default_effect, _default_options = normalize_transition_effect_request(
+ default_transition.get("effect", "fade"),
+ default_transition.get("effect_options"),
+ )
+ default_duration = validate_seconds(
+ default_transition.get("duration", DEFAULT_TRANSITION_DURATION),
+ "canonical transition duration",
+ allow_zero=default_effect is None,
+ )
+
+ slide_transition = _transition_scope(
+ slide_cfg,
+ label="Canonical animations.json slide",
+ )
+ if "effect" in slide_transition:
+ effect, _effect_options = normalize_transition_effect_request(
+ slide_transition["effect"],
+ slide_transition.get("effect_options"),
+ )
+ else:
+ effect = default_effect
+ duration = validate_seconds(
+ slide_transition.get("duration", default_duration),
+ "canonical slide transition duration",
+ allow_zero=effect is None,
+ )
+ return 0 if effect is None else round(duration * 1000)
+
+
def _effective_slide_animation(
config: dict[str, Any],
slide_cfg: dict[str, Any],
@@ -963,10 +1045,17 @@ def rebuild_animations(
output_path: Path,
narration_padding: float,
force: bool,
+ narration_start_floor: float = DEFAULT_NARRATION_START_FLOOR,
) -> AnimationBuildResult:
"""Derive narration timing without modifying the canonical animation file."""
- if not math.isfinite(narration_padding) or narration_padding < 0:
- raise ValueError("Narration padding must be finite and non-negative")
+ narration_padding = _finite_non_negative_seconds(
+ narration_padding,
+ "Narration padding",
+ )
+ narration_start_floor = _finite_non_negative_seconds(
+ narration_start_floor,
+ "Narration start floor",
+ )
_reject_output_alias(
output_path,
[canonical_path, plan_path],
@@ -983,9 +1072,12 @@ def rebuild_animations(
timing_plan: dict[str, list[TimingPlanEntry]] | None = None
if plan_path.is_file():
- expected_srt_sha256, planned_padding, loaded_plan = _load_timing_plan(
- plan_path
- )
+ (
+ expected_srt_sha256,
+ planned_padding,
+ planned_start_floor,
+ loaded_plan,
+ ) = _load_timing_plan(plan_path)
if not math.isclose(
narration_padding,
planned_padding,
@@ -996,6 +1088,16 @@ def rebuild_animations(
"Narration padding differs from the timing plan: "
f"plan={planned_padding}, command={narration_padding}"
)
+ if planned_start_floor is not None and not math.isclose(
+ narration_start_floor,
+ planned_start_floor,
+ rel_tol=0,
+ abs_tol=1e-9,
+ ):
+ raise ValueError(
+ "Narration start floor differs from the timing plan: "
+ f"plan={planned_start_floor}, command={narration_start_floor}"
+ )
current_srt_sha256 = _subtitle_fingerprint(slide_names, subtitle_dir)
if current_srt_sha256 != expected_srt_sha256:
raise ValueError(
@@ -1049,6 +1151,17 @@ def rebuild_animations(
f'Derived animation slide "{slide_name}" must be an object'
)
settings = _effective_slide_animation(canonical, canonical_slide)
+ transition_duration_ms = _effective_transition_duration_ms(
+ canonical,
+ canonical_slide,
+ )
+ narration_lead_in_ms = round(
+ narration_lead_in_seconds(
+ transition_duration_ms / 1000,
+ start_floor=narration_start_floor,
+ )
+ * 1000
+ )
plan_entries = timing_plan.get(slide_name) if timing_plan else None
states, used_svg = _resolve_animation_groups(
project_path,
@@ -1122,14 +1235,18 @@ def rebuild_animations(
else:
anchored_count += 1
referenced_cues.add(cue_number)
- desired_start_ms = cues[cue_number - 1].start_ms
+ cue_start_ms = cues[cue_number - 1].start_ms
+ desired_start_ms = (
+ narration_lead_in_ms + cue_start_ms
+ )
actual_start_ms = max(desired_start_ms, previous_end_ms)
delay_ms = actual_start_ms - previous_end_ms
drift_ms = actual_start_ms - desired_start_ms
if drift_ms > 500:
drift_warnings.append(
f"{slide_name}/{state.group_id}: cue {cue_number} "
- f"starts at {_seconds_from_ms(desired_start_ms):.3f}s, "
+ f"starts at {_seconds_from_ms(cue_start_ms):.3f}s after "
+ f"a {_seconds_from_ms(narration_lead_in_ms):.3f}s lead-in; "
f"animation starts at {_seconds_from_ms(actual_start_ms):.3f}s "
f"(after-previous drift {_seconds_from_ms(drift_ms):.3f}s)"
)
@@ -1159,7 +1276,14 @@ def rebuild_animations(
ignored_cue_count += len(cues) - len(referenced_cues)
- advance_ms = int((audio_duration + narration_padding) * 1000)
+ advance_ms = round(
+ (
+ audio_duration
+ + narration_padding
+ + narration_lead_in_ms / 1000
+ )
+ * 1000
+ )
if previous_end_ms > advance_ms:
raise ValueError(
f'Animations on slide "{slide_name}" end at '
@@ -1270,8 +1394,11 @@ def _presentation_slide_members(package: zipfile.ZipFile) -> list[str]:
return members
-def _read_powerpoint_timings(pptx_path: Path, slide_count: int) -> list[tuple[int, int]]:
- timings: list[tuple[int, int]] = []
+def _read_powerpoint_timings(
+ pptx_path: Path,
+ slide_count: int,
+) -> list[PowerPointTiming]:
+ timings: list[PowerPointTiming] = []
with zipfile.ZipFile(pptx_path) as package:
slide_members = _presentation_slide_members(package)
if len(slide_members) != slide_count:
@@ -1280,7 +1407,8 @@ def _read_powerpoint_timings(pptx_path: Path, slide_count: int) -> list[tuple[in
f"but the project has {slide_count}"
)
for slide_index, member in enumerate(slide_members, 1):
- summary = read_slide_transition_xml(package.read(member))
+ slide_xml = package.read(member)
+ summary = read_slide_transition_xml(slide_xml)
if summary.logical_count != 1:
raise ValueError(
f"Narrated PPTX slide {slide_index} has "
@@ -1292,24 +1420,45 @@ def _read_powerpoint_timings(pptx_path: Path, slide_count: int) -> list[tuple[in
f"Narrated PPTX slide {slide_index} has no recorded advance time"
)
transition_ms = summary.duration_ms or 0
- if advance_ms <= 0 or transition_ms < 0:
+ narration_delay_ms = read_narration_start_delay_xml(
+ slide_xml.decode("utf-8")
+ )
+ if (
+ advance_ms <= 0
+ or transition_ms < 0
+ or narration_delay_ms < 0
+ or narration_delay_ms >= advance_ms
+ ):
raise ValueError(
f"Narrated PPTX slide {slide_index} has invalid timing values"
)
- timings.append((transition_ms, advance_ms))
+ timings.append(
+ PowerPointTiming(
+ transition_ms=transition_ms,
+ narration_delay_ms=narration_delay_ms,
+ advance_ms=advance_ms,
+ )
+ )
return timings
def _powerpoint_audio_starts(
- timings: list[tuple[int, int]],
+ timings: list[PowerPointTiming],
) -> tuple[list[int], int]:
"""Return theoretical narration starts and the complete PPTX timeline."""
audio_starts: list[int] = []
timeline_ms = 0
- for transition_ms, advance_ms in timings:
- audio_start_ms = timeline_ms + transition_ms
+ for timing in timings:
+ slide_start_ms = timeline_ms
+ audio_start_ms = (
+ slide_start_ms
+ + timing.transition_ms
+ + timing.narration_delay_ms
+ )
audio_starts.append(audio_start_ms)
- timeline_ms = audio_start_ms + advance_ms
+ timeline_ms = (
+ slide_start_ms + timing.transition_ms + timing.advance_ms
+ )
return audio_starts, timeline_ms
@@ -1610,17 +1759,19 @@ def _merge_subtitles_result(
merged_cues: list[SubtitleCue] = []
- for slide_name, audio_start_ms, (_transition_ms, advance_ms) in zip(
+ for slide_name, audio_start_ms, timing in zip(
slide_names,
audio_starts,
timings,
):
slide_cues = local_cues[slide_name]
- if slide_cues[-1].end_ms > advance_ms:
+ narration_window_ms = timing.advance_ms - timing.narration_delay_ms
+ if slide_cues[-1].end_ms > narration_window_ms:
raise ValueError(
f"{slide_name}.srt ends at "
f"{_seconds_from_ms(slide_cues[-1].end_ms):.3f}s, after the "
- f"PowerPoint slide advance at {_seconds_from_ms(advance_ms):.3f}s"
+ "available narration window before PowerPoint advances at "
+ f"{_seconds_from_ms(narration_window_ms):.3f}s"
)
for cue in slide_cues:
merged_cue = SubtitleCue(
@@ -1757,6 +1908,16 @@ def build_parser() -> argparse.ArgumentParser:
default=0.5,
help="Seconds added after each narration before slide advance (default: 0.5)",
)
+ animations.add_argument(
+ "--narration-start-floor",
+ type=float,
+ default=DEFAULT_NARRATION_START_FLOOR,
+ help=(
+ "Minimum seconds from transition start to narration start; "
+ "0 waits only for transition completion "
+ f"(default: {DEFAULT_NARRATION_START_FLOOR:g})"
+ ),
+ )
animations.add_argument(
"--force",
action="store_true",
@@ -1865,6 +2026,7 @@ def main(argv: list[str] | None = None) -> int:
audio_dir=audio_dir,
output_path=output_path,
narration_padding=args.narration_padding,
+ narration_start_floor=args.narration_start_floor,
force=args.force,
)
print(f"Narration animation config written: {output_path}")
diff --git a/skills/ppt-master/scripts/native_enhance_pptx_core.py b/skills/ppt-master/scripts/native_enhance_pptx_core.py
index 378f470b..54979fe0 100644
--- a/skills/ppt-master/scripts/native_enhance_pptx_core.py
+++ b/skills/ppt-master/scripts/native_enhance_pptx_core.py
@@ -59,6 +59,7 @@ from pptx_transitions import ( # noqa: E402
NATIVE_TRANSITION_KEYS,
apply_slide_motion_xml,
normalize_transition_effect_request,
+ read_slide_transition_xml,
set_directory_use_timings,
validate_pptx_transition_package,
validate_seconds,
@@ -72,10 +73,12 @@ from svg_to_pptx.pptx_package.narration import ( # noqa: E402
AUDIO_CONTENT_TYPES,
AUDIO_MARKER_PNG_BYTES,
AUDIO_REL_TYPE,
+ DEFAULT_NARRATION_START_FLOOR,
IMAGE_REL_TYPE,
MEDIA_REL_TYPE,
NARRATION_EXTENSIONS,
inject_narration,
+ narration_lead_in_seconds,
next_shape_id,
probe_audio_duration,
)
@@ -902,6 +905,7 @@ def _apply_audio(
enter: EnterUpdate,
timings_enabled: bool,
narration_padding: float,
+ narration_start_floor: float,
audio_duration: float | None = None,
) -> bool:
media_dir = extract_dir / "ppt" / "media"
@@ -925,6 +929,24 @@ def _apply_audio(
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)
+ source_transition = read_slide_transition_xml(slide_xml)
+ if enter.policy == "replace":
+ transition_duration = enter.duration
+ elif enter.policy == "none":
+ transition_duration = 0.0
+ else:
+ # Legacy spd-only transitions expose no exact milliseconds. Treat
+ # those as unknown and keep the full configured floor after the
+ # preserved transition rather than guessing an application duration.
+ transition_duration = (
+ source_transition.duration_ms / 1000
+ if source_transition.duration_ms is not None
+ else 0.0
+ )
+ narration_lead_in = narration_lead_in_seconds(
+ transition_duration,
+ start_floor=narration_start_floor,
+ )
shape_id = next_shape_id(slide_xml)
slide_xml = inject_narration(
slide_xml,
@@ -933,18 +955,38 @@ def _apply_audio(
audio_rid=audio_rid,
media_rid=media_rid,
poster_rid=poster_rid,
+ start_delay=narration_lead_in,
)
advance = AdvanceUpdate(mode="preserve")
- if timings_enabled:
- duration = audio_duration
+ duration = audio_duration
+ if duration is None and (
+ timings_enabled or source_transition.advance_after_ms is not None
+ ):
+ duration = probe_audio_duration(audio_path)
+ if (
+ not timings_enabled
+ and source_transition.advance_after_ms is not None
+ ):
if duration is None:
- duration = probe_audio_duration(audio_path)
+ raise RuntimeError(
+ f"Unable to validate narration against slide {slide.index} "
+ f"auto-advance with ffprobe: {audio_path}"
+ )
+ required_playback_ms = round((narration_lead_in + duration) * 1000)
+ if source_transition.advance_after_ms < required_playback_ms:
+ raise RuntimeError(
+ f"Slide {slide.index} advances after "
+ f"{source_transition.advance_after_ms} ms, before delayed "
+ f"narration can finish at {required_playback_ms} ms; enable "
+ "timings or lengthen the source auto-advance"
+ )
+ if timings_enabled:
if duration is None:
raise RuntimeError(f"Unable to read narration duration with ffprobe: {audio_path}")
advance = AdvanceUpdate(
mode="narration",
- after=duration + narration_padding,
+ after=narration_lead_in + duration + narration_padding,
)
wrote_advance = False
@@ -1223,6 +1265,7 @@ def _build_enhancement_plan(
transition: str | None,
transition_duration: float | None,
narration_padding: float | None,
+ narration_start_floor: float | None,
apply_transition_without_audio: bool | None,
existing_plan: dict | None = None,
) -> dict:
@@ -1241,6 +1284,19 @@ def _build_enhancement_plan(
"narration padding",
allow_zero=True,
)
+ raw_start_floor: object
+ if narration_start_floor is not None:
+ raw_start_floor = narration_start_floor
+ else:
+ raw_start_floor = previous_timings.get(
+ "narration_start_floor",
+ DEFAULT_NARRATION_START_FLOOR,
+ )
+ resolved_start_floor = validate_seconds(
+ raw_start_floor,
+ "narration start floor",
+ allow_zero=True,
+ )
transitions_enabled, transition_config = _resolved_draft_transition_config(
project,
previous,
@@ -1297,6 +1353,7 @@ def _build_enhancement_plan(
),
"source": "audio_duration",
"narration_padding": resolved_padding,
+ "narration_start_floor": resolved_start_floor,
},
"transitions": {
"enabled": transitions_enabled,
@@ -1729,6 +1786,7 @@ def init_project(args: argparse.Namespace) -> int:
transition=args.transition,
transition_duration=args.transition_duration,
narration_padding=args.narration_padding,
+ narration_start_floor=args.narration_start_floor,
apply_transition_without_audio=args.apply_transition_without_audio,
)
_write_json(_plan_path(project_path), plan)
@@ -1813,6 +1871,7 @@ def plan_project(args: argparse.Namespace) -> int:
transition=args.transition,
transition_duration=args.transition_duration,
narration_padding=args.narration_padding,
+ narration_start_floor=args.narration_start_floor,
apply_transition_without_audio=args.apply_transition_without_audio,
existing_plan=existing_plan,
)
@@ -1915,6 +1974,25 @@ def apply_project(args: argparse.Namespace) -> int:
except ValueError as exc:
return fail_preflight([str(exc)])
+ if args.narration_start_floor is not None:
+ raw_narration_start_floor = args.narration_start_floor
+ elif "narration_start_floor" in timings_cfg:
+ raw_narration_start_floor = timings_cfg["narration_start_floor"]
+ else:
+ raw_narration_start_floor = DEFAULT_NARRATION_START_FLOOR
+
+ try:
+ if "audio" in modules:
+ narration_start_floor = validate_seconds(
+ raw_narration_start_floor,
+ "narration start floor",
+ allow_zero=True,
+ )
+ else:
+ narration_start_floor = DEFAULT_NARRATION_START_FLOOR
+ except ValueError as exc:
+ return fail_preflight([str(exc)])
+
output_path = (
Path(args.output).expanduser().resolve()
if args.output
@@ -2034,6 +2112,7 @@ def apply_project(args: argparse.Namespace) -> int:
enter=enter_update,
timings_enabled="timings" in modules,
narration_padding=narration_padding,
+ narration_start_floor=narration_start_floor,
audio_duration=readiness.audio_durations.get(slide.index),
) or wrote_auto_advance
audio_exts.add(audio.suffix.lower())
@@ -2330,6 +2409,12 @@ def build_parser() -> argparse.ArgumentParser:
)
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(
+ "--narration-start-floor",
+ type=_non_negative_seconds_arg,
+ default=DEFAULT_NARRATION_START_FLOOR,
+ help="minimum seconds from transition start to narration start",
+ )
init.add_argument(
"--apply-transition-without-audio",
action="store_true",
@@ -2361,6 +2446,12 @@ def build_parser() -> argparse.ArgumentParser:
type=_non_negative_seconds_arg,
default=None,
)
+ plan.add_argument(
+ "--narration-start-floor",
+ type=_non_negative_seconds_arg,
+ default=None,
+ help="replace the saved narration start floor; omitted values preserve it",
+ )
plan.add_argument(
"--apply-transition-without-audio",
action="store_true",
@@ -2387,6 +2478,12 @@ def build_parser() -> argparse.ArgumentParser:
)
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(
+ "--narration-start-floor",
+ type=_non_negative_seconds_arg,
+ default=None,
+ help="override the confirmed narration start floor for this export",
+ )
apply.add_argument("--force", action="store_true", help="apply without a confirmed enhancement plan")
apply.add_argument(
"--apply-transition-without-audio",
diff --git a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
index 681f602d..61dbd01a 100644
--- a/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
+++ b/skills/ppt-master/scripts/svg_to_pptx/pptx_package/builder.py
@@ -99,10 +99,12 @@ from .narration import (
AUDIO_CONTENT_TYPES,
AUDIO_REL_TYPE,
AUDIO_MARKER_PNG_BYTES,
+ DEFAULT_NARRATION_START_FLOOR,
IMAGE_REL_TYPE,
MEDIA_REL_TYPE,
apply_recorded_timing,
inject_narration,
+ narration_lead_in_seconds,
next_shape_id,
probe_audio_duration,
)
@@ -4683,6 +4685,7 @@ def create_pptx_with_native_svg(
transition_effect_options: dict[str, object] | None = None,
text_flow: str | None = None,
primary_language: str | None = None,
+ narration_start_floor: float = DEFAULT_NARRATION_START_FLOOR,
) -> bool:
"""Create a PPTX file with native DrawingML shapes.
@@ -4723,6 +4726,8 @@ def create_pptx_with_native_svg(
narration_audio: Optional dict mapping SVG stem to narration audio file.
use_narration_timings: Whether to set slide auto-advance from audio duration.
narration_padding: Extra seconds added after each narration before advancing.
+ narration_start_floor: Minimum seconds from transition start to narration
+ start. Any remainder after the transition becomes silent lead-in.
merge_paragraphs: Legacy compatibility option. True selects reflow;
False selects split. Do not combine with ``text_flow``.
text_flow: Positional-tspan policy: preserve authored line breaks in
@@ -5586,6 +5591,15 @@ def create_pptx_with_native_svg(
slide_xml = slide_xml_path.read_text(encoding='utf-8')
narration_shape_id = next_shape_id(slide_xml)
+ narration_transition_duration = (
+ slide_transition_duration
+ if slide_transition is not None
+ else 0.0
+ )
+ narration_lead_in = narration_lead_in_seconds(
+ narration_transition_duration,
+ start_floor=narration_start_floor,
+ )
slide_xml = inject_narration(
slide_xml,
shape_id=narration_shape_id,
@@ -5593,6 +5607,7 @@ def create_pptx_with_native_svg(
audio_rid=audio_rid,
media_rid=media_rid,
poster_rid=poster_rid,
+ start_delay=narration_lead_in,
)
if use_narration_timings:
@@ -5601,13 +5616,16 @@ def create_pptx_with_native_svg(
raise RuntimeError(
f"Unable to read narration duration with ffprobe: {audio_path}"
)
+ narration_advance_after = (
+ narration_lead_in + duration + narration_padding
+ )
slide_xml = apply_recorded_timing(
slide_xml,
- advance_after=duration + narration_padding,
+ advance_after=narration_advance_after,
transition_duration=slide_transition_duration,
transition_effect=slide_transition,
)
- resolved_advance_after = duration + narration_padding
+ resolved_advance_after = narration_advance_after
resolved_advance_on_click = False
package_uses_timings = True
slide_xml_path.write_text(slide_xml, encoding='utf-8')
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 bdfcb109..0648875b 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
@@ -70,7 +70,12 @@ from ..drawingml.theme_fonts import (
load_theme_font_spec,
)
from ..drawingml.utils import unsafe_exported_font_faces
-from .narration import NARRATION_EXTENSIONS, find_narration_files, probe_audio_duration
+from .narration import (
+ DEFAULT_NARRATION_START_FLOOR,
+ NARRATION_EXTENSIONS,
+ find_narration_files,
+ probe_audio_duration,
+)
from .template_structure import (
TemplateStructureError,
load_pptx_structure_lock,
@@ -1096,6 +1101,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(
+ '--narration-start-floor',
+ type=non_negative_float,
+ default=DEFAULT_NARRATION_START_FLOOR,
+ help=(
+ 'Minimum seconds from slide-transition start to narration start; '
+ 'set 0 to start immediately after the transition '
+ f'(default: {DEFAULT_NARRATION_START_FLOOR})'
+ ),
+ )
parser.add_argument(
'--inherit-motion-from',
type=str,
@@ -1899,6 +1914,7 @@ Recorded narration:
narration_audio=narration_audio,
use_narration_timings=use_narration_timings,
narration_padding=args.narration_padding,
+ narration_start_floor=args.narration_start_floor,
text_flow=args.text_flow,
image_optimize=not args.no_image_optimize,
image_max_dimension=args.image_max_dimension,
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 58ccdd22..1e5b231c 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
@@ -20,6 +20,7 @@ from pptx_transitions import (
parse_source_xml,
read_slide_transition_xml,
serialize_source_xml,
+ validate_seconds,
)
@@ -40,6 +41,7 @@ AUDIO_CONTENT_TYPES = {
}
NARRATION_EXTENSIONS = tuple(AUDIO_CONTENT_TYPES.keys())
+DEFAULT_NARRATION_START_FLOOR = 0.8
AUDIO_MARKER_SIZE_EMU = 457200 # 48 SVG px
AUDIO_MARKER_OFF_CANVAS_EMU = -AUDIO_MARKER_SIZE_EMU
@@ -300,7 +302,30 @@ def _numeric_ids(
return ids
-def _create_audio_timing_element(shape_id: int, ctn_id: int) -> ET.Element:
+def narration_lead_in_seconds(
+ transition_duration: float,
+ *,
+ start_floor: float = DEFAULT_NARRATION_START_FLOOR,
+) -> float:
+ """Return silence after a slide transition before narration starts."""
+ transition_seconds = validate_seconds(
+ transition_duration,
+ "narration transition duration",
+ allow_zero=True,
+ )
+ floor_seconds = validate_seconds(
+ start_floor,
+ "narration start floor",
+ allow_zero=True,
+ )
+ return max(0.0, floor_seconds - transition_seconds)
+
+
+def _create_audio_timing_element(
+ shape_id: int,
+ ctn_id: int,
+ start_delay_ms: int,
+) -> ET.Element:
audio = ET.Element(_qn(PML_NS, "audio"))
media_node = ET.SubElement(
audio,
@@ -313,7 +338,11 @@ def _create_audio_timing_element(shape_id: int, ctn_id: int) -> ET.Element:
{"id": str(ctn_id), "fill": "hold", "display": "0"},
)
start_conditions = ET.SubElement(time_node, _qn(PML_NS, "stCondLst"))
- ET.SubElement(start_conditions, _qn(PML_NS, "cond"), {"delay": "0"})
+ ET.SubElement(
+ start_conditions,
+ _qn(PML_NS, "cond"),
+ {"delay": str(start_delay_ms)},
+ )
target = ET.SubElement(media_node, _qn(PML_NS, "tgtEl"))
ET.SubElement(target, _qn(PML_NS, "spTgt"), {"spid": str(shape_id)})
return audio
@@ -466,8 +495,9 @@ def inject_narration(
audio_rid: str,
media_rid: str,
poster_rid: str,
+ start_delay: float = 0.0,
) -> str:
- """Inject a hidden narration media shape and slide-entry autoplay timing."""
+ """Inject a hidden narration shape and delayed slide-entry autoplay timing."""
if isinstance(shape_id, bool) or not isinstance(shape_id, int) or shape_id <= 0:
raise ValueError("narration shape_id must be a positive integer")
if shape_id > MAX_OOXML_UNSIGNED_INT:
@@ -475,6 +505,17 @@ def inject_narration(
"narration shape_id exceeds the OOXML unsigned-integer limit: "
f"{shape_id}"
)
+ start_delay_seconds = validate_seconds(
+ start_delay,
+ "narration start delay",
+ allow_zero=True,
+ )
+ start_delay_ms = round(start_delay_seconds * 1000)
+ if start_delay_ms > MAX_OOXML_UNSIGNED_INT:
+ raise ValueError(
+ "narration start delay exceeds the OOXML unsigned-integer limit: "
+ f"{start_delay_ms} ms"
+ )
root = parse_source_xml(slide_xml)
if root.tag != _qn(PML_NS, "sld"):
@@ -533,15 +574,101 @@ def inject_narration(
"tmRoot/p:childTnLst",
)
child_nodes.append(
- _create_audio_timing_element(shape_id, next_timing_id)
+ _create_audio_timing_element(
+ shape_id,
+ next_timing_id,
+ start_delay_ms,
+ )
)
else:
- audio_timing = _create_audio_timing_element(shape_id, next_timing_id + 1)
+ audio_timing = _create_audio_timing_element(
+ shape_id,
+ next_timing_id + 1,
+ start_delay_ms,
+ )
_insert_root_timing(root, _new_timing(audio_timing, next_timing_id))
return serialize_source_xml(root, slide_xml).decode("utf-8")
+def read_narration_start_delay_xml(slide_xml: str) -> int:
+ """Return the latest embedded narration picture's autoplay delay in ms."""
+ root = parse_source_xml(slide_xml)
+ if root.tag != _qn(PML_NS, "sld"):
+ raise ValueError("narration source XML root must be p:sld")
+
+ audio_shape_properties: list[ET.Element] = []
+ for picture in root.iter(_qn(PML_NS, "pic")):
+ if not any(
+ element.tag == _qn(DRAWINGML_NS, "audioFile")
+ for element in picture.iter()
+ ):
+ continue
+ properties = list(picture.iter(_qn(PML_NS, "cNvPr")))
+ if len(properties) != 1:
+ raise ValueError(
+ "narration audio picture must contain exactly one p:cNvPr"
+ )
+ audio_shape_properties.extend(properties)
+ if not audio_shape_properties:
+ raise ValueError("narration source has no embedded audio picture")
+
+ narration_shape_id = max(
+ _numeric_ids(
+ audio_shape_properties,
+ "narration audio shape",
+ minimum=1,
+ )
+ )
+ delays: list[int] = []
+ for audio in root.iter(_qn(PML_NS, "audio")):
+ media_node = audio.find(_qn(PML_NS, "cMediaNode"))
+ if media_node is None:
+ continue
+ target = media_node.find(
+ f"{_qn(PML_NS, 'tgtEl')}/{_qn(PML_NS, 'spTgt')}"
+ )
+ if target is None or target.get("spid") != str(narration_shape_id):
+ continue
+ time_node = _direct_child(
+ media_node,
+ _qn(PML_NS, "cTn"),
+ "p:audio/p:cMediaNode/p:cTn",
+ )
+ start_conditions = _direct_child(
+ time_node,
+ _qn(PML_NS, "stCondLst"),
+ "p:cTn/p:stCondLst",
+ )
+ condition = _direct_child(
+ start_conditions,
+ _qn(PML_NS, "cond"),
+ "p:stCondLst/p:cond",
+ )
+ raw_delay = condition.get("delay")
+ try:
+ delay = int(raw_delay)
+ except (TypeError, ValueError) as exc:
+ raise ValueError(
+ f"narration timing has invalid start delay: {raw_delay!r}"
+ ) from exc
+ if delay < 0 or delay > MAX_OOXML_UNSIGNED_INT:
+ raise ValueError(
+ "narration timing start delay is outside the OOXML "
+ f"unsigned-integer range: {delay}"
+ )
+ delays.append(delay)
+
+ if not delays:
+ raise ValueError("narration source has no autoplay timing for its audio picture")
+ if len(set(delays)) != 1:
+ raise ValueError(
+ "narration source timing branches disagree on autoplay delay: "
+ f"{sorted(set(delays))}"
+ )
+ return delays[0]
+
+
def apply_recorded_timing(
slide_xml: str,
*,