+
+---
+
+A music box that fits in a QR code. [Source on Codeberg](https://codeberg.org/nupanick/qrplay).
+
+
+
+## scanning a code
+- scan with your phone's photo app or barcode app and *copy* all the text.
+- in an empty browser tab, *paste* the text into the URL bar.
+- press play!
+
+## making music
+
+### notes and commands
+
+- `CDEFGAB` are musical notes. you can make a note sharp with `/` or flat with `:`. for example, C sharp is `C/` and A flat is `A:`.
+- `X` rests for the current note length.
+- `+-` changes the octave up or down. The default is the 4th octave, the one which contains middle C.
+- `WHQISTJ` changes the rhythm of the following notes. The note lengths are Whole, Half, Quarter, eIghth, Sixteenth, Thirtysecond, and sixtyfourth (J). the default is T.
+- `3` divides the current note length into triplets. for instance `Q3ABC` would play three notes that add up to one quarter note.
+- `.` increases the current note length by 50%, so `H.A` would play a note that lasts for three quarters.
+- `Vnn` sets the current volume to a number between 0 and 99. the default is `V30`. `V35` is twice as loud, and `V40` is twice as loud as that.
+- `Unnn` sets the tempo in beats per minute. the default is `U137`, for [historic reasons](https://nicole.express/2025/zoo-of-zero-motivation.html).
+- `R` resets the pitch and note duration back to the defaults.
+
+### samples
+
+`$𝑥...*` saves a sample in slot 𝑥. For instance, `$0RSDDI+D-A*` would save the Megalovania riff into slot 0. you then play the sample like a note, with `0`.
+
+the characters `012456789YZ` and space are QR-friendly and are reserved for storing samples. If you run out, you can also use ``[\]^_`{|}~``, newline, lowercase letters, or any UTF16 code unit.
+note that `3` is missing as it is already used for triplets.
+
+special case: if a sample ends with the letter `V`, it will play asynchronously with the main track. for instance, you could play a chord like this: `$0CV*0 G`.
+This would play the C from the sample and the G from the main track at the same time.
+
+samples keep separate octave and note length from the main track, but setting volume or tempo within a sample will change it globally when played.
+
+samples can save and play samples, including themselves. if a sample plays itself it will loop.
+to prevent browser crashes, recursion and loops are capped at 100 iterations, and the limit decreases each time it is reached.
+if a sample saves into its own slot, you won't be able to play it again.
+
+if a sample uses an incompatible character, then it cannot be played. you can use this to write comments, like `$:TITLE: MY COOL SONG*`.
+you can nest samples/other comments in your comment, but you can't use `$` `*` as ordinary text.
+you can also write lowercase letters as comments if no samples are written for them, such as at the top, before your song.
+
+## making a QR code
+
+- make a copy of *qrplay.html*.
+- remove all comments, leading whitespace, and trailing whitespace.
+- remove all newlines.
+- add `DATA:TEXT/HTML,` at the start, including the comma.
+- paste your song at the end.
+- replace all spaces with `%20`, `#` with `%23`, newlines with `%0A`, and `%` with `%25` if it is followed by two numbers.
+- use a QR generator like [Zint](https://sourceforge.net/projects/zint/) to convert your code.
+
+Your code will compress the best if it only uses the QR Alphanumeric subset. This means `0-9A-Z $%*+-./:`. There are no newlines or lowercase letters.
+
+Zint allows you to mix data of different types, so you don't have to write your *entire* song this way, but it will save space if you do.
+
+on a linux machine, with `qrencode` installed, you can use `make SONG=` to do this automatically, or use `make SONG=` to make a QR code with no song.
+
+## conversion
+
+qrplay is based on [ZZM](https://museumofzzt.com/file/browse/detail/zzm-audio/), which itself based on the [ZZT Music Format](https://chriskallen.com/zzt/zztoop.php#sound).
+To convert from ZZT Ultra or ZZM to qrplay:
+
+- uppercase all notes. `abcdefg` becomes `ABCDEFG`.
+- if converting from ZZM (not ZZT Ultra), add `R` to the start of every line.
+- replace sharps (`#`) with `/`, flats (`!`) with `:`, and resets (`@`) with `R`.
+- collect `Z` channels together by their number (so `Z01 A Z02 B Z01 C Z03 D` becomes `Z01 AC Z02 B Z03 D`)
+- if the song uses any drums `012456789`, add these approximations at the beginning of the file. note that all of them will overwrite slot Z when played.
+ ```
+ $0$ZRJ33+++GV*ZX*
+ $1$ZRJ33+B+C#DEFF#GV*ZX*
+ $2$ZRJ33++G++DDB--G++DDBV*ZX*
+ $4$ZRJ33+++EA-G--B++G++C#V*ZX*
+ $5$ZRJ33++A#GA#G-A#+G-B+GV*ZX*
+ $6$ZRJ33+A++C#-AAE+E--AV*ZX*
+ $7$ZRJ33+FFED#DDC#V*ZX*
+ $8$ZRJ33++DDDDDD#EV*ZX*
+ $9$ZRJ33BA#BB-A+A#-BV*ZX*
+ ```
+ (at the default rate of 137bpm, J33 is 3.8ms, a little longer than the millisecond "clicks" used by ZZT.
+ the approximations here are based on source code from [The Reconstruction of ZZT](https://github.com/asiekierka/reconstruction-of-zzt/blob/master/SRC/SOUNDS.PAS#L105).)
+- replace `Z` channels with immediately played async samples, optionally excluding the last one. for instance, `Z01 AC Z02 B Z03 D` becomes `$ZACV*Z $ZBV*Z D`.
+
+to choose a slot for immediately played async samples:
+- if any drum (or Y or Z) isn't used, you can use that slot.
+- if all drums are used, you can use a lowercase letter like `z`.
+- if all drums are used but you can't use a lowercase letter (alphanumeric QR code), you can remove all spaces from the file and use space (`$ ACV* $ BV* D`).
+- if all drums are used but you can't use a lowercase letter or space (alphanumeric QR code with formatting or escaped spaces),
+ you can use 0 and move the 0 drum sample to the start of each channel sample.
+
+There is no equivalent of some ZZT ultra commands. You should remove them to avoid confusion.
+- P priority override. alternative: remove the notes that you don't want to play.
+- O octave override. alternative: use `R` to reset to octave 4 and `-+` to choose an octave.
+- K echo mode. alternative: play the same sample twice with a slight delay and a volume change.
+- % pitch sliding. alternatives: none. you will have to play staccato instead.
+
+## thanks
+
+- SArpnt for their hard work and helpful feedback to make the code as small and QR-friendly as possible, even as I kept trying to cram in "one more feature".
+- asie for the [Reconstruction of ZZT](https://github.com/asiekierka/reconstruction-of-zzt/blob/master/SRC/SOUNDS.PAS), which served as the blueprint for this project.
+- Chris Allen for the [ZZT Ultra Hall of Music](https://chriskallen.com/zzt/hallofmusic.html), for documenting and showcasing the ZZM format and several awesome songs.
+- Nicole Express for this [blog post](https://nicole.express/2025/zoo-of-zero-motivation.html) that helped me understand the timings.
+- Thonky for the [QR Alphanumeric Mode](https://www.thonky.com/qr-code-tutorial/alphanumeric-mode-encoding) reference.
+- the great people at Mozilla for documenting how to generate sound in a web browser, particularly the page about the [OscillatorNode](https://developer.mozilla.org/en-US/docs/Web/API/OscillatorNode).
+- there's a good chance this would not exist if I hadn't been exposed to [Jesse's Bookmarklets](https://www.squarefree.com/bookmarklets/) back in the 2000s. Thanks, Jesse!
diff --git a/static/qrplay/index.html b/static/qrplay/index2.html
similarity index 100%
rename from static/qrplay/index.html
rename to static/qrplay/index2.html
diff --git a/static/qrplay/qrplay-v3-sunshine.png b/static/qrplay/qrplay-v3-sunshine.png
new file mode 100644
index 0000000..34b6dca
Binary files /dev/null and b/static/qrplay/qrplay-v3-sunshine.png differ
+
+## scanning a code
+- scan with your phone's photo app or barcode app and *copy* all the text.
+- in an empty browser tab, *paste* the text into the URL bar.
+- press play!
+
+## making music
+
+### notes and commands
+
+- `CDEFGAB` are musical notes. you can make a note sharp with `/` or flat with `:`. for example, C sharp is `C/` and A flat is `A:`.
+- `X` rests for the current note length.
+- `+-` changes the octave up or down. The default is the 4th octave, the one which contains middle C.
+- `WHQISTJ` changes the rhythm of the following notes. The note lengths are Whole, Half, Quarter, eIghth, Sixteenth, Thirtysecond, and sixtyfourth (J). the default is T.
+- `3` divides the current note length into triplets. for instance `Q3ABC` would play three notes that add up to one quarter note.
+- `.` increases the current note length by 50%, so `H.A` would play a note that lasts for three quarters.
+- `Vnn` sets the current volume to a number between 0 and 99. the default is `V30`. `V35` is twice as loud, and `V40` is twice as loud as that.
+- `Unnn` sets the tempo in beats per minute. the default is `U137`, for [historic reasons](https://nicole.express/2025/zoo-of-zero-motivation.html).
+- `R` resets the pitch and note duration back to the defaults.
+
+### samples
+
+`$𝑥...*` saves a sample in slot 𝑥. For instance, `$0RSDDI+D-A*` would save the Megalovania riff into slot 0. you then play the sample like a note, with `0`.
+
+the characters `012456789YZ` and space are QR-friendly and are reserved for storing samples. If you run out, you can also use ``[\]^_`{|}~``, newline, lowercase letters, or any UTF16 code unit.
+note that `3` is missing as it is already used for triplets.
+
+special case: if a sample ends with the letter `V`, it will play asynchronously with the main track. for instance, you could play a chord like this: `$0CV*0 G`.
+This would play the C from the sample and the G from the main track at the same time.
+
+samples keep separate octave and note length from the main track, but setting volume or tempo within a sample will change it globally when played.
+
+samples can save and play samples, including themselves. if a sample plays itself it will loop.
+to prevent browser crashes, recursion and loops are capped at 100 iterations, and the limit decreases each time it is reached.
+if a sample saves into its own slot, you won't be able to play it again.
+
+if a sample uses an incompatible character, then it cannot be played. you can use this to write comments, like `$:TITLE: MY COOL SONG*`.
+you can nest samples/other comments in your comment, but you can't use `$` `*` as ordinary text.
+you can also write lowercase letters as comments if no samples are written for them, such as at the top, before your song.
+
+## making a QR code
+
+- make a copy of *qrplay.html*.
+- remove all comments, leading whitespace, and trailing whitespace.
+- remove all newlines.
+- add `DATA:TEXT/HTML,` at the start, including the comma.
+- paste your song at the end.
+- replace all spaces with `%20`, `#` with `%23`, newlines with `%0A`, and `%` with `%25` if it is followed by two numbers.
+- use a QR generator like [Zint](https://sourceforge.net/projects/zint/) to convert your code.
+
+Your code will compress the best if it only uses the QR Alphanumeric subset. This means `0-9A-Z $%*+-./:`. There are no newlines or lowercase letters.
+
+Zint allows you to mix data of different types, so you don't have to write your *entire* song this way, but it will save space if you do.
+
+on a linux machine, with `qrencode` installed, you can use `make SONG=