Add `replaceInstrument()` or similar method to Plugin API

[manolo]

Your idea

Add a new method replaceInstrument(part, instrumentId) to the Plugin API Score class that allows plugins to programmatically change the instrument of a part.

This would work similarly to the "Change Instrument" dialog in Staff/Part Properties, but accessible from QML plugins.

Example usage:

var part = curScore.parts[0];
curScore.replaceInstrument(part, "bandurria");

Problem to be solved

Currently, plugins can read instrument information (instrumentId, longName, shortName) but cannot change instruments programmatically. Users need this functionality for:

• Porting scores between different ensembles.
• Batch processing multiple scores to standardize instrumentation
• Automating instrument assignments based on score analysis

The only workaround is manual interaction with the Change Instrument dialog, which cannot be scripted.

Prior art

• Feature request Make staff properties 'change instrument' and 'change channel' available in plugin API
• Forum discussion of users asking for this capability
• Existing methods like appendPartByMusicXmlId() for instrument manipulation via Plugin API

Additional context

The instrumentId parameter should match IDs from instruments.xml (e.g., "pluck.guitar.nylon-string", "wind.flutes.flute").

Checklist

• This request follows the guidelines for reporting issues
• I have verified that this feature request has not been logged before, by searching the issue tracker for similar requests

[XiaoMigros]

In general, it would be great to expose many (if not all) of the methods in notationparts.cpp, i.e. methods controlled by the layout panel in the UI.

[XiaoMigros]

I'd be happy to tackle this if my above would be desired

[manolo]

@XiaoMigros Yes, exposing at least the most useful methods there would be great.
I added a PR for the method I needed for my plugin. If you prefer to start an epic with tasks and methods to wrap, I can take some of them.

[XiaoMigros]

I don't think the PR is the correct way to do this - to my knowledge the engraving module should not be dependent on the notation module. I can tackle this alone - probably easier if one person does - and will open a PR with a more expansive solution.

[cbjeukendrup]

The engraving module should indeed not depend on notation, because that would be a circular dependency. But we could question whether the plugin API should still be inside the engraving module.

Anyway, @XiaoMigros I would be interested to see your implementation as well.

[manolo]

@XiaoMigros I fully agree. I'm not very familiar with the MS sources, so I already guessed that my approach might be wrong; the MS architecture and testing setup are hard to understand just by reading the code and trying out things.
I'll keep my PR as a reference, thus, I changed it to a draft. I might still experiment with the implementation for learning purposes.
I'd be happy if you implement this. Let me know if it’s something you plan to work on soon.

[manolo]

I simplified the PR using the tips from @XiaoMigros and @cbjeukendrup, and it no longer uses the notation module.
I'm keeping it as a draft in case it can help as a reference for the final implementation, since it also brings tests into the picture.