fix: align beaming, metronome, count-in and automations with pick-up bars; fix beat timers and multi-track MIDI events

[Danielku15]

Note

AI-authored disclosure (alphatab-ai-authored-v1)

Portions of this content were authored by an AI agent. The agent has read
AGENTS.md and the human submitter accepts responsibility for
compliance with the rules in that document.

Issues

Fixes #2871

Proposed changes

#2871: in a pick-up bar (anacrusis) the beaming is wrong, and the metronome and count-in are out of sync. alphaTab stores a pick-up's beats from tick 0, and the bar plays only for its content length. Musically, though, a pick-up is the end of a full bar. No layer knew about that shift:

• rendering and triplet feel read positions inside the bar as if the bar started on the downbeat;
• the synthesizer's metronome was one global grid derived from MIDI time-signature events, which have no notion of bars or pick-ups.

Analysing the issue turned up more defects in the same layers, so this PR fixes all of them.

Design

• Pick-up offset: MasterBar caches the pick-up's position within the full bar of its time signature: the full bar duration minus the actual duration. It is computed once in finish() and is internal (not part of the public API or JSON). Beaming, triplet feel and the metronome add it to positions inside the bar. One offset per master bar is enough, because Guitar Pro also counts every voice from the bar start.
• Automation positions: Automation.ratioPosition is relative to the full time signature duration, also in pick-ups. Guitar Pro 8 writes 0.5 for a tempo change on the 3rd eighth of a 3-eighth pick-up in 2/4, and the GP, MusicXML and Capella importers already follow this. All conversions now go through one internal ModelUtils helper.
• Metronome: MidiFileGenerator emits the clicks bar by bar through the new IMidiFileHandler.addMetronome, so repeats, jumps, time-signature changes and pick-ups are resolved where the bars are known.
  • AlphaSynthMidiFileHandler adds them as AlphaTabMetronomeEvents, but not in SMF1 mode, so exported MIDI files are unchanged.
  • The sequencer keeps the old time-signature grid for MIDI files without clicks.
• Count-in: it counts one full bar and then continues until the beat where playback starts. Guitar Pro 8 and MuseScore 4 behave the same way, for pick-ups as well as for starts in the middle of a bar.

Behaviour changes

Reference score: \ts 2 4 \ac C4.8 D4.8 E4.8 | F4.4 G4.4 | … at 120 bpm.

Case	Before	After
Beaming of the pick-up	C and D joined, E with its own flag	C with its own flag, D and E joined (as in GP8 and MuseScore)
Metronome clicks (tick:beat)	0:0 960:1 1920:0 2880:1 …, so every click after the pick-up falls on an off-beat	480:1 1440:0 2400:1 3360:0 …
Count-in before the pick-up	2 clicks, the pick-up starts at 1000 ms (felt as a downbeat)	3 clicks, the pick-up starts at 1250 ms
Count-in when starting on beat 3 of 4/4	4 clicks, the start note is felt as beat 1	6 clicks, the start note is on beat 3
Swing (triplet feel) in the pick-up	C swung as the long note, D short, E straight	C straight, D and E swung as a pair
Tempo change on E	plays at tick 720	plays at tick 960
alphaTex sustain pedal on E	ratio 0.667	ratio 0.5 (GP convention)
Metronome beat numbers, one-quarter pick-up in 4/4	pick-up 0, bar 1 starts at 1	pick-up 3, bar 1 starts at 0
Metronome beat numbers after 7/8 → 4/4	4/4 bar counts 3,0,1,2	0,1,2,3
Beat timers, two tracks at 120 bpm	track A 0/4000/8000, track B 2000/6000/10000 ms	0/2000/4000 ms for both tracks
Beat timer after a mid-bar tempo change to 60	bar 3 shows 8000 ms	5000 ms
MidiFile.events with MidiFileFormat.MultiTrack	stack overflow	merged events, same-tick order preserved on all platforms
Regular bars without a pick-up or meter change	—	unchanged (identical click ticks; the audio export reference is untouched)

Notes:

• The metronome beat numbers (metronomeNumerator) are only visible to midiEventsPlayed consumers. The built-in synthesizer plays every click the same.
• Beat timers: each staff started where the previous staff ended, and the bar-end calculation compared a bar-relative tick with an absolute one. Both staves now start from the bar start time that the play-through already tracks correctly.
• MidiFile.events: the getter called itself instead of filling its local list. The tracks are now merged instead of sorted, because the C# port's sort is not stable.

Not changed (deliberately)

• Incomplete bars without the pick-up flag keep playing for the full duration of their time signature.
• In exported MIDI files, a pick-up keeps the time signature of the score.
• The tempo marker stays drawn at a linear position across the bar width, the same as in GP8.

API changes

• IMidiFileHandler.addMetronome(tick, counter, durationInTicks) is a new required member. Custom handler implementations need to add it; they can ignore the call. The same happened with addTickShift in fix(player): grace beats on song start #2415.
• Doc updates on AlphaTabMetronomeEvent and Automation.ratioPosition.

Tests

• MidiFileGenerator.test.ts:
  • metronome: regular bars, time-signature change, pick-up, whole-beat pick-up, pick-up with repeat
  • triplet feel in a pick-up
  • tempo automation in a pick-up
  • beat timers with multiple tracks and after a mid-bar tempo change
  • multi-track MidiFile.events
• SyncPoint.test.ts: count-in at a bar start, before a pick-up and mid-bar
• AlphaTexImporter.test.ts: sustain-pedal position in a pick-up
• Visual test special-notes/beaming-anacrusis

TypeScript, C# and Kotlin builds and test suites pass.

Checklist

• I consent that this change becomes part of alphaTab under its current or any future open source license
• This PR is linked to an accepted issue (see above)
• Changes are implemented
• New tests were added
• I have read AGENTS.md if an AI helped draft any part of this PR

AI authorship disclosure

• No AI agent authored any part of this PR (description, code, tests, or commit messages)
• An AI agent contributed to this PR. The AI-authored disclosure block
  (alphatab-ai-authored-v1) is present at the top of this body, and I have
  personally reviewed every change and can explain each one

Further details

• This is a breaking change
• This change will require update of the documentation/website