The Tiniest Example

Here’s a learning technique I just discovered.

I was working on video rendering on Android devices – reading through and mashing together libraries and example code I found. The task as it’s currently structured has 6 main classes interacting:

  • An extractor to present encoded frames of video from a file
  • A decoder to decode each frame
  • An animator to keep this happening regularly and check if it’s time to show a new frame
  • A view which is the interface element the video will be shown in, and which I’m using as a convenient repository for all the other action (this seems to be pretty standard approach)
  • A renderer which talks to OpenGL, the rendering API

I’ve been bodging everything together in one prototyping/sketchpad project. My approach was to keep it just-about-functional for my one test case (displaying three overlaid alpha-blended video elements) as I swapped in and out components and ported bits from Java to Kotlin.

I definitely learnt a lot from that, but today I tried a different tack.

Instead of accomplishing a fairly complete task messily and crudely, I took the single component I wanted to understand and placed it in a blank, fresh project. Then I tested it!

A boring screenshot

I got the class, TimeAnimator, to report all salient variables to GUI elements. Like debug text but organised so I can see the situation at a glance.

I realised I couldn’t make it do what I thought it had been doing, which was fire events at a steady framerate equal to the video framerate (of 30fps).

I shuffled through variants of the class and learnt what they do.

After a bit, I realised none of them did what I wanted. I went back to the library I was studying and finally twigged that the controlling framerate/timing information came from the decoded video data, which was merely being checked (at a frequency much faster than the framerate) by the TimeAnimator, which is not meant to run anywhere near as slow as 30fps.

So far, so trivial. But I might have kept playing with the original code for ages without actually challenging my assumptions, distracted by all its moving parts and the fact that it looked somewhat like the final product I wanted.

I will definitely be reusing this technique of isolating the smallest component that I don’t understand, and “prickin’ it and frickin’ it” as my favourite rapper Guru might say.

Hope to be back here soon to discuss what this video functionality is actually for!

Synth Sins

Warm analogue it ain’t. I knew when I started coding my synth-sequencer, Foldy, a few months ago, that it’d be harshly digital and crude sounding. I was inspired by tracker software as well as by two old PC-only music programs, Drumsynth and Hammerhead (which were the basis of my beat-creating project last year).

I’m releasing it today and calling it version 1.0. It works, but some iffy design decisions mean I won’t keep developing it.

That said, the code quality is a step up from my last release, the experimental art tool MoiréTest. I was able to go back and make big changes in Foldy, without the whole thing crumbling, which is always a good sign.

For the rest of this post I’ll explain what the program does, then what questionable decisions I made and how I would do it again.

(To try it yourself, download Foldy.jar from here and double click on it. If that doesn’t work try the further instructions in the readme.)

Foldy takes in a musical sequence, which you can type into a box in the app window. Notes are numbered as MIDI notes, where A=440 is at 69, and notes range from 0 to 128, and separated by commas. A rest is -1.

(By the way, did you know that, incredibly annoyingly, there is no industry standard for numbering the octaves of MIDI notes? The frequencies are agreed on, but one manufacturer’s C3 is another’s C4… how sad. This doesn’t impact Foldy though, I just work from the frequencies.)

The speed that notes are played is altered using tempo and beat subdivision controls. All the other parameters in the window modify the sound of individual notes. Only one note can play at a time. This kept things a bit simpler though, with the Java Sound API, opening another output line or mixing two together wouldn’t be much harder.

I was going to include a choice of mathematical curves, possibly Bezier curves, for the amplitude envelope, out of a perverse desire to avoid the bog-standard Attack-Decay-Sustain-Release model, which is suited to a keyboard instrument where a note is attacked, held and released. I was thinking this synth could be more percussive, inspired by the basic sample-playback model of drum machines and trackers (a type of sampler software originally made for Amiga computers and associated with the demoscene).

Unfortunately I didn’t finish the Bezier stuff, but in any case it probably wasn’t suitable. (For one thing, Bezier curves can easily have two y values for one x value.) In fact, I didn’t do any extra envelope options, partly because envelopes typically drive filters or modulations, but these are not allowed by my architecture. If there’s an obvious v1.1 feature, extra envelope curves is it.

One feature that did make it in is “wave-folding”. To get more complex waveforms, I cut a sine wave at a certain amplitude, and invert anything above that amplitude. This can be done multiple times to add a lot of harmonics.

Adding harmonics to a sine wave by folding it at 1/2, then 1/4 amplitude

