Rundown converter
Documentation · Changelog · Corpus findings · Plan
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 or normalized XLSX. 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
cargo run --locked -p rundown-converter --bin rundown-converter -- convert show.xlsx --sheet "Main" --output show.ontime.xlsx
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.
The output extension selects native .json or spreadsheet .xlsx export.
convert --neutral exports the neutral IR to JSON instead of an Ontime project.
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. Setup exposes two General options, also saved in resolution profiles and usable from the CLI:
- Ignore all warnings (
ignore_warnings): try excluding rows with missing start/duration/title, untimed content, orphan notes or unresolved breaks, then rebuild and validate. Column ambiguity, malformed timings, overlaps and other inconsistencies still block export. Manual row and duration decisions are kept. Automatically excluded rows are counted in the summary and remain visible in All rows. Disable the option and recheck to restore them. - Treat rows without a timing as notes (
untimed_as_notes): attach rows without a timing to the preceding event. When both options are enabled, this runs before warning exclusions so notes are kept wherever possible.
Changes take effect on analysis / recheck. A checklist shows Column detection, Gap detection, Schedule construction,
and Consistency checks. Checked green boxes mean Passed; other steps explicitly
say Needs attention, Recheck required, or Not checked.
Blocking column errors open Columns automatically. Row corrections become
available after the timing mapping is unambiguous and rechecked. Spreadsheet
cells marked as times display as HH:MM:SS in samples and the inspector; the
original stored value remains available in the inspector.
When several columns could have the same timing role, the error gives a short
instruction and highlights all candidate columns in amber immediately. The
Choose … column… button scrolls to that candidate group and gives it one slow
brightness pulse with a fixed border, which distinguishes the group when several
mapping issues are present. The short message and button share a line when space
permits. The original inference explanation remains under the subdued Technical details.
Review has two views:
The main navigation and Review view tabs use a subtle purple tint so they remain visually distinct from labels and ordinary actions; the active tab uses the stronger accent.
-
Schedule & corrections combines the schedule preview and row editing in one table. Start/end/duration, titles, colored issues and row types are visible together. Click anywhere on a source row or inferred gap to select it; a subtle tint marks the selection while retaining its status color. Edit row… opens the selected source row editor, including title, start, end and duration corrections. Edit gap… opens an inferred gap’s timing, diagnostics and allocation choice even though it has no source cells. 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 and gaps for context. 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, dim gray means ignored, teal marks gaps, and medium-gray timing values were inferred rather than read directly from the rundown. Start, end and duration are colored independently, so a row can show exactly which values were calculated. An overlap marks both the later cue and its predecessor in red because either timing may need correction; each row’s hover leads with the warning or error severity, code, source location, full explanation and a concrete way to resolve it. Timing inference is conveyed by the table colors instead of repeated in the hover. Row status and editing hints follow as secondary information; raw source cells remain in the double-click inspector. For overlaps, both affected rows explain their side of the conflict. Gaps appear in schedule order with their start, end and elapsed duration (no timer). Named breaks use their source row; inferred gaps update after recheck. Each gap offers Keep gap (default, no timer), Extend previous timing, Add to next timing, and Create event. Create event turns the entire gap into a timed Ontime event; its title defaults to the named break, or “Break”, and can be edited in the gap editor. Double-click the row or use Edit gap… for the additional options.
Click Distribute… directly beneath the gap resolution in the schedule to enable distribution and change its event count and direction. Once enabled, this control reads Across N events and remains clickable; it uses the pending colour until Apply & recheck. The same options remain available in the gap editor. Distribute across neighbours divides the gap equally across N contiguous events:
- Extend previous / Add to next lengthens each of the previous / following N timers.
- Keep gap inserts N untimed intervals, after previous events or before following events.
- Create event inserts N new timed events at those same positions, interleaved with the original events; generated titles include their part number.
Internal start times move, but the combined block’s start and end stay fixed. Original event durations stay unchanged for Keep gap / Create event. Whole-second gaps use whole-second shares, assigning any remainder to the first parts. Insufficient neighbours, intervening gaps or markers, overlaps, and unknown boundaries block the resolution with an actionable error. No partial adjustment is applied for an unavailable resolution. Apply & recheck updates the preview and both Ontime JSON and XLSX exports. Generated events use a distinct blue row tint and title colour, identified by Event from break in the legend; untimed gaps remain teal. Errors and pending changes retain their priority colours. Created events and redistributed intervals remain accessible under Gaps for review and undo. Choose Keep gap and turn distribution off to restore the original interval. Choices persist in
gap_resolutions;gap_optionsholdsdistribute,count,direction(previousorfollowing) andtitle, keyed by the original gap key. If other corrections change those original boundaries, remove the stale choice in Setup or reset decisions and recheck. Column-layout memory does not transfer gap choices. Unknown values show?. Unresolved source rows offer Ignore to set the ignore resolution and Details to open the row editor. Ignoring requires recheck and can be undone under All rows. Ignore all unresolved (N) applies this to unresolved source rows and timed rows missing a title across the sheet, regardless of the current filter. Other timed rows, timing errors and existing manual corrections are excluded. Hover over a title or details button for row status and full diagnostic explanations. Double-click anywhere on a source row, or click its Details / Error button, to open the same editor (inline dropdowns keep their normal interaction). It shows timing, editable row type and start/end/duration corrections, full diagnostics, timing decisions and a formatted table of original cells (including empty values and formulas). Pending edits are distinguished from the last analyzed timing. Issues opens the issue navigator, including sheet-level and gap errors. The table fills the remaining space; its title column expands with the window. Scrollable panels and dialogs show solid scrollbars only when content overflows. While scrolling is needed, the bars stay visible rather than fading away. The export confirmation wraps paths and instructions without a horizontal scrollbar; a vertical scrollbar appears only if the content exceeds the window. Failed exports open Results, with the error, destination, Replace existing output, Retry export, and Save elsewhere… together. Enable replacement explicitly or choose another filename; retrying clears the error on success. Preview cells align at the top; blank title lines are omitted without changing original values in the inspector or exports. On narrow windows, timing values stack so corrections remain accessible. The table reserves space for timing text and row controls, then wraps titles into the remaining width. Changes require recheck; the timing preview and diagnostics continue to show the previous analysis. -
Columns shows a concise verified mapping summary, green detected roles, per-column role dropdowns, and sample values. The main choices are Auto, Ignore, Timing, Duration, Title, and Metadata. Indented dropdowns select Start / Start–end / End, Primary title / Secondary title, or Custom Ontime field / Notes respectively. Role uniqueness applies to these specific choices, so two Title columns can supply primary and secondary titles. Selecting Title on another column prefers the unused secondary role. Saved profiles retain their existing specific role names. Suggested: … shows useful automatic recommendations even after a manual choice. Problems are grouped by affected column, with short explanations and suggested corrections instead of repeating each invalid cell. Review column… or Choose duration handling… scrolls to and highlights the affected column; columns needing attention remain amber. Expand Complete error log to read or copy every original diagnostic and source location. This grouping changes only the GUI summary, not CLI logs. Missing required columns are reported at sheet level: no unrelated column is highlighted, and existing role suggestions remain available. A missing-column warning uses an amber card with an indented Next step explaining which role to choose, without duplicate summary headings. Column problems, ambiguous mappings, row and gap diagnostics, and operation errors share this card layout. Warnings use amber and errors use red, with corrective steps visible and technical diagnostic details expandable. When detection is blocked, recognised headers still provide hints; these do not replace validation. Expand Detection evidence for full inference and validation details; hover the Columns tab for a compact explanation of the role choices. Start–end maps one column containing full ranges such as
08h00 - 08h30; every relevant timing cell must contain both bounds. Start selects only the first clock from a cell, so a mixed08h45 - 09h10value can provide the 08:45 anchor while the selected duration column determines the timer. A duration column has a nested Duration handling choice instead of extra column roles: whole cell, minimum, maximum, upper median or sum. Separate Add margin and Split into multiple entries toggles can be combined with that choice. Add margin takes an explicit positive duration (for example2 min) and adds that gap after every entry, including the last one; splitting applies the selected handling and margin to each separated group. The order is Split → Duration handling → Add margin. For example,20 min + 5 minand10 min + 2 minon separate lines produce 25-minute and 12-minute entries with Split + Sum. Selecting one duration column explicitly resolves duplicate TIMER headers. Each split entry has its own Ignore choice in the preview and editor. After Apply & recheck, only that entry and its margin are removed; remaining entries are recalculated from the source start. All rows retains excluded entries with an Auto (Event) choice to restore them. Title and timing edits still apply to the source row. If the source row was previously ignored as a whole, restore it and recheck first to see its individual split entries. Secondary title selects another title source with a nested handling menu: Either uses the main title when present and the secondary when it is empty; Merge joins both nonempty titles with an em dash; Notes adds the secondary to event notes; Metadata creates a custom field named from its column header. Merge with previous title reuses the latest nonempty primary title when the current one is blank:Session - Talk 1,Session - Talk 2. A new primary title starts a new sequence; explicitly ignored rows do not supply titles. Before the first primary title, it uses the secondary alone. Explicit row title corrections take precedence over all title handling modes and do not change the primary title carried into subsequent rows. Notes appends a column’s values to Ontime event notes. Metadata creates an Ontime custom field named from the source header. Ignore excludes the column from inference and Ontime output. Several columns can use any of these destinations. Auto restores inference: production headers such as video, light/lumière, sound/son, PowerPoint and slides become metadata; note, comment, remark and instruction headers become notes; other unused columns are ignored. Manual header mapping remains available in Setup for the header row and column choices. The separate Advanced settings section contains duration units and profile JSON.
The row type selector shows the detected type in parentheses, such as Auto (Event). Auto (?) means unresolved or awaiting recheck.
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 title and timing corrections restore source or calculated values. Start and end accept
clock times such as 09:30 or 09:30:00; duration accepts explicit values such as
2 min or 00:02:00. Missing timings, overlaps and decisions for rows without a timing can be
resolved here. Unsupported interpretations and unresolved conflicts retain explicit
errors; correct the source when available controls cannot express the intended fix.
CLI errors for rows without a timing also include a labeled source preview.
Save resolutions… opens the save/load/remember controls without taking space away from the correction table. Export turns green when all checks pass and no edits are pending. Results offers Open, Open output folder and Copy path, plus Ontime JSON…, Ontime XLSX…, and Neutral JSON… buttons to save another format. Each opens a destination dialog beside the previous export; cancelling leaves the current export unchanged. These actions require a validated rundown. 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.
Header detection recognizes French labels including Heure and Action (event title). An ambiguous label such as Temps is resolved from the column data, rather than assumed to mean duration.
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 or an Ontime-ready XLSX 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.
When a cached result is missing, the converter safely calculates arithmetic made
of numbers, same-sheet cell references, parentheses and +, -, * or /.
It does not run spreadsheet functions or macros. Remaining formulas are grouped
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 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 |
Start–end cell 08h00 - 08h30 | Use 08:00 and 08:30 directly and derive a 30-minute duration |
Start cell 08h45 - 09h10, duration 20 min + 5 min with Maximum | Use 08:45 and a 20-minute timer; the unused end in the Start cell does not constrain it |
Duration 20 min + 5 min with Maximum and a 2 min margin | Create a 20-minute event followed by a two-minute untimed gap |
| Multiline duration with Split | Create sequential virtual entries, one for each separated duration group; a start–end range bounds their combined durations and margins, with remaining time kept as a gap |
| 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.
Ontime settings
The Ontime settings tab controls project preferences in native Ontime JSON. Enable CSS style override is checked by default, including for existing profiles. This enables the CSS already installed on the destination Ontime instance; it does not embed or replace the stylesheet. Custom CSS can take precedence over timer colours.
Choose 12/24-hour clocks, the viewer language (or an installed custom translation), normal/warning/danger timer colours, and names for three auxiliary timers. Other defaults match Ontime: 24-hour clocks, English and its standard timer colours. Changes apply to the next export without requiring schedule reanalysis. Save/reuse resolutions to retain them. XLSX and neutral IR JSON do not contain project settings.
CLI profiles accept the same preferences under ontime, for example:
{"ontime": {"override_styles": true, "time_format": "24", "language": "fr"}}
Optional fields are normal_color, warning_color, danger_color (hex colours),
and aux_timer_names (three strings). Full project imports apply these preferences;
use Ontime’s Partial Load when you want to keep an existing project’s settings.
Output choice
For multi-sheet workbooks, the default GUI filename includes the selected sheet:
show - Main stage.ontime.json (or .ontime.xlsx / .neutral.json). Switching
sheets updates the suggested name, while a manually chosen output path is kept.
Single-sheet filenames remain unchanged. Characters unsafe in filenames are
replaced with underscores.
After saving, the GUI opens Results with a green Export successful panel, the saved path, and Open / Open output folder / Copy path actions. A confirmation with the filename remains in the bottom bar when switching tabs. Starting another operation clears the previous confirmation; failed exports show an error instead.
Native Ontime JSON is the primary target: it lets the exporter control time
relationships and project structure without a second column-mapping step.
XLSX export writes one Ontime worksheet with Time Start, Time End, Duration, Cue,
Title, Notes, Timer Type, Link Start, Colour, ID, Flag, Count to end,
End Action, Warning Time, Danger Time and Skip columns, followed by selected
metadata columns. Playback settings match the JSON export: Link Start is explicitly
FALSE so Ontime does not link events across intentional gaps. Notes contain only
columns assigned to Notes; metadata remains in separate columns.
Headers match Ontime v4’s import-screen defaults (case-insensitive). In particular,
Notes is plural in XLSX; the native JSON field remains note.
Native JSON uses Ontime’s schema keys such as timeStart, timeEnd and timerType.
Times use HH:MM:SS strings accepted by Ontime. Import the file with Ontime’s
spreadsheet importer
and map the displayed columns. Schedule gaps remain visible through absolute
event starts; the exporter does not invent timer rows for them. Ontime’s current
file importer accepts XLSX and does not expose ODS upload, so ODS is not generated.
These outputs share the validated IR and are not intermediate steps for native
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. 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"},
"duration_mode": "maximum",
"duration_split": true,
"duration_separator": "\\n\\n",
"column_usage": {"C": "notes", "D": "metadata", "F": "ignore"},
"expected_headers": {"A": "Horaires", "B": "Durée"},
"untimed_as_notes": true,
"row_kinds": {"20": "marker"},
"titles": {"8": "Opening remarks"},
"starts": {"8": "09:30"},
"ends": {"8": "09:32"},
"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, start_end, end, duration, title and secondary_title. A start_end
column requires a complete clock range such as 08h00 - 08h30 in every relevant
timed cell and supplies both values without a separate end mapping. A start
mapping extracts only the first clock when its cell also contains an end clock.
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. titles, starts, ends and durations are keyed by one-based source row;
corrected cells are excluded from whole-column validation while all remaining
explicit mappings still undergo it.
Map a secondary title using "columns": {"title": "D", "secondary_title": "E"}.
secondary_title_mode accepts either (default), merge, merge_previous, notes or metadata.
Notes and metadata use the same destinations in Ontime JSON and XLSX as ordinary
Notes and Metadata columns. The primary title column remains required; rows with
both titles empty still need correction.
duration_mode is optional and remains attached to the single duration role.
minimum, maximum, median and sum select from explicit duration values in mixed text.
Upper median selects the middle value after sorting; for an even count it
chooses the higher of the two middle values. For example, 5 min + 20 min
selects 20 minutes. The profile key remains median for compatibility with saved
resolutions. With splitting, it operates on each separated group independently.
duration_add_margin: true with duration_margin: "2 min" adds a two-minute
untimed gap after each event. The value is independent of the source durations
and selected operation; it also applies with Sum and whole-cell handling.
Missing, nonpositive or ambiguous values block analysis with an actionable error.
Explicit starts remain anchors: if a margin overlaps the next event, validation
reports it instead of moving that event.
duration_split: true creates sequential virtual
events and applies the selected handling to each group separated by
duration_separator; \\n, \\n\\n and \\t mean newline,
blank line and tab. The default strict behavior requires the complete cell to be
one duration. For non-split policies, a one-value summary line followed by a more
detailed multi-value line is treated as an alternative expression, avoiding double
counting. Legacy duration_mode: "margin" profiles remain supported; new GUI
choices use Maximum with the Add margin toggle. Legacy profiles using duration_mode: "split" are read as Sum with
splitting enabled.
ignored_parts: {"20": [2]} excludes only the second split entry of source row
20. Both numbers are one-based; original split indices remain stable when other
parts are excluded. If a saved index no longer fits the split settings, analysis
reports an error instead of silently applying it to another entry.
column_usage maps column letters to notes, metadata or ignore. Every choice
prevents that column from being inferred as a start, start–end, end, duration or
title, and a column cannot also have an explicit timing or title mapping. Notes values are joined
into the Ontime event note, including values from attached note rows and merged
continuations. Metadata creates a project-level Ontime text custom field and stores
each event’s value in its custom object. Ignore removes the values from Ontime;
rows containing only ignored values need no clarification. Inferred timing and
correction provenance remain visible in the neutral IR and review UI but are not
added to Ontime notes.
With no manual choice, timing and title inference runs first. Remaining columns use conservative header rules: recognised production departments and media become metadata, recognised note-like headers become notes, and everything else is ignored. 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.
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.
Under Save resolutions…, the two main actions are Save resolution and Reuse remembered resolution. Advanced contains file management, reset, and forget controls.
Save resolution as… (under Advanced) 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.
Save 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.
Remember column layouts
In Save resolutions…, column layout controls appear first, followed by sheet resolutions. Action buttons share the same full-width sizing, including Advanced actions. Remember column layout saves the resolved column roles, Notes/Metadata/Ignore choices, duration units/handling/split/margin settings, and secondary-title handling. It is available once columns are valid, even if there are schedule errors or pending row corrections.
Reuse remembered columns matches header text and order, ignoring casing and
extra whitespace. Event content, sheet names and header row position may differ.
It restores only column decisions: existing row edits and Ontime preferences are
preserved, and row corrections from another rundown are never copied. Apply &
recheck before export; the timing data is still validated across the whole column.
Ambiguous matching header rows are not applied. Forget column layout removes
this separate memory, stored under resolutions/columns in the same user
configuration directory. Exact-sheet resolutions continue to work as before.
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 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. Five user-approved source workbooks are tracked in rundowns and exercised by offline regression tests alongside the synthetic fixtures. Other local originals, PDFs and generated exports remain untracked.
See all tools and repository development.
In Setup → General options, Default break name names unnamed gaps and the events created from them. Source break names and individual event titles take precedence. Leave it empty to retain automatic names. Apply & recheck after changing it; the setting is saved with resolution profiles.
Rundown evaluation corpus
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 and
original-name/checksum manifest. 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 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 behaviors and limitations, not a general success percentage.
Supplied examples
| Example | Evidence and result |
|---|---|
| ESTIVALES, OUVERTURE | Correctly identifies Heure, Durée and Contenu / Détail. Shared merged durations remain one timer; merged windows with individual durations become consecutive cues with leftover slack. Untimed production directions need a note classification. Final 11:45 cue lacks duration and blocks export pending clarification. |
| ESTIVALES, CLOTURE | Five timing blocks. With the explicit untimed_as_notes policy, converts to five timers; all original continuation/direction rows remain in the IR; exported notes depend on the selected Notes columns. This policy is a test scenario, not a confirmed interpretation from the owner. |
| Plénière 2, Feuil1 | Both C and D are named TIMER and contain plausible durations. Returns AMBIGUOUS_COLUMN; parent-segment versus child-cue timing needs clarification. No automatic conversion is claimed. |
| GIFAV 2026 Auditorium | Horaires contains consistent parent-session start/end ranges and is detected as a combined Start–end column. Durée mixes child ranges with speaking/QA text, so it cannot be flattened into one duration role. Mapping Start–end to A and Title to D, retaining presentations as notes, validates Thursday with 11 entries and three gaps. Friday reaches schedule validation with 10 entries and three gaps, then correctly reports the source overlap between the 13:45–15:45 poster session and the 14:45–15:45 following session. |
| Montage PDF | Text is extractable, but includes overlapping logistics tasks, missing durations and different locations. Not a single established timer sequence. |
| Exploitation/démontage PDF | Text is extractable; page-spanning directions, simultaneous activities and untimed arrivals require track and row classification. PDF import remains a stretch goal. |
The supplied originals contain production details and contacts. The five tracked
workbooks were explicitly approved for Git inclusion by the user; this does not
assert a blanket redistribution license for third-party material. Test assertions
and documentation avoid reproducing their production text. An unchanged local file can be inspected with
rundown-converter inspect INPUT --json; this output contains the original cells,
so treat it like the source document.
PDF feasibility trial
A bounded follow-up trial attempted automatic table recovery from all 17 pages
of the two supplied PDFs. Result: useful text/table recovery, but no dependable
whole-document timer conversion. PDF importer work is paused; the application
continues to return PDF_REQUIRES_REVIEW. This is a finding about these samples,
not evidence that all PDF rundowns are unsuitable.
Extraction attempts
First compare pdftotext -layout with word coordinates from
pdftotext -bbox-layout. Plain reading order sometimes joins a clock and its
activity, while multiline cells and vertically centred text prevent reliable
row detection from baselines alone. The rendered first page of each document
was inspected to compare the recovered coordinates with the visible grid.
Then use pdftocairo -svg to recover the table borders. In these files the borders
are thin filled rectangles. A temporary Python standard-library prototype
clusters their coordinates into column boundaries and row bands, assigns words
by their bounding-box centres, and records missing horizontal borders as possible
vertical cell spans. This is specific to ruled, text-based PDFs; it does not
establish support for scans, borderless tables or other PDF drawing conventions.
The first geometry pass lost a column on two Montage continuation pages where the left border was absent. It also missed text above the first visible border on some pages. A second pass aligns column boundaries across the document and extends the outer row bounds to include body text. It recovers four columns for Montage and five for Exploitation on every page.
| Measurement | Montage | Exploitation/démontage |
|---|---|---|
| Pages | 4 | 13 |
| Nonempty geometric row bands | 33 | 123 |
| Body words assigned to cells | 714 | 2,645 |
| Repeated page-heading words excluded | 16 | 39 |
| Populated time cells | 13 | 46 |
| Explicit start/end ranges | 1 | 15 |
| Start-only cells | 9 | 31 |
| Other time-cell values | TBC, 01H/2H, 2H MAX | None |
All non-heading words were assigned in this second pass. That is extraction coverage, not proof that every cell boundary, inherited start or event grouping is correct. Row bands are geometric subdivisions, not a count of semantic events. Missing grid borders and cross-page continuations still need interpretation.
Timing experiment and stop decision
For a deliberately generous trial, write the recovered rows to temporary CSVs
with guessed Start/Title/Owner/Location/Notes headers and enable the existing
untimed_as_notes policy. No start or duration is filled from the next row.
Keep page/bounding-box and possible-merge evidence in separate temporary JSON;
this CSV trial does not resolve or automatically apply those ambiguous spans.
Montage stops at column validation on its three unresolved time-cell values. Exploitation reaches IR construction but reports 31 missing durations. Its 12 orphan-note diagnostics are downstream consequences of unresolved preceding events, not 12 additional extraction failures. A shared time cell can cover several simultaneous tasks; treating them as consecutive cues is unjustified.
As a diagnostic only, test the explicit-range subset separately. Montage’s single range validates, but that excludes almost the entire document. Exploitation’s 15 ranges yield 14 candidate timers and one untimed break, with six overlapping predecessor pairs and three gap-overlap diagnostics. This subset also omits the 31 start-only entries, so it is not an acceptable converted rundown even if those conflicts were removed. No partial Ontime project was published.
The remaining obstacles are semantic: selecting simultaneous tracks, deciding whether rows without a timing are instructions or events, distinguishing arrivals and cutoff markers from timers, and interpreting uncertain overnight deadlines. Neither a following start nor a missing table border supplies that information. Per the requested stop condition, no experimental reader or new runtime dependency was added. Revisit with a sequential PDF containing explicit durations/end times, or after adding explicit track and row-role selection to the neutral model. Temporary extractions and the prototype stay outside Git; no private PDF content or contact details are redistributed.
Public examples
| Source | Result and useful variation |
|---|---|
| Stagetimer | Header below title blocks, Excel serial times, formula placeholders. The populated row has inconsistent start/end/duration values; validation returns CONFLICTING_TIMES. |
| Attenditai | Instruction sheet plus blank formula-driven schedule. Formula cells without usable cached values require recalculation/population; no invented events. |
| Joinways | AM/PM times, section labels embedded in the clock column, parallel setup tasks. Unmerged labels require explicit row classifications before column inference can succeed; overlaps then require separate tracks. |
| LiveFocus | Three sheets, cached formula durations in minutes and fractional-day clocks. Minute units are inferred from start/end pairs. Blank formula rows and full-width merged footer are structural. The completed example reports overlapping activities. |
| Novus | String clock times and two-part durations. Whole-column comparison with start/end pairs establishes hh:mm; the populated XLSX sheet converts without a profile. |
| Events Authority | Two sheets, a title block, Excel clock values and chained formulas. The main schedule infers start/end/title and validates nine events plus one gap after its total row is explicitly ignored. The preparation sheet is correctly kept separate. |
| Arena Takeover | A sports cue sheet mixes countdowns (T-30:00), elapsed time, quarter clock, halftime and final-game tokens in one clock column. It fails whole-column validation instead of pretending these are one wall-clock schedule; durations also require an explicit unit. |
| LASSO broadcast | A compact broadcast CSV uses Item as its title header and mm:ss durations. Manual mapping reaches IR construction, where a cue without a duration remains an actionable blocker. |
| LASSO corporate | A conference CSV interleaves timed cues with session headings and end markers. Manual mapping exposes those rows for classification and leaves the final missing duration unresolved rather than silently dropping it. |
| The AV Company | Instructions, blank template and populated example sheets, with a two-level visual header, Excel fractional-day durations, continuation notes and a final -- marker. Explicit header/column choices and three row classifications produce a valid 20-event schedule. The workbook also contains formatting far beyond the visible data columns, which remains harmless but verbose in inference evidence. |
Two additional institutional sources (Moira Shire and Monash University) rejected requests with HTTP 403. A speaker toolkit page exposed no direct workbook link. No authentication or access restrictions were bypassed.
The second search deliberately retained cases that fail or need review. They add
relative sports clocks, broadcast mm:ss, structural session rows, two-level
headers, preparation sheets and wide production metadata; a corpus of only
successful single-track schedules would not exercise the converter’s stop rules.
Ontime verification
Generated native JSON was run through Ontime’s actual rundown parser and metadata
calculation from version 4.15.1, source commit
0fe52483eb756228589321b83c3b0f810dfb36b1.
The synthetic lunch example preserves all four events, their start/end/duration
values and unlinked starts; Ontime calculates a 5,400,000 ms gap before resumption.
The five-event closing-sheet scenario and eleven-event public Novus example
also preserve every timer through that parser. This verifies parser and schedule
semantics, not an operated live show or every
Ontime project section. The user’s installed version still needs confirmation.
Regression coverage
Synthetic tests cover whole-column contradictions, duplicate TIMER headers,
ambiguous duration units resolved by other rows, Excel time values and merges,
notes/markers, gaps, conflicting triples, backward times, negative durations,
output collisions, source preservation, cancellation, CLI exit codes and desktop
worker state. tests/supplied_corpus.rs additionally tests French header detection
and typed Excel durations in both Moebius files, duplicate timers in Plénière 2,
merged blocks and source-row retention in ESTIVALES, and parent ranges, gaps and
the real Friday overlap in GIFAV. These tests are offline and never write exports
beside the fixtures. Public downloads remain outside CI.
Validation of the first implementation
All workspace Rust tests and 43 Python tests passed, along with formatting, Clippy and warning-free Rustdoc. Whole-workspace line coverage is 86.20% against the 75% gate, including production GUI/PDF code. The native converter Setup window was visually inspected; headless egui tests exercise Review/Results, compact layouts, worker completion, errors and export. Full interactive operation on Windows/macOS and a live Ontime playback session have not been verified.
Rundown converter development plan
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; corpus findings record real inputs and unresolved questions. Unchecked tasks below remain future work; broader design requirements are not claims of implemented support.
Completion audit
Audited against the 0.3.0-rc.1 source and documentation on 2026-11-03. The
five required workflow stages and the requested shared CLI/GUI review experience
are implemented. Remaining work is acceptance hardening, explicitly unsupported
schedule models, packaging and stretch goals.
| Area | Status | Evidence or remaining work |
|---|---|---|
| 1. Whole-column inference | Complete | Header/data evidence, manual mapping and whole-column contradictions are implemented and tested. Explicit roles can select the start component of a mixed range and apply one documented extraction policy to a mixed duration column. |
| 2. Untimed gaps | Complete | Named and inferred gaps enter the IR; keep/extend previous/add to next resolutions are available. |
| 3. Complete IR | Complete for supported single-day schedules | Explicit and inferred timing provenance, notes, metadata, corrections and exclusions are retained. |
| 4. Consistency checks | Complete for supported single-track schedules | Conflicting triples, backward/negative timing, overlaps and gap boundaries block export. |
| 5. Ontime output | Complete | Native Ontime JSON, neutral JSON and normalized XLSX share the validated IR; native parsing was checked against Ontime 4.15.1. |
| CLI and desktop review | Complete for the release-candidate workflow | Inspect/validate/convert, Setup/Review/Results, mapping, row editing, profiles, remembered resolutions and pending/recheck behavior are present. Recent-file persistence and broader native/platform interaction checks remain. |
| Public evaluation corpus | Expanded, still not a benchmark | Ten external files now cover XLSX and CSV successes, deliberate failures and manual-resolution cases. A fully reviewed expected-result matrix and held-out accuracy exercise remain. |
| PDF input | Trial complete; importer paused | The bounded 17-page experiment recovered tables but could not establish dependable sequential timers. |
| Parallel tracks and midnight/day rollover | Unsupported by design | These require explicit models; current behavior stops instead of guessing. |
| Portable release bundles | Open | Workspace builds include the converter, but release packaging is still reporter-oriented. |
| XLSX re-export stretch goal | Complete | Writes Ontime-importable normalized columns. |
| Typst/PDF report stretch goal | Open | No report exporter is implemented. |
| Buffer-adjustment stretch goal | Open | No proposal, feasibility or redistribution workflow is implemented. |
| ODS | Intentionally excluded | Ontime’s file importer does not expose ODS upload; XLSX is the supported spreadsheet export. |
Architecture
Workspace member: crates/rundown-converter/, with binaries
rundown-converter and rundown-converter-gui. It uses 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.
Source extraction prepares tables before the five distinct processing stages:
source readers -> source tables
1. infer and verify column meanings across rows
2. identify untimed gaps and record them in the draft IR
3. construct the complete IR from source times and gap constraints
4. validate schedule consistency
5. export the validated IR to Ontime JSON
Each stage has a separate result and diagnostics. A later stage must not silently reinterpret an earlier decision. Unresolved column meanings block stage 2; unresolved gap boundaries remain explicit constraints for stage 3. If a complete schedule cannot be established, return an actionable error rather than exporting partial guesses. Stage 4 is an independent validation pass over the complete IR, not a side effect of export. All exporters consume the same validated IR.
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 spreadsheet functions. A bounded arithmetic parser may calculate same-sheet references when cached results are missing; unsupported or stale 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, notes, custom-field metadata, additional original columns, event/break/marker kind |
| Timing | Optional explicit start/end, duration, day offset, fixed/relative intent, inferred/resolved values |
| Gap | Untimed break, boundary references/constraints, resolved interval when known, provenance, no timer display |
| 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.
1. Infer and verify column meanings
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. Infer meaning primarily from data across the entire column: one ambiguous cell can be resolved by evidence in other rows. A column must retain one semantic role and a compatible unit interpretation throughout the selected table. Different textual formats may express the same role; roles must not switch row by row.
Require the chosen interpretation to fit every relevant nonempty data cell, not
just a majority or a sample. If no single meaning fits, return
INCONSISTENT_COLUMN_MEANING with conflicting cell references and ask the user to
clarify headers, correct values or explicitly separate distinct tables. An
explicit mapping must also pass this check. Empty cells provide no evidence;
recognized headings/totals are structural rows with recorded classifications,
not convenient exceptions used to hide contradictory event data. Check semantic
consistency here; chronological contradictions belong to stage 4.
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:
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.
2. Identify gaps and incorporate them into the IR
Identify breaks with no timer to display before deriving event durations. Use source labels, structural evidence and independently established event ends and following starts. Record each gap in the draft IR with its boundary references, known times and unresolved constraints. A named untimed lunch row is a gap, not an event with a missing duration. A break explicitly intended as a timed cue remains a different entry kind.
Gaps consume schedule time but never create a timer or show a duration as an event. Their intervals may appear in the diagnostic preview for explanation. Resolve unknown boundaries in stage 3 when sufficient evidence exists; otherwise ask for clarification. A long start-to-start interval alone is insufficient to 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. 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. Complete the ordered entries and gap intervals, preserving provenance and explicit versus inferred facts. Missing facts that cannot be derived must produce a clarification error; do not call an unresolved schedule complete.
4. Check schedule consistency
Validate the complete IR independently of the reader and export target. Check start/end/duration agreement using a documented precision tolerance, time going backward within each session/track, negative durations, overlaps and gap boundaries. Keep source order; never sort away a backward time or repair it by assuming a new day. Validate that gaps do not overlap events or accidentally consume cue time.
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.
5. Generate importable output
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 untimed gap remains empty; do not use a delay entry or synthetic timer to represent it. Preserve the independent start after it.
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.
Stretch goals
Additional exports
Generate a Typst report (editable source and rendered PDF) from the validated IR. XLSX re-export provides explicit, normalized columns suitable for Ontime import; ODS remains unavailable because Ontime’s current file importer does not expose ODS upload. Keep untimed gaps free of timer rows in every output. These exports do not become intermediate steps for JSON export.
Optional buffer adjustment
Offer an explicit correction mode that removes time from event rows to reserve buffer in a cramped schedule. Keep the original IR and create a separate proposed revision with a before/after preview and a per-row adjustment record. Never apply this automatically during inference, validation or export.
Let the user choose a target buffer (duration or percentage), scope/session, distribution (equal cuts or proportional cuts), minimum event durations and protected rows. By default distribute cuts across all eligible timed rows in the selected scope; untimed gaps, markers and protected rows contribute nothing. Reject infeasible requests with the maximum achievable buffer. Allocate integer rounding remainders deterministically so cuts sum exactly to the requested buffer.
Define where the saved time goes: either slack after each shortened event while keeping its start, or a consolidated buffer before a selected anchor. Consolidation requires explicit permission to move affected intermediate starts; preserve fixed session/restart anchors and protected timings. Never lengthen an existing break by accident or count existing slack as newly recovered time. If a source already overlaps, distinguish cuts needed to eliminate the overlap from additional cuts needed to create the requested buffer. Column ambiguities must be resolved first; correction must not conceal malformed times or silently choose their meaning.
Run the complete stage-4 validation again on any proposed revision before stage-5 export. Report remaining conflicts and export only a valid selected revision. Test insufficient capacity, minimum durations, protected rows, anchor preservation, rounding, existing gaps, overlap repair and GUI/CLI parity.
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
- Inspect existing CLI, GUI, Ontime export and repository documentation.
- Check official Ontime documentation for schedule gaps and import options.
- Specify neutral model, ambiguity policy, start-time priority and break rules.
- Add separate tool documentation and link it from the repository overview.
- Inspect both supplied XLSX workbooks and both PDFs; download five public workbook layouts with a provenance manifest. Record findings separately.
- 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. Pause importer work: column recovery succeeds, but missing durations and simultaneous tracks prevent dependable whole-document timer conversion.
- Add bounded XLSX and UTF-8 CSV/TSV readers, synthetic regression fixtures, merged-block handling and source-located formula errors.
- Verify exported event times and a 90-minute gap through the Ontime 4.15.1 native rundown parser and metadata calculation at the recorded source commit.
- Add initial Setup/Review/Results GUI, source preview, column/unit selectors, shared profile controls and worker/cancellation tests.
- Keep inference evidence and the source table on Review after failures; add column-role dropdowns, row classifications and title/start/end/duration corrections.
- Save/overwrite/save-as portable resolution profiles and explicitly remember, reuse or forget validated resolutions matched to the complete sheet.
- Redesign Review into Resolve rows / Schedule preview / Columns, with one issue at a time, row navigation/filtering, a full-height correction table and separate saved-resolution controls. Preserve pending edits and previous results until recheck; verify compact layout and dropdown interaction.
- Merge schedule preview and row corrections with All rows / Included rows / Needs attention filters, preserving ignored rows for restoration and displaying attached notes individually without duplicating their timers.
- Add recent-file persistence and comprehensive native GUI interaction checks.
- 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.
- Stage 1: implement whole-column inference, explicit mappings and located errors. Test ambiguous cells clarified by other rows, incompatible meanings in one column, structural rows and misleading headers/units.
- Keep one Duration column role while offering nested whole-cell, minimum, maximum, upper median and sum extraction policies, plus independent margin and split toggles. Let a Start mapping select only the first clock in a mixed range; retain margin gaps and split entries in the IR.
- Add a secondary title role with Either, Merge, Notes and Metadata handling, shared across CLI profiles, GUI review and exports.
- Stage 2: identify untimed gaps and populate draft IR constraints. Test named and unnamed breaks, unknown boundaries and distinction from timed break cues.
- Stage 3: construct the complete IR from times and gap constraints. Test start-only schedules, missing final duration and provenance of inferred values.
- Stage 4: independently validate backward times, negative durations, contradictory triples, overlaps, gap boundaries and explicit markers.
- Add explicit midnight/day and multiple-track interpretations; current behavior rejects these rather than guessing.
- Implement inspect/validate/convert CLI and atomic exports. Test CLI status, output collisions, cancellation, source preservation and deterministic results.
- Stage 5: 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, 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.
- Stretch: add XLSX re-export with verified Ontime-compatible columns and documented format support.
- Stretch: add Typst source/PDF reports.
- Stretch: add explicit buffer adjustment, before/after review, feasibility checks and revalidation, with the cases listed above.
- 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.
Cross builds and portable releases
Run commands from the repository root. The primary release workflow is the
rust_realease named bundle described below. The standalone packager remains
available for manual/offline packaging until native acceptance tests are complete. Cross needs Docker or Podman;
Cross.toml selects Windows GNU x64 and Linux GNU x64 images. Jenkins does not
run release builds or publish releases.
cross build --locked -p pptx-reporter --release --target x86_64-pc-windows-gnu
cross build --locked -p pptx-reporter --release --target x86_64-unknown-linux-gnu
python3 scripts/package-portable.py --target x86_64-pc-windows-gnu --fetch-ffprobe
python3 scripts/package-portable.py --target x86_64-unknown-linux-gnu --fetch-ffprobe
The packager reads target/<target>/release/ and produces a Windows ZIP or Linux
.tar.gz in dist/, plus a SHA-256 checksum. Each includes GUI and CLI binaries,
FFprobe, licenses/provenance and quick-start instructions. Existing archives
are protected; use --output DIR for a new test build.
FFprobe
scripts/fetch_ffprobe.py downloads BtbN FFmpeg 9.0 release-branch, non-shared
LGPL builds. It verifies GitHub’s archive SHA-256, executable format and x86-64
architecture, then tests ffprobe -version on a matching host. Foreign binaries
are inspected without execution. Verified binaries/notices are cached in
ignored downloads/ffprobe/; no FFprobe binary is committed.
The default upstream latest tag moves. Pin repeatable builds with
--ffprobe-release TAG --ffprobe-sha256 HASH. Provenance records release/asset
IDs, download URL and digest. Cached files are checked on reuse, but online
metadata verification still requires GitHub access.
For offline packaging or another provider:
python3 scripts/package-portable.py --target x86_64-pc-windows-gnu \
--ffprobe /path/to/ffprobe.exe --ffprobe-licenses /path/to/notices
Review upstream platform requirements and distribution notices for the selected build. Test Windows launch, drag/drop, file dialogs, scaling, Unicode paths and opening reports on a Windows machine; cross-compilation alone cannot verify them.
Release automation
Root Cargo.toml → workspace.package.version is authoritative. The reporter
inherits it; its manifest contains cargo-binstall metadata. rust-release.toml
configures targets and the canonical Gitea URL for
rust_realease:
rust_realease . --package pptx-reporter --dry-run
rust_realease . --package pptx-reporter --compile-only
Publication needs a clean checkout and a matching explicitly created/pushed
version tag. The existing local v0.1.0 marks the original trial, not subsequent
changes; do not move it implicitly.
The portable named bundle adds Windows/macOS ZIPs and a Linux .tgz, containing both
Cargo binaries, adjacent FFprobe, quick-start instructions and licenses. Canonical
cargo-binstall .tgz archives remain unchanged and require external FFprobe.
Python 3.11+ is required on the build host only.
The protocol-1 hook scripts/prepare-release.py uses the publisher’s output and
cache directories, copies FFprobe/notices and emits a hashed file manifest. It
never guesses Cargo output paths or creates archives. The publisher handles
archive validation, checksums and upload. See the upstream
named-bundle contract.
crates/pptx-reporter/ffprobe-pins.json pins a dated BtbN release, exact non-shared
LGPL 9.0 asset name and published SHA-256 digest per Windows/Linux target. Dated assets have
versioned names, unlike the downloader’s default latest assets. To update,
review the provider release and its notices, then update all three fields together.
These dated releases are not marked immutable by GitHub; digest verification
fails closed if an asset changes. Pinned cached binaries and notices are rechecked locally before any network access;
unpinned downloads still refresh upstream metadata.
rust_realease . --package pptx-reporter --target x86_64-unknown-linux-gnu --compile-only
Dry-run validates static configuration without downloads. Compile-only prepares
and packages bundles without a token, tag creation, push or publication. After a
successful invocation, read dist/latest-artifacts.json; resolve its manifest
and checksums paths relative to dist/. Resolve assets relative to the resulting
artifact-manifest.json directory and verify SHA256SUMS. Do not guess build paths.
Before publication, extract both portable trees. On Linux, generate a report using adjacent FFprobe without relying on PATH. On Windows, launch the GUI and generate a report without separately installed FFmpeg or Python. Cross compilation and fixture tests do not replace native acceptance tests. Keep the standalone packager until those checks are complete. Jenkins remains checks/coverage/badges only.
macOS
Release builds include aarch64-apple-darwin (Apple Silicon) and
x86_64-apple-darwin (Intel), with macOS 13.0 as the minimum. Choose the
portable ZIP for your Mac. It contains pptx-reporter, pptx-reporter-gui,
FFprobe, notices and a quick-start guide. Extract the entire archive, then run
./pptx-reporter-gui in Terminal, or:
./pptx-reporter presentation.pptx --report all
Keep FFprobe beside the applications. No separate FFmpeg, Python, PowerPoint or PDF compiler is needed. The smaller canonical cargo-binstall TGZs contain only the reporter applications and still require external FFprobe.
These are separate architecture-specific executables, not universal binaries
or Finder .app bundles. They are not Developer ID signed or notarized.
If macOS blocks a trusted release, open Terminal in the extracted folder:
xattr -d com.apple.quarantine pptx-reporter pptx-reporter-gui ffprobe
chmod +x pptx-reporter pptx-reporter-gui ffprobe
./pptx-reporter-gui
An attribute-not-found message means that file is already unquarantined. Native startup, file dialogs, drag/drop, report generation and Gatekeeper behavior still require testing on compatible Macs.
Bundled macOS FFprobe
scripts/build_macos_ffprobe.py builds FFprobe from the exact official source
archive and SHA-256 pinned per Mac target in ffprobe-pins.json. It uses the
same digest-pinned cargo-zigbuild image as the reporter, enables local file
probing, and disables network input and external codec-library autodetection.
It does not enable GPL or nonfree components. The dependency is a separate
LGPL executable with statically linked FFmpeg libraries and only macOS system
libraries loaded dynamically.
The source build needs Linux, Python 3.11+, and Podman or Docker (selected via
CROSS_CONTAINER_ENGINE, or Podman if available). The image must be available
to the engine. Compilation runs with container networking disabled; downloading
the pinned source occurs first on the host. First preparation can take several
minutes. The cache identity covers the source pin, target, image and recipe;
reused payloads have their hashes and Mach-O compatibility checked. A warm
cache needs no dependency download.
Each Mac portable ZIP includes the complete FFmpeg source archive, LGPL license,
reproduction scripts and BUILDING.txt under LICENSES/ffmpeg/. The dependency
validator checks the CPU, macOS minimum and system-only library paths without
running foreign binaries. The publisher must include Mach-O support for named
bundle executables, in addition to its existing macOS build support.
On the Linux release host, the same publisher routes Apple targets through the
digest-pinned cargo-zigbuild image in [build.apple]; Cross remains responsible
for Windows/Linux. No host Xcode or Darwin Cross image is used.
The image pin, SDK path and deployment minimum are explicit in
rust-release.toml. See the upstream
automated macOS workflow.
# Validate the complete four-target release configuration.
rust_realease . --package pptx-reporter --dry-run
# Build/package just the two macOS architectures, without publication.
rust_realease . --package pptx-reporter \
--target aarch64-apple-darwin --target x86_64-apple-darwin --compile-only
# Build/package the complete release, including Windows/Linux portable bundles.
rust_realease . --package pptx-reporter --compile-only
Review SHA256SUMS and archive executable modes, including the bundled FFprobe. The publisher checks Mach-O
architecture, the exact macOS deployment minimum and system-only dynamic
dependencies. Foreign cargo-binstall checks install files without executing
them; macOS runtime validation is explicitly skipped on Linux.
Publish the complete configured matrix together so its checksum manifest covers
all platforms.
Application artwork
All three Rust apps embed their own PNG window icon and Windows ICO resource, including CLI-only Windows builds. Linux/FreeBSD X11 uses the window icon; Wayland desktops match each app ID to its desktop entry. macOS uses the ICNS resource in an app bundle. A bare Unix executable has no Finder/application-menu icon.
Five coordinated icons were generated with the built-in ImageGen tool. The
exact prompts are retained. Each Rust crate keeps its
app-icon-source.png, app-icon.png, app-icon.ico and app-icon.icns in
assets/. Python artwork lives in tools/assets/exporter/; Companion artwork lives in
companion-modules/media-player-classic/companion/assets/. Earlier reporter and
converter artwork remains available under its original filenames.
Builds consume committed derivatives and need no image tools. To regenerate the
256px PNG, seven-size ICO (16–256px), and ICNS (128–1024px), install ImageMagick 7
and run python3 scripts/build-icons.py from the repository root.
Desktop launchers
After building or extracting a release, create a launcher pointing to the binary at its permanent location. The helper refuses existing launchers/icons. Linux/BSD launchers reference the original executable and stop working if it moves. macOS bundles copy the binary and adjacent LICENSES directory. Reporter bundles also copy an adjacent FFprobe (requiring its LICENSES directory); otherwise FFprobe must be on PATH. Recreate macOS bundles after updating binaries.
# Linux / FreeBSD: install into your desktop's user application directory.
python3 scripts/create-desktop-launcher.py ascii-names \
--binary "$PWD/target/release/ascii-names" --output "$HOME/.local/share"
# macOS: create a Finder/Dock launcher (run on the Mac).
python3 scripts/create-desktop-launcher.py ascii-names --platform macos \
--binary "$PWD/target/release/ascii-names" --output "$HOME/Applications"
The same helper supports pptx-reporter and rundown-converter; pass their
-gui executable. Reporter and rundown portable archives include the helper,
its supporting module, and the icon formats, so these commands also work from
an extracted archive. Respect XDG_DATA_HOME instead of ~/.local/share when
customized. Desktop menus may need a refresh. Windows executables have embedded
icons; shortcuts inherit those icons.
Python scripts and the Companion module run inside a host application and cannot
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. 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.
Releases containing both tools
The workspace version applies to both tools. Build the reporter with the root configuration, and the converter with its overlay (which omits FFprobe):
rust_realease . --package pptx-reporter --compile-only
rust_realease . --package rundown-converter --config rust-release-rundown.toml --compile-only
Publish both packages’ canonical and portable archives under the same version
tag. Aggregate their checksum lists into one SHA256SUMS; do not replace one
package’s checksums with the other’s. Each archive includes both CLI and GUI.
Development
Documentation · CI and coverage · Releases
Layout and workflow
| Directory | Purpose |
|---|---|
tools/ | Python prototypes and document utilities |
tests/ | Python regression and CI/packaging tests |
crates/<tool>/ | Rust ports, each with its own source, tests and assets |
scripts/ | Shared CI and release helpers |
docs/ | Tool usage and specialized workflows |
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 is a separate Rust workspace member with CLI and egui interfaces. Its implementation checklist and evaluation corpus 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
profiles. Members inherit that metadata. Keep one root Cargo.lock and target/.
The reporter is the default member; CI explicitly checks the entire workspace.
Use -p pptx-reporter to select it when building from a multi-tool workspace.
Checks
Use a recent stable Rust toolchain. Python tools need 3.9+; CI helpers need 3.11+. Run from the repository root:
cargo fmt --all --check
cargo clippy --locked --workspace --all-targets --all-features -- -D warnings
cargo test --locked --workspace --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --locked --workspace --all-features --no-deps
python3 -m unittest discover -s tests -v
cargo build --locked --workspace --all-features
Rust regression tests cover archive parsing, trimming, loops, report formats, Ontime, CLI errors and GUI state; both PDF layouts compile with the embedded engine. Probe-process tests use a controlled stub. No external FFmpeg, FFprobe or Typst CLI is required for CI. The application still needs FFprobe at runtime. Python exporter tests mock external document applications. Inspect rendering changes visually as well.
cargo build -p pptx-reporter --no-default-features builds the CLI without the
GUI or PDF engine; add --features pdf to restore embedded PDFs.
Keep generated files out of Git. Commit each completed task after checks; do not push without authorization. See CI and coverage and cross builds and packaging.
The converter can run without desktop dependencies using
cargo run --locked -p rundown-converter --no-default-features --bin rundown-converter -- --help.
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 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.
Rundown Converter changelog
Unreleased
v0.7.0 — 2026-11-14
-
Update the shared Rust application version to 0.7.0; see the release notes.
-
Add direct links to the published mdBook manual from the project README, tool guide and documentation indexes.
-
Add an mdBook manual built from the existing guides, with local assets and downloads. Jenkins publishes successful main builds under
/mnt/books/manuals/; staging, link validation and scoped publication have regression coverage. -
Use absolute Gitea main-branch URLs for repository file links in the root README; verify linked files exist.
v0.6.0 — 2026-11-14
-
Synchronize the shared Cargo package version with the v0.6.0 milestone tag; see the release notes.
-
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
7e47054: Track normalized supplied XLSX fixtures and exercise them in corpus regression tests.