From 0a3855cd3463b33413ef6f4fc0b0e416af747749 Mon Sep 17 00:00:00 2001
From: Matthew James Briggs <matthew.james.briggs@gmail.com>
Date: Mon, 6 Jul 2026 20:00:12 +0000
Subject: [PATCH] feat: model the full <time> element via a TimeChoice

Redesign the time-signature api around a TimeChoice that switches
between the simple case (the ordinary N/D you want 99% of the time) and
a complex case that quarantines everything unusual. The simple type and
the complex machinery live in separate headers, so ordinary 4/4 work
never has to look at the complex surface.

Public shape (src/include/mx/api/):
- TimeSignatureData.h: TimeFraction (shared beats/beat-type leaf) and
  TimeSignatureData { TimeSignatureSymbol symbol; TimeFraction fraction; }
  where the symbol is the narrow {unspecified, common, cut}.
- ComplexTimeSignature.h: the full ComplexTimeSymbol vocabulary,
  TimeSeparator, TimeRelation, InterchangeableTimeSignature,
  MeteredTimeSignature, and ComplexTimeSignature -- itself a
  { metered, senzaMisura } choice mirroring the spec's one real fork.
- TimeChoice.h: the { simple, complex } switch, carrying the
  whole-<time> attributes (isImplicit, display).

Guarantees:
- TimeChoice::complex auto-collapses a simple-equivalent meter (one
  fraction, no interchangeable, no separator, a symbol the simple case
  can express) back to simple, so a plain N/D can never hide in the
  complex arena and there is one canonical representation.
- The two symbol enums do not overlap on the unusual values:
  single-number/note/dotted-note exist only in the complex vocabulary,
  so they cannot appear on the simple type.

Per-staff signatures move to std::map<int, TimeChoice>
staffTimeSignatures on MeasureData (keyed by staff index; no staff
index baked into the signature type).

Choice-type logic (factories, accessors, equality, auto-collapse) lives
in TUs under src/private/mx/api/, keeping the headers declaration-only.

impl: TimeReader translates each core::Time to a TimeChoice;
PropertiesWriter::writeTime regenerates all shapes and takes the staff
index separately; MeasureReader/MeasureWriter route by staff scope and
carry per-staff overrides forward; Converter gains narrow/full symbol,
separator, and relation tables.

Four corpus files newly pass the api round-trip and are pinned
(ly11d/e composite, ly11f symbols, ly11h senza-misura).
---
 src/include/mx/api/ComplexTimeSignature.h     | 148 ++++++++
 src/include/mx/api/MeasureData.h              |  13 +-
 src/include/mx/api/TimeChoice.h               |  78 ++++
 src/include/mx/api/TimeSignatureData.h        |  66 ++--
 src/private/mx/api/ComplexTimeSignature.cpp   |  66 ++++
 src/private/mx/api/TimeChoice.cpp             | 115 ++++++
 src/private/mx/examples/Write.cpp             |   3 +-
 src/private/mx/impl/Converter.cpp             |  70 ++++
 src/private/mx/impl/Converter.h               |  25 ++
 src/private/mx/impl/Cursor.cpp                |   6 +-
 src/private/mx/impl/Cursor.h                  |  11 +-
 src/private/mx/impl/MeasureReader.cpp         |  51 ++-
 src/private/mx/impl/MeasureWriter.cpp         |  10 +-
 src/private/mx/impl/PartReader.cpp            |   1 +
 src/private/mx/impl/PropertiesWriter.cpp      | 107 +++++-
 src/private/mx/impl/PropertiesWriter.h        |   6 +-
 src/private/mx/impl/TimeReader.cpp            | 128 +++----
 src/private/mx/impl/TimeReader.h              |  39 +-
 src/private/mxtest/api/ApiK007aScoreData.h    |   2 +-
 src/private/mxtest/api/ApiK007cScoreData.h    |   2 +-
 .../mxtest/api/ApiK009bSlurScoreData.h        |   3 +-
 .../mxtest/api/ApiK014aFermatasScoreData.h    |   3 +-
 .../mxtest/api/ApiK015aLayoutScoreData.h      |   3 +-
 src/private/mxtest/api/ApiLy43eScoreData.h    |  10 +-
 .../mxtest/api/ApiMuAccidentals1ScoreData.h   |   8 +-
 src/private/mxtest/api/ChordApiTest.cpp       |   2 +-
 .../mxtest/api/TimeSignatureApiTest.cpp       | 332 +++++++++++++++++-
 src/private/mxtest/api/roundtrip-baseline.txt |  10 +
 28 files changed, 1140 insertions(+), 178 deletions(-)
 create mode 100644 src/include/mx/api/ComplexTimeSignature.h
 create mode 100644 src/include/mx/api/TimeChoice.h
 create mode 100644 src/private/mx/api/ComplexTimeSignature.cpp
 create mode 100644 src/private/mx/api/TimeChoice.cpp

diff --git a/src/include/mx/api/ComplexTimeSignature.h b/src/include/mx/api/ComplexTimeSignature.h
new file mode 100644
index 000000000..fe57e2aef
--- /dev/null
+++ b/src/include/mx/api/ComplexTimeSignature.h
@@ -0,0 +1,148 @@
+// MusicXML Class Library
+// Copyright (c) by Matthew James Briggs
+// Distributed under the MIT License
+
+#pragma once
+
+#include "mx/api/ApiCommon.h"
+#include "mx/api/TimeSignatureData.h"
+
+#include <optional>
+#include <string>
+#include <variant>
+#include <vector>
+
+namespace mx
+{
+namespace api
+{
+
+// The full MusicXML time-symbol vocabulary. Used for a complex meter's own symbol and for an
+// interchangeable pair's symbol. Unlike the narrow TimeSignatureSymbol (common/cut only), this
+// includes the unusual display modes that force a signature into the complex arena.
+enum class ComplexTimeSymbol
+{
+    unspecified,  // ordinary fractional display
+    common,       // the C glyph
+    cut,          // the slashed-C glyph
+    singleNumber, // the meter drawn as a single number
+    note,         // the beat-type drawn as a downstem note glyph
+    dottedNote    // the beat-type drawn as a dotted downstem note glyph
+};
+
+// The line drawn between beats and beat-type (MusicXML time-separator). 'unspecified' writes no
+// attribute (the spec default is "none").
+enum class TimeSeparator
+{
+    unspecified,
+    none,
+    horizontal,
+    diagonal,
+    vertical,
+    adjacent
+};
+
+// How a dual/interchangeable pair is visually joined (MusicXML time-relation).
+enum class TimeRelation
+{
+    unspecified,
+    parentheses,
+    bracket,
+    equals,
+    slash,
+    space,
+    hyphen
+};
+
+// The alternate meter of an interchangeable dual pair, e.g. the "(6/8)" of "3/4 (6/8)". It decorates
+// a primary metered signature and carries its own relation, symbol, and separator, independent of
+// the primary's.
+struct InterchangeableTimeSignature
+{
+    // The alternate meter's fractions. One = simple, more than one = composite. Nonempty when used.
+    std::vector<TimeFraction> fractions;
+
+    TimeRelation relation{TimeRelation::unspecified};
+    ComplexTimeSymbol symbol{ComplexTimeSymbol::unspecified};
+    TimeSeparator separator{TimeSeparator::unspecified};
+};
+
+MXAPI_EQUALS_BEGIN(InterchangeableTimeSignature)
+MXAPI_EQUALS_MEMBER(fractions)
+MXAPI_EQUALS_MEMBER(relation)
+MXAPI_EQUALS_MEMBER(symbol)
+MXAPI_EQUALS_MEMBER(separator)
+MXAPI_EQUALS_END;
+MXAPI_NOT_EQUALS_AND_VECTORS(InterchangeableTimeSignature);
+
+// A metered (as opposed to senza-misura) complex time signature: a primary meter of one or more
+// fractions, plus its decorations. A single fraction with no symbol, no separator, and no
+// interchangeable is simple-equivalent and TimeChoice::complex collapses it back to the simple case;
+// so a MeteredTimeSignature that survives as complex always carries at least one of: more than one
+// fraction, an unusual symbol, a separator, or an interchangeable alternate.
+struct MeteredTimeSignature
+{
+    // The primary meter's fractions. One = a single meter (decorated); more than one = composite
+    // (additive), e.g. 2/4 + 3/8. Nonempty in a valid state.
+    std::vector<TimeFraction> fractions{TimeFraction{"4", "4"}};
+
+    ComplexTimeSymbol symbol{ComplexTimeSymbol::unspecified};
+    TimeSeparator separator{TimeSeparator::unspecified};
+    std::optional<InterchangeableTimeSignature> interchangeable;
+};
+
+MXAPI_EQUALS_BEGIN(MeteredTimeSignature)
+MXAPI_EQUALS_MEMBER(fractions)
+MXAPI_EQUALS_MEMBER(symbol)
+MXAPI_EQUALS_MEMBER(separator)
+MXAPI_EQUALS_MEMBER(interchangeable)
+MXAPI_EQUALS_END;
+MXAPI_NOT_EQUALS_AND_VECTORS(MeteredTimeSignature);
+
+// Everything unusual about a time signature, kept out of the way of the simple case. It is itself a
+// choice: either a metered signature (composite meters, unusual symbols, separators, interchangeable
+// dual meters) or senza-misura (unmetered music). The two are mutually exclusive in MusicXML, which
+// this choice makes structurally true: a senza-misura signature cannot carry a symbol or an
+// interchangeable, and a metered one cannot be senza-misura.
+//
+// Reached only through TimeChoice::asComplex(). Constructing one whose metered value is
+// simple-equivalent yields a *simple* TimeChoice instead (auto-collapse), so a plain N/D can never
+// hide in here.
+class ComplexTimeSignature
+{
+  public:
+    enum class Kind
+    {
+        metered,
+        senzaMisura
+    };
+
+    // Defaults to a metered 4/4 (this default is never simple-equivalent-collapsed on its own; that
+    // happens only when handed to TimeChoice::complex).
+    ComplexTimeSignature();
+
+    static ComplexTimeSignature metered(MeteredTimeSignature value);
+
+    // The string is the senza-misura display glyph (often empty, sometimes "X").
+    static ComplexTimeSignature senzaMisura(std::string glyph = {});
+
+    Kind kind() const;
+    bool isMetered() const;
+    bool isSenzaMisura() const;
+
+    // Precondition: isMetered().
+    const MeteredTimeSignature &asMetered() const;
+
+    // Precondition: isSenzaMisura(). The returned string is the display glyph (may be empty).
+    const std::string &asSenzaMisura() const;
+
+    bool operator==(const ComplexTimeSignature &other) const;
+
+  private:
+    std::variant<MeteredTimeSignature, std::string> myValue;
+};
+
+MXAPI_NOT_EQUALS_AND_VECTORS(ComplexTimeSignature);
+
+} // namespace api
+} // namespace mx
diff --git a/src/include/mx/api/MeasureData.h b/src/include/mx/api/MeasureData.h
index 659796157..11ecde555 100644
--- a/src/include/mx/api/MeasureData.h
+++ b/src/include/mx/api/MeasureData.h
@@ -12,7 +12,7 @@
 #include "mx/api/PartSymbolData.h"
 #include "mx/api/StaffData.h"
 #include "mx/api/TempoData.h"
