Plan standalone rundown converter and document timing policies
This commit is contained in:
parent
568aaa3c2d
commit
48414bf279
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -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).
|
||||
Loading…
Reference in New Issue