For the past few years, I’ve prototyped a REPL for synth sounds and pattern playback and want to document things before I forget where I’ve been while talking about where I’m going.

A buddy of mine was listening to me rant about my work and invented the name “Rototem” that’s evocative of a tower with spinning things on it. This conceptually matches what I want to make and use… a funny hybrid between a CLI for sound with a pattern player included.

Rototem was a proof of concept of this using AMY as the sound back-end and a REPL of my creation, and an expansion of AMY’s “wire protocol”.

I’ve made several videos of me playing with this at YouTube

Intro

zoe is a simple C library that allows you to access a zip file that has been appended to an executable. This means that your binary can include all the files it needs to function, without needing to rely on external files or archives. And because the zip file is appended to the end of the executable, it’s all contained within a single file. Underneath zoe is the wonderful miniz library should you need to perform more technical zip file work.

For my first use case, I created zoe to help me package sound performance and audio samples with my rototem sound tool. Using zoe, rototem can now find and read the files contained within the appended zip file, without needing to reference any external file. This made it much easier to distribute the rototem, as I only needed to send a single file.

But the usefulness of zoe doesn’t stop there. Because the zip file is attached to the executable, you can use command-line utilities like the zip tool to add, remove, or update the files within the archive. This makes it easy to keep your files up-to-date, and allows users of the binary to do so themselves.

Library overview

Here’s a run-down of the zoe library’s functions:

char *zoe_self(char *exename);
zoe_t *zoe_open(char *zipname);
void zoe_close(zoe_t *zoe);
int zoe_files(zoe_t *zoe);
char *zoe_name_at(zoe_t *zoe, int i);
int zoe_find(zoe_t *zoe, char *name);
zoe_file_t *zoe_fopen_at(zoe_t *zoe, int i);
void zoe_fclose(zoe_file_t *zfile);
#define ZOE_FILE(z) (z->mem)

• zoe_self resolves a full pathname to the exename provided. This enables zoe to open the attached zip file regardless of where it’s located and without troubles due to symbolic filesystem links.
• zoe_open finds the appended zip file and returns a zoe_t structure, which is used for further operations.
• zoe_close frees any allocations created by zoe_open.
• zoe_files returns the number of files in the appended zip file.
• zoe_name_at returns the filename using an index number (0 to the number returned from zoe_files()-1).
• zoe_find returns the index of a file with the given name, or -1 if not found.
• zoe_fopen_at opens a file in the appended zip using an index number and returns a zoe_file_t structure that contains a FILE pointer that can be used with the C buffered I/O library, along with the provided ZOE_FILE macro.
• zoe_fclose closes the file opened by zoe_fopen_at.

Usage

Using zoe is straightforward. Simply call zoe_open with a full path to your executable), and zoe will validate and open the appended zip file. You can then use the other functions to retrieve information about the files in the archive, or to open and read the files themselves.

Clone zoe and build it like this

git clone https://github.com/octetta/zoe.git
pushd zoe; make; popd

Create example.c for learning like

// example.c
#include <stdio.h>
#include "zoe/zoe.h"
int main(int argc, char *argv[]) {
    zoe_t *z = zoe_open(zoe_self(argv[0]));
    int n = zoe_files(z);
    printf("%d files in %s\n", n, argv[0]);
    for (int i=0; i<n; i++)
        printf("#%d -> %s\n", i, zoe_name_at(z, i));
    zoe_close(z);
    return 0;
}

Build and run the example without any attached zip file like

$ gcc example.c zoe/libzoe.a -o example
$ ./example
0 files in ./example

Add a starting .zip file like

$ echo "this is the first archive file" > first
$ zip first.zip first
  adding: first (deflated 6%)
$ cat example first.zip > example.zip
$ chmod +x example.zip
$ ./example.zip
1 files in ./example.zip
#0 -> first (size:31)

Add new file to the example.zip binary like

$ zip -A example.zip example.c
Zip entry offsets appear off by 113576 bytes - correcting...
  adding: example.c (deflated 40%)
$ ./example.zip
2 files in ./example.zip
#0 -> first (size:31)
#1 -> example.c (size:358)

Update an existing file in example.zip like

$ echo "updating the first archive file" > first
$ zip -A example.zip first
Zip entry offsets do not need adjusting
updating: first (deflated 3%)
$ ./example.zip
2 files in ./example.zip
#0 -> first (size:32)
#1 -> example.c (size:358)

Remove a file from example.zip like

