Implementing a Custom Cursor in v1.9.0-alpha: Coordination & Lifecycle Questions

[AvaTheArchitect]

@Danielku15

Hi Daniel,

I've put together a specialized reproduction lab for the custom cursor implementation we've been discussing. You can find the functional code here: alphatab-integration-lab

✅ Successes & Progress

• Nested Bounds Fix: We resolved the "Fixed Cursor" issue by identifying that the 1.9.0-alpha uses a nested property structure (visualBounds.x) rather than flat properties.
• Player Sync: We’ve confirmed that the EnabledSynthesizer is required to drive the playerPositionChanged events effectively.
• Visual Standard: We’ve achieved the "Songsterr-style" look with top/bottom overhangs by calculating offsets based on the beat's Y-coordinates.

🛠️ Technical Blockers & Questions:
We have a few specific questions regarding the rendering engine's output in this alpha branch:

1. Horizontal Centering: Currently, visualBounds.x provides the left edge of the beat. Is there a visualBounds.w (width) or a recommended "note-head center" property in the 1.9 alpha so we can perfectly center the cursor over fret numbers regardless of font size?
2. Vertical Padding/Collision: To achieve the "breakout" look, we are using a $-20$px offset on the Y-axis. However, this occasionally crowds "System" elements like INTRO or Tempo markings. Does AlphaTab expose a "Top Margin" or "System Padding" constant we can adjust to ensure the notation stays clear?
3. Lifecycle Events: We’re encountering a intermittent TypeError when attaching listeners to soundFontLoaded and playerPositionChanged. Is there a specific lifecycle event we should wait for (other than renderFinished) to ensure the player's event emitters are fully instantiated before we call .on()?
4. Note-Level Granularity (HOPO): We noticed that playerPositionChanged seems to anchor to the Beat. For rapid transitions like pull-offs (e.g., Fret 3 to 0), the cursor sometimes "skips" the intermediate visual state. So for example if I click on the various fret numbers on pull-offs or even a rake xxx for example, it doesn't recognize it therefore it won't move. Is there a recommended way to sync the cursor with Note-level transitions within a beat, or should we be looking at a different event emitter for legato/HOPO groups?

📱 Mobile & Horizontal View Considerations
We’re keeping an eye on horizontal layouts. Since we are now using Beat Y instead of System Y, the cursor should technically "follow" the staff even on mobile. We've included some safety checks in the repo to handle renderer recalculations.
Looking forward to your thoughts on the coordinate properties! Hopefully this is what you need, but if you need anything else please let me know!

Thank you!

Brett

[Danielku15]

Thanks for the repo, this will allow us better to discuss things. Claude often refers to specific files and implementation details of your project which leave a big gap when discussing problems.

Generally: In the new demo project you are not using the vite plugin like we require it. This is visible by a warning regarding bundlers (even though I'd expect a Vite warning here).

https://alphatab.net/docs/getting-started/installation-vite

Just a general note in case I wasn't explicit enough on the versioning: you should not use 1.9.0 (basically any -alpha prerelease) for any production workloads, it is not "released" and neither considered stable nor production ready. It can break any day and I do not provide any quality/stability guarantees. If you have doubts, you might want to read more on how semver works.

1. Horizontal Centering...Is there a visualBounds.w (width)

Please read https://alphatab.net/docs/reference/api/boundslookup and what's provided on code level as docs. All information should on how to obtain sizes and positions should be there. In case of doubts it might be the best choice to look on how things are implemented in alphaTab itself or how we do things on the website. It's all open source and accessible.

2. Vertical Padding/Collision...Does AlphaTab expose a "Top Margin" or "System Padding" constant we can adjust to ensure the notation stays clear?

There are various paddings and margins configurable, they are all documented on the settings docs https://alphatab.net/docs/reference/settings you'll have to check which one fits your needs. Keep in mind that alphaTab is rather aiming to reduce paddings and aligning things more compact: #2010

3. Lifecycle Events: We’re encountering a intermittent TypeError when attaching listeners to soundFontLoaded and playerPositionChanged.

This sounds unfamiliar. What exactly are you experiencing? Launching your demo project doesn't show such specific errors.

Just generally Vite has a problem that it doesn't "refresh" properly any new files copied to the public dir. On a very initial clean start, when the sonivox.sf2 might be copied the first time, the vite dev server might not pick up the file. Starting npm run dev again typically solves this. You might need to check for vite options and settings which solve this.

4. Note-Level Granularity (HOPO): We noticed that playerPositionChanged seems to anchor to the Beat....

I'd need a more specific insight on that. alphaTab is as specific as it can be to tell the browser to animate and update things. You simply might be hitting FPS limitations of the browser where alphaTab cannot do anything. I'm not aware of any specific problems in alphaTab that we would be doing things "wrong". You could do some performance profiling (using dev tools) in your app to see if there are some indicators towards a real problem.