From f1a39750a45cca36f78b6cede1a1c37e6b7f7d21 Mon Sep 17 00:00:00 2001
From: Matthew James Briggs <matthew.james.briggs@gmail.com>
Date: Mon, 6 Jul 2026 05:58:38 +0000
Subject: [PATCH] feat(api): time signature staff-scoping and composite meter
 support

Splits the time-signature half out of the original combined time-signature
and transposition PR so each can be reviewed and merged independently.

Closes #268
---
 src/include/mx/api/MeasureData.h              |  10 +-
 src/include/mx/api/TimeSignatureData.h        |  50 +++++--
 src/private/mx/examples/Write.cpp             |   5 +-
 src/private/mx/impl/Cursor.cpp                |   2 +-
 src/private/mx/impl/Cursor.h                  |   2 +-
 src/private/mx/impl/MeasureReader.cpp         |  78 ++++++++--
 src/private/mx/impl/MeasureWriter.cpp         |   7 +-
 src/private/mx/impl/PartReader.cpp            |   2 +-
 src/private/mx/impl/PropertiesWriter.cpp      |  24 ++-
 src/private/mx/impl/PropertiesWriter.h        |   2 +-
 src/private/mx/impl/TimeReader.cpp            |  87 +++++++----
 src/private/mx/impl/TimeReader.h              |  22 ++-
 src/private/mxtest/api/ApiK007aScoreData.h    |   4 +-
 src/private/mxtest/api/ApiK007cScoreData.h    |   4 +-
 .../mxtest/api/ApiK009bSlurScoreData.h        |   6 +-
 .../mxtest/api/ApiK014aFermatasScoreData.h    |   6 +-
 .../mxtest/api/ApiK015aLayoutScoreData.h      |   6 +-
 src/private/mxtest/api/ApiLy43eScoreData.h    |  20 +--
 .../mxtest/api/ApiMuAccidentals1ScoreData.h   |  12 +-
 src/private/mxtest/api/ChordApiTest.cpp       |   4 +-
 .../mxtest/api/TimeSignatureApiTest.cpp       | 141 +++++++++++++++++-
 src/private/mxtest/file/MxFileRepositoy.cpp   |   1 +
 22 files changed, 391 insertions(+), 104 deletions(-)

diff --git a/src/include/mx/api/MeasureData.h b/src/include/mx/api/MeasureData.h
index 659796157..a4f72d9b0 100644
--- a/src/include/mx/api/MeasureData.h
+++ b/src/include/mx/api/MeasureData.h
@@ -31,7 +31,11 @@ class MeasureData
     // this is the notes and other music data
     std::vector<StaffData> staves;
 
-    TimeSignatureData timeSignature;
+    // resolved, carried-forward time signature(s) in effect for this measure. Normally a single
+    // entry with staffIndex == INDEX_UNSPECIFIED (applies to all staves). When staff-scoped time
+    // signatures are used, there is one entry per staff. Mirrors the isImplicit carry-forward
+    // semantics of the old singular field.
+    std::vector<TimeSignatureData> timeSignatures;
 
     // an empty measureNumber indicates a normal
     // measure number (i.e. the measure's
@@ -100,7 +104,7 @@ class MeasureData
     std::vector<TransposeData> transpositions;
 
     MeasureData()
