Organize documentation by tool and update references

This commit is contained in:
Dandaedre 2026-11-14 17:57:06 +01:00
parent 839e2154d1
commit a8bcf7ff7b
45 changed files with 178 additions and 102 deletions

View File

@ -3,7 +3,7 @@
These are feasibility notes for possible tools, not implemented features or
committed delivery plans.
See the [future program task list](docs/program-task-list.md) for the planned
See the [future program task list](docs/planning/program-task-list.md) for the planned
DMX driver/firmware project and far-future Dante virtual soundcard research.
## Flipper Link: USB control from the web and Stream Deck
@ -19,6 +19,6 @@ with action selection, variables and feedback. Remote support varies by Flipper
application; exposing every internal action is not guaranteed. USB ownership,
reconnection and stopping held actions need particular care.
See [Flipper Link feasibility and proposed design](docs/flipper-link.md) for
See [Flipper Link feasibility and proposed design](docs/planning/flipper-link.md) for
the supported interfaces, limitations, architecture, implementation stages and
primary sources. Hardware validation is still required.

View File

@ -9,10 +9,11 @@
</p>
<p align="center">
<a href="docs/releases.md">Portable releases</a> ·
<a href="docs/development/releases.md">Portable releases</a> ·
<a href="#quick-start">Quick start</a> ·
<a href="docs/README.md">Documentation</a> ·
<a href="docs/changelogs.md">What's new</a> ·
<a href="docs/development.md">Development</a>
<a href="docs/development/README.md">Development</a>
</p>
## Choose your tool
@ -20,43 +21,43 @@
<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>
<a href="docs/pptx-reporter/README.md"><img src="crates/pptx-reporter/assets/app-icon.png" width="72" height="72" alt="PPTX Reporter icon"></a>
<h3><a href="docs/pptx-reporter/README.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>
<p><a href="docs/pptx-reporter/visual-guide.md">Visual walkthrough</a> · <a href="docs/pptx-reporter/README.md">Guide</a> · <a href="docs/pptx-reporter/report-formats.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>
<a href="docs/rundown-converter/README.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/README.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>
<p><a href="docs/rundown-converter/README.md">Guide</a> · <a href="docs/rundown-converter/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>
<a href="docs/midra-layout/README.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/README.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>
<p><a href="docs/midra-layout/README.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>
<a href="docs/ascii-names/README.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/README.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>
<p><a href="docs/ascii-names/README.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>
<a href="docs/exporter/README.md"><img src="tools/assets/exporter/app-icon.png" width="72" height="72" alt="Document Exporter icon"></a>
<h3><a href="docs/exporter/README.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>
<p><a href="docs/exporter/README.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>
@ -70,14 +71,14 @@
## Quick start
**Start with a portable app:** see [release bundles and platform instructions](docs/releases.md).
**Start with a portable app:** see [release bundles and platform instructions](docs/development/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.
[Apple Silicon or Intel](docs/development/releases.md#macos). Keep the bundled FFprobe beside the app.
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.
and generate. The [illustrated guide](docs/pptx-reporter/visual-guide.md) walks through each step;
a [Windows quick start](docs/pptx-reporter/windows-quickstart.txt) is also available.
<details>
<summary><strong>Run from source</strong> — Rust apps and Python exporter</summary>
@ -101,7 +102,7 @@ python3 tools/exporter.py presentation.pptx --output pdf,images
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.
See [development setup](docs/development/README.md) for prerequisites and checks.
</details>
@ -128,7 +129,7 @@ local VectorCraft CLI. See [formats, dependencies and licensing builds](docs/int
| 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) |
| Build and contribute | [Development](docs/development/README.md) · [CI and coverage](docs/development/ci.md) · [Cross builds and releases](docs/development/releases.md) |
| Desktop integration | [App icons and launchers](docs/development/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/planning/program-task-list.md) |

View File

@ -1,4 +1,4 @@
//! Application palettes adapted from SOTV's song database; see docs/midra-layout.md.
//! Application palettes adapted from SOTV's song database; see docs/midra-layout/README.md.
use super::*;
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)]

33
docs/README.md Normal file
View File

