Add illustrated desktop reporter user guide
Beffroi/beffroi-tools/pipeline/head There was a failure building this commit Details

This commit is contained in:
Dandaedre 2026-10-20 14:41:11 +02:00
parent 534cce41cd
commit 1b2925eb9c
7 changed files with 97 additions and 0 deletions

View File

@ -17,6 +17,7 @@ The reporter needs FFprobe (included in portable bundles); PDF generation is
built in. The exporter needs DeckCraft for PPTX or PdfCraft for PDF input.
Run source commands from the repository root; CLI tools support `--help`.
- [Illustrated user guide](docs/user-guide.md)
- [Reporter](docs/rust-reporter.md) · [Windows quick start](docs/windows-quickstart.txt)
- [Report options and Python reference](docs/pptx-videos.md)
- [Document exports](docs/exporter.md)

Binary file not shown.

After

Width:  |  Height:  |  Size: 72 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 80 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 112 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 20 KiB

View File

@ -2,6 +2,7 @@
Create video timing reports from a PowerPoint presentation using the desktop
app or CLI. Python and PowerPoint are not required for the Rust application.
For a walkthrough with screenshots, see the [user guide](user-guide.md).
```sh
cargo run --locked --bin pptx-reporter-gui

95
docs/user-guide.md Normal file
View File

@ -0,0 +1,95 @@
# PPTX Reporter user guide
The desktop app turns embedded PowerPoint videos into timing reports. The
Windows GUI has been confirmed working by the project owner. Screenshots below
show the same interface running on Linux with a sample presentation; window
borders, file dialogs and path separators differ on Windows.
## 1. Open a presentation
On Windows, extract the **whole portable ZIP** and launch
`pptx-reporter-gui.exe`. Keep `ffprobe.exe` beside it. No Python, PowerPoint or
Typst installation is needed.
Drag one `.pptx` into the window, or click **Choose presentation…**. You can
also choose a previously used file from **Recent presentations**.
![Start screen with the presentation picker and drop area](images/reporter/01-start.png)
## 2. Choose what to create
Check the selected filename and **Save to** path. Use **Choose…** under Output
folder for another destination, or **Use default** to reset it.
| Mode | Result |
| --- | --- |
| Extract + reports | Save embedded videos and generate reports |
| Reports only | Generate reports without keeping newly extracted videos |
| Extract only | Save videos without generating reports |
For easy reading, choose **Reading & printing**: it selects Web page, PDF and
Compact PDF. Add **Ontime** if you need a rundown import. **Defaults** selects
Markdown and Ontime; **All** selects every format. Individual checkboxes let
you adjust any selection.
The example below uses Reports only, with readable reports and Ontime selected.
![Selected presentation, save location and report formats](images/reporter/02-options.png)
Click the purple action button. Its label follows your mode: **Generate
reports**, **Extract videos**, or **Extract & generate reports**.
## 3. Open your results
During processing, the app shows the current step and progress where measurable.
Time estimates apply to that phase. **Cancel** stops between steps and interrupts
FFprobe; an active PDF compilation finishes before stopping.
When **Your files are ready** appears, click **Open** beside a report or
**Open output folder**. **Copy path** copies a file's location, not its contents.
Scroll down if the result list extends below the window.
![Completed run with report files and Open actions](images/reporter/03-results.png)
The default output is beside your presentation:
```text
Showcase_videos/
├── reports/ timing reports and editable Typst sources
└── videos/ extracted media, when requested
```
The `.typ` files are editable PDF sources; open `.pdf` for normal reading.
Existing reports are regenerated. Existing videos are reused unless **Advanced
→ Replace existing extracted videos** is enabled. The source PPTX is preserved.
A presentation with no embedded videos produces no new reports.
## 4. Read the timings
Reports follow slide order. Durations account for PowerPoint start/end trims;
trim details appear under the media name. A **Looping** marker identifies a
video without a usable finite playback duration. Loops and unsupported timing
are excluded from playback totals and Ontime. Extracted videos remain untrimmed.
Compact PDF keeps the slide, media name and duration in a portrait layout.
Here is the top of the sample report:
![Compact PDF preview showing a trimmed video and a looping video](images/reporter/04-compact-report.png)
To use the rundown, import `timings.ontime.json` into **Ontime 4** via
**Editor → Project → Manage projects**. This is different from `timings.json`,
which contains general report metadata. See [Ontime details](pptx-videos.md#ontime-import)
for skipped events and choosing your show start time.
## If something needs attention
- **FFprobe cannot be found:** keep the bundled executable beside the app, or
select it under **Advanced → FFprobe → Locate…**.
- **Generate is disabled:** choose a presentation and at least one report format,
or select Extract only.
- **A warning or failure appears:** expand **Activity & diagnostics** for details.
- **A report will not open:** use Open output folder and open it with an installed
PDF reader or browser. Ontime JSON needs to be imported into Ontime.
For CLI options and exact playback semantics, see [Reporter](rust-reporter.md)
and [Report options](pptx-videos.md).