[azfoo]

🤖 Claude

The time map learns quarter notes, and distances and lengths in bars and beats.

What changed

Quarter stamps (first and third commits). tilia_core/timemap/qstamps.py moves the quarter stamps of #621 (beat units and time signatures) out of its BeatTimeline, at 0ee8ea45: beat_quarter_lengths, _build_quarter_stamps, _build_time_stamp_table, get_quarter_stamp_by_time and get_time_by_quarter_stamp, with the same rules.

• A beat lasts its value × 4 / denominator quarter notes. Each beat's stamp is the sum of the lengths before it, from 0.
• Times and stamps convert by interpolating between beats and extrapolating beyond them with the nearest gap's tempo. Past the last beat, that is the last gap's tempo, not the last beat's own length.
• The stamps are exact Fractions inside and floats where they meet times, so at a beat TimeMap.qstamp gives float() of the exact stamp, as feat: beat patterns, beat units, time signatures and quarter stamps #621 does.

MeasureRow gains two exact fields, which a folded table's rows get too:

• qstamp, its downbeat's stamp;
• quarters, its length, computed from the meter like the time signature.

TimeMap gains four methods:

• qstamp(t) and time_at_qstamp(q);
• quarters(start, end): the difference of two qstamps, rounded to a millionth as length() is;
• assumed_between(start, end): whether an assumed meter went into quarters(start, end).

To answer that, qstamps.py gains beats_between, which gives the beats whose lengths a span's quarter notes count. It sits beside the conversions and extrapolates the same way:

• past the last beat, the last gap's beat counts, which is the bar before's when the last bar has a single tap;
• an end before the start covers the bars in between;
• times aren't snapped, and an end exactly on a beat takes nothing from that beat.

The map builds its stamp table the first time a qstamp is asked for, not when the map itself is built. The index reads every file's positions and never asks for qstamps, and exact sums over a long piece take a while. The table is cached in the instance's __dict__ rather than with functools.cached_property, which on Python 3.10 and 3.11 holds one lock shared by every instance.

On a synthetic 93,000-beat timeline the map takes 0.55 s to build, against 0.44 s on v1-prerelease (best of 7, Python 3.11). The difference comes from the rows' exact qstamp and quarters. Building the stamp table with the map made it 0.73 s.

Distances and lengths (second commit). TimeMap.position(t, unit), length(start, end, unit) and unit_seconds(t, unit), with unit either "bar" or "beat", port the prototype's position, length, beat_seconds and bar_seconds (ql_timemap.py).

• A position runs from 0 at the first beat. A bar counts 1 whatever its metre, and the fraction inside a bar counts beats. The closing barline ends the last bar.
• A length is the difference of two positions, rounded to a millionth, and None when either end is off the map. An end on the closing barline is on the map; a start there isn't.
• unit_seconds is in the file's unit.
• Both ends are snapped first, as they are for positions.
• Any other unit gives None and logs an error. The prototype counts beats for any unit other than "bar", but no file can give another unit: only a caller can.

Tests

• test_timemap_qstamps.py ports feat: beat patterns, beat units, time signatures and quarter stamps #621's test_quarter_stamps.py case for case, and adds the spec's User Story 3, scenarios 1–3 and 5.
  • One test runs a grid of spans, with and without a one-tap last bar. Wherever assumed_between says no, giving the assumed bar another meter must leave quarters() unchanged.
  • Another test checks that the first qstamps on two maps don't wait for each other.
• test_timemap_distances.py adds scenarios 4 and 6: eight bars at any tempo, a 3/4 bar inside 4/4, how long a beat and a bar last, the end of the media, and a quarters file.
• test_timemap_shared.py no longer skips test_qstamps. It compares the quarter stamps of all 18 shared examples, at every beat and on every row, without changing any expected value.
• test_timemap_prototype.py: the 7 tests marked needs_distances pass unchanged, so the mark and its definition are gone.

Open question

The last beat's length when its value differs from the beat before's (an uneven pattern, or a last bar under a unit of its own) is open as TimeLineAnnotator/project-management#325. Until it is answered:

• the closing barline is one gap after the last beat;
• past the last beat, quarter notes follow feat: beat patterns, beat units, time signatures and quarter stamps #621's rule, the last gap's tempo.

For such a last bar, quarters(row.start, row.end) differs from the row's quarters (1.5 against 1 under 2+3 with a one-tap last bar). No migrated file has such a last beat.

Tests run