@ -0,0 +1,33 @@
# Documentation
[Project portal](../README.md) · [Changelogs](changelogs.md) · [Development](development/README.md)
## Tools
| Tool | Start here | Reference and background |
| --- | --- | --- |
| PPTX Reporter | [Guide](pptx-reporter/README.md) · [Visual walkthrough](pptx-reporter/visual-guide.md) | [Report formats](pptx-reporter/report-formats.md) · [Windows quick start](pptx-reporter/windows-quickstart.txt) · [Portable quick start](pptx-reporter/portable-quickstart.txt) |
| Rundown Converter | [Guide](rundown-converter/README.md) · [Portable quick start](rundown-converter/portable-quickstart.txt) | [Corpus findings](rundown-converter/corpus.md) · [Plan](rundown-converter/plan.md) |
| Midra Layout | [Guide](midra-layout/README.md) | [Resolutions and cropping](midra-layout/resolutions.md) · [Device checks](midra-layout/device-check.md) · [Plan](midra-layout/plan.md) |
| ASCII Names | [Guide](ascii-names/README.md) | [Changelog](ascii-names/changelog.md) |
| Document Exporter | [Guide](exporter/README.md) | [Changelog](exporter/changelog.md) |
| MPC-HC Companion | [Setup and development](../companion-modules/media-player-classic/README.md) | [Changelog](media-player-classic/changelog.md) |
## Shared resources
- **Development:** [setup and checks](development/README.md), [CI and coverage](development/ci.md), [builds and portable releases](development/releases.md), [application artwork](development/releases.md#application-artwork).
- **File and device contracts:** [interface index](interfaces/README.md), including versioned examples and compatibility rules.
- **Starter files:** [Midra Layout templates](../README.md#midra-layout-templates) in [templates/midra-layout](templates/midra-layout/).
- **Release history:** [v0.3.0 notes](releases/v0.3.0.md) and [per-tool changelogs](changelogs.md).
- **Future work:** [ideas](../Ideas.md), [program task list](planning/program-task-list.md), [Flipper Link feasibility](planning/flipper-link.md).
## Where documentation belongs
Keep each tool's guide, plans, screenshots and changelog in its named folder.
Shared contributor instructions live in `development/`, historical release notes
in `releases/`, and cross-tool research in `planning/`. The Companion setup guide
stays beside its module source.
Keep save/export contracts and their versioned examples in `interfaces/`, and
reusable starter documents in `templates/`. These files are also used by tests;
update incoming links and code or packaging references whenever a document moves.

View File

@ -1,6 +1,8 @@
# ASCII names
<img src="../crates/ascii-names/assets/app-icon.png" width="96" alt="Application icon">
[Documentation](../README.md) · [Changelog](changelog.md)
<img src="../../crates/ascii-names/assets/app-icon.png" width="96" alt="Application icon">
A small Rust application for cleaning filenames before using a folder on an
ASCII-only computer. Run it on your modern computer while the USB drive is plugged in.

View File

@ -4,6 +4,8 @@
## Unreleased
- Group the guide and supporting documentation in this tool’s folder; update portal, cross-document and packaging links for the new paths.
- Add ImageGen application artwork in PNG, Windows ICO and macOS ICNS formats. Embed native icons and support Linux/BSD desktop entries and macOS app launchers; native Windows/macOS visual checks remain required.
## 2026-11-13

View File

@ -3,7 +3,7 @@
Short internal notes for testing and bookkeeping, newest first. Existing history
is only partially backfilled; Git has the full record.
- [Midra Layout](midralayout/changelog.md) (including the Python device probe)
- [Midra Layout](midra-layout/changelog.md) (including the Python device probe)
- [PPTX Reporter](pptx-reporter/changelog.md)
- [Rundown Converter](rundown-converter/changelog.md)
- [ASCII Names](ascii-names/changelog.md)

View File

@ -1,5 +1,7 @@
# Development
[Documentation](../README.md) · [CI and coverage](ci.md) · [Releases](releases.md)
## Layout and workflow
| Directory | Purpose |
@ -13,9 +15,9 @@
Prototype in Python, then add a Rust workspace member when the workflow is
stable. Retire the Python implementation once the Rust port is validated.
The PPTX reporter is now Rust-only; the document exporter remains Python.
The [rundown converter](rundown-converter.md) is a separate Rust workspace member
with CLI and egui interfaces. Its [implementation checklist](rundown-converter-plan.md)
and [evaluation corpus](rundown-corpus.md) track coverage and remaining limitations.
The [rundown converter](../rundown-converter/README.md) is a separate Rust workspace member
with CLI and egui interfaces. Its [implementation checklist](../rundown-converter/plan.md)
and [evaluation corpus](../rundown-converter/corpus.md) track coverage and remaining limitations.
Avoid speculative shared crates; extract common code when multiple tools need it.
The root `Cargo.toml` owns workspace metadata, the shared version and build
@ -57,6 +59,6 @@ Its tests generate synthetic XLSX inputs and never require private source files
or network downloads. The existing workspace test, lint, Rustdoc and coverage
commands include both tools; reporter release packaging remains separate.
The [ASCII filename cleaner](ascii-names.md) is a separate Rust workspace member.
The [ASCII filename cleaner](../ascii-names/README.md) is a separate Rust workspace member.
Run `cargo run --locked -p ascii-names` for its drag-and-drop window, or pass a
folder for CLI cleanup. It uses the same workspace checks and coverage gates.

View File

@ -5,7 +5,7 @@ Jenkins must use a Multibranch Pipeline supplying `BRANCH_NAME`, with the
The current worker runs in a FreeBSD jail; the Tools stage logs `uname -sr`.
Older jails without `renameat2` verify the ASCII cleaner's safe refusal instead
of its successful-rename paths. Those paths must also run on a supported host;
see [FreeBSD test coverage](ascii-names.md#freebsd-ci-hosts).
see [FreeBSD test coverage](../ascii-names/README.md#freebsd-ci-hosts).
SCM credentials, webhooks and the publication mount are administrator setup.
CI checks formatting, Clippy, rustdoc, Python/Rust tests and
whole-workspace Rust coverage. It never creates tags or release artifacts.

View File

@ -221,7 +221,7 @@ replace its OS icon. Their PNG/ICO/ICNS files are available for custom shortcuts
the Companion README displays its module icon. Shared libraries, CI scripts,
packaging helpers and `progress.py` are not standalone applications.
Launcher output is described in [the desktop launcher contract](interfaces/desktop-launchers.md).
Launcher output is described in [the desktop launcher contract](../interfaces/desktop-launchers.md).
Automated checks validate icon containers and launcher output on Linux. Finder,
Dock, Windows Explorer/taskbar and individual Wayland desktop behavior still
need native visual checks. The macOS launchers are not signed or notarized.

View File

@ -1,6 +1,8 @@
# Export presentations and PDF pages
<img src="../tools/assets/exporter/app-icon.png" width="96" alt="Application icon">
[Documentation](../README.md) · [Changelog](changelog.md)
<img src="../../tools/assets/exporter/app-icon.png" width="96" alt="Application icon">
```sh
python3 tools/exporter.py presentation.pptx --output pdf,images

View File

@ -4,6 +4,8 @@
## Unreleased
- Group the guide and supporting documentation in this tool’s folder; update portal, cross-document and packaging links for the new paths.
- Add ImageGen application artwork in PNG, Windows ICO and macOS ICNS formats. Artwork is available for shortcuts and documentation; the tool remains hosted by its terminal or Companion.
## 2026-10-20

20
docs/interfaces/README.md Normal file
View File

@ -0,0 +1,20 @@
# File and device interfaces
[Documentation](../README.md) · [Midra Layout guide](../midra-layout/README.md)
These contracts describe persistent formats, compatibility, validation and device
transfers. Versioned examples live beside the relevant contract and are exercised
by regression tests.
| Contract | Contents |
| --- | --- |
| [Midra Layout project](midra-layout.md) | JSON project versions, SVG geometry, validation and migration |
| [Application settings](midra-layout-settings.md) | Per-user preferences and settings versions |
| [Geometry exchange](midra-layout-exchange.md) | Import/export formats, precision, omissions and round trips |
| [Recovery files](midra-layout-recovery.md) | Recovery storage and restore behavior |
| [Device import](midra-device-import.md) | Read-only device geometry import |
| [Device send](midra-device-send.md) | Reviewed writes, crop conversion and restore diagnostics |
| [Input previews](midra-input-preview.md) | Device snapshot retrieval and caching |
| [Desktop launchers](desktop-launchers.md) | Generated shortcuts and launcher metadata |
For report output semantics, see [PPTX Reporter formats](../pptx-reporter/report-formats.md).

View File

@ -2,7 +2,7 @@
Implementation: [`tools/midra_probe.py`](../../tools/midra_probe.py).
Tests: [`tests/test_midra_probe.py`](../../tests/test_midra_probe.py).
Hardware evidence and usage: [Eikos check](../midra-layout-device-check.md).
Hardware evidence and usage: [Eikos check](../midra-layout/device-check.md).
## Snapshot
@ -27,7 +27,7 @@ Geometry extraction uses these paths below `device`:
## Container SVG
This uses the existing [geometry SVG marker](midra-layout.md#svg-geometry-exchange-version-1),
This uses the existing [geometry SVG marker](midra-layout.md#legacy-svg-geometry-exchange-version-1),
`data-midra-layout-geometry="1"`, so a full-screen container is not mistaken for
an ignorable background. Root `width`, `height`, and `viewBox` come from the device
canvas. One or two rectangles are emitted in explicit `--layers` order, with IDs

View File

@ -1,6 +1,8 @@
# Midra Layout
<img src="../crates/midra-layout/assets/app-icon.png" width="96" alt="Application icon">
[Documentation](../README.md) · [Changelog](changelog.md) · [Interfaces](../interfaces/README.md) · [Plan](plan.md)
<img src="../../crates/midra-layout/assets/app-icon.png" width="96" alt="Application icon">
A native Rust/egui workspace for positioning rectangular layers, with offline editing
and an explicit Eikos 4K device link.
@ -127,7 +129,7 @@ choices as draw.io imports.
The draw.io adapter accepts single-page `.drawio`/`.xml` files (including native
compression) and raw or once-percent-encoded `mxGraphModel` clipboard XML, like
[the supplied clipboard fixture](../crates/midra-layout/tests/fixtures/drawio-rectangle.txt).
[the supplied clipboard fixture](../../crates/midra-layout/tests/fixtures/drawio-rectangle.txt).
Draw.io coordinates map **1:1 to screen pixels**, with a top-left origin. This is
an explicit import convention; no page-scale, physical-unit or viewport-size
conversion is inferred. Missing X/Y means zero. Decimal dimensions are preserved.
@ -296,7 +298,7 @@ with both sizing strategies and Centered crop conversion readback-tested on
Eikos 3.3.10. Program sending is enabled by a manual preference. Ordinary local
editing does not send; linked send is a direct user action. Physical-output
comparison, broader firmware coverage and non-Centered/masked conversion remain
[acceptance/backlog work](midra-layout-plan.md#remaining-acceptance-and-release-checks).
[acceptance/backlog work](plan.md#remaining-acceptance-and-release-checks).
Visible-box center readouts are distinct from crop-corrected device containers.
Internal precision is retained; views show one decimal and exports whole pixels.
@ -310,8 +312,8 @@ corner conversion, group drag/undo, selection boxes, alignment targets, and GUI
paste/focus behavior. Layer-list scrolling uses the wheel or scrollbar so dragging
across list entries cannot accidentally scroll while selecting.
See the [project plan](midra-layout-plan.md) and
[resolution/cropping specification](midra-layout-resolutions.md) for the implemented
See the [project plan](plan.md) and
[resolution/cropping specification](resolutions.md) for the implemented
geometry model and remaining hardware-verification work.
Each layer row has **Lock / Locked** and **Hide / Show** buttons. Locked layers
@ -546,7 +548,7 @@ pixels, advanced crops in usable-input pixels, combined retained native bounds,
visible size/center, and projected full-input geometry. These values are not a
verified device recipe: Centered-mode container behavior, crop units/limits and
quantization still require offline firmware verification. No hardware commands
are generated or sent. See [the resolution model](midra-layout-resolutions.md)
are generated or sent. See [the resolution model](resolutions.md)
for equations and worked examples.
## Display/export precision and midpoint handles
@ -672,8 +674,8 @@ cell IDs; generated HTML labels and raster text fallbacks are ignored. Draw.io
may crop and rebase that SVG unless the exported diagram includes the background
layer. These exports round-trip whole-pixel visible-box geometry, not
source/crop settings; JSON preserves the full project. See the
[geometry exchange contract and native draw.io checks](interfaces/midra-layout-exchange.md)
and [project save contract](interfaces/midra-layout.md).
[geometry exchange contract and native draw.io checks](../interfaces/midra-layout-exchange.md)
and [project save contract](../interfaces/midra-layout.md).
Visual crop mode also provides **Reset crop** beside **Done adjusting crop** in
layer properties. It restores 100% content zoom and centered offsets, keeps the
@ -725,7 +727,7 @@ and are not included in project JSON or geometry exports.
The SOTV palettes are bundled with the app from
`sotv/song_database/styles/themes/` in the sibling `SOTV_Websites` repository;
Corporate Light uses `styles/base/variables.css`. No sibling repository is needed
to build or run Midra Layout. See the [theme catalog and settings contract](interfaces/midra-layout-settings.md)
to build or run Midra Layout. See the [theme catalog and settings contract](../interfaces/midra-layout-settings.md)
for names, source files, stable IDs and palette adaptations.
### Saved application options
@ -750,7 +752,7 @@ Unreadable, malformed or unsupported settings use defaults and show an Options
error; the original file is preserved and saving is disabled until the file is
repaired or moved and the application restarted. Write failures keep options
active in memory and offer **Retry saving options**. No project data, images or
clipboard contents are stored here. The [settings interface](interfaces/midra-layout-settings.md)
clipboard contents are stored here. The [settings interface](../interfaces/midra-layout-settings.md)
documents the file and compatibility rules.
**Keep aspect ratio when resizing** is also available below the position/size
@ -811,8 +813,8 @@ means all changed fields matched device readback. There are no automatic sends
from edits, imports or undo. Closing the connection window does not cancel a send
already started; wait for its result before loading another project.
See [hardware checks and limitations](midra-layout-device-check.md) and the
[device exchange contract](interfaces/midra-device-send.md). The footer's ONLINE
See [hardware checks and limitations](device-check.md) and the
[device exchange contract](../interfaces/midra-device-send.md). The footer's ONLINE
status reflects the last successful read, not continuous polling.
## Layer management
@ -978,7 +980,7 @@ path and failures. A corrupt/unsupported recovery file is preserved with autosav
paused; Retry recovery attempts to load it again. For a write failure, Retry
attempts to save again. New project explicitly replaces the recovery copy.
See the [recovery file contract](interfaces/midra-layout-recovery.md).
See the [recovery file contract](../interfaces/midra-layout-recovery.md).
Right-click a layer in the viewport for **Rename layer…** / **Delete layer** alongside
the existing tools. Layer-list rows have a compact menu with just those two actions.
@ -1014,7 +1016,7 @@ The returned resolution/freshness comes from the device; this is not a full-size
source recording. Existing image-size/aspect warnings apply before adding.
Added stills are fixed references with independent hide/show/remove controls and
are embedded in saved projects. They do not become layer-content textures or
change source routing. See the [input preview contract](interfaces/midra-input-preview.md).
change source routing. See the [input preview contract](../interfaces/midra-input-preview.md).
Opening a project or restoring recovery now reads, validates and decodes embedded
references in a worker. The current editor stays intact until the whole project

View File

@ -4,6 +4,8 @@
## Unreleased
- Group the guide and supporting documentation in this tool’s folder; update portal, cross-document and packaging links for the new paths.
- Add manual Midra input-still capture through the verified WebRCS PNG endpoint, with preview/Add as reference, one request at a time and a five-second minimum interval. No live polling or device-setting writes; active-input 512 × 288 and inactive blank-image responses checked on the Eikos.
- Load project/recovery files and decode embedded references in a background worker, install atomically, preserve work on errors/cancel and pause recovery autosave while loading. Reconcile the historical plan into completed implementation, remaining features and separate hardware/platform acceptance checks.

View File

Before

Width:  |  Height:  |  Size: 13 KiB

After

Width:  |  Height:  |  Size: 13 KiB

View File

Before

Width:  |  Height:  |  Size: 15 KiB

After

Width:  |  Height:  |  Size: 15 KiB

View File

Before

Width:  |  Height:  |  Size: 12 KiB

After

Width:  |  Height:  |  Size: 12 KiB

View File

@ -88,7 +88,7 @@ The helper has no device write operation, bypasses system proxies, refuses
redirects, bounds reads to 32 MiB and never overwrites an existing output file.
Snapshots may contain network/private configuration; keep them out of Git and
sanitize before sharing. Its exchange contract is documented in
[interfaces](interfaces/midra-device-import.md).
[interfaces](../interfaces/midra-device-import.md).
## Reviewed send and cropped-layer round trip
@ -114,7 +114,7 @@ TAKE, input configuration, output configuration, masks and effects were not chan
The installed WebRCS bundle maps crop edges linearly from 0–65535 to 0–100% or
0–contentWidth/contentHeight pixels. Its layer size limits are 0–65535 and center
limits −67268–67268; this adapter requires positive dimensions. These findings
support the [device exchange contract](interfaces/midra-device-send.md).
support the [device exchange contract](../interfaces/midra-device-send.md).
These tests verify firmware acceptance, readback and mathematical import round trip.
They do not replace visual comparison on a physical screen with a known test image;
@ -165,4 +165,4 @@ images/state stay temporary and are not committed.
The implementation fetches a still only on demand, limits concurrent requests
to one and enforces a five-second minimum interval. It does not change snapshot
enable/size, input routing, capture-library commands or any preset.
See [input preview interface](interfaces/midra-input-preview.md).
See [input preview interface](../interfaces/midra-input-preview.md).

View File

@ -6,9 +6,9 @@ original draft checklist: unchecked items below are actual remaining work,
not already implemented features awaiting a historical milestone.
The original visual proposals are retained below for design context.
The [user guide](midra-layout.md) describes current controls; the
[device-send contract](interfaces/midra-device-send.md) and
[hardware findings](midra-layout-device-check.md) distinguish automated tests,
The [user guide](README.md) describes current controls; the
[device-send contract](../interfaces/midra-device-send.md) and
[hardware findings](device-check.md) distinguish automated tests,
device readback and physical-screen acceptance.
## Completed implementation
@ -103,7 +103,7 @@ device readback and physical-screen acceptance.
Input capture was tested with the connected Eikos on 2026-11-14: a read-only GET
returned a 512 × 288 PNG from active input 3; inactive input 1 returned a blank
128 × 128 PNG. See [snapshot contract](interfaces/midra-input-preview.md).
128 × 128 PNG. See [snapshot contract](../interfaces/midra-input-preview.md).
No input routing, snapshot settings, still-library slot or layer was modified.
Snapshot dimensions/freshness are device-controlled and broader firmware behavior
remains unverified.
@ -156,7 +156,7 @@ viewport occupies the left; the fixed right inspector groups the layer list,
corner selector, offsets, size and WebRCS outputs in reading order. Thin outlines,
corner markers, center crosshairs and dimension guides make selection unambiguous.
![Concept A: dark operator workspace](design/midra-layout/a-concept.svg)
![Concept A: dark operator workspace](design/a-concept.svg)
Best for working beside show-control tools. The tradeoff is less contrast against
dark reference images; add a contrasting outline halo and an outline-only mode.
@ -169,7 +169,7 @@ A light inspector and drafting surface with screen-coordinate rulers. The same
placement workflow emphasizes measurements and field readability. The artwork
retains its own colors independently of the UI theme.
![Concept B: light workspace with coordinate rulers](design/midra-layout/b-concept.svg)
![Concept B: light workspace with coordinate rulers](design/b-concept.svg)
Best for daytime preparation and detailed artwork matching. It uses more visible
measurement marks and can feel busier; rulers and guides should be optional. Its
@ -181,7 +181,7 @@ A wider viewport and narrower contextual inspector. This proposal illustrates th
multi-selection state: a named reference layer, explicit alignment actions
and a compact per-layer coordinate table. The layer list remains on the right.
![Concept C: compact workspace with two selected layers](design/midra-layout/c-concept.svg)
![Concept C: compact workspace with two selected layers](design/c-concept.svg)
Best for repeated placement and comparison once the basic workflow is familiar.
Less space for numeric explanations makes it weaker as the initial default.

View File

@ -194,9 +194,9 @@ crop on each vertical side. The retained native region is 600 × 500, scaled by
Implemented device adapter: supports both an **output-sized Midra layer with internal
cropping** and a **source-aspect layer container with derived sizing
and cropping**. These use distinct container sizing algorithms, described in
[the device exchange contract](interfaces/midra-device-send.md), with hardware
[the device exchange contract](../interfaces/midra-device-send.md), with hardware
write/readback checks on Eikos 3.3.10. Physical-screen comparison remains outstanding. See
[remaining acceptance checks](midra-layout-plan.md#remaining-acceptance-and-release-checks).
[remaining acceptance checks](plan.md#remaining-acceptance-and-release-checks).
The intended hardware aspect choice is **Centered**, as requested. The

View File

@ -1,7 +1,7 @@
# Flipper Link: feasibility study
Status: proposed tool; no implementation or hardware validation yet.
Research date: 2026-11-06. [Back to future ideas](../Ideas.md).
Research date: 2026-11-06. [Back to future ideas](../../Ideas.md).
## Verdict

View File

@ -1,10 +1,12 @@
# PPTX reporter
<img src="../crates/pptx-reporter/assets/app-icon.png" width="96" alt="Application icon">
[Documentation](../README.md) · [Changelog](changelog.md) · [Visual walkthrough](visual-guide.md) · [Report formats](report-formats.md)
<img src="../../crates/pptx-reporter/assets/app-icon.png" width="96" alt="Application icon">
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).
For a walkthrough with screenshots, see the [user guide](visual-guide.md).
```sh
cargo run --locked --bin pptx-reporter-gui
@ -38,7 +40,7 @@ subfolders. Reports are regenerated; extracted videos are reused unless
HTML, Markdown, plain text, JSON, Typst, PDF, compact PDF and Ontime are supported.
Durations account for per-shape trims. Loops and unsupported timing stay visible
in reports but are omitted from Ontime and playback totals. Extracted media
remains unchanged. See [report options and semantics](pptx-videos.md).
remains unchanged. See [report options and semantics](report-formats.md).
PDF compilation and fonts are embedded; no Typst installation or package
downloads are needed. FFprobe is discovered beside the app, in its `bin/`
@ -48,7 +50,7 @@ On Windows, extract the whole portable ZIP and launch `pptx-reporter-gui.exe`.
`pptx-reporter.exe` provides the CLI and opens the GUI when given no arguments.
Linux desktop builds need windowing/OpenGL libraries at runtime.
See [development](development.md) for source checks and [releases](releases.md)
See [development](../development/README.md) for source checks and [releases](../development/releases.md)
for Cross builds, packaging and dependency provenance.
## Batches and video folders

View File

@ -4,6 +4,8 @@
## Unreleased
- Group the guide and supporting documentation in this tool’s folder; update portal, cross-document and packaging links for the new paths.
- Add ImageGen application artwork in PNG, Windows ICO and macOS ICNS formats. Embed native icons and support Linux/BSD desktop entries and macOS app launchers; native Windows/macOS visual checks remain required.
## 2026-11-03

View File

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 47 KiB

View File

Before

Width:  |  Height:  |  Size: 44 KiB

After

Width:  |  Height:  |  Size: 44 KiB

View File

Before

Width:  |  Height:  |  Size: 36 KiB

After

Width:  |  Height:  |  Size: 36 KiB

View File

Before

Width:  |  Height:  |  Size: 20 KiB

After

Width:  |  Height:  |  Size: 20 KiB

View File

@ -1,6 +1,6 @@
# Report formats and timing semantics
Use the Rust CLI below, or see the [illustrated desktop guide](user-guide.md).
Use the Rust CLI below, or see the [illustrated desktop guide](visual-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.
@ -141,4 +141,4 @@ line logs instead. `NO_COLOR` disables colors; `TERM=dumb` also disables animati
Multiple PPTX files, folders of videos, and folders containing PPTX files or
video subfolders use the same timing and report rules. Batches produce one
combined export with named Ontime groups, ordered by filename. See
[batch examples and folder rules](rust-reporter.md#batches-and-video-folders).
[batch examples and folder rules](README.md#batches-and-video-folders).

View File

@ -20,7 +20,7 @@ The default window is 760 × 560. **Setup** and **Results** stay at the top;
the action button, progress and Cancel stay at the bottom. At smaller sizes or
with enlarged text, the active pane can scroll without hiding those controls.
![Start screen with the presentation picker and drop area](images/reporter/01-start.png)
![Start screen with the presentation picker and drop area](images/01-start.png)
## 2. Choose what to create
@ -42,7 +42,7 @@ you adjust any selection.
The example below uses Reports only, with PDF, Markdown and Ontime selected.
![Selected presentation, save location and report formats](images/reporter/02-options.png)
![Selected presentation, save location and report formats](images/02-options.png)
Click the purple action button. Its label follows your mode: **Generate
reports**, **Extract videos**, or **Extract & generate reports**.
@ -60,7 +60,7 @@ not its contents. Results scroll independently of the bottom action bar.
You can switch tabs during a run; input and format controls stay disabled until
it finishes. Errors remain visible in the bottom bar.
![Completed run with report files and Open actions](images/reporter/03-results.png)
![Completed run with report files and Open actions](images/03-results.png)
The default output is beside your presentation:
@ -86,11 +86,11 @@ 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)
![Compact PDF preview showing a trimmed video and a looping video](images/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)
which contains general report metadata. See [Ontime details](report-formats.md#ontime-import)
for skipped events and choosing your show start time.
## If something needs attention
@ -103,5 +103,5 @@ for skipped events and choosing your show start time.
- **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).
For CLI options and exact playback semantics, see [Reporter](README.md)
and [Report options](report-formats.md).

View File

@ -1,12 +1,14 @@
# Rundown converter
<img src="../crates/rundown-converter/assets/app-icon.png" width="96" alt="Application icon">
[Documentation](../README.md) · [Changelog](changelog.md) · [Corpus findings](corpus.md) · [Plan](plan.md)
<img src="../../crates/rundown-converter/assets/app-icon.png" width="96" alt="Application icon">
Status: first implementation, available from source. A Rust core powers both the
CLI and egui desktop app, styled like the [PPTX reporter](rust-reporter.md).
CLI and egui desktop app, styled like the [PPTX reporter](../pptx-reporter/README.md).
It reads XLSX and UTF-8 CSV/TSV, infers columns, preserves untimed gaps and exports
Ontime JSON or normalized XLSX. Ambiguous documents stop for clarification. See the
[development plan](rundown-converter-plan.md) and [sample findings](rundown-corpus.md).
[development plan](plan.md) and [sample findings](corpus.md).
## Quick start
@ -280,7 +282,7 @@ into one review issue with the affected cells; recalculate and save those files
in Excel or LibreOffice. The converter cannot determine whether cached values are
stale. CSV/TSV uses UTF-8, quoted fields and comma/semicolon/tab detection.
Legacy XLS, ODS, Word, PDF and scans are not yet supported. A
[PDF feasibility trial](rundown-corpus.md#pdf-feasibility-trial) recovered table
[PDF feasibility trial](corpus.md#pdf-feasibility-trial) recovered table
text from the supplied PDFs but could not establish a complete timer schedule;
PDF importer work is paused for now. Input files are limited
to 32 MiB; XLSX expanded content is limited to 128 MiB.
@ -376,7 +378,7 @@ JSON export. A Typst source/PDF report remains a stretch goal.
The adapter targets Ontime 4 native project JSON. Its events and schedule metadata
were checked with the Ontime 4.15.1 native parser; see the
[verification record](rundown-corpus.md#ontime-verification). Import the generated
[verification record](corpus.md#ontime-verification). Import the generated
project through Ontime's project manager. All starts are currently exported
unlinked, including derived starts, so later anchors survive edits to earlier
cues. Timers use duration lock and manual end actions.
@ -541,18 +543,18 @@ before a chosen anchor if the user explicitly allows intermediate starts to move
Fixed restart times stay protected. Impossible requests must report the available
capacity; existing overlaps must be accounted for before claiming new buffer.
Every adjusted schedule must pass validation again before export. See the
[buffer design](rundown-converter-plan.md#optional-buffer-adjustment).
[buffer design](plan.md#optional-buffer-adjustment).
## Expanding coverage
The [sample findings](rundown-corpus.md) list the supplied documents, public
The [sample findings](corpus.md) list the supplied documents, public
workbooks and unresolved interpretation questions. Further examples should keep
table structure, cell formats and representative time values when redacted.
Five user-approved source workbooks are tracked in [rundowns](../rundowns/README.md)
Five user-approved source workbooks are tracked in [rundowns](../../rundowns/README.md)
and exercised by offline regression tests alongside the synthetic fixtures. Other
local originals, PDFs and generated exports remain untracked.
See [all tools](../README.md) and [repository development](development.md).
See [all tools](../../README.md) and [repository development](../development/README.md).
In Setup → General options, **Default break name** names unnamed gaps and the
events created from them. Source break names and individual event titles take

View File

@ -4,6 +4,8 @@
## Unreleased
- Group the guide and supporting documentation in this tool’s folder; update portal, cross-document and packaging links for the new paths.
- Add ImageGen application artwork in PNG, Windows ICO and macOS ICNS formats. Embed native icons and support Linux/BSD desktop entries and macOS app launchers; native Windows/macOS visual checks remain required.
## 2026-11-09

View File

@ -2,13 +2,13 @@
The supplied corpus now includes five XLSX workbooks (seven sheets) and two PDFs.
The five workbooks are tracked at the user's request, with normalized filenames
and unchanged contents; see the [fixture inventory](../rundowns/README.md) and
[original-name/checksum manifest](../rundowns/sources.json). Four offline integration
and unchanged contents; see the [fixture inventory](../../rundowns/README.md) and
[original-name/checksum manifest](../../rundowns/sources.json). Four offline integration
tests exercise all seven sheets through the real reader and pipeline. PDFs and
generated exports remain ignored. Seven public XLSX downloads and three public
CSV files remain local evaluation inputs under `downloads/rundown-corpus/`.
The [public source manifest](../crates/rundown-converter/tests/public-corpus.json)
The [public source manifest](../../crates/rundown-converter/tests/public-corpus.json)
records download URLs, source pages, SHA-256 hashes and retrieval date. Downloads
are manual research inputs, never a network dependency of CI. Templates are not
a representative accuracy benchmark; these observations establish specific

View File

@ -2,7 +2,7 @@
Status: the XLSX/CSV release candidate is available with a shared core, CLI and
egui interface. User-facing scope and current limitations are in
[Rundown converter](rundown-converter.md); [corpus findings](rundown-corpus.md)
[Rundown converter](README.md); [corpus findings](corpus.md)
record real inputs and unresolved questions. Unchecked tasks below remain future
work; broader design requirements are not claims of implemented support.
@ -159,7 +159,7 @@ identify a break. No optional synthetic break timer is generated for these gaps.
## 3. Construct the complete IR from times
Apply the policies in the [tool overview](rundown-converter.md#timing-and-breaks).
Apply the policies in the [tool overview](README.md#timing-and-breaks).
Solve constraints within a session while preserving explicit anchors. An explicit
start/end pair yields duration; a start/duration pair yields end. If all three
are present, retain all three plus calculated values for stage 4 to compare.
@ -262,7 +262,7 @@ errors must remain visible with direct corrective actions.
workbook layouts with a provenance manifest. Record findings separately.
- [x] Run a bounded PDF guessing experiment over all 17 supplied pages using
text coordinates and vector table borders. Record recovery and validator
results in the [PDF feasibility trial](rundown-corpus.md#pdf-feasibility-trial).
results in the [PDF feasibility trial](corpus.md#pdf-feasibility-trial).
Pause importer work: column recovery succeeds, but missing durations and
simultaneous tracks prevent dependable whole-document timer conversion.
- [x] Add bounded XLSX and UTF-8 CSV/TSV readers, synthetic regression fixtures,
@ -324,7 +324,7 @@ errors must remain visible with direct corrective actions.
- [ ] Complete usage examples, supported-format matrix, limitations and illustrated
GUI instructions. Add runnable quick-start commands only once they exist.
- [x] Run appropriate Python CI/packaging tests and all Rust gates listed in
[Development](development.md#checks), plus whole-workspace coverage. Preserve
[Development](../development/README.md#checks), plus whole-workspace coverage. Preserve
production GUI coverage and reporter behavior. Record unavailable manual checks.
- [ ] Extend manual packaging/release preparation for both binaries and supported
platforms, including only dependencies this tool needs. CI must not publish releases.

View File

@ -5,7 +5,7 @@ spreadsheet, review inferred columns and schedule corrections, and export an
Ontime project or XLSX. No FFprobe installation is required.
The rundown-converter binary provides the CLI. Run it with --help for options.
Full documentation: https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/rundown-converter.md
Full documentation: https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/rundown-converter/README.md
macOS: these binaries are unsigned. If macOS blocks a trusted download, see
https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/releases.md
https://proxy.dandaedre.com/gitea/Beffroi/beffroi-tools/src/branch/main/docs/development/releases.md

View File

@ -14,5 +14,5 @@ files = [
{ source = "scripts/desktop_icons.py", destination = "scripts/desktop_icons.py", workspace-relative = true },
{ source = "LICENSE", destination = "LICENSES/MIT.txt", workspace-relative = true },
{ source = "assets/fonts/LICENSE", destination = "LICENSES/DejaVu.txt" },
{ source = "docs/rundown-portable-quickstart.txt", destination = "README.txt", workspace-relative = true },
{ source = "docs/rundown-converter/portable-quickstart.txt", destination = "README.txt", workspace-relative = true },
]

View File

@ -34,7 +34,7 @@ files = [
{ source = "scripts/desktop_icons.py", destination = "scripts/desktop_icons.py", workspace-relative = true },
{ source = "LICENSE", destination = "LICENSES/reporter-MIT.txt", workspace-relative = true },
{ source = "assets/fonts/LICENSE", destination = "LICENSES/DejaVu.txt" },
{ source = "docs/portable-quickstart.txt", destination = "README.txt", workspace-relative = true },
{ source = "docs/pptx-reporter/portable-quickstart.txt", destination = "README.txt", workspace-relative = true },
]
[package.bundles.prepare]

View File

@ -74,7 +74,7 @@ def main():
shutil.copy2(ROOT / "LICENSE", licenses / "reporter-MIT.txt")
shutil.copy2(ROOT / "crates/pptx-reporter/assets/fonts/LICENSE", licenses / "DejaVu.txt")
shutil.copytree(args.ffprobe_licenses, licenses / "ffmpeg")
shutil.copy2(ROOT / "docs/windows-quickstart.txt", folder / "README.txt")
shutil.copy2(ROOT / "docs/pptx-reporter/windows-quickstart.txt", folder / "README.txt")
icons = folder / "icons/pptx-reporter"
icons.mkdir(parents=True)
for extension in ("png", "ico", "icns"):

View File

@ -27,7 +27,7 @@ class PortableTests(unittest.TestCase):
licenses = root / "ffmpeg-licenses"
licenses.mkdir()
(licenses / "LICENSE").write_text("fixture notice")
for file in ("LICENSE", "crates/pptx-reporter/assets/fonts/LICENSE", "docs/windows-quickstart.txt",
for file in ("LICENSE", "crates/pptx-reporter/assets/fonts/LICENSE", "docs/pptx-reporter/windows-quickstart.txt",
"crates/pptx-reporter/assets/app-icon.png",
"crates/pptx-reporter/assets/app-icon.ico",
"crates/pptx-reporter/assets/app-icon.icns",