beffroi-tools/docs/pptx-videos.md

6.7 KiB

Report options and Python reference

Report semantics apply to both implementations. Commands below use the Python reference; for the desktop app and Rust CLI see Reporter. Only the Python implementation needs the external Typst CLI for PDFs.

Extract videos and create Markdown and Ontime timing reports:

python3 tools/pptx_videos.py presentation.pptx

Generate one or more report formats without keeping newly extracted videos:

python3 tools/pptx_videos.py presentation.pptx --timings-only --report html,pdf
python3 tools/pptx_videos.py presentation.pptx --report all

--report accepts comma-separated formats and can be repeated. Markdown and Ontime are included by default; an explicit --report replaces this selection. Use --report all for every format, including both PDF layouts (requires Typst) and Ontime. The output root is <presentation-stem>_videos, or the directory supplied with -o. Extracted media goes in videos/; all reports and Typst sources go in reports/:

presentation_videos/
├── videos/
│   └── media1.mp4
└── reports/
    ├── timings.md
    └── timings.ontime.json

Markdown and HTML links point to ../videos/; JSON extracted_file paths are relative to the report directory too. --timings-only reuses media in videos/ when available, otherwise probes temporary copies without creating that folder. --extract-only creates no report folder.

PDF uses the Typst CLI and retains timings.typ for editing. HTML and Typst/PDF include colored summary cards and pills; Markdown and TXT use aligned tables. JSON includes numeric durations in seconds, sizes in bytes, and slide references.

For a compact portrait PDF with slide numbers, media names, and duration pills:

python3 tools/pptx_videos.py presentation.pptx --timings-only --report pdf-dense

This creates timings-dense.pdf and its editable timings-dense.typ source. It has a discreet title containing the presentation name and no summary cards. Slide numbers and media names are plain text; durations and loop markers use pills. Trimmed videos show a discreet line under the media name with the amounts removed from the start and end. Looping videos carry an amber Looping pill next to their name and a dash instead of a finite duration. Use --report pdf,pdf-dense to produce both layouts.

Timings require ffprobe (from FFmpeg); PDF additionally requires typst on PATH. Use --extract-only to extract without a report. Presentations with no embedded videos produce no output.

Playback durations and trimming

Reports list each video occurrence separately, in slide order. Reusing a media file on another slide, or in two shapes on one slide, can produce different durations. Media size and embedded-video counts still count each file once.

Duration is the single-play duration after PowerPoint's start and end trims. The full reports also show Original duration and Playback status. HTML and both PDF layouts show start/end trim details below the media name and an amber Looping pill for repeated playback. Markdown and TXT include the trim details in the Playback column. pdf-dense retains its three columns; its duration pill shows a status when there is no usable duration.

  • PowerPoint's end trim is the amount removed from the end, not an end timestamp: a 10-second clip with 1 second trimmed from the start and 2 from the end plays for 7 seconds.
  • Repeats show Looping. Custom speed, reverse playback, conditional endings, finite animation duration caps, and playback across slides show Custom timing. These are not simulated and have no effective duration.
  • Invalid trim values show Invalid trim. Unknown source durations remain Unknown. No duration is invented.
  • The duration total adds known effective playback durations, once per occurrence. Loops and unsupported/invalid timing contribute nothing.
  • This is playback length once started, not total time spent on a slide. Click-to-start waits, slide transitions, and interactive animation sequences are not evaluated. Extracted media files are unchanged.

JSON retains file-level metadata under videos, with per-occurrence settings, trim offsets, original/effective durations, status, and diagnostic notes under playbacks. total_duration_seconds totals effective occurrences; total_media_duration_seconds retains the original once-per-file total.

Implementation references: Microsoft's media trim definition, time-offset units, and animation timing properties.

Ontime import

python3 tools/pptx_videos.py presentation.pptx --timings-only --report ontime

This writes timings.ontime.json, a native Ontime 4 project. It is separate from timings.json, which remains the general metadata report. Import it through Editor → Project → Manage projects. To bring the rundown into an existing project, import the file and use Partial Load. See Ontime's import instructions.

  • Each supported video occurrence becomes an event, sorted by slide. Reused media and multiple video shapes on the same slide get distinct events.
  • Event cues contain the slide number, titles contain filenames, and notes identify the presentation and archive media path.
  • Durations apply PowerPoint trims and retain milliseconds. Starts are linked, beginning at midnight; change the first playable event's start to your show time after import.
  • Loops, unsupported playback timing, and invalid trims are completely omitted. Unknown source durations use zero and are marked skipped with a review note. Unreferenced videos appear last and are also skipped. Durations exceeding Ontime's 23:59:59 limit require manual review.
  • No automatic playback or external-media downloads are configured. Slides without embedded videos are not included. Add speaking time manually.

The export was checked against Ontime 4's native project-section parsers; Ontime 3 is not supported by this export schema.

Progress output

Interactive terminals show a single animated progress line with completed video count, elapsed time, and the current extraction/probing/report step. It clears when finished, leaving report paths, the final summary, and warnings/errors. Long operations keep animating. Redirecting either output stream uses ordinary line logs instead. NO_COLOR disables colors; TERM=dumb also disables animation.