pptx-reporter/README.md

153 lines
6.5 KiB
Markdown

# PPTX Reporter
![current version](https://assets.dandaedre.com/coverage/idle-org/pptx-reporter/main/version.svg)
![test status](https://assets.dandaedre.com/coverage/idle-org/pptx-reporter/main/test.svg)
![line coverage](https://assets.dandaedre.com/coverage/idle-org/pptx-reporter/main/coverage.svg)
**PPTX Reporter is a desktop application** that turns the videos in a
PowerPoint presentation—or a folder of ordinary video files—into a clear timing
report. It can also extract embedded videos and prepare a rundown for
[Ontime](https://www.getontime.no/).
You do not need PowerPoint, Python, or Typst. The desktop app guides you from
the source files to finished reports.
<p align="center">
<img src="crates/pptx-reporter/assets/app-icon.png" width="128" alt="PPTX Reporter icon">
</p>
## Download the desktop app
[**PPTX Reporter v0.7.0 release notes and all downloads →**](https://github.com/idle-org/pptx-reporter/releases/tag/v0.7.0)
| Your computer | Portable desktop package |
| --- | --- |
| Windows 64-bit | [Download ZIP](https://github.com/idle-org/pptx-reporter/releases/download/v0.7.0/pptx-reporter-portable-x86_64-pc-windows-gnu-v0.7.0.zip) |
| Linux 64-bit | [Download TGZ](https://github.com/idle-org/pptx-reporter/releases/download/v0.7.0/pptx-reporter-portable-x86_64-unknown-linux-gnu-v0.7.0.tgz) |
| Apple Silicon Mac | [Download ZIP](https://github.com/idle-org/pptx-reporter/releases/download/v0.7.0/pptx-reporter-portable-aarch64-apple-darwin-v0.7.0.zip) |
| Intel Mac | [Download ZIP](https://github.com/idle-org/pptx-reporter/releases/download/v0.7.0/pptx-reporter-portable-x86_64-apple-darwin-v0.7.0.zip) |
Extract the **complete archive** before opening the application. The portable
package includes the GUI, FFprobe, fonts, licenses, and a command-line version
for optional automation.
On Windows, launch `pptx-reporter-gui.exe`. On Linux or macOS, launch
`pptx-reporter-gui` from the extracted folder. The Mac downloads are unsigned;
see the [Mac launch instructions](docs/development/releases.md#macos) if
Gatekeeper blocks the application.
## Create a report in the GUI
1. Drop one or more `.pptx` files, a video folder, or a folder containing
presentations into the window.
2. Choose what to create and where to save it.
3. Select the report formats you need.
4. Click **Generate reports**.
The original presentation and videos are preserved.
![PPTX Reporter start screen with the presentation picker and drop area](docs/pptx-reporter/images/01-start.png)
## Choose your output
The **Create** menu controls whether PPTX Reporter extracts embedded videos,
creates reports, or does both.
| Choice | Use it when you want to… |
| --- | --- |
| **Reports only** | Read timings without keeping another copy of the videos |
| **Extract + reports** | Save the embedded videos and create timing reports |
| **Extract only** | Save embedded videos without producing reports |
The common report formats appear directly on the Setup screen:
- **PDF** creates an easy-to-share report.
- **Markdown** creates an editable text report.
- **Ontime** creates `timings.ontime.json`, ready to import as a rundown.
- **More formats…** offers a web page, compact PDF, JSON, plain text, Typst,
and useful presets.
By default, output goes beside the first input. Use **Change…** to put it
somewhere else.
![A selected input with report formats and destination ready to run](docs/pptx-reporter/images/02-options.png)
## Open the finished reports
When processing finishes, the **Results** tab lists every generated file. Use
**Open** to view a report or **Open output folder** to see everything together.
Expand **Activity & diagnostics** if the app reports a warning.
![Completed run with report files and Open actions](docs/pptx-reporter/images/03-results.png)
For a presentation named `Showcase.pptx`, the default output is:
```text
Showcase_videos/
├── reports/ PDF, web, text, JSON and Ontime reports
└── videos/ extracted media, when requested
```
Reports follow slide order and account for PowerPoint start and end trims.
Looping videos and unsupported timings remain visible, but they are excluded
from finite playback totals and Ontime cues. Extracted media is not trimmed or
otherwise changed.
![Compact PDF report with slide, media and duration columns](docs/pptx-reporter/images/04-compact-report.png)
## Import a rundown into Ontime
Generate the **Ontime** format, then import
`reports/timings.ontime.json` through **Editor → Project → Manage projects**
in Ontime 4. Use this file instead of `timings.json`, which contains the
general report data.
See [report formats and timing](docs/pptx-reporter/report-formats.md) for skipped
events and show start times.
## If something does not work
- **The Generate button is disabled:** select an input and at least one report
format, or choose **Extract only**.
- **FFprobe cannot be found:** keep the bundled executable beside the app, or
choose it under **Settings → FFprobe → Locate…**.
- **A warning or failure appears:** expand **Activity & diagnostics** to see
the affected file and processing step.
- **A report does not open:** use **Open output folder** and open it with an
installed PDF reader or browser. Ontime JSON must be imported into Ontime.
The [illustrated user guide](docs/pptx-reporter/visual-guide.md) covers batches,
progress, cancellation, existing files, and every report preset.
## Optional command line use
The GUI is the main way to use PPTX Reporter. The portable package also contains
`pptx-reporter.exe` for scripts and repeatable batch jobs. Source builds can run
the same commands with `cargo run --locked --bin pptx-reporter --`:
```sh
# Reports for one presentation
pptx-reporter presentation.pptx --report all
# An Ontime rundown from a folder of videos
pptx-reporter ./show --timings-only --report ontime
# Extract embedded videos without reports
pptx-reporter presentation.pptx --extract-only
```
For batch behavior and exact playback semantics, see the
[complete reference](docs/pptx-reporter/README.md).
## Documentation and development
- [Illustrated user guide](docs/pptx-reporter/visual-guide.md)
- [Report formats and timing](docs/pptx-reporter/report-formats.md)
- [Development guide](docs/development/README.md)
- [Changelog](docs/pptx-reporter/changelog.md)
PPTX Reporter is open-source software under the [MIT License](LICENSE). Its
development includes LLM-generated or LLM-assisted work with human review, and
it is used in professional settings. Report problems through
[GitHub Issues](https://github.com/idle-org/pptx-reporter/issues).