feat: expose API for changing part instruments

Author: manolo

src/engraving/api/v1/score.cpp

@@ -32,6 +32,11 @@
 #include "editing/editsystemlocks.h"
 #include "types/typesconv.h"
 
+// notation
+#include "notation/inotation.h"
+#include "notation/inotationparts.h"
+#include "notation/notationtypes.h"
+
 // api
 #include "apistructs.h"
 #include "cursor.h"
@@ -158,6 +163,49 @@ void Score::appendPartByMusicXmlId(const QString& instrumentMusicXmlId)
     score()->appendPart(t);
 }
 
+//---------------------------------------------------------
+//   Score::replaceInstrument
+//---------------------------------------------------------
+
+void Score::replaceInstrument(apiv1::Part* part, const QString& instrumentId)
+{
+    if (!part) {
+        LOGW("replaceInstrument: part is null");
+        return;
+    }
+
+    const InstrumentTemplate* t = searchTemplate(instrumentId);
+    if (!t) {
+        LOGW("replaceInstrument: <%s> not found", qPrintable(instrumentId));
+        return;
+    }
+
+    // Get the notation interface to access INotationParts
+    mu::notation::INotationPtr notationPtr = notation();
+    if (!notationPtr) {
+        LOGW("replaceInstrument: notation is null");
+        return;
+    }
+
+    mu::notation::INotationPartsPtr parts = notationPtr->parts();
+    if (!parts) {
+        LOGW("replaceInstrument: notation parts is null");
+        return;
+    }
+
+    // Create InstrumentKey for the main instrument of the part
+    mu::notation::InstrumentKey instrumentKey;
+    instrumentKey.partId = muse::ID(part->part()->id());
+    instrumentKey.instrumentId = muse::String::fromQString(part->part()->instrumentId());
+    instrumentKey.tick = mu::engraving::Fraction(0, 1); // Main instrument at tick 0
+
+    // Create the new Instrument from the template
+    mu::engraving::Instrument newInstrument = mu::engraving::Instrument::fromTemplate(t);
+
+    // Call replaceInstrument through the notation layer
+    parts->replaceInstrument(instrumentKey, newInstrument);
+}
+
 //---------------------------------------------------------
 //   Score::firstSegment
 //---------------------------------------------------------

src/engraving/api/v1/score.h

@@ -236,6 +236,15 @@ class Score : public apiv1::ScoreElement, public muse::Injectable
     /// \since MuseScore 3.5
     Q_INVOKABLE void appendPartByMusicXmlId(const QString& instrumentMusicXmlId);
 
+    /// Replaces the instrument for a given part with a new instrument.
+    /// This changes the instrument definition including its name, clef, and sound.
+    /// \param part - The Part object whose instrument should be replaced.
+    /// \param instrumentId - ID of the new instrument, as listed in
+    /// [`instruments.xml`](https://github.com/musescore/MuseScore/blob/3.x/share/instruments/instruments.xml)
+    /// file.
+    /// \since MuseScore 4.7
+    Q_INVOKABLE void replaceInstrument(apiv1::Part* part, const QString& instrumentId);
+
     /// Appends a number of measures to this score.
     Q_INVOKABLE void appendMeasures(int n) { score()->appendMeasures(n); }
     Q_INVOKABLE void addText(const QString& type, const QString& text);