However, this is a restrictive technique with a distinctive grinding, mechanical sound. All we’re doing here is shaping a waveform which is then repeated exactly at the period of the note frequency. The ear instantly picks up the lack of complexity.

I remember when I was a teenager, having the following bright idea: if I can see that the recorded waveform from my bass consists of repeated bumps, can’t I just sample one of those and repeat it/change the speed of it to get any bass note I want?

Why, chap, it’s simply a bunch of bumps (by the way, don’t record bass in stereo like I did here)

This is the basic concept of wavetable synthesis. However, when done as simply as that, it sounds completely artificial, not at all like a bass guitar. The sound of any real instrument has complexities like propagating resonances, changes in pitch, string rattle and other distortions/energy loss.

(E.g. listen to the low note in this sampled bassline – it’s starts really sharp, then reverts to normal. That’s because plucking of a stringed instrument raises the pitch of the note momentarily, especially on an open string – I think this was an open E string on the original sampled recording, just it’s been pitched up here.)

Foldy has no capability for such modulations. I could try put them in, but here we come up against the compromises I made at the start.

Because I was afraid that rounding errors would mount up and give me grief, I decided to keep everything as whole numbers, taking advantage of the fact that digital audio ultimately is whole numbers: a series of amplitudes or “samples” each expressed as, for example a 16bit or “short” integer. (Most studios mix at 24bit these days, but say CD audio only goes up to 16bit precision.)

This informed the basis of the synth. Desired frequencies and tempos are approximated by a wavelength and a subdivision length expressed in whole samples. 44100 samples per second might seem fairly precise, but for musical pitches, it isn’t. So I found a compromise that bounded pitch error to about 20 cents:

Foldy tries to fit multiple wave cycles within a whole number of samples, for example 3 cycles in 401 samples. This gives a bit more precision, because the wavelength is 401/3 = 133.667 samples, in between the 133 and 134 wavelengths that are all I could get otherwise.

I then use these bits of audio, which I call “chunks”, and which could contain a single cycle or a handful of cycles, in the same way I was using single wave cycles originally. So every note would contain hundreds of them. Then I decided I could reuse this division to store amplitude envelopes – I gave each chunk a starting amplitude, and interpolated between these. (Of course, this is redundant at the moment because my overall envelopes are merely a linear interpolation from maximum to zero! But with a curved envelope, the result would be to store the curve within a few dozen or hundred points, with straight lines from point to point.)

Ugh… I don’t even want to write about it anymore. It wasn’t well conceived and caused me a lot of hassle. It precluded any of the more intriguing synthesis techniques I like, such as frequency modulation, because pitch in this system is fixed for each note (and imprecise).

Long story short, when I opened up the source code of Drumsynth recently, I realised that… it just uses floats and gets along fine. For modulation, it simply keeps track of phase as another float. I should’ve done that.

(That said, I think Drumsynth’s sound quality is far from pristine. This isn’t from rounding errors, I’m certain, but from not doing more complex stuff like supersampling. But, that’s out of my ability level right now anyway.)

Using floats, I still would have had trouble with the timing for the sequencer, probably… but that would have led me to the realisation that I was biting off too much!

It’s not a complete loss. I really enjoyed trying to calculate sine waves while sticking to integer arithmetic . I found out about Bhaskara‘s approximation, implemented it, and then found some really nice code using bitshifts to do a Taylor Series approximation of a sine wave. (I wish I had the chops to come up with it myself!)

Reading the source of Drumsynth also completely changed my approach to the GUI code. I originally had all of the classes that make up the synth – Note, Chunk, Sequence and so on – also be GUI elements by inheriting Java Swing component classes. I think I picked this up from some book or tutorial, but it’s obviously not good. It breaks the basic principle of decoupling.

Drumsynth blew my mind with its simplicity. There are no classes as it’s written in C, an imperative language. The synthesis is just one long function! I almost didn’t know you could do that, having spent a year studying Java and OOP. But given that the app is non-realtime (meaning that there is a third of a second pause to calculate the sound before you can hear it)… this is the sensible approach. Logically, it is one long straight task that we’re doing.

So I ripped out the GUI code from my main classes, and stuck it into one class called Control. Drumsynth’s GUI is even more decoupled: it’s written in a different language – a Visual Basic form that calls DLLs to access the synth functions!

(Yes, I know this is pretty out-of-date inspiration – heck Drumsynth even cheekily uses INI files for configuration though they were officially deprecated – but I think the lesson on directness and decoupling stands.)

