ArduboyTones - a library for generating tone sequences

(Scott) #1

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 README.md 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 audio.off() 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.

Strange behavior with setRGBled
Poop Panic!(for 1st ARDUBOY GAME JAM)
Nomis: A simple memory game similar to Simon(tm)
Domino 'All Fives'
CosmicPods - tiny shoot- 'em-up game for Arduboy
Rayne the Rogue
Arduminer Development Progress
Red / Blue LED won't analog if arduboy.begin();
Arduboy has entered the building
New game - BurgardTime
Arduboy Music Conversion Help
SkateArdDie! - Awesome
Arduboy2 - The now recommended alternative to the Arduboy Library
Arduboy2 - The now recommended alternative to the Arduboy Library
(Josh Goebel) #2

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.

#3

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.

(Scott) #4

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 README.md file in the repository.

You would start your sketch like so:

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

Arduboy2 arduboy;
ArduboyTones sound(arduboy.audio.enabled);

void setup() {
  arduboy.begin();
}

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
sound.<functionName>().

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,
  TONES_END
};

sound.tones(scale);

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()) { };
(Jay Garcia) #5

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:

(Scott) #6

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:

(Scott) #7

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

(Jay Garcia) #8

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!

(Jay Garcia) #9

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).

(Scott) #10

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.

(Scott) #11

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.

(Jay Garcia) #12

Shit dude. Apologies for missing the -o2 switch.

I’ll play w/ it. :grin:

This is the monster we’re working on.