$ zip -A -d example.zip example.c
Zip entry offsets do not need adjusting
deleting: example.c
$ ./example.zip
1 files in ./example.zip
#0 -> first (size:32)

Where to find out more about zoe

zoe is on my GitHub page at https://github.com/octetta/zoe.git .

If you want to discuss zoe, DISCORD INFO HERE.

Wrapping up

Overall, I’m happy with the results of my work on zoe. It’s a lightweight and versatile library that has already made my life much easier.

If you’re looking for a way to package files with your executable I highly recommend giving zoe a try.

If you remember from the article Elixir + AMY = BEEP!, I made a CLI tool to use for learning AMY’s wire protocol that lets you type in a string, hit enter, and have AMY make sound from that string.

That CLI tool was using C’s standard I/O library, which if you didn’t already know, doesn’t have cursor handling or text editing abilities at all.

In the open source world, the well-known option to enable editing is GNU Readline, which is perfectly capable, but as is with many GNU libraries, is a bit large for what it does.

Another option is antirez’ linenoise library, which in character for many things antirez has created is minimal, and beautiful.

The option I wound up working with is jart’s bestline library, which is inspired by anterez’ but with jart’s extraordinary eye for completeness and minimal resulting binary size.

There’s not much to say with regards to how I use bestline in my code, as it’s a straightforward pattern like this:

#include <stdio.h>
#include "bestline.h"
int main(int argc, char *argv[]) {
    char *l;
    while (1) {
        l = bestline("r> ");
        if (l == NULL) break;
        printf("YOU TYPED -> %s\n", l);
        free(l);
    }
    return 0;
}

It’s notable that this pattern, at least in single process / single-threaded programs, means the code it’s linked with can’t respond to events while it’s in the bestline function.

I chatted with jart about this and she suggested an elegant way to add this functionality to bestline that would allow appearingly parallel functions, but in the end I chose to add a function pointer / callback style to allow use of a custom read function that’s responsible for demultiplexing input.

The new function I added to bestline is:

void bestlineUserIO(void *userReadFn, void *userWriteFn, void *userPollFn);

Which gives you hooks into the read, write, and poll functions used by bestline.

I added a demo of this in the bestline codebase called multi.c which multiplexes console input with a UDP socket listener by replacing the userReadFn with my custom version wherein I use the poll function.

Check it out if you have similar needs.

You can read about that here, but as a short recap, Ports allow Elixir to run and talk to external programs such as amy-message through standard input and output channels.

With a Port created as p, this code:

send(p, {self(), {:command, "v5w7p60"}})

..will write v5w7p60 to the input channel of amy-message.

This week, I’ll focus on getting responses from amy-message that we can use in our code.

The Port module uses Elixir’s mailboxes to communicate with programs it starts. This was demonstrated in the use of the send function above.

To get something back from a Port, we need to use the complimentary receive function, as:

iex(9)> r = receive do msg -> msg end
{#Port<0.6>, {:data, ": "}}

In this example, the resulting r is a tuple containing values telling us where the message came from and a tuple containing an atom :data and the actual data ": " sent by amy-message.

We can use pattern-matching to extract the actual data from this tuple like:

iex(10)> {_, {:data, s}} = r
{#Port<0.6>, {:data, ": "}}
iex(11)> s
": "

FYI, s contains ": ", which is the prompt string amy-message wrote to indicate it’s waiting for a new incoming command string.

There’s one thing to be cautious about with receive though. If for some reason amy-message doesn’t send a response, receive will wait forever for a response, making Elixir’s iex appear to lock up (although the BEAM-VM is actually running just fine).

To safeguard against this, use after with the receive function and specify the number of milliseconds to wait for a message, like this:

iex(12)> r = receive do msg -> msg after 1_000 -> :timeout end
:timeout

…here we see the :timeout atom was returned after 1,000 milliseconds of nothing in the mailbox.

To make the timeout condition easier to work with, change the return structure to mimic a normal mailbox message by returning a tuple containing a :timeout atom and an empty string:

iex(13)> r = receive do msg -> msg after 1_000 -> {self(), {:timeout, ""}} end
{#PID<0.108.0>, {:timeout, ""}}
iex(14)> {_, {_, s}} = r                                                      
{#PID<0.108.0>, {:timeout, ""}}
iex(15)> s
""

Now that we have these basic elements in place, more complex interactions with amy-message are possible.

A simple example would be to ask amy-message for its sysclock ( the number of milliseconds the AMY sound engine has been running) by sending @c, then capturing the response:

iex(3)> send(p, {self(), {:command, "@c"}})                                  
{#PID<0.108.0>, {:command, "@c"}}
iex(4)> r = receive do msg -> msg after 1_000 -> {self(), {:timeout, ""}} end
{#Port<0.7>, {:data, "13531\n: "}}
iex(5)> {_, {:data, s}} = r
{#Port<0.7>, {:data, "13531\n: "}}

There’s a little more work to do, as s contains two lines of text: the sysclock number as a string, a return character \n, and the prompt character.

We handle this by splitting s into an array a, using "\n" to signal what to split on:

iex(18)> a = String.split(s, "\n")
["13531", ": "]

Then convert the sysclock element of a into a number using a pipeline:

iex(21)> sysclock = a |> Enum.at(0) |> String.to_integer
13531

Now sysclock is a number where can perform math functions.

Knowing sysclock inside a running AMY engine will be useful as a way to synchronize audio and events with AMY engines running on other devices.

We now have the basic structure for interacting with things started with the Port module!

One last thing to show is how to stop amy-message in a controlled manner:

send(p, {self(), {:command, ":q"}})

…upon which, no trace should be left running.

You can verify this by:

pgrep -laf amy-message

I think we’ve covered enough for now, I certainly had to refer to the Elixir documents here to write this and hope it was useful for you.

Next time, I’ll present a module to simplify these interactions and show a very simple event sequencer.

Until then, enjoy a few live-coding sessions showing new features I’ve added to the AMY codebase:

Capture a PCM patch, modify it, and store to a user PCM patch…

Wave sequencing and the resonant low-pass filter…

I saw an interesting project called AMY on Hacker News for sound generation (which has NOTHING to do with Elixir, BTW).

AMY provides a software audio synthesizer with 64 simultaneous “voices” (aka oscillators) that can generate sound via several different methods:

• Periodic pure waveforms
• Short audio samples
• FM/DX7 style synthesizer patches
• Cool stuff I don’t quite understand yet with “partials”

For more details, the AMY github project is at github and has all the details.

AMY’s authors ( Brian Whitman and DAn Ellis ) use it for another interesting project called the Alles mesh synthesizer .

AMY and Alles are loving nods to sound experiments of the past, one of which I’d heard about (Atari’s 1980’s AMY sound chip ) and the other I’d not (Hal Alles’ 1970’s Bell Labs Digital Synthesizer ), but apparently the Atari AMY chip was inspired by the Alles synthesizer.

While Brian’s and DAn’s projects aren’t direct copies of their namesakes, the inspiration is evident the more I learn.

Anyway, after playing with AMY (the software package) for several days, I wanted to get back to the Elixir part of this project, and thought it would be interesting to connect the two.

Looking at the existing AMY code, there are three obvious methods that Elixir might be able to use for control.

• A standalone test tool using the C-API that generates three tones using data structures and function calls.
• A WASM module with the entire C-API, used by their demo webpage.
• A Python module with wrappers for the C-API.

None of these methods quite fit my mental picture, with the closest being the Python module.

This was slightly more complicated than I wanted however, and would require me to write data structure conversion and method invocation code.

Rather, I wanted something that was somewhat like a black-box, kind of how the POKEY chip of the Atari 400 or SID chip of the Commodore 64 worked:

Joe in 1981

Joe in 1982

Joe in 2023

One enticing option the API exposes is a function for what they call a “wire protocol” that doesn’t require sharing complex data structures or functions.

The wire protocol uses short ASCII strings to control AMY, which the authors describe as a way to “make using AMY from any sort of environment as easy as possible”.

Wire protocol messages are handled via a function named amy_play_message that accepts a char * parameter.

Seems like this was exactly the magic dust I was looking for!

Using this, my strategy is to create a standalone binary to pass wire protocol via standard input into the amy_play_message function.

I contributed the amy-message code to the AMY github codebase and have been using it to learn the protocol and the behavior of AMY’s voices.

I have an uncommited change that enables command-line history and editing when amy-message is run from a shell; reach out if you’d like more details.

Another rationale for creating amy-message was to use it as a “port driver” inside Elixir.

Port drivers are discussed at hex.pm, but the short version is Elixir runs an external program uses stdin/stdout as a communication channel.

Port drivers provide a relatively safe way to extend Elixir functionality without introducing unsafe code into Elixir’s BEAM VM.

Since AMY and the associated sound libraries start threads and have some amount of dynamic memory allocation that might be “dangerous”, I feel better about isolating things in a child process to keep BEAM safe.

With this work in place, it’s just a matter of putting the amy-message binary somewhere Elixir can find it, and sending wire procotol strings through Port functions.

• Here’s a summary of use

Port.open({:spawn, "./amy-message -l"}, [:binary])
flush() # see the available audio backends
p = Port.open({:spawn, "./amy-message -d 0"}, [:binary])
send(p, {self(), {:command, "v5w7p60"}})  # set osc5 to PCM "bird" patch
send(p, {self(), {:command, "v5l1"}})  # play osc5

• Here’s a video of me building and running it…

• Here’s a hastily written web app inspired from an AMY example to try the wire protocol.

• Joe’s AMY explorer

After all this, it might seem like very little Elixir learning happened, which is kind of true, but this is organically growing towards an audio project for Elixir I hope to write more of and about.

So stay tuned…

Notes:

AMY currently runs on Windows, macOS, and Linux systems (including Raspberry Pi’s), so this same approach should work equally well on these platforms. I’ve mostly run on x86_64 Linux, but lightly tested on macOS and a Raspberry Pi 3B.

AMY also targets ESP32 and other minimal horsepower platforms. It’s conceivable that a variation of the port example above could send wire protocol via UART or Bluetooth, or something else.

Links:

• Brian Whitman’s web AMY example
• Interview with an Atari AMY chip developer Tom Zimmerman
• Laurie Spiegel playing a Alles synthesizer in 1977
• Judy Jackson playing a Alles synthesizer in 2016

I won’t try to justify the exact reasons why I’m not using WP, but instead will list what I wanted:

• Native use of Markdown
• Static rendering of the site
• Easy to backup to github
• Preprocessors for code highlighting and text-as-diagrams

I tried several based on Rust, Go, and even Elixir, but wound up choosing the Ruby tool Jekyll.

One talk I was super excited to attend was Forrest M. Mims III’s but realized at the last minute that it overlapped a builder session I’d already paid to attend.

If you don’t know the name, he’s pretty much a hero in the hobby electronics world. He had a monthly column in one of the magazines I treasured in the 70’s (Popular Electronics) in addition a whole series of books and kits sold at Radio Shack.

His books have this distinct hand-written style:

(snipped from his book Getting Started in Electronics)

Back to the Moogfest part of this, I snuck out of the builder session to see if I could sneak a peek at the beginning of his talk and to my surprise, he was standing outside the venue waiting to get set up.

He was super nice and chatty.

Apparently his wife Minnie is his “official” photographer and she volunteered to take this picture of us.

He’s still active with atmospheric observations on his Facebook page.

scp A-FILE $HOST:
Unable to negotiate with $HOST port 22:
  no matching host key type found. Their offer: ssh-rsa,ssh-dss

A bit of googling showed other folks having the same problem fixed it the following way:

• Add these lines at the top of .ssh/config

HostKeyAlgorithms ssh-rsa
PubkeyAcceptedKeyTypes ssh-rsa

• For each host in .ssh/config that complains when you ssh or scp:

host $HOST
    hostname $HOST.com
    user $USER
    HostKeyAlgorithms +ssh-rsa,ssh-dss

In first session (this will be the server):

iex(1)> {:ok, socket} = :gen_tcp.listen(3000, [:binary, active: false])
{:ok, #Port<0.6>}
iex(2)> {:ok, data} = :gen_tcp.recv(socket, 0)

From the second session:

iex(1)> {:ok, server} = :gen_tcp.connect({0,0,0,0}, 3000, [])
{:ok, #Port<0.6>}
iex(2)> :gen_tcp.send(server, "hello")
:ok

Back in the first session:

iex(3)> {:ok, data} = :gen_tcp.recv(client, 0) 
{:ok, "hello"}

In first session (this will be the server):

iex(1)> {:ok, socket} = :gen_udp.open(3000, [:binary , active: false])
{:ok, #Port<0.7>}

From the second session:

iex(4)> {:ok, socket} = :gen_udp.open(3001)
{:ok, #Port<0.8>}
iex(5)> :gen_udp.send(socket, {0,0,0,0}, 3000, "yo")
:ok

Back in the first session:

iex(4)> {:ok, data} = :gen_udp.recv(socket, 0)
{:ok, { {127, 0, 0, 1}, 3001, "yo"} }