My overall lessons from this project are:

  • Do normal stuff rather than trying to reinvent things.
  • Find exactly what draws you to a project and make that the focus. E.g. with this I would’ve been better off making something smaller and more conventional but which allowed me to try some unusual FM stuff.
  • Even though I’ve so, so much further to go, I kinda like low-level stuff. I mean, okay, nothing in Java is actually low-level, but still I was dealing with buffers, overflows, even endianness! Those are fun errors to fix.
  • Read other people’s code!

Even more generally, there’s a kind of tricky question here. This project showed me that it’d be a huge amount of work to approach the quality level of some of the audio programming frameworks out there such as JSFX, VST/Synthmaker, or JUCE. If I’m interested in actually programming synths for musical purposes, I should use one of those.

On the other hand, these are all coded in C or C++ (maybe with another abstraction layer such as EEL scripting language in the case of JSFX). If I really want to understand fundamentals, I should learn C.

But, it’s not very likely I’ll get a job doing high performance programming of that sort, considering the competition from those with as much enthusiasm as me for flash graphics or cool audio, but much more chops! I’m at peace with that – I quit music to get out of a profession that is flooded with enthusiasts.

Stuff to mull over.

Thoughts on Beginner Programming Languages

I coded up a prototype recently in a new realm: video compositing in real time. It was enjoyable for a few reasons, one of which was the language I used.

Processing has been around for a while. It’s designed to give instant access to graphics programming. It does that by exposing one-line functions that draw to a window without pretty much no configuration needed, by locking in a folder structure (e.g. images you want to work with go in a “data” subfolder), and tying everything together in a simple dev environment.

It’s ostensibly aimed at visual artists and students, and it fits in a lineage of what we could call “beginner languages” that intentionally hide complexity. Because I’ve now had a variety of encounters with such languages, including QBasic in my teens, a previous failed attempt to learn Processing, and a bit of a tool around with Racket earlier this year, I thought I’d try pin down some thoughts on them.

Let’s maybe take a wide perspective on my whole encounter, from the first thought of “Maybe I could use Processing?”

I DuckDuckGo-ed it, and a nice .org site popped up. Wow! First impressions were really good. The whole vibe of the community and ecosystem is cheerful and welcoming.

A nifty header style from the Processing website

There are pleasing non-jargon phrases all over the front page: “Creative Applications”, “Sketchpad”, “Visual arts”, “books available” – and yet it also feels like extensive technical work has been done, with links to implementations in multiple languages, and the obligatory Github profile, and many sponsors and partners.

I’m gonna go through this experience both from my current point of view, and an imagined one of a total beginner programmer. Both of these would give the Processing site, and related ones like Happy Coding, a hearty

The default installation format is a portable one. That might be a hassle to some. Or maybe it’s actually good. Unzip it and go, no permissions or shortcuts or whatevs.

The splash screen

The IDE loads showing a crisp splash screen with generative vector patterns like the main site. It’s perfectly decent, except for one thing which the docs make a lot of fuss about. Each code file is called a “sketch” – and the folder where these are kept is insistently referred to as “the sketchbook”. This caused me about ten minutes of trying to figure out if the sketchbook was a file format, and figuring out that it was automatically placed in a different location than where I’d unzipped the IDE. Calling it “sketches” would have made that clearer.

But for our absolute beginner, it’s not so bad: the IDE opens with a blank file, and you can copy in some example code and click the run button, and it works straight away. That’s REALLY nice.

This is what I really want to explore today. The trade-offs of simplification.

I think there’s an interesting conflict, in that simplification can make the first steps easier – which again is super valuable – but the next steps harder.

Both times I tried out Processing, I had this sinking feeling of near-betrayal as the light fun of the early steps sank into a morass of what feels like second-guessing the developers.

And I had it years back with the natural-language interactive fiction system, Inform 7, which I gave up on.

Making first steps easier is an illusion – one gets the feeling of accomplishment without really understanding what’s going on.

That can be all right. Computers hide inner workings from us all the time. The issue is finding the right balance of illusion so that the first peek behind the curtain doesn’t shatter fragile confidence.

I explore systems by trying odd things. For example, when I was checking out the Standard Vector Format for geometrical web graphics modifiable with JavaScript, I gravitated to abusing the “dashed line” capability to make weird art. (Overlaying super wide dashed lines to form swimming shapes and random pixel patterns.)

