There is a jam night I go to. One stage, three minute sets, about a hundred people in the room and maybe thirty of them carrying instruments. The host builds bands on the spot out of whoever turned up, which in practice means working out what to do with twenty guitarists when five drummers showed.

Jam Slam is the app I built for that. Players join from a QR code, the app proposes lineups, the host fixes them, and the night runs as a scored competition with a themed challenge each round.

Joining

There is no login for players. What a player actually does with this app is type a name, pick an instrument, and then check twice an hour whether they are up next. That did not seem worth an OAuth screen in a dark bar. The host signs in with Google, because the host wants their sessions back next month, and nobody else signs in at all.

Signup asks a second question: anything else you can cover? Bass and drums run short before anything else does, and a fair number of guitarists can get through a song on bass. Each one who says so turns a band that is one player short into a band that can play. It is not a question that works out loud. In front of a hundred people nobody puts their hand up.

Working out the bands

I set out to write a matching algorithm and ended up writing a rationing one. Guitarists are never scarce. Drummers and bass players are, so the number of bands is the number of drummers present, and the rest of the job is spreading everyone else across them.

The app proposes and the host edits. It never applies its own suggestion. It also prints what it did in the words a person would use: five drummers so five bands, twenty guitarists for fifteen seats, Kofi moved to bass so band five had a rhythm section, three on the bench. I added that after noticing I would not trust a lineup I could not check.

The bench

Bands stay together all night, so whoever sits out the first round tends to sit out all of them. Every player carries a count of rounds played. The bench sorts by it and anyone on zero is marked, and before a final round the app says who has still not been on stage.

It does not stop the host starting the round. Software that refuses to continue during a live event is worse than the problem it is preventing.

Running the night

Every band plays every round against a prompt. Cover a song in a different genre than the original. Three false endings. The drummer picks the song and counts it in. I wrote twenty five of them.

Scoring is an append only table of awards rather than a winner per round. Hosts call ties, double a round that went well, and hand out three points for playing bass with a beer bottle. Each of those is a row. There is no voting in the app either. The room claps and the host decides, and the app writes down what was decided.

A player's phone shows one of three things: you are up, on deck, or in the hole. There are no notifications, because web push on iOS needs the user to install the site to their home screen first and nobody at a party is doing that. It has to survive being read at arm's length in a dark room.

Build notes

Next.js and Postgres on Vercel. The matching code is pure functions with twenty five tests behind it, which is most of the test suite, because it is the part that is hard to check by eye.

I kept a decisions file while building it. Twenty eight entries, including the things that came out again: in app voting, self reported skill levels, a meter that scored applause through the phone microphone, push notifications, and the elimination bracket I started with. The bracket went when I worked out the timings. Eight bands at three minute sets with four minute changeovers means most people play once and then watch for two hours.

It is deployed and it has not run a real night yet. The next jam is the test.