-        : staves{}, timeSignature{}, number{}, measureNumbering{MeasureNumbering::unspecified},
+        : staves{}, timeSignatures{TimeSignatureData{}}, number{}, measureNumbering{MeasureNumbering::unspecified},
           multiMeasureRest{VALUE_UNSPECIFIED}, implicit{Bool::unspecified}, nonControlling{Bool::unspecified},
           width{DOUBLE_UNSPECIFIED}
     {
@@ -109,7 +113,7 @@ class MeasureData
 
 MXAPI_EQUALS_BEGIN(MeasureData)
 MXAPI_EQUALS_MEMBER(staves)
-MXAPI_EQUALS_MEMBER(timeSignature)
+MXAPI_EQUALS_MEMBER(timeSignatures)
 MXAPI_EQUALS_MEMBER(number)
 MXAPI_EQUALS_MEMBER(measureNumbering)
 MXAPI_EQUALS_MEMBER(multiMeasureRest)
diff --git a/src/include/mx/api/TimeSignatureData.h b/src/include/mx/api/TimeSignatureData.h
index a6829808f..c4b915b08 100644
--- a/src/include/mx/api/TimeSignatureData.h
+++ b/src/include/mx/api/TimeSignatureData.h
@@ -7,6 +7,7 @@
 #include "mx/api/ApiCommon.h"
 
 #include <string>
+#include <vector>
 
 namespace mx
 {
@@ -20,17 +21,35 @@ enum class TimeSignatureSymbol
     singleNumber
 };
 
-class TimeSignatureData
+// TimeSignatureComponent represents a single beats/beat-type pair. Most time signatures have
+// exactly one component (e.g. "4/4"). Composite time signatures (e.g. "3+2/8" notated with
+// multiple <time> children, or an additive meter written as separate beats/beat-type pairs)
+// are represented by multiple components.
+struct TimeSignatureComponent
 {
-  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"
     std::string beats;
 
     // the bottom number of the time signature, e.g. "4" in a "5/4"
     std::string beatType;
+};
+
+MXAPI_EQUALS_BEGIN(TimeSignatureComponent)
+MXAPI_EQUALS_MEMBER(beats)
+MXAPI_EQUALS_MEMBER(beatType)
+MXAPI_EQUALS_END;
+MXAPI_NOT_EQUALS_AND_VECTORS(TimeSignatureComponent);
+
+class TimeSignatureData
+{
+  public:
+    // common, cut
+    TimeSignatureSymbol symbol;
+
+    // one beats/beat-type pair per component. most time signatures have exactly one entry; a
+    // composite/additive time signature (e.g. multiple <time> beats/beat-type pairs) has more
+    // than one. use setSimple() to populate the common single-component case.
+    std::vector<TimeSignatureComponent> components;
 
     // a time signature is implicit when it is not specified by the musicxml
     bool isImplicit;
@@ -39,24 +58,35 @@ class TimeSignatureData
     // implicit, the 'display' field will be ignored
     Bool display;
 
+    // this value is optional. INDEX_UNSPECIFIED means unspecified. when value is
+    // unspecified it means that the time signature applies to all staves within the part
+    int staffIndex;
+
+    // convenience helper for the common case of a single beats/beat-type pair.
+    void setSimple(const std::string &beats, const std::string &beatType)
+    {
+        components.clear();
+        components.push_back(TimeSignatureComponent{beats, beatType});
+    }
+
     inline bool isEqualTo(const TimeSignatureData &other) const
     {
-        return (beats == other.beats) && (beatType == other.beatType) && (symbol == other.symbol);
+        return (components == other.components) && (symbol == other.symbol) && (staffIndex == other.staffIndex);
     }
 
     TimeSignatureData()
-        : symbol{TimeSignatureSymbol::unspecified}, beats{"4"}, beatType{"4"}, isImplicit{true},
-          display{Bool::unspecified}
+        : symbol{TimeSignatureSymbol::unspecified}, components{TimeSignatureComponent{"4", "4"}}, isImplicit{true},
+          display{Bool::unspecified}, staffIndex{INDEX_UNSPECIFIED}
     {
     }
 };
 
 MXAPI_EQUALS_BEGIN(TimeSignatureData)
 MXAPI_EQUALS_MEMBER(symbol)
-MXAPI_EQUALS_MEMBER(beats)
-MXAPI_EQUALS_MEMBER(beatType)
+MXAPI_EQUALS_MEMBER(components)
 MXAPI_EQUALS_MEMBER(isImplicit)
 MXAPI_EQUALS_MEMBER(display)
+MXAPI_EQUALS_MEMBER(staffIndex)
 MXAPI_EQUALS_END;
 MXAPI_NOT_EQUALS_AND_VECTORS(TimeSignatureData);
 } // namespace api
diff --git a/src/private/mx/examples/Write.cpp b/src/private/mx/examples/Write.cpp
index 57a8e8c07..77c664ba9 100644
--- a/src/private/mx/examples/Write.cpp
+++ b/src/private/mx/examples/Write.cpp
@@ -39,9 +39,8 @@ 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.isImplicit = false;
+    measure.timeSignatures.front().setSimple("4", "4");
+    measure.timeSignatures.front().isImplicit = false;
 
     // add a staff
     measure.staves.emplace_back(StaffData{});