This tendency of mine clashes with the carefully-laid illusions of beginner languages. It took me say twenty minutes and half a screen of code to display one layer of a candle flame and show it, chuffed, to my dad. Implementing my actual goal of compositing a few layers with filtering and interactive controls, took a whole day, much of which was spent in frustration as the seemingly generous affordances of the language turned to cobwebs.

Here were some things that tripped me up after my first joyful success:

  • drawing off-screen required trawling the none-too-voluminous developer docs to figure out the difference between a PImage and a PGraphics object -I’m guessing working on an off-screen a buffer wasn’t considered a fundamental use case for people coming from a visual arts background
  • a Movie object acts like an Image, but its width and height fields are set at 0 until the first call to its read() method (making some initialisation stuff harder)
  • some graphics functions are overloaded so that they can take either the red green blue components of the desired colour or a single component as a greyscale value – but not consistently
  • drawing to an off-screen buffer has to take place inside the single set draw() method, otherwise it randomly will draw to the main window in flickers

And there was more, but this is boring. Once I figured them out, it was okay. Even the rather arcane pipeline I ended up with – a Movie’s read() setting a flag that an update is required, which is checked in draw() which if necessary calls loadPixels(), updatePixels(), beginDraw() and endDraw() on the various buffers, and the actual draw calls and filter calls, in the correct order – is more or less understandable. (I didn’t say optimal!)

It’s just that… there’s a let-down from the initial hey presto! to what feels like debugging a somewhat complex system you don’t understand. Now there’s nothing wrong with that process. That’s how to learn. But could the journey from delight to disappointment be mitigated?

It was that feeling of having waded in a bit beyond my depth and being swept away by uncontrollable factors, that turned me off Processing and Inform 7 before.

However… I don’t think Processing could be much better. The only ways to smooth my experience would be tiny tweaks: if someone rewrote a tutorial, tweaked a line in an example, and so on. I see why people talk of community as a central aspect of high-quality software.

My conclusion is that despite the inevitability of harsh contact with system complexity, beginner languages are great – but don’t start one, join an existing one.

Community building is also behind those good vibes that are maybe even more important than the technicalities, when welcoming interested newbies.

Oh, and yeah, what did I actually code? Glad you asked. Taking some tips from an awesome visual effects tutorial by an enthusiastic fellow called Lendon Bracewell, I made some candle flame effects for a votive shrine app I’m planning. The idea is for this to become a fast prototyping/design tool when I’m assembling my app’s candle animations and effects. Check it.

Till next time.

Side Project Satisfaction

Today I finished up a coding project, which was to make a simple synthesiser written in Java. I noted though, as I dashed off a quick readme file and uploaded the repository for the last time, a distinct sense of anticlimax, even disappointment. The app didn’t work out that well. Instead of writing an account of what I was trying to make and how I set about it, then, this evening I want to reflect on ways to avoid that letdown, specifically with side projects where you have total creative freedom.

This is about accepting and optimising for the way my brain works. Which is: it creates lots and lots of ideas at the start of a creative process. Here are some of the ideas I had for my synth:

  • adding harmonics by wave-folding
  • only using fixed-point arithmetic (inspired by early trackers and my general interest in retrocomputing)
  • using fast sine approximations
  • using sine lookup tables
  • stretched harmonics
  • harmonics detuned to simulate string mass
  • using Bezier curves as volume envelopes
  • doing additive synthesis by mixing together multiple instances of my basic instrument
  • doing additive synthesis by creating custom waveforms containing the desired harmonics
  • generating just intonated and 5-limit tunings
  • generating tunings from two overlapped harmonic series
  • generating 12-tone equal temperament and quarter-tone (24-tone) tunings mathematically
  • using the stuttering/echoing sound of buffer underruns as a musical effect
  • adding frequency modulation synthesis
  • having the synth be about a limited subset of sounds like bells, marimbas and bass
  • avoiding certain assumptions from the MIDI standard, e.g. removing note duration in favour of focusing on note onsets only (an idea influenced by my study of African-derived musics which have this emphasis)
  • using the synth in some kind of persistent, low-key online game as a way for players to leave melodies for each other to find
  • using rules to generate different melodies from the same basic info (say an array of integers), for example with different tunings or in different modes and scales
  • generating scales, chords and perhaps melodic cells or fragments geometrically, using relations I know from my study of music theory back in the day (e.g. a chord is every odd member of a scale is an approximation to 7 stacked fifths in a chromatic space generated using the twelfth root of two)
  • making an interface to expose these options interactively

