15 KiB
Rundown converter
Status: first implementation, available from source. A Rust core powers both the CLI and egui desktop app, styled like the PPTX reporter. It reads XLSX and UTF-8 CSV/TSV, infers columns, preserves untimed gaps and exports Ontime JSON. Ambiguous documents stop for clarification. See the development plan and sample findings.
Quick start
Run from the repository root:
cargo run --locked -p rundown-converter --bin rundown-converter-gui
cargo run --locked -p rundown-converter --bin rundown-converter -- inspect show.xlsx
cargo run --locked -p rundown-converter --bin rundown-converter -- validate show.xlsx --sheet "Main"
cargo run --locked -p rundown-converter --bin rundown-converter -- convert show.xlsx --sheet "Main" --output show.ontime.json
Try the included synthetic lunch example:
cargo run --locked -p rundown-converter --bin rundown-converter -- convert crates/rundown-converter/tests/fixtures/lunch.csv --output /tmp/lunch.ontime.json
Select a sheet explicitly when a workbook has several. inspect --json exposes
original cells, formulas, formats relevant to timing, and merged ranges.
validate --json gives structured decisions, diagnostics and the IR when available.
convert --neutral exports that neutral IR instead of Ontime JSON. Existing output
requires --overwrite; the source itself cannot be the output. Parent output
directories must already exist. Exit codes: 0 success, 1 read/profile/write failure,
2 unresolved rundown diagnostics (also used by clap for invalid command syntax).
CLI logs are plain text on stderr; JSON results go to stdout.
In the desktop app, choose or drop one file, read its sheets, select a sheet and click Analyze rundown. Review has two views:
- Schedule & corrections combines the schedule preview and row editing in one
table. Start/end/duration, source contents, colored issues, row meaning and
duration corrections are visible together. All rows includes ignored rows;
Included rows hides ignored rows and rows containing only ignored columns,
while keeping notes, markers and breaks; Needs attention shows rows with
diagnostics from the last analysis. Ignored rows can be restored using All rows.
Notes attached to another event keep their own source row and identify their
parent timer instead of duplicating it. Amber means unresolved, red means an
error, and gray means ignored. Unknown values show
?. Click a row number/title to read all original cells. Issues opens the issue navigator, including sheet-level and gap errors; row issue buttons open the relevant explanation. The table fills the remaining space. On narrow windows, timing values stack so corrections remain accessible. Changes require recheck; the timing preview and diagnostics continue to show the previous analysis. - Columns shows inference evidence, per-column role dropdowns, and sample values. Selecting one duration column explicitly resolves duplicate TIMER headers. Metadata keeps a column as Ontime notes without treating its values as timing or titles; Ignore excludes it from inference and Ontime output. Several columns can be metadata or ignored. Auto restores inference; other columns remain included as metadata by default. Expand Remap columns, header and units / advanced profile for header row, duration units and JSON settings (also in Setup).
Click Apply & recheck after corrections. Pending edits retain the issue list and previous preview so you can resolve several rows without losing your place; export and remembering a resolution remain blocked until validation succeeds. Blank duration corrections restore source values. Missing durations and untimed row decisions can be resolved here. Unsupported interpretations, invalid start/end values, conflicting timings and unresolved overlaps retain explicit errors; correct the source when available controls cannot express the intended fix. CLI untimed-row errors also include a labeled source preview.
Resolutions… opens the save/load/remember controls without taking space away from the correction table. Results offers Open, Open output folder and Copy path. Details contains status, completed analysis stage count and the full IR, including original rows. Cancel is observed between analysis stages and before publishing an export; reading a workbook or an active stage finishes first.
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.
Workflow
Open or drop a document and select its sheet/table, then follow five stages:
- Infer column meanings from data across rows. An ambiguous cell can be clarified by other rows, but one meaning must fit the whole column; otherwise return an error asking for clearer headers, corrected values or an explicit mapping.
- Identify untimed gaps and incorporate them into the draft intermediate representation (IR). These breaks occupy schedule time without a shown timer.
- Construct the complete IR from times and gap constraints, preserving original and inferred values. Ask for clarification when required facts remain unknown.
- Check the complete schedule for inconsistencies, including backward times, negative durations, overlaps and contradictory start/end/duration values.
- Generate native Ontime JSON from the validated IR, with optional neutral JSON for inspection or reuse. Open the result or its output folder.
Review and correction controls expose each stage's decisions and errors. CLI and GUI follow this same sequence; export cannot bypass unresolved errors.
The CLI and GUI use the same detection, validation and export code. CLI failures identify the source location and return a nonzero exit status. Inputs stay unchanged; existing output requires explicit overwrite permission. Processing is local. XLSX preserves merged ranges and cached formula values; formulas and macros are never executed. Recalculate and save formula-based workbooks before importing. 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 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.
Timing and breaks
Explicit start times are schedule anchors. Durations can come from a duration column or an unambiguous start/end pair. The preview distinguishes original values from calculated values, unresolved values and gaps.
| Source evidence | 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. Its delay documentation also describes schedule gaps absorbing delays. The export retains a known unnamed break as a gap, with the following start unlinked. Untimed gaps remain in the IR without generating a synthetic timer or displaying a timer duration. An explicitly timed break cue remains distinct from such gaps. 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. Stretch goals are a Typst report (editable source and PDF) and XLS/ODS re-export with normalized columns directly suitable for Ontime import. Actual file-format and column compatibility must be verified against the target release; any required format conversion will be documented. These outputs share the validated IR and are not intermediate steps for native JSON export.
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. 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.
Clarification profiles
Pass --profile mapping.json, or load/edit the same JSON in the desktop app:
{
"header_row": 1,
"columns": {"start": "A", "duration": "B", "title": "G"},
"column_usage": {"C": "metadata", "F": "ignore"},
"expected_headers": {"A": "Heure", "B": "Durée"},
"untimed_as_notes": true,
"row_kinds": {"20": "marker"},
"durations": {"8": "2 min"}
}
This illustrates options, not a profile to apply blindly to the supplied files.
Rows are one-based original worksheet rows; columns use Excel letters. Supported
roles are start, end, duration and title. duration_unit accepts minutes,
seconds, hh:mm, mm:ss or excel. Cell number formats establish Excel time
units where available; otherwise units must be explicit or consistently supported
by independent start/end pairs. Unknown profile keys and changed expected headers
are errors. Explicit mappings still undergo whole-column validation.
column_usage maps column letters to metadata or ignore. Both choices prevent
that column from being inferred as a start, end, duration or title, even when its
header suggests one of those roles. A column cannot also have an explicit timing
or title mapping. Metadata appears in Ontime event notes, including metadata from
rows attached as notes or merged continuations. Ignore removes those cell values
from Ontime notes; rows containing only ignored values need no clarification.
Original cells remain available in the review and neutral IR for retained rows.
These choices are saved in profiles and remembered resolutions; use Apply &
recheck before export. The default inclusion of other source columns is unchanged.
row_kinds accepts event, gap, marker, note and ignore. Notes attach to
the preceding event. Untimed markers remain in the IR but are not exported as
timers. An ignored row is recorded as an explicit exclusion. Duration overrides
retain original cell values and the fact that a correction was requested. Use
expected_headers to guard reusable profiles against changed layouts.
Save resolution as… writes a portable profile JSON, usable with CLI
--profile. Save (overwrite resolution) replaces the loaded/saved profile;
Save as refuses existing files unless its replacement checkbox is enabled.
These actions save decisions, not a rewritten spreadsheet or an Ontime export.
Profiles may contain unfinished decisions; loading one always requires a fresh
analysis. Explicitly loaded profiles use worksheet row numbers, so review their
applicability when the document has changed.
Remember resolution stores a validated profile in the platform's user
configuration directory, under rundown-converter/resolutions (on Linux,
$XDG_CONFIG_HOME/rundown-converter/resolutions, normally
~/.config/rundown-converter/resolutions). The status displays the exact path.
Reuse remembered resolution becomes available for an identical sheet and
loads its decisions for revalidation; Forget removes that remembered file.
Matching includes every cell, timing format, formula, merge, sheet name and row
order, so changed documents cannot silently inherit row corrections. This is
explicit reuse rather than automatic application. Changing file or sheet clears
current decisions. Remembered files contain profile decisions and a hash in their
filename, not a copy of the workbook; they remain local to this machine.
Current limits
One selected sheet represents one sequential, single-day schedule. Parallel tracks, midnight rollover and hierarchical parent/child timers need separate interpretations; the converter does not sort or flatten them automatically. A merged clock window plus individual row durations creates bounded sequential cues. A shared merged duration creates one timer with the other rows retained as notes. Unmerged untimed directions need explicit classification.
A full-width merged text band is treated as a section/footnote and recorded in the IR. Nonempty unmerged text in a time column is a contradiction, not silently ignored. Missing end/duration in a start-only schedule remains unresolved. Recent-file persistence, direct start/end/title editing and portable release bundles remain future work. JSON profiles provide the same supported resolution decisions in both interfaces.
Stretch goal: reserve buffer time
An optional correction mode will shorten timed rows to create a requested buffer in an overcrowded schedule. It will offer equal or proportional cuts, minimum durations and protected rows, with a before/after preview. Original values remain available. Untimed breaks do not contribute time cuts.
Saved time can stay as slack after each event, preserving starts, or be collected 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.
Expanding coverage
The sample findings list the supplied documents, public workbooks and unresolved interpretation questions. Further examples should keep table structure, cell formats and representative time values when redacted. Private originals stay out of Git; regression fixtures are synthetic.
See all tools and repository development.