beffroi-tools/docs/pptx-videos.md

138 lines
6.8 KiB
Markdown

# Report formats and timing semantics
Use the Rust CLI below, or see the [illustrated desktop guide](user-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.