And so on. The obvious common factor among all of these, I would say, is that there is no common factor. They are an extremely heterogenous bunch suggesting a whole lot of varied perspectives. Some are from a coder’s perspective (fixed-point calculation), some are about synthesising technique, some reflect my own limitations of ability, some are more like observations about the nature of music. Many have a distinctly contrarian flavour.

You can probably see the problem. There is no way to ever succeed at a project “defined by” such a list. And I’m not talking about success defined externally, but even just personal satisfaction. There are far too many requirements, many of which are contradictory.

The ideas there which are more rooted and achievable have another issue: they are technical challenges only, which makes them arbitrary. There’s no way to know if the solution arrived at is good, because there’s no agreed-upon way to measure performance. Should my bezier curve envelope allow two values for a given x input (which an unconstrained quadratic bezier can easily have), or forbid such curves? There’s no right answer because I haven’t defined what I’m trying to do.

This is in stark contrast to the school projects I’ve done for my higher diploma course: making a banking app, or an e-commerce website. Even if the work could get boring with those, the remit is clear and it’s satisfying when such a system comes together.

How did I manage to put a few weeks into my synth without realising that I hadn’t fixed upon a goal?

Or do I even need a goal? There’s nothing wrong with just fiddling about with stuff for fun, there’s even a fancy phrase to make it sound more official: “stochastic tinkering“. However, I know that I get my fun as a programmer in quite a specific way – by turning stuff that doesn’t work into stuff that does. When definitions are too loose, there’s no way to decide whether something works.

I’ve come up with a few pointers on how I might avoid this looseness in future.

The first is to design something conventional with a fictional, “normal” user in mind. This was how my school projects got done. This is good because convention (shopping carts in an e-commerce site, account selection in a banking site) guides you. This leverages the part of my mind that can’t stand to be wrong, and that likes tidying up: as long as the project fails to meet conventional expectations, I’ll be nettled into improving it.

However, finding the motivation to develop without the ego boost of originality would be hard for me. I know from the experience of finishing up my synth that work done just for the sake of appearing competent to strangers who come across my Github profile, isn’t very sustaining. The school projects had the virtue of being compulsory.

The second solution is to design something I’d like to use. This is… hard actually. It requires some self-awareness and honesty. I made a synth because I thought it’d be cool… or so I thought. Yet if I truly believed synths are cool, I’d probably have used one in the last few months; I haven’t done any synth-based music-making though in that time (despite having dozens of software synths installed on my computer). My conclusion is that I find synths to be a pleasantly intricate subject for mental distraction, but that I don’t actually have much desire to use them.

And similarly with the pixel art app I made before the synth. I like thinking about pixel patterns and generating them, yet if I liked making pixel art I’d be making some.

So, thinking honestly about one’s interests and requirements isn’t all that easy.

A third approach is to make something new, but very small. This worked well with something I made last year, an interactive sine wave visualiser. I actually made use of it, just for a second, while working on my synth to help me think about differentiating sines.

I’ve read advice to programmers about making tools that do one thing very well, and I can see the sense of it.

A fourth thing that has worked well for me is collaborating. When I’m working closely with others, my desire to appear right is a strong motivator. The hard part though for a side project is putting the energy into finding collaborators and the contradictory twin fears of not being good enough versus working with someone I feel is holding me back.

Those are actually familiar negative thoughts from my musician days.

Well, that’s what I wanted to write. Conclusion: even though my brain likes nothing better than lashing out idea after idea, finding the right one takes courage and deliberation. And it seems likely that good project ideas will combine a couple of the following: doing one thing only; being conventional; solving a real problem I have; being collaborations.

Harping On

I made an online toy in JavaScript, called TextHarp. Try it out (it needs a computer rather than a phone because it uses mouse movements).

The idea popped into my head a few weeks ago. It won’t leave the prototype stage because this combination of technologies – pure HTML, CSS and JS (although do I use one library to synthesise sounds) doesn’t robustly support what I wanted.

I aimed to turn a piece of text into an instrument, where moving the cursor over any letter which corresponds to a musical note – so, ‘c’, ‘d’, ‘e’, ‘f’, ‘g’, ‘a’, ‘b’ – would pluck the letter like the string of a harp, and play that note as a sound!

At the time, I was thinking of a few possibilities

  • adding audio feedback for testing web pages, so that a developer/designer could hear if an element was malformed or missing information (aspects which are often invisible to the eye)
  • sonification, a concept which I think is rapidly going out of date as people realise its enormous limitations, but which was about turning reams of data into continuous sound patterns that would somehow reveal something within the data, but which I think were usually just third-rate electronic music or else showed no more than a good graph could, and basically made clear that the humanities PhD system sucks in people who’d be better off elsewhere… sorry I seem to have gotten into a rant here
  • simple enrichment and adding magic to the experience of visiting a webpage

