From 48414bf279b433f89639f8c149c5686a3aaaae62 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Tue, 3 Nov 2026 11:47:55 +0100 Subject: [PATCH] Plan standalone rundown converter and document timing policies --- README.md | 5 +- docs/development.md | 3 + docs/rundown-converter-plan.md | 187 +++++++++++++++++++++++++++++++++ docs/rundown-converter.md | 90 ++++++++++++++++ 4 files changed, 283 insertions(+), 2 deletions(-) create mode 100644 docs/rundown-converter-plan.md create mode 100644 docs/rundown-converter.md diff --git a/README.md b/README.md index f8ff04b..ef7ae3a 100644 --- a/README.md +++ b/README.md @@ -30,9 +30,9 @@ 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`. -## Visual guide +## PPTX reporter visual guide -**[Follow the illustrated user guide →](docs/user-guide.md)** +**[Follow the illustrated PPTX reporter guide →](docs/user-guide.md)** Screenshots walk you through choosing a presentation, selecting formats, opening reports, and reading video timings. @@ -42,5 +42,6 @@ opening reports, and reading video timings. - [Reporter](docs/rust-reporter.md) · [Windows quick start](docs/windows-quickstart.txt) - [Report formats and timing semantics](docs/pptx-videos.md) - [Document exports](docs/exporter.md) +- [Rundown converter](docs/rundown-converter.md) (planned) · [Development plan](docs/rundown-converter-plan.md) - [Development](docs/development.md) · [CI and coverage](docs/ci.md) - [Cross builds and portable releases](docs/releases.md) diff --git a/docs/development.md b/docs/development.md index ec53f19..ce6bdf6 100644 --- a/docs/development.md +++ b/docs/development.md @@ -13,6 +13,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 planned [rundown converter](rundown-converter.md) will use a Rust core with +CLI and egui interfaces; its [implementation checklist](rundown-converter-plan.md) +tracks preparation and sample-driven development separately from available tools. Avoid speculative shared crates; extract common code when multiple tools need it. The root `Cargo.toml` owns workspace metadata, the shared version and build diff --git a/docs/rundown-converter-plan.md b/docs/rundown-converter-plan.md new file mode 100644 index 0000000..a3e7f40 --- /dev/null +++ b/docs/rundown-converter-plan.md @@ -0,0 +1,187 @@ +# Rundown converter development plan + +Status: design and task list prepared; sample-driven implementation has not +started. User-facing scope is in [Rundown converter](rundown-converter.md). + +## Architecture + +Planned workspace member: `crates/rundown-converter/`, with binaries +`rundown-converter` and `rundown-converter-gui`. These names are reserved by this +plan only; no empty crate or Cargo member is added during preparation. +Use the reporter's Rust/clap/eframe approach and optional desktop feature. +A Python prototype is optional for investigating a difficult format, not a +second maintained implementation. + +The processing pipeline is: + +```text +source readers -> source tables -> header/column detection -> neutral rundown + -> timing resolution and validation -> Ontime adapter -> file +``` + +Readers retain original cell text, typed values, number formats, merged-cell +ranges and source coordinates when available. A table model separates extraction +from interpretation so format-specific quirks do not leak into the Ontime adapter. +PDF extraction must retain page/position information and expose unreliable reading +order; image-only documents must produce an actionable unsupported/extraction +error until a tested reader exists. Never execute document macros or formulas. +Missing or stale formula results require explicit handling. + +Planned core modules cover readers, detection, neutral model, timing, diagnostics, +export and orchestration. GUI and CLI are thin clients of the same core; neither +contains independent parsing rules. Extract shared reporter UI utilities only +when useful code reuse is demonstrated; do not couple the new model to videos, +FFprobe, Typst or the reporter's sequential timer assumptions. + +## Neutral representation + +Use a versioned serializable model independent of Ontime fields and units. +Represent unresolved facts explicitly; validation produces an exportable model +only when required decisions are resolved. + +| Entity | Information to retain | +| --- | --- | +| Document | Source identity, reader, sheet/table choices, model version, interpretation settings | +| Source reference | File, sheet/page, row/cell or bounding region, original text | +| Rundown/session | Ordered entries, label, date/day context, stage/track where established | +| Entry | Stable identity, cue, title, speaker, notes, additional original columns, event/break/marker kind | +| Timing | Optional explicit start/end, duration, day offset, fixed/relative intent, inferred/resolved values | +| Gap | Known previous end and next start, interval, provenance, explicit or inferred classification | +| Decision | Selected mapping/rule, evidence, alternatives, user overrides | +| Diagnostic | Stable code, severity, source reference, explanation, corrective action | + +Use integer time units, not floating-point arithmetic, for normalized durations +and schedule calculations. Keep wall-clock times plus date/day offsets separate +from elapsed durations. Preserve given and derived values so conflicts are +reportable rather than overwritten. Convert to Ontime milliseconds only in the +adapter. Stable identities should be reproducible for unchanged input; do not +promise identity stability across arbitrary source edits. + +## Detection and clarification + +Combine normalized French/English header aliases, cell types, number formats, +value patterns and consistency across rows. Normalize accents, casing, spacing +and line breaks without losing original text. Evaluate candidate header bands +and mappings jointly instead of assigning columns from individual keywords. + +Account for title blocks above tables, merged/multiline headers, repeated headers, +blank separators, continuation rows, section labels, footnotes and totals. +Account for clock forms such as `09:30`/`9h30`, explicit units such as `15 min`, +spreadsheet time serials, formula results, decimal commas and CSV delimiters. +An unlabelled `10:30` or bare `15` is not sufficient evidence for a time role/unit. +Formatting and keywords are evidence, not proof. + +Calibrate acceptance thresholds and the separation between competing mappings +against examples. Do not present heuristic scores as statistical probabilities. +Report the winning evidence and meaningful alternatives. If required roles or +row classifications remain ambiguous, block export; nonessential columns can +remain preserved metadata with a warning. Never silently drop a possible cue. + +Example diagnostic, with proposed wording: + +```text +AMBIGUOUS_TIME_COLUMN — Sheet “Jour 1”, C4:C28, header “Temps” +Values such as “10:30” could be start times or durations. +Clarify the header to “Début” or “Durée (mm:ss)”, or map column C and its units. +No Ontime file was written. +``` + +Mappings must be possible without modifying originals. CLI options/config and a +GUI mapping panel should select table, header rows, column roles and units. +Reusable mapping profiles should verify expected headers before applying; a +changed document must not silently inherit an unsuitable profile. + +## Timing resolution and export contract + +Apply the policies in the [tool overview](rundown-converter.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, validate agreement using a documented precision tolerance. + +Do not infer an end across an unknown break, another session, another day or a +parallel track. Midnight rollover must be supported by evidence or an explicit +setting. Treat unresolved overlap, negative duration, invalid time and unavailable +final duration as actionable errors. Define zero-duration markers separately from +missing-duration events. Never silently clamp or wrap unsupported target values. + +The Ontime adapter will map absolute starts to independent schedule entries and +link only entries explicitly intended to follow their predecessor. Duration-lock, +end-lock and count-to-end playback are distinct choices: preserving a scheduled +start must not silently enable count-to-end or automated playback. Keep default +end actions manual. Validate target limits, ordering, grouping and project schema. +An established gap remains empty by default; do not use a delay entry to represent +an ordinary lunch break. If visible inferred break cues are implemented, label +and track them separately from source events. + +Export via a temporary file and publish only after complete validation, with +explicit overwrite behavior and cleanup on errors/cancellation. Produce neutral +JSON separately from native Ontime JSON with unmistakable filenames. Diagnostic +preview may remain available on failure, but an invalid project must not be +published. Keep local source paths out of exported project notes by default. + +## CLI and desktop experience + +Proposed CLI operations are inspect, validate and convert; finalize syntax after +sample review. Support explicit output, sheet/table selection, mappings, units, +neutral JSON and overwrite. Provide useful progress, plain redirected logs, +`NO_COLOR`, documented exit codes and structured diagnostics for automation. +CLI operation must not depend on GUI availability or interactive prompts. + +Match the reporter's compact egui layout, purple primary action, native file +picker, drag/drop, recent inputs, output controls, Settings, fixed bottom progress +and Cancel, scrollable content, and Results with Open/Open folder/Copy path. +Add a Review pane for source samples, mappings and the resolved schedule; show +anchored starts, inferred durations, breaks and blockers clearly. Keep controls +usable in small windows and at larger text sizes. Conversion runs on a worker +thread; controls reflect running/cancelled/completed states. Parsing and export +errors must remain visible with direct corrective actions. + +## Ordered task list and acceptance gates + +- [x] Inspect existing CLI, GUI, Ontime export and repository documentation. +- [x] Check official Ontime documentation for schedule gaps and import options. +- [x] Specify neutral model, ambiguity policy, start-time priority and break rules. +- [x] Add separate tool documentation and link it from the repository overview. +- [ ] Inventory supplied examples by format/layout; record intended interpretations + and the user's Ontime version. Decide first-release input coverage from these. +- [ ] Build sanitized fixtures and an expected-result matrix before tuning rules. + Include difficult examples and some held-out layouts to detect overfitting. +- [ ] Confirm a pinned Ontime schema/release and create a minimal import experiment + with independent starts and a lunch gap; verify actual schedule and playback. +- [ ] Scaffold the Rust member, core model, optional GUI and CLI; retain reporter + defaults. Include the new member in workspace CI, documentation and coverage. +- [ ] Implement the required source readers and extraction diagnostics. Test + unsupported/encrypted/corrupt inputs and formula/merged-cell behavior as relevant. +- [ ] Implement detection, explicit mappings and source-located errors; verify + competing headers and misleading time formats fail clearly. +- [ ] Implement timing constraints and gaps. Test known/unknown lunch gaps, + start-only schedules, contradictory triples, missing final duration, overlaps, + midnight/day transitions, zero-duration markers and multiple sessions/tracks. +- [ ] Implement inspect/validate/convert CLI and atomic exports. Test CLI status, + output collisions, cancellation, source preservation and deterministic results. +- [ ] Implement the Ontime adapter and neutral JSON export. Check native imports + against the pinned parser and manually inspect real Ontime behavior; don't rely + solely on JSON snapshots. Verify that later anchors survive earlier edits and + gaps remain visible in the schedule; document playback implications. +- [ ] Implement desktop Setup/Review/Results, mapping corrections and diagnostics. + Verify GUI/CLI parity; manually inspect representative and ambiguous inputs, + resized windows, larger text, long paths, progress and cancellation. +- [ ] Run the supported corpus end to end: each source cue must be represented or + have an explicit reviewed exclusion; every unresolved ambiguity must block export. +- [ ] Complete usage examples, supported-format matrix, limitations and illustrated + GUI instructions. Add runnable quick-start commands only once they exist. +- [ ] Run appropriate Python CI/packaging tests and all Rust gates listed in + [Development](development.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. +- [ ] Commit each completed implementation task with its validation summary. + +## Documentation conventions + +Keep README as a short repository entry point with quick-start examples and links. +Each tool has its own usage page; detailed design/task tracking stays separate. +Use one H1 per page, sentence-case headings, fenced code with a language, ordinary +relative Markdown links and consistent tables/lists. Label planned features and +commands clearly. The existing illustrated guide remains explicitly scoped to the +PPTX reporter; add a separate converter guide when a working GUI can be captured. diff --git a/docs/rundown-converter.md b/docs/rundown-converter.md new file mode 100644 index 0000000..b5ebeb0 --- /dev/null +++ b/docs/rundown-converter.md @@ -0,0 +1,90 @@ +# Rundown converter + +Status: preparation complete; implementation awaits representative rundowns. +This is a separate planned tool, with a Rust core, CLI and egui desktop app +similar to the [PPTX reporter](rust-reporter.md). No converter command is +available yet. The implementation checklist is in the +[development plan](rundown-converter-plan.md). + +## Purpose + +Convert differently formatted conduites (rundowns) into an Ontime project without +manually rebuilding each document. Detect tables, headers, event titles and timing +columns using explainable heuristics. Preserve source order and scheduled start +times, especially when a session resumes after a break. + +When the source is ambiguous, stop export with a precise explanation and ask for +clearer headers or an explicit column mapping. Never silently swap start times +and durations, discard questionable rows, or fill unknown durations with zero. + +## Planned workflow + +1. Open or drop a document, then select a sheet or table if several are plausible. +2. Inspect detected headers, sample rows and a normalized schedule preview. +3. Resolve highlighted ambiguities through column mappings or clearer source + headers. Ordinary unambiguous files should require no manual mapping. +4. Export native Ontime JSON and optionally a neutral JSON representation for + inspection or reuse. Open the result or its output folder. + +The CLI and GUI will use the same detection, validation and export code. CLI +failures will identify the source location and return a nonzero exit status. +Inputs stay unchanged; existing output requires explicit overwrite permission. +Processing is local. Initial supported formats and reader dependencies will be +chosen from the supplied examples; spreadsheet, text, Word and PDF layouts must +not be assumed interchangeable. Scans require a separate extraction strategy. + +## Timing and breaks + +Explicit start times are schedule anchors. Durations can come from a duration +column or an unambiguous start/end pair. The preview will distinguish original +values from calculated values, unresolved values and gaps. + +| Source evidence | Planned interpretation | +| --- | --- | +| Cue at 11:45 lasting 15 minutes; next cue at 13:30 | Preserve a 12:00–13:30 gap and the 13:30 start | +| Named lunch row from 12:00 to 13:30 | Preserve an explicit break with its original label | +| Cue at 11:45; next cue at 13:30; no end or duration | Event duration versus break is unknown; do not invent a lunch break | +| Start 11:45, end 12:00, duration 20 minutes | Report conflicting timing and request clarification | +| Final cue has only a start | Request its end/duration or an explicit non-timed classification | + +Inferring a duration from the next start is allowed only when the source or a +user-selected policy establishes consecutive events. That policy and each +inference must remain visible. A long interval alone does not prove a break. +Do not extend the preceding timer through an established gap or shift an +explicit start to make durations fit. Overlaps, day changes and parallel stages +need explicit interpretation rather than automatic sorting or midnight wrapping. + +Ontime documents independent starts, linked starts and separate duration/end +strategies in [Smart time entry](https://docs.getontime.no/quick-tips/smart-time-entry/). +Its [delay documentation](https://docs.getontime.no/quick-tips/managing-delays/) +also describes schedule gaps absorbing delays. The planned default export will +retain a known unnamed break as a gap, with the following start unlinked. +An optional visible “Break (inferred)” cue can be evaluated during implementation; +it must be visibly synthetic and must not change the following scheduled start. +Schedule preservation does not imply automatic playback or guarantee that an +operator will start an event on time. + +## Output choice + +Native Ontime JSON is the primary target: it lets the exporter control time +relationships and project structure without a second column-mapping step. +Ontime supports project files and spreadsheet interchange; see its +[import/export documentation](https://docs.getontime.no/quick-tips/import-export/). +An XLSX export is a possible later convenience for human editing, not a required +intermediate format. Legacy XLS output is not planned. + +The existing reporter targets Ontime 4. The new adapter will initially target +that family, with the exact tested release/schema recorded before implementation +is accepted. Import and timing behavior must be verified in that release; +consulting documentation alone does not establish compatibility. + +## Examples needed next + +Provide representative originals, including difficult or ambiguous layouts and +at least one missing lunch/break timer. For ambiguous examples, indicate the +intended start, duration and break interpretation where known. Include the +Ontime version you use. Redacted documents are fine if table structure, cell +formats and time values remain representative. Private originals will not be +committed; regression fixtures will be synthetic or explicitly cleared for use. + +See [all tools](../README.md) and [repository development](development.md).