-#include "mx/api/TimeSignatureData.h"
+#include "mx/api/TimeChoice.h"
 #include "mx/api/TransposeData.h"
 
 #include <map>
@@ -31,7 +31,15 @@ class MeasureData
     // this is the notes and other music data
     std::vector<StaffData> staves;
 
-    TimeSignatureData timeSignature;
+    // The measure's time signature (applies to all staves). A TimeChoice: simple for the ordinary
+    // N/D case, complex for anything unusual.
+    TimeChoice timeSignature;
+
+    // Only use this if you need different time signatures on different staves. Normally empty; keyed
+    // by staff index, one entry per staff-scoped <time number="N"> override. Effective-time-signature
+    // rule: for a given staff, an entry here whose key matches wins; otherwise fall back to the
+    // singular timeSignature above.
+    std::map<int, TimeChoice> staffTimeSignatures;
 
     // an empty measureNumber indicates a normal
     // measure number (i.e. the measure's
@@ -110,6 +118,7 @@ class MeasureData
 MXAPI_EQUALS_BEGIN(MeasureData)
 MXAPI_EQUALS_MEMBER(staves)
 MXAPI_EQUALS_MEMBER(timeSignature)
+MXAPI_EQUALS_MEMBER(staffTimeSignatures)
 MXAPI_EQUALS_MEMBER(number)
 MXAPI_EQUALS_MEMBER(measureNumbering)
 MXAPI_EQUALS_MEMBER(multiMeasureRest)
diff --git a/src/include/mx/api/TimeChoice.h b/src/include/mx/api/TimeChoice.h
new file mode 100644
index 000000000..c142f186d
--- /dev/null
+++ b/src/include/mx/api/TimeChoice.h
@@ -0,0 +1,78 @@
+// MusicXML Class Library
+// Copyright (c) by Matthew James Briggs
+// Distributed under the MIT License
+
+#pragma once
+
+#include "mx/api/ApiCommon.h"
+#include "mx/api/ComplexTimeSignature.h"
+#include "mx/api/TimeSignatureData.h"
+
+#include <variant>
+
+namespace mx
+{
+namespace api
+{
+
+// A measure's (or a staff's) time signature. It switches between the simple case -- the ordinary
+// N/D you want 99% of the time -- and the complex case, which quarantines everything unusual
+// (composite meters, senza-misura, interchangeable, unusual display symbols). Read the kind, then
+// reach for asSimple() or asComplex().
+//
+// The whole-<time> attributes that apply regardless of shape live here, not on either leaf:
+// isImplicit (was the signature restated in this measure or carried forward) and display
+// (print-object show/hide).
+//
+// Invariant: a simple-equivalent signature is always held as simple. TimeChoice::complex collapses a
+// complex value whose meter is really just a plain fraction (one fraction, no interchangeable, no
+// separator, and a symbol the simple case can express) down to simple, so there is exactly one
+// canonical representation and the simple case can never hide inside the complex one.
+//
+// Defaults to a simple, implicit 4/4.
+class TimeChoice
+{
+  public:
+    enum class Kind
+    {
+        simple,
+        complex
+    };
+
+    // True when the source did not restate the time signature here (it was carried forward). The
+    // writer emits a <time> only for entries where this is false. Denormalized onto every measure.
+    bool isImplicit{true};
+
+    // Print/hide the time signature (<time print-object=...>). Ignored when isImplicit.
+    Bool display{Bool::unspecified};
+
+    // Defaults to a simple, implicit 4/4.
+    TimeChoice();
+
+    static TimeChoice simple(TimeSignatureData value);
+
+    // Builds a complex time signature, unless the value is simple-equivalent, in which case the
+    // result is a *simple* TimeChoice (auto-collapse). isImplicit/display are left at their defaults;
+    // set them on the returned value.
+    static TimeChoice complex(ComplexTimeSignature value);
+
+    Kind kind() const;
+    bool isSimple() const;
+    bool isComplex() const;
+
+    // Precondition: isSimple().
+    const TimeSignatureData &asSimple() const;
+
+    // Precondition: isComplex().
+    const ComplexTimeSignature &asComplex() const;
+
+    bool operator==(const TimeChoice &other) const;
+
+  private:
+    std::variant<TimeSignatureData, ComplexTimeSignature> myValue;
+};
+
+MXAPI_NOT_EQUALS_AND_VECTORS(TimeChoice);
+
+} // namespace api
+} // namespace mx
diff --git a/src/include/mx/api/TimeSignatureData.h b/src/include/mx/api/TimeSignatureData.h
index a6829808f..5d1a1b1cd 100644
--- a/src/include/mx/api/TimeSignatureData.h
+++ b/src/include/mx/api/TimeSignatureData.h
@@ -12,52 +12,56 @@ namespace mx
 {
 namespace api
 {
+
+// The symbol drawn in place of, or alongside, a simple time signature. This is the narrow vocabulary
+// that belongs to the simple case: an ordinary fraction, optionally shown with the C (common) or the
+// slashed-C (cut) glyph. The weirder display modes (single-number, note, dotted-note) live only in
+// the complex arena (see ComplexTimeSignature.h) and are not expressible here on purpose.
 enum class TimeSignatureSymbol
 {
-    unspecified,
-    common,
-    cut,
-    singleNumber
+    unspecified, // ordinary fractional display, e.g. 4/4 drawn as two numbers
+    common,      // the C glyph (4/4)
+    cut          // the slashed-C glyph (2/2)
 };
 
-class TimeSignatureData
+// One beats/beat-type pair. The strings are free-form by design: they may hold compound values
+// ("3+2"), decimals ("1 + 2.5"), or compound denominators ("8 + 16"). This is the shared leaf reused
+// by the simple TimeSignatureData and by the composite/interchangeable meters in the complex arena;
+// it carries no symbol, which is what lets it be shared across arenas whose symbol vocabularies differ.
+struct TimeFraction
 {
-  public:
-    // common, cut
-    TimeSignatureSymbol symbol;
-
-    // the top number of the time signature, e.g. "5" in a "5/4" or "3+2" in a "(3+2)/8"
+    // the top number of the time signature, e.g. "5" in "5/4" or "3+2" in "(3+2)/8"
     std::string beats;
 
-    // the bottom number of the time signature, e.g. "4" in a "5/4"
+    // the bottom number of the time signature, e.g. "4" in "5/4"
     std::string beatType;
+};
 
-    // a time signature is implicit when it is not specified by the musicxml
-    bool isImplicit;
-
-    // use this to hide a time sigature with Bool::no. If a time signature is
-    // implicit, the 'display' field will be ignored
-    Bool display;
-
-    inline bool isEqualTo(const TimeSignatureData &other) const
-    {
-        return (beats == other.beats) && (beatType == other.beatType) && (symbol == other.symbol);
-    }
+MXAPI_EQUALS_BEGIN(TimeFraction)
+MXAPI_EQUALS_MEMBER(beats)
+MXAPI_EQUALS_MEMBER(beatType)
+MXAPI_EQUALS_END;
+MXAPI_NOT_EQUALS_AND_VECTORS(TimeFraction);
 
-    TimeSignatureData()
-        : symbol{TimeSignatureSymbol::unspecified}, beats{"4"}, beatType{"4"}, isImplicit{true},
-          display{Bool::unspecified}
-    {
-    }
+// The simple time signature: the ordinary N/D that you reach for 99% of the time, optionally shown
+// with the common or cut glyph. Everything unusual (composite meters, senza-misura, interchangeable
+// dual meters, and the single-number/note/dotted-note display modes) is quarantined in
+// ComplexTimeSignature. Access a measure's time signature through TimeChoice (TimeChoice.h), which
+// switches between this simple case and the complex one and holds the whole-<time> attributes
+// (isImplicit, display).
+//
+// Defaults to 4/4 with no symbol.
+struct TimeSignatureData
+{
+    TimeSignatureSymbol symbol{TimeSignatureSymbol::unspecified};
+    TimeFraction fraction{"4", "4"};
 };
 
 MXAPI_EQUALS_BEGIN(TimeSignatureData)
 MXAPI_EQUALS_MEMBER(symbol)
-MXAPI_EQUALS_MEMBER(beats)
-MXAPI_EQUALS_MEMBER(beatType)
-MXAPI_EQUALS_MEMBER(isImplicit)
-MXAPI_EQUALS_MEMBER(display)
+MXAPI_EQUALS_MEMBER(fraction)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(TimeSignatureData);
+
 } // namespace api
 } // namespace mx