diff --git a/src/private/mx/impl/Cursor.cpp b/src/private/mx/impl/Cursor.cpp
index f5cc20cf7..b251dedc5 100644
--- a/src/private/mx/impl/Cursor.cpp
+++ b/src/private/mx/impl/Cursor.cpp
@@ -12,7 +12,7 @@ namespace mx
 namespace impl
 {
 Cursor::Cursor(int numStaves, int globalTicksPerQuarter)
-    : timeSignature{}, ticksPerQuarter(globalTicksPerQuarter), tickTimePosition(0), voiceIndex(0), staffIndex(0),
+    : timeSignatures{}, 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..62a5aaf59 100644
--- a/src/private/mx/impl/Cursor.h
+++ b/src/private/mx/impl/Cursor.h
@@ -19,7 +19,7 @@ namespace impl
 class Cursor
 {
   public:
-    api::TimeSignatureData timeSignature;
+    std::vector<api::TimeSignatureData> timeSignatures;
     int ticksPerQuarter;
     int tickTimePosition;
     int voiceIndex;
diff --git a/src/private/mx/impl/MeasureReader.cpp b/src/private/mx/impl/MeasureReader.cpp
index 199e67319..a1b399dec 100644
--- a/src/private/mx/impl/MeasureReader.cpp
+++ b/src/private/mx/impl/MeasureReader.cpp
@@ -216,24 +216,82 @@ impl::MeasureCursor MeasureReader::getCursor() const
 void MeasureReader::parseTimeSignature() const
 {
     TimeReader timeReader{myPartwiseMeasure.musicData()};
-    api::TimeSignatureData timeSignature;
 
-    if (timeReader.getIsTimeFound())
+    std::vector<api::TimeSignatureData> carriedForward;
+    if (myCurrentCursor.measureIndex > 0)
     {
-        timeSignature = timeReader.getTimeSignatureData();
-        timeSignature.isImplicit = false;
+        carriedForward = myPreviousMeasureCursor.timeSignatures;
     }
-    else // no time signature was found
+
+    std::vector<api::TimeSignatureData> effective;
+
+    if (!timeReader.getIsTimeFound())
+    {
+        // no <time> this measure -> copy carried-forward list verbatim, force implicit. at
+        // measure 0 there is nothing to carry forward yet, so fall back to a single default
+        // (matches the pre-vector behavior of a default-constructed TimeSignatureData).
+        effective = carriedForward;
+        if (effective.empty())
+        {
+            effective.push_back(api::TimeSignatureData{});
+        }
+        for (auto &ts : effective)
+        {
+            ts.isImplicit = true;
+        }
+    }
+    else
     {
-        if (myCurrentCursor.measureIndex > 0)
+        auto parsed = timeReader.getTimeSignatures();
+        bool anyUnscoped = false;
+        for (auto &ts : parsed)
         {
-            timeSignature = myPreviousMeasureCursor.timeSignature;
+            ts.isImplicit = false;
+            if (ts.staffIndex != api::INDEX_UNSPECIFIED && ts.staffIndex > myCurrentCursor.getNumStaves() - 1)
+            {
+                ts.staffIndex = api::INDEX_UNSPECIFIED;
+            }
+            if (ts.staffIndex == api::INDEX_UNSPECIFIED)
+            {
+                anyUnscoped = true;
+            }
+        }
+
+        if (anyUnscoped)
+        {
+            // one or more unscoped entries -> the new effective list replaces everything
+            effective = std::move(parsed);
+        }
+        else
+        {
+            // all entries are staff-scoped -> merge into the carried-forward list by staffIndex
+            effective = carriedForward;
+            for (auto &e : effective)
+            {
+                e.isImplicit = true;
+            }
+            for (const auto &p : parsed)
+            {
+                bool replaced = false;
+                for (auto &e : effective)
+                {
+                    if (e.staffIndex == p.staffIndex)
+                    {
+                        e = p;
+                        replaced = true;
+                        break;
+                    }
+                }
+                if (!replaced)
+                {
+                    effective.push_back(p);
+                }
+            }
         }
-        timeSignature.isImplicit = true;
     }
 
-    myOutMeasureData.timeSignature = timeSignature;
-    myCurrentCursor.timeSignature = timeSignature;
+    myOutMeasureData.timeSignatures = effective;
+    myCurrentCursor.timeSignatures = effective;
     advanceTickTimePosition(0, "parseTimeSignature");
 }
 
diff --git a/src/private/mx/impl/MeasureWriter.cpp b/src/private/mx/impl/MeasureWriter.cpp
index a9b548a2b..288e20918 100644
--- a/src/private/mx/impl/MeasureWriter.cpp
+++ b/src/private/mx/impl/MeasureWriter.cpp
@@ -129,9 +129,12 @@ void MeasureWriter::writeMeasureGlobals()
         myPropertiesWriter->writePartSymbol(*myMeasureData.partSymbol);
     }
 
-    if (!myMeasureData.timeSignature.isImplicit)
+    for (const auto &timeSignature : myMeasureData.timeSignatures)
     {
-        myPropertiesWriter->writeTime(myMeasureData.timeSignature);
+        if (!timeSignature.isImplicit)
+        {
+            myPropertiesWriter->writeTime(timeSignature.staffIndex, timeSignature);
+        }
     }
 
     int localStaffCounter = 0;
diff --git a/src/private/mx/impl/PartReader.cpp b/src/private/mx/impl/PartReader.cpp
index 2311ff004..b031f5ba1 100644
--- a/src/private/mx/impl/PartReader.cpp
+++ b/src/private/mx/impl/PartReader.cpp
@@ -124,7 +124,7 @@ api::PartData PartReader::getPartData()
         {
             myOutPartData.transposition = transpositionData;
         }
-        myCurrentCursor.timeSignature = measureData.timeSignature;
+        myCurrentCursor.timeSignatures = measureData.timeSignatures;
         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..cb2852244 100644
--- a/src/private/mx/impl/PropertiesWriter.cpp
+++ b/src/private/mx/impl/PropertiesWriter.cpp
@@ -140,16 +140,30 @@ void PropertiesWriter::writeTraditionalKey(const api::KeyData &inKeyData, core::
     ioKey.setChoice(core::KeyChoice::traditionalKey(tkg));
 }
 
-void PropertiesWriter::writeTime(const api::TimeSignatureData &value)
+void PropertiesWriter::writeTime(int staffIndex, const api::TimeSignatureData &value)
 {
     core::Time time{};
 
-    core::TimeSignatureGroup tsg{};
-    tsg.setBeats(value.beats);
-    tsg.setBeatType(value.beatType);
+    if (staffIndex >= 0)
+    {
+        time.setNumber(core::StaffNumber{staffIndex + 1});
+    }
+
+    std::vector<core::TimeSignatureGroup> groups;
+    groups.reserve(value.components.size());
+    for (const auto &component : value.components)
+    {
+        core::TimeSignatureGroup tsg{};
+        tsg.setBeats(component.beats);
+        tsg.setBeatType(component.beatType);
+        groups.push_back(std::move(tsg));
+    }
+
+    core::OneOrMore<core::TimeSignatureGroup> timeSigGroups{};
+    timeSigGroups.setItems(std::move(groups));
 
     core::TimeChoiceGroup tcg{};
-    tcg.setTimeSignature(core::OneOrMore<core::TimeSignatureGroup>{tsg});
+    tcg.setTimeSignature(std::move(timeSigGroups));
 
     time.setChoice(core::TimeChoice::group(tcg));
 
diff --git a/src/private/mx/impl/PropertiesWriter.h b/src/private/mx/impl/PropertiesWriter.h
index b3eb43021..3b9cef668 100644
--- a/src/private/mx/impl/PropertiesWriter.h
+++ b/src/private/mx/impl/PropertiesWriter.h
@@ -49,7 +49,7 @@ 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);
+    void writeTime(int staffIndex, const api::TimeSignatureData &value);
     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..d1ee380ff 100644
--- a/src/private/mx/impl/TimeReader.cpp
+++ b/src/private/mx/impl/TimeReader.cpp
@@ -20,7 +20,7 @@ namespace impl
 {
 
 TimeReader::TimeReader(std::span<const core::MusicDataChoice> inMusicDataChoices)
-    : myMusicDataChoiceSet{inMusicDataChoices}, myTime{nullptr}, myIsTimeFound{false}, myTimeSignatureData{}
+    : myMusicDataChoiceSet{inMusicDataChoices}, myIsTimeFound{false}, myTimeSignatures{}
 {
     myIsTimeFound = initialize();
 }
@@ -30,9 +30,9 @@ bool TimeReader::getIsTimeFound() const
     return myIsTimeFound;
 }
 
-mx::api::TimeSignatureData TimeReader::getTimeSignatureData() const
+std::vector<mx::api::TimeSignatureData> TimeReader::getTimeSignatures() const
 {
-    return myTimeSignatureData;
+    return myTimeSignatures;
 }
 
 bool TimeReader::initialize()
@@ -44,23 +44,51 @@ bool TimeReader::initialize()
             const auto &props = mdc.asAttributes();
             if (props.time().size() > 0)
             {
-                myTime = &props.time().front();
-                return parseTime();
+                bool anyParsed = false;
+                for (const auto &time : props.time())
+                {
+                    if (parseTime(time))
+                    {
+                        anyParsed = true;
+                    }
+                }
+                return anyParsed;
             }
         }
     }
     return false;
 }
 
