What you're building

Open 8beety.com in another tab before you read any further. Sixty seconds with the real thing will teach you more than this chapter does, and this chapter reads better once you have heard what it is describing.

The 60-second tour

1. Drop in a .mid file, or a saved 8BEETY project. The auto-arranger reads your tracks and assigns them to chip channels the way a chiptune composer would have: melody to a pulse channel, bass to the triangle or the wavetable, drums to the noise generator, chords turned into fast arpeggios.
2. Press play. What you are hearing is a sound model of the actual chip, not an "8-bit" filter sitting on top of a normal synth.
3. Pick your console from one dropdown. NES gives you the 2A03: two square waves, a triangle for bass, noise for drums. GB gives you the Game Boy: squares, a wavetable voice, stereo hard-panning. SNES gives you eight sampled voices, strings and e.piano and brass and choir, with the Super Nintendo's signature echo. SEGA gives you five channels of gritty Yamaha FM plus 8-bit DAC drums. Switching remaps your whole arrangement onto the new chip's channels and instruments, mid-playback, without stopping.
4. Shape the arrangement. Drag tracks between channel cards. Choose instruments: square leads, plucks, FM bells, sampled flutes. Tweak duty, attack and decay, vibrato. Set poly modes (highest note, lowest note, arpeggio speed, or split across channels). Split a track into regions so the chorus does not have to sound like the verse. Fatten a lead with detune or echo layering.
5. Use Chord Assist. It detects your key and your chord progression, enriches plain triads with diatonic 7ths and 9ths if you want that, and suggests substitute progressions drawn from a 108-progression corpus.
6. Export. WAV, rendered offline and studio-clean, with an optional loop-twice-and-fade because game music loops. Video, a 9:16 MP4 sized for TikTok and Shorts and Reels, your song scrolling DAW-style across the screen of a drawn Game Boy for the 8-bit chips or above an SNES-style or Genesis-style console for the 16-bit ones, with your song title on the cartridge label. MIDI, your arranged version back out as a standard file. Project JSON, so you can reload the whole arrangement later.
7. Share a link. The entire project, MIDI included, is compressed into the URL itself. No account, no upload, no server holding your file.

What makes it sound right instead of merely retro

Anybody can put a bitcrusher on a piano. The difference is in four decisions, all of which were written down before the code existed.

• Pitches go through the real chips' register math. High notes drift slightly out of tune exactly the way the hardware drifted, because the pitch round-trips through the same integer timer the console used.
• Chords become arpeggios at twenty a second. That is the actual technique NES composers used to fake polyphony on a chip that did not have it, and it is where the signature chiptune shimmer comes from.
• The chip quirks are modeled, not smoothed out. The NES output runs through the console's real nonlinear mixer and output filter. The Game Boy's volume changes snap to its 64 Hz envelope clock. The SNES voices get BRR-flavored grit and gaussian warmth. The Genesis FM uses the YM2612's genuine operator algorithms.
• Everything is quantized to 60 fps. Parameter changes land on frame boundaries and nowhere else, because that is the clock those sound drivers actually ran on. The quantization is not a limitation being worked around. It is part of the sound.

None of that is an accident, and none of it was discovered while coding. Every one of those bullets is a line in a document that existed before the first prompt, which is what the next chapter is about.

How to read the repo

The repo is github.com/ShaneDolphin/8beety, and it is the most useful thing in this guide, because everything in it is real. Open these five, in this order, and give each one a few minutes.

1. SPEC.md. What was decided before any code existed. Read the non-goals and the core rules and skip the chip math on the first pass.
2. CLAUDE.md. The standing rules, the ones the coding agent read at the top of every session. Notice how short it is and how little of it is style.
3. docs/superpowers/plans/. How the work was actually sliced, twelve implementation plans as they were executed. Open one and look at the shape of a task, not the content of it.
4. tests/. What "done" meant in practice. This is where a claim turns into a result.
5. src/engine/compile.ts. The pure function everything else hangs off. Playback, WAV export, and video export are all downstream of this one call.

Skim, do not study. You are looking for the shape of a project that was built this way, not for a working knowledge of FM synthesis. You will come back to individual files as the chapters need them.