diff --git a/README.md b/README.md index 77419b9..02555a5 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/docs/images/reporter/01-start.png b/docs/images/reporter/01-start.png new file mode 100644 index 0000000..0ecaf3c Binary files /dev/null and b/docs/images/reporter/01-start.png differ diff --git a/docs/images/reporter/02-options.png b/docs/images/reporter/02-options.png new file mode 100644 index 0000000..a7d7242 Binary files /dev/null and b/docs/images/reporter/02-options.png differ diff --git a/docs/images/reporter/03-results.png b/docs/images/reporter/03-results.png new file mode 100644 index 0000000..ed8b220 Binary files /dev/null and b/docs/images/reporter/03-results.png differ diff --git a/docs/images/reporter/04-compact-report.png b/docs/images/reporter/04-compact-report.png new file mode 100644 index 0000000..af01ea4 Binary files /dev/null and b/docs/images/reporter/04-compact-report.png differ diff --git a/docs/rust-reporter.md b/docs/rust-reporter.md index 536597b..e2503ef 100644 --- a/docs/rust-reporter.md +++ b/docs/rust-reporter.md @@ -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 diff --git a/docs/user-guide.md b/docs/user-guide.md new file mode 100644 index 0000000..9d69349 --- /dev/null +++ b/docs/user-guide.md @@ -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).