diff --git a/src/private/mx/api/ComplexTimeSignature.cpp b/src/private/mx/api/ComplexTimeSignature.cpp
new file mode 100644
index 000000000..5a63dff61
--- /dev/null
+++ b/src/private/mx/api/ComplexTimeSignature.cpp
@@ -0,0 +1,66 @@
+// MusicXML Class Library
+// Copyright (c) by Matthew James Briggs
+// Distributed under the MIT License
+
+#include "mx/api/ComplexTimeSignature.h"
+
+#include <cassert>
+#include <utility>
+
+namespace mx
+{
+namespace api
+{
+
+ComplexTimeSignature::ComplexTimeSignature() : myValue{MeteredTimeSignature{}}
+{
+}
+
+ComplexTimeSignature ComplexTimeSignature::metered(MeteredTimeSignature value)
+{
+    ComplexTimeSignature result;
+    result.myValue = std::move(value);
+    return result;
+}
+
+ComplexTimeSignature ComplexTimeSignature::senzaMisura(std::string glyph)
+{
+    ComplexTimeSignature result;
+    result.myValue = std::move(glyph);
+    return result;
+}
+
+ComplexTimeSignature::Kind ComplexTimeSignature::kind() const
+{
+    return std::holds_alternative<MeteredTimeSignature>(myValue) ? Kind::metered : Kind::senzaMisura;
+}
+
+bool ComplexTimeSignature::isMetered() const
+{
+    return std::holds_alternative<MeteredTimeSignature>(myValue);
+}
+
+bool ComplexTimeSignature::isSenzaMisura() const
+{
+    return std::holds_alternative<std::string>(myValue);
+}
+
+const MeteredTimeSignature &ComplexTimeSignature::asMetered() const
+{
+    assert(isMetered());
+    return *std::get_if<MeteredTimeSignature>(&myValue);
+}
+
+const std::string &ComplexTimeSignature::asSenzaMisura() const
+{
+    assert(isSenzaMisura());
+    return *std::get_if<std::string>(&myValue);
+}
+
+bool ComplexTimeSignature::operator==(const ComplexTimeSignature &other) const
+{
+    return myValue == other.myValue;
+}
+
+} // namespace api
+} // namespace mx
diff --git a/src/private/mx/api/TimeChoice.cpp b/src/private/mx/api/TimeChoice.cpp
new file mode 100644
index 000000000..105cce91e
--- /dev/null
+++ b/src/private/mx/api/TimeChoice.cpp
@@ -0,0 +1,115 @@
+// MusicXML Class Library
+// Copyright (c) by Matthew James Briggs
+// Distributed under the MIT License
+
+#include "mx/api/TimeChoice.h"
+
+#include <cassert>
+#include <optional>
+#include <utility>
+
+namespace mx
+{
+namespace api
+{
+
+// Maps a complex symbol to the narrow simple symbol, but only for the three values the simple case
+// can express. The unusual display modes (single-number, note, dotted-note) have no simple
+// equivalent, so they return nullopt and keep the signature complex.
+static std::optional<TimeSignatureSymbol> timeChoiceSimpleSymbol(ComplexTimeSymbol symbol)
+{
+    switch (symbol)
+    {
+    case ComplexTimeSymbol::unspecified:
+        return TimeSignatureSymbol::unspecified;
+    case ComplexTimeSymbol::common:
+        return TimeSignatureSymbol::common;
+    case ComplexTimeSymbol::cut:
+        return TimeSignatureSymbol::cut;
+    case ComplexTimeSymbol::singleNumber:
+    case ComplexTimeSymbol::note:
+    case ComplexTimeSymbol::dottedNote:
+        return std::nullopt;
+    }
+    return std::nullopt;
+}
+
+// A metered signature is simple-equivalent when it is a single plain fraction with no decorations:
+// one fraction, no interchangeable, no separator, and a symbol the simple case can express. Returns
+// the equivalent simple value, or nullopt when the meter is genuinely complex.
+static std::optional<TimeSignatureData> timeChoiceAsSimpleEquivalent(const ComplexTimeSignature &value)
+{
+    if (!value.isMetered())
+    {
+        return std::nullopt;
+    }
+    const auto &metered = value.asMetered();
+    if (metered.fractions.size() != 1 || metered.interchangeable.has_value() ||
+        metered.separator != TimeSeparator::unspecified)
+    {
+        return std::nullopt;
+    }
+    const auto simpleSymbol = timeChoiceSimpleSymbol(metered.symbol);
+    if (!simpleSymbol.has_value())
+    {
+        return std::nullopt;
+    }
+    return TimeSignatureData{*simpleSymbol, metered.fractions.front()};
+}
+
+TimeChoice::TimeChoice() : myValue{TimeSignatureData{}}
+{
+}
+
+TimeChoice TimeChoice::simple(TimeSignatureData value)
+{
+    TimeChoice result;
+    result.myValue = std::move(value);
+    return result;
+}
+
+TimeChoice TimeChoice::complex(ComplexTimeSignature value)
+{
+    if (const auto simpleEquivalent = timeChoiceAsSimpleEquivalent(value); simpleEquivalent.has_value())
+    {
+        return simple(*simpleEquivalent);
+    }
+    TimeChoice result;
+    result.myValue = std::move(value);
+    return result;
+}
+
+TimeChoice::Kind TimeChoice::kind() const
+{
+    return std::holds_alternative<TimeSignatureData>(myValue) ? Kind::simple : Kind::complex;
+}
+
+bool TimeChoice::isSimple() const
+{
+    return std::holds_alternative<TimeSignatureData>(myValue);
+}
+
+bool TimeChoice::isComplex() const
+{
+    return std::holds_alternative<ComplexTimeSignature>(myValue);
+}
+
+const TimeSignatureData &TimeChoice::asSimple() const
+{
+    assert(isSimple());
+    return *std::get_if<TimeSignatureData>(&myValue);
+}
+
+const ComplexTimeSignature &TimeChoice::asComplex() const
+{
+    assert(isComplex());
+    return *std::get_if<ComplexTimeSignature>(&myValue);
+}
+
+bool TimeChoice::operator==(const TimeChoice &other) const
+{
+    return isImplicit == other.isImplicit && display == other.display && myValue == other.myValue;
+}
+
+} // namespace api
+} // namespace mx
diff --git a/src/private/mx/examples/Write.cpp b/src/private/mx/examples/Write.cpp
index 57a8e8c07..0b379ce04 100644
--- a/src/private/mx/examples/Write.cpp
+++ b/src/private/mx/examples/Write.cpp
@@ -39,8 +39,7 @@ int main(int argc, const char *argv[])
     // add a measure
     part.measures.emplace_back(MeasureData{});
     auto &measure = part.measures.back();
-    measure.timeSignature.beats = "4";
-    measure.timeSignature.beatType = "4";
+    measure.timeSignature = TimeChoice::simple(TimeSignatureData{});
     measure.timeSignature.isImplicit = false;
 
     // add a staff
diff --git a/src/private/mx/impl/Converter.cpp b/src/private/mx/impl/Converter.cpp
index 56d28eb07..dc49a1302 100644
--- a/src/private/mx/impl/Converter.cpp
+++ b/src/private/mx/impl/Converter.cpp
@@ -1340,6 +1340,41 @@ const Converter::EnumMap<core::CancelLocation, api::CancelLocation> Converter::c
     {core::CancelLocation::beforeBarline(), api::CancelLocation::beforeBarline},
 };
 
+// core normal() folds into api unspecified: absent and "normal" are the same display.
+// The simple (narrow) symbol vocabulary: common/cut only. core normal() folds into api unspecified.
+const Converter::EnumMap<core::TimeSymbol, api::TimeSignatureSymbol> Converter::simpleTimeSymbolMap = {
+    {core::TimeSymbol::common(), api::TimeSignatureSymbol::common},
+    {core::TimeSymbol::cut(), api::TimeSignatureSymbol::cut},
+    {core::TimeSymbol::normal(), api::TimeSignatureSymbol::unspecified},
+};
+
+// The complex (full) symbol vocabulary. core normal() folds into api unspecified.
+const Converter::EnumMap<core::TimeSymbol, api::ComplexTimeSymbol> Converter::complexTimeSymbolMap = {
+    {core::TimeSymbol::common(), api::ComplexTimeSymbol::common},
+    {core::TimeSymbol::cut(), api::ComplexTimeSymbol::cut},
+    {core::TimeSymbol::singleNumber(), api::ComplexTimeSymbol::singleNumber},
+    {core::TimeSymbol::note(), api::ComplexTimeSymbol::note},
+    {core::TimeSymbol::dottedNote(), api::ComplexTimeSymbol::dottedNote},
+    {core::TimeSymbol::normal(), api::ComplexTimeSymbol::unspecified},
+};
+
+const Converter::EnumMap<core::TimeSeparator, api::TimeSeparator> Converter::timeSeparatorMap = {
+    {core::TimeSeparator::none(), api::TimeSeparator::none},
+    {core::TimeSeparator::horizontal(), api::TimeSeparator::horizontal},
+    {core::TimeSeparator::diagonal(), api::TimeSeparator::diagonal},
+    {core::TimeSeparator::vertical(), api::TimeSeparator::vertical},
+    {core::TimeSeparator::adjacent(), api::TimeSeparator::adjacent},
+};
+
+const Converter::EnumMap<core::TimeRelation, api::TimeRelation> Converter::timeRelationMap = {
+    {core::TimeRelation::parentheses(), api::TimeRelation::parentheses},
+    {core::TimeRelation::bracket(), api::TimeRelation::bracket},
+    {core::TimeRelation::equals(), api::TimeRelation::equals},
+    {core::TimeRelation::slash(), api::TimeRelation::slash},
+    {core::TimeRelation::space(), api::TimeRelation::space},
+    {core::TimeRelation::hyphen(), api::TimeRelation::hyphen},
+};
+
 api::Step Converter::convert(core::Step inStep) const
 {
     return findApiItem(stepMap, api::Step::c, inStep);
@@ -1661,6 +1696,41 @@ api::CancelLocation Converter::convert(core::CancelLocation value) const
     return findApiItem(cancelLocationMap, api::CancelLocation::unspecified, value);
 }
 
