beffroi-tools/docs/pptx-videos.md

7.1 KiB

Report formats and timing semantics

Use the Rust CLI below, or see the illustrated desktop guide. Run source commands from the repository root. With a prebuilt CLI, replace cargo run --locked --bin pptx-reporter -- with pptx-reporter (or pptx-reporter.exe on Windows). The Python reporter has been retired.

Extract videos and create Markdown and Ontime timing reports:

cargo run --locked --bin pptx-reporter -- presentation.pptx

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

cargo run --locked --bin pptx-reporter -- presentation.pptx --timings-only --report html,pdf
cargo run --locked --bin pptx-reporter -- 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 built-in PDF layouts 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 embedded Typst engine 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:

cargo run --locked --bin pptx-reporter -- 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 generation needs no external CLI. 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

cargo run --locked --bin pptx-reporter -- 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.

Batch and folder inputs

Multiple PPTX files, folders of videos, and folders containing PPTX files or video subfolders use the same timing and report rules. Batches produce one combined export with named Ontime groups, ordered by filename. See batch examples and folder rules.