That last is out of favour for web design nowadays. Instead, minimalism, accessibility and function are the buzz words. Fair enough… but also ominously envisaging the web as merely where stressed and harried folk get updates from a corporate or government source, staring down at their little phone screen.

Well. My little toy isn’t going to do anything to overturn that paradigm. Still, let’s take a short tour of the challenges in making it work.

I used basic JavaScript mouse events to change elements in the webpage, modifying what’s called the Document Object Model; which is nothing more than how your browser perceives a page: as a hierarchy of bits containing other bits, any of which can be scripted to do stuff.

My script caused each paragraph to detect when the mouse was over it. Then it cut the paragraph into one-character chunks and placed each of these single letters into a <span></span> HTML tag, so that it became its own card-carrying member in the Document Object Model.

Not very elegant at all! Also, despite span tags being supposedly invisible, throwing in so many of them causes the paragraphs to twitch a little, expanding by a couple of pixels, which wouldn’t be good enough for a production page.

However, it works. I set each of the single-letter chunks to play a synthesized tone when the mouse goes over them, and that’s it. Also, when the mouse leaves that paragraph’s zone, I stitch the letters back together, the way it was.

The downsides are that any HTML tags used to format or structure the text tend to get damaged by the process. Usually resulting in piles of gibberish, or text disappearing cumulatively. It would be possible to improve that, but with a lot of manual work. And, the browser’s attempts to be clever by healing broken tags here actually cause a lot of difficulties.

Defining some new kind of object that held the text and knew the location of each letter, would be a better bet.

However, I’m turned off this avenue of enquiry for the moment, because dealing with audio in browsers is a pain. Not for the first time, musical and sensual uses of technology have been left in the gutter while visuals get all the investment.

There are two big problems with web audio. First, JavaScript doesn’t offer precise timing. I see precision, whether in first person computer games, input devices, or in this case reactivity of audio, as inherently empowering – inviting us as humans to raise our game and get skilled at something. Sadly, much of our most vaunted current technology crushes this human drive to excel and be stylish, with delays and imprecision: touchscreens, cloud services, bloated webpages…

Where was I? Yes, the second problem is that Google Chrome made it standard that web sites can’t play sound upon loading up, but only after the user interacts with them. Well meaning, but really shit for expressivity – and quite annoying to work around. My skillz are the main limitation of course, but even trying out two libraries meant to fix the issue, I couldn’t make my audio predictably avoid error messages or start up smoothly.

No tech company would forbid web pages from showing images until the user okays it. But sound is the second class citizen.

When I know my JS better, I’ll hopefully find a solution. But the sloppy timing issue is discouraging. Some demos of the library I used show that you can do some decent stuff, although the one I experimented with took a good idea – depict rhythm as a cycle – and managed to fluff it with two related interface gripes. They made the ‘swing’ setting adjustable for each bar of a multi-bar pattern – pointless and unmusical. And they made the sequencer switch from bar to bar along with the sound being played – theoretically simple and intuitive, but – especially with the above-mentioned time imprecision of web interfaces – actually resulting in loads of hits being clicked into the wrong bar. (And if I say a drum machine is hard to use, it probably is – I’ve spent so much time fooling around with software drum machines I ought to put it at the top of my CV.)

But what am I saying! That demo’s way more polished than mine.

Perhaps even a little too polished! Visually anyway. All of the examples on that site are rather slick and clean-looking, perhaps because, I believe, the whole library has some affiliation with Google.

Ah, I’m being a prick now and a jealous one too, but one scroll down that demos page would make any human sick. The clean grids. The bright colours. The intuitive visualisations – yes, technology now means that you too can learn music, it’s just a bit of fun! Practice, time feel, listening, gear, human presence – nah!! And then the serious, authoritative projects – generated-looking greyscale, science-y formal patterns and data…. bleh.

My next JavaScript project is an exploration of a visual style which I explicitly intend to raise a middle finger to those kind of polished, bland graphics. I’ll be taking lessons from my 90s/00s gaming past to experiment with pixel art but without the hammed-up console-nostalgia cutesiness.

And I’ll be using standard web technologies – JS, SVG – to make anything I come up with 100% reusable by non-programmers.

Thanks for reading!