+core::TimeSymbol Converter::convert(api::TimeSignatureSymbol value) const
+{
+    return findCoreItem(simpleTimeSymbolMap, core::TimeSymbol::normal(), value);
+}
+
+core::TimeSymbol Converter::convert(api::ComplexTimeSymbol value) const
+{
+    return findCoreItem(complexTimeSymbolMap, core::TimeSymbol::normal(), value);
+}
+
+api::ComplexTimeSymbol Converter::convert(core::TimeSymbol value) const
+{
+    return findApiItem(complexTimeSymbolMap, api::ComplexTimeSymbol::unspecified, value);
+}
+
+core::TimeSeparator Converter::convert(api::TimeSeparator value) const
+{
+    return findCoreItem(timeSeparatorMap, core::TimeSeparator::none(), value);
+}
+
+api::TimeSeparator Converter::convert(core::TimeSeparator value) const
+{
+    return findApiItem(timeSeparatorMap, api::TimeSeparator::unspecified, value);
+}
+
+core::TimeRelation Converter::convert(api::TimeRelation value) const
+{
+    return findCoreItem(timeRelationMap, core::TimeRelation::parentheses(), value);
+}
+
+api::TimeRelation Converter::convert(core::TimeRelation value) const
+{
+    return findApiItem(timeRelationMap, api::TimeRelation::unspecified, value);
+}
+
 double Converter::convertToAlter(int semitones, double cents)
 {
     double alter = 0.0;
diff --git a/src/private/mx/impl/Converter.h b/src/private/mx/impl/Converter.h
index 503833a4b..3dc0939a0 100644
--- a/src/private/mx/impl/Converter.h
+++ b/src/private/mx/impl/Converter.h
@@ -40,6 +40,9 @@
 #include "mx/core/generated/StemValue.h"
 #include "mx/core/generated/Step.h"
 #include "mx/core/generated/TechnicalChoice.h"
+#include "mx/core/generated/TimeRelation.h"
+#include "mx/core/generated/TimeSeparator.h"
+#include "mx/core/generated/TimeSymbol.h"
 #include "mx/core/generated/Transpose.h"
 #include "mx/core/generated/Valign.h"
 #include "mx/core/generated/WedgeType.h"
@@ -159,6 +162,24 @@ class Converter
     core::CancelLocation convert(api::CancelLocation value) const;
     api::CancelLocation convert(core::CancelLocation value) const;
 
+    // Simple (narrow) symbol: common/cut only. unspecified maps to core normal(); callers skip the
+    // attribute entirely for unspecified (absent and normal mean the same thing on the wire).
+    core::TimeSymbol convert(api::TimeSignatureSymbol value) const;
+
+    // Complex (full) symbol: the whole MusicXML time-symbol vocabulary. The reader always builds a
+    // ComplexTimeSymbol (TimeChoice::complex collapses to simple when possible), so core->api goes
+    // through this one.
+    core::TimeSymbol convert(api::ComplexTimeSymbol value) const;
+    api::ComplexTimeSymbol convert(core::TimeSymbol value) const;
+
+    // api::TimeSeparator::unspecified means "write no attribute"; callers skip it.
+    core::TimeSeparator convert(api::TimeSeparator value) const;
+    api::TimeSeparator convert(core::TimeSeparator value) const;
+
+    // api::TimeRelation::unspecified means "write no element"; callers skip it.
+    core::TimeRelation convert(api::TimeRelation value) const;
+    api::TimeRelation convert(core::TimeRelation value) const;
+
     static double convertToAlter(int semitones, double cents);
     static std::pair<int, double> convertToSemitonesAndCents(double alter);
 
@@ -197,6 +218,10 @@ class Converter
     const static EnumMap<core::SoundID, api::SoundID> instrumentMap;
     const static EnumMap<core::KindValue, api::ChordKind> kindMap;
     const static EnumMap<core::CancelLocation, api::CancelLocation> cancelLocationMap;
+    const static EnumMap<core::TimeSymbol, api::TimeSignatureSymbol> simpleTimeSymbolMap;
+    const static EnumMap<core::TimeSymbol, api::ComplexTimeSymbol> complexTimeSymbolMap;
+    const static EnumMap<core::TimeSeparator, api::TimeSeparator> timeSeparatorMap;
+    const static EnumMap<core::TimeRelation, api::TimeRelation> timeRelationMap;
 
   private:
     template <typename CORE_TYPE, typename API_TYPE>
diff --git a/src/private/mx/impl/Cursor.cpp b/src/private/mx/impl/Cursor.cpp
index f5cc20cf7..a67ec560e 100644
--- a/src/private/mx/impl/Cursor.cpp
+++ b/src/private/mx/impl/Cursor.cpp
@@ -12,9 +12,9 @@ namespace mx
 namespace impl
 {
 Cursor::Cursor(int numStaves, int globalTicksPerQuarter)
-    : timeSignature{}, ticksPerQuarter(globalTicksPerQuarter), tickTimePosition(0), voiceIndex(0), staffIndex(0),
-      isBackupInProgress(false), isFirstMeasureInPart(true), isChordActive(false), myNumStaves(numStaves),
-      myGlobalTicksPerQuarter(globalTicksPerQuarter)
+    : timeSignature{}, staffTimeSignatures{}, ticksPerQuarter(globalTicksPerQuarter), tickTimePosition(0),
+      voiceIndex(0), staffIndex(0), isBackupInProgress(false), isFirstMeasureInPart(true), isChordActive(false),
+      myNumStaves(numStaves), myGlobalTicksPerQuarter(globalTicksPerQuarter)
 {
 }
 
diff --git a/src/private/mx/impl/Cursor.h b/src/private/mx/impl/Cursor.h
index 807027d07..5c626fc3a 100644
--- a/src/private/mx/impl/Cursor.h
+++ b/src/private/mx/impl/Cursor.h
@@ -5,7 +5,9 @@
 #pragma once
 
 #include "mx/api/MeasureData.h"
-#include "mx/api/TimeSignatureData.h"
+#include "mx/api/TimeChoice.h"
+
+#include <map>
 
 namespace mx
 {
@@ -19,7 +21,12 @@ namespace impl
 class Cursor
 {
   public:
-    api::TimeSignatureData timeSignature;
+    api::TimeChoice timeSignature;
+
+    // carried per-staff <time number="N"> overrides, keyed by staff index; persists measure-to-measure
+    // like the singular timeSignature above
+    std::map<int, api::TimeChoice> staffTimeSignatures;
+
     int ticksPerQuarter;
     int tickTimePosition;
     int voiceIndex;
diff --git a/src/private/mx/impl/MeasureReader.cpp b/src/private/mx/impl/MeasureReader.cpp
index 199e67319..e40b57297 100644
--- a/src/private/mx/impl/MeasureReader.cpp
+++ b/src/private/mx/impl/MeasureReader.cpp
@@ -58,6 +58,9 @@
 #include "mx/utility/Throw.h"
 #include "mx/utility/Unused.h"
 
+#include <algorithm>
+#include <iterator>
+#include <map>
 #include <set>
 
 namespace mx
@@ -215,25 +218,53 @@ impl::MeasureCursor MeasureReader::getCursor() const
 
 void MeasureReader::parseTimeSignature() const
 {
-    TimeReader timeReader{myPartwiseMeasure.musicData()};
-    api::TimeSignatureData timeSignature;
+    // start from the carried-forward state; anything this measure does not restate stays implicit
+    api::TimeChoice timeSignature;
+    std::map<int, api::TimeChoice> staffTimeSignatures;
+
+    if (myCurrentCursor.measureIndex > 0)
+    {
+        timeSignature = myPreviousMeasureCursor.timeSignature;
+        staffTimeSignatures = myPreviousMeasureCursor.staffTimeSignatures;
+    }
 
-    if (timeReader.getIsTimeFound())
+    timeSignature.isImplicit = true;
+    for (auto &entry : staffTimeSignatures)
     {
-        timeSignature = timeReader.getTimeSignatureData();
-        timeSignature.isImplicit = false;
+        entry.second.isImplicit = true;
     }
-    else // no time signature was found
+
+    TimeReader timeReader{myPartwiseMeasure.musicData()};
+    for (const auto &found : timeReader.getTimeSignatures()) // isImplicit == false on each
     {
-        if (myCurrentCursor.measureIndex > 0)
+        int staffIndex = found.staffIndex;
+
+        // clamp an out-of-range staff number to "all staves", mirroring the keys pattern
+        if (staffIndex != api::INDEX_UNSPECIFIED && staffIndex > myCurrentCursor.getNumStaves() - 1)
+        {
+            staffIndex = api::INDEX_UNSPECIFIED;
+        }
+
+        if (staffIndex == api::INDEX_UNSPECIFIED)
+        {
+            // a restated unscoped time governs all staves: it supersedes carried-forward per-staff
+            // overrides (but not overrides stated explicitly in this same measure)
+            timeSignature = found.timeChoice;
+            for (auto it = staffTimeSignatures.begin(); it != staffTimeSignatures.end();)
+            {
+                it = it->second.isImplicit ? staffTimeSignatures.erase(it) : std::next(it);
+            }
+        }
+        else
         {
-            timeSignature = myPreviousMeasureCursor.timeSignature;
+            staffTimeSignatures[staffIndex] = found.timeChoice;
         }
-        timeSignature.isImplicit = true;
     }
 
     myOutMeasureData.timeSignature = timeSignature;
-    myCurrentCursor.timeSignature = timeSignature;
+    myOutMeasureData.staffTimeSignatures = staffTimeSignatures;
+    myCurrentCursor.timeSignature = std::move(timeSignature);
+    myCurrentCursor.staffTimeSignatures = std::move(staffTimeSignatures);
     advanceTickTimePosition(0, "parseTimeSignature");
 }
 
diff --git a/src/private/mx/impl/MeasureWriter.cpp b/src/private/mx/impl/MeasureWriter.cpp
index a9b548a2b..bbc5c885f 100644
--- a/src/private/mx/impl/MeasureWriter.cpp
+++ b/src/private/mx/impl/MeasureWriter.cpp
@@ -131,7 +131,15 @@ void MeasureWriter::writeMeasureGlobals()
 
     if (!myMeasureData.timeSignature.isImplicit)
     {
-        myPropertiesWriter->writeTime(myMeasureData.timeSignature);
+        myPropertiesWriter->writeTime(myMeasureData.timeSignature, api::INDEX_UNSPECIFIED);
+    }
+
+    for (const auto &[staffIndex, staffTimeSignature] : myMeasureData.staffTimeSignatures)
+    {
+        if (!staffTimeSignature.isImplicit)
+        {
+            myPropertiesWriter->writeTime(staffTimeSignature, staffIndex);
+        }
     }
 
     int localStaffCounter = 0;
diff --git a/src/private/mx/impl/PartReader.cpp b/src/private/mx/impl/PartReader.cpp
index 2311ff004..27b6c1473 100644
--- a/src/private/mx/impl/PartReader.cpp
+++ b/src/private/mx/impl/PartReader.cpp
@@ -125,6 +125,7 @@ api::PartData PartReader::getPartData()
             myOutPartData.transposition = transpositionData;
         }
         myCurrentCursor.timeSignature = measureData.timeSignature;
+        myCurrentCursor.staffTimeSignatures = measureData.staffTimeSignatures;
         myCurrentCursor.ticksPerQuarter = reader.getCursor().ticksPerQuarter;
         myOutPartData.measures.emplace_back(std::move(measureData));
         ++myCurrentCursor.measureIndex;
diff --git a/src/private/mx/impl/PropertiesWriter.cpp b/src/private/mx/impl/PropertiesWriter.cpp
index 342f0a9bc..be20d12ca 100644
--- a/src/private/mx/impl/PropertiesWriter.cpp
+++ b/src/private/mx/impl/PropertiesWriter.cpp
@@ -11,6 +11,7 @@
 #include "mx/core/generated/Clef.h"
 #include "mx/core/generated/ClefGroup.h"
 #include "mx/core/generated/Fifths.h"
+#include "mx/core/generated/Interchangeable.h"
 #include "mx/core/generated/Key.h"
 #include "mx/core/generated/KeyAccidental.h"
 #include "mx/core/generated/KeyChoice.h"
@@ -28,6 +29,8 @@
 #include "mx/core/generated/Time.h"
 #include "mx/core/generated/TimeChoice.h"
 #include "mx/core/generated/TimeChoiceGroup.h"
+#include "mx/core/generated/TimeRelation.h"
+#include "mx/core/generated/TimeSeparator.h"
 #include "mx/core/generated/TimeSignatureGroup.h"
 #include "mx/core/generated/TimeSymbol.h"
 #include "mx/core/generated/TraditionalKeyGroup.h"
@@ -140,42 +143,112 @@ void PropertiesWriter::writeTraditionalKey(const api::KeyData &inKeyData, core::
     ioKey.setChoice(core::KeyChoice::traditionalKey(tkg));
 }
 
-void PropertiesWriter::writeTime(const api::TimeSignatureData &value)
+// converts a list of api fractions (a primary or interchangeable meter) to a core OneOrMore;
+// an (invalid) empty meter falls back to a single 4/4 pair
+static core::OneOrMore<core::TimeSignatureGroup> propertiesWriterTimeSignatureGroups(
+    const std::vector<api::TimeFraction> &inFractions)
 {
-    core::Time time{};
-
-    core::TimeSignatureGroup tsg{};
-    tsg.setBeats(value.beats);
-    tsg.setBeatType(value.beatType);
+    std::vector<core::TimeSignatureGroup> groups;
+    for (const auto &fraction : inFractions)
+    {
+        core::TimeSignatureGroup tsg{};
+        tsg.setBeats(fraction.beats);
+        tsg.setBeatType(fraction.beatType);
+        groups.push_back(std::move(tsg));
+    }
+    if (groups.empty())
+    {
+        core::TimeSignatureGroup tsg{};
+        tsg.setBeats("4");
+        tsg.setBeatType("4");
+        groups.push_back(std::move(tsg));
+    }
+    core::OneOrMore<core::TimeSignatureGroup> result{};
+    result.setItems(std::move(groups));
+    return result;
+}
 
+// builds the metered (group) TimeChoice from an api MeteredTimeSignature, and sets the meter's own
+// symbol/separator on the <time> element
+static void propertiesWriterSetMetered(core::Time &ioTime, const api::MeteredTimeSignature &inMetered,
+                                       const Converter &converter)
+{
     core::TimeChoiceGroup tcg{};
-    tcg.setTimeSignature(core::OneOrMore<core::TimeSignatureGroup>{tsg});
-
-    time.setChoice(core::TimeChoice::group(tcg));
+    tcg.setTimeSignature(propertiesWriterTimeSignatureGroups(inMetered.fractions));
 
-    const auto symbol = value.symbol;
-    if (symbol != api::TimeSignatureSymbol::unspecified)
+    if (inMetered.interchangeable.has_value())
     {
-        if (symbol == api::TimeSignatureSymbol::common)
+        const auto &alternate = *inMetered.interchangeable;
+        core::Interchangeable interchangeable{};
+        interchangeable.setTimeSignature(propertiesWriterTimeSignatureGroups(alternate.fractions));
+        if (alternate.relation != api::TimeRelation::unspecified)
         {
-            time.setSymbol(core::TimeSymbol::common());
+            interchangeable.setTimeRelation(converter.convert(alternate.relation));
         }
-        else if (symbol == api::TimeSignatureSymbol::cut)
+        if (alternate.symbol != api::ComplexTimeSymbol::unspecified)
         {
-            time.setSymbol(core::TimeSymbol::cut());
+            interchangeable.setSymbol(converter.convert(alternate.symbol));
         }
-        else if (symbol == api::TimeSignatureSymbol::singleNumber)
+        if (alternate.separator != api::TimeSeparator::unspecified)
         {
-            time.setSymbol(core::TimeSymbol::singleNumber());
+            interchangeable.setSeparator(converter.convert(alternate.separator));
         }
+        tcg.setInterchangeable(std::move(interchangeable));
     }
 
+    ioTime.setChoice(core::TimeChoice::group(std::move(tcg)));
+
+    if (inMetered.symbol != api::ComplexTimeSymbol::unspecified)
+    {
+        ioTime.setSymbol(converter.convert(inMetered.symbol));
+    }
+    if (inMetered.separator != api::TimeSeparator::unspecified)
+    {
+        ioTime.setSeparator(converter.convert(inMetered.separator));
+    }
+}
+
+void PropertiesWriter::writeTime(const api::TimeChoice &value, int staffIndex)
+{
     Converter converter;
+    core::Time time{};
+
+    if (value.isSimple())
+    {
+        const auto &simple = value.asSimple();
+        core::TimeChoiceGroup tcg{};
+        std::vector<api::TimeFraction> fractions{simple.fraction};
+        tcg.setTimeSignature(propertiesWriterTimeSignatureGroups(fractions));
+        time.setChoice(core::TimeChoice::group(std::move(tcg)));
+        if (simple.symbol != api::TimeSignatureSymbol::unspecified)
+        {
+            time.setSymbol(converter.convert(simple.symbol));
+        }
+    }
+    else
+    {
+        const auto &complex = value.asComplex();
+        if (complex.isSenzaMisura())
+        {
+            // the symbol attribute is not used with senza-misura
+            time.setChoice(core::TimeChoice::senzaMisura(complex.asSenzaMisura()));
+        }
+        else
+        {
+            propertiesWriterSetMetered(time, complex.asMetered(), converter);
+        }
+    }
+
     if (value.display != api::Bool::unspecified)
     {
         time.setPrintObject(converter.convert(value.display));
     }
 
+    if (staffIndex != api::INDEX_UNSPECIFIED)
+    {
+        time.setNumber(core::StaffNumber{staffIndex + 1});
+    }
+
     myAttributes.addTime(time);
     myHasContent = true;
 }
diff --git a/src/private/mx/impl/PropertiesWriter.h b/src/private/mx/impl/PropertiesWriter.h
index b3eb43021..16b076a88 100644
--- a/src/private/mx/impl/PropertiesWriter.h
+++ b/src/private/mx/impl/PropertiesWriter.h
@@ -7,7 +7,7 @@
 #include "mx/api/ClefData.h"
 #include "mx/api/KeyData.h"
 #include "mx/api/PartSymbolData.h"
-#include "mx/api/TimeSignatureData.h"
+#include "mx/api/TimeChoice.h"
 #include "mx/api/TransposeData.h"
 #include "mx/core/generated/Attributes.h"
 #include "mx/core/generated/Key.h"
@@ -49,7 +49,9 @@ class PropertiesWriter
     void writeKey(int staffIndex, const api::KeyData &inKeyData);
     static void writeTraditionalKey(const api::KeyData &inKeyData, core::Key &ioKey);
     static void writeNonTraditionalKey(const api::KeyData &inKeyData, core::Key &ioKey);
-    void writeTime(const api::TimeSignatureData &value);
+    // staffIndex is INDEX_UNSPECIFIED for the unscoped <time>, else the zero-based staff index of a
+    // <time number="N"> override.
+    void writeTime(const api::TimeChoice &value, int staffIndex);
     void writeNumStaves(int value);
     void writeStaffDetails(int staffIndex, int staffLines);
     void writeStaffDetails(int staffIndex, int staffLines, double staffSize);
diff --git a/src/private/mx/impl/TimeReader.cpp b/src/private/mx/impl/TimeReader.cpp
index a8ccdd70e..d1ad3a1c6 100644
--- a/src/private/mx/impl/TimeReader.cpp
+++ b/src/private/mx/impl/TimeReader.cpp
@@ -3,115 +3,115 @@
 // Distributed under the MIT License
 
 #include "mx/impl/TimeReader.h"
+#include "mx/api/ComplexTimeSignature.h"
 #include "mx/core/generated/Attributes.h"
+#include "mx/core/generated/Interchangeable.h"
 #include "mx/core/generated/Time.h"
 #include "mx/core/generated/TimeChoice.h"
 #include "mx/core/generated/TimeChoiceGroup.h"
 #include "mx/core/generated/TimeSignatureGroup.h"
-#include "mx/utility/Throw.h"
+#include "mx/impl/Converter.h"
 
-#include <cmath>
-#include <set>
-#include <string>
+#include <utility>
+#include <vector>
 
 namespace mx
 {
 namespace impl
 {
 
-TimeReader::TimeReader(std::span<const core::MusicDataChoice> inMusicDataChoices)
-    : myMusicDataChoiceSet{inMusicDataChoices}, myTime{nullptr}, myIsTimeFound{false}, myTimeSignatureData{}
+static std::vector<api::TimeFraction> timeReaderFractions(std::span<const core::TimeSignatureGroup> inGroups)
 {
-    myIsTimeFound = initialize();
-}
-
-bool TimeReader::getIsTimeFound() const
-{
-    return myIsTimeFound;
-}
-
-mx::api::TimeSignatureData TimeReader::getTimeSignatureData() const
-{
-    return myTimeSignatureData;
+    std::vector<api::TimeFraction> fractions;
+    for (const auto &pair : inGroups)
+    {
+        fractions.push_back(api::TimeFraction{pair.beats(), pair.beatType()});
+    }
+    return fractions;
 }
 
-bool TimeReader::initialize()
+TimeReader::TimeReader(std::span<const core::MusicDataChoice> inMusicDataChoices) : myTimeSignatures{}
 {
-    for (const auto &mdc : myMusicDataChoiceSet)
+    for (const auto &mdc : inMusicDataChoices)
     {
         if (mdc.kind() == core::MusicDataChoice::Kind::attributes)
         {
-            const auto &props = mdc.asAttributes();
-            if (props.time().size() > 0)
+            for (const auto &time : mdc.asAttributes().time())
             {
-                myTime = &props.time().front();
-                return parseTime();
+                myTimeSignatures.push_back(createTimeChoice(time));
             }
         }
     }
-    return false;
 }
 
-bool TimeReader::parseTime()
+const std::vector<TimeReaderResult> &TimeReader::getTimeSignatures() const
 {
-    const auto &timeChoice = myTime->choice();
+    return myTimeSignatures;
+}
+
+TimeReaderResult TimeReader::createTimeChoice(const core::Time &inTime)
+{
+    Converter converter;
+    api::TimeChoice timeChoice;
 
-    if (timeChoice.kind() == core::TimeChoice::Kind::group)
+    const auto &choice = inTime.choice();
+    if (choice.kind() == core::TimeChoice::Kind::senzaMisura)
     {
-        const auto sigGroupSet = timeChoice.asGroup().timeSignature();
-        MX_ASSERT(sigGroupSet.size() > 0);
-        return parseTimeSignatureGroup(sigGroupSet.front());
+        // the string content is the display glyph (often empty); a senza-misura carries no symbol
+        timeChoice = api::TimeChoice::complex(api::ComplexTimeSignature::senzaMisura(choice.asSenzaMisura()));
     }
     else
     {
-        return false;
-        // MX_THROW( "TODO - other time signature stuff" );
-    }
-}
-
-bool TimeReader::parseTimeSignatureGroup(const core::TimeSignatureGroup &timeSig)
-{
-    myTimeSignatureData.beats = timeSig.beats();
-    myTimeSignatureData.beatType = timeSig.beatType();
+        const auto &group = choice.asGroup();
+        api::MeteredTimeSignature metered;
+        metered.fractions = timeReaderFractions(group.timeSignature());
 
-    if (myTime->symbol().has_value())
-    {
-        if (*myTime->symbol() == core::TimeSymbol::common())
+        if (inTime.symbol().has_value())
         {
-            myTimeSignatureData.symbol = api::TimeSignatureSymbol::common;
+            metered.symbol = converter.convert(*inTime.symbol());
         }
-        else if (*myTime->symbol() == core::TimeSymbol::cut())
+        if (inTime.separator().has_value())
         {
-            myTimeSignatureData.symbol = api::TimeSignatureSymbol::cut;
+            metered.separator = converter.convert(*inTime.separator());
         }
-        else if (*myTime->symbol() == core::TimeSymbol::singleNumber())
+
+        if (group.interchangeable().has_value())
         {
-            myTimeSignatureData.symbol = api::TimeSignatureSymbol::singleNumber;
+            const auto &core = *group.interchangeable();
+            api::InterchangeableTimeSignature alternate;
+            alternate.fractions = timeReaderFractions(core.timeSignature());
+            if (core.timeRelation().has_value())
+            {
+                alternate.relation = converter.convert(*core.timeRelation());
+            }
+            if (core.symbol().has_value())
+            {
+                alternate.symbol = converter.convert(*core.symbol());
+            }
+            if (core.separator().has_value())
+            {
+                alternate.separator = converter.convert(*core.separator());
+            }
+            metered.interchangeable = std::move(alternate);
         }
+
+        // complex() collapses back to simple when the meter is really just a plain fraction
+        timeChoice = api::TimeChoice::complex(api::ComplexTimeSignature::metered(std::move(metered)));
     }
-    else
+
+    timeChoice.isImplicit = false;
+    if (inTime.printObject().has_value())
     {
-        myTimeSignatureData.symbol = api::TimeSignatureSymbol::unspecified;
+        timeChoice.display = converter.convert(*inTime.printObject());
     }
 
-    myTimeSignatureData.display = api::Bool::unspecified;
-    if (myTime->printObject().has_value())
+    int staffIndex = api::INDEX_UNSPECIFIED;
+    if (inTime.number().has_value())
     {
-        bool isPrint = *myTime->printObject() == core::YesNo::yes();
-
-        if (isPrint)
-        {
-            myTimeSignatureData.display = api::Bool::yes;
-        }
-        else
-        {
-            myTimeSignatureData.display = api::Bool::no;
-        }
+        staffIndex = static_cast<int>(inTime.number()->value()) - 1;
     }
 
-    myTimeSignatureData.isImplicit = false;
-
-    return true;
+    return TimeReaderResult{std::move(timeChoice), staffIndex};
 }
 } // namespace impl
 } // namespace mx
diff --git a/src/private/mx/impl/TimeReader.h b/src/private/mx/impl/TimeReader.h
index b89b640ea..8201ee561 100644
--- a/src/private/mx/impl/TimeReader.h
+++ b/src/private/mx/impl/TimeReader.h
@@ -4,37 +4,42 @@
 
 #pragma once
 
-#include "mx/api/TimeSignatureData.h"
+#include "mx/api/TimeChoice.h"
 #include "mx/core/generated/MusicDataChoice.h"
-#include "mx/impl/Cursor.h"
+#include "mx/core/generated/Time.h"
 
 #include <span>
+#include <vector>
 
 namespace mx
 {
 namespace impl
 {
+// A single translated <time>: the resulting TimeChoice plus the staff it is scoped to
+// (INDEX_UNSPECIFIED for an unscoped <time> that applies to all staves).
+struct TimeReaderResult
+{
+    api::TimeChoice timeChoice;
+    int staffIndex;
+};
+
+// Finds every <time> element in a measure's <attributes> (there can be several: one unscoped plus
+// per-staff <time number="N"> overrides) and translates each to a TimeChoice. The constructor does
+// all of the work; query the results with getTimeSignatures().
 class TimeReader
 {
   public:
-    // The constructor will do all of the parsing
-    // after that you can query the discovered time
-    // element properties using accessors on the
-    // cached data
-    TimeReader(std::span<const core::MusicDataChoice> inMusicDataChoices);
-    bool getIsTimeFound() const;
-    mx::api::TimeSignatureData getTimeSignatureData() const;
+    explicit TimeReader(std::span<const core::MusicDataChoice> inMusicDataChoices);
 
-  private:
-    std::span<const core::MusicDataChoice> myMusicDataChoiceSet;
-    const core::Time *myTime;
-    bool myIsTimeFound;
-    mx::api::TimeSignatureData myTimeSignatureData;
+    // Every translated <time>, in document order. Each TimeChoice has isImplicit == false.
+    const std::vector<TimeReaderResult> &getTimeSignatures() const;
+
+    // Translates one core::Time to one TimeChoice (all shapes: simple, composite, senza-misura,
+    // interchangeable). isImplicit is left false; staff scoping is returned separately.
+    static TimeReaderResult createTimeChoice(const core::Time &inTime);
 
   private:
-    bool initialize();
-    bool parseTime();
-    bool parseTimeSignatureGroup(const core::TimeSignatureGroup &timeSig);
+    std::vector<TimeReaderResult> myTimeSignatures;
 };
 } // namespace impl
 } // namespace mx
diff --git a/src/private/mxtest/api/ApiK007aScoreData.h b/src/private/mxtest/api/ApiK007aScoreData.h
index 5cf3a884f..1172ca559 100644
--- a/src/private/mxtest/api/ApiK007aScoreData.h
+++ b/src/private/mxtest/api/ApiK007aScoreData.h
@@ -50,8 +50,8 @@ inline void addFirstMeasureWithNote(mx::api::MarkType markType, mx::api::PartDat
     using namespace mx::api;
     outPartData.measures.emplace_back(MeasureData{});
     auto measureP = &outPartData.measures.front();
+    measureP->timeSignature = TimeChoice::simple(TimeSignatureData{});
     measureP->timeSignature.isImplicit = false;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::unspecified;
     measureP->staves.emplace_back(StaffData{});
     auto staffP = &measureP->staves.at(0);
     staffP->clefs.emplace_back(ClefData{});
diff --git a/src/private/mxtest/api/ApiK007cScoreData.h b/src/private/mxtest/api/ApiK007cScoreData.h
index 6057ed5ff..d96f4eecb 100644
--- a/src/private/mxtest/api/ApiK007cScoreData.h
+++ b/src/private/mxtest/api/ApiK007cScoreData.h
@@ -54,8 +54,8 @@ inline void addFirstMeasureWithNote(mx::api::MarkType markType, mx::api::PartDat
     using namespace mx::api;
     outPartData.measures.emplace_back(MeasureData{});
     auto measureP = &outPartData.measures.front();
+    measureP->timeSignature = TimeChoice::simple(TimeSignatureData{});
     measureP->timeSignature.isImplicit = false;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::unspecified;
     measureP->staves.emplace_back(StaffData{});
     auto staffP = &measureP->staves.at(0);
     staffP->clefs.emplace_back(ClefData{});
diff --git a/src/private/mxtest/api/ApiK009bSlurScoreData.h b/src/private/mxtest/api/ApiK009bSlurScoreData.h
index 412bc20af..f6e1c2db0 100644
--- a/src/private/mxtest/api/ApiK009bSlurScoreData.h
+++ b/src/private/mxtest/api/ApiK009bSlurScoreData.h
@@ -29,8 +29,7 @@ inline mx::api::ScoreData apiK009bSlurAttributesScoreData()
     // 1
     part.measures.emplace_back(MeasureData{});
     auto measure = &part.measures.back();
-    measure->timeSignature.beats = "4";
-    measure->timeSignature.beatType = "4";
+    measure->timeSignature = TimeChoice::simple(TimeSignatureData{});
     measure->timeSignature.isImplicit = false;
     measure->staves.emplace_back(StaffData{});
     auto staff = &measure->staves.back();
diff --git a/src/private/mxtest/api/ApiK014aFermatasScoreData.h b/src/private/mxtest/api/ApiK014aFermatasScoreData.h
index 9776dce4a..5f0a480e3 100644
--- a/src/private/mxtest/api/ApiK014aFermatasScoreData.h
+++ b/src/private/mxtest/api/ApiK014aFermatasScoreData.h
@@ -25,8 +25,7 @@ inline mx::api::ScoreData apiK014aFermatasScoreData()
     // 1
     part.measures.emplace_back(MeasureData{});
     auto measure = &part.measures.back();
-    measure->timeSignature.beats = "4";
-    measure->timeSignature.beatType = "4";
+    measure->timeSignature = TimeChoice::simple(TimeSignatureData{});
     measure->timeSignature.isImplicit = false;
     measure->staves.emplace_back(StaffData{});
     auto staff = &measure->staves.back();
diff --git a/src/private/mxtest/api/ApiK015aLayoutScoreData.h b/src/private/mxtest/api/ApiK015aLayoutScoreData.h
index 4498316a0..9b1b178c1 100644
--- a/src/private/mxtest/api/ApiK015aLayoutScoreData.h
+++ b/src/private/mxtest/api/ApiK015aLayoutScoreData.h
@@ -60,8 +60,7 @@ inline mx::api::ScoreData apiK015aLayoutScoreData()
     part.measures.emplace_back(MeasureData{});
     auto measure = &part.measures.back();
     measure->width = 0.0;
-    measure->timeSignature.beats = "4";
-    measure->timeSignature.beatType = "4";
+    measure->timeSignature = TimeChoice::simple(TimeSignatureData{});
     measure->timeSignature.isImplicit = false;
     measure->staves.emplace_back(StaffData{});
     auto staff = &measure->staves.back();
diff --git a/src/private/mxtest/api/ApiLy43eScoreData.h b/src/private/mxtest/api/ApiLy43eScoreData.h
index ba17dedf7..0efa6eb4a 100644
--- a/src/private/mxtest/api/ApiLy43eScoreData.h
+++ b/src/private/mxtest/api/ApiLy43eScoreData.h
@@ -28,8 +28,8 @@ inline mx::api::ScoreData apiLy43eScoreData()
     measureP->keys.emplace_back(KeyData{});
     auto keyP = &measureP->keys.back();
     keyP->mode = KeyMode::major;
+    measureP->timeSignature = TimeChoice::simple(TimeSignatureData{TimeSignatureSymbol::common});
     measureP->timeSignature.isImplicit = false;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::common;
     measureP->staves.emplace_back(StaffData{});
     measureP->staves.emplace_back(StaffData{});
     auto staff1P = &measureP->staves.at(0);
@@ -180,8 +180,8 @@ inline mx::api::ScoreData apiLy43eScoreData()
     // measure 2 - setup
     part.measures.emplace_back(MeasureData{});
     measureP = &part.measures.back();
+    measureP->timeSignature = TimeChoice::simple(TimeSignatureData{TimeSignatureSymbol::common});
     measureP->timeSignature.isImplicit = true;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::common;
     measureP->keys.emplace_back(KeyData{});
     keyP = &measureP->keys.back();
     keyP->fifths = 2;
@@ -291,8 +291,8 @@ inline mx::api::ScoreData apiLy43eScoreData()
     // measure 3 - setup
     part.measures.emplace_back(MeasureData{});
     measureP = &part.measures.back();
+    measureP->timeSignature = TimeChoice::simple(TimeSignatureData{TimeSignatureSymbol::common});
     measureP->timeSignature.isImplicit = true;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::common;
     measureP->staves.emplace_back(StaffData{});
     measureP->staves.emplace_back(StaffData{});
     staff1P = &measureP->staves.at(0);
@@ -397,8 +397,8 @@ inline mx::api::ScoreData apiLy43eScoreData()
     // measure 4 - setup
     part.measures.emplace_back(MeasureData{});
     measureP = &part.measures.back();
+    measureP->timeSignature = TimeChoice::simple(TimeSignatureData{TimeSignatureSymbol::common});
     measureP->timeSignature.isImplicit = true;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::common;
     measureP->staves.emplace_back(StaffData{});
     measureP->staves.emplace_back(StaffData{});
     staff1P = &measureP->staves.at(0);
@@ -409,8 +409,8 @@ inline mx::api::ScoreData apiLy43eScoreData()
     staff1P = &measureP->staves.at(0);
     staff1P->voices[voice].notes.emplace_back(NoteData{});
     noteP = &staff1P->voices[voice].notes.back();
+    measureP->timeSignature = TimeChoice::simple(TimeSignatureData{TimeSignatureSymbol::common});
     measureP->timeSignature.isImplicit = true;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::common;
     noteP->userRequestedVoiceNumber = voice + 1;
     noteP->tickTimePosition = 0;
     noteP->pitchData.step = Step::c;
diff --git a/src/private/mxtest/api/ApiMuAccidentals1ScoreData.h b/src/private/mxtest/api/ApiMuAccidentals1ScoreData.h
index 4ce620621..210bfb730 100644
--- a/src/private/mxtest/api/ApiMuAccidentals1ScoreData.h
+++ b/src/private/mxtest/api/ApiMuAccidentals1ScoreData.h
@@ -37,8 +37,8 @@ inline mx::api::ScoreData apiMuAccidentals1ScoreData()
 
     part.measures.emplace_back(MeasureData{});
     auto measure = &part.measures.back();
-    measure->timeSignature.beats = "3";
-    measure->timeSignature.beatType = "4";
+    measure->timeSignature =
+        TimeChoice::simple(TimeSignatureData{TimeSignatureSymbol::unspecified, TimeFraction{"3", "4"}});
     measure->timeSignature.isImplicit = false;
     measure->staves.emplace_back(StaffData{});
     measure->keys.emplace_back(KeyData{});
@@ -86,8 +86,8 @@ inline mx::api::ScoreData apiMuAccidentals1ScoreData()
 
     part.measures.emplace_back(MeasureData{});
     measure = &part.measures.back();
-    measure->timeSignature.beats = "3";
-    measure->timeSignature.beatType = "4";
+    measure->timeSignature =
+        TimeChoice::simple(TimeSignatureData{TimeSignatureSymbol::unspecified, TimeFraction{"3", "4"}});
     measure->timeSignature.isImplicit = true;
     measure->staves.emplace_back(StaffData{});
     staff = &measure->staves.back();
diff --git a/src/private/mxtest/api/ChordApiTest.cpp b/src/private/mxtest/api/ChordApiTest.cpp
index f502a3aa2..b01c082de 100644
--- a/src/private/mxtest/api/ChordApiTest.cpp
+++ b/src/private/mxtest/api/ChordApiTest.cpp
@@ -209,7 +209,7 @@ TEST(KompChordBug_PIVOTAL_147058063, ChordApi)
     bassClef.tickTimePosition = 0;
     originalStaffPtr->clefs.push_back(bassClef);
 
-    originalMeasure.timeSignature = TimeSignatureData{};
+    originalMeasure.timeSignature = TimeChoice::simple(TimeSignatureData{});
     originalMeasure.timeSignature.isImplicit = false;
 
     originalStaffPtr = &(*originalMeasure.staves.begin());
diff --git a/src/private/mxtest/api/TimeSignatureApiTest.cpp b/src/private/mxtest/api/TimeSignatureApiTest.cpp
index 702528d90..afd18b515 100644
--- a/src/private/mxtest/api/TimeSignatureApiTest.cpp
+++ b/src/private/mxtest/api/TimeSignatureApiTest.cpp
@@ -9,18 +9,64 @@
 #include "mx/api/DocumentManager.h"
 #include "mxtest/file/MxFileRepository.h"
 
+#include <sstream>
+
 using namespace std;
 using namespace mx::api;
 using namespace mxtest;
 
-namespace
+static constexpr const char *const kTimeSignatureApiTestFileName = "testAccidentals1.xml";
+
+// puts the given time signature into a one-part score; extraStaves > 0 adds staves so that per-staff
+// time signatures survive the reader's staff-count sanity check
+static ScoreData timeSignatureApiTestScore(const TimeChoice &inTimeSignature, int extraStaves = 0)
+{
+    ScoreData score;
+    score.parts.push_back(PartData{});
+    auto &part = score.parts.back();
+    part.measures.emplace_back();
+    auto &measure = part.measures.back();
+    measure.timeSignature = inTimeSignature;
+    measure.staves.emplace_back(StaffData{});
+    for (int i = 0; i < extraStaves; ++i)
+    {
+        measure.staves.emplace_back(StaffData{});
+    }
+    return score;
+}
+
+// serializes the score and reads it back through the api
+static ScoreData timeSignatureApiTestRoundTrip(const ScoreData &inScore)
 {
-constexpr const char *const fileName = "testAccidentals1.xml";
+    auto &docMgr = DocumentManager::getInstance();
+    const auto originalIdResult = docMgr.createFromScore(inScore);
+    if (!originalIdResult.ok())
+    {
+        return ScoreData{};
+    }
+    const int originalId = originalIdResult.value();
+    std::stringstream xml;
+    docMgr.writeToStream(originalId, xml);
+    docMgr.destroyDocument(originalId);
+    std::istringstream iss{xml.str()};
+    const auto reloadedIdResult = docMgr.createFromStream(iss);
+    if (!reloadedIdResult.ok())
+    {
+        return ScoreData{};
+    }
+    const int reloadedId = reloadedIdResult.value();
+    const auto reloadedScoreResult = docMgr.getData(reloadedId);
+    docMgr.destroyDocument(reloadedId);
+    if (!reloadedScoreResult.ok())
+    {
+        return ScoreData{};
+    }
+    return reloadedScoreResult.value();
 }
 
 TEST(implicitCarryover, TimeSignatureApi)
 {
-    const auto scoreData = mxtest::MxFileRepository::loadFile(fileName);
+    const auto scoreData = mxtest::MxFileRepository::loadFile(kTimeSignatureApiTestFileName);
     CHECK_EQUAL(1, scoreData.parts.size());
     const auto &part = scoreData.parts.front();
     CHECK_EQUAL(2, part.measures.size())
@@ -28,16 +74,284 @@ TEST(implicitCarryover, TimeSignatureApi)
     auto t = measureIter->timeSignature;
 
     CHECK(!t.isImplicit);
-    CHECK_EQUAL("3", t.beats);
-    CHECK_EQUAL("4", t.beatType);
-    CHECK(t.symbol == TimeSignatureSymbol::unspecified);
+    REQUIRE(t.isSimple());
+    CHECK_EQUAL("3", t.asSimple().fraction.beats);
+    CHECK_EQUAL("4", t.asSimple().fraction.beatType);
+    CHECK(t.asSimple().symbol == TimeSignatureSymbol::unspecified);
 
     ++measureIter;
     t = measureIter->timeSignature;
     CHECK(t.isImplicit);
-    CHECK_EQUAL("3", t.beats);
-    CHECK_EQUAL("4", t.beatType);
-    CHECK(t.symbol == TimeSignatureSymbol::unspecified);
+    REQUIRE(t.isSimple());
+    CHECK_EQUAL("3", t.asSimple().fraction.beats);
+    CHECK_EQUAL("4", t.asSimple().fraction.beatType);
+}
+
+T_END
+
+TEST(defaultIsSimpleImplicitFourFour, TimeSignatureApi)
+{
+    TimeChoice t;
+    CHECK(t.isImplicit);
+    REQUIRE(t.isSimple());
+    CHECK(t.kind() == TimeChoice::Kind::simple);
+    CHECK_EQUAL("4", t.asSimple().fraction.beats);
+    CHECK_EQUAL("4", t.asSimple().fraction.beatType);
+    CHECK(t.asSimple().symbol == TimeSignatureSymbol::unspecified);
+    CHECK(t.display == Bool::unspecified);
+}
+
+T_END
+
+TEST(autoCollapseSimpleEquivalent, TimeSignatureApi)
+{
+    // a plain single-fraction meter with no decorations collapses to simple
+    MeteredTimeSignature plain;
+    plain.fractions = {{"3", "4"}};
+    auto collapsed = TimeChoice::complex(ComplexTimeSignature::metered(plain));
+    REQUIRE(collapsed.isSimple());
+    CHECK_EQUAL("3", collapsed.asSimple().fraction.beats);
+
+    // common/cut collapse too, mapping to the narrow simple symbol
+    MeteredTimeSignature common;
+    common.symbol = ComplexTimeSymbol::common;
+    auto collapsedCommon = TimeChoice::complex(ComplexTimeSignature::metered(common));
+    REQUIRE(collapsedCommon.isSimple());
+    CHECK(collapsedCommon.asSimple().symbol == TimeSignatureSymbol::common);
+}
+
+T_END
+
+TEST(complexStaysComplex, TimeSignatureApi)
+{
+    // more than one fraction -> genuinely composite, stays complex
+    MeteredTimeSignature composite;
+    composite.fractions = {{"2", "4"}, {"3", "8"}};
+    CHECK(TimeChoice::complex(ComplexTimeSignature::metered(composite)).isComplex());
+
+    // an unusual symbol (no simple equivalent) keeps it complex
+    MeteredTimeSignature single;
+    single.fractions = {{"3", "4"}};
+    single.symbol = ComplexTimeSymbol::singleNumber;
+    CHECK(TimeChoice::complex(ComplexTimeSignature::metered(single)).isComplex());
+
+    // a separator keeps it complex
+    MeteredTimeSignature separated;
+    separated.fractions = {{"3", "4"}};
+    separated.separator = TimeSeparator::diagonal;
+    CHECK(TimeChoice::complex(ComplexTimeSignature::metered(separated)).isComplex());
+
+    // an interchangeable alternate keeps it complex
+    MeteredTimeSignature dual;
+    dual.fractions = {{"3", "4"}};
+    InterchangeableTimeSignature alt;
+    alt.fractions = {{"6", "8"}};
+    dual.interchangeable = alt;
+    CHECK(TimeChoice::complex(ComplexTimeSignature::metered(dual)).isComplex());
+
+    // senza-misura is always complex
+    CHECK(TimeChoice::complex(ComplexTimeSignature::senzaMisura("X")).isComplex());
+}
+
+T_END
+
+TEST(equality, TimeSignatureApi)
+{
+    TimeChoice a;
+    TimeChoice b;
+    CHECK(a == b);
+
+    // isImplicit is part of equality
+    b.isImplicit = false;
+    CHECK(a != b);
+    b.isImplicit = true;
+    CHECK(a == b);
+
+    // simple fraction difference
+    a = TimeChoice::simple(TimeSignatureData{TimeSignatureSymbol::unspecified, {"3", "4"}});
+    CHECK(a != b);
+    b = TimeChoice::simple(TimeSignatureData{TimeSignatureSymbol::unspecified, {"3", "4"}});
+    CHECK(a == b);
+
+    // simple vs complex never compare equal
+    MeteredTimeSignature composite;
+    composite.fractions = {{"2", "4"}, {"3", "8"}};
+    a = TimeChoice::complex(ComplexTimeSignature::metered(composite));
+    CHECK(a != b);
+
+    // nested composite second-fraction difference
+    MeteredTimeSignature other;
+    other.fractions = {{"2", "4"}, {"3", "16"}};
+    b = TimeChoice::complex(ComplexTimeSignature::metered(other));
+    CHECK(a != b);
+    b = TimeChoice::complex(ComplexTimeSignature::metered(composite));
+    CHECK(a == b);
+
+    // interchangeable relation-only difference
+    MeteredTimeSignature dualA;
+    dualA.fractions = {{"3", "4"}};
+    InterchangeableTimeSignature altA;
+    altA.fractions = {{"6", "8"}};
+    altA.relation = TimeRelation::parentheses;
+    dualA.interchangeable = altA;
+    a = TimeChoice::complex(ComplexTimeSignature::metered(dualA));
+
+    MeteredTimeSignature dualB = dualA;
+    dualB.interchangeable->relation = TimeRelation::bracket;
+    b = TimeChoice::complex(ComplexTimeSignature::metered(dualB));
+    CHECK(a != b);
+
+    // senza-misura glyph difference
+    a = TimeChoice::complex(ComplexTimeSignature::senzaMisura("X"));
+    b = TimeChoice::complex(ComplexTimeSignature::senzaMisura(""));
+    CHECK(a != b);
+    b = TimeChoice::complex(ComplexTimeSignature::senzaMisura("X"));
+    CHECK(a == b);
+}
+
+T_END
+
+TEST(roundTripComposite, TimeSignatureApi)
+{
+    MeteredTimeSignature composite;
+    composite.fractions = {{"2", "4"}, {"3", "8"}};
+    auto t = TimeChoice::complex(ComplexTimeSignature::metered(composite));
+    t.isImplicit = false;
+
+    const auto reloaded = timeSignatureApiTestRoundTrip(timeSignatureApiTestScore(t));
+    REQUIRE(!reloaded.parts.empty());
+    const auto &actual = reloaded.parts.at(0).measures.at(0).timeSignature;
+    CHECK(!actual.isImplicit);
+    REQUIRE(actual.isComplex());
+    REQUIRE(actual.asComplex().isMetered());
+    const auto &fractions = actual.asComplex().asMetered().fractions;
+    REQUIRE(2 == fractions.size());
+    CHECK_EQUAL("2", fractions.at(0).beats);
+    CHECK_EQUAL("4", fractions.at(0).beatType);
+    CHECK_EQUAL("3", fractions.at(1).beats);
+    CHECK_EQUAL("8", fractions.at(1).beatType);
+}
+
+T_END
+
+TEST(roundTripSenzaMisuraWithGlyph, TimeSignatureApi)
+{
+    auto t = TimeChoice::complex(ComplexTimeSignature::senzaMisura("X"));
+    t.isImplicit = false;
+
+    const auto reloaded = timeSignatureApiTestRoundTrip(timeSignatureApiTestScore(t));
+    REQUIRE(!reloaded.parts.empty());
+    const auto &actual = reloaded.parts.at(0).measures.at(0).timeSignature;
+    CHECK(!actual.isImplicit);
+    REQUIRE(actual.isComplex());
+    REQUIRE(actual.asComplex().isSenzaMisura());
+    CHECK_EQUAL("X", actual.asComplex().asSenzaMisura());
+}
+
+T_END
+
+TEST(roundTripSenzaMisuraWithoutGlyph, TimeSignatureApi)
+{
+    auto t = TimeChoice::complex(ComplexTimeSignature::senzaMisura());
+    t.isImplicit = false;
+
+    const auto reloaded = timeSignatureApiTestRoundTrip(timeSignatureApiTestScore(t));
+    REQUIRE(!reloaded.parts.empty());
+    const auto &actual = reloaded.parts.at(0).measures.at(0).timeSignature;
+    CHECK(!actual.isImplicit);
+    REQUIRE(actual.isComplex());
+    REQUIRE(actual.asComplex().isSenzaMisura());
+    CHECK_EQUAL("", actual.asComplex().asSenzaMisura());
+}
+
+T_END
+
+TEST(roundTripInterchangeable, TimeSignatureApi)
+{
+    MeteredTimeSignature metered;
+    metered.fractions = {{"3", "4"}};
+    InterchangeableTimeSignature alt;
+    alt.fractions = {{"6", "8"}, {"3", "8"}}; // a composite alternate
+    alt.relation = TimeRelation::parentheses;
+    alt.symbol = ComplexTimeSymbol::cut;
+    alt.separator = TimeSeparator::horizontal;
+    metered.interchangeable = alt;
+    auto t = TimeChoice::complex(ComplexTimeSignature::metered(metered));
+    t.isImplicit = false;
+
+    const auto reloaded = timeSignatureApiTestRoundTrip(timeSignatureApiTestScore(t));
+    REQUIRE(!reloaded.parts.empty());
+    const auto &actual = reloaded.parts.at(0).measures.at(0).timeSignature;
+    REQUIRE(actual.isComplex());
+    REQUIRE(actual.asComplex().isMetered());
+    const auto &actualMetered = actual.asComplex().asMetered();
+    CHECK_EQUAL("3", actualMetered.fractions.at(0).beats);
+    REQUIRE(actualMetered.interchangeable.has_value());
+    CHECK(*actualMetered.interchangeable == alt);
+}
+
+T_END
+
+TEST(roundTripWidenedSymbolAndSeparator, TimeSignatureApi)
+{
+    MeteredTimeSignature metered;
+    metered.fractions = {{"3", "4"}};
+    metered.symbol = ComplexTimeSymbol::note;
+    metered.separator = TimeSeparator::diagonal;
+    auto t = TimeChoice::complex(ComplexTimeSignature::metered(metered));
+    t.isImplicit = false;
+
+    const auto reloaded = timeSignatureApiTestRoundTrip(timeSignatureApiTestScore(t));
+    REQUIRE(!reloaded.parts.empty());
+    const auto &actual = reloaded.parts.at(0).measures.at(0).timeSignature;
+    REQUIRE(actual.isComplex());
+    REQUIRE(actual.asComplex().isMetered());
+    CHECK(actual.asComplex().asMetered().symbol == ComplexTimeSymbol::note);
+    CHECK(actual.asComplex().asMetered().separator == TimeSeparator::diagonal);
+}
+
+T_END
+
+TEST(roundTripPerStaff, TimeSignatureApi)
+{
+    // staff 0 (unscoped default) in 4/4; staff 1 overridden to 3/8
+    auto shared = TimeChoice::simple(TimeSignatureData{});
+    shared.isImplicit = false;
+
+    auto score = timeSignatureApiTestScore(shared, 1); // two staves
+
+    auto staffTime = TimeChoice::simple(TimeSignatureData{TimeSignatureSymbol::unspecified, {"3", "8"}});
+    staffTime.isImplicit = false;
+    score.parts.at(0).measures.at(0).staffTimeSignatures[1] = staffTime;
+
+    // add a second measure so we can observe per-staff carry-forward
+    score.parts.at(0).measures.emplace_back();
+    auto &secondMeasure = score.parts.at(0).measures.back();
+    secondMeasure.staves.emplace_back(StaffData{});
+    secondMeasure.staves.emplace_back(StaffData{});
+
+    const auto reloaded = timeSignatureApiTestRoundTrip(score);
+    REQUIRE(!reloaded.parts.empty());
+    REQUIRE(2 == reloaded.parts.at(0).measures.size());
+
+    const auto &firstMeasure = reloaded.parts.at(0).measures.at(0);
+    CHECK(!firstMeasure.timeSignature.isImplicit);
+    CHECK_EQUAL("4", firstMeasure.timeSignature.asSimple().fraction.beats);
+    REQUIRE(1 == firstMeasure.staffTimeSignatures.size());
+    REQUIRE(firstMeasure.staffTimeSignatures.count(1) == 1);
+    const auto &actualStaffTime = firstMeasure.staffTimeSignatures.at(1);
+    CHECK(!actualStaffTime.isImplicit);
+    REQUIRE(actualStaffTime.isSimple());
+    CHECK_EQUAL("3", actualStaffTime.asSimple().fraction.beats);
+    CHECK_EQUAL("8", actualStaffTime.asSimple().fraction.beatType);
+
+    // the override carries forward, implicitly, into the next measure
+    const auto &carried = reloaded.parts.at(0).measures.at(1);
+    CHECK(carried.timeSignature.isImplicit);
+    REQUIRE(1 == carried.staffTimeSignatures.size());
+    REQUIRE(carried.staffTimeSignatures.count(1) == 1);
+    CHECK(carried.staffTimeSignatures.at(1).isImplicit);
+    CHECK_EQUAL("3", carried.staffTimeSignatures.at(1).asSimple().fraction.beats);
 }
 
 T_END
diff --git a/src/private/mxtest/api/roundtrip-baseline.txt b/src/private/mxtest/api/roundtrip-baseline.txt
index c4b19619e..c096a1ce2 100644
--- a/src/private/mxtest/api/roundtrip-baseline.txt
+++ b/src/private/mxtest/api/roundtrip-baseline.txt
@@ -298,3 +298,13 @@ musuite/testAccidentals2.xml
 # MeasureWriter: the field and its Converter existed but neither side ever
 # called it, so <measure-numbering> was silently dropped on round-trip.
 ksuite/k015a_System_Layout.xml
+
+# Unblocked by the TimeSignatureData redesign: <time> now models every spec
+# shape (composite/additive multi-pair meters, senza-misura, interchangeable,
+# per-staff number=, separator, note/dotted-note symbols) instead of reading
+# only the first beats/beat-type pair of the first <time> and dropping the
+# rest on round-trip.
+lysuite/ly11d_TimeSignatures_CompoundMultiple.xml
+lysuite/ly11e_TimeSignatures_CompoundMixed.xml
+lysuite/ly11f_TimeSignatures_SymbolMeaning.xml
+lysuite/ly11h_TimeSignatures_SenzaMisura.xml