-bool TimeReader::parseTime()
+bool TimeReader::parseTime(const core::Time &time)
 {
-    const auto &timeChoice = myTime->choice();
+    const auto &timeChoice = time.choice();
 
     if (timeChoice.kind() == core::TimeChoice::Kind::group)
     {
         const auto sigGroupSet = timeChoice.asGroup().timeSignature();
         MX_ASSERT(sigGroupSet.size() > 0);
-        return parseTimeSignatureGroup(sigGroupSet.front());
+
+        // all TimeSignatureGroup entries in this <time> element share the same symbol/display/
+        // staffIndex (those live on the <time> element itself); each contributes one component
+        // to a single TimeSignatureData, so a composite time signature round-trips as one
+        // TimeSignatureData with multiple components.
+        api::TimeSignatureData timeSignatureData;
+        bool isFirst = true;
+        for (const auto &sigGroup : sigGroupSet)
+        {
+            if (isFirst)
+            {
+                parseTimeSignatureGroup(time, sigGroup, timeSignatureData);
+                isFirst = false;
+            }
+            else
+            {
+                timeSignatureData.components.push_back(
+                    api::TimeSignatureComponent{sigGroup.beats(), sigGroup.beatType()});
+            }
+        }
+        myTimeSignatures.push_back(std::move(timeSignatureData));
+        return true;
     }
     else
     {
@@ -69,47 +97,56 @@ bool TimeReader::parseTime()
     }
 }
 