Postmortem for my First App

Three and a half months ago I started a software development course, to build a new career as a programmer. I’ve also quit playing music. As we come to the start of a new year I’m very happy with these choices and with the prospects ahead.

One of the things I’ve loved for a long time about programming was the culture of sharing knowledge. It directly influenced the tone of this blog. So, while I don’t know whether I’ll continue writing about programming on Drum Chant or make a new blog for it, today I want to try my hand here anyway at a software postmortem.

Following the time-honoured format (which I first saw on gamasutra.org I think, and also used on this blog before), I’ll introduce my project, discuss what went right in the production, what went wrong, and what lessons can be learned about software development.

Introduction

I developed my first app in Java this month. It’s a number-guessing game simulating a lottery draw. I call it Gambler’s Delight. I had previously worked on a similar brief for a group project in school which I enjoyed enormously. So I decided to remake that idea on my own, using a more elegant, manageable design.

The game affords multiple rounds of attempts to win the lottery. In each round the user fills out a lottery ticket of 1-3 lines, where each line is a guess at the 6 random lottery numbers which will be drawn. When the user decides to play their ticket, the application draws the 6 random numbers and tells the player how good their guesses were, awarding fictional cash prizes depending on performance. Finally, the app keeps a record of all the rounds played and displays this when the user requests to end the play session.

So, it’s rather like the Irish National Lottery‘s digital play platform. I didn’t refer to this when designing my game, but my effort converges on the same concepts.

How the pros did it

You may be already seeing some of the design issues I faced:

  • how to make sure the player chooses six unique numbers
  • how to have automatically chosen (“quick pick”) numbers
  • given that some lines are active and ready to play, some not, how to deal with the transitions from inactive to active and back

My own learning goals for the project were to get my head around Java’s Swing library, which provides platform-independent graphical user interface (GUI) widgets, as well as some intermediate programming concepts like interfaces, events, exceptions, and of course the object-oriented programming principles of encapsulation, inheritance and abstraction. (The fourth technique always mentioned with that group, polymorphism, didn’t really come into my app.)

Or, to put it crudely, I wanted to make a simple game but:

  • split it out intelligibly into classes representing real-world objects,
  • use the premade Swing classes more or less as they’re meant to be used, and
  • keep a handle on the structure and proliferation of my code.

What Went Right

A clean GUI: I designed the look of my program in one blast of inspiration, which luckily was then realisable in one of Swing’s layout manager classes, the euphoniously named GridBagLayout.

I decided that each line of 6 numbers would be built as 6 text fields, similar to a licence key or credit card number entry form. And I was able to have all necessary user actions available on this one, small window, in a layout based on the number 3.