• uv sync --all-packages
• uv run --package tilia-core pytest packages/tilia-core -q (Python 3.11): 878 passed, 3 skipped, 1 xfailed. The xfail is needs_find_time_map, which feat(core): choose a document's time map by role #733 (choosing the time map) removes.
• uv run --isolated --python 3.10 --package tilia-core pytest packages/tilia-core -q: 881 passed, 1 xfailed.
• python scripts/check_packages.py (Python 3.14): all package checks passed.

Guarantees, and what removing their code did

For each guarantee, its code was removed or neutralised, the time map's tests (tests/timemap: 400 tests and 1 xfail, on Python 3.11) were run, and the code was restored.

Guarantee	Neutralised by	Result
Stamps are summed exactly, then floated	summing floats	2 failed: test_triplets_are_exact, shared "1/3 over four taps"
Past the last beat, the last gap's tempo	the last beat's own length	1 failed: test_past_last_beat_keeps_last_gap_tempo
Before the first beat, extrapolated	clamping the time to the first beat	2 failed
A beat lasts value × 4 / denominator	lengths equal to the values	36 failed, 12 of the 18 shared cases among them
A row's qstamp is the sum of the measures before it	dropping the running sum	27 failed, all 18 shared cases among them
A row's quarters is the sum of its beats' lengths	quarters equal to the numerator	18 failed
Nothing computed reaches the file	writing each row's qstamp onto its downbeat	1 failed: test_setting_a_beat_unit_changes_every_qstamp_after_it
A missing or non-finite time has no qstamp	dropping the isfinite check	1 failed
The stamp table is built once, on first use	not caching it	1 failed: test_conversions_reuse_one_table
Maps building their tables don't wait for each other	functools.cached_property	1 failed: test_first_qstamps_on_two_maps_dont_wait_for_each_other
quarters() is rounded to a millionth	not rounding	1 failed
assumed_between: past the last beat, the last gap's beat	the last beat's own	2 failed, the one-tap grid among them
assumed_between: an end before the start covers the bars between	not sorting the ends	2 failed, the two-tap grid among them
assumed_between: an end exactly on a beat takes nothing from it	bisect for bisect_left	1 failed
assumed_between: not snapped, as qstamps aren't	snapping both ends	3 failed, both grids among them
assumed_between: False for a missing time	dropping the check	1 failed
A bar counts 1, its fraction counts its beats	dividing by 4	4 failed
The closing barline ends the last bar	dropping that branch	5 failed
A length's start on the closing barline is off the map	treating it like an end	3 failed
Lengths are rounded to a millionth	not rounding	1 failed
A length's end is snapped	not snapping it	2 failed
unit_seconds of a bar runs from its downbeat to the next	the beat's length instead	6 failed
unit_seconds snaps first	not snapping	2 failed
An unknown unit gives None, logged	accepting any unit	4 failed

Untested, or tested only in part:

• The no-shared-lock test fails on Python 3.10 and 3.11 only. From 3.12, cached_property has no lock, so the test passes either way.
• Two threads asking the same new map for its first qstamp may both build the table, and either one is kept. No test runs that.

Other open PRs on the same files

#733 (choosing the time map) changes table.py, timemap.py and test_timemap_prototype.py too. Lookups (TimeLineAnnotator/project-management#218) will change timemap.py and find_rows. Whichever merges later rebases. In test_timemap_prototype.py, this PR removes needs_distances and #733 removes needs_find_time_map, and each rewords the comment on the other's mark. Whoever rebases drops both marks and both comments.

__init__.py and its __all__ are left alone. Nothing new needs exporting once the others have landed: the new names are methods of TimeMap and fields of MeasureRow, which are already exported. qstamps.py's functions stay internal, as the contract lists none of them.

Part of TimeLineAnnotator/project-management#215

🤖 Generated with Claude Code

[azfoo]

🤖 Claude

A review of this PR before anyone else's found that assumed_between could miss an assumed meter that quarters() counts. f93e17d fixes it:

• it now reads the beats quarters() counts (beats_between), not the bars positions read;
• quarters() is rounded to a millionth, as length() is;
• the stamp table no longer takes the lock that functools.cached_property shares across instances on Python 3.10 and 3.11.

The description is updated: what changed, the test counts, and the guarantee table.

One question is left for the plan: TimeLineAnnotator/project-management#325, the length of a last beat whose value differs from the beat before it. Its answer may change _closing_barline or the last tempo in qstamps.py.