-bool TimeReader::parseTimeSignatureGroup(const core::TimeSignatureGroup &timeSig)
+bool TimeReader::parseTimeSignatureGroup(const core::Time &time, const core::TimeSignatureGroup &timeSig,
+                                         mx::api::TimeSignatureData &outData)
 {
-    myTimeSignatureData.beats = timeSig.beats();
-    myTimeSignatureData.beatType = timeSig.beatType();
+    outData.setSimple(timeSig.beats(), timeSig.beatType());
 
-    if (myTime->symbol().has_value())
+    if (time.symbol().has_value())
     {
-        if (*myTime->symbol() == core::TimeSymbol::common())
+        if (*time.symbol() == core::TimeSymbol::common())
         {
-            myTimeSignatureData.symbol = api::TimeSignatureSymbol::common;
+            outData.symbol = api::TimeSignatureSymbol::common;
         }
-        else if (*myTime->symbol() == core::TimeSymbol::cut())
+        else if (*time.symbol() == core::TimeSymbol::cut())
         {
-            myTimeSignatureData.symbol = api::TimeSignatureSymbol::cut;
+            outData.symbol = api::TimeSignatureSymbol::cut;
         }
-        else if (*myTime->symbol() == core::TimeSymbol::singleNumber())
+        else if (*time.symbol() == core::TimeSymbol::singleNumber())
         {
-            myTimeSignatureData.symbol = api::TimeSignatureSymbol::singleNumber;
+            outData.symbol = api::TimeSignatureSymbol::singleNumber;
         }
     }
     else
     {
-        myTimeSignatureData.symbol = api::TimeSignatureSymbol::unspecified;
+        outData.symbol = api::TimeSignatureSymbol::unspecified;
     }
 
-    myTimeSignatureData.display = api::Bool::unspecified;
-    if (myTime->printObject().has_value())
+    outData.display = api::Bool::unspecified;
+    if (time.printObject().has_value())
     {
-        bool isPrint = *myTime->printObject() == core::YesNo::yes();
+        bool isPrint = *time.printObject() == core::YesNo::yes();
 
         if (isPrint)
         {
-            myTimeSignatureData.display = api::Bool::yes;
+            outData.display = api::Bool::yes;
         }
         else
         {
-            myTimeSignatureData.display = api::Bool::no;
+            outData.display = api::Bool::no;
         }
     }
 
-    myTimeSignatureData.isImplicit = false;
+    if (time.number().has_value())
+    {
+        outData.staffIndex = time.number()->value() - 1;
+    }
+    else
+    {
+        outData.staffIndex = api::INDEX_UNSPECIFIED;
+    }
+
+    outData.isImplicit = false;
 
     return true;
 }
diff --git a/src/private/mx/impl/TimeReader.h b/src/private/mx/impl/TimeReader.h
index b89b640ea..ec2dcef9d 100644
--- a/src/private/mx/impl/TimeReader.h
+++ b/src/private/mx/impl/TimeReader.h
@@ -9,9 +9,16 @@
 #include "mx/impl/Cursor.h"
 
 #include <span>
+#include <vector>
 
 namespace mx
 {
+namespace core
+{
+class Time;
+class TimeSignatureGroup;
+} // namespace core
+
 namespace impl
 {
 class TimeReader
@@ -23,18 +30,23 @@ class TimeReader
     // cached data
     TimeReader(std::span<const core::MusicDataChoice> inMusicDataChoices);
     bool getIsTimeFound() const;
-    mx::api::TimeSignatureData getTimeSignatureData() const;
+
+    // returns one TimeSignatureData per <time> element found in the first <attributes> block
+    // that has any. staffIndex is populated from the <time number="..."> attribute (1-based,
+    // converted to 0-based); it is NOT clamped against the part's staff count here - the caller
+    // (MeasureReader) is responsible for clamping against the actual staff count.
+    std::vector<mx::api::TimeSignatureData> getTimeSignatures() const;
 
   private:
     std::span<const core::MusicDataChoice> myMusicDataChoiceSet;
-    const core::Time *myTime;
     bool myIsTimeFound;
-    mx::api::TimeSignatureData myTimeSignatureData;
+    std::vector<mx::api::TimeSignatureData> myTimeSignatures;
 
   private:
     bool initialize();
-    bool parseTime();
-    bool parseTimeSignatureGroup(const core::TimeSignatureGroup &timeSig);
+    bool parseTime(const core::Time &time);
+    bool parseTimeSignatureGroup(const core::Time &time, const core::TimeSignatureGroup &timeSig,
+                                 mx::api::TimeSignatureData &outData);
 };
 } // namespace impl
 } // namespace mx