The concept ((also demonstrating the importance of having appropriate stationery on hand 🙂 )
My GUI in action

Encapsulation: as you can see in the source code, I split the functionality of my game into 9 classes and and an interface. Many of these are satisfactorily neat and conceptually self-contained. Even the bigger ones use some basic principles to hide their data, i.e. private variables. Also, I followed the correct convention for passing arrays – copying their contents into a new array before passing that – to avoid giving the requesting class access to a private array in cases where this matters, e.g. the LottoTicket’s getResults() method.

Keeping control of my code: I was pleased that by the end of this project, I still knew clearly what everything did and where to look for any particular functionality. I could skim my code and know what I was looking at thanks to nice variable and method names, whitespace and my reasonably clear class structure. I’m an ultra verbal thinker so writing lines like “history.updateWith(ticket.getResults());” that do what they sound like they do in approximately readable English, pleases me no end.

Use of Java classes: the built-in classes I used – probably around 12 or so – were rewarding to study and build around. Of course they are, they’re made by top people! The experience of using things like Swing’s InputVerifier or Container classes, say, is of initial simplicity giving way to great depth and flexibility. The big but logical inheritance hierarchies of these components are inspiring. I’d love to make something someday as worked-out and usable as these. The only downside of my plug-and-play approach is that I ended up using a good few classes quite superficially. I can see how later it’d be all about digging down deeper and overriding parts of fundamental classes to put my desired custom behaviours in more unified containers that match their purpose more elegantly.

Use of events: I used a good few of Java’s event types and wrote one of my own, so now I have at least some insight into event-driven programming.

Bullet-proof UX and validation: I’m proud of this achievement even though conceptually, behind the scenes, it could’ve been cleaner. My interface instantaneously reacts to invalid input with an appropriate error message and an updated count of how many lines are ready to be played. The only exception is, I allow the user to leave fields blank for smoother navigation. It’s impossible to leave an unplayable input in a field, and impossible to play a line that doesn’t validate correctly (e.g. has blanks). There are two subtleties to this. First, I had to use multiple kinds of events to make sure and cover all interactions: DocumentEvents, FocusEvents, ActionEvents… and then pass the appropriate EventListener classes back and forth when building all the objects (lines, fields, verifiers) in my game. That’s overly complex for sure. On the plus side, I had to take care of weird player behaviour like going back and deleting numbers from previously finished lines. That involves some slightly tedious code but the result is robust.

Minimising hardcoding: I kept crucial gameplay variables in a separate LottoRules class and made sure that they only need to be changed once to correctly change the game’s behaviour. However, I chickened out of following this to its proper conclusion of allowing customisable line lengths and number of lines per ticket – the game logic can handle this, but the user interface wouldn’t dynamically adjust.

What Went Wrong

Having no target audience: the game was inspired by a brief for a college project. It doesn’t fulfill any real user’s needs and therefore there’s no point continuing to develop it. Honing in on excellent design becomes arbitrary in this situation. For my next project I’ll come up with something that I, and hopefully many people, definitely want.

Insufficient use of exceptions and defensive programming tactics: changes in one part of the code could easily cause crashes or undetermined behaviour because I don’t check the validity of values or handle wrong values (apart from the user input discussed above). That said, I think I’m right to move on without polishing this more.

Hardcoding: this point also contravenes good programming practice. The UI I made isn’t adaptable to different line lengths/amounts, and has some per-pixel hardcoding. But here I was coming up against the fact that system-independent GUI design is hard. Java’s Swing layout managers are pretty flexible and wide-ranging, but with that comes a lack of predictability and precision. I think next time I might try a different GUI technology – AWT, or something web-based – just to keep learning new stuff.

Lack of reusability: although I made one class explicitly for future use, (TextNiceties which deals with plurals and counting words) I mostly failed at designing for reuse which is, so my software engineering teacher says, the holy grail. Partly this is due to the trivial but finicky task: much of what I wrote is for the necessities of this particular game. Then there was the spreading of GUI code throughout my classes, which I’ll discuss below, but which obviously makes my code specific to one task.

Refactoring is hard: “restructuring existing computer code—changing the factoring—without changing its external behavior” as Wikipedia defines it, was challenging. I already had a working prototype at the start of this project, from my school group work. Unfortunately I tended to unthinkingly take elements of the previous design into my new one. And I also assumed that problems were already solved without noticing that with changed design assumptions, my previous techniques were now invalid. So, I made two failed attempts at restructuring my GUI code before settling on a pattern of passing a window (JFrame) object into my various classes so they could paint themselves onto it.

Deciding what object should have what responsibilities: I had the concept of an overarching “app” creating a lotto “ticket” containing “lines” which each contained number “fields”. Reasonable enough, but the question of which object should know about which other objects was hard! This applied to the UI creation, the validation, and the game state changes… I have tons to learn here.

Over-engineered interface: I allowed the user to invalidate a completed line of numbers by clearing text fields. This adds nothing, it’s merely a standard text input convention. I think an excellent design would intentionally limit such possibilities in the interests of clarity and simplicity. I note that the Irish National Lottery interface:

  • uses a graphical grid of numbers that are either selected by a single left click, eliminating duplicates automatically
  • doesn’t allow deselection (deletion) of numbers, so lines are simply always valid once completed – and bright colours are used to indicate the change to valid
  • therefore never has e.g. the first line invalid while subsequent ones are playable, an edge case I had to write a fair bit of overly-involved code to deal with

Conclusion

I’ll stop there. That’s a lot of chat about a learning project, but hey I’m proud of it and I sank a few days into it. Nice one if you read through it all and perhaps I’ll be back soon with a cooler project. A friend of mine gave me the idea of doing something that queries a web API, and I also think I want to do something with non-trivial calculations (maybe some geometry/graphics) and file handling.

*EDIT* Oh, one last addition – I think I know now what the solution is for organising the line, field and ticket objects and their drawing code. Sticking closer to the paradigm from John P. Russell’s excellent beginners Java book, I would go back to having each major element subclass a Swing component such as a JPanel, and draw itself in its constructor. And, I would structure the lines like a group of radio buttons: first a LottoLine would be created, and it would be passed into the constructor of all its LottoFields.

Ah well, there’s always more improvements to make. Still happy to draw a line under this project, cause it works and the code is readable.