Plan standalone rundown converter and document timing policies

This commit is contained in:
Dandaedre 2026-11-03 11:47:55 +01:00
parent 568aaa3c2d
commit 48414bf279
4 changed files with 283 additions and 2 deletions

View File

@ -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)

View File

@ -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

View File

@ -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.

90
docs/rundown-converter.md Normal file
View File

@ -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).