diff --git a/src/private/mxtest/api/ApiK007aScoreData.h b/src/private/mxtest/api/ApiK007aScoreData.h
index 5cf3a884f..b6e919e03 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.isImplicit = false;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::unspecified;
+    measureP->timeSignatures.front().isImplicit = false;
+    measureP->timeSignatures.front().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..f637adb3b 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.isImplicit = false;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::unspecified;
+    measureP->timeSignatures.front().isImplicit = false;
+    measureP->timeSignatures.front().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..70182eba2 100644
--- a/src/private/mxtest/api/ApiK009bSlurScoreData.h
+++ b/src/private/mxtest/api/ApiK009bSlurScoreData.h
@@ -29,9 +29,9 @@ 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.isImplicit = false;
+    measure->timeSignatures.front().components.front().beats = "4";
+    measure->timeSignatures.front().components.front().beatType = "4";
+    measure->timeSignatures.front().isImplicit = false;
     measure->staves.emplace_back(StaffData{});
     auto staff = &measure->staves.back();
     staff->clefs.emplace_back(ClefData{});
diff --git a/src/private/mxtest/api/ApiK014aFermatasScoreData.h b/src/private/mxtest/api/ApiK014aFermatasScoreData.h
index 9776dce4a..b36f1c481 100644
--- a/src/private/mxtest/api/ApiK014aFermatasScoreData.h
+++ b/src/private/mxtest/api/ApiK014aFermatasScoreData.h
@@ -25,9 +25,9 @@ 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.isImplicit = false;
+    measure->timeSignatures.front().components.front().beats = "4";
+    measure->timeSignatures.front().components.front().beatType = "4";
+    measure->timeSignatures.front().isImplicit = false;
     measure->staves.emplace_back(StaffData{});
     auto staff = &measure->staves.back();
     staff->clefs.emplace_back(ClefData{});
diff --git a/src/private/mxtest/api/ApiK015aLayoutScoreData.h b/src/private/mxtest/api/ApiK015aLayoutScoreData.h
index 4498316a0..dce2e479b 100644
--- a/src/private/mxtest/api/ApiK015aLayoutScoreData.h
+++ b/src/private/mxtest/api/ApiK015aLayoutScoreData.h
@@ -60,9 +60,9 @@ 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.isImplicit = false;
+    measure->timeSignatures.front().components.front().beats = "4";
+    measure->timeSignatures.front().components.front().beatType = "4";
+    measure->timeSignatures.front().isImplicit = false;
     measure->staves.emplace_back(StaffData{});
     auto staff = &measure->staves.back();
     staff->clefs.emplace_back(ClefData{});
diff --git a/src/private/mxtest/api/ApiLy43eScoreData.h b/src/private/mxtest/api/ApiLy43eScoreData.h
index ba17dedf7..5c7d708b8 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.isImplicit = false;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::common;
+    measureP->timeSignatures.front().isImplicit = false;
+    measureP->timeSignatures.front().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.isImplicit = true;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::common;
+    measureP->timeSignatures.front().isImplicit = true;
+    measureP->timeSignatures.front().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.isImplicit = true;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::common;
+    measureP->timeSignatures.front().isImplicit = true;
+    measureP->timeSignatures.front().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.isImplicit = true;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::common;
+    measureP->timeSignatures.front().isImplicit = true;
+    measureP->timeSignatures.front().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.isImplicit = true;
-    measureP->timeSignature.symbol = TimeSignatureSymbol::common;
+    measureP->timeSignatures.front().isImplicit = true;
+    measureP->timeSignatures.front().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..a914553ae 100644
--- a/src/private/mxtest/api/ApiMuAccidentals1ScoreData.h
+++ b/src/private/mxtest/api/ApiMuAccidentals1ScoreData.h
@@ -37,9 +37,9 @@ 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.isImplicit = false;
+    measure->timeSignatures.front().components.front().beats = "3";
+    measure->timeSignatures.front().components.front().beatType = "4";
+    measure->timeSignatures.front().isImplicit = false;
     measure->staves.emplace_back(StaffData{});
     measure->keys.emplace_back(KeyData{});
     auto &key = measure->keys.back();
