fix(player): skip count-in in backing track and external media modes instead of freezing

[leocaseiro]

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

Partially fixes #2397: only the page freeze and the jump to the song start when count-in is enabled in backing-track / external-media mode, which @Danielku15 confirmed as a bug in #2397 (comment) (reported in #2397 (comment)).

Proposed changes

With countInVolume > 0 in PlayerMode.EnabledBackingTrack or PlayerMode.EnabledExternalMedia, pressing play froze the page, and starting playback mid-song rewound the media to the song start. Two changes:

1. MidiFileSequencer.fillMidiEventQueueToEndTime loops on the state it advances. The loop condition now reads _currentState instead of _mainState, so the loop ends whichever state (main, count-in, one-time MIDI) is active.
2. The media players skip the count-in. AlphaSynthBase.play() starts the count-in only when a new protected supportsCountIn getter returns true (the default). BackingTrackPlayer, and with it ExternalMediaPlayer, return false: the media plays as-is and there is no synthesizer output for the count-in metronome. Without the count-in, play() no longer seeks to 0, so the media keeps its position. The synthesizer player is unchanged.

New tests in test/audio/SyncPoint.test.ts:

• count-in-keeps-position-backing-track / -external-media: start at 30 s with count-in. The media is not seeked back to the song start, and the next media time update continues past 30 s.
• fill-to-end-time-during-count-in: fill the sequencer to an end time while the count-in is active. The test synthesizer counts its reads and throws, so a regression fails instead of hanging the run.
• count-in-playback-synthesizer: the synthesizer player still starts its count-in.

Out of scope:

• Mixing the synthesizer with media, the rest of External Media Sync / Backing Tracks - Allow mixing with Synthesizer #2397. External Media Sync / Backing Tracks - Allow mixing with Synthesizer #2397 should stay open: please unlink it in the PR's Development box before merging.
• playBeat / playNote in these modes still seek the media to the song start while the note plays (the same updateTimePosition(0, true) pattern; the loop change only removes the freeze it could cause at the song start).
• The metronome: with only the metronome on, these modes play without freezing, but the metronome stays silent because it also needs mixing.

Root-cause analysis

• Freeze (MIDI sequencer layer). In the media modes the playback time comes from the media: the timeUpdate handler of BackingTrackPlayer calls fillMidiEventQueueToEndTime(mediaTime). The loop compared _mainState.currentTime with the end time, but it filled _currentState. While the count-in (or a one-time MIDI state) is active, the main state does not advance, so the loop never ended and blocked the main thread ("Page unresponsive") while the media kept playing.
• Rewind (player layer). AlphaSynthBase.play() starts the count-in with updateTimePosition(0, true). BackingTrackPlayer forwards every seek to the media (seekTo), so starting at 0:30 sent the media back to the song start.
• Scope. This affects any score in these two modes with countInVolume > 0; the synthesizer mode is not affected. Skipping the count-in matches the current limitation that alphaTab cannot mix the synthesizer with media (see External Media Sync / Backing Tracks - Allow mixing with Synthesizer #2397). supportsCountIn gives a future mixed mode one place to opt back in.
• Platforms. Plain TypeScript. It transpiles to a protected virtual / override property in C# and to protected open val / override val in Kotlin, the same shape as existing overridden getters such as LineBarRenderer.bottomGlyphOverflow.

Testing done

• packages/alphatab: npm test passes (82 files, 1862 tests); npm run lint and npm run typecheck are clean.
• C#: transpiled and built with 0 warnings and 0 errors; the SyncPoint tests pass (28/28) on .NET 10 with DOTNET_ROLL_FORWARD=Major (the test project targets net8.0).
• Kotlin: transpiled only; the generated code was inspected, but it was not compiled or run locally.
• Manually in the playground Control demo with backing-track scores, including a synced Guitar Pro file of my own: with count-in on, playing from mid-song no longer freezes or rewinds. In the synthesizer mode the count-in still plays before the song. The external-media mode is covered by the unit tests only.

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

countInVolume is now ignored in the backing-track and external-media modes (before, it froze the page). Its API docs do not mention that yet; I can add a note if wanted.

🤖 Generated with Claude Code

[leocaseiro]

Sets the current clock, instead of the main one, to match fillMidiEventQueueToEndTime.

[leocaseiro]

@Danielku15, I noticed you simplified my latest tests, so I tried to keep it simple this time.

Let me know if this provides good coverage or if you would prefer a different testing approach.