559 lines
36 KiB
Markdown
559 lines
36 KiB
Markdown
# Rundown converter
|
||
|
||
Status: first implementation, available from source. A Rust core powers both the
|
||
CLI and egui desktop app, styled like the [PPTX reporter](rust-reporter.md).
|
||
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](rundown-converter-plan.md) and [sample findings](rundown-corpus.md).
|
||
|
||
## Quick start
|
||
|
||
Run from the repository root:
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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_options` holds `distribute`, `count`,
|
||
`direction` (`previous` or `following`) and `title`, 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 mixed
|
||
`08h45 - 09h10` value 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 example `2 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 min` and `10 min + 2 min` on 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:
|
||
|
||
1. 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.
|
||
2. Identify untimed gaps and incorporate them into the draft intermediate
|
||
representation (IR). These breaks occupy schedule time without a shown timer.
|
||
3. Construct the complete IR from times and gap constraints, preserving original
|
||
and inferred values. Ask for clarification when required facts remain unknown.
|
||
4. Check the complete schedule for inconsistencies, including backward times,
|
||
negative durations, overlaps and contradictory start/end/duration values.
|
||
5. 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](rundown-corpus.md#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](https://docs.getontime.no/quick-tips/smart-time-entry/).
|
||
Its [delay documentation](https://docs.getontime.no/quick-tips/managing-delays/)
|
||
also describes schedule gaps absorbing delays. The 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:
|
||
|
||
```json
|
||
{"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](https://docs.getontime.no/features/import-spreadsheet/)
|
||
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](rundown-corpus.md#ontime-verification). 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:
|
||
|
||
```json
|
||
{
|
||
"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](rundown-converter-plan.md#optional-buffer-adjustment).
|
||
|
||
## Expanding coverage
|
||
|
||
The [sample findings](rundown-corpus.md) 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](../rundowns/README.md)
|
||
and exercised by offline regression tests alongside the synthetic fixtures. Other
|
||
local originals, PDFs and generated exports remain untracked.
|
||
|
||
See [all tools](../README.md) and [repository development](development.md).
|
||
|
||
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.
|