@@ -86,9 +86,9 @@ inline mx::api::ScoreData apiMuAccidentals1ScoreData()
 
     part.measures.emplace_back(MeasureData{});
     measure = &part.measures.back();
-    measure->timeSignature.beats = "3";
-    measure->timeSignature.beatType = "4";
-    measure->timeSignature.isImplicit = true;
+    measure->timeSignatures.front().components.front().beats = "3";
+    measure->timeSignatures.front().components.front().beatType = "4";
+    measure->timeSignatures.front().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..34f3625dc 100644
--- a/src/private/mxtest/api/ChordApiTest.cpp
+++ b/src/private/mxtest/api/ChordApiTest.cpp
@@ -209,8 +209,8 @@ TEST(KompChordBug_PIVOTAL_147058063, ChordApi)
     bassClef.tickTimePosition = 0;
     originalStaffPtr->clefs.push_back(bassClef);
 
-    originalMeasure.timeSignature = TimeSignatureData{};
-    originalMeasure.timeSignature.isImplicit = false;
+    originalMeasure.timeSignatures = {TimeSignatureData{}};
+    originalMeasure.timeSignatures.front().isImplicit = false;
 
     originalStaffPtr = &(*originalMeasure.staves.begin());
     NoteData note{};
diff --git a/src/private/mxtest/api/TimeSignatureApiTest.cpp b/src/private/mxtest/api/TimeSignatureApiTest.cpp
index 702528d90..1f9196ceb 100644
--- a/src/private/mxtest/api/TimeSignatureApiTest.cpp
+++ b/src/private/mxtest/api/TimeSignatureApiTest.cpp
@@ -7,6 +7,7 @@
 
 #include "cpul/cpulTestHarness.h"
 #include "mx/api/DocumentManager.h"
+#include "mxtest/api/TestHelpers.h"
 #include "mxtest/file/MxFileRepository.h"
 
 using namespace std;
@@ -16,7 +17,18 @@ using namespace mxtest;
 namespace
 {
 constexpr const char *const fileName = "testAccidentals1.xml";
+
+ScoreData makeOneMeasureScore()
+{
+    ScoreData score;
+    score.parts.emplace_back(PartData{});
+    auto &part = score.parts.back();
+    part.measures.emplace_back(MeasureData{});
+    auto &measure = part.measures.back();
+    measure.staves.emplace_back(StaffData{});
+    return score;
 }
+} // namespace
 
 TEST(implicitCarryover, TimeSignatureApi)
 {
@@ -25,21 +37,138 @@ TEST(implicitCarryover, TimeSignatureApi)
     const auto &part = scoreData.parts.front();
     CHECK_EQUAL(2, part.measures.size())
     auto measureIter = part.measures.cbegin();
-    auto t = measureIter->timeSignature;
+    auto t = measureIter->timeSignatures.front();
 
     CHECK(!t.isImplicit);
-    CHECK_EQUAL("3", t.beats);
-    CHECK_EQUAL("4", t.beatType);
+    CHECK_EQUAL(1, t.components.size());
+    CHECK_EQUAL("3", t.components.front().beats);
+    CHECK_EQUAL("4", t.components.front().beatType);
     CHECK(t.symbol == TimeSignatureSymbol::unspecified);
 
     ++measureIter;
-    t = measureIter->timeSignature;
+    t = measureIter->timeSignatures.front();
     CHECK(t.isImplicit);
-    CHECK_EQUAL("3", t.beats);
-    CHECK_EQUAL("4", t.beatType);
+    CHECK_EQUAL("3", t.components.front().beats);
+    CHECK_EQUAL("4", t.components.front().beatType);
     CHECK(t.symbol == TimeSignatureSymbol::unspecified);
 }
 
