ArduboyTones - a library for generating tone sequences

I’ve created a new library which generates tones and tone sequences, for playing sound effects and simple music in Arduboy sketches, called ArduboyTones. It is simple to use and efficient. It creates substantially less code than the ArduboyPlaytune library, or even the Arduino tone() function.

For all the details on the ArduboyTones library, see the file in the repository.

Features of ArduboyTones are:

  • Like ArduboyPlaytune and Arduino tone(), sounds are played using interrupts in the background, while the “real” code continues to run in the foreground.

  • Plays 1, 2 or 3 tones in sequence, using the tone() function, or any length sequence stored in an array, using the tones() or tonesInRAM() functions.

  • Durations of silence (musical rests) can be included.

  • Each tone can be played at normal volume or a higher volume. High volume drives the speaker at twice the voltage.

  • Sound can be globally muted using the standard Arduboy audio.on() and functions.

  • Uses only timer 3, so the Arduboy’s RGB LED will work properly using setRGBled() without conflict, unlike Arduboy V1.1 or the ArduboyPlaytune library.

  • The library is “hard coded” for the Arduboy hardware, so the sketch doesn’t have to specify the speaker pins in any function calls.

Because ArduboyTones takes over the timer 3 interrupt, it can’t be used with the Arduboy library V1.1 which grabs the timer 3 interrupt for its tunes functions. If you wish to use ArduboyTones in your sketch, you should use my Arduboy2 library for the main API.

Update: I’ve decided to just maintain AduboyTones in my own repository as given above.
@ekem and/or other people of authority,
If you want ArduboyTones to become an “official” library, just say the word and create a new ArduboyTones repository under the Arduboy user on GitHub. I’ll try to get it up and running as quickly as possible. We could then start the process of making it available through the Arduino IDE Library Manager.


Awesome. This is the way to do music (if we want it in “default” libs)… to split it out into it’s own official class… so you can use it if you want but still free to [easily] choose alternative.

Can you give me an example of how is meant to be used? So I just run it into my Arduboy and see how it works.

First, ArduboyTones can’t be used with the current V1.1 Arduboy library due to interrupt conflicts. You’ll have to use the Arduboy2 library. Make sure you have both Arduboy2 and ArduboyTones installed in the Arduino IDE.

You can try the ArduboyTonesTest example program included in the library and examine it for examples of using the library.
File > Examples > ArduboyTones > ArduboyTonesTest

For complete documentation, see the file in the repository.

You would start your sketch like so:

#include <Arduboy2.h>
#include <ArduboyTones.h>

Arduboy2 arduboy;
ArduboyTones sound(;

void setup() {

Write the rest of you sketch the same as usual. Whenever you want to play a tone or sequence of tones, you use one of the ArduboyTones library functions. Since the above example names the ArduoboyTones class object sound you call the functions as

For example:

sound.tone(1000, 500); // play a 1000Hz tone for 500ms
sound.tone(NOTE_A4, 200); // play piano note A4 (440Hz) for 200ms

// Play C4 followed by E4 followed by G4 each for 100ms
sound.tone(NOTE_C4,100, NOTE_E4,100, NOTE_G4,100);

If you want to play more than 3 notes in a row using a single function call, you can put the notes in an array and use the tones() function:

const uint16_t scale[] PROGMEM = {
  NOTE_C3,500, NOTE_D3,500, NOTE_E3,500, NOTE_F3,500,
  NOTE_G3,500, NOTE_A4,500, NOTE_B4,500, NOTE_C4,500,


All tones play in the “background” while the sketch continues. If you want to do nothing while waiting for the tones to complete, you can use the playing() function:

while (sound.playing()) { };

Thank you MLXXXP for the awesome contribution to the Arduboy community.

The ArduboyTones.tones() method is more flexible than the ArduboyTunes.tone() method by far.

What i’m having trouble with is that programs like miditools seems to help with music generation workflow, such as working with a MIDI app to generate a .mid file, then convert to the necessary unsigned char data.

Have you considered such an approach w/ ArduboyTones?

I ask because trying to create music by an array of notes & durations is time consuming, error prone and can possibly hurt the adoption of the library.

Thanks :slight_smile:

Already done (as long as you’re comfortable with using a command line program).

I’ve enhanced the MIDITONES program to allow converting a MIDI SMF file to AruduboyTones format, in addition to its original purpose of converting to the Playtune format (used in the current Arduboy library). I just haven’t announced it yet (so I guess this can be considered the announcement :slight_smile:)

Len Shustek, the author of MIDITONES, didn’t wish to include my enhancements in his program but is fine with me creating a fork. My program is called midi2tones and can be found here:

ArduboyTones is now easier to install. It’s now available in the Arduino IDE library manager.

  • In the Arduino IDE select from the menus: Sketch > Include Library > Manage Libraries...
  • In the Library Manager Filter your search… field enter arduboytones.
  • Click somewhere within the ArduboyTones entry.
  • Click on the Install button.

The Arduboy2 library is also now installable via the Library Manager in the same way.

For more library installation information see

Installing Additional Arduino Libraries - Using the Library Manager

1 Like

That’s bad ass dude. I had not realized that you forked Miditones :smiley:

I’ll take a look and see if this helps us =).

Thanks a ton, Scott!

1 Like

It just hit me that Tones & Tunes are not compatible.

Seems that MIDI2Tones creates a byte stream, where sound.tones() requires uint16.

My hopes was that tones() would allow me to 1) play tunes in the background, 2) play up to 3 tones in sequence to create sound effects (something that Tunes can’t do).

