alphaTab and Request For Native Support for TablEdit's File Format

[SteveMcBill]

Project: alphaTab
Suggested category: Ideas

Dear Daniel and the alphaTab development team,

I would like to suggest adding native support for TablEdit's .tef file format, particularly the latest Version 3 format.

TablEdit is used by guitarists and other musicians to create, edit and play musical scores incorporating tablature. Many of its users have extensive collections of existing .tef files containing musical notation, guitar tablature, fingering, rhythmic information and performance settings.

Currently, alphaTab supports several useful formats, including Guitar Pro and MusicXML, but TablEdit files cannot be loaded directly.

This creates a problem for musicians whose existing scores are held in TablEdit. They must convert their files into another format before using alphaTab, potentially losing information or encountering differences in notation and playback.

I have been investigating alphaTab as the basis of a browser-based guitar practice player for my guitar website. My experiments have demonstrated that alphaTab can render and play Guitar Pro files successfully. However, when working with TablEdit files converted to MusicXML, I have encountered differences in notation and playback, including unusual rests and the loss of swing feel.

I have not yet established precisely where all these differences originate, but they illustrate why direct support for the native format could be valuable.

Ideally, a TablEdit importer would preserve as much of the original score information as possible, including:

Standard musical notation and tablature.
Note durations, triplets and other rhythmic information.
Swing settings and tempo changes.
Repeats, endings and other playback instructions.
String and fret positions, tunings and capo settings.
Relevant articulations and performance markings.

I appreciate that implementing a new importer would require investigation of the file format and its capabilities. In particular, support for the current TablEdit Version 3 format would be important to users with modern TablEdit installations.

Would you consider adding TablEdit support to alphaTab, or discussing whether such an importer might be feasible?

I believe this could make alphaTab useful to a wider community of musicians and developers who want to bring their existing TablEdit scores into web-based applications.

Thank you for developing and maintaining alphaTab.

Best regards,
Steve

[Danielku15]

Funny that I never had TablEdit on my radar. Its double funny because they use alphaTab on their own website https://tabledit.com/tabs/index.shtml 😁

Could be an interesting addition but I'd need to reach out to the developers to get the official spec. Anything reverse-engineered might be incomplete. We could learn from MuseScore how they read it, but MuseScore is GPL and we have to be careful not to adopt their code but only learn.

I'll reach out to the devs to see what their opinion is on sharing the spec with me to add TablEdit support in alphaTab.

[SteveMcBill]

