Problem
add_movie() exists but is half-built: it embeds the video blob and creates the picture poster, but the playback configuration that PowerPoint exposes through Video Tools → Playback (Trim, Volume, Start Automatically vs On Click, Loop, Rewind After Playing, Hide While Not Playing) is unauthorable — those live in <p:cMediaNode> inside <p:timing>, and the timing tree is unmodelled (overlaps with Animations epic). Audio is worse: there is no audio API at all. Issues track auto-play (scanny/python-pptx#427, 16c), trim/start-time (#811, 6c), animated GIFs (#501), narration (#622), audio replacement (#784, #805), and corrupted-on-removal (#974, 6c). YouTube embeds (#839) and HTML embeds (#777, 12c) are PowerPoint features that should at minimum round-trip without corruption.
Sub-features
Prior art
- Open PRs: none directly on the playback-configuration surface.
- User issues this would close: #322, #323, #427, #430, #501, #622, #752, #767, #777, #782, #784, #802, #805, #811, #839, #847, #926, #974.
- OOXML: PresentationML §19.3.1.4
<p:audioFile>, <p:videoFile>; §19.5.10 <p:cMediaNode> (playback config inside timing tree); <p:nvSpPr>/<p:nvPr> carries <a:audioFile> / <a:videoFile> rel; online video uses <p15:linkRel> extension.
- Code paths:
src/pptx/parts/media.py, src/pptx/shapes/picture.py (Movie subclass), src/pptx/oxml/shapes/picture.py. Cross-cuts with Animations epic on cMediaNode.
Acceptance criteria
- A pptx authored with
movie.playback.start = MSO_MEDIA_START.AUTO; movie.playback.loop_until_stopped = True plays automatically and loops in PowerPoint.
- Audio shapes round-trip and play.
- Removing a Movie via
shape.delete() produces a saveable, openable deck (no corruption).
- Animated GIF preserves animation on round-trip.
- 25+ unit tests + 8 behave scenarios.
Effort: L
Phase A: audio API + safe removal + replace (M). Phase B: playback configuration (depends on Animations epic Phase B for cMediaNode, M). Phase C: GIF / online-video / HTML embed preservation (S).
Problem
add_movie()exists but is half-built: it embeds the video blob and creates the picture poster, but the playback configuration that PowerPoint exposes through Video Tools → Playback (Trim, Volume, Start Automatically vs On Click, Loop, Rewind After Playing, Hide While Not Playing) is unauthorable — those live in<p:cMediaNode>inside<p:timing>, and the timing tree is unmodelled (overlaps with Animations epic). Audio is worse: there is no audio API at all. Issues track auto-play (scanny/python-pptx#427, 16c), trim/start-time (#811, 6c), animated GIFs (#501), narration (#622), audio replacement (#784, #805), and corrupted-on-removal (#974, 6c). YouTube embeds (#839) and HTML embeds (#777, 12c) are PowerPoint features that should at minimum round-trip without corruption.Sub-features
Slide.shapes.add_audio(audio_file, x, y, cx, cy)— parallel toadd_movieMovie.playback.start = MSO_MEDIA_START.AUTO|ON_CLICK|IN_CLICK_SEQUENCEMovie.playback.loop_until_stopped,.rewind_after,.hide_while_not_playing,.volume(0.0–1.0)Movie.playback.trim_start_ms/.trim_end_msfor video trimmingSlide.notes_audio/Slide.narrationsetteradd_picture("file.gif")preserves animation (currently shows first frame only)Movie.replace_media(new_file)parallel toPicture.replace_image()shape.delete()on a Movie/Audio drops the rels and cMediaNode without corrupting timing tree<a:videoFile>+<p15:linkRel>)Prior art
<p:audioFile>,<p:videoFile>; §19.5.10<p:cMediaNode>(playback config inside timing tree);<p:nvSpPr>/<p:nvPr>carries<a:audioFile>/<a:videoFile>rel; online video uses<p15:linkRel>extension.src/pptx/parts/media.py,src/pptx/shapes/picture.py(Movie subclass),src/pptx/oxml/shapes/picture.py. Cross-cuts with Animations epic on cMediaNode.Acceptance criteria
movie.playback.start = MSO_MEDIA_START.AUTO; movie.playback.loop_until_stopped = Trueplays automatically and loops in PowerPoint.shape.delete()produces a saveable, openable deck (no corruption).Effort: L
Phase A: audio API + safe removal + replace (M). Phase B: playback configuration (depends on Animations epic Phase B for cMediaNode, M). Phase C: GIF / online-video / HTML embed preservation (S).