ArduboyTones is a bit more limited than ArduboyPlaytune with respect to playing background music and sound effects at the same time. However:

  1. It can play tunes in the background. The tune must be monotonic, whereas ArduobyPlaytune can play two voice polyphonic.

  2. You can play effects of up to 3 tones (or more using an array) but it will stop whatever sound (background music or other effect) is currently playing. You can use the playing() function to know when the effect has ended and then restart the background music. Unfortunately, each time you do this the background music will start from the beginning.

I wrote ArduboyTones to be very small, simple and efficient. It wasn’t really intended to allow both background music and effects at the same time. I figured ArduboyPlaytune served that purpose, at the expense of larger code size and causing problems with the RGB LED.

1 Like

midi2tones can create either a Playtune compatible byte stream or the “frequency/duration pair” stream used by ArduboyTones.

For ArduobyTones compatible output you use the -o2 command line option.

1 Like

Shit dude. Apologies for missing the -o2 switch.

I’ll play w/ it. :grin:

This is the monster we’re working on.


Dear all,
Sorry to be a pain, I am trying to understand why most piezo sounders have a signal wire for PWM and a ground and the Arduboy has two signal wires with 2 x PWM in sync (I had a look at the signal on a scope today). How does this work? I know from the forums you created some clever code to raise the volume. Please advise.

I am a teacher and have been asked by a student!

Steve Daly

1 Like

This might help …

1 Like

That article not very relevant to the question. A real Arduboy does have a non-typical piezo speaker, with two ceramic elements; one on each side of the flexible metal disc. A standard piezo transducer has only a single element on one side of the metal disc. When driven properly, a dual element disc can produce more volume for the same size as a single element but the way the Arduboy is wired it only makes use of one of the elements (so a single sided disc could have been used, and is for most homemade designs).

I think this post of mine better explains the use of two pins:


Thanks guys, this information is very useful in understanding the operation of the circuit, thank you kindly for the explanation, I’ll forward it on to the students.


Hi sorry to bother you. I took a scope reading during playing Picovaders and got channel 1 and 2 trace one each pin of the piezo buzzer. See picture. I wonder if I made a mistake as I would have expected so see one of the signals inverted? Any idea?

Note that there is a 220 ohm resistor between the signal coming from Arduino Pin 5 (ATmega32U4 pin 31) and the buzzer lead that it drives. (It’s shown as capacitor C12 in the schematic but it’s populated with a resistor.) Therefore, if you’re scoping that buzzer lead itself, you are probably seeing an attenuated version of the other buzzer lead.

With Picovaders, Pin 5 is held at low and only Pin 13 is driven with an audio signal.

To look at the Pin 5 output, you can put your probe on the microprocessor side of the resistor, as circled in green in this photo:


1 Like

Thanks Scott, that makes sense. I will have a go and get back to you! Thank you very much for your time. Greatly appreciated.