Turn README into an illustrated project portal

This commit is contained in:
Dandaedre 2026-11-14 16:26:48 +01:00
parent d92c4f5c9f
commit 42a92b8f1a
1 changed files with 104 additions and 38 deletions

142
README.md
View File

@ -1,67 +1,133 @@
# beffroi-tools
<h1 align="center">beffroi-tools</h1>
![current version](https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/version.svg)
![test status](https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/test.svg)
![line coverage](https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/coverage.svg)
<p align="center">Local tools for presentations, show timing, screen layouts and media workflows.</p>
Local document and media tools: a Rust PPTX video reporter with a drag-and-drop
app, a spreadsheet rundown converter for Ontime, an ASCII filename cleaner,
and Python document exports.
<p align="center">
<img src="https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/version.svg" alt="Current version">
<img src="https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/test.svg" alt="Test status">
<img src="https://assets.dandaedre.com/coverage/Beffroi/beffroi-tools/main/coverage.svg" alt="Line coverage">
</p>
<p align="center">
<a href="docs/releases.md">Portable releases</a> ·
<a href="#quick-start">Quick start</a> ·
<a href="docs/changelogs.md">What's new</a> ·
<a href="docs/development.md">Development</a>
</p>
## Choose your tool
<table>
<tr>
<td width="50%" valign="top">
<a href="docs/rust-reporter.md"><img src="crates/pptx-reporter/assets/app-icon.png" width="72" height="72" alt="PPTX Reporter icon"></a>
<h3><a href="docs/rust-reporter.md">PPTX Reporter</a></h3>
<p>Inspect presentation videos, read playback timings, and export reports or Ontime rundowns.</p>
<p><strong>Desktop app · CLI</strong></p>
<p><a href="docs/user-guide.md">Visual walkthrough</a> · <a href="docs/rust-reporter.md">Guide</a> · <a href="docs/pptx-videos.md">Report formats</a></p>
</td>
<td width="50%" valign="top">
<a href="docs/rundown-converter.md"><img src="crates/rundown-converter/assets/app-icon.png" width="72" height="72" alt="Rundown Converter icon"></a>
<h3><a href="docs/rundown-converter.md">Rundown Converter</a></h3>
<p>Turn spreadsheet rundowns into Ontime schedules, with timing checks before export.</p>
<p><strong>Desktop app · CLI</strong></p>
<p><a href="docs/rundown-converter.md">Guide</a> · <a href="docs/rundown-corpus.md">Sample findings</a></p>
</td>
</tr>
<tr>
<td valign="top">
<a href="docs/midra-layout.md"><img src="crates/midra-layout/assets/app-icon.png" width="72" height="72" alt="Midra Layout icon"></a>
<h3><a href="docs/midra-layout.md">Midra Layout</a></h3>
<p>Arrange screen layers, exchange geometry, and review transfers to an Eikos 4K device.</p>
<p><strong>Desktop app</strong></p>
<p><a href="docs/midra-layout.md">Guide</a> · <a href="#midra-layout-templates">Templates</a> · <a href="docs/interfaces/midra-layout-exchange.md">Geometry formats</a></p>
</td>
<td valign="top">
<a href="docs/ascii-names.md"><img src="crates/ascii-names/assets/app-icon.png" width="72" height="72" alt="ASCII Names icon"></a>
<h3><a href="docs/ascii-names.md">ASCII Names</a></h3>
<p>Clean up filenames to ASCII with paced renames, collision protection, and unchanged file contents.</p>
<p><strong>Desktop app · CLI</strong></p>
<p><a href="docs/ascii-names.md">Guide</a></p>
</td>
</tr>
<tr>
<td valign="top">
<a href="docs/exporter.md"><img src="tools/assets/exporter/app-icon.png" width="72" height="72" alt="Document Exporter icon"></a>
<h3><a href="docs/exporter.md">Document Exporter</a></h3>
<p>Export PPTX to PDF or slide images, render PDF pages, and compress PDFs to a target size.</p>
<p><strong>Python CLI</strong></p>
<p><a href="docs/exporter.md">Guide and dependencies</a></p>
</td>
<td valign="top">
<a href="companion-modules/media-player-classic/README.md"><img src="companion-modules/media-player-classic/companion/assets/app-icon.png" width="72" height="72" alt="MPC-HC Companion icon"></a>
<h3><a href="companion-modules/media-player-classic/README.md">MPC-HC Companion</a></h3>
<p>Control Media Player Classic Home Cinema from Companion with playback actions and player feedback.</p>
<p><strong>Companion 5.1 module</strong></p>
<p><a href="companion-modules/media-player-classic/README.md">Setup and development</a></p>
</td>
</tr>
</table>
## Quick start
On Windows, extract the portable ZIP and open `pptx-reporter-gui.exe`.
Drop PPTX files or a video folder into the window, select report formats, and generate.
Keep the bundled `ffprobe.exe` beside the app.
**Start with a portable app:** see [release bundles and platform instructions](docs/releases.md).
For PPTX Reporter, extract the ZIP and open `pptx-reporter-gui.exe` on Windows
or run `./pptx-reporter-gui` on macOS 13+. Choose the macOS archive for
[Apple Silicon or Intel](docs/releases.md#macos). Keep the bundled FFprobe beside the app.
On macOS 13+, extract the portable ZIP for Apple Silicon (`aarch64`) or Intel
(`x86_64`) and run `./pptx-reporter-gui`. FFprobe is included; keep it beside the app.
See [macOS release details](docs/releases.md#macos).
Drop a presentation or video folder into the reporter, choose report formats,
and generate. The [illustrated guide](docs/user-guide.md) walks through each step;
a [Windows quick start](docs/windows-quickstart.txt) is also available.
To run from source:
<details>
<summary><strong>Run from source</strong> — Rust apps and Python exporter</summary>
Run these commands from the repository root:
```sh
# PPTX Reporter: desktop, full report, or Ontime timings
cargo run --locked --bin pptx-reporter-gui
cargo run --locked --bin pptx-reporter -- presentation.pptx --report all
cargo run --locked --bin pptx-reporter -- ./show --timings-only --report ontime
# Other desktop apps
cargo run --locked -p rundown-converter --bin rundown-converter-gui
cargo run --locked -p midra-layout
cargo run --locked -p ascii-names
# Document exports
python3 tools/exporter.py presentation.pptx --output pdf,images
```
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`.
The reporter needs FFprobe; PDF generation is built in. The exporter needs
DeckCraft for PPTX or PdfCraft for PDF input. CLI tools support `--help`.
See [development setup](docs/development.md) for prerequisites and checks.
</details>
## Midra Layout templates
Midra also imports/exports native PPTX and Figma FIG; Illustrator AI uses an optional
local VectorCraft CLI. See [formats, dependencies and `no_proprietary` builds](docs/interfaces/midra-layout-exchange.md#optional-native-document-codecs-and-licensing-builds).
Ready-made canvases with two named 16:9 layers. Choose a size, then a format.
<details>
<summary><strong>Browse Full HD and UHD 4K templates</strong> — SVG, draw.io, JSON, CSV, DXF and HTML</summary>
These starter files contain two named 16:9 layers on an exact pixel canvas.
- **Full HD — 1920 × 1080:** [SVG](docs/templates/midra-layout/midra-layout-1080p-2-layers.svg) · [draw.io](docs/templates/midra-layout/midra-layout-1080p-2-layers.drawio) · [JSON](docs/templates/midra-layout/midra-layout-1080p-2-layers.json) · [CSV](docs/templates/midra-layout/midra-layout-1080p-2-layers.csv) · [DXF](docs/templates/midra-layout/midra-layout-1080p-2-layers.dxf) · [HTML](docs/templates/midra-layout/midra-layout-1080p-2-layers.html)
- **UHD 4K — 3840 × 2160:** [SVG](docs/templates/midra-layout/midra-layout-4k-2-layers.svg) · [draw.io](docs/templates/midra-layout/midra-layout-4k-2-layers.drawio) · [JSON](docs/templates/midra-layout/midra-layout-4k-2-layers.json) · [CSV](docs/templates/midra-layout/midra-layout-4k-2-layers.csv) · [DXF](docs/templates/midra-layout/midra-layout-4k-2-layers.dxf) · [HTML](docs/templates/midra-layout/midra-layout-4k-2-layers.html)
## PPTX reporter visual guide
Midra also imports/exports native PPTX and Figma FIG; Illustrator AI uses an optional
local VectorCraft CLI. See [formats, dependencies and licensing builds](docs/interfaces/midra-layout-exchange.md#optional-native-document-codecs-and-licensing-builds).
**[Follow the illustrated PPTX reporter guide →](docs/user-guide.md)**
</details>
Screenshots walk you through choosing a presentation, selecting formats,
opening reports, and reading video timings.
## Explore further
## More documentation
- [Changelogs](docs/changelogs.md) — short per-tool change notes
- [Reporter](docs/rust-reporter.md) · [Windows quick start](docs/windows-quickstart.txt)
- [Report formats and timing semantics](docs/pptx-videos.md)
- [ASCII filename cleaner](docs/ascii-names.md)
- [Document exports](docs/exporter.md)
- [Rundown converter](docs/rundown-converter.md) · [Sample findings](docs/rundown-corpus.md)
- [Midra layout helper](docs/midra-layout.md) · [Geometry formats](docs/interfaces/midra-layout-exchange.md) · [Project format](docs/interfaces/midra-layout.md) · [Plan](docs/midra-layout-plan.md)
- [Development](docs/development.md) · [CI and coverage](docs/ci.md)
- [Cross builds and portable releases](docs/releases.md) · [App icons and desktop launchers](docs/releases.md#application-artwork)
- [MPC-HC Companion module development](companion-modules/media-player-classic/README.md)
- [Future ideas](Ideas.md)
- [Future program task list](docs/program-task-list.md)
| Resource | Links |
| --- | --- |
| Updates | [Per-tool changelogs](docs/changelogs.md) |
| Build and contribute | [Development](docs/development.md) · [CI and coverage](docs/ci.md) · [Cross builds and releases](docs/releases.md) |
| Desktop integration | [App icons and launchers](docs/releases.md#application-artwork) |
| Midra internals | [Project format](docs/interfaces/midra-layout.md) · [Device checks](docs/midra-layout-device-check.md) · [Plan](docs/midra-layout-plan.md) |
| What's next | [Ideas](Ideas.md) · [Program task list](docs/program-task-list.md) |