Notewhacker

A game for learning sheet music notation.

Connect your General Midi-enabled musical instrument of choice to your computer. Start Notewhacker and try to hit your instrument’s keys matching the notes scrolling on a staff on your screen.

2024-05-03, version 0.0.5 (See CHANGELOG.org)

Installing and running

Download the software (e.g. clone from git).

Easiest way to get the software running is to use Quicklisp:

• Install Quicklisp, if not installed already. (Rest of the steps assume it’ll be installed to default directory ~/quicklisp.)
• Copy or move the notewhacker directory into quicklisp’s local-projects directory ~/quicklisp/local-projects.
• Run in Lisp repl (ql:quickload "notewhacker"). This will automatically download and compile the dependencies and compile Notewhacker.
• Start the program with (notewhacker:main).
  • Notewhacker tries to guess the midi instrument. If you use JACK, you need to connect your instrument to Notewhacker, e.g. with qjackctl. If you use OSS, you may need to set *midi-device-pathname* to the path to the midi device of your choice (e.g. /dev/midi4).
• After initial installation, you can load Quicklisp in your Lisp repl with (load "~/quicklisp/setup.lisp") before loading Notewhacker, e.g. in SBCL:

$ sbcl
...
* (load "~/quicklisp/setup.lisp")
T
* (ql:quickload "notewhacker")
...
("notewhacker")
* (notewhacker:main)

System requirements

• Reasonably recent Linux operating system (might work on other Unixes too, incl. MacOS, and maybe even on Windows)
  • Audio:
    • Either JACK (or Pipewire which is default in modern Linux)
    • Or OSS or ALSA with OSS emulation turned on
  • Simple Directmedia Layer version 2.0 system library
• OpenGL 2.0 compatible graphics card and drivers
  • Related libraries for Linux
• Clozure Common Lisp or SBCL implementation of Common Lisp
• General Midi compatible musical instrument or some such
  • For quick testing a virtual keyboard like vkeybd is sufficient

Changing the visible staffs and midi channels

• To e.g. remove the staff with the f-clef (𝄢) modify file notewhacker.lisp function gen-game-loop by removing the s-expression starting (f-staff (make-instance....
• By default g-clef (𝄞) only matches events in midi channel 0 and f-clef (𝄢) events in channel 1. To change both recognize all channels, change in the aforementioned file and function the lines with :midi-channel 0 and :midi-channel 1 both to :midi-channel nil.

Keyboard control (mostly for testing or debugging)

• On (Finnish/Swedish) QWERTY keyboard key C corresponds to C4 note, F to C4 sharp etc. When hit while holding left shift they generate midi channel 1 events, channel 0 otherwise. For testing purposes; game can’t be played reasonably using keyboard.

Getting sound out from your controller

Notewhacker doesn’t output sound by itself but assumes your instrument generates sound.

However, some MIDI controller keyboards do not have their own tone generators but rely on another MIDI device (e.g. a computer) to produce sound.

One solution to hear the notes you play in Notewhacker is that you could start a software synthesizer like e.g. fluidsynth and route the MIDI data to both Notewhacker and the software synth. Preferred way to do this is to utilize Notewhacker’s JACK interface, as JACK makes routing very easy.

MIDI routing on OSS only system

If, however, you need to use OSS only, I implemented a MIDI-thru system. To enable it, first create a FIFO with terminal command:

mkfifo $HOME/midi-thru

(Or if you want to change the FIFO’s name, modify also the *midi-thru-pathname* variable in oss-midi.lisp.)

Then add :notewhacker-midi-thru to *FEATURES* and compile Notewhacker again; i.e. do the following in your Lisp repl:

* (pushnew :notewhacker-midi-thru *features*)
... [some output which depends on your system] ...
* (asdf:load-system :notewhacker :force t)
... [lots of output] ...

Then, install a software synthesizer, e.g. fluidsynth (and some soundfonts). Start it and force it to use OSS:

fluidsynth -a oss -m oss -o midi.oss.device=$HOME/midi-thru /usr/share/sounds/sf2/FluidR3_GM.sf2

(The /usr/share/sounds/sf2/FluidR3_GM.sf2 part depends on where you have the soundfonts installed.)

If you’re running on a system with PulseAudio, you may need to run:

padsp fluidsynth -a oss -m oss -o midi.oss.device=$HOME/midi-thru /usr/share/sounds/sf2/FluidR3_GM.sf2

(Or if on a system with Alsa, replace padsp with ossd.)

To get a graphical UI, you can replace fluidsynth with qsynth in the commands above.

Then start Notewhacker normally and enjoy the sounds! (You can use normal program change controls to choose different General Midi instruments; all data is routed through the MIDI-thru, not just the messages Notewhacker understands.)

Demo

Short demo of version 0.0.1 at YouTube.

Acknowledgments

This project includes some parts of code derived from work of 3b (see comments in files notewhacker.lisp function main, and graphics.lisp function with-vecto-canvas-as-texture). The derived code is published here with the original author’s consent.

The font for musical notation (feta.ttf) is copied from project Denemo. The font was originally derived from Lilypond project. See file LICENSE.feta.ttf.txt for more information.

The text font (CrimsonText_Roman.ttf) was created by Sebastian Kosch and licensed with SIL Open Font License and redistributed with Notewhacker in its original version. It was downloaded from Font Squirrel. See file SIL Open Font License.CrimsonText-Roman.ttf.txt for more information.

Thanks to Yrjö Kari-Koskinen for improvements, ideas and testing.

Finally, this software exists thanks to Lisp In Summer Projects contest.

To do

• More intelligence to target chord creation.
  • User configurable note range.
  • Reasonable chords. Now they are totally random within a certain predetermined range.
  • Learning: generate target notes which player finds difficult more often.
• Key signature changes during game.
• Accordion-mode (Handling Stradella Bass System).
• Reading target notes from a midi file to enable practising a piece.

Known bugs

On some graphics cards all of the textures have a thin transparent line going across them. This happens e.g. on Nvidia Quadro NVS 4200M. The software was developed using Intel HD4000 graphics card, and VirtualBox with Windows host OS and Intel HD 530 graphics card, which don’t expose this bug.

Author

Janne Nykopp <[email protected]>

License

GNU General Public License Version 3, 29 June 2007