Q: State and future of ATMLib

I come up with this topic because I’m confused about ATMLib.

Since i’m in the middle of making a new game I’ve started to think about some BMG and because I have no idea/talent about music I’ve asked a friend to compose some things. ATMLib has this wonderful visual tool on Team a.r.g.'s site which I wanted to share with him so he can make some music. I started a small search on the forums and read through some topics and I got really confused.

There seems to be 3 ATMLib repos atm:

Libraries in the IDEs:
Both libraries in the Arduino Library and PlatformIO Library-Managers link to Team a.r.g.'s ATMLib.

Known issues in Team a.r.g.'s ATMLib:
There seems to be a bug in Team a.r.g.'s ATMLib which is resolved in the other forks.

Known issues in moduscreate’s ATMLib:
moduscreate’s ATMLib has a new format of the audio-format which is not backwards compatible. That’s why moduscreate made an updated version of the Tracker Editor which is undocumented and only hard to find through forum posts.
The documentation is not updated and leads to unanswered issues with the playback:

@JayGarcia has worked on Evade2 which uses ATMLib2 and said to take it’s source as reference.

Taking a brief look at the code shows that the ATMLib2 methods atm_synth_play_score(const uint8_t *song)/ATMsynth ::play(const uint8_t *song) expect the address of the scores struct and not to the raw data as in the original ATMLib.

What I wish for:

  • Merge the different forks as @JO3RI mentioned it in this post.
  • Update the documentation
    – By telling the way it really works.
    – Update the examples.
    – Put in a link to the right Editor and make a big hint which says “Only works in Firefox” - Yes, this took me a while. :wink:

If that’s not an option:

- Please fix the bug in Team a.r.g.'s ATMLib and tell everybody to forget ATMLib2 atm. (not the preferred way)


Hi @Botisaurus,

we are working on the official ATMlib2 (together with @dxb and moduscreate for the moment, so we’re not going to update ATMlib. It’s usable as it is (look at Arduventure).

The new Library isn’t out officially yet, but it does work (use on your own risk, meaning that things still can change), so it’s not in the library manager yet.

Library ATMlib2: https://github.com/TEAMarg/ATMlib2
editor 2: https://teamarg.github.io/trackEditor2/
a demo (not finished, but working) using the new lib (so you need to download the lib yourself): https://github.com/TEAMarg/DM-14-ATMlib2

PS: the new library will fix the bugs of the first library and will by default feature 4 music channels + 2 SFX channels.

PS2: no, you can’t rush us, into doing it quicker :rofl:
PS3: you should use chrome, not firefox !!!


Thank you for your fast reply and clarification @JO3RI!
Good to hear and I am totally happy with the way you go! I just wanted to know, what was going on.


I will not. :wink: Just wanted to know what will happen.

I’m using chrome on mac but it sometimes it skips some tones. Safari doesn’t even play anything back. Only firefox works for me. Same goes for my windows 10 PC. Haven’t tried the new track editor tough. :wink:


Thanks @JO3RI for replying, you beat me to it.

The ATMLib bug @Botisaurus mentioned is already fixed in ATMLib2. ATMLib2 works and is under active development so bugs are found they will get fixed. The downside is that the API is in flux so to avoid surprises you probably should check out the ATMLib2 repo into your own “sketch”.

The one and only ATMlib2 repo is the Team ARG one. Ignore the others :slight_smile:


@JO3RI @dxb has there anything be changed and/or updated regarding ATMlib2 that’s not yet public? I like to revive the project


I am terrible with this kind of stuff, so, if this was advanced at all, I’d be incredibly grateful!

Yes a lot is new and “unpublished”. I would like to resume work on it and I think I can do that soon.

@JO3RI asked for some features that meant (another) redesign. The latest version of this new approach compiles and runs and has some test scripts but it’s lacking a GUI tracker, and needs more testing and some actual musicians using it and giving feedback before trying to call the score format ‘stable’.

The main feature of the new design is support for stacked effects. This is meant to allow creating patterns that are really instruments. So for instance the top level pattern associated with a channel calls 2nd level patterns in sequence and each 2nd level pattern can start a note and call a 3rd level pattern which controls volume/frequency/waveform to achieve a specific sounding “instrument”.

The synth supports SFX by allowing voices to be taken over by a arbitrary number of SFX players. SFX players can play simplified scores or control voice oscillators directly. In fact the osc.c code module which implements the actual “oscillators” can be used without the synth to produce very good (multichannel) SFX adding only a few hundred bytes of code (from memory I think osc.c takes up 600 bytes or less of progmem) to an application.


In all honesty, I only understood half of that.

Patterns, voices, notes, oscillators, synth - it’s all Greek to me.
Τον λογαριασμό παρακαλώ.

is the music editor for ATMlib available somewhere now? it was on the TeamARG website, which is no longer available, but maybe someone saved it?

Do you mean this?



exactly ) thanks!
but it does not play new edit track…



1 Like

thanks )

“Play track” works but “Play song” does not
and I remember that during the composition of the track the keys of the corresponding tone were highlighted on the picture of the piano… It doesn’t work now.
Dear @Mr.Blinky, if it’s not too much trouble, please fix it.

UPD: Sorrry. Just forgot to set VOL to max. “Play song” also works fine

Does anyone have C/C++ code for all asm inserts of ATMlib?
Or can help to convert AVR asm>C?
It would really help to make an ESPboy port.
Playing Arduventure without original music and sounds is pretty boring :wink:

ATMlib uses timer/counter generated hardware PWM and modulates it as a DAC to create the output waveform. Without hardware DAC capability it may be difficult to perform ATMlib functionality on the ESPboy.

Almost the same thing was in the Arduboy Playtune lib, and it works fine on the ESPboy after the transfer. I hope I can find the time and motivation to repeat the success for ATMlib

I see “C” comments to asm code in @Mr.Blinky fork of the ATMlib
What is the difference with original TeamARG ATMlib?

When I analized and optimized ATMlib I added C code as comments to make it easier to understand what’s going on. The C code at line 152 is a C implementation of the ISR.

1 Like

Thanks to MrBlinky’s C++ code at ATMlib I managed to port ATMlib for ESP8266 and the Arduventure game now has music and plays it perfectly.
However there is a problem with the examples built into the library.

Let’s take the song01.ino example.
In the file song.h a melody is defined

#define Song const uint8_t PROGMEM
Song music[] = { ...}

But there are negative values in the data array, and of course the compiler generates errors

song.h:92:1: error: narrowing conversion of '-5' from 'int' to 'uint8_t' {aka 'unsigned char'} [-Wnarrowing]
song.h:92:1: error: narrowing conversion of '-16' from 'int' to 'uint8_t' {aka 'unsigned char'} [-Wnarrowing]
song.h:92:1: error: narrowing conversion of '-4' from 'int' to 'uint8_t' {aka 'unsigned char'} [-Wnarrowing]
song.h:92:1: error: narrowing conversion of '-2' from 'int' to 'uint8_t' {aka 'unsigned char'} [-Wnarrowing]

And if I force the type to (uint8_t), it compiles, but wrong sound

  0x41, (uint8_t)-16, // FX: VOLUME SLIDE ON: steps = -8
  0x9F + 16, // DELAY: 16 ticks
  0x40, 16, // FX: SET VOLUME: volume = 16
  0x41, (uint8_t)-4, // FX: VOLUME SLIDE ON: steps = -4
  0x9F + 4, // DELAY: 4 ticks

How to fix it right way?