beffroi-tools/docs/rundown-converter/README.md

565 lines
36 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Rundown converter
[Read the full manual →](https://books.dandaedre.com/manuals/rundown-converter/)
[Documentation](../README.md) · [Changelog](changelog.md) · [Corpus findings](corpus.md) · [Plan](plan.md)
<img src="../../crates/rundown-converter/assets/app-icon.png" width="96" alt="Application icon">
Status: first implementation, available from source. A Rust core powers both the
CLI and egui desktop app, styled like the [PPTX reporter](../pptx-reporter/README.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](plan.md) and [sample findings](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](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](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](plan.md#optional-buffer-adjustment).
## Expanding coverage
The [sample findings](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/README.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.