+TEST(setSimple, TimeSignatureData)
+{
+    TimeSignatureData t;
+    t.components.push_back(TimeSignatureComponent{"3", "8"});
+    CHECK_EQUAL(2, t.components.size());
+    t.setSimple("5", "4");
+    CHECK_EQUAL(1, t.components.size());
+    CHECK_EQUAL("5", t.components.front().beats);
+    CHECK_EQUAL("4", t.components.front().beatType);
+}
+
+TEST(TimeSignatureDataEquality_change_staffIndex, TimeSignatureData)
+{
+    TimeSignatureData t1;
+    t1.setSimple("6", "8");
+    t1.isImplicit = false;
+    t1.staffIndex = 0;
+    auto t2 = t1;
+    CHECK(t1 == t2);
+    CHECK(!(t1 != t2));
+
+    // change one thing
+    t1.staffIndex += 1;
+    CHECK(t1 != t2);
+    CHECK(!(t1 == t2));
+}
+
+TEST(TimeSignatureDataEquality_change_components, TimeSignatureData)
+{
+    TimeSignatureData t1;
+    t1.setSimple("6", "8");
+    auto t2 = t1;
+    CHECK(t1 == t2);
+
+    t1.components.push_back(TimeSignatureComponent{"3", "4"});
+    CHECK(t1 != t2);
+    CHECK(!(t1 == t2));
+}
+
+TEST(staffScopedRoundTrip, TimeSignatureApi)
+{
+    auto score = makeOneMeasureScore();
+    auto &measure = score.parts.front().measures.front();
+    measure.staves.emplace_back(StaffData{});
+
+    TimeSignatureData t1;
+    t1.setSimple("3", "4");
+    t1.isImplicit = false;
+    t1.staffIndex = 0;
+
+    TimeSignatureData t2;
+    t2.setSimple("6", "8");
+    t2.isImplicit = false;
+    t2.staffIndex = 1;
+
+    measure.timeSignatures = {t1, t2};
+
+    const auto xml = mxtest::toXml(score);
+    CHECK(xml.find("number=\"1\"") != std::string::npos);
+    CHECK(xml.find("number=\"2\"") != std::string::npos);
+
+    const auto result = mxtest::fromXml(xml);
+    REQUIRE(result.parts.size() == 1);
+    REQUIRE(result.parts.front().measures.size() == 1);
+    const auto &resultTimeSignatures = result.parts.front().measures.front().timeSignatures;
+    REQUIRE(resultTimeSignatures.size() == 2);
+
+    bool foundStaff0 = false;
+    bool foundStaff1 = false;
+    for (const auto &ts : resultTimeSignatures)
+    {
+        if (ts.staffIndex == 0)
+        {
+            foundStaff0 = true;
+            CHECK_EQUAL("3", ts.components.front().beats);
+            CHECK_EQUAL("4", ts.components.front().beatType);
+        }
+        else if (ts.staffIndex == 1)
+        {
+            foundStaff1 = true;
+            CHECK_EQUAL("6", ts.components.front().beats);
+            CHECK_EQUAL("8", ts.components.front().beatType);
+        }
+    }
+    CHECK(foundStaff0);
+    CHECK(foundStaff1);
+}
+
+TEST(compositeMultiComponentRoundTrip, TimeSignatureApi)
+{
+    const auto scoreData = mxtest::MxFileRepository::loadFile("timesigs_composite-ref.musicxml");
+    REQUIRE(scoreData.parts.size() == 1);
+    const auto &part = scoreData.parts.front();
+    REQUIRE(part.measures.size() == 1);
+    const auto &measure = part.measures.front();
+    REQUIRE(measure.timeSignatures.size() == 1);
+    const auto &t = measure.timeSignatures.front();
+    CHECK(!t.isImplicit);
+    REQUIRE(t.components.size() == 3);
+    CHECK_EQUAL("1 + 2.5", t.components.at(0).beats);
+    CHECK_EQUAL("2 + 4", t.components.at(0).beatType);
+    CHECK_EQUAL("3 + 2", t.components.at(1).beats);
+    CHECK_EQUAL("16", t.components.at(1).beatType);
+    CHECK_EQUAL("1.5 + 5", t.components.at(2).beats);
+    CHECK_EQUAL("8 + 16", t.components.at(2).beatType);
+
+    // round trip through write/read again and confirm the composite survives
+    const auto xml = mxtest::toXml(scoreData);
+    const auto result = mxtest::fromXml(xml);
+    REQUIRE(result.parts.size() == 1);
+    REQUIRE(result.parts.front().measures.size() == 1);
+    const auto &resultTimeSig = result.parts.front().measures.front().timeSignatures.front();
+    REQUIRE(resultTimeSig.components.size() == 3);
+    CHECK(resultTimeSig.components == t.components);
+}
+
 T_END
 
 #endif
diff --git a/src/private/mxtest/file/MxFileRepositoy.cpp b/src/private/mxtest/file/MxFileRepositoy.cpp
index 139052f4a..e95a10ce5 100644
--- a/src/private/mxtest/file/MxFileRepositoy.cpp
+++ b/src/private/mxtest/file/MxFileRepositoy.cpp
@@ -469,6 +469,7 @@ void MxFileRepository::initializeNameSubdirectoryMap()
     myNameSubdirectoryMap.emplace("transposition.musicxml", "custom");
     myNameSubdirectoryMap.emplace("segno_coda_roundtrip.3.0.xml", "custom");
     myNameSubdirectoryMap.emplace("segno_coda_roundtrip.3.1.xml", "custom");
+    myNameSubdirectoryMap.emplace("timesigs_composite-ref.musicxml", "rpatters1");
 
     // mxl
     myNameSubdirectoryMap.emplace("Dichterliebe01.mxl", "mxl");