Thanks Daniel, I am sure Matthieu will be interested (Matthieu Leschemelle. - (TablEdit developer/owner).

We have discussed the matter and Matthieu used the French AI (Claude) to develop a first try parser to enable TablEdit files to be used on websites using the alphaTAb engine. It was done quickly and there were still issues with various aspects of translation of the effects in TablEdit being incorrectly translated or not translated at all.. I picked up the work he had done and have been attempting to push it further along but am finding it quite frustrating as I do not know the Version 3 TablEdit file structure at all well (being just a long-term TablEdit user - see here: https://www.stevemcwilliam.co.uk/guitar/tef-practice/

If you could contact Matthieu I am sure he will be interested in collaborating - he was when I put him in touch with the MusEdit community and the MusEdit introduction of TablEdit importation began.

You can contact Matthieu on the TablEdit forum - https://groups.io/g/tabledit - or, if you wish, by using the information below (from Google):
You can contact Matthieu Leschemelle directly using the official TablEdit Contact Information details below:
• Email: matt0308@tabledit.com
• Alternative Support Email: support@tabledit.com
• Phone: +33 (1) 39219424
• Mailing Address:
Matthieu Leschemelle
8 avenue Gambetta
78100 Saint Germain en Laye
France

Many thanks for your interest. I think such an addition to alphaTab would open up a lot of TablEdit based tablature website usgae.

Cheers and thanks again.

Steve

[Danielku15]

I already reached out to Matthieu and got a reply, I've got the spec and his intermediate importer code at hands. I added #3006 to track the support of this format.

[SteveMcBill]

Thanks Daniel - appreciated.

[SteveMcBill]

Daniel,   If you need any assistance with testing as the development of an importation facility for TablEdit (.tef) files, I am happy to help as and when I can.   Cheers,    Steve Steve J. McWilliam

[Danielku15]

The initial implementations are done in #3013 If you want you could try building this feature branch for some local tests on your side. I requested some feedback from Matthieu if they are fine with integrating the format support like this. If he confirms one of the next alphaTab 1.10 packages will allow testing via official builds.

[SteveMcBill]

Danile,   Many thanks indeed for your superbly quick response - I will definitely have a go at testing the current state. I am very interested to see if you have managed to deal with TablEdit's 'Swing' ability (2 levels).   Cheers and thanks again.   Steve Steve J. McWilliam Message ID: ***@***.***>

[Danielku15]

Matthieu has expressed wishes to maybe only support Format 3 to encourage people upgrading. Would this still fit your needs?

Regarding Swing: generally alphaTab wasn't extended to have new capabilities with this importer. The importer tries to map the swing definitions to the closest counterpart we support in alphaTab today but you will likely have to expect differences. Feel free to report separately if you have the need to support some specific patterns, then I can add them until we maybe support fully dynamic patterns one day.

[SteveMcBill]

Hi Daniel,   I think not supporting V2 files is a shame BUT I can understand Matthieu's preference.  As to myself, I amended all my .tef files to Version-3 when I started attempting to develop my own player using alphaTab (sadly my knowledge of the file format wasn't really sufficient to make as much progress as I wanted - see here: https://www.stevemcwilliam.co.uk/guitar/tef-practice/ <https://www.stevemcwilliam.co.uk/guitar/tef-practice/>  Consequently, only supporting V3 .tef file importation will be fine for myself - thanks for asking.   The two files we've most recently tested, Calliope Rag and Beauty In Tears, are both Format 3 and have imported successfully. I do have a substantial collection of older TablEdit files, but provided these can be opened and resaved in the newer format using TablEdit itself, I think that is a reasonable solution.   Regarding Swing, I understand the limitations you've described. My initial impression from listening to Calliope Rag was that alphaTab had reproduced TablEdit's one-level Swing setting quite convincingly. However, I haven't yet tested enough different patterns to draw any firm conclusions.  I'd prefer to carry out some further comparisons before requesting additional swing functionality. If I identify particular patterns that aren't being reproduced satisfactorily, I'll provide you with specific examples. I've also started testing more demanding files involving Reading Lists, tied notes and rolled chords. I've already identified a few differences which I'll investigate further before reporting them. Thanks again for making this importer available for testing. It's a very promising development, and I'm keen to help establish how well it handles real-world TablEdit files. If you would like any .tef files to use when undertaking your own testing please do let me know and I can send you some over.  Many thanks for the offer to have me request support for more variations in the future. Very much appreciated. Steve Steve J. McWilliam Message ID: ***@***.***>

[SteveMcBill]

Hi Daniel,   I've now carried out some initial testing of your TablEdit importer using several of my own TEF files. I thought it would be useful to report the findings so far. All the files tested are unprotected Format 3 files. I previously converted the Tape ’n’ Tab Club collection of TEF files to Format 3, so Matthieu's suggestion of supporting Format 3 only would be perfectly acceptable for my purposes. Here are the results so far.1. General import and playback The importer successfully loaded, rendered and played both: * All Of A Row – Traditional * Calliope Rag – James Scott * Beauty In Tears This is an encouraging start. The basic note and tablature rendering is working, and playback is functioning.2. Calliope Rag – Reading List discrepancy This is the most significant issue identified so far. I compared playback directly between TablEdit and your alphaTab test player. The actual performance sequences are: TablEdit: Section 1, 1, 2, 2, 1, 3, 3, 1, End. alphaTab: Section 1, 1, 2, 2, 1, 2, 2, 3, 3, End. In other words, alphaTab plays Section 2 twice more than it should, and consequently does not return to Section 1 before finishing. The Calliope Rag Reading List contains 11 entries: 01 – Measures 1–20 02 – Measures 5–19 03 – Measures 21–37 04 – Measures 22–37 05 – Measures 5–19 06 – Measures 21–21 07 – Measures 38–45 08 – Measures 38–43 09 – Measures 46–47 10 – Measures 5–19 11 – Measures 48–49 I have attached two screenshots: * The original TablEdit Reading List. * The Firefox Console showing three warnings from the importer. The warnings read: "The reading list cannot be expressed exactly, playback order differs: expected [...], actual [...]&quot; This is particularly useful because the importer is already identifying a difference between the expected and actual playback sequences. I would be interested to know whether the problem lies in translating the Reading List into alphaTab's repeat/navigation structures, or in alphaTab's subsequent interpretation of those structures.3. Beauty In Tears – tied notes Beauty In Tears loads and plays its repeats correctly and reaches the end of the piece. However, the final triad is played twice. My suspicion is that the importer or subsequent MIDI generation is treating the continuation of the tied notes as additional played notes. This needs further investigation, but I wanted to bring it to your attention. I've attached the Beauty In Tears TEF file for reference.4. Rolled chords I also noticed a difference in the way rolled chords are reproduced. In TablEdit, a rolled chord has a perceptible separation between the individual notes as they are played. In alphaTab, the same passage sounds much more like a rapid brush across the strings, with the notes almost merging into one sound. I understand that your importer maps TablEdit rolls to the closest equivalent currently available in alphaTab. It may therefore be a limitation of the existing playback implementation rather than an importer error. Nevertheless, I think it is worth investigating whether the individual string offsets and overall roll duration could be adjusted to produce a closer approximation.5. Swing One positive observation concerns Calliope Rag. Using my ears rather than any objective timing analysis, I thought the one-level Swing setting in TablEdit was reproduced quite convincingly in alphaTab. I appreciate your explanation that the importer maps swing definitions to the closest currently supported alphaTab equivalent, rather than introducing new playback capabilities. I haven't yet tested enough different swing patterns to identify any specific shortcomings, so I don't have a request for additional swing functionality at this stage.6. Test-player display observations A few interface issues are also apparent in the current test player: * The playback controls are positioned too far to the left. * The controls should remain fixed at the top of the page. * The score does not scroll automatically during playback. * Only the first few systems are visible, with no satisfactory vertical scrolling. * Some notes appear greyed out. * The tablature is rather pale and difficult to follow. * The title header appears limited to two lines. Three lines would be preferable, as in my existing player. I appreciate that these are largely test-player presentation issues rather than necessarily problems with the importer itself. I mention them for completeness.Summary The initial results are encouraging. Basic Format 3 importing, notation rendering and playback are working. The main outstanding technical issues I have identified are: 1. Incorrect Reading List execution in Calliope Rag, with the importer itself reporting expected/actual sequence differences. 2. The final tied triad in Beauty In Tears being played twice. 3. Rolled chords sounding considerably more compressed than in TablEdit. I'm continuing to test other files and will report any further findings, preferably with specific examples. Thanks again for your work on this. Having native TablEdit import in alphaTab would be a very useful development, and I'm keen to help test it thoroughly.   Steve Steve J. McWilliam Message ID: ***@***.***>

[SteveMcBill]

Hi Daniel,   Following my earlier report concerning Calliope Rag, I've now completed a further test using another of my TablEdit files: "Russian Wedding Dance". Unfortunately, this reveals a second example of incorrect Reading List execution. 1. Original TablEdit Reading List The file contains 34 written measures and 21 Reading List entries: Entry From measure To measure 1 1 4 2 1 3 3 5 13 4 1 4 5 1 3 6 5 5 7 14 29 8 22 28 9 30 31 10 1 4 11 1 3 12 5 13 13 1 4 14 1 3 15 5 5 16 14 29 17 22 28 18 30 31 19 1 4 20 1 3 21 32 34 The Reading List is clearly more complex than a straightforward conventional repeat structure.2. alphaTab playback When played in your test player, the repeats are not executed as intended. I have confirmed that the playback sequence is incorrect. The Firefox Console also reports: "The reading list cannot be expressed exactly, playback order differs: expected [...], actual [...]&quot; I've attached a screenshot showing the original Reading List and another showing the corresponding alphaTab diagnostic warning. This is particularly useful because the importer is identifying the discrepancy between its expected sequence and the sequence alphaTab actually produces.3. Significance We now have two independent examples: * Calliope Rag: Section 2 is played twice more than intended, and the final return to Section 1 is omitted. * Russian Wedding Dance: The complex Reading List is not reproduced correctly, with the importer again reporting a difference between expected and actual playback order. This suggests that the problem is not specific to one particular TEF file, but concerns the translation or execution of more complex TablEdit Reading Lists. I think the verification mechanism you've implemented is valuable and should certainly be retained. It provides a useful means of identifying these discrepancies. It would be interesting to establish whether the limitations are in the translation of the Reading List into alphaTab's repeat/navigation structures, or in alphaTab's subsequent execution of those structures.Attachments 1. russwedd.tef – original Russian Wedding Dance file. 2. Russian Wedding Dance Reading List.png – screenshot of the original TablEdit Reading List. 3. Russian Wedding Dance Console.png – screenshot of the alphaTab verification warning. I'll continue testing other files and will report any further findings. Thanks again for your work on this. I'm keen to help establish how reliably the importer can reproduce real-world TablEdit arrangements, particularly those with more complicated performance sequences.   Steve Steve J. McWilliam Message ID: ***@***.***>

[Danielku15]

Thanks for testing. Found already some of the problems you mentioned and pushed some improvements. Here a wider status update:

Calliope Rag reading list: fixed. The importer turned the reading list into the wrong repeat and jump structure. alphaTab now plays your 11 entries in the same order as TablEdit's MIDI export. One limit remains: after a D.C. or D.S., alphaTab plays repeats only once, so lists that repeat a section again after such a jump are still shortened (with a warning).

Final chord played twice: fixed. TablEdit ties a note to the previous note on the same string even across voices, and the importer only looked within one voice.

Grey notes: fixed. alphaTab draws every voice after the first in a lighter colour, and the importer put the upper voice first. The main voice now comes first. The colours are configurable in alphaTab.

Rolled chords: the roll speed matches TablEdit. alphaTab currently rolls only the notes of one voice, so chords that TablEdit splits over several voices barely roll. This is a limitation of alphaTab itself, not of the importer.

Test player: which page or player did you use for your test? Then I can look into the layout, toolbar, scrolling and title header points.

Files: attachments sent by e-mail don't reach GitHub. Could you upload Beauty In Tears (.tef) and the screenshots through the GitHub web page? Your Format 3 Calliope Rag would also help to confirm the fix.

[SteveMcBill]

Superb Daniel - thank you - Ill get on with things tomorrow evening (out during the day I'm afraid). if you want any of the tef files they can be downloaded easily from my website pages - see over on the various tab pages at:   https://www.stevemcwilliam.co.uk/guitar/tab.htm <https://www.stevemcwilliam.co.uk/guitar/tab.htm> Cheers for now and thanks again.   Steve Steve J. McWilliam You are receiving this because you authored the thread.Message ID: ***@***.***>

[SteveMcBill]

Hi Daniel, A further thought/note:   That's excellent progress! Thank you for investigating and implementing these improvements so quickly. The fixes for Calliope Rag, the tied final chord in Beauty In Tears and the greyed-out notes address exactly the problems I reported. Regarding your questions:   Test player I used the standalone test page you asked me to build within your feature-branch repository: packages/playground/tef-test.html It is accessed locally through Vite at: http://localhost:5173/tef-test.html The associated TypeScript file is tef-test.ts in the same directory.   Test files I'll upload the following through the GitHub web interface: * Beauty In Tears (beuttear(2).tef) * Calliope Rag (calliope(3).tef) * The relevant Reading List and Console screenshots. I'll also retest Calliope Rag against your latest changes.   Regarding Russian Wedding Dance, this is particularly interesting in view of your comment about repeats following D.C. and D.S. navigation. Its Reading List contains several returns to earlier passages, so it may provide a useful test of that remaining limitation.   I understand the limitation with rolled chords spread across multiple voices. It would be useful if alphaTab could eventually support rolling notes across voices, but I appreciate that this is a wider alphaTab issue rather than something you can resolve solely within the importer. Thanks again. This is moving in a very promising direction.   Steve Steve J. McWilliam You are receiving this because you authored the thread.Message ID: ***@***.***>

[SteveMcBill]

Following the changes made yesterday evening Daniel, which commit do you wish me to test next ??

Cheers,
Steve

[Danielku15]

I am a bit lost with all those e-mail messages and your feedback. it looks very messy in GitHub and the clear references are often missing. can you try to consolidate your latest findings so I can work through them?

[SteveMcBill]

Consolidated Testing Report – alphaTab TablEdit Format 3 Importer (PR #3013)

Hi Daniel,

I've consolidated my testing findings below into a single report, following your request.

I've separated the original problems, your reported corrections, known limitations and outstanding testing requirements. Hopefully this will provide a clear reference point for working through the remaining issues.

The purpose of my testing is to establish how reliably the native TablEdit Format 3 importer reproduces real-world TablEdit scores, both in notation and playback.

1. Test environment

Repository: CoderLine/alphaTab
Branch: feature/tabledit-importer
Pull request: #3013
Target: develop

I am using the standalone test page:
packages/playground/tef-test.html
Its companion TypeScript file is:
packages/playground/tef-test.ts
The page is accessed locally through Vite:
http://localhost:5173/tef-test.html

This is a separate test harness and is not my existing Guitar Player application.

2. Format 3 support

You asked whether restricting the importer to TablEdit Format 3 would be acceptable, following Matthieu's preference to encourage users to upgrade.
I confirmed that this is perfectly acceptable for my purposes.

When I began developing my own player, I converted my entire Tape 'n' Tab Club collection to Format 3. Although I still have a substantial collection of older TablEdit files, these can be opened and resaved in the newer format using TablEdit itself.
All the files used in my recent tests are unprotected Format 3 files.

3. Initial import and playback results

The importer successfully loaded, rendered and played:

• All Of A Row – Traditional
• Calliope Rag – James Scott
• Beauty In Tears

This was an encouraging start. Basic notation and tablature rendering worked, and playback was functional.

The following issues were identified during more detailed testing.

4. Calliope Rag – Reading List execution

This was the first major problem.
The TablEdit Reading List contains 11 entries.
The intended playback sequence, expressed as sections, is:

TablEdit:
1, 1, 2, 2, 1, 3, 3, 1, End

The original alphaTab importer produced:
Original alphaTab playback:
1, 1, 2, 2, 1, 2, 2, 3, 3, End

In other words, Section 2 was played twice more than intended, and the final return to Section 1 was omitted.
The importer also produced diagnostic console warnings identifying the difference between the expected and actual playback sequences.

Your subsequent update: FIXED.

You explained that the importer had converted the Reading List into the wrong repeat and jump structure, and that you had corrected this. You reported that alphaTab now plays all 11 entries in the same order as TablEdit's MIDI export.

Outstanding action: I need to retest Calliope Rag against your corrected implementation.

5. Beauty In Tears – Final tied chord played twice

Beauty In Tears loaded and played its repeats correctly and reached the end of the piece.
However, the final triad was played twice.
I suspected that tied notes were being interpreted as additional played notes rather than continuations of the existing notes.

Your subsequent update: FIXED.

You explained that TablEdit can tie a note to the previous note on the same string even across different voices, whereas the importer had only searched within an individual voice.

You have corrected this.

Outstanding action: Retest Beauty In Tears to confirm that the final triad now sounds correctly.

6. Russian Wedding Dance – Complex Reading List

I tested a second, more demanding file after identifying the Calliope Rag problem.
Russian Wedding Dance contains 34 written measures and 21 Reading List entries, with multiple returns to earlier passages.

The original importer did not reproduce the intended playback sequence. The console again reported differences between the expected and actual sequences.
This is significant because it demonstrates that the problem was not confined to one particular TEF file. It concerns the handling of more complex TablEdit Reading Lists.

Your subsequent update: PARTIALLY RESOLVED / KNOWN LIMITATION.

You explained that alphaTab currently plays repeats only once after a D.C. or D.S. instruction. Reading Lists that require a section to be repeated again after such a jump are therefore still shortened, with a warning.

Russian Wedding Dance is particularly useful for investigating this limitation.

Outstanding action: Retest the file against your latest implementation and establish exactly which parts of its Reading List are now reproduced correctly and which remain unsupported.

7. Voice ordering and greyed-out notes

In the original test, some notes appeared greyed out in the rendered score.

Your subsequent update: FIXED.

You explained that alphaTab draws voices after the first in a lighter colour, and that the importer had been placing the upper voice first.
You have changed the voice ordering so that the main voice comes first. You also mentioned that the colours are configurable in alphaTab.

Outstanding action: Confirm the corrected rendering in our next test.

8. Rolled chords

I noticed a difference between TablEdit and alphaTab playback.

In TablEdit, rolled chords have a perceptible separation between the individual notes. In alphaTab, the same passages sounded much more like a rapid brush across the strings, with the notes almost merging into one sound.

Your explanation:
The importer maps TablEdit rolls to alphaTab's closest equivalent arpeggio types and calculates brush duration according to roll speed and string count.
However, alphaTab currently rolls only the notes within an individual voice. Where TablEdit distributes a chord across several voices, the notes barely roll.

You identified this as a limitation of alphaTab itself rather than an importer error.

Current status: Known alphaTab limitation.

It would nevertheless be useful if alphaTab could eventually support rolling chords across multiple voices, as this would provide a closer reproduction of TablEdit playback.

9. Swing

I specifically asked whether you had managed to reproduce TablEdit's two-level swing capability.

You explained that the importer maps TablEdit swing definitions to the closest equivalent currently supported by alphaTab, but that differences should be expected.

My initial listening test of Calliope Rag suggested that its one-level swing was reproduced quite convincingly.
I have not yet tested enough different patterns to identify specific shortcomings.

Current status: No confirmed defect. Further testing required.

I will report specific examples if I identify swing patterns that are not reproduced satisfactorily.

10. Test-player presentation

There are a few issues with the standalone test page that I mentioned for completeness:

• The toolbar controls are not properly aligned.
• The page does not scroll automatically during playback.
• Only the first few notation systems are visible, with no satisfactory vertical scrolling.
• Some notes appeared greyed out (addressed by your voice-ordering correction).
• The tablature is rather pale and difficult to follow.
• The title header currently displays only two lines. Three lines would be preferable, as in my existing player.
  These are primarily test-harness presentation issues rather than importer problems.

I suggest we concentrate on importer correctness first and return to the interface afterwards.

11. Test files and supporting evidence

I have uploaded the relevant TEF files and screenshots through the GitHub web interface, as requested.
The files supplied include:

• Beauty In Tears – beuttear(2).tef
• Calliope Rag – calliope(3).tef
• Russian Wedding Dance – russwedd.tef
• Calliope Rag Reading List and Console screenshots.
• Russian Wedding Dance Reading List and Console screenshots.

These provide the original scores and evidence of the playback discrepancies reported above.

12. Current position and proposed testing sequence

For clarity, here is the status of the principal findings:

Item	Current status
Basic Format 3 import	Working in initial tests
Calliope Rag Reading List	Fix reported – retest required
Beauty In Tears tied final chord	Fix reported – retest required
Russian Wedding Dance Reading List	D.C./D.S. limitation remains
Voice ordering / grey notes	Fix reported – retest required
Rolled chords across voices	Known alphaTab limitation
Swing	Further testing required
Test-player presentation	Deferred

I propose the following testing sequence:

1. Calliope Rag – verify the corrected 11-entry Reading List.
2. Beauty In Tears – verify the tied final chord.
3. Russian Wedding Dance – investigate the remaining D.C./D.S. limitation.
4. Check the corrected voice ordering and note colours.
5. Continue testing swing and rolled chords with additional examples.

One final point: Could you please identify the latest commit containing your reported corrections, or confirm which commit you would like me to test?

I want to make sure that my next test is against the correct version of your feature branch.

---

Thank you again for the speed with which you have investigated and implemented these improvements. The initial results are very encouraging, and I am keen to continue testing the importer thoroughly.

Native TablEdit support would be a very useful addition to alphaTab, particularly for the many existing guitar tablature collections that use this format.

Steve