145 lines
7.1 KiB
Markdown
145 lines
7.1 KiB
Markdown
# Report formats and timing semantics
|
|
|
|
Use the Rust CLI below, or see the [illustrated desktop guide](visual-guide.md).
|
|
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:
|
|
|
|
```sh
|
|
cargo run --locked --bin pptx-reporter -- presentation.pptx
|
|
```
|
|
|
|
Generate one or more report formats without keeping newly extracted videos:
|
|
|
|
```sh
|
|
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/`:
|
|
|
|
```text
|
|
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:
|
|
|
|
```sh
|
|
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](https://learn.microsoft.com/en-nz/openspecs/office_standards/ms-pptx/c835eea3-fd6f-4055-8a57-92b193b7b2e3),
|
|
[time-offset units](https://learn.microsoft.com/en-nz/openspecs/office_standards/ms-pptx/a3ead080-d9cb-4b4a-8014-6d815248c23b),
|
|
and [animation timing properties](https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.presentation.commontimenode).
|
|
|
|
## Ontime import
|
|
|
|
```sh
|
|
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](https://docs.getontime.no/quick-tips/import-export/).
|
|
|
|
- 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](README.md#batches-and-video-folders).
|