jaxter184

Monthly Log 2025

Unknown — Wed, 26 Feb 2025 00:00:00 +0000

01 - January

Learned to play the first bit of Verrat on the HXCSTR (the piano part in the first 20 seconds). Surprisingly easy! The rest has been much harder. TODO: upload a quick video
Started working with a designer to make crofu look less ugly. Their current progress is available at https://ghostcatte.codeberg.page/crofu-design/
Started working on updating knus (forked from the unmaintained knuffel) to KDL 2.0. Keep up with my progress here. I've still got a long way to go, but a lot of the "main" features are implemented (bare identifier string arguments, new keywords). I'm still a bit bummed that the proposal to remove / from reserved identifier characters didn't pan out, but such is life.
tlature (apparently people pronounce it as "lature" when I format it as ↹lature)
- Bumped kdl dependency to 6.0.0 (implementing KDL 2.0)
- Lots of refactoring, as usual
- Added some audio and event metering functionality
- Added a plugin logger view
- Wrote my first proc macro to make a "splittable" trait derive that implements a trait allowing a structure to be split into main and audio thread versions.

02 - February

Been exploring a game concept for a turn-based tower defence. Explored a couple different game engines because I was tired of bevy compile times. Ended up settling on macroquad. Revived tacticum because it seemed to be a good fit.
more crofu legal studying
built a cheese press
made pho and kkwabaegi
got a bowl at a local makers market

Making crofu

Unknown — Wed, 25 Dec 2024 00:00:00 +0000

crofu is a platform designed to test out incremental converse crowdfunding.

Databases

Databases have been a new thing that I've had to learn for crofu. I've got a lot of experience in static webdev (mostly from this wiki), but I wasn't able to think of a good way to implement crofu as a static site. It seemed like even the very bare minimum implementation of crofu would require a web API backed by some sort of database.

On the other hand, making the decision to just make a dynamic website has saved me a lot of weird mental gymnastics I otherwise would've had to do. Accounts and login? Just stick em in the database. Fediverse integration? Database. How do I securely generate page layouts? Load from the database client-side. API? Just a thin wrapper around the database. I can see now why web developers are the way they are: everything is just so easy when you give up on performance and simplicity.

Right now, I'm using Postgres. I don't remember why, I think someone just recommended it at some point and I just haven't run into any issues with it. Some aspects of SurrealDB seemed cool, but I really don't trust the project, and it seems like it would've been a hassle to use.

NOTE: everything below this line is outdated. I'm now using axum.

Web development has historically disgusted me. So many frameworks, so much cruft spread across various W3C standards, so much to know about, and an unappealing problem space. That, combined with cultural elements of corporate minimalism, the rise of Elektron-based webapps, and the infamous "move fast, break things" approach have kept me mostly in the realm of desktop and embedded software. Which isn't to say I've never made a website. In fact, some of the earliest software I've ever made were websites (the actual earliest are probably games, but the timeline is hazy and the definition can sometimes be blurry).

One of the projects that's been on my frontburner recently is incremental converse crowdfunding. This is one of the few projects I've worked on that practically requires a dynamic website. I considered implementing it with email, or ActivityPub, or a TUI that connects to a REST backend, but while none of those would require a web frontend, I think it would be a challenge to make them comfortable for a non-technical audience to use, and since I have to use web technologies anyway, might as well just make a regular website.

I've been putting off actually working on it, out of a fear of certificate authorities, nginx, DDOS attacks, authentication (especially password storage), and handling money, just to name the big ones. But a friend recently made a website where he plans to sell software directly to his customers (rather than through Gumroad, which is what he currently uses). Software politics aside, it was interesting to me that he was doing this because it seemed pretty slick, and he seemed to lack the fear that I had with my own website. I assumed this was based on the fact that he was using a bunch of existing services and frameworks, and the part of his stack that caught my attention was Supabase. I eventually realized that it didn't actually solve most of the more prominent issues I was worried about, but at the time, the particular features of Supabase that seemed appealing to me were that it handled authentication, had a free tier, and was self-hostable.

Currently, I use Rocket for my entire stack. I initially started with Yew, before realizing that it's intended for frontends. I might return to it later if I figure out that the frontend is actually something where I need to have a lot of dynamic stuff going on, because under no condition am I going to write any JavaScript or TypeScript.

Without a cloud service like Supabase, my options are pretty limited. Either I can roll my own authentication (almost certainly a bad idea, if years of pwns are any indicator), or I can hook into an existing website's authentication, through something like OAuth. One such standard that came up in my research was IndieAuth, which, as I understand it, runs on top of OAuth to log people into sites using their logins from, for example, their social media accounts. This is an improvement from OpenID Connect, which requires each website to explicitly allow logins from each provider it chooses to support. Twitter used to support it, but after the API closures, it no longer works. There are some smaller tools listed on the IndieAuth website, including a plugin for WordPress, but the biggest IndieAuth provider is probably GitHub. I think moving forward, Fediverse projects will probably start to support it, but right now, support for IndieAuth is pretty sparse. That being said, it seems to be my best option at the moment.

to be continued

🏮 PS06 - Impulse Regulator

Unknown — Sat, 14 Dec 2024 00:00:00 +0000

I've almost certainly forgotten something, so feel free to email me for clarification (or if you want me to build you something): [email protected]?subject=Shiny%20Cube%20Sculpture">[email protected]

Build guide

Laser cut 3mm clear acrylic

Export the laser cutting files from 06-panel.FCStd
- Select the Page in the tree view
- File -> Export (Ctrl+E)
- Filetype: Technical Drawing (*.svg)
- Save
Might need to be manually cleaned up
6 pieces
Thanks to the friends who let me borrow their laser cutter

One-way tint film

This particular product was shipped without a cardboard roll, or any outside protection, so there were some scuffs and wrinkles
Is often adhesive backed, even if it doesn't seem like it
Spritz down some water while applying, it makes bubbles easier to move, and doesn't affect the adhesive as far as I can tell
Apply to acrylic a bit too large, then cut away the excess
The holes are a little weird, but you can just roughly cut inside them with a craft knife

3D-printed corner brackets

Export from 06-corner.FCStd
Print with the inner side down, outer corner facing up
Get the ethernet hole version by setting the tip to Pocket008 (in the treeview right click menu as Set tip)
May need to use a drill to clean up the holes depending on your printer
I used PETG, but most "regular" materials are probably fine

Bits and bobs

Ethernet keystone jack
LED Ring (80mm outer diameter)
T Plates
M3*8mm machine screws (to attach panels to corners)
M5*8mm machine screws (for aluminum extrusion)
M3 eye bolts
M3*OD5mm*6mm Heat-set inserts
M3 and M5 Slot T-nuts
2mm*125mm Steel rods
ID80mm*100mm Acrylic tube
- TODO: drilling procedure
0.5mm cable
Cable clamps (I just bought the smallest ones I could find)
- I also used crimp-style ones, but they require a special tool, so if you're just doing a one-off, it's probably better to just use the screw-style ones
Aluminum extrusion
- TODO: lengths

TODO: document electrical crimes

December Adventure 2024

Unknown — Sun, 01 Dec 2024 00:00:00 +0000

Time for my second annual December Adventure!

Last year, I did some work on ↹lature, and I learned a lot about which parts of December Adventure work for me (and which don't). I go over why I enjoy December Adventure so much in the "retrospective" section of the article, but in short, I think the main benefits are feeling free to spend as little time as you want on it (as long as you do something) and having the flexibility to go in whatever direction you feel motivated to go.

I encourage y'all to check out other participants as well! There's a pretty comprehensive list at https://eli.li/december-adventure#section, and the #DecemberAdventure hashtag is usually pretty busy this time of year (mostly on the Fediverse, but maybe BlueSky has some going on too?).

This year, my project is:

crofu - Incremental converse crowdfunding platform

In short, crofu is a weird crowdfunding platform I've been working on for the last two months (and ideating for the last two years), and it happens to be the project I have the most momentum on right now. While it would be cool to work on ↹lature again, I think it would be really good synergy to use ↹lature development as a proof-of-concept/dogfooding opportunity for crofu, so I'm trying to work to get crofu in at least a testable state before I move on to more ↹lature stuff.

Day 1

I forgot December Adventure was starting until like the night before the first, so I was in the middle of a refactor. I was gonna finish it up today, but I got distracted with some type safety improvements around IDs. Pretty much everything in the database (Profiles, projects, tasks) is indexed by a UUID, and I want to prevent myself from using the wrong UUID in the wrong situation, so I wrapped each of them with a distinct type (for example: struct IdProject(uuid::Uuid)) and impl'd a bunch of traits for them using a macro.

macro_rules! id_type {
	($name:ident) => {
		#[derive(sqlx::Type, serde::Serialize)]
		// This lets me use this type directly when interfacing with `sqlx`
		// instead of having to unwrap it with `id.0` every time
		#[sqlx(transparent)]
		#[derive(Debug, Clone, Copy, PartialEq, Eq)]
		pub struct $name(Uuid);

		// This is necessary beacuse I use the id sometimes when generating HTML, mostly in forms.
		impl std::fmt::Display for $name {
			fn fmt<'a>(&self, f: &mut std::fmt::Formatter<'a>) -> Result<(), std::fmt::Error> {
				write!(f, "{}", self.0)
			}
		}

		impl From<Uuid> for $name {
			fn from(uuid: Uuid) -> Self {
				Self(uuid)
			}
		}

		impl From<$name> for Uuid {
			fn from(id: $name) -> Uuid {
				id.0
			}
		}

		// these let me check for equality between this wrapper type and a bare UUID
		impl PartialEq<Uuid> for $name {
			fn eq(&self, uuid: &Uuid) -> bool {
				self.0 == *uuid
			}
		}

		impl PartialEq<$name> for Uuid {
			fn eq(&self, id: &$name) -> bool {
				*self == id.0
			}
		}
	}
}

pub(crate) use id_type;

A fairly modest start to my December Adventure, but a good start nonetheless!

Day 2

Finished up the refactor I mentioned yesterday. The basic idea was to make accessing the database a little more ergonomic: instead of big methods like database.get_tasks_by_project_id(project_id) and database.edit_project_by_id(project_id, edits), I'd instead call database.project(project_id).tasks() and database.project(project_id).edit(edits). This not only makes it clearer what table is being edited, but also makes naming functions a lot easier.

One of the things I didn't really concern myself with was dealing with indexing based on slugs (for example, when using a URL endpoint like crofu.net/my-profile/a-project and performing some operation on the corresponding project (usually getting info), but using the slug (a-project in this case) since it doesn't have access to the UUID. The way I have it now, I'm just using the old method of having a top-level database.get_project_by_slug() method, but I think I might have a database.project_by_slug(project_slug) that returns the same thing as database.project(project_id).

Day 3

Spent the evening doing some CSS and layout improvements, mostly around the pledge editing box. My two main inspirations when it comes to website style are https://sr.ht and https://comradery.co, and it really shows. I'm not too worried about aesthetics or anything, and the only goal right now is to make it clear how to use the website. As a result, I don't have much to say about it, but here's a screenshot:

Hopefully it's obvious which parts of the page do what.

Day 4

Today was mostly a cleanup day:

Fixed an issue where /foo resolves correctly, but /foo/ does not
Fixed project and task editing
Messed with the CSS on the login page, and added links to /register in /login, and vice versa
Added a little icon for private projects

Day 5

Added dashboard for general profile operations. The first page I added was to show all the pledges you've made so far:

I also changed the URL format from crofu.net/my-profile to crofu.net/~my-profile, like how sourcehut does it. With the previous method, I had to block out a bunch of profile names like "dashboard" and "profile" and "login" so they wouldn't collide with the existing URLs. I might still make a list of forbidden usernames, but I'll probably stick to terms like "admin" that might be confusing. Since I had a single url.rs that I put all of my URL definitions in, this change was pretty quick and easy: (see diff)

I think tomorrow is going to be a documentation day, since I've got a few emails and info forms that I want to write.

Day 6

Wrote two emails, one to a local co-op and one to a lawyer specializing in co-ops. The one to the local co-op was pretty straightforward, just a "hi please help" sort of thing. I might publish the one I sent to the lawyer if I get their permission (technically, I think I'm allowed to do whatever, but I think it would be courteous to at least let them know first).

Wanted to write the info sheet that I'm sending out to creators for the trial run, but I didn't get around to it. I've also got one more email to write.

Day 7

Spent most of the day researching cooperatives and legal resources, and didn't actually put pen to paper. I think this sort of activity, while helpful, kinda goes against the spirit of December Adventure. Rather than planning every last detail, I feel like it's more about being able to shake off the stun and create something, no matter how minor or ill-conceived. Much of the stuff I worked on last December Adventure was refactoring work, and it's likely that I'll refactor it again, but that doesn't mean that it's wasted. A lot of the time, it's much faster and easier to try something out and see what goes wrong than to try to plan ahead for every hypothetical.

Plus, that's the main problem I've been having with crofu development so far: I've been doing so much planning and worrying and hypothesizing, and I have very little actual outcome to show for it, and I think the best way forward is to just put something together and put it out there, and lay out the tracks as I'm riding the train. There are a couple caveats, namely that I'm working with money here, and I'd like to be careful on that front, but even there, I should focus more on having conversations and reaching out to more people who have actually gone through this before rather than scouring the internet for blog posts and videos.

The goal tomorrow is to get back to coding.

Day 8

Added markdown support for descriptions. A super straightforward change, just cargo added a markdown package and wrapped a maud::PreEscaped(markdown::to_html(description)) around the existing description.

Faffed around a bit trying to figure out how object storage works, then I realized I'm probably overengineering, and decided just to store files on the local filesystem for the short term. We'll see how that pans out.

Day 9

Another quick day: added a "complete task" button and reorganized some files. Gave up on image uploads for now because they seem like a hassle and I don't really need them for the initial test.

Day 10,11

Totally missed day 10 because I was working on a sculpture (article incoming soonish), but day 11 was pretty successful. I'm still in the "haphazard improvisational slapping together" phase of the project (which frankly might never end), but I've got a basic payment flow working, which is one of the last parts that I actually need to run my trial. It's using an internal wallet with fake money, which definitely won't be how it works for the final project, but for now, it lets me run my self-funded trial phase. Looking forward, I think the best thing to do would be to make this a formal payment process so that people pay for pledges individually, but if it's not to legally fraught, I think a wallet would be worth considering. It allows people to distribute "free credits", either at a project level or at the site level, which could be a neat way for projects to interact with their communities. No clue what the tax implications are there though, so the most complicated I think I'll get is a cart system where people can pay for multiple pledges in a single transaction (though under the hood, it'd still be separate transactions, like how Bandcamp works).

Apparently Overwatch is doing a 6v6 test thing next week, so I'm trying to get to a solid foundation on this project by then so I don't have to be working on any big sweeping changes.

Day 12

Spent the evening getting an account set up at https://mythic-beasts.com. They put my order on hold for manual confirmation, but other than that, the setup was actually pretty straightforward. I ran into a lot of errors, but they all had clear error messages, and I learned a lot while fixing them. This is in stark contrast to my experience with ovhcloud, where I had no idea what was going wrong (sometimes I wasn't even aware something was wrong), and it was always something stupid, and usually their fault rather than mine. Also, mythic beasts uses a pretty functional html-driven site, again in contrast to ovhcloud, which is like 4 different single page webapps composed primarily of javascript.

Also tested lettre, an email library. I was kinda surprised how easy it was to just send an email. To be fair, I had already done a lot of the config inputs at arms length because I've been using meli and sending from a custom domain. But even so, its cool that old internet protocols like SMTP just kinda work.

Day 13

Short day, just finished setting up things on https://mythic-beasts.com. Got crofu running on my virtual server and verified that email is working, and was able to access it through the URL I bought for it. Mythic beasts continues to be excellently clear about capabilities and available services (and their costs).

Documentation is hit or miss though:

I thought I just needed to set up a mail address to be able to send emails via SMTP, but apparently I also needed a mailbox. Once I knew that's what I needed to do, though, it was really easy to set up.
Setting up SPF records and DKIM (email security stuff) were literally a single click each. Setting it up for this site (jaxter184.net) was 25 minutes of trial and error.
Still haven't gotten HTTPS, but I think I'm fine just using HTTP for the initial tests. They have clear documentation for HTTPS on their web hosting service, but not for their VPS service.

My total costs so far:

mythic-beasts
- VPS (~$7/mo)
- email (~$2/mo)
crofu.org domain registration ($15/yr)

Certainly not nothing, but it's wild to me that I can get someone to manage my server and email stuff for less than the cost of a Netflix or Spotify subscription. Though that maybe says more about Netflix and Spotify than it does about VPSes.

Tommorrow I'll be back to actual crofu development. The current plan is to get the login flow working smoothly, with clear error messages.

Day 14

Actually, I send credentials with the URL in a POST message, so I actually need to use HTTPS. I'll do that later though.

Today I wrote some shell scripts for testing web interaction. One of the things that the test revealed is that I've been using content tags when I should've been using void tags in a few cases (ex: <br></br> instead of just <br>), so I spent a few minutes fixing that.

paths="/ /register /login /fake /~jaxter184 /~jaxter184/tlature /~jaxter184/tlature/task/plugin-iir-eq"
for ea_path in $paths
do
	echo "=================" $ea_path "================="
	curl http://0.0.0.0:3000$ea_path --silent > out.html
	xmllint --html out.html > /dev/null
done

It seems to be falsely flagging my <nav> blocks, apparently because they're an HTML5 feature. Gonna ignore for now.

Also forgot to add money to the wallet of the task owner when a pledge is paid so I did that too. Did some weird stuff with postgresql transactions that I frankly don't fully understand. I'll have to come back to this before I start processing other peoples' money.

Didn't get around to improving login error messages, but I'll kick the can on that one.

Day 15

Finally improved the login error messages. I think it looks a little simple, but I'll do some trials and see how usable it is before making any more changes to how it looks. Also implemented email registration. Basically how it works is that there's a SQL table of user profiles and secret codes (UNIX timestamp plus a UUID):

create table if not exists email_verify
(
	id UUID primary key not null references "profiles"(id),
	code text not null unique
);

When the user registers, it creates an entry in the database, generating a new code. The code is overwritten whenever a new verification email is resent (which also happens whenever the email changes). The body of the email has a link that looks like https://crofu.org/verify-email?v=<insert secret code here>, which is a page that just checks whether the logged-in user's secret code in the table matches the one that's given in the URL parameter, and if it is, then it marks a column in the profiles table indicating that its email is verified.

Verifying your email doesn't do anything yet, but in the future, I think it'll be a prerequisite for donating and creating projects (pledging should have as few barriers as possible though).

Day 16

Literally spent my entire evening playing Nomia (very fun game despite being fairly early in development).

To abide by the December Adventure spirit, I added a few registration tests using the curl -> xmllint process I showed on Day 14. It involved using some XPath queries, which can get pretty gnarly depending on the website:

xmllint --html out.html --xpath '/html/body/div/form/fieldset/table/tr/td/label[@for="username"]/../../following-sibling::tr[1]/td[1]/text()'

XPath Breakdown

/html/body/div/form/fieldset/table/tr/td/label: The first part is pretty straightforward, and just goes down the tree looking for all the heirarchies that fit the pattern:

<html>
	<body>
		<div>
			<form>
				<fieldset>
					<!-- etc -->

[@for="username"]: This part checks the attributes of the <label> tags to find one that looks like <label for="username">

/../..: This just goes up the tag heirarchy the same way it works in a file path

/following-sibling::tr[1]: This is a pattern I found that just looks for sibling nodes (nodes that are at the same heirarchy level and share the same parent) and picks the first one

/td[1]: Picks the first <td> child node

text(): Prints the text contents, i.e. <tag>this part of the xml data, excluding the tags</tag>

Day 17

Added an account page for checking email verification status

Day 18

Added a button to the account page to resend the verification email. It's one of the slowest parts of the website since it has to do the whole email sending thing in the background. There's probably something I could do on that front, but I'll leave that for later.

Day 19

Added a rudimentary version of the expected donation score (a more complete version is described here: https://wiki.jaxter184.net/icc/scoring/). While doing this, I ran into a bunch of annoying SQL bugs. At one point, I converted all the sqlx macros into regular function calls, which skips some convenient checks on the SQL queries. I had originally done it to try to get it to compile on fly.io, but since I'm not using fly.io anymore, I think I'll convert them back.

Day 20

Despite spending 2.5 hours of my day playing Overwatch right after work, I ended up accomplishing a lot today.

The main thing I did today was, as I foreshadowed, changing all the sqlx function calls back into macros. There were a couple weird things to do with the enum types, but I just tossed a as "task_state: _" after every SELECT field in the SQL command and an as _ after every query argument in the Rust code, and that seemed to solve pretty much all the issues I was having with it.

Added error messages when you fail a login
Fixed a few miscellaneous bugs and refactored some currently unused task deletion code
Implemented HTTPS (basically just had to copy the axum rustls example and run certbot certonly --standalone)

Note the 's' in the URL bar

Day 21

Cleaned up some code, mostly in main.rs around using axum. Something about graceful shutdown and redirecting HTTP to HTTPS. Mostly copying and pasting from axum examples.

Day 22

Added a field for changing your email. There are a lot of cases where the server panics (in an async thread, so it doesn't bring down the whole site), including when the email is changed to one that is already in use. I might do some research into ways to do error handling in axum so I can improve both the cases where it happens, as well as the ergonomics of the code itself.

Day 23

Added an error message when changing the email to an existing value

Day 24

Did some testing on the website and found/fixed a few minor issues, mostly just blank pages when there should be an error message, or rephrasing text.

Also implemented a stipend system so that each user gets $5 when verifying their email, but with a limit that I can update regularly to mitigate bot registrations. Things that I probably won't have to worry about, but addressing early can save me future headache. I might also gamify it so that you get a dollar a day just for visiting.

Day 25

Did a lot of stuff today! The site is finally ready to start seeing test use by people who are not me. If you want to check out what's going on so far, the site is available at https://crofu.org. I'd love to hear any feedback, even if it's just "I opened it and didn't understand what was going on". In the few hours that it's been up, I've gotten a few people who visited it, but no one ever got past the home screen. I have no idea why this is, so if you have any thoughts on the subject, please reach out at [email protected]">[email protected].

I think if I really wanted to, I could start my official trial run in January, but while it would be cool to start at the literal beginning of the year, I don't want to rush into anything, so I'll probably start a week or two into the month, assuming I keep pace.

Things I did today:

Just added a file output and picked a filter level that makes sense.
- I think there are some additions I can make that will make logging cleaner (like implementing my own Filter as recommended here), but I'll worry about that when the current logging becomes a problem.
Made some scripts to make deploying and testing ever so slightly faster and easier
Change lettre (email sending library) to use rustls instead of openssl, which lets me compile to musl, which I had to do because my server is running Ubuntu, which uses a much older glib version than my development machine, which uses arch btw. Before, I was pulling the repo and recompiling crofu each time on the server, but now I can just build locally and scp the binary over, which is a lot quicker and doesn't require me to put the whole Rust toolchain on the tiny server that I've rented.
Fix a bug with project visibility, and show the current visibility setting of profiles/projects/tasks that the currently logged in user controls.
Add some server-side processing to reduce the complexity of the redirect information in login/registration URLs

Day 26

Improved the logging. Trying to not get too invasive with it, but adding the user agent and requested path really helped. It turns out a lot of the visits to my site are either Fediverse servers, scrapers, or bots looking for vulnerabilities, such as:

/wp-admin/setup-config.php - WordPress admin portal
/cgi-bin/luci/;stok=/locale
/actuator/gateway/routes
/.env
/api/v2/static/not.found
/remote/logincheck
/fonts/ftnt-icons.woff
/cgi-bin/luci/;stok=/locale
/geoserver/web
/query
/solr/admin/info/system
/solr/admin/cores
/v2/_catalog
/libs/js/iframe.js

Day 27

Got some really good feedback today, and spent basically the whole day addressing it.

Fixed a logic bug that displays the logged in user's projects on every profile page
Replaced all uses of the unpopulated displayname field with the slug
Changed default font to sans-serif
Put an ICC summary on the landing page so people don't have to immediately leave the website
Autogenerate project/task slug based on the displayname and put it in an "Additional settings" collapsible menu
Improve styling of new/edit project/task page
Add PostgreSQL constraints that prevent multiple tasks with the same slug, and relax the constraint that requires a project slug be globally unique (instead, it now must be unique within the profile).

Just goes to show that if you want to motivate me, just look at something I did and complain about it.

Day 28

Another pretty packed day

Allow username login
Add PostgreSQL constraint requiring that usernames be case-insensitively unique
Update curl tests to use HTTPS
Refactor database interface to be a little more modular, at the cost of potentially worse performance. I'll try to benchmark it later, and likely refactor this again, maybe using diesel since I'm not really loving sqlx.
Refactor the way that I organize functions on pages that need to be loaded with errors, like registration and new project/task creation

The way I implemented that last item was a bit hacky. I'm using axum, which uses "extractor"s to load the items in a function signature using the HTTP request data.

For example, the function signature for the https://crofu.org/~profile/new-project route is:

async fn get_new_project(
	Path(profile): Path<String>,
	db: Extension<Database>,
	auth_session: AuthSession,
	uri: Uri,
) -> Result<Html<String>, ()>;

Path(profile): Path<String> - populated according to the route (.route(&url::new_project(":profile"), get(get_new_project))), which specifies one matchable path parameter: the profile name.
db: Extension<Database> - I'm honestly not totally solid on how exactly this one works since I basically just copy/pasted it from an example, but my assumption is that the Extension type is what lets me access it like a global state by just adding it as a .layer(db) when initializing the Router.
auth_session: AuthSession - Another copy/paste, but this one is probably from the AuthManagerLayer provided by the axum_login library.
uri: Uri - The URI, which I use to generate the nav bar.

Notably, all of these types have to implement FromRequest or FromRequestParts (I think), which is what makes them extractors and allows the router to use them to generate web pages. While these functions are normally called by the router (the get(get_new_project)) in the .route(...) call above is where that connection is made), I can also, of course, use this as a regular function, for example by the post::new_project function that I use to process the form generated by get_new_project (TODO: draw a flow chart on how these calls work). However, if I add a parameter like error_state: Option<NewProjectErrorState>, then I get a compilation error complaining that the trait `Handler<_, _>` is not implemented for fn item <function signature of get_new_project>, since Option<NewProjectErrorState> is not a proper extractor.

My solution to this problem was to make NewProjectErrorState an extractor. Extractors should generally be based on request data, but I chose to ignore that because it makes my life easier. I chose FromRequestParts over FromRequest because the half-second of reading documentation I did suggested that the former has fewer restrictions, and can be optimized more efficiently than the latter.

#[axum::async_trait]
impl<S> FromRequestParts<S> for NewProjectState where S: Send + Sync, {
	type Rejection = ();
	async fn from_request_parts(_: &mut Parts, _: &S) -> Result<Self, Self::Rejection> { Ok(Self::default()) }
}

My implementation basically does nothing and always populates NewProjectErrorState with its default values. This works in my case because I want it to always load from the router using its defaults, since errors should only be displayed when get_new_project() gets used by post::new_project():

mod post {
	pub async fn new_project(
		/* other parameters */
		Form(form): Form<EditProjectForm>,
	) -> Result<Response, ()> {
		// ...
		if db.session_profile(&auth_session).unwrap()
			.new_project(&form.slug, &form.name, &form.description, form.page_state).await
			.is_err() {
			return Ok(get_new_project(
				path, db, auth_session, uri,
				NewProjectErrorState { form, slug_taken: true },
			).await.into_response());
		}
		// ...
	}
}

All that work just so I don't have to have an intermediary fn render_new_project() that gets called by both post::new_project() and get_new_project().

Day 29

Did a little more database API refactoring, just a continuation of what I did yesterday. The general idea is that instead of having the get_project_by_slug() function in the main database struct return a Project, I instead have it return a ProjectDatabase, which is an API structure that exposes more controls. Put another way, I used to return a read-only structure, but now I return something that can be used to modify the project, and getting the original read-only structure now requires an additional function call.

Day 30

I was busy with other stuff, so I missed the day

Day 31

Added error messages to the POST request handlers for the task. Basically just more continuation of the stuff I did on the 28th.

Retrospective

As it usually is with my December Adventures, I ended up getting a lot of stuff done (despite that not being the direct goal). While I'm pretty happy with the current state of the project, I think there's still a lot more stuff to do, and I've become a little less confident in both the idea itself and my ability to execute on it. I am, however, now in a much better place to understand where the shortcomings are and fix them.

Last year, the things I wanted to do better were keep up with other people's adventures and do less refactoring. I think it's just the nature of working on a brand new project, but I didn't spend nearly as long refactoring as I did last year. There was still a bit, but in retrospect, I think it's just the nature of the way I do things to refactor often. Plus, my main reason for doing less refactoring was that it was less exploratory, but thinking about it more, frequent refactoring is the natural result of a very exploratory process. Rust's ability to let me confidently change my approach allows me to try many more things than if I had to stick to whatever design I make, and knowing that I'll change it if it's bad lets me make decisions much quicker.

As for keeping up with other peoples' adventures, I didn't do it as much as I probably should have. Early on, I saw a few, but I found myself not keeping up with them because they didn't really have a narrative through-line.

Which brings me to my goals for next year:

Have a narrative through-line. The adventure is much more interesting and compelling when it's presented as a story, even if that story is mundane. Not sure yet exactly what this will entail, but I have a whole 11 months to think about it.
Instead of just consuming the firehose, pick a few adventures to keep up with. I think it'll be much easier to keep up with other peoples' adventures if I just stick to a few from people I like, or people who are doing things I'm interested in.

2024 was not the year of the tracker on the Linux desktop, but hopefully 2025 will be the advent of ICC, thus enabling the subsequent year of the tracker on the Linux desktop.

Graph Layout Algorithm

Unknown — Thu, 05 Sep 2024 00:00:00 +0000

Blender's node editor UI

Node editors are really neat! They're a very intuitive way to visualize the dependent relationships of the various parts of a process, from graphics rendering pipelines to audio patches. I've been doing a lot of keyboard-driven TUI stuff for the last few years, and while node editors are a very GUI-centric interface, I think with a few tweaks, a TUI node editor could be a very reasonable thing to do.

The main challenge that makes node editors so GUI-centric is that there is a lot of mouse interaction. While you can use a mouse in a TUI, keyboards are by far the preferred input method, and the spatial nature of a node editor makes it tough to navigate with just a keyboard. Some node editors solve this by tying navigation to the topology of the graph: up arrow key selects the parent, down arrow key selects the first child, left and right navigate siblings. If all the nodes are connected (they usually are, and even if they aren't, there are workarounds), this allows you to navigate to any other node with ease.

However, even if you solve navigation, a lot of the clicking in a node editor is just moving nodes around to tidy the connections, and having to use arrow keys for that would greatly slow down workflows, which basically nullifies 80% of the benefit of a keyboard-only input method.

Which brings me to my solution: node placement should be determined only by topology. No more clicking around reorganizing nodes, they'll be placed mostly in the right place automatically, no more manually routing connections, plus you won't need to store extra data in files to keep track of positions.

prior art

mermaid and dot have some way of placing nodes by topology that i didnt bother looking into

vocabulary

graph - a set of nodes with connections between them
directed graph - a graph where the connections are directional
directed acyclic graph - a directed graph where following a series of connections from node to node will never result in a loop
node - an object in a graph that connects to other nodes
connection - a relationship between two nodes, generally represented with a line connecting the two (footnote: choosing this over the classical graph theory term "edge" because it's a little confusing since we're talking about the geometry of how things get drawn)
line segment - when drawing a connection, these are the straight parts between bends
joining - the place where two connections with the same destination represented by separate lines come together into one line
splitting - the place where a connection between a source and two destinations splits apart into separate lines

background

why are we using a DAG?
how is it related to a tree?

goals

For simplicity, we will assume rectangular nodes and orthogonal connections that only travel horizontally and vertically, with right angled turns.

For clarity, we will assume all data flows in one direction. In some cases, this may be left to right, in our case, we will pick bottom to top.

requirements

Connections cannot pass behind nodes, as they would be much harder to follow.

Connections can only overlap when perpendicular. Put another way, only two connections can overlap at any point, and one must be travelling horizontally while the other travels vertically.

it must be clear whether segments are intersecting at a junction or passing over each other

nice-to-haves

Positioning should be predictable. If I know how two nodes are connected, and I know where one of the nodes is, I should be able to know where the other is as accurately as possible.

should be as compact as possible

minimize connection intersections, both when passing over each other and when splitting/joining at a junction

if it doesn't interfere with any of the above heuristics, the segments of a line between bends should try to be similar to each other in length.

Try to draw the least amount of lines possible. This primarily means that connected nodes should be placed close to each other. Also, if two connections join, they should do so at the earlist point possible, so that the majority of their travel is as a combined line.

willing to allow minor space inefficiencies for a simpler or faster algorithm

our use case

The actual data that the node is representing is arbitrary, but I've chosen my favorite kouign amann recipe.

Assuming we have a loose list of which components have which ingrendients (these are the directed connections):

dough requires salt
butter sheet requires salt
butter sheet requires sugar
dough requires water
syrup requires sugar
syrup requires spices
dough requires butter
kouign amann requires syrup
dough requires flour
laminated dough requires dough
butter sheet requires butter
laminated dough requires butter sheet
dough requires yeast
kouign amann requires laminated dough

We can sort that list and build a heirarchical representation of the ingredients is as follows (in order of amount):

* kouign amann
	* laminated dough
		* dough
			* flour
			* water
			* butter
			* yeast
			* salt
		* butter sheet
			* butter
			* sugar
			* salt
	* syrup
		* sugar
		* spices

We're basically 80% of the way there already! Though now comes the tough part, where we figure out how to display these with connections between them so that items (like butter and salt) aren't repeated.

You could imagine that if this were a graphics pipeline, it would be much more efficient to just calculate the butter and salt processes once, and reuse that output for the inputs to both the dough and the butter sheet processes.

the algorithm is as follows

Place nodes and their children

Before we even draw any connections, let's roughly arrange all of the nodes first, based on their relationships to each other, starting with the root:

Note the two inputs at the bottom of the node, which are for laminated dough and syrup. We'll follow those two inputs and place their corresponding nodes:

So far so good. laminated dough was placed in a way that automatically connects it to the corresponding input on the kouign amann node, but syrup wasn't. Later when we draw connections, we'll bump the lower row down one unit so that we can make the connection, but for now, we'll leave them where they are for simplicity.

Horizontal nudging

Quick pause: it's not immediately obvious now, but if we try to connect syrup, butter sheet is going to make the connections a bit more roundabout than necessary, even if we do the vertical bumping mentioned earlier:

It's not too bad, but there are similar cases that we could run into in the future that are much worse:

Recall one of our goals: "Try to draw the least amount of lines possible".

To address these cases, let's adjust our algorithm to nudge parent nodes to their leftmost child. This will pull it further from its parent, but since there is one connection to the parent and two to its children, putting it closer to its children draws fewer lines:

We'll have to do the same horizontal nudging to butter sheet in the next step (which will move syrup again, poor fella).

However, it happens to be the case that butter and salt, the last two ingredients of dough, are also ingredients in butter sheet, so for more compactness, we can modify our nudging algorithm to only move parent nodes when all of their children are to the right.

Vertical nudging

Now all of the nodes have been placed, but there's one more adjustment that we should make before drawing connections. It seems that sugar is on the same row as butter sheet even though one is an ingredient of the other. A quick fix is to nudge it down one row. In this case, we don't have to move it anymore, but if it collided with something on its row, we'd nudge it (and its parents) to the right.

Also, once we bump sugar down one row, we can tuck in spices. This is our first time nudging something to the left, and the mechanics of that are a little weird, so I'll leave that as a bonus in the appendix (TODO).

Easy connections

Alright! How exciting! All the nodes are placed and we're ready to draw connections. Let's start with the easy ones: anywhere where we can just draw an unobstructed horizontal line between inputs and outputs, let's do that:

This is another place where the exact mechanics of the algorithm are up for grabs. Should the ingredients on the bottom row stay aligned? To do so would make connections longer, but would maybe be more readable. Since our original goals emphasize compactness, I'll leave it as-is for now, but maybe I'll return to it later.

We could also mode syrup and its children to the left by one unit, which would make one line one unit shorter, but tracking when that optimization could be made would greatly increase the complexity of the algorithm, which is no fun for anyone, so we can ignore that.

Harder connections

The only connections left are the inputs of butter sheet. There is no way to lay out the connections without at least one intersection, so now is when we need to start worrying about all the rules regarding connections and create a measurable heuristic for how good a connection is. To review (and simplify), our rules for connections are:

All ingredients flow from bottom to top
Connections cannot pass behind nodes
Unrelated connections can only overlap when perpendicular
Minimize connection intersections, both junctions and overlaps
Try to draw the least amount of lines possible.

First, let's take a closer look at what we're working with:

The inputs of butter sheet, in order, are butter, sugar, salt.

The way I went about doing this is creating a pathing algorithm (similar to A*) that tries to make its way to the other end of the connection.

TODO: the rest of the article

appendix

box drawing characters

what are they

what are the caveats (output pipe can't match both block wall and connection type/style)

Nokia Battery Comparison Chart

Unknown — Thu, 08 Aug 2024 00:00:00 +0000

Recommended sizes (mostly due to popularity/availability):

BL-5C
BP-4L

Name	Capacity (mAh)	Voltage	Capacity (Wh)	Weight (g)	BSI (kOhm)	Footprint (mm)	Thickness (mm)	Chemistry	Connector
BL-6X	700	3.7						Lithium
BL-4YW	2000	3.7						Lithium	harness
BML-3		2.4			no BSI pin			Ni-Mh
BLK-4S	750	7.2						Lithium
BLS-2N	1050	3.8						Lithium
BV-4D	1320	3.7						Lithium	pinch
BBT-3S		6						Ni-MH
BL-5F	950	3.7			27	46 x 40	5	Lithium
BPS-2	1100	3.8						Lithium
BL-5B	820-890	3.7		24	75	46 x 33.9	5.65	Lithium
BL-6C	1070-1150	3.7				53 x 34	?	Lithium	side pad
BR-5C	970	3.7				53 x 34	6	Lithium
BL-6P	830	3.7			75	37 x 37	6	Lithium
BL-5X	600	3.7				32.9 x 37.7	5.4	Lithium
BBH-1H	1700	6						Ni-MH	bottom pad
BL-4D	1200	3.7		24	100	60 x 44	4	Lithium	pinch
BLD-3	780	3.7		19	44	52.3 x 32.4	5.3	Lithium
BBH-1SF	800	6						Ni-MH
BP-4GW	2000	3.7						Lithium	harness
BL-4J	1200	3.7			100	59 x 37.5	4	Lithium	pinch
BP-6X	700	3.7						Lithium
BL-8N	700	3.7			no BSI pin			Lithium
BMH-1V	550	6		89		120 x 42	14	Ni-MH
BL-5CA	700	3.7		18	47	53 x 33.9	5.6	Lithium
BV-5JW	1450	3.8	5.5	28	7.3	58.5 x 38	5.6	Lithium	cable
BP-4L	1500	3.7			120	66 x 44	5	Lithium	pinch
BLL-2		3.6						Lithium
BMC-3	1100	3.6						Ni-Mh
BL-4CT	860	3.7	3.2		75	54 x 34	4	Lithium
BL-5BT	870	3.7			75	45 x 33	5	Lithium
BLB-3	920	3.7						Lithium
BL-4B	700	3.7			68	46 x 34	4.3	Lithium
BBH-1S	600	6						Ni-MH
BLJ-1	400	7.2		48		120 x 42	10	Lithium
BV-5XW	2000	3.7						Lithium	harness
BP-4W	1800	3.7				84 x 48	3.8	Lithium	pinch
BV-4NW	2000	3.7						Lithium	harness
BLJ-4	1500	7.2		106		120 x 42	22	Lithium
BLN-3		3.6						Lithium
BL-8L	700	3.7						Lithium
BL-5K	1200	3.7						Lithium	pinch
BL-5C	970-1050	3.7	3.885	23	82	53 x 34	6	Lithium	side pad
BL-5J	1320	3.7	4.9	22.15	100	60 x 38	5.5	Lithium	pinch
BPS-1	600	3.7						Lithium
BP-5L	1300-1500	3.7						Lithium	side pad
BLC-1	950	3.6						Lithium
BL-4BA	630	3.7			33	46 x 34	4.3	Lithium
BBH-2H	1100	6						Ni-CD
BL-4S	860	3.7			75	50 x 38	4.8	Lithium
BP-3L	1300	3.7	4.8	28		66 x 44	4.1	Lithium	pinch
BL-5CB	800	3.7		21	30	53 x 34	5.8	Lithium
BP-5M	900	3.7	3.3		75	41 x 40	6	Lithium
BP-6EW	1830	3.7						Lithium	harness
BLB-2	650-750	3.7			46	53 x 33	7	Lithium
BBT-1XV	600	6						Ni-MH
BL-6Q	970	3.7						Lithium
BMH-1	550	6		85		120 x 42	14	Ni-MH
BP-5Z	1080	3.7	4			41.6 x 43.9	5.6	Lithium	pinch
BP-3001L	1240	3.7						Lithium	bottom pad
BL-6F	1200	3.7						Lithium	pinch
BL-5CT	1050	3.7			82	54 x 34	5	Lithium
BLL-3		3.6						Lithium
BP-6M	1070-1100	3.7			91.5	40 x 41	6	Lithium
BP-6MT	1050	3.7			91	40 x 41	6.5	Lithium
BL-4U	1000	3.7			82	61 x 38	4	Lithium
BMP-1A	700	3.6						Ni-MH
BP-5T	1650	3.7						Lithium	pinch
BLC-2		3.6			74.1-75	53 x 38.3	7.4	Lithium
BL-4C	860	3.7		24	75	53 x 34	4.5	Lithium

BLB-2 may have a different BSI resistance for the 650 mAh model. The wiki was unclear.

BSI resistance is generally measured between the GND and BSI pin

Datasheet for a BL-5C clone: https://docs.rs-online.com/ab5a/0900766b80cf37fc.pdf

Good part for the side pad-style connector: https://www.aliexpress.us/item/3256804968015691.html. The important part is that the pitch is roughly 3mm and the point of contact is roughly 3mm high. For this reason, I like the 4.6H variant. Some taller alternatives for you sickos out there: https://www.aliexpress.us/item/3256804706549757.html

Discontinued part for pinch connector: https://jlcpcb.com/partdetail/DCHAIN-BA030637042059/C5827004. A bit of a stretch, but it may be possible to use parts from here: https://www.lcsc.com/products/PCB-Welding-Terminal_11512.html, with the caveat that they're all through-hole and all the ones I've looked at are too big.

Close-up of the harness-style battery connector

There's probably a similar part somewhere in this list: https://www.lcsc.com/products/Board-to-Board-and-Backplane-Connector_960.html

TODO:

implement natural sorting so I can remove the underscores from the capacity section
put arrows in header row so its more obvious that the table is sortable
missing

Sources

Basically everything scraped from the cpkb.org wiki pages on Nokia batteries (it's down at time of writing, which is a bit concerning)
- The cpkb wiki is under the GNU Free Documentation License 1.3, which disallows editing, but as I understand it, everything I've copied is technical information, and holds the same copyright status as a phone book. If anyone knows more about law than me and thinks this is technically illegal, I'd appreciate if you let me know.
BP-4W dimensions from: https://www.batterymart.com/p-bli-1322-1-4-nokia-bp-4w-battery.html
Table sorting code adapted from: https://github.com/tofsjonas/sortable/blob/main/sortable.js
TODO: add info from here: https://pinoutguide.com/CellularPhones-A-N/nokia_bl-4j_battery_pinout.shtml

PCB swatch

Unknown — Mon, 05 Aug 2024 00:00:00 +0000

The main goal of this swatch PCB is to use as a visual reference when creating PCB art, specifically for this life counter project.

A similar project: https://arx.wtf/blog/1-front-panels-tips

I encourage you to download the file!

Design

To show how different layers interact, the front side features every combination of copper, silkscreen, and mask (and lack thereof), plus two sizes of hatching. My favorite combo is probably the one where every layer has small haching.

The back features a couple test patterns to let me know how small my features can be. According to the fab house's support team, the reason that the black silkscreen on white mask came out differently than the other two is because it was processed by a different engineer who skipped a step assuming that I was putting silkscreen over the holes in the mask on purpose. I'm honestly kinda glad that I got a few different versions because I now have references for what the end result is like in both cases.

TODO: closeup pics

Life Counter

Unknown — Sun, 30 Jun 2024 00:00:00 +0000

A friend had a cool abacus life counter that he made with his favorite card, so I made a feeble imitation of it using processes and components that were more familiar to me. It's hypothetically usable for keeping track of any integer value in any game, such as a planeswalker's loyalty count or any resource in a board game or tabletop roleplaying game.

I'm not selling them yet, but I'm planning to. To be notified when they're available, [email protected]?subject=Life%20counter%20notification%20request&body=I%20would%20like%20to%20be%20emailed%20once%20the%20life%20counter%20is%20available.%20Thanks.">click here, fill in your email (if it isn't already done so automatically), and hit "send". Alternatively, you can try to make one yourself using the published schematics and code, in which case I'm happy to help!

Front

Back

Layers

Stacked layer view

3D printed frame with little corner indents to keep everything together
Thin, hard plastic sheet to protect the card and display
The card "Oko, Thief of Crowns" from the trading card game, Magic, the Gathering. I bought a bunch of this significantly cheaper card with a similar layout to practice the cutout on.
PCB with an e-ink display, STM32F030C8T6, and side-mounted switches
Two pieces of laser-cut ~1.5mm acrylic welded together with solvent. Pattern created by manually editing the courtyard output of KiCAD.

Flat layer view (front)

Flat layer view (back)

The two versions I've made, with the e-ink display mirrored.

The programming pads are designed for pogo pins, but it's a hassle to hold them on by hand when I'm iterating on code, so I've soldered a header on the one on the right.

Display considerations

The numbers on the left conveniently cover up the weird bit at the base of the cable connector

When the display is flipped, I can put the buttons on the same side as the numbers, but at the cost of seeing the weird bit

the noise in the other pictures are a result of the displays being turned off for a long period of time

The e-paper circuit primarily references the manufacturer's documentation, but I also looked at the Pimoroni Badger 2040 (schematic) and the Waveshare E-Paper Driver HAT.

Old version

The first version. It's much more readable in the dark.

I really liked the rear-illuminated icons, but unfortunately, the LEDs greatly increase the power draw. I'm not sure by exactly how much, but my estimate is that it takes the power on duration from a few days to a few hours. I wanted to use a coin cell in the final version so I wouldn't have to worry about charging or other lithium polymer battery considerations, and the LEDs were pretty much the only thing that drew a lot of power, so they were the first thing to go.

I also thought the PCB art was really cool, and I want to experiment with stuff like halftone/dither and outlines and compensating for the silkscreen leakage, but I'll probably do that on a project that I'm not planning to sell, because I'd prefer to avoid having Wizards of the Coast sic the Pinkertons on me.

Things to try in the future

USB connector at the top? or the side? or the bottom?
Add optional LEDs for those who want to use it as an "on" indicator (the e-ink display doesn't have time to change it's display when the unit is powered off)
See how it fits with Pokémon, Digimon, and Yu-Gi-Oh cards (and maybe others?)
Make the case on a resin printer. Should be thinner and more precise, and maybe let me make clips like on injection molded parts. If I do the clips, I can probably also redesign the acrylic back to make the clips flush with the back.
https://github.com/klepas/open-baskerville/tree/master/specimens

Open Hardware Summit

Unknown — Wed, 12 Jun 2024 00:00:00 +0000

Open Hardware Summit in Montréal

Went up with some friends who are building a digital theremin

Canada does a really good job supporting cooperatives compared to the US (at least based on my anecdotal experience in both cases).

Kouign Amann

The bagels sucked. I liked the bagels I had in New York better.

I did, however, have a very good pastry called Kouign Amann Delicious cake made of butter, sugar, and bread (in order of amount). One of the people in the group I was staying with wanted to go to a café named after the pastry one morning, and after eating it, I was thinking about it for the entire rest of my trip.

After I came back, I tried making the pastry using this recipe (conveniently based on the exact same patisserie I happened to visit), and it only took one failure to successfully make one.

Hackerspaces

visited several very cool hackerspaces. don't remember the names of the places i visited, but they were all incredible. saw a cool sculpture.

Also visited ResistorNYC while i was in New York and it was very impressive.

Individuals and organizations

State machines

Unknown — Sat, 25 May 2024 00:00:00 +0000

During development of a character combat game, it is important to be able to materialize and iterate on ideas quickly. Some games use XML files, others use Microsoft Excel, and games like Balatro and Hades 2 are written mostly in Lua (to the delight of their modding communities). Overwatch uses a visual programming language called "Statescript", described in Dan Reed's GDC 2017 talk (alt link), and it is a particularly exciting example of how such a system can be designed. According to the talk, Statescript is used to manage all the game logic, animations, and sounds that comprise a hero ability (including their primary fire weapons), as well as things like HUD UI elements (ex: ultimate meter, character portrait, health bar, ability icons).

A whirlwind primer on finite state machines

Feel free to skip this section if you are familiar with the term "finite state machine"

A state machine has states (duh?)

Each state can transition into another. The arrow on the left indicates that that is the "starting" state, and the double circle on the right indicates that it is a valid "ending" state.

Transitions can have conditions. In this case, if var is true, then the state machine goes A -> B, and if var is false, then it goes A -> C -> B.

State machines can be arbitrarily complex.

Note that for every node (that is not an ending node) always transitions to exactly one another node. For example, the conditions of the outgoing edges of node C are a bit weird, but no matter what the values of u and w are, C will always transition to only one of F, B, or D:

`u`	`w`	`!u` (to `F`)	`u && w` (to `B`)	`u && !w` (to `D`)	node
❌	❌	✅	❌	❌	`F`
✅	❌	❌	❌	✅	`D`
❌	✅	✅	❌	❌	`F`
✅	✅	❌	✅	❌	`B`

Now that we're on the same page about what a finite state machine is, it's time for something completely different because:

Actually, I don't want a finite state machine

Though finite state machines are one of the most common types of state machines in the context of programming, they aren't the only one. In the aforementioned Statescript, for example, multiple states can be "active" at once, and the flow of states interacts with the "tick" timing system used to synchronize game logic in Overwatch. Loosening the rules like this allows for a more flexible system and (hopefully) cleaner state machines.

Current design

Each spell/skill is its own state machine containing:
- states
- attributes - in-game variables turning speed, position
- resources - skill-specific variables such as ammo and fire rate, as well as timers
States can transition between each other
States can be triggered to be "active" even without a preceding state
When activated, states perform actions, such as starting a timer or dealing damage

Here is an extremely simple example of a "dash" skill that moves the player quickly in the direction they are currently facing:

// skill
"dash": {

	// state that triggers on button press
	"do": (
		activate_on: All([
			// on button input
			Ext(Input(Rise)),
			// if cooldown is not active
			TimerExpired("dash::cooldown"),
		]),
		action: [
			StartTimer("dash::cooldown", 0.5),
			StartTimer("dash::duration", 0.05),
			Ext(SelfEffect([
				// forces player to move in the direction it is facing (i.e. not strafing)
				SetMoveControl(Forwards),
				// "Stats" are game variables that directly control some aspect of game logic
				AddStatMod(
					// Set turn speed to 0, preventing turning
					TurnLimit,
					// Information for order of operations. The name is for when we want to delete the modifier later.
					(priority: 2, modifier: UpperLimit, name: "dash::"),
					0,
				),
				AddStatMod(
					MoveSpeed, 
					(priority: 2, modifier: Add, name: "dash::"),
					80.,
				),
			])),
		],
	),

	// state that runs at end of dash to reset the player
	"end": (
		activate_on: TimerExpired("dash::duration"),
		// `pre_state` is the list of states that this "end" state transitions from.
		// These states must be active in order for "end" to trigger, and will all be deactivated when that happens.
		pre_states: ["do"],
		// Deactivate this state ("end") after triggering
		transient: true,
		action: [
			Ext(SelfEffect([
				RemoveStatMod(
					TurnLimit, 
					(priority: 2, modifier: UpperLimit, name: "dash::"),
				),
				RemoveStatMod(
					MoveSpeed, 
					(priority: 2, modifier: Add, name: "dash::"),
				),
				// return movement to the default
				RevertMoveControl
			])),
		],
	),

},

Note that all the variables are prefixed with dash::. Variables are all global, and the prefix serves as a sort of namespace so that the dash "cooldown" timer doesn't interfere with the shoot "cooldown" timer.

next time

why is ammo a non-integer value

meters

implementation details:

colliders
variables
serialization
stats (move speed, etc)

Considering wiping the slate and reimplementing it as Lua scripts. depends on how much i need the Lua functionality, and how consise the scripts end up looking.

Circle Physics

Unknown — Thu, 09 May 2024 00:00:00 +0000

Real-time strategy (RTS) games like StarCraft and Pikmin are characterized by their ability to simulate large numbers of units. One of the interesting things that I noticed about Pikmin is that it seems that the Pikmin almost always organize into circles when carrying objects, and almost all the enemies have round hitboxes and hurtboxes. Similarly, when calculating how they push each other around, all of the units in StarCraft 2 (and similar games) are also calculated as circles. All this made me wonder if there was some trait of real-time strategy games that made it advantageous to limit all moving objects to circles in their physics simulation.

While I have not spoken to any developers of these games to confirm that RTS games indeed tend to use circles, the following are my observations that potentially explain this:

RTS games have tons of dynamic units, so even a tiny savings in processing per unit can result in a large overall performance improvement
Circle collisions are easy to calculate. Circles a and b are colliding if: distance_between(a.position, b.position) < a.radius + b.radius
Because the objects are circles, their rotation does not change physics behavior, and physics does not have to change rotation. Contrast that to a square, where hitting its corner at an angle will cause it to spin, and it can hit other objects while spinning and move them as a result.

A prelude: axis-aligned halfplane

Assuming 2D space for now, the absolute simplest shape we can define collision detection for is the axis-aligned halfplane. Given a horizontal line that intercepts the Y axis at height y, lets define our halfplane as being the space above that line. We can tell whether a point collides with this halfplane by simply comparing y to the point's Y value:

fn is_above(p: Point, y_intercept: f32) -> bool {
	p.y > y_intercept
}

and given the following points and halplane:

[TODO: plot]

we can easily calculate that is_above(a, y) == true and is_above(b, y) == false, so we know a collides and b does not. Easy peasy!

The main event: circles

To start off, let's do the same thing we did with the halfplane and check for whether a point collides with a circle:

fn is_inside(p: Point, c: Circle) -> bool {
	let distance = sqrt((c.position.x - p.x).powi(2) + (c.position.y - p.y).powi(2));
	distance < c.radius
}

Eek, seems like there are a few nasty operations in there. According to latkin, square roots are about 6 times more computationally intensive than additions or subtractions, and exponents are even worse. Fortunately, since ${a^2 = a * a}$, we can replace all of these operations with well-placed multiplications, at the cost of making the code a bit harder to read:

fn is_inside(p: Point, c: Circle) -> bool {
	let dx = c.position.x - p.x;
	let dy = c.position.y - p.y;
	let d_squared = dx * dx + dy * dy;
	d_squared < c.radius * c.radius
}

(Extra reading on when pow is more expensive than multiplication)

I'm not too worried about readability; people used to do much less readable things in the name of computational efficiency. Plus, the libraries I've used usually have functions for ergonomically calculating d_squared, so it ends up looking more like:

fn is_inside(p: Point, c: Circle) -> bool {
	c.position.distance_squared(p) < c.radius * c.radius
}

Probably the most common thing we would need to calculate when simulating physics for a bunch of circles is figuring out when circles are colliding with each other. For that, we can just use the check from the beginning of the article (distance_between(a.position, b.position) < a.radius + b.radius), using the tricks we know to make things more efficient and clean:

fn is_colliding(a: Circle, b: Circle) -> bool {
	let rad = a.radius + b.radius;
	a.position.distance_squared(b.position) < rad * rad
}

So given the two shapes we've talked about so far, the halfplane and the circle, plus the points that we've tested them with, we can calculate the following collisions:

	point	halfplane	circle
point	❌	✅	✅
halfplane	✅	✅	❌
circle	✅	❌	✅

Comparing whether two points are colliding is pretty trivial, since they are only touching if they're exactly the same, so to complete the matrix, we really just need to figure out how halfplanes and circles collide, which is pretty straightforward.

fn is_colliding(c: Circle, y_intercept: f32) -> bool {
	abs(c.position.y - y_intercept) < c.radius
}

More halfplanes

Let's go back to the halfplane example from earlier for a bit. Why was it necessary to limit it to perfectly horizontal and vertical halfplanes? What if we try to generalize to halfplanes of any slope rather than just the ones aligned with the X and Y axes?

Assuming that the edge of the halfplane is defined by two points p1 and p2, we can tell which side of the edge point d is on by finding the terms to the slope intercept definition y = mx + b. Hopefully you're brushed up on your grade school geometry/algebra:

fn is_above(d: Point, p1: Point, p2: Point) -> bool {
	let slope = (p2.y - p1.y) / (p2.x - p1.x); // m = Δy / Δx
	let intercept = p2.y - slope * p2.x; // b = y - mx
	(d.y - slope * d.x) > intercept
}

[TODO: plot]

Which, in this case, is [TODO: calculation], meaning d is below the edge. As you can see, this takes quite a few more operations than the axis-aligned case, and the division is particularly nasty, as it takes about [4 times as long] as adding or subtracting. If you're clever, you may also be worried about the case where the edge is vertical, when p2.x - p1.x == 0, which will result in a division by zero when calculating slope. To fix this, we can rearrange things to reduce calculations to two multiplications and four subtractions:

$${ \begin{align*} d_y - \text{slope} * d_x &> p_{2y} - \text{slope} * p_{2x} && \text{our original equation} \\ d_y - \frac{p_{2y} - p_{1y}}{p_{2x} - p_{1x}}d_x &> p_{2y} - \frac{p_{2y} - p_{1y}}{p_{2x} - p_{1x}}p_{2x} && \text{slope} = \frac{p_{2y} - p_{1y}}{p_{2x} - p_{1x}}\\ d_y - p_{2y} &> \frac{p_{2y} - p_{1y}}{p_{2x} - p_{1x}}d_x - \frac{p_{2y} - p_{1y}}{p_{2x} - p_{1x}}p_{2x} && \text{add terms to both sides}\\ d_y - p_{2y} &> \frac{p_{2y} - p_{1y}}{p_{2x} - p_{1x}}(d_x - p_{2x}) && \text{factor out slope}\\ (p_{2x} - p_{1x})(d_y - p_{2y}) &> (p_{2y} - p_{1y})(d_x - p_{2x}) && \text{this is actually illegal?}\\ \end{align*} }$$

So it turns out you're not supposed to do that last part because multiplying both sides of an inequality with a negative number will flip the inequality, and since we don't know whether ${p_{2x} - p_{1x}}$ is positive or negative, we can't know whether or not we have to flip the inequality. My solution to this is to simply invert the result when ${p_{2x} - p_{1x}}$ is negative, resulting in the following function:

fn is_above(d: Point, p1: Point, p2: Point) -> bool {
	let check = (p2.x - p1.x) * (d.y - p2.y) > (p2.y - p1.y) * (d.x - p2.x);
	check != (p2.x > p1.x) // != is functionally identical to a boolean XOR
}

That was a lot more work than the axis-aligned case, and even after all that, it's still quite a bit more computationally intensive.

for the future

I do all of my game development these days using Bevy, which has plenty of physics extensions, but I was under the impression that my use case was esoteric enough that it would make sense to implement my own in order to have fine control over efficiency. However, it seems that many of the existing libraries use similar ideas under the hood.

collisions
- all the fun collision shapes and the stackoverflow posts I got them from
nudging
- i want to refactor this.
im a little concerned about the unused height axis, but itll probably be fine. but what if I want an attack used on a bridge to not affect any units under the bridge? and what if I do want it to affect them?
turn speed limiting https://youtu.be/K1bQuMnMqKY?t=546
- quaternions

Up next:

🔀 State machines - Creating a state machine scripting language to implement spells for a MOBA

↹lature

Unknown — Tue, 26 Mar 2024 00:00:00 +0000

From the README:

↹lature is a tracker-style DAW. Its most unique features include:

First-class support for Open Sound Control
CLAP plugin support
Terminal UI
Keyboard-focused workflow with Kakoune/vim style keybindings
Headless mode for portable playback on a SBC or dedicated live performance machine
A directly editable, git-friendly file format

An optional aside regarding Bitwig's modular environment

Around 2017, I was reverse-engineering the Bitwig Studio internal device files to try and create my own version of the modular environment that they had been teasing since before the 1.0 release. Screenshots of it are hard to find, but there's one at the bottom of [this article](https://sevish.com/2016/microtonal-music-in-bitwig-studio).

Bitwig stores its device files in /opt/bitwig-studio/Library/devices on Linux, and in some old macOS versions, they stored them in JSON format. Though the binary format is (as far as I know) completely bespoke, it is vaguely reminiscent of BSON.

One of the other interesting things that they were doing before 3.0 was embedding their own (JIT?) compiled language called Nitro. As far as I know, there exists no documentation for it online, and I am hesitant to post any example code since basically all existing Nitro code is copyrighted by Bitwig, but it basically looks like C with some special plumbing keywords.

Anyway, I had at some point reverse-engineered it to the point that I could create my own devices with their own UIs! The import process was a bit hacky, and there was a tedious process of dragging and dropping every time I opened Bitwig to ensure that the devices were properly loaded when opening existing files, but I had achieved my goal of having a modular environment where I could make Bitwig devices (though UIs had to be written manually in JSON). My first device was a "notepad" device that was basically just a text box for writing notes in a track.

Fast forward a few months, and Bitwig 3.0 is released, along with some very cool new devices, including "The Grid". The Grid was a more abstract, "friendly" interface that I assume is meant to act as a substitute for access to the real modular environment that they use internally to create their native devices, with the target audience leaning more toward musicians than programmers. Notably, it lacked any tools for creating inline UIs or doing frequency-domain processing (though I have heard rumors that these features are coming at some point in the near future).

But worse (for me), the devices files in the new version were all encrypted (I think). This meant that any new devices released from then on were completely inaccessible to me. While this wasn't too big of a deal since I wanted to make my own devices anyway, this reminded me that this sort of introspection into the inner workings of Bitwig Studio isn't necessarily something Bitwig Gmbh the corporation appreciates. The company's goal is, by definition, to make money, and one of the main ways they do that is by creating new devices that users need to buy additional updates to access. If there were some pack of homebrew devices, this would make it harder for them to sell updates.

I don't harbor too much ill will towards Bitwig, and there are myriad potential reasons for doing this that aren't in conflict with my goals (and are, in many cases, in sync):

They want to prevent their future DSP from being accessible by competitors like Ableton
They might have been getting support requests from confused people trying to use my tool without realizing it wasn't an official Bitwig tool (I tried to match the Bitwig color scheme with my device editor tool, which in retrospect, was a poor choice)

The true reason(s) I can only speculate about, but either way, I had learned a lot about programming practices and tools from this adventure. pytwig (the library I made that I assume Bitwig is OK with because they haven't asked me to take it down yet) was my first "real" programming project used by people other than just me, and while there's nothing specific to this project that enabled that (perhaps I could have pursued VST development instead to the same effect), I think it gave me the confidence I needed to execute on a project that better represented my own vision.

Fast forward a few more years: free-audio (backed by Bitwig and u-he) releases the CLAP specification, a C-based API for creating audio processing devices. (That's a surprise tool that can help us later)

Honorary mention (but not technically relevant to ↹lature (yet)): dawproject, a DAW interchange format.

motivation

Features that I want in a DAW:

text-based save files
- better git-friendliness
- readable/editable in a text editor
modal editing
- first-class keyboard-only workflow
- ideally in a TUI
can play audio on a raspberry pi
the features listed at the top of this article
screen reader compatible
package manager for parts that are non-redistributable due to copyright
documentation for music (comments in the file, UI elements inline with the plugin chain where you can write stuff)
capable of integrating a voice synthesizer into the software

Reaper comes really close, but I think only technically. I feel like it doesn't fulfill the spirit of text-editability, and the modal editing only comes with a plugins like reaper-keys or reaper-nvim. I think in order for a keyboard-only workflow to be actually usable, you have to really rethink what exactly the needs of a DAW are.

The subtext for all of these features is that fundamentally, I want this DAW to be one that panders to my every whim. No matter how ridiculous the feature, if it's something I want, it should be something this DAW does. If these requirements don't speak to you the way they speak to me, you're probably better off using Bitwig or Reaper (both very good DAWs that I still use!).

general design philosophy

UI should be limited in scope to a few of the most heavily used parts of the interface
similarly, common actions should be bound to the easiest keybinds, and uncommon actions should only be accessible by command line
all actions should be accessible by a "scripting" language
actions should be easy to type quickly for the "normal" case, but should be configurable (with optional parameters) for esoteric cases

prior art

FOSS DAWs

TUI music software

Orca
Cacophony (not technically TUI, but certainly TUI-esque)
midiTracker
any livecoding tool with a CLI REPL or a plaintext file format + hot reloading

trackers

1987 - the ultimate soundtracker
1989 - OctaMED
1990 - Future Composer
1990 - Digital Mugician
1993 - FastTracker 2
1994 - ScreamTracker 3
1995 - Impulse Tracker
1997 - OpenMPT ()
2002 - Renoise
2005 - MilkyTracker ()
2005-2015 - FamiTracker (source)
2006 - SchismTracker ()
2008 - SunVox (open core?)
2009 - Sonant
2011 - DefleMask
2015-2018 - 0CC-FamiTracker ()
2018 - zytrax ()
2018 - sointu ()
2018-2020 - j0CC-Famitracker ()
2018 - Reality Adlib Tracker ()
2019 - ft2-clone (clone of FastTracker 2) ()
2020 - Dirtywave M8
2020 - bintracker ()
2020 - Dn-FamiTracker ()
2021 - Furnace ()
2021 - protrekkr ()
2024 - WaveTracker ()
2024 - pl_synth ()

devlog

Controller support

Controller support is implemented using JACK. I initially used midir, but I couldn't figure out how to synchronize notes within the buffer. While the approach that minimizes average latency would be for all the notes to trigger at the beginning of the audio frame, I have heard that psychoacoustically, stable jitter is more important to playability than latency. Plus, at large buffer sizes, having all the messages in a frame trigger at the beginning would likely be noticably distracting.

To implement this, I first add an additional port to the JackProcess struct:

pub struct JackProcess {
	// ...
	in_port_midi: jack::Port<jack::MidiIn>,
}

Then search for a controller and connect it to the port:

for ea_port in active_client.as_client().ports(None, Some("8 bit raw midi"), jack::PortFlags::IS_OUTPUT) {
	if ea_port.contains("HXCSTR") {
		log::debug!("found port {ea_port:?}");
		active_client.as_client().connect_ports_by_name(&ea_port, &format!("{}:midi_in", active_client.as_client().name()))
			.expect(&format!(r#"Could not connect ↹lature midi input to "{:?}"."#, ea_port));
	}
}

Lastly, read the input port in the process loop, adapting the push_event function that I use for auditioning cells:

for jack::RawMidi { time, bytes } in self.in_port_midi.iter(ps) {
	if bytes.len() == 3 {
		let msg = OscMessage {
			addr: "/HXCSTR".to_string(),
			args: vec![OscType::Midi(OscMidiMessage {
				port: 1,
				status: bytes[0],
				data1: bytes[1],
				data2: bytes[2],
			})],
		};
		pd.push_event_root((time as u64, msg));
	}
}

Note that the controller search and OSC message are hardcoded with the string "HXCSTR". Ideally, I'd have both a configurable method to automatically connect controllers as well as a manual menu system in the TUI to set up such connections.

I added controller support so I could practice playing HXCSTR, which unfortunately only supports MIDI at this point in time, but OSC support would likely be similarly trivial.

Chain view

Hypothetically, the entire audio graph can be represented as a list of nodes and the connections between them, where you can see each sound processor as a little "block", and their ports are routed explicitly into each other. However, most DAWs instead have a channel-based workflow, where sound processors are on one of many channels, and the audio from one flows into the next in the series. One of the driving forces that I think about when designing interfaces is to try to make the common use cases easy and clear, and relegate the uncommon use cases to more laborious and obscure parts of the interface. In the case of the audio graph, it is very common for signal chains to be considered on a per-instrument basis, where one set of notes is piped into an instrument processor followed by effect processors. This maps very neatly to the channel-based topology, and as such, I chose to try to preserve that in ↹lature.

The solution I came up with was the "chain", where a Block is a container for a series of Processors. I was struggling with a good way to draw the chain in a way that was scrollable, and this is one of the parts where making ↹lature TUI-based caused some friction in the implementation.

I mostly copied the default behavior of panning in [niri], but for those not familiar, in broad strokes, the requirements were these:

The selected processor should always be fully visible (if possible)
The chain view should not pan if it does not need to (including when blocks are deleted or resized)

I faffed about a bit for a working solution, but ended up with this:

let frame_width = f.size().width as i32;
// clamp cursor to chain length
self.cursor = self.cursor.min(constraints.len() - 1);
// get the x offset and width of currently selected processor
let cursor_x_offset = constraints.iter().take(self.cursor).sum::<u16>() as i32;
let cursor_width = constraints.get(self.cursor)
	.expect("bounds check should clamp cursor to a valid index of constraints");
// this calculation determines the view offset
self.offset = self.offset.clamp(cursor_x_offset + *cursor_width as i32 - frame_width, cursor_x_offset);

let mut idx_offset = 0;
let mut x_offset = 0;
// because it can be partially cut off, we must calculate the width of the leftmost visible processor
let first_width = loop {
	match constraints.get(idx_offset) {
		Some(width) => {
			x_offset += *width as i32;
			if x_offset > self.offset {
				break (x_offset - self.offset) as u16;
			}
			idx_offset += 1;
		}
		None => unreachable!("offset should not go past end of chain")
	}
};

CLAP TUI extension

source code

TODO: elaborate

Replicon

Unknown — Thu, 01 Feb 2024 00:00:00 +0000

Replicon is a bevy-centric interface built on top of the renet networking library. It provides some derivable traits and bevy plugins to apply to your game in, ideally, a very modular and straightforward way.

NOTE: for the following, I'm using bevy version 0.11

First task: Headless dedicated server

In the various bevy networking libraries I've evaluated, the examples tend to be for a "main" client that also performs the role of a server, and "sub" clients that hook into that main client's server to connect to each other. While that's neat, in my case, I want my server to run headlessly on an always-on computer, so for me, it would be nice for the server-side to be in a separate binary with no UI or input functionality. Adapting an example to do this also seems like a good way to learn more about the library.

Turning off display

The bevy repo has a nice example for headless operation.

The important part is:

let refresh = Duration::from_secs_f64(1.0 / 60.0);
MinimalPlugins.set(ScheduleRunnerPlugin::run_loop(refresh))

Though there are some plugins in DefaultPlugins that are required by some of the plugins like rapier-3d that I'm using for server-side game logic checks.

let refresh = Duration::from_secs_f64(1.0 / 60.0);
let app = App::new()
	.add_plugins(DefaultPlugins.build().disable::<WinitPlugin>())
	.add_plugins(ScheduleRunnerPlugin::run_loop(refresh))
;

Refactoring

In preparation for networking my existing game, I reorganized most of my game logic for better separation between the parts that are going to be on the client and server. In the end, of the systems I've implemented so far, there are going to be:

some that run in the client, ex: input handling
some than run in the server, ex: determining when the game is over
some that run in both, ex: most of the game logic

For the most part, I use const generics so that I can keep the number of structs relatively low:

pub struct PlayerPlugin<const IS_SERVER: bool>;

impl<const IS_SERVER: bool> Plugin for PlayerPlugin<IS_SERVER> {
	fn build(&self, app: &mut App) {
		app
			.add_systems(
				Update,
				(
					tick_player.before(bevy_mod_wanderlust::movement),
					ocean_kill,
					draw_gizmos,
					tick_unit,
				).run_if(in_state(GameState::Playing)),
			)
			// ...
		;

		if IS_SERVER {
			app
				.add_systems(
					Update,
					(
						player_events_server,
						confirm_projectile,
					).run_if(in_state(GameState::Playing)),
				)
			;
		}
		else {
			app
				.add_systems(
					Update,
					(
						player_init_system,
						player_events_client,
						tick_player_spell,
					).run_if(in_state(GameState::Playing)),
				)
			;
		}
	}
}

After doing this, I was able to add replicon with relatively little friction. Of course, it didn't work at all straight out of the gate, but at the very least, it compiled. Usually, with a Rust program, that would mean it's mostly working, but I think part of the tradeoff that Bevy makes is that it does a lot of stuff (running systems, managing components) dynamically, so some of Rust's strong typing advantages aren't quite so prominent in their API.

This results in a bit of a strange pattern:

fn player_events_server(
	mut commands: Commands,
	mut player_events: EventReader<FromClient<PlayerEvent>>,
	mut players: Query<(Entity, &UnitId, &mut PlayerState, &mut UnitStateSync)>,
) {
	for FromClient { client_id: _, event } in player_events.iter() {
		player_events_helper(true, event, &mut commands, &mut players);
	}
}

fn player_events_client(
	mut commands: Commands,
	mut player_events: EventReader<PlayerEvent>,
	mut players: Query<(Entity, &UnitId, &mut PlayerState, &mut UnitStateSync)>,
) {
	for event in player_events.iter() {
		player_events_helper(false, event, &mut commands, &mut players);
	}
}

fn player_events_helper(
	is_server: bool,
	event: &PlayerEvent,
	commands: &mut Commands,
	players: &mut Query<(Entity, &UnitId, &mut PlayerState, &mut UnitStateSync)>,
) {
	match event.event_kind {
		PlayerEventKind::Spawn(id) => {
			if is_server {
				commands
					.spawn((
						PlayerBundle::new(id),
						Replication,
					));
			}
		}
		PlayerEventKind::StartAction(idx) => {
			if idx > 4 { return }
			if let Some(mut player) = players.iter_mut().filter(|ea| *ea.1 == event.id).next() {
				player.2.spells[idx].1 = SpellState::Cast;
			}
		}
		PlayerEventKind::FinishAction(idx) => {
			if idx > 4 { return }
			if let Some(mut player) = players.iter_mut().filter(|ea| *ea.1 == event.id).next() {
				player.2.spells[idx].1 = SpellState::Release;
			}
		}
		PlayerEventKind::Moving(dir) => {
			if let Some(mut player) = players.iter_mut().filter(|ea| *ea.1 == event.id).next() {
				player.3.direction_input = dir.clamp_length(0.0, 1.0);
			}
		}
		PlayerEventKind::Facing(dir) => {
			if let Some(mut player) = players.iter_mut().filter(|ea| *ea.1 == event.id).next() {
				player.3.direction_input_2 = dir.clamp_length(0.0, 1.0);
			}
		}
	}
}

Server to client

There are three things you have to do for a bevy Entity to be replicated from your server to your client:

Implement serde::{Serialize, Deserialize} for the Component
Mark the compenent as replicatable by using App::replicate() when instatiating your app
Instantiate the Entity on your server with Replicon's Replication component

To send events from the client to the server, you follow three similar steps:

Implement serde::{Serialize, Deserialize} for the Event
Mark the event as one that should be sent using App::add_client_event(EventType)
The event can be sent using the usual EventWriter<YourEvent> parameter in your client system, but to read these from the server system, you use EventReader<FromClient<YourEvent>>, which wraps the event and bundles it with the client_id

Client to server

For some game events, letting the client send an event and just waiting until the server processes it and sends back a replicated entity is fine, but there are many actions that should be much more responsive, like movement and abilities. Unfortunately, the server will not replicate entities created on the client. After spending an hour perusing through various Overwatch videos to understand better how their netcode works, I found the solution in the Replicon documentation after looking for just a few minutes.

The resource ClientEntityMap allows you to connect an entity on the client with an entity on the server to synchronize with.

Usage is fairly straightforward:

Create the entity on the client
Send the Entity (a simple ID for the entity for use locally in the client's ECS) to the server, for example by using an event
Once it receives the Entity, the server creates a similar entity with all of the components that should be replicated across the server and all the clients
Use ClientEntityMap::insert to connect the client Entity with the server Entity (you only have to do this for the client that created the original entity, as the other clients should use the server's entity instead)

For example, I have a projectile that gets instantiated in certain conditions. It is implemented with a cast function that handles all the logic for it, and returns a SpellEvent::Projectile(Spell, UnitId, Entity) where Spell and UnitId is information that the server needs to identically run the cast function on the server side, and the Entity that the client created so that it can connect it to the Entity that the server makes.

TODO:

I have a bug where two projectiles are created when two clients are connected to the server when only one should be created
How should non-deterministic events be handled? For example, the random spread of a shotgun-like projectile
Need to test on a high-latency connection to make sure that the projectile is not rubber-banded on the client side (or at least, any rubber-banding is minimal)
Use replicon_snap to interpolate instead of just hard snapping

Monthly Log 2024

Unknown — Thu, 01 Feb 2024 00:00:00 +0000

01 - January

tlature

Did some refactoring around Commands so that I could:

Map commands like :wq to multiple edits
Make App-level commands, like :? to open the help dialog
Add tooltips to subcommands like :add, which are not commands in themselves, but rather components of other commands like :add plugin or :add block

Bevy Replicon

Did a cursory evaluation of a bunch of bevy networking crates. Decided to use Replicon for my current game, and wrote about the process of integrating it:

🌐 Bevy netcode - Exploring various online multiplayer solutions for the Bevy game engine

Replicon

02 - February

tlature

I probably should've been taking notes on what I'm working on while I was working on it, but in lieu of a more thorough description, here's a summary of my git log:

Add better RouteView and PluginView panels, including parameter editing
Add chain view scrolling: Instead of squeezing every processor on the page, chain view panels now have a fixed width, and the ones that don't fit aren't shown until the selection moves offscreen.
Add base64-encoded plugin state for non-UTF-8 plugin state bytestreams

FediCard

Nash and hexephre from labyrinth.social made a little tool for creating FediCards! It's built using Godot, which is really neat, but in the comments, there seem to be a few issues when running on some browsers and OSes.

To that end, I've been playing around a lot with web technologies, and in particular, HTML and SVG. In my naïveté, I figured I'd be able to whip up a quick browser-based editor to provide a more compatible (albeit less functional) companion application. Check out the proof-of-concept here

Problem 1

My first instinct was to make an SVG file that gets edited, and directly export that. After hand-minimizing an SVG file and defining all of its style in CSS, I ran into issues with HTML <input> tags embedded in the SVG data.

In retrospect, I could've probably rigged up some sort of Javascript shenanigan, but at the time, I was hoping to get away with as little Javascript as possible. So I converted all of the SVG rectangles to <div> tags.

Problem 2

There's no way to resize the <textarea> dynamically based on its contents with just HTML. My solution to this problem was to ignore it.

Problem 3

After adding some controls for zooming into the image, I ran into an issue where the zooming was causing the image to exceed the bounds.

I turned the img tag into a <div> because I have no idea what I'm doing and the internet told me that would work. And it did.

Rowing machine mod

A while back, I found a used rowing machine on craigslist. It was in really good condition (still had the plastic screen protector, and clearly hadn't been used that much). I've been using it pretty regularly, and for the most part, I'm happy with it, but there's one issue that's been bugging me: after ~3 minutes of inactivity, the screen resets, and does so with almost no warning.

Obviously, the only solution is to reverse engineer the device so that I can build my own distance tracking device. And because the original head unit is mounted to the machine using a VESA mount, this has the added benefit of letting me mount a screen and speakers instead, so I can more comfortably watch stuff while I exercise.

Finding pinout

First step was to figure out what all the pins did. I took apart the head unit, and looked at the board to figure out what did what.

Then I probed the pins to check for voltages and any discernable signals. Under the assumption that the black wire was ground, I found pins with 9 volt and 3.3 volt signals, which I just assumed were power, but other than that, the only other pins I could identify from the 10 total pins were a pair of differential signals.

Next step was to open up the body of the machine. In retrospect, I shouldn't have wasted any time with the head unit, because everything I needed to know was in here. There is a small cylindrical sensor pointing to the air resistance wheel, and after following its wires back to the cable harness, I probed it to find that its resistance dropped when it got close to a magnet mounted on the air resistance wheel. With this, I could just treat it like a pull-up switch and use it to count revolutions.

Building on a perfboard

These days, it's really easy and cheap to get a custom PCB made. With excellent FOSS tools like [KiCad], there are very few excuses to not make a PCB. My excuse in this case was that I wanted to get this running within a few days.

TODO:

add pics
adding power switch after building the board
alternate mcu pins
reverse mount headers
embassy i/o interrupts
48 revolutions with interleaved i2c
210 when doing one every 10 buttons (maybe because of debouncing or noise? should try with hysteresis)

Next step is to get some sort of speed detection going, but in it's current state, it does everything I need it to, so I suspect that I won't get around to doing anything like that for a while.

Monthly Log

I don't want to complain too much because the fact that I've been able to do 6 months (wow!) of monthly logs without missing any by more than a day or two has far exceeded the expectations I had when I started, but I think I still haven't quite found a good "voice" for blogging yet. Plus, my posts are a bit slapdash and dry, and tend to just say "I did this, then I did this, so I had to do this", rather than outlining any actually useful perspectives or processes, or building an interesting narrative. I had also hoped to use these logs as an opportunity to practice my German, but I've yet to translate any of them yet. Maybe next month.

03 - March

Controller support for ↹lature

more bevy replicon stuff

Tried a few libraries for rollback/snapshot netcode:

bevy_timewarp
- no examples, documentation is pretty rough
bevy_replicon_snap
- seems very immature, got a lot of weird behavior at high latencies. (Tangentially, tc qdisc add dev lo root netem delay 200ms is a fun command)

Overall, I spent way too much time spinning my wheels and have very little to show for it. I spent the last day of the month basically undoing most of my changes to revert it back to being a local-multiplayer game. I'm also trying to refactor it to make more sense, but seeing how I have very little experience, it's pretty tough. I think I might just start from scratch on a simpler game, with more focus on game mechanics and playability rather than spending so much time on high-complexity features like scriptable abilities and multiplayer. Maybe even enter a game jam or something.

blender mod

bought a $30 blender on craigslist because i was tired of holding down the cup on my smaller personal ninja blender
fool that I am, this one you have to hold down the button, so I still can't walk away from it while blending
so i soldered a toggle switch on it in parallel with the momentary switch
fortunately, it was easier to take apart than my old smaller blender
i once again forgot to take pics
super easy modification that i think anyone can do to almost any blender

04 - April

Mostly game development this month:

🧙 Spell Scripting - Creating a state machine scripting language to implement spells for a MOBA

⭕ Circle physics - A physics engine specifically for real-time strategy games

But also a bit of ↹lature:

↹lature - devlog - Implementing a niri-like signal chain viewer

Monthly log

It is the 27th of May, and I am just now uploading my log entries for April. I originally intended to write and post my logs while I was travelling at the beginning of May, but that just didn't happen at all. On the bright side, I spent basically the whole day yesterday revamping and reorganizing the wiki, hopefully in a way that makes it easier to write for. I'm also really proud of the two articles that I did end up with, and think that they're some of my best.

05 - May

Went to Montréal for Open Hardware Summit.

Additional wiki features:

This website - Adding shortcodes to my Zola template
Wrote two small tools for using my HP ZBook X2 G4:
- flourish, a touchscreen gesture launcher. Currently needs to be run as root, which makes it almost useless because then it can't launch things or modify niri.
- hp-quick-keys, a launcher than listens to the "quick keys" on the ZBook, which are exposed as a USB Human Interface Device. This works much better since it doesn't require root. TODO: talk about the different gestures and how they're measured
Added magnetic feet to my keyboard (TODO: pics)
I've been "falling behind" on my self-imposed monthly "schedule", which I think means I should be making smaller posts and updating them more often

06 - June

Documented an old project (mostly taking pictures):

❤️ Life Counter - Device for keeping track of an integer value in a tabletop game

research screenless computer
research persistence of vision vibration sculpture
start programming esp32s (again)
inline latch for cardboard boxes (downloadable 3D print to be added)
tlature transport refactor
planned out a more elaborate bed desk with overhead rails
increased the font size on my rowing machine display

07 - July

Got DAC output working on a Raspberry Pi Zero for screenless computer
Fixed my rowing machine: the strap broke, so I replaced it with some cheap webbing I got off Aliexpress, which also broke. Bought a nicer nylon webbing (also from Aliexpress), and that worked a lot better.
Made a Gaussian curvature visualization script for Blender. My plan is to eventually adapt this into a plugin that flattens faces to make them zero curvature for papercraft and acrylic bending purposes.
wifi-button: made a PCB and played around with MDNS on the ESP32
Made a swatch to see how different layers interact on a PCB to use it in PCB art
Started working on a TUI extension for the CLAP plugin format

08 - August

Swatch PCBs came in, turns out they decide whether to remove silkscreen from areas with no mask on a case-by-case basis.

🟩️ PCB swatch - Color and pattern test for PCB art

Life counter
- Touched up the PCB last month, and tested the new boards this month after they came in.
- Turns out the STM32 has about a megaohm between its GPIO pins and ground, which messes with the enable input of the load switch im using. I wanted the buttons to pull down and have the load switch input low enable, but it seems like that would require a bunch more diodes.
- Cleaned up the art file, will make a script that turns the cleaned-up version into a set of KiCad files.
- Made an inkscape extension that I intended to use for this, but I ended up using the GIMP newspaper filter and tracing the bitmap instead. Looks very comic-y.
- (TODO: elaborate, clarify, document in life counter article)
Wifi button
- Assembled, doesn't work very reliably, partially because of the wifi antenna.
- LED driver was a bit of a pain; using the same one in the life counter
Someone sent me some contributions to tui-nodes! Didn't expect it, and the changes were well done and much needed, so it was a very pleasant surprise. It was also my first time using git-am, which was very enlightening. I now realize that I need to migrate to meli as soon as possible. But also, the mail service I'm currently using doesn't seem to let me send emails from my domain (though receiving seems to work fine, so git-am should work fine for now as long as I don't need to request changes).
Made a single DDR pad. TODO: write an article about it sometime this month. Will be tough because I neglected to take pictures.
Screenless computer
- Couldn't get the hifi DAC that I was using on my Raspberry Pi Zero to work on my Orange Pi Zero 2W.
- Gonna work on the software side for now while that simmers. Made a quick mockup with speech-dispatcher and jack. Next step is to playback samples (probably wanna load them into memory first, for the alphabet).
PoE
- Got a 5V output using a dedicated PoE ethernet jack and a Silvertel-esque module.
- Have been working with PoE injectors, which it turns out aren't actually compliant because they inject voltage regardless of whether the device requests it. Ordered a cheap PoE switch for testing.
- Also want to try out dual rail generation (i.e. both positive and negative voltage), so I ordered a transformer for that. I have no idea if it's going to work.
- Messed around with inductors
Tried to test some coils for reverse-engineering Wacom EMR pens, but it didn't work. Ordered a headless oscilliscope that should make things a bit more convenient. TODO: write article, or at least a linkdump

09 - September

wrote an article for how graph drawing works in tui-nodes to try to make things easier for contributors who want to improve that part:

Graph Layout Algorithm - Novel (i think?) algorithm for drawing a directed acyclic graph
- made a little program for drawing in a tui, but used a svg output instead for better compatibility: https://git.sr.ht/~jaxter184/woogie
Added modifier and release keybinds to niri. currently testing it to make sure it's working right before upstreaming, and I've already run into a few issues.
building a dead bug circuit for PoE
flashed a ch32 riscv chip, excited to try out ethernet on it

10 - October

Set up author tags for this wiki
- https://adventures-with-pi.blogspot.com/2024/10/setting-up-author-attribution-for.html
- https://rknight.me/blog/setting-up-mastodon-author-tags/
Tried to learn Elixir so I could develop crofu with it, but failed miserably:

crofu - Incremental converse crowdfunding platform

TODO: update crofu article with my takeaways
Made a board for use with SFP connectors so I can have an inter-board connection format. Would be nice if there was an inline connector version of it, but I think I've found a reasonable solution despite that. TODO: small writeup
More PoE dead bug progress
Reverse engineering the Dell Canvas totem. Turns out it literally just works by putting capacitive touch pads in a specific layout. TODO: small writeup

11 - November

Been playing an unconscionable amount of Overwatch because they've got a "classic" game mode replicating what the game was like when it was first released. I've missed Bastion's headshots and old ultimate so much.
Set up a RISCV microcontroller for a friend to use in their art project (different from the ethernet ch32 from September, but same flashing process)
Been working on a sculpture. Haven't documented it at all, but will probably try to by mid next week so I can put a little placard pointing to the article when I put it in a local show.
Made more progress with crofu using Axum:

crofu - Incremental converse crowdfunding platform
Made an attachment for my pants to mount my keyboard to. Still a work in progress.

December Adventure 2023

Unknown — Fri, 01 Dec 2023 00:00:00 +0000

December Adventure

I never really gel'd with Advent of Code. I think it's just not really for me. But while I didn't really enjoy the contents event itself, I think the premise is fun, and it's nice to be able to do something with a bunch of people who share similar interests with you. It is perhaps because of that desire that I immediately found myself on board with December Adventure as soon as I heard about it.

The December Adventure is low key. The goal is to write a little bit of code every day in December.

The project towards which I'm going to do my December Adventure development is the CLAP plugin library for ↹lature. While I'd love to do a brand new plugin each day (and I probably have enough ideas to get through the month doing that), the premise of the adventure seems to encourage low-key, consistent progress, so I'm going to aim for something a little less manic, and set my end-goal as developing a meaningful feature every day.

Watch my progress here: https://git.sr.ht/~jaxter184/tlature-plugins

Current list of plugins:

chord name to note generator
simple instruments
- sampler
simple fx
- filter
- compressor
livestock auctioneer physical model
- maybe even something as simple as a singing voice synth with a southern drawl
tools
- osc output
- automation
- adsr
- lfo
- step sequencer
- https://nimble.itch.io/catjammer

(Not intended to be exhaustive, just to show the general roadmap)

day 01

While this wasn't my initial plan, I spent basically my whole evening reorganizing the ↹lature plugin repositories. Today, I:

Renamed structs to make the plugins consistent with each other
Moved structs to make code easier to navigate
Combined the tlature-dev and tlature-std plugin repositories
Made a cargo-generate template for creating new plugins

While this is all a lot of really helpful preparatory work (renaming and moving structs was particularly time-consuming), I'm particularly excited about the template. It was surprisingly easy to make, and I'm looking forward to both using it myself and also asking people who expressed interest in the project in the past to try it out to see how difficult it is for them to use.

day 02

Did some organization on the main ↹lature repository to make it more sturdy. The goal is to be able to easily point people to a specific commit or tag where everything hopefully "just works".

The most on-track December Adventure thing I did was making an event-offset plugin that offsets incoming events in time and pitch. Well, not every event, just note events. Also it doesn't do anything yet, it just passes events through. That is, I think it does, but I can't tell because I haven't set up a way to test it yet. So I spent the rest of my day working on a ↹lature feature to be able to define event output files. It's not done yet, but once it is, it should be helpful for debugging plugins in the future.

But it's December Adventure! So falling off course and working on something completely different and then not finishing it is still a success!

day 03

Trying to create plugins for ↹lature has really pointed out all the flaws of its current state. I thought it would be easier to make event plugins instead of audio plugins because it would be easier to debug and test for, but it turns out that not only have I neglected to set up any tests, but I've also completely underdesigned all my event handling. I'm not totally sure what I'm doing going forward, but at the very least, I added a feature to convert CLAP plugin event outputs back into OSC messages, so I can confirm that the event-offset plugin does indeed work as I would expect it to in its current form (i.e. it passes the events through as-is)!

I'm really liking this whole December Adventure thing. The flexibility of being able to explore things at my own pace gives me space to breathe and give this stuff the time it deserves instead of churning out solution after solution.

day 04

↹lature is, by design, an OSC-powered DAW. Back when it was just a sequencer, that worked because all it had to do was generate notes and spit them out somewhere. But as the project grew into a more complete audio workstation, I decided that I wanted the sequencer to be "aware" of the downstream consumers of the messages, and once plugins were added, I also had to add some sort of converter between OSC and various CLAP events. Until now, I was able to get away with that because I was only doing the lossy conversion from OSC, a very flexible, generic message format, to CLAP events, which is more structured. So now that I want to convert them back, I'm not sure how to do it.

To illustrate, there are multiple OSC messages that can convert to the same CLAP event. /notes/v0 i 60 and / ii 0 60 both convert to middle C on the 0th voice. So if a CLAP plugin outputs a middle C, which of those OSC messages should it convert to?

The solution that I came up with is that it shouldn't. OSC conversions should only go one way. Maybe in the future it would make sense to set up some sort of conversion, but for now, the plan is that any plugin that wants to output events for ↹lature to send to other plugins should output OSC events only.

To facilitate this, I created an OSC message extension that provides OscEvent (that is, I copied the MIDI SysEx event format from regular CLAP and changed some names). It essentially consists of a buffer that is written to and read from using the rosc encode/decode functions.

Behold!:

fn process(
	&mut self,
	_process: Process<'_>,
	_audio: Audio<'_>,
	events: Events<'_>,
) -> Result<ProcessStatus, PluginError> {
	for ea_event in events.input {
		events.output.try_push(ea_event).unwrap();
		let packet = rosc::OscPacket::Message(rosc::OscMessage { addr: "test".to_string(), args: vec![] });
		let buf = rosc::encoder::encode(&packet).unwrap();
		let (ptr, len) = (buf.as_ptr(), buf.len());
		std::mem::forget(buf);
		let osc_event = OscEvent::new(
			EventHeader::new(ea_event.header().time()),
			0,
			unsafe { std::slice::from_raw_parts(ptr, len) }, // SAFETY: leaks are safe
		);
		events.output.try_push(osc_event).unwrap();
	}

	Ok(ProcessStatus::ContinueIfNotQuiet)
}

if let Some(ev) = ea_event.as_event::<OscEvent>() {
	let map = pd.event_map.entry(ctx.clone()).or_default();
	let packet = rosc::decoder::decode_udp(ev.data()).unwrap().1;
	match packet {
		OscPacket::Message(msg) => {
			map.push((ev.header().time().into(), msg));
		}
		OscPacket::Bundle(_) => todo!("handle OSC bundles"),
	}
}

There are a lot of things that aren't great about the code above (memory leaks, allocation on the audio thread, ignoring bundles), but those are problems for future me to solve.

day 05

(When reading the following, it may help to know that Location is more or less just a reimplementation of PathBuf that uses String instead of OsString. If that isn't clear, just think of Location as a string that represents a path, like /home/jaxter/music/ninja_tuna.flac)

I think the most difficult thing with ↹lature so far has been deciding how routing works. The general philosophy is as follows:

routing should be easy to understand if explained properly
Locations should be generally analagous to paths on a filesystem, and the routing syntax should reflect that
for people editing the project file directly (for example, in a text editor), opportunities for error should be minimized
the "royal road" should be encouraged by the syntax, generally by making it short and simple compared to less common alternatives
the actual logical code for routing should be relatively simple, with few edge cases

I believe the current method achieves this, though perhaps not to the extent I would like. That being said, having added OSC outputs to plugins has shown me the flaws of my current scheme, so I made a few additions to adjust the routing behavior. Currently, the process data is structured roughly like this:

ProcessData {
	audio_map: BTreeMap<Location, AudioBuffer>,
	event_map: BTreeMap<Location, Vec<rosc::OscMessage>>
}

In this case, there are two places that can represent the "path" of the event: the Location key in event_map, or the rosc::OscMessage, which contains an address field. The changes I want to make are to resolve an ambiguity as to whether the new path should be reflected in the ProcessData event_map key or in the OSC message's address. I've decided for now that the event_map key of any newly routed message will simply the current context (that is, the path of the parent block), and the rest of the path will go in the OscMessage address. I'm a little hesitant to split it up like that because it makes matching message paths difficult later down the pipelite, but chances are, it will need to be refactored again soon anyway, so I'm fine leaving things a little messy and placeholder-esque for now.

All of that planning aside, the only change I made today was to reflect this design in the loop that gets the events of Processor::Plugin.

day 06

After making the changes yesterday in the Processor::Plugin processing, I had to change Processor::Route behavior to be consistent with it, which broke some tests. I think in cases like these when I make some weird change that might affect behavior, I'm really appreciative of my past self for setting up these tests to give me a more clear path to things working as they should. I wish I had the energy today to describe this particular case where I benefitted from a test, but for now, I will just say what has been said many times, and more persuasively by many others: write unit tests for your code!

day 07

Honestly not sure why I thought I needed OSC support in order to make an event offset event. I can just make ↹lature pass note events to downstream processors. Maybe I just wanted to not deal with implementing both an OSC channel and a CLAP event channel, and just only dealing with OSC events?

Anyway, today I just added some logic for handling CLAP NoteOnEvents in addition to OSC events.

Things have been slowing down, and I'll probably skip tomorrow to do some non-computer-touching stuff. I'm a little sad that things haven't been as adventurous as I had hoped when starting December Adventure, but I'll be ambiently thinking about how I can shift my progress to be more exploratory going forward.

~~TODO:~~ Implement CLAP event channel routing

day 08

(rest day)

day 09

As alluded to in day 07, the thing about December Adventure that I like the most is the idea of exploring a little bit of a fun idea every day. The most recent few days have felt like a lot of slogging in place, and I was hoping to get out of that funk, so I've expanded the scope to be anything ↹lature-related rather than just plugins, with a priority on fun new features that I don't see in a lot of music software or TUI programs.

First on my list is a file/string picker pop-up. While common in music software, it's not so common in TUIs, so there are a couple interesting things to think about when it comes to the design. But before working on the feature itself, I first need to figure out how my GUI is going to work in general, in particular how various elements are created/activated. Two organization methods that I've run into in the past are stacks and layers. With stacks, you push and pop overlays, and with layers, you activate and deactivate overlays. The main difference is that with stacks, overlay order can be dynamic, while with layers, overlay order is fixed.

When it comes to the interface, it should be easy for the end user to be able to tell how their actions will translate to actions in the software before they actually perform them. A stack throws a wrench in this understandability, because with a given screen, there may be 3 different overlays, plus something going on in the status bar. Rather than using something like color or highlighting to show what is currently focused, I think making the layer order fixed would train people to instinctually know what's focused by assigning a sort of "priority" to each type of overlay. For example, if a help dialog always has higher priority than the numerical argument input, then you know that if you see a help dialog, you can't perform any num arg inputs. Things get a little tougher with the command bar, because it's pretty subtle whether or not its active from just the command input itself, so adding a command info dialog and autocomplete assistance menus will make it clearer that the command entry is actually active.

I did a bit of messing around to see what things would be like in terms of implementing each, and I decided that while both have their flaws, I like layers slightly more.

One thing that makes it difficult is that I want overlay state like the numerical argument and replacement values to be a dynamic "variable" rather than a statically define Rust struct, with the goal of making it more accessible from the hypothetical future scripting language. I implemented rhai support in the past, but removed it because I didn't like how I had to structure the application state to accommodate it, so maybe it's worth considering removing that entirely.

~~TODO:~~ Implement layer UI
~~TODO:~~ Add string picker pop-up

day 10

Spent all day today spinning my wheels trying to figure out how I should refactor layers to work. I think I'm going to abandon this for now and come back to it after December Adventure ends. (Update: I did not abandon this, and it now works pretty ok)

day 11

Not even sure what counts as December Adventure anymore, but spent the evening configuring Zellij. It's a pretty neat piece of software, and while there are a couple things that annoy me about it (mostly visual clutter), I learned a lot of things that seem to be very helpful for higher-level planning for ↹lature.

While not intentional, it really helped me solidify a big decision with ↹lature: session management. I have two choices when it comes to managing ↹lature sessions: I could do it all internally, and have the program itself organize the various panels and windows and tabs, or I could hook into the window/session management of some other program.

Just to give a run down of what exactly I mean by session management, there are various programs that manage different workspaces/windows/sessions:

Kakoune has a concept of "buffers", which are basically all the documents you have open, plus a few extra scratch areas where you can do things like peruse the various references of an identifier to goto, or see debug information, and all of the buffers are associated with a session, which can be used to connect a different client to the current set of buffers.
Bitwig has tabs, which can each have a project, similar to a web browser.
Sway, my window manager, can organize windows in various ways, but the most basic method is tiling windows into various panes, which show up side-by-side.
Zellij has pretty much all of these: panes fit into a tab, and tabs are hosted in a session, which a seperate Zellij client can connect to.

I hadn't really given too much consideration, and assumed that I would be implementing this myself in ↹lature, but it seems like Zellij has enough functionality (through things like zellij action) for ↹lature to be able to integrate pretty seamlessly with it (given an appropriate configuration).

There were also a couple other things that exploring Zellij helped with. Being a TUI Rust program, it runs into many of the same restrictions that ↹lature does, but compared to Helix (another TUI Rust program), there were a few aspects of Zellij's approach that I liked more, particularly with regards to keymapping, mode management, and plugins, all of which I'll probably talk about as December Adventure continues. Also, it uses KDL!

Despite not having even looked at any ↹lature code today, I made a lot of progress on it! While I'd like to say that it was all part of the plan, and that December Adventure put me in an exploratory, casual mindset that led to me making the decision to take a step back and just check out some other stuff, that's not really what happened. I just happened to check out Zellij on a whim, and it just happened to be really helpful for getting a better idea of what I want ↹lature to be. That being said, I'm pretty sure I wouldn't have tried Zellij if I was doing Advent of Code right now.

day 12

Recently, a friend started working on a Discord bot, and it made me jealous, so I decided to go fix up the bot I made for ↹lature. My bot was pretty simple: you'd send it a message, and it would reply with a rendered .wav of the output.

The main thing I had to do to fix it was to migrate the rendering code to use the new ProcessData structure, which greatly simplified the setup. Next, I just need to update the part that interfaces with Discord to match. There's also the concern with calculating the tail, but hopefully that just works without too much fuss.

An example of the old message format:

@jaxter184-bot-test
sheet

ticks 6985_0000
"" {
	bass {
		"" (i0)"
			,21 [ _ ] [ ,21 _ ] . ,2D _ ,21 _ ,1F ,21 _ [ ,2D _ ] . ,1F _ [ ,21 _ ]
			. [ ,21 _ ] ,21 . ,2B ,2D ,24 ,25 ,26 . [ ,32 _ ] [ ,24 _ ] . ,26 _ [ ,21 _ ]
			. [ ,21 _ ] ,21 _ [ ,24 _ ] . ,21 . ,27 ,28 _ ,26 _ ,24 _ ,21
			_ . ,21 . ,23 . [ ,2F _ ] ,23 ,24 . [ ,30 _ ] ,26 ,27 ,26 _ ,24
		"
	}

	drums {
		kick  (F)",T ....... ,T ,T ..... ,T ,T . ,T ..... ,T ..... ,T . *6;20 ,T . *E;20 ,T . *8;20"
		snare (F)".... ,T ... *38;8"
		hat  (i0)"*4. ,C0 ,50 *3A;2"
		crash (F)",T *3F."
	}
}

graph

"" {
	"" "mixer" {
		(ai)a01 "../bass/"
		(ai)a02 "../drums/"
	}
	lead "sisqsa" state=(inline)"q"
	bass "sisqsa" state=(inline)"q"
	drums "beep-kit"
}

day 13

The goal was to adapt the rest of the ↹lature discord bot to work, and while that did get done, I unfortunately ran into an issue with the tail where it would always return a length of 1. While trying to figure that out, I adjusted the tests so that they would dump the audio output into a file, and in doing so, I uncovered another issue: the test audio output was not the same as the output when opening the test projects with the TUI. I'll hopefully figure it out tomorrow.

day 14

Spoiler: I didn't figure out yesterday's problem. I had a few things going on today, and I didn't do as much work on ↹lature as I wanted to. But, in the spirit of December Adventure, I at least took a look. I've got a little TUI tool called twv that I use to inspect audio files, and it seems that there's either a bug in twv or something weird with the output, because I can't see it. It's likely that the signal is entirely outside the -1.0 to 1.0 range, but since I'm writing it to a WAV file as integers, it should clip? I think? I'll figure it out tomorrow.

day 15

We're already halfway through December Adventure! The days have been whizzing by, and I haven't completed a single plugin. But that's OK, because I've been exploring tons!

I've refactored the twv code a bit, and added character markers for zero, NaN, and end of file.

After fixing this and using it on the output, I found out that:

Using Ctrl+C to close my recording program results in a malformed WAV file that thinks it has a length of 0 despite being 188kB
When I gracefully shutdown the recording program, it seems that the expected sine wave is mostly intact, except for a few discontinuities, which I assume occur at buffer boundaries.

To show this off, I want to make a little asciinema recording where I create a WAV recording from ↹lature, and open it in twv. To do so, I need to add a feature to my CLI recording utility to let it connect to ports in the middle of its execution, and not just at startup. While working on that, I ran into a bug. Did you know that a backgrounded program can't read a line from stdio while starting an async JACK client? Neither did I! (Or maybe you did, in which case, why didn't you tell me‽)

After several hours, I think I've fixed everything I needed to make the recording that demonstrates the problem I had yesterday. While I could probably make the recording at this point, it's getting late, so I'll leave learning autocast and making the recording for tomorrow.

day 16

There were a couple extra things I had to do to get my utilities to work with autocast. The main incompatibility was that the point in the recording when ↹lature starts is not fixed. Sometimes it takes longer to start up, so I couldn't repeatably zoom in on the exact point of the discontinuity. To fix this, I added the [ keybind to twv, which pans the waveform such that the first nonzero sample is at the very left of the screen. From the first nonzero point, the buffer discontinuity is always exactly the buffer length.

But after sorting through all that, I present the first December Adventure demo! (Though it seems there's an issue with how box-drawing characters are drawn in the asciinema player, so you may need to download the asciicast and use the asciinema CLI to play it back)

(link to demo)

Commands used:

$ cat tlature-engine/projects/load/main.tlgr.kdl
$ jaxrec -p 1 tlature:output_1 -e &> jaxrec.log & tlature tlature-engine/projects/load
$ du out.wav
$ twv out.wav

To break down the chunky command in the middle:

jaxrec: my recording utility. The recording ends automatically when all the input ports have been disconnected.
-p 1: open one port in the jack client, and write a single-channel (mono) WAV file.
tlature:output_1: the positional arguments to jaxrec match output ports to each input using a regex, or simply the first port(s) that start with this string.
-e: ignores the stdin. Usually, jaxrec ends when enter is pressed, but as described yesterday, this prevents the JACK client from starting, so we use this flag to disable that feature.
&> jaxrec.log: pipe all stdout and stderr to the file jaxrec.log.
&: run the previous command (jaxrec) in the background, and start the next command immediately. Contrast with ;, which waits until the previous command finishes before running the next command.
tlature tlature-engine/projects/load: open the project file in ↹lature.

While I was getting this working, I realized why the output was not consistent between the TUI and the tests: the tests have extremely large buffers, such that the entire test runs in one buffer, so there are no buffer edges for the test tone to be discontinuous across. After fixing that, the tests seem to be pretty much in line with the behavior of the TUI, so I think I can move forward with debugging why the events aren't getting read in the tests, after which I can move on to fixing the Discord bot.

day 17

Started a bit of work on a KDL highlighter for kakoune. It's just a basic implementation that colors numeric values and quoted strings, and sets the indentation on each newline. Not directly relevant to ↹lature, but it'll at least make the files a bit easier to read and write.

TODO: Features that I plan to add are properly highlighting the types, node name, and comments.

day 18

Did a little bit more diagnosis on why my tests are behaving strangely. I made two findings:

The OSC messages are not stored in chronological order. My assumption was that clack sorts the order when it creates the event buffer, but that could very well not be the case. In fact, it may be better for performance for that to be done on ↹lature's side rather than on clack's.
The test-tone plugin sees exactly one parameter change that sets the frequency to 440 Hz. It is likely that this is from the first event. Potentially related to the above bullet point.
When adding an abridged version of the ave-maria example project as a test, only the arpeggio voice is output in the test, and the reverb plugin (michaelwillis' Dragonfly Reverb) raises some sort of DPF error. ~~Possibly also due to out-of-order events.~~ (Update: this was not due to the out-of-order events, and is still an issue)

~~TODO:~~ Tomorrow I'll try actually putting the events in the right order before they're added to clack's event buffer.

day 19

Did a couple of minor fixes for event processing. As alluded to yesterday, I fixed the event order, as well as an additional bug where the root block sends a blank OSC message on note off.

day 20

Missed one spot where transport events are sent after all of the other messages instead of being interleaved with them. The solution was calling sort on the event buffer (which I should have been doing in the first place), so events being sent out of order should no longer be an issue.

~~TODO:~~ The plan tomorrow is to take a shorter day by organizing commits and checking the behavior of all my tests and examples.

day 21

Organized the commits as planned, and fixed the Discord bot, so now everything works as it did before I made all the ↹lature changes.

I updated to the latest version of serenity (a Rust crate interface to the Discord API), but I think what I should've done is use poise, which is a higher-level framework that makes things like context menu bot commands easier. I'm not gonna worry about that for now, and go back to ↹lature work tomorrow.

This weekend is also the start to my time off work, so I'm hoping to spend the time doing some particularly fun stuff with ↹lature, and maybe get another demo out. I don't want to put too much pressure on myself to get stuff done, but it's the final stretch of December Adventure, and I want to continue hiking along as I've been doing up until now. I think the theme of "do a little bit every day, with an exploratory mindset" has been very beneficial so far, not only for the project itself, but also my attitude towards it.

day 22

Made some plans for how the UI layers are going to be implemented. And that's not a euphemism for not having done anything, I did actually write some code today! Comments count as code, right?

Anyway, I'm chalking today off as a sort of wind-up to a future follow-through. I deserve it. In fact, I always deserve to take things slow.

day 23

I added a bunch of stuff today, and pretty much all of it is stuff that I discussed on day 09:

Refactored to a layer/mode hybrid UI system
Refactored the CommandTemplate struct to be (hopefully) a bit easier to work with in the future when I add documentation for individual arguments
Added a command popup interface, which is the main use case for the string input dialog that I mentioned on day 09
Added commands for adding, inserting, and removing a processor

But maybe it's easier to describe with a demo, showing the newly added processor commands:

(link to demo)

~~TODO:~~ I forgot to also demo the new command popup (which is probably the more fun and interesting addition), but it's late, so I'll do it tomorrow.

day 24

Added a structure to communicate information about the currently selected item, so that you can use commands like :insert processor delay without specifying the block that the processor is going to be added to (before, you had to use :add processor --processor 0:this-block/3 delay)
Improved the command popup. Hints are now filtered based on whether they start with the current typed value, and you can use Tab to navigate hints.
~~TODO:~~ Ran into a bug where processors are added even if they don't exist, which has proven to be a bit tough to fix because of the way that ↹lature is structured
TODO: There seems to be a hitch in the audio thread, so I'll probably do some profiling after December Adventure ends, and maybe look more into the real-time safety

I'll be honest, these log entries are much more for myself than they are for other people. I think something that would help with that is drawing a clearer narrative. For example, starting with how I want the user flow to work, some bad approaches to accomplishing that, and then my final approach.

But until then, another demo! (The one I said I'd make yesterday):

(unfortunately, the box drawing characters are still a bit broken)

day 25

Fixed the bug where adding a plugin that doesn't exist crashes the program

I started some work on refactoring the structure I made yesterday. As it is now, it just passes in arguments (like --block) automatically, but really, I want the argument parsers to understand the value, so I can use relative paths.

day 26

Finished refactoring the environment information passing. I'm really happy with how usable commands like rm processor are now. You can now use a relative path to add and remove processors and blocks, which also lets me use . as a default value for the --block and --processor variables, which gets interpreted as the currently selected item.

day 27

Started some work on refactoring the OSC channels to more general CLAP event channels. Right now, I'm creating OSC events by leaking memory which is definitely not sustainable, and I'm approaching the limit to the hacks I can get away with by just leaking, so my plan for tomorrow is to get a better idea of what CLAP needs from a lifetime perspective, and adjust my implementation to better align with that.

day 28

Finished changing OSC channels to CLAP event channels. Did a lot of strange stuff that is definitely not real-time safe (I will leave that for future me to figure out), but it passes the events as needed, and didn't really require too much thinking. I just changed one of the types from Vec<(u64, OscMessage)> to clack::EventBuffer, and followed the Rust compiler's instructions from there. The most involved part was writing a function to filter the events in the buffer and produce a Vec<(u64, OscMessage)> for the OSC file writer.

Hooray for Rust and its ability to facilitate fearless^{[citation needed]} refactoring!

Just yesterday, ↹lature received the first ticket submitted by someone other than me! There are a few requests that folks have pointed out to me over private channels because I asked them, but this is the first one from someone I've had no prior contact with, and I didn't have to solicit them for feedback. It might seem pretty insignificant from an outside perspective, but personally, it's really cool to see that someone cares enough about this project to let me know that something is broken, even if it's just because they want to check it out as research for their own project. In fact, I'm pretty flattered that they looked at it and thought it would be a good reference in the first place.

day 29

Fixing windows support, as requested. I actually should have been working on it for a while because someone else had also requested it (via private channels, and after I solicited them to try it out), but the high of receiving a ticket really motivated me to actually work on this.

There are three main things that are *nix-specific:

The conversion OS paths to C strings in the resource directory extension
The stdio redirect shenanigans to print plugin stdout to a file while still printing the TUI to the terminal
JACK (technically cross-platform, but I dare you to find me a Windows or MacOS user who regularly uses JACK)

Today, I worked on the first two. The resource directory extension was pretty easy, I just had to follow the compiler's instructions. With the stdio stuff, my solution was to ignore it, which will result in issues when plugins print errors, but that also generally shouldn't happen, and if it does, it means there's probably something in either ↹lature or the plugin that needs to be fixed.

There may be other things that I'm forgetting, but I suppose I will find out when I actually try to use ↹lature on Windows.

day 30

I had forgotten how awful of an experience Windows is. I had to install a bunch of stuff (Rust/cargo, git, ASIO4ALL, JACK), and for the most part, it went fine, other than the part where I had to agree to a license (that I didn't read) to use the MSVC compiler (🤢). It was a bit annoying to have to go to each website and download the installer, but that's easy peasy compared to the weird display/USB issues I was having the whole time. For some reason, my USB hub kept disconnecting every couple seconds, and Windows really didn't like my second monitor. This last one is probably on me, but the peak disk speed was around 50MB/s, probably because I'm connecting my NVME SSD to my computer via USB type C.

Anyway, after I got everything installed and got past the hiccups of running JACK on a Windows machine, the TUI showed up and I was able to navigate around the UI! While I will almost certainly never use this, it's nice to see that it at least works, and didn't take too much extra effort to adjust things for Windows compatibility.

After checking that, I added some help windows to make it easier to know what the available hotkeys are in any given mode. I'd like to eventually do this in a more structured way such as implementing default keybinds in a KDL file rather than manually written out in Rust, but to implement it how I'm imagining would likely require me to add a scripting language (and not roll it back this time), which would also let me implement the keybinds as a file.

I think I'll explore Lua support eventually (since rhai was a bust), but since tomorrow is the last day of December Adventure, I think I'll try to top it off neatly by finishing the event offset plugin, bringing this adventure full-circle to what I started the month with.

day 31

It's the last day of December Adventure! Today, I fixed event buffers so that CLAP events are properly passed down. I assume there are still a bunch of problems with it (especially with regards to non-serial signal paths and nested groups), but for the most part, it seems to work as expected. Most importantly, the event-offset plugin works as intended! If I put it between the tracker processor and the physical/marimba plugin, it shifts the pitch up by the designated amount. Right now, that amount is just a default value of 20 because parameters are kind of a hassle that I don't want to deal with at the moment. But it works! The first task (at least, the first "actual" task) that I set out to complete for December Adventure is now finished!

retrospective

The main thing I was surprised about when it came to December Adventure is how consistent I was. There were a few days where I did less than 10 minutes of work, and one day that I didn't do anything at all (though in my defence, I had a lot going on that day, and knew a few days in advance that I wouldn't be doing anything), but other than that, I made meaningful contributions towards my project every day this month! Looking back at my original plan, it's laughable that I ever thought I would be capable of "a brand new plugin each day", or the "meaningful feature every day" that I fell back on, but even with "just touch the code at least once every day", I'm really happy with all the progress I made on this project.

As for why I think I was able to do it, I think there are a few key benefits to December Adventure:

Choose your own adventure - Whatever you decide to work on is something that you get to pick, so you're naturally more inclined to do it compared to, for example, the coding interview-esque challenges of Advent of Code.
Relaxed - There isn't any competitive pressure involved, and you're just working on stuff because you want to.
Minimal - There's a sort of sentiment that I picked up on that any amount of progress is valid progress. For me, the first minute of working on something every day is the hardest, usually because of decision paralysis, but by weighing 10 minutes of work against failing the task in the first week, or breaking a 2 week streak, I found it much easier to just get started on literally anything, which usually led to multiple hours spent happily chugging away.

There are a few things that I think could have been better:

Community - While I did keep up with a few other peoples' December Adventures, mostly through the #DecemberAdventure Fediverse hashtag, there wasn't much of a dialogue. I would read other people's logs, other people would read mine (hopefully, though I don't blame them if they didn't; my log is over 6000 words at this point), but I didn't feel like I had anything meaningful to add to their progress, and therefore didn't find myself commenting on their progress.
Refactoring - I personally found myself doing a lot of refactoring and bug fixing rather than exploring new things. I think to some extent, this was inevitable, but it would have been nice to somehow have been aware of this in advance so I could have more realistic expectations about how I was going to spend the month. Which isn't to say that I regret it! I'm really happy with everything I did during December Adventure.

Anyway, overall, it was a great month and I'm really glad I did it. Thanks to eli and all the other folks who did December Adventure! Here's hoping 2024 is the year of the tracker on the Linux desktop!

Papercraft

Unknown — Thu, 30 Nov 2023 00:00:00 +0000

I bought a nice printer recently, and what better way to test it out than to make some papercrafts? I loved papercraft as a kid, and the tools have come a long way since when I was last involved in the hobby. Back in my day, all we had was the free demo of Pepakura, or papertoys.com (Sydney Opera House was my favorite, and Statue of Liberty was my least favorite). But now, there's a Blender add-on! And Fold Up Toys (Which has a much better Statue of Liberty)!

First attempt

The model I chose was "Pixel House", by tacocrepe, licensed under CC-BY 4.0:

It's a really fun design! The stone foundation and white top walls give off a Tudor Revival vibe, but the white windows look a bit like paper, and combined with the wooden posts, I came away with this with an impression of early Japanese architecture. And the kicker for me is that I could probably get away with simplifying the shape to roughly a cube with a triangular prism on top.

I tried to pick a model that would be quick and easy to make, but I ended up wanting to simplify the geometry even more. After learning the shortcut for adding an edge through a face across two of its vertices (J), I was able to make the changes that I wanted to.

First things first, the simplifications were absolutely not a good tradeoff. It didn't make assembly much easier, and in my opinion, it lost a lot of the magic that made the model work in the first place. The colors turned out nice though! The toner rubbed off a bit in some places, but I believe that has to do with the printer settings, and not the actual quality of the printer or toner or paper, so it's probably an easy fix.

Being as creatively insatiable as I am, I naturally started on a second attempt pretty much as soon as I finished it.

Second attempt

The main changes I made were that I omitted the simplifications (the actual shape is practically identical to the original model, just meshed slightly differently for better unfolding), and replacing the windows with sanded clear plastic so that I could put a little light inside and illuminate it. About half of the time and effort spent cutting was probably spent on the windows.

I also totally forgot to take pictures of the process, but it's more or less what you would expect: I cut out all the pieces and glued the tabs in. But I do have the printout if you want to try it out yourself (yay for Creative Commons)!

Things I learned

The measurement marks on the rotary cutter that I have are nice for when you know the measurements for what you are cutting, but I found that they're too difficult to use accurately when cutting along a printed line.

Scoring a fold with the blunt side of a craft knife blade makes for an easier, crisper fold. I had been doing a similar thing with a "bend" wheel for my rotary paper cutter, but not only is using a craft knife more accurate, but it is also more effective in making a sharp bend.

Omitting small tabs can make assembly much easier, without sacrificing too much stability.

Glue sticks are very annoying to use. Use liquid glue instead. I use PVA glue, mostly out of convenience; I had a very old bottle of glue laying around from when I was in like kindergarten.

Comparison shot. New house is on the left.

Lights!

The colors came out a bit less vibrant, and I'm not sure exactly why, but I would venture a guess that it has to do with the fact that I changed the print preset to one for heavier paper. But the craft itself turned out great, and it was a lot of fun! I'm glad I tried it again with a more faithful geometry.

Rust Audio Chat Archive

Unknown — Tue, 07 Nov 2023 00:00:00 +0000

A curated chat archive of the various Rust Audio chat rooms

Discord
Matrix
Telegram
https://rust.audio/ (Discourse is discontinued)

Rules:

Follow the rules of the source chat room(s)
Only document publicly available information
Do not explicitly quote anyone without their permission

Guidelines:

Only post Q&A and technical discussions (if someone answers their own question, that's fine too): Things like project updates, organizational drama, and other news don't really make sense to document on this wiki.
Avoid opinions: "I think JACK is all you need to support" should instead be "JACK is cross-platform, so an application that uses it as a backend could hypothetically run on most modern computers"
Change/add a timestamp if you edit a section: it's nice to know how out-of-date a piece of information could be. Use ~~~~~, which will turn into a datestamp when the edit is published.
If someone mentions details regarding their project, try to omit them unless the information is important, '''and''' they give permission

FAQ

What are some resources for learning DSP?

https://github.com/BillyDM/Awesome-Audio-DSP

Why should I use Rust over C++?

(paraphrased from this comment)

DSP: About the same, since it's just performing calculations, the performance of which is roughly the same across almost all compiled languages.
Metaprogramming: C++ templates are a little more flexible than Rust macros, and Rust's generics require a lot of explicitness since they're more closely tied to the type system.
Plumbing: Thread and type safety are really nice to have, and eliminate whole classes of bugs. Something something "fearless concurrency".
Abstraction level: Rust's memory model is simpler, and doesn't really give up much in terms of higher-level abstractions. You can easily and ergonomically use Rust for anything from a bare-metal embedded program (as long as you're on ARM or RISC-V) to a browser application (via WASM) to a web server, and anything in between.

(a couple additions that were not in the above comment)

Cargo is lovely
Refactoring is really nice
Async is fun, though not particularly useful for audio applications yet
A lot of nice development tooling:
- integrated unit tests,
- benchmarking
- docstrings
- helpful error messages
- the log crate
- panic traces
- error handling in general
nih-plug is really nice

How do I create virtual audio devices that I can route signals to/from?

At time of writing (2023-06-15) there aren't any robust cross-platform methods for this, but on Linux, using Pipewire or JACK as your audio server will let you route audio freely. Pipewire works with both PulseAudio and JACK clients, while a JACK server will only be able to communicate with JACK clients.

linkdump

https://github.com/RustAudio/dasp for some DSP building blocks
https://github.com/MeadowlarkDAW/creek for audio streaming from disk
https://github.com/wrl/baseplug/blob/trunk/examples/svf/svf_simper.rs svf code example
https://github.com/WeirdConstructor/HexoDSP
https://github.com/WeirdConstructor/synfx-dsp
https://github.com/tesselode/kira Library for expressive game audio

Realtime programming:

http://www.rossbencina.com/code/real-time-audio-programming-101-time-waits-for-nothing

Graph processing:

Crates for handling soundfonts:

https://docs.rs/soundfont/latest/soundfont/ only parses .sf* files, and doesn't actually do any audio decoding
https://docs.rs/fluidlite/latest/fluidlite/

Discussion

Issues with WAV file decoding

Pitch/frequency of the resulting output is too high

Check to verify that the sample rate of your file matches the sample rate of the output
Make sure that the channel count is being taken into consideration. If you are reading a mono WAV file as if it were stereo, the resulting output will be an octave higher (double the frequency) and twice as fast (half as long)

Output amplitude is too small/large

Make sure the numeric type is correct (i.e. not an f32 when you should be using an i16)

Trig function ranges

Traditionally, sine functions will have a period of 2π, but (allegedly) in many implementations of sine, the input is scaled to make the range from 0.0 to 1.0. If possible, it would make more sense to just make your initial phase range from 0.0 to 1.0 and use a sine function that doesn't do the rescaling to save two multiplications. The performance benefit of this is pretty minimal.

Poems

Unknown — Mon, 06 Nov 2023 00:00:00 +0000

zero

gotta start somewhere

this is hard

oat of sight, oat of mind

What could the humble oat teach us if we were not alienated from them?

Would they suggest growing and thriving to secure my future, as their ancestors did?
Would they take root without hesitation, as if it was the only option?
Would they bend with the wind, as the combine harvester reaps with unstoppable efficiency?

Tragically, I can't find the answers in my oat milk.

Tone Tram

Unknown — Mon, 02 Oct 2023 00:00:00 +0000

Tangentially related to aliqot, but not necessarily a sequel or anything.

The ondes Martenot is an instrument made by some French guy. I like it because it is essentially a more tactile version of the theremin, where you can still make large sweeping slides in pitch and volume, but you get to feel how you're doing it. Some versions of the instrument even come with registrations bumps that let you feel where the pitches are.

I want to make a digital one.

The pitch wire

The main feature of the ondes Martenot is that the pitch is controlled by pulling a wire back and forth using a ring. I am far from the first to make a digital version, and as far as I can tell, the go-to approach is to use the wire to spin a wheel attached to an encoder or potentiometer:

I don't like this approach because it requires either a multi-turn potentiometer or a calibration sequence whenever the instrument is powered on to know exactly where the ring is.

My solution is to construct an absolute linear encoder using magnets and hall effect sensors.

de Bruijn sequence

The original idea for this project actually came from me, on a complete whim, wanting to know whether there was a shift equivalent to the Gray code. That is, in the same way that the Gray code is a series of unique values in a sequence that differ from their neighbors by one bit, was there an equivalent code where the values were shifted versions of their neighbors? The answer, of course, is yes, and it's called the de Bruijn sequence. The main benefit of such an encoding is that where I need N*M magnets in Gray Code, where N is the number of bits and M is the number of positions, I could just use one channel of M magnets. This saves a lot of money in magnets and a lot of labor in putting things together, plus its much easier to design and produce around one row than N rows.

It turns out that the 2 bit case is the same for both Gray code and de Bruijn sequence, so as an example, lets consider the three bit case:

Gray code:

a ⬜ ⬜ ⬜
b ⬜ ⬜ 🟫
c ⬜ 🟫 🟫
d ⬜ 🟫 ⬜
e 🟫 🟫 ⬜
f 🟫 🟫 🟫
g 🟫 ⬜ 🟫
h 🟫 ⬜ ⬜
a ⬜ ⬜ ⬜

Each row differs by the next row by one bit

de Bruijn sequence:

a ⬜ ⬜ ⬜
b ⬜ ⬜ 🟫
c ⬜ 🟫 🟫
d 🟫 🟫 🟫
e 🟫 🟫 ⬜
f 🟫 ⬜ 🟫
g ⬜ 🟫 ⬜
h 🟫 ⬜ ⬜
a ⬜ ⬜ ⬜

The last two bits of each row is the same as the first two bits of the next

One way to visualize the de Bruijn sequence to make the shifting relationship clearer is to visualize the value in the context of the rest of the sequence (similar to what is done on the Wikipedia page):

a [⬜ ⬜ ⬜]🟫 🟫 🟫 ⬜ 🟫
b [⬜ ⬜ 🟫]🟫 🟫 ⬜ 🟫 ⬜
c [⬜ 🟫 🟫]🟫 ⬜ 🟫 ⬜ ⬜
d [🟫 🟫 🟫]⬜ 🟫 ⬜ ⬜ ⬜
e [🟫 🟫 ⬜]🟫 ⬜ ⬜ ⬜ 🟫
f [🟫 ⬜ 🟫]⬜ ⬜ ⬜ 🟫 🟫
g [⬜ 🟫 ⬜]⬜ ⬜ 🟫 🟫 🟫
h [🟫 ⬜ ⬜]⬜ 🟫 🟫 🟫 ⬜
a [⬜ ⬜ ⬜]🟫 🟫 🟫 ⬜ 🟫 (repeats)

Hopefully this makes it clearer that each row is a (cyclically) left-shifted version of the previous row. Given the sequence ⬜ ⬜ ⬜ 🟫 🟫 🟫 ⬜ 🟫 , we could use a row of magnets arranged with one pole representing zero and the other representing one, and read any three adjacent magnets to know exactly where along the row we are, and which three magnets we are reading.

If the hall effect sensors are analog, then we could potentially get an additional 12 bits of precision between magnets (depending on the ADC, minus noise, and assuming magnets have exactly equal magnetic flux).

Optional technical caveat:

I say "potentially" because I am assuming that the in-between values are unique. For example, an analog read halfway between the first two values ⬜ ⬜ ⬜ and ⬜ ⬜ 🟫 would read ⬜ ⬜ 🔴 , where 🔴 is the analog value halfway between ⬜ and 🟫 . If we turn on the instrument in that position and it knows nothing about the previous context, we can only know exactly where we are if ⬜ ⬜ 🔴 is a unique value. One way this could not be true is for the value ⬜ 🔴 🔴 , if there existed adjacent values ⬜ ⬜ 🟫 and ⬜ 🟫 ⬜ as well as ⬜ 🟫 🟫 and ⬜ ⬜ ⬜ . In this case, we know this isn't possible since the shifting property does not allow ⬜ 🟫 🟫 to be next to ⬜ ⬜ ⬜ . I believe it is the case for every situation like this that there is only one valid pair of adjacent values, but I'm no mathematician.

Even with all the inaccuracies, I'm not aware of any linear position sensing mechanisms with that level of precision. In addition, because none of the sensing components contact each other, the wear over time is greatly lower than, for example, a linear potentiometer, where a wiper has to slide back and forth across a thin carbon strip.

According to my limited research, applying this concept to sensing is not an uncommon practice, but much of the literature discussing it is paywalled.

construction

TODO

hall effect sensors
gluing magnets is a pain
modular connector that works with my cowbell pcb
de bruijn sequences
- aren't unique
- how to decode position?
- if there's one thing I've learned in the last thousand revisions of this section, it's that these pattern explanations are in dire need of interactive visualization
- implement footnotes so I can mention that you can extend the sequence to: ⬜ ⬜ ⬜ 🟫 🟫 🟫 ⬜ 🟫 ⬜ ⬜

Monthly Logs 2023

Unknown — Sat, 30 Sep 2023 00:00:00 +0000

09 - September

Updated contact page

It's been almost exactly one year since I made a contact page for collecting all the different public online spaces where I exist. I had a weird experience the other day where I joined a Discord channel, and someone there used contact.jaxter184.net to find my SoundCloud account, and then posted my music in the Discord channel. At least, I assume they did, because I have it linked in my Discord bio, though it's possible they just searched "jaxter184". But even if they didn't use my contact page in this particular case, I like the idea of making it easier for these disparate parts of my online life to be more connected, especially in this age where social media platforms seem to be fragile and temporary.

As part of this refresh, I decided to change my profile picture. I've been using my old one for several years, but I've recently changed the way I'm doing my hair (and it will probably change again in the near future), so the old one felt outdated. Previously, I had used Blender to render all the fancy shapes hanging around my head, but I wanted to be a little more reserved in the new one, so I shrunk the hexagon and used Inkscape. This has the side-benefit of being more web-friendly in the few places that I can use an SVG file. I also had an SVG version of the old profile picture that I made for a much older website, but I seem to have lost it.

Old	New

Frankly, I think I prefer the old one. The sheen on the face covering is neat, and there's a bit more whimsy in the loops around my head and the little orange icosahedrons. That being said, I'm pretty happy with how the gradients look in the new one, and it's certainly a more accurate depiction of what I look like now. Hopefully I'm a bit quicker to replace this new one than I was to replace the old one.

Attempted to debug probe.rs

A friend reached out to me to try and do some Matter IoT stuff recently, and this is the chip he wanted to use. So far, I've generated a peripheral access crate from the SVD files, and verified that it works by using Silicon Labs' Simplicity Commander tool to flash the ELF file.

However, the tool I use for most of my embedded development is probe-rs, and I thought it would be nice to try and add support for the particular chip I'm using. They have support for some other Silicon Labs chips already, so how hard could it be to add support for this one?

[pause for dramatic effect]

I've had an issue simmering in their tracker for a while now, and they've basically held my hand through the debugging process. To be clear, the reason this is so difficult and taking so long is due to my incompetence (if it wasn't clear from the issue discussion). At this point, I'm considering just buying a dev board for Yatekii and asking them to figure it out. Would probably be faster and easier on their side rather than trying to remotely debug through a lossy, flawed communication channel (i.e. yours truly).

Started Tone Tram

I have ideated yet another digital musical instrument interface to add to my pile of half-complete digital musical instrument interface pile. I am nothing if not consistent.

This one is basically an ondes Martenot, but digital. Pretty funny coincidence that "Martenot" backwards is "tone tram", since this thing is basically a little train that goes back and forth to control the pitch of a tone.

Tone tram - Reconstituting the ondes Martenot

Started crofu

I've procrastinated on implementing ICC for quite a while now. I think at this point, with the help of the people who have been kind enough to talk about it with me, I've developed the idea enough that I'll learn the most from simply executing it.

And so, behold:

crofu - Incremental converse crowdfunding platform

Wrote my first monthly log

It remains to be seen how consistent I will be with these, but at the very least, I think it helps with the blog-writing process. It's very rare that I'll "finish" a project, so focusing on the little things that I've done this month might be a better way to exercise my blogging muscles, and make it easier to write the more interesting articles on a given project. I'm also planning on making project posts more "live", so that they change as I progress through the project.

There are a couple different goals of this blog, but one big one is to share the progress I've made. Developing on an idea is a slow process riddled with obstructions, and maybe by sharing my experiences, someone doing something similar in the future will be able to move more effectively through the problem space. Of course, no matter how much you learn about a subject, there will always be issues, so I'm not too worried about depriving someone of the joy of figuring things out.

10 - October

Card game?

Two of the folks on labyrinth.social came up with an idea for Mastodon trading cards. The idea immediately roused my interest, perhaps because I've been very loosely dabbling in game design on and off for the last few months (running a DnD campaign, trying out Bevy). While there are plenty of services online that will print playing cards for you with arbitrary designs on both the front and back, if there's one thing I hate, it's spending a reasonable amount of money for something convenient and high-quality when I could instead spend even more money and time and get a far inferior result. So after spending about $30 on paper, glue, and varnish, and $150 on a used laser printer, I've come up with a vague process for creating some cards that look and feel slightly better than if you simply printed them out on regular paper with a regular printer.

This is in a very very early state, but hopefully it develops into something meaningful! Next step (honestly, this step should have come before the huge money sink) is to do a few mockup designs and develop some game rules. I had a few small ideas when I initially came across the concept:

notes

the goal is not necessarily to win, its to:

have fun
interact
commune
self-express

minor goals:

communicate
learn
connect

though formalizing some sense of "victory" would help with the "have fun" part

there should be a "game mechanic". perhaps dnd-esque? in that it is collaborative rather than competitive
- ooh, maybe like a multiplayer solitaire? or Set
- even if there are no winners and losers, there should still be a meaningful result.
in my imagined world, people carry these cards around like business cards and exchange them
there should be no reason to counterfeit them. they should only have meaning because someone you know gave them to you.
put nfc chips in them?
each instance should have a different back, and maybe a front frame style

Re-entering the world of papercraft

I also made a little papercraft to test the printer, and I think I'm gonna do more:

✂️ Papercraft - First attempt

Researched wikis

I stumbled upon Maggie Appleton's history of Digital Gardens on Mastodon, and while it has some insightful observations on the nature of personal wikis and how they interact with the rest of the internet, honestly, all it took for me to get on board with the idea was simply the word "garden". It feels so much more in line with the kind of thing that I want to make than "blog". So what are the steps I need to take to convert this blog to a garden?

Initially, I thought the move would be disruptive. I was looking up wiki engines, and considering maybe even maintaining a separate wiki and blog. ikiwiki stood out as a particularly interesting engine, and prided itself on its configurability, and the fact that you could also use it as a static blog generator. Tragically, it is written in Perl.

But running into ikiwiki made me realize that maybe a blog and a wiki are two different shapes of the same material? If I could just add some extra navigation elements and link more aggressively between pages, then I'd be 90% of the way to a wiki.

That being said, there are some features -- like automatically styling external links and streamlined editing without logging in, or limiting edits to people who are (perhaps using IndieAuth) -- that I would like to have, but would require significantly more work than simply making a few minor changes to my Zola theme.

Like with the previous project, I haven't made any meaningful steps toward actually doing anything. But I'm excited!

Also, recently, one of my favorite 'Lu's got in contact with my other favorite 'Lu' and recommended that they cultivate a personal wiki. The Hundred Rabbits log is what inspired me to start recording these monthly log entries in the first place, so it's cool to see someone who I really respect directly influencing someone else who I really respect. Especially when I'm being influenced in the same way!

Additional reading

Refactored tlature

While it may seem like I'm starting tons of projects and not actually working on my old ones, it's actually the case that the single non-sleep activity I spent the most time doing the last 32 days (16.1% according to my logs) was working on tlature. I set a bit of an artificial deadline for myself as I approached the start date of my new job to get as much work done on it as possible before I started. While I had hoped to get to a point where it was usable by someone other than myself to make music, I don't think it's quite there yet.

The current plan is to do a more detailed writeup of what I actually did once I get Zola set up for a more wiki-like workflow, but in a few words, I:

Refactored routing
- Block is now a chain of processors rather than just one
- User-defined routing is now its own processor rather than something built into the Block
Revamp how the view modes behave; everything is now nested
Refactor Tracker as a processor
Refactor how commands work

As you can see, it was mostly refactoring, and there were very few new features. In fact, I'd say it's probably less capable now than it was at the beginning of the month. Even so, I think overall, this is a good result, and has primed the codebase for future features. Unless my whims shift once again and I do another huge refactor.

Wrote my second monthly log

I was about 23 hours late to this month's post, but frankly, the fact that I did it at all is something that I'm proud of. It could have very easily been the case that I simply forgot to make one. In fact, it wasn't until about 2 hours ago that I even remebered this was a thing that I was doing. Maybe I should set an alarm or a calendar event to remind me.

In terms of the actual log content, I feel like I'm still having trouble with the actual writing part; a lot of my sentences are a bit clunky, and it's tough to communicate what I want to, in the way that I want to, but also make sentences flow naturally into each other. But such problems are exactly the kind of thing that I'm hoping to fix by making these entries, so I'm glad that I'm at least noticing the shortcomings.

I think the core to this is going to be to better understand why people read blog posts (and wiki articles), and what I can be doing to make my writing more appealing for those people. So if you've made it this far, please reach out and let me know what you think! Or even just let me know that you've made it here.

11 - November

More papercraft

I made a second version of the papercraft house I made last month.

It glows!

✂️ Papercraft - Second attempt

More wiki development

Addad a bunch of features to my wiki template, including the site map and table of contents that you see on the left sidebar (on desktop), and little icons after every link, based on what site it links to (notably, Wikipedia).

Also moved to Codeberg pages (and will probably move again because I really don't like the upload workflow). The issue that I had with sourcehut pages is that it won't let you use third party Javascript. While I totally understand, and still use sourcehut pages for my other site, I really wanted Sketchfab and KiCanvas support, and while I could get away with including KaTeX source in my webpage, this was not true of Sketchfab's embeds, and would likely require me to learn npm and TypeScript (eww) to do it for KiCanvas.

Rust on RISCV ESP32s

Did some cursory exploration of flashing Rust code to RISCV ESP32s. Seems to work OK for both the ESP32-C2 and ESP32-C3, but I couldn't find or modify a Wi-Fi example to work with the C2. I'll keep you updated though.

Game engines

Wrote about every game I've made in recent history, and the engines (or lack thereof) that I used:

🎮 Game development

12 - December

For December Adventure, I worked on some ↹lature features laying the groundwork for better plugin integration:

December Adventure 2023

ICC Concerns

Unknown — Mon, 25 Sep 2023 00:00:00 +0000

This was originally part of the main ICC blog post, but I split it off because it got too long.

Read this first: ICC

funding comes after publication

For many products, there is a large up-front cost required to even begin work on completing it. This is true for almost all physical products, especially tech hardware. ICC has no solution for these cases. It instead focuses on information-based products, like art and music and software, as they can usually be broken down into sub-tasks, their distribution costs are almost zero, and the cost to the author to get started is generally very low.

The risk has to go somewhere, whether it is the funder risking the loss of their investment or the producer risking the loss of the work they put in. The reason ICC decides the money has to come after is because fluidity is important to the scoring process, and money is more fluid than the deliverable (i.e. you can't release 90% of an artwork, but you can provide 90% of the funding). Also, since there are generally far more funders than producers in any given transaction, it makes more sense to treat the funders as a more consistent collective decision-making body than the producers.

This is all to say that ICC isn't a viable means of funding for someone with very little starting funds, so this will likely be used as either as a side gig to complement a separate, more stable income, or for artists who already have a significant fanbase. However, no other method of funding really allows artists to start from zero financial or social resources without putting all the risk on the funder.

ziglang bounty post

(added 23-268)

https://ziglang.org/news/bounties-damage-open-source-projects/

This blog post highlights many issues with bounties that might also apply to ICC:

Bounties foster competition at the expense of cooperation.

Possibly also applies to ICC. It depends on how an organization decides to distribute a pledge that multiple people worked on, and ICC makes few moves, if any, to help with this. The case that I see being the most common is that donation payouts are shared, and new contributors get a reduced share (the rest goes to maintainer) until they reach some threshold. This has many downsides:

for maximum payout, a contributor is encouraged work on a task alone
new contributors are considered outsiders with reduced entitlements
without good management, there might be conflicts when multiple members work on the same task

In the case of an organization with multiple members, perhaps it makes more sense for all donations to a project to go to one big pool, and for there to be some other decision-making process for deciding how the donations are distributed.

battle royale dynamics

Instead of scouting for a suitable candidate, you’re letting battle royale dynamics pick a winner for you, at the expense of everybody who’s going to lose the competition.

This observation highlights the importance of tying the pledge not just to a work, but also to the creator. If a different creator produces interchangably similar work, it is hopefully obvious that they should not be entitled to all of the pledges that were made towards this creator's work.

Likewise, by reducing or eliminating the payout in the case that an outsider completes a task, these battle royale dynamics do not form, and a suitable candidate can still be carefully selected.

risk allocation

Instead of creating a clear contract where you take on some of the risk, you implicitly put the entirety of the risk on the contestants (eg partial solutions don’t get any payout).

A later point that I believe is also related:

Instead of spreading unease to all the people involved, it would be preferable you instead learned how to do business properly.

The allocation of risk to contestants only forms when the criteria for payout is simply completing the task. As long as the payout is tied to both the work and the creator, ICC does not allocate risk any more poorly than it would be in a donation-based scheme. That is, because payouts don't go to drive-by contributors, the risk of two people working on the same task is the same as it is in any other FOSS project since there is no financial incentive for people not associated with the organization (assuming the organization does a good job allocating work, which, to be fair, is not a given).

reckless action to pass a test suite

Instead of allocating time and resources to proper due diligence, you instead penalize any form of thoughtfulness in favor of reckless action (eg a solution just needs to pass a test suite).

As far as I can tell, this is less relevant due to converse crowdfunding. Thoughtfulness is still required because the final arbiter for quality is the donor, who can use whatever subjective mechanisms are necessary to assess quality.

software lifecycle considerations

Instead of planning for the full lifecycle of software, which also includes maintenance, you end up with a quickly bitrotting artifact that is of no practical use to anybody.

Funding maintenance is definitely a concern, especially for larger projects. ICC does not work well in cases where a few very wealthy organizations all want the same thing, and most open source libraries fall under this case. Maintenance is incredibly important (I think most developers would say that it's even more important than new features), but very boring (both for maintainer and user) and hard to fund.

The Zig post goes one step further and highlights that if a contributor cares more about the payout than the long-term sustainability of the project, then their priorities discourage them from submitting maintainable code.

For individual artists, this seems like an easy, though not trivial, obstacle to overcome. My worries are greater when it comes to larger organizations and more complex projects (like Zig). I've been simmering on an organizational structure that can work in tandem with ICC, but I'm skeptical as to whether it will actually work:

All donations go to the organization, and is distributed based on "shares", which are received when one completes a task. As a result, the contributor gets much less up front, but over time, they get a portion of all future donations. This encourages contributors to make their contributions more sustainable over the long term.

While this seems better than simply giving all the donations to the contributor that completes the task, I am a little hesitant to prescribe such a bureaucracy, and I think this is something that should be figured out by the organization in question.

On projects less radical than Zig, you might also put pressure on the development team to accept the winning submission, which, given the above, will probably not be the most well-thought-out and maintainable solution.

I have no solution, except crossing my fingers and hoping people are reasonable and understanding about this.

conclusion

As I understand it, the conflict in the WASIX issue linked in the Zig blog post mainly stemmed from the fact that implementing WASIX would not have aligned with the goals of Zig. Even though the bounty payout is not contingent on the implementation being accepted into the mainline branch, it is understandable how this bounty could be used as a tool to subvert the goals of the leadership and community to push the progress of the project in a direction that its participants don't want it to go in (another relevant section). While this concern is not explicitly mentioned in the Zig blog post, it highlights yet another important aspect of ICC: the artist is the sole entity that is allowed to create new proposals. Before, I had made this decision because I thought it would be annoying and unwieldy for the donors to be able to create new proposals (not to mention the logistical headache of determining when two proposals are similar enough to combine into one). However, as this conflict shows, it is absolutely imperative for proposal creation and modification to be restricted to the artist in order to preserve artistic freedom, and it is perhaps worth looking into additional protections.

Most of these points seem extremely pertinent to ICC (especially the last two), and are worth thorough analysis during and after the initial test run. It should not be understated the degree to which these issues could result in harming FOSS more than it helps. The worst outcome for this is that it leads to the destruction of a FOSS project that would have otherwise survived, without preserving a project that would have otherwise died.

does not solve the FOSS maintenance crisis

The Tidelift open source maintainer survey report contains a lot of disheartening results:

60% of maintainers are unpaid
Maintainers are spending 3x more time on security than they did a few years ago
In the wake of the xz utils hack, two-thirds of maintainers are less trusting of contributors
The open source maintainer community is getting grayer (i.e. older)

Unlike a developer, a maintainer's role is less to implement new desired features, and more to ensure that a software project continues to work in the future as the world around it changes. This entails bug fixes, security improvements, using updated dependencies, and adding support for newer hardware, to name a few. Most of these things aren't really things people would be willing to pay for in an ICC scheme, at least not in the numbers required to justify the work.

Bullshit Jobs is my least favorite David Graeber book, but one of the takeaways I got from reading it is that one of the reasons many important jobs (nursing, teaching, waste management, etc) pay poorly is because extortion is an important part of wage negotiations (if you don't pay me more, I will leave this job), and people are less willing to withold their labor when they think what they're doing is an important, or even critical thing that needs to be done.

In a way, every quid pro quo financial transaction is extortion (for example, buying food at a grocery store), and since ICC may imply this sort of transaction, a maintainer may feel uncomfortable signaling that the only thing standing between them and fixing this important piece of infrastructure is getting paid. I would argue that the implied contract of "if you produce it, I will fund this" is not a contract in the case of ICC since the donor is allowed to refuse with no repercussion other than the system knowing that they pledged some amount and didn't contribute it.

artistic freedom

I personally believe that this method allows for more artistic freedom than copyright-based compensation schemes (like commissions). I have no real basis for believing this, and will be on the lookout for the effects of this funding method on artistic freedom when I see more data.

In the end, the producer still gets final say in what they choose to do. Even if one option has significantly more fund offers than the others, the artist is still justified in deciding to do one of the others, and those who offered to pay for the most popular one don't lose any money from this.

more money means more influence

In general, people with more money have more power, and if implemented without careful intent, this tool will likely cause the same power consolidation effects of many other market systems. One way to counteract this is some sort of voting system where each person gets a single vote, but that has its own complications in verifying that all of the voters are actually distinct people (and not bots or malicious actors), or the fact that some people are more reliant on a project than others. That being said, the goal with ICC is to make money flow to people making cool things, with no regard for power, and the currently targeted demographic is one that is very conscious of how money and power flow. I've seen very few people who pursue art or FOSS software out of a desire for money and power. This is also why my platform (as is currently planned) requires FOSS and/or Creative Commons licensing, as it filters out the people for whom this is exclusively a means of making more money (which isnt to say that making money can't be someone's primary goal).

Another potential concern is that an individual with a large amount of money could basically have monopoly-level artistic influence over a large part of digital art production. However, if this platform led to a small amount of people paying artists large amounts of money to produce what they (both the funder and the producer) want, I'd say thats an outcome I'd be willing to work with.

That being said, the hope is that most of the income comes from a large number of individuals instead of a couple rich people or big companies. If you're paying for something, it's because you're getting something out of it in return, and ideally, a large number of people should be getting something from these projects. Plus, if you're not paying, you have no say in what gets made.

low variance and regular output producers

For a producer who only produces one type of content at a fixed interval, there isn't much economic benefit to incremental converse crowdfunding over methods like crowdfunded patronage or donation.

case study: 99% Invisible

The main work that 99% Invisible produces is their weekly podcast discussing design. There isn't really any reason for a listener to pledge towards a "Release a podcast" product offering, as the quality, quantity, and timing of that deliverable would be practically the same regardless of funding amount. Moreover, part of the joy of the podcast is revealing a part of the built world that is often underappreciated, so holding a poll to decide on the topic of the next podcast would be antithetical to this premise. For this type of creator, it would make more sense to run funding drives (which, last time I checked, is what 99% Invisible does), use a platform like Ko-fi or Patreon, or seek public funding.

research

(added 23-104)

It goes without saying that research is an important part of the development process. I believe ICC would not be ideal for directly funding research for a few reasons:

The value of research is hard to know before it is done. Using exploration of a forest as an analogy, the biggest and most important breakthroughs aren't those that cover the largest area, but rather those in the path that connect the starting point to the destination.
It is hard to break down into smaller increments, as the value is really only realized in aggregate. A deliverable like "produce a reliable method to sense the position of a shuttle along a rail" would have so many factors involved in its assessment that even with conditional offerings, it would be difficult to express the suitability across the various use cases, and how the final solution navigates the many tradeoffs involved.

accessibility

(added 23-268)

Accessibility improvements only really get done via central planning measures (at a small scale, Apple, at larger scales, the American Disability Act). I don't forsee ICC hurting current accessibility efforts, but it is important to recognize that this is not really a "rising tide that lifts all boats" in FOSS and free culture, and that other measures are necessary.

#OpenSource and #FreeSoftware is predicated on people "scratching their own itch", with the expectation that if a solution is useful to you, it will likely be useful to others. But that breaks down when it comes to hard, niche problems that require specialized knowledge and skills. Things like good #accessibility in desktop environments doesn't happen without lots of effort, knowledge and intent.

getting scooped

If you're a video essayist, you might want to create proposals that describe the topic of the proposed video in detail. However, doing so could result in a lower-effort essayist "scooping" your topic before you. While it would be interesting to see how the essayist would combat that (perhaps by using the "scoop" as another reference to fact check their own video, or to gauge the audience reaction and use that to expand on some parts and remove others), in general, the best move is probably to use more vague descriptions of the topics in their proposals.

a bit complicated

One of the claimed benefits of Ko-fi over other platforms is its simplicity. ICC at its base level is a non-negligible amount of stuff to be aware of, and once you incorporate details like sub-deliverables and expected donation score and conditional offerings, it becomes an economic labyrinth. In addition, the onus is on the donor to determine to what extent the creator has satisfied their claims, which is additional work that not a lot of supporters are willing to put the time and energy into.

Notably, the game engine Bevy observed that when it moved from a simple system (send all money to the creator/maintainer) to a more complex system (choose which contributer to send money to), new donors went way down.

money corrupts the joy of creation

In some cases where there is no financial incentive, there's a lot more passion, in part out of necessity. But such a scenario is almost never financially sustainable.

money is not an ideal driver for an organization

Big multi-person projects will fall apart if the main thing holding them together is money. These things need vision and a group of people who collectively hold it, especially early on. For money to be the sole motivator is inviting failure, and in the case that it makes it past the early stages, leads to an organization that is driven by a perverse incentive.

CC-BY-NC

Not really an issue with the actual mechanism behind ICC, but it's probably not legal for an artist to use this as a platform for a work that triggers the non-commercial restrictions of a Creative Commons license. While ICC is a framework for donation (it does not transfer any rights or meaningful property in exchange for the donation), I belive the non-commercial restriction still triggers even in the case of donation-funded media (like Blender open movies). Just something that it's probably worth clarifying to the artist.

this seems pretty consumerist

Sure, this does "encourage the acquisition of goods and services in ever-increasing amounts" (which is how Wikipedia defines consumerism), but in moderation, isn't that a good thing?

It's really easy to look at the world and find one of the myriad ways that the profit motive results in a sub-optimal outcome. For example, the immense resources and investment in self-driving cars, and the relative dearth invested in electrifying and automating public mass transit, simply because creating a world where people are forced to buy, insure, and maintain heavy machinery to participate in society is much more lucrative than getting them where they need to be cheaply and efficiently. While ICC as an endeavor seeks to better align the profit motive with actual good societal outcome, there is an argument that could be made that relying so heavily on the profit motive is fundamentally flawed, and the only solution is to stop depending on it. I have no idea how to accomplish that, and I feel like I will get a lot more actual good done by pushing for my incremental changes that I will trying to implement an unspecified ideal solution.

That being said, if you're looking for a less commerce-driven solution, here are some options:

lobby politicians to increase funding for public services like radio and television
publicly voice support for your country's endowments and fellowships (like the National Endowment for the Arts)
support the artists in your local and online communities
go commission a profile picture or something. artists are really good at that kind of thing, and its really satisfying to show off something that was made just for you. also maybe like a ringtone.
- ~~https://banchan.art/~~ RIP
- (arguably also commerce-driven)
https://comradery.co/: Democratic cooperative Patreon alternative
https://resonate.coop/pricing/: Alternative funding model for music streaming
Benn Jordan's proposal of socialized copyright

donor entitlement

In order to preserve artistic autonomy, it must be abundantly clear that even if a proposal has the highest expected payout, it is not guaranteed to be the top priority. The creator should always be the one making the final decision, and they should ideally be completely unencumbered in their decision. Of course, reality is a poor fit for ideals, and even if someone was totally free to do whatever they wanted in their project, we live in a society with laws and costs of living that will influence what they are willing or capable of doing.

closing statement

For the foreseeable future, any attempt to fund a cool public project is a balance of doing the right thing for the future of the project and finding a sustainable source of income. If improvements came without costs and sacrifices, then things would be much easier. Hopefully, this paradigm is an improvement on the options currently available, but that remains to be seen.

MIDI Sucks: A Rant

Unknown — Sat, 01 Apr 2023 00:00:00 +0000

The following is an archive of a Twitter thread I made on January 12, 2019.

MIDI is a garbage standard that needs to be replaced in order for the music production and performance world to progress. It's modern development basically consists of workaround after workaround to try to make something that vaguely resembles a usable format.

The only thing its good at is boiling down keyboard instrument data. Literally any instrument that doesn't consist of a black-and-white set of clavier keys cannot be fully expressed using MIDI. For example, drums make different sounds depending on where and when you hit them.

MIDI also doesn't have enough data precision to represent a lot of human expression. Most notably, they had to split pitch bend control into two MIDI messages. If that's not kludging it, I don't know what is.

Furthermore, General MIDI is weak. It did well up until the early 2000s because pop music had a very limited use of synthesis. Everything was basically either a saw/squ lead/pad. However, with the surge in electronic influence on pop music, this is no longer the case.

127 is a very limited number. There are more than 127 types of musical sounds in the world. Heck, the number of percussion sounds alone exceeds the 127 limit of MIDI. Also, 7 bits? Really? Are we gonna live in 2019 and still not use a power of 2?

OSC is the obvious alternative, but it lacks a crucial feature that made MIDI ubiquitous: standardization. Because OSC doesn't have a rigorous standard, it can't really compete, which, in its defense, was intentional. MIDI's rigidity is what will (hopefully) lead to its demise.

Another crucial downside of OSC that I forgot to mention is that it doesn't have a file format. It kinda makes sense due to the fact that the messages aren't standardized, but if it's gonna overtake MIDI, having a way to save streams of data to read later or edit is a must.

Not to beat a dead horse, but another thing MIDI lacks that I forgot to mention is that it can't send multiple messages at once, making it pretty annoying and unpredictable when using it to stream live sequenced music data.

Replies

@[REDACTED] said: I think it works just fine...

My reply:

I think this picture is actually a very good argument against MIDI. In the center of your image is the Roland TR-808, which is quite possibly the most iconic electronic instrument ever, despite not using MIDI at all in any component of its functionality.

In addition, most of the stuff on 19' racks don't use MIDI as far as I can tell, and it would also be physically impossible for your mixer board to be MIDI compatible because it has more than 16 channels. Ultimately, MIDI was meant for a very specific thing: keyboard instruments.

I think of all the gear in that picture, the only thing that requires MIDI to function at a basic level is that red synth in the top right. Sure, some of the things in that picture can send and recieve MIDI, but I assuming you don't use the MIDI functionality of those keyboards.

Addendum (2023-091): The 'M' in "MPC" literally stands for MIDI, so that product could also probably be classified as one that "requires MIDI to function at a basic level".

A Plea for PoE

Unknown — Thu, 30 Mar 2023 00:00:00 +0000

Ever since music festivals became the primary medium for electronic music, live performance has become more about the giant spectacle of screens, lights, and fire. The musician becomes a mere speck on the stage, only there to make the audience feel like they're not just paying for a pre-programmed lightshow and a playlist¹. CDJs and laptops lock the performer to one position, and limits the dynamism and physicality of their performances. Heck, it's called Electronic *Dance* Music, but the vast majority of DJs don't do much more than bob their head, pump their arms, and clap their hands (TODO: write an article about how throwing a cake is the most innovative dance move ever performed by a DJ). It's great that electronic music has given lighting and effects operators the freedom to unleash their craft on the world, but I can't help but compare these shows to more musically performative events like rock concerts and drum circles, and wonder: what could it look like if today's instruments were better at expressing today's music?

I do want to emphasize: it is not the music, the musician, or the stage that is in need of reform. There is plenty of musicianship and creativity in electronic music today; arguably more than there was for rock and classical. Rather, it's the limitations and hassle of the hardware that restrict how that music can be performed. Perhaps a laptop is effective and convenient enough for the production of music, but I don't see a future in laptops as a tool for performance.

Anecdote of a musical stage perforance

I recently helped out with a few showcases for a local multimedia festival. One such showcase brought in a bunch of musicians of various genres one after another. One band had 5 members and a drum kit that had to be moved on and off, while one had just a laptop and a microphone². Now, between the two, you would think that the laptop would be a lot easier, right? Contrary to what I had expected, technical difficulties with the laptop put the whole schedule back almost an hour. A dongle was lost at some point, cables had to be switched out, devices had to be restarted; a textbook example of Murphy's Law. And this was on top of the already cumbersome setup process of taking each device out of a suitcase and plugging in the various power and USB cables. Once it got started, though, the performance was really cool!

The rest of this blog post presents a case for Power over Ethernet, a technological standard that I think is underused in music hardware today. I can't guarantee that it will solve all of these problems, but if there's anything I've learned from those last few days of stage work, it's that electronic music performance setup processes are in dire need of simplification. In its current state, using a laptop on stage with its tangle of cables going to MIDI controllers, audio interfaces, and power supplies is a complicated problem, solutions for which are very fragile (compared to setups for other types of music performance). My goal with this manifesto is to convince music hardware manufacturers to simplify the experience for electronic musicians performing their music, and provide them with the resources to make it easy to do so.

Crash course on PoE

Power over Ethernet (PoE) is a set of standards for, as you may have guessed, sending power over an Ethernet connection. Similar to USB-PD, the devices negotiate power, and both sides have to be compatible with the standard. If one side does not support it, the communication channel falls back to the default, which is 5 volts 0.5 amps (2.5 watts) for USB and no power for Ethernet.

As a disclaimer, PoE is competing against plain USB for most music hardware, but if you want something like a built-in speaker or motorized faders or LEDs out the wazoo, you'll want more than the 2.5 watts that regular USB is rated for, which will require some sort of external DC power supply, whether that's a barrel jack wall wart, USB-PD or PoE (or just crossing your fingers and hoping that your USB 2.0 host can provide more than 0.5 amps).

In all my reading, I was only able to find three "canonical" applications for PoE: security cameras, IP phones (phones that communicate over the internet rather than cell networks), and commercial wireless access points. Hopefully we can change that.

PoE vs USB-PD

	Ethernet	USB 3.0
Use cases	Limited to internet networking, and a small handful of other niches (one of which we will come back to later)	Very flexible, and near-universal (which seems to have been the goal, based on the name).
Speed	Cat 5e only allows for speeds up to 1 gigabit per second (but Cat 8 allows for up to 80 gigabits!)	At time of writing, can go up to 20 gigabits per second with compatible devices and cables.

	PoE	USB	USB-PD
Availability	Power usually comes from a switch, and most network switches (outside of commercial IT) don't support PoE (though PoE switches seem to be more common than USB-PD hubs)	Nearly every modern electronic device supports this. Computers, phones, keyboards, portable speakers, books, cigarettes, screwdrivers, etc.	Most laptops come with USB-PD chargers at time of writing, and if a battery bank has a USB type C output, chances are, it supports USB-PD.
Power	802.3af (Base-level PoE) nominally supports 15.4 watts, while 812.3bt (PoE++) supports up to 90 watts^[1]^[2]. Usually runs at 48 volts^[3].	A measly 5 volts at 0.5 amps, but often more than enough for digital musical instruments.	Boasts over 180 watts at 36 volts.
Impl	Requires dedicated circuitry. See the section on implementing PoE.	Just a plain 5 volt DC output.	Doesn't necessarily require a dedicated chip, only that your microcontroller has peripherals for USB-PD negotiation.
Negotiation	"Passive" process using current draw	Automatic, no negotiation	i have no clue tbh

So why PoE?

Despite USB being a better standard for 90% of applications, there is still a reason that Ethernet dominates the networking industry. The two main benefits that I can see are: cables are extremely cheap (and easy to crimp yourself), and can get extremely long. With USB 3.0 (using 26 AWG wire), you get approximately 3 meters maximum³. Even with the lower-bandwith USB 2.0, you get only get 5 meters^[4]^[5]. On the other hand, Ethernet cables (of any Category) are generally rated for 100 meters.

I believe this extra length is absolutely vital for making digital music controllers more performable. With USB, the musician is tethered to a circular area with a radius of 5 meters, but with Ethernet, the laptop doesn't even have to be on the stage. It could be setup somewhere out of the way and left alone between performances, which would have almost certainly prevented the issue with the laptop in the anecdote from earlier, since you could have all the equipment set up before the show starts, or at the very least, start setting up before the previous band is done. Or you could go as far as to have a rack-mount desktop, connect it to a PoE switch, and run a single ethernet cable to each musician and move around with the same freedom that an electric guitarist might have. Just one cable between the musician and the sound system.

While I don't know of any hardware that uses PoE specifically, there are plenty of open standards for audio over an Ethernet connection, often used to send many channels of audio over a "digital snake" from a stage to its sound booth and back. It isn't strange to see a roll or two of Cat 5(e) cable in a live venue's arsenal.

Some Pioneer CDJs and mixers are equipped with Ethernet for a feature that they call Pro DJ Link. Among other things, it connects any attached filesystems to other devices on the network, and can send the audio to a laptop (also on the network) with the appropriate software. I only know about this because during the aforementioned showcase, anytime there was a DJ accompanying the vocalist, the CDJs and mixer would be brought on stage in their flight case, (along with a Wi-Fi router and power strip), and setup was as easy as just plugging in the power and letting the booth take it from there. It was quick, easy, and went without a hitch every time.

The current state of DJ hardware connectivity is the future that I see for all music hardware: controllers, audio interfaces, rack-mount synthesizers, effects processors, eurorack, and anything other electronic device that can be used to make or perform music, all connected to one PoE switch offstage and nothing else.

One of the other use cases I've discovered recently is [Personal Monitoring Mixers]. These are apparently pretty common in studios and orchestra pits, and often (but not always) have PoE support. Unfortunately, they also tend to use proprietary audio over IP protocols, which I'm not too jazzed about.

Enter: Open Sound Control

By reading this far, you have just activated my trap card. For the past 3 years or so, I have slowly been coming to the conclusion that Open Sound Control (OSC) is the solution to almost all of my musical problems. Voice synthesizer plugin needs some way to receive phoneme info? OSC has character and string types. Want more semantically useful numeric types in a tracker-based DAW? OSC has single and double precision floats, 32 and 64 bit integers, booleans, infinity, timetags, and nil (if you count that as a numerical value). Need a file format that can express sample-accurate timing and namespacing? It's not standardized, but oscdump has a pretty reasonable output, and if that's not to your liking, you can just store the raw bytes, since time information is encoded in the packet (along with the message and its namespace, of course). Of course, OSC has its own drawbacks, so if you can do something entirely with MIDI, it's probably best to do it with MIDI. But if you need the length of an Ethernet connection anyway, you might as well use OSC as the transport layer for your MIDI data.

One of the notable things about OSC is that its designed to run on top of a network. Most OSC-compatible software asks for things like IP addresses and ports, and can communicate with OSC endpoints over the internet. OSC was made for Ethernet, and with the locking clip feature of RJ45 connectors (or optionally Ethercon), longer maximum cable length, and industry adoption of audio over Ethernet, PoE music hardware seems like it could be the "killer app" of OSC.

Implementing PoE

It's a bit tough to say authoritatively which is easier to implement between PoE and USB-PD from a hardware development perspective (focusing on the receiving end), as I've never implemented either.

That being said, I've spent a lot of my last few months looking at PoE, and it seems like the most simple way to go about it is using an RJ45 jack with built-in magnetics and a bridge rectifier (HY931147C or LPJ4112CNL), and a module like those offered by Silvertel, which total to about $15, which doesn't even include any of the parts you would need for the data part of ethernet. Certainly much more expensive than a USB-B jack.

If you're willing to get more DIY with it, you can break both the RJ45 jack and the PoE module up into their discrete components, for example with the following parts:

price	part no.	description
$0.88	MTJ-88ARX1-FSM-LG	RJ45 jack*
~$0.50	S16503G	magnetics (isolation filter, transformer)
$0.02	MB10S	bridge rectifier
$1.18	TPS2376D	PoE negotiator
$0.76	TX4138	step-down regulator

*: The RJ45 jack can be cheaper if you don't care about status LEDs or shielding

Approximating the generic parts (resistors, diodes, capacitors, inductors, etc) to less than $1 total, this comes out to under $4.34, which is still much more than the USB-B jack, but still managable for a high-end digital instrument.

TODO: finish

Closing thoughts

Please let me connect the music half of my 19" rack to the networking half.

Footnotes

Don't get me wrong, a good light operator makes the show worth watching; ghostdad is at least 20% responsible (a conservative estimate!) for the success of Worlds and its public perception as a Gesamtkunstwerk rather than just an album. Also, CDJs can totally be the right instrument for certain situations! Small sets at showcases and conventions, and places like Boiler Room come to mind. If you want music at your party, then a DJ is the perfect musician, and CDJs are the perfect instrument. Plus, some musicians don't want to learn to play an instrument, but still want to be involved in the presentation of their music, and for that, CDJs are perfect.

One performer even brought his own hardware rack-mount vocal processing device, complete with a dedicated technician/operator, who stood at the side, just offstage and spent most of the performance turning a single knob (presumably in a very particular or technically demanding way, otherwise he wouldn't have been flown out to do it)

I've definitely used USB (both 2.0 and 3.0) cables that are longer than the recommended maximum length, but even so, the maximum recommended length of an Ethernet cable is orders of magnitude longer. There are also active USB cables, and some that transmit over optical fibers, but at great cost.

References

[1] https://www.netgear.com/business/solutions/poe/overview/

[2] https://www.tp-link.com/us/solution/poe/

[3] https://superuser.com/questions/1105242/how-many-volts-there-are-in-poe

[4] http://janaxelson.com/usb3faq.htm#ca_maximum

[5] https://blog.tripplite.com/usb-cable-max-length

ICC Prior Art

Unknown — Wed, 28 Dec 2022 00:00:00 +0000

Continued from: ICC

bounties

Bountysource is a platform that allows bounties to be assigned to feature requests in an open-source code repository like GitHub (it currently does not support sr.ht, GitLab, Codeberg, or Bitbucket). Bountysource differs from incremental converse crowdfunding by:

allowing both users and developers to make bounties for a project, rather than just the project owners
acting as an escrow agent between feature requesters and devlopers (ICC explicitly does not hold any money, and allows funders to withhold funding after the deliverable is published)

Other examples:

https://github.com/obsproject/obs-studio/wiki/OBS-Project-Bounty-Program
https://contest.com/
https://docs.libretro.com/development/bounties/ (not a separate example, but discusses Bountysource)
https://www.cadsketcher.com/cad-sketcher-bounty-board

There have been quite a few arguments over the years against using bounties:

https://twitter.com/mitsuhiko/status/1703452194429690346
https://ziglang.org/news/bounties-damage-open-source-projects/
- A point-by-point analysis of the ziglang blog post is available in this supplementary reading
https://wiki.gnome.org/Attic/BountiesDiscussion
http://dneary.free.fr/gimp_bounties.html
https://discourse.gnome.org/t/bounty-development/5395/6

patronage

I am personally a fan of the feudal patron system where individuals with large amounts of money (like the Medicis) fund artists (like Mozart or DaVinci) to produce art. These days, it doesn't really make sense in the modern world where we have the labor specialization to fill important jobs like food production efficiently with just a few people, leaving pretty much everyone else to do whatever they want, and wealth consolidation is generally frowned upon. But given the situation at the time, I think it's cool that rich people (and churches) had an appreciation for the value and utility of the fine arts. Rich people these days have no sense of noblesse oblige.

That being said, it is neither democratic nor sustainable for the power of patronage to be so densely concentrated to so few people.

There are some small-scale examples of classical patronage, such as art commissions and feature sponsorships. http://ikiwiki.info/consultants/ describes their model as a way to "fund the development of a specific feature", which is frankly very similar to the proposal of ICC, but without being incremental, converse, or crowdfunded.

crowdfunded patronage

To address the issues with feudal patronage, platforms like Comradery, Ko-fi, and Patreon take this model and combine it with crowdfunding. These platforms are a pretty good way for creators with a decent following to get money from the their audiences. In general, I am in support of these platforms (Comradery and Ko-fi in particular), and I believe these types of crowdfunding will still have a place in the future, but a qualm I have with them is the issue of cross-subsidization.

To focus on a particular example, let's look at the Patreon of insaneintherainmusic, who makes Jazz (and Jazz-adjacent) covers of video game music. Funders pay a set price per cover video, which suggests that that is the product they are paying for. However, the patron tiers tell a different story; depending on how much a funder pays per video, they receive perks like access to special patron-only communication channels, early previews, and free lossless music downloads. In terms of incentive, it is clear to me that these perks, and not the actual videos, are what these patrons are paying for. After all, the videos will come out regardless of whether I, as an individual, choose to give $5, $1, or $0. For producers who don't have this kind of tier, Patreon is essentially a donation platform.

UPDATE: Patreon is phasing out per-creation billing, and will discontinue it by November 2025: https://news.patreon.com/articles/understanding-apple-requirements-for-patreon

Ko-fi is similar, but only allows monthly videos (rather than per-deliverable), and also has infrastructure for shops, commissions, and one-time donations. While their language is more clear about the fact that you're paying for the perks, some users don't have perks, or the perks are very low in value compared to the value of their creative or technical output, which, again, means that this is essentially a donation platform (albeit a very successful one).

case study: Philosophy Tube reading list

Philosophy Tube is a YouTube channel that aims to "give out a philosophy degree for free" (paraphrased). There used to be a book wishlist where people could buy books for the channel, and it is explicitly advertised that buying books from this list could have a big influence on the topic of future videos. There are some similarities to ICC: the artist proposes topics for future works, and people can use donations to steer the direction of the channel. There are, however, a few critical differences:

not converse: payment comes before the deliverable
there is no guarantee that an episode will be published that uses the book
funding is one-to-one; rather than being selected by a crowd, it is selected by an individual
the money goes to Amazon
it does not scale very well (limited by reading speed)

I believe that this wishlist has been abandoned, and nowadays, the channel is mainly funded through Nebula and Patreon, which is understandable given the last bullet point and the size of the channel's audience.

commissions

It's great that technology has made it so easy for me to commission a work of art from an artist I like. However, commissions are pretty expensive, and are generally heavily restricted by copyright. This leads to a less extreme version of the issue with patronage, where only people who can afford high prices for a luxury product can influence the creative output of artists. In my opinion, the critical downside of this is that commissions are a pretty inefficient use of artist time; since a digital product can be copied infinitely, there's a lot of missed revenue from only being able to sell the product to one person.

Commissions can be done fairly easily even without a dedicated platform, but Fiverr is a site that specializes in commissions. I've used Fiverr to sell work in the past, and it's fine, but it's not really creator-focused, and the quality is a bit shoddy.

As a sidenote, it may be useful going forward to think of ICC as a combination of commissions and crowdfunded patronage.

donation

Donation is a great way for a funder to show their appreciation for the creator in a tangible and beneficial way. However, the thing that makes this method of funding so meaningful, namely the lack of direct incentive for the funder, is exactly what makes it an unreliable and disproportionate form of funding. Unreliable because whether a person does or doesn't donate is difficult to predict and influence, and disproportionate because better quality or quantity doesn't have a direct influence on the donation total.

That being said, soliciting donations is often sufficient and sustainable for maintaining a project, even large projects like Wikipedia. Or rather, especially large projects like Wikipedia.

Quick sidenote: donations to the Wikimedia Foundation do not go to the volunteer editors of Wikipedia, many of whom believe that it is important that Wikipedia editors don't get compensated in order to prevent conflicts of interest and perverse incentives. A small fraction of the donations go to server infrastructure, but most of the money goes to employees of the foundation, whose job is, as far as I can tell, to solicit more donations for the Wikimedia Foundation. A "Bullshit Job" if I've ever heard one.

Examples:

OpenCollective - a donation platform with a focus on transparent spending
LiberaPay - a donation platform where funders can provide periodic donations to creators who contribute to the commons, whether they "make free art, spread free knowledge, [or] write free software"

advertising/sponsorships

I'm not a fan of advertising.

I don't like that I, as a producer, have to choose between ethics and money. Sure, I have the option to just ignore sponsors if I value ethics over money, but say I were a 3D printing video producer, and other people in my space are getting paid to shill some 3D printer filament while I have to pay for my own, plus they can use that extra funding to make their product better. Similarly to the previous case, I'm at a disadvantage as a result of my stubbornness.

I don't like that I, as a consumer, can be so easily influenced by a third party to buy their product. This ability to influence me also gives them a financial incentive to gather data on my behavior, ideally without me knowing. Knowledge is power, and through advertising, that power can be leveraged to move money from my hands to theirs. Also I think advertisements are annoying and I have yet to hear of a single person who believes otherwise.

I don't like that I, as a third party, can get a producer to leverage the trust they have with their audience to make me money. If I don't advertise and my competitors do, and my product is not good enough to compensate for the difference in brand recognition, then I lose sales. I'm not sure what the ideal method of informing consumers is, but I think the current state of advertising is definitely not it.

To be clear, "advertising sponsorships" refers to a third party giving a producer money in exchange for promotion of the third-party's good or service to the producer's audience. Affiliate links are often used to track the effectiveness of these sponsorships. Systems like GitHub Sponsors are more akin to crowdfunded patronage or donation.

There are some benefits to advertising though, and these benefits make it a very enticing (and difficult to replace) system for the people that use it. The main benefit (for the advertiser) is that participation is extremely passive. Advertising requires no login, no payment information, no calls to action. Sometimes can even happen without the viewer noticing with techniques like product placement (and that lack of awareness is, in my opinion, a big part of the problem).

microtransactions

In a sense, it is the opposite of advertising, in that participation is much more deliberate, and rather than targeting a wide range of people, it targets a very small subset of people who pay large amounts (known as whales), and constantly re-affirm their committment. Whales often make up the large majority of income for free-to-play games, and subsidize development, allowing even huge online games like Fortnite to be widely accessible at no cost or burden to the player. "From each according to ability, to each according to need", if you will.

I also put things like TikTok's live gifts and Twitch bits in this category, but they are a notably distinct subset that encourages its own behaviors.

collectibles

There is a class of item which has near-zero utility and cost to manufacture despite having a comparatively high price. Items in this category include signed portraits, art books, and vinyl records (way more people buy them than people who actually listen to them; myself included).

The primary issue with this class of product is the fact that they only provide funds by cross-subsidizing other offerings. With this useless token whose value is practically only influenced by how much other people are willing to pay for it, you can take a token like a vinyl record that costs $6 to produce, and sell it for $100 (or more). Its value comes primarily from its rarity, which limits the amount of these that you can produce before you start losing money, but for most people, it's worth making a few of these tokens to cross-subsidize their actual product, even if the collectors make far more money than the producers.

NFTs

Though they were a passing fad that pretty much disappeared as soon as they started being regulated, NFTs were advertised as a solution for this type of problem, and I think they're at least worth acknowledging. Non-fungible tokens were a means of abstracting a concept or non-tangible item into a tradeable digital token, allowing people to effectively trade it with each other as they would a unique physical item. There was a period of time when people brought these up whenever I mentioned ICC, but it seems those days have passed.

Open source pledge

Aside from the fact that it primarily targets maintainers of infrastructural FOSS projects (which ICC is not very well-equipped to serve), the Open Source Pledge (OSP) seems in some ways similar to ICC. Notably, it follows the same converse principle of "if you produce it, I will fund it", and is also nominally "pledge"-based.

However, because of the perspective that the leadership is approaching it from, and the shame-based nature of the campaign, I am skeptical in the OSP's ability to effectively solicit donations. My criticisms of the OSP can be summed up with two observations:

the only difference between the OSP and a voluntary periodic donation is the branding
the money is coming from large companies

Difference to voluntary periodic donation (or rather, the lack thereof)

The progenitor of the Open Source Pledge (OSP) is Chad Whitacre's article "Open Source Is a Restaurant", where they spend most of the article giving a long-winded and, in my opinion, ultimately irrelevant analogy about different models for charging for food.

They criticize grants because there are "hoops" that companies have to jump through to get them, but running a whole marketing campaign to shame corporations seems to me like a lot more work than navigating the grantwriting bureaucracy. Plus, I imagine this campaign will have to be repeated indefinitely, with much more momentum and support behind it than there is now, because, as the OSP campaign's own advertisements point out, tech companies are extremely stingy, and they never seem to feel shame in that fact. Heck, there are tech companies have been directly targeted for their active role in genocide, and I haven't seen any meaningfully change their behavior on that front.

Not only that, but I don't see any recommended mechanism for choosing which projects to donate to in the OSP literature, which indicates to me that it's up to the companies to decide? In which case what you've essentially done is replace a grant writing team with an entire marketing departement that is trying to convince the companies depnding on your project to donate to you instead of one of their other dependencies. Not only is this a more expensive hoop, but it is arguably more annoying than simple grant writing because the target audience is every dependent company and their developers, rather than just the entity distributing the grant. In contrast, ICC, rather than pitting different projects against each other, its more that different tasks under the same project are competing with each other, and assuming all tasks share a marketing budget, it doesn't really make sense for them to advertise against each other.

TODO: clarify why that's the case, stick in the anecdote about how
tobacco companies agreed to an advertising ban because something
something tragedy of the commons, and more profit when they didnt have
to compete with each other in advertising

Perhaps I'm approaching this with too much naïvité, but for the type of FOSS project that this targets, why not just threaten a strike? The maintainers could just say "this is how much money we need to sustain the project, and if we don't get it, then we will stop maintaining it until we do". Essentially, that would put the burden on the software companies to figure out a good way to fund it.

As it stands, the only companies that will choose to accept the OSP are those that feel honor, or ethical obligation, creating an artificial financial disadvantage for those companies (compared to those with no such honor or ethics). One could argue that this downside is worth being able to fund FOSS projects, but I'm skeptical whether that's the case.

The money comes from large companies

This might be unintuitive, but I think money should come from individual users more than large companies. Or at the very least, the amount that large companies give to a project should be a small proportion of the total. Taking the US government as an example, sources of money have a huge influence on the decisionmaking of an organization, even without an explicit quid pro quo, so collecting money from many smaller donors is, from my observation, important for making sure a software project remains beholden and accountable to its actual users instead of just one giant user.

thanks.dev

Sentry, one of the main participants of the OSP, is also one of the main donors on the platform https://thanks.dev, another donation platform. However, unlike the OSP, thanks.dev at least tries to implement a mechanism for determining how money should go to dependencies. The main flaw in this is that this creates a metric that can be gamed. While I'm hopeful that this will generally not be the case, consider this imaginary example:

Assuming the metric is based on number of calls into a API. A developer has a choice to implement something as either one call or two, and by making it two calls, they can increase the calls from each of their dependent libraries by an average of 3. Assuming each dependent has roughly 1000 API calls to various libraries before the new changes, then using two calls represents about a 0.3% increase in the metric. If they have 60 dependents with an average donation pool of $100,000 per year: $${60 * 100,000 * 0.3% = 18,000}$$ That's a roughly $18,000 per year increase in that one choice. Of course, these numbers are complete spitballed fabrications, but hopefully this shows that just one small change could potentially lead to huge changes in income, making it very enticing to make your library subtly more cumbersome and verbose to use than it otherwise would be.

With careful decisions on how the metric is calculated, I think it's possible for this to be mitigated enough that it's a net positive, but it does end up being a bit of an arms race.

However, unlike many other algorithms, the ICC algorithm works under the assumption that all involved understand its inner workings, and in fact, only works if people understand how it works. This hopefully makes it more stable and robust, and less prone to change.

Some other attempts at similar systems:

https://docs.drips.network/
- https://www.drips.network/blog/posts/radworks-gives-1m-to-foss-dependencies-with-drips
https://tea.xyz/
- had a scandal a while back where people tried to claim project income by adding .yml files to FOSS repositories.

Notably, both of these are cryptocurrency-centric projects, and for the same reason that I think large companies should not be the primary funding source for FOSS projects, I also think that speculative cryptocurrency bubble money is also not healthy, with the added downside of being even less financially sustainable.

TODO:

TikTok yum yum ice cream girl
- she's not doing it because she loves doing it and people want to see it.
- she's doing it because tiktok has created a system and she's figured out a way to game it.
- my tinfoil hat hypothesis is that the thing people like about it is the sense of control and connection (the instant gratification helps).
- how that concept be reframed into something that actually works for the common good?
https://artfight.net/donate
- not sure how to categorize this is because its a donation, but there are goal tiers that collectively paywall features (i.e.
bitwig's update model
- explicitly not a subscription
- i havent bought a bitwig update in like 5 years because i dont use it as much, but im glad i still can
- how common is it for people to just chain updates back to back instead of just waiting?
- how do the users feel about it? how do they perceive it?
  - do they consider it "free updates that come with the update they bought"?
  - or just "buying a year of updates"? (probably this one)
group buys / presale
- massdrop

ICC Scoring

Unknown — Wed, 28 Dec 2022 00:00:00 +0000

Read this first: ICC

Expected Donation Score

In my opinion, the most obvious concern is: if a donor can withhold their donation, what's preventing them from making a very large pledge and not paying after the work is published?

My proposed solution to this is to assign each donor a score that would roughly predict the amount that a given donor will give based on their pledge amount and past donations.

Lets consider an example: A fraudulent donor made a large pledge for proposal A that they don't intend to pay. I, as an artist, am choosing what to work on, and I see that proposal A has a much higher payout estimate than proposal B, and work on A as a result. Once I release my work, I end up not getting paid nearly as much as I would have for B, which, in this example, has mostly genuine pledges (though I cannot know that at this point in time).

This is where the "Expected Donor Score" (EDS) comes in.

One potential formula for this metric is $${S_0 = \frac{D}{P}}$$ where ${S_0}$ is the coefficient, ${D}$ is the sum of a donor's past donations, and ${P}$ is the sum of a donor's past pledges. But alas! If the fraudulent funder has previously fulfilled their pledge with a donation of $0.01, then they have a maximum EDS, and we're back to square one.

To fix this, let's scale the EDS by the amount paid: $${S_1 = D\frac{D}{P} = \frac{D^2}{P}}$$ Now, while the fraudulent funder still has an EDS of 1, a genuine funder who has paid $120 of their proposed $200 over the past 2 years has an EDS of 72, greatly outshining the fraudulent funder. 72 is a really big number though, and over the course of many years, it could be reasonable for a third donor to spend thousands of dollars total, making their "influence" many orders of magnitude higher than even the donor who has spent $120.

Let's try adding a time scaling factor. $${S_2 = \sum_i e^{-t_i} \frac{D_i^2}{P_i}}$$ where each payment/offering pair is scaled by how recent it was, ${t_i}$ being the amount of time that has passed since payment ${i}$ in months (an arbitrary time unit). Doing some napkin math, it seems like this helps with balancing the influence of long-term donors vs medium-term donors. We could add a few scaling and offset factors here and there, but for the most part, this seems to solve the problem at hand.

It's worth noting that this is definitely not the only solution to the stated problems, and almost certainly not the best! Perhaps it would be worth allowing artists to mess with this formula in order to let them use whatever they believe best predicts payouts.

One last potential issue I want to address is how fund offering amounts scale the EDS. Someone who has paid $120 over the course of a year suddenly declaring a $2000 fund offering is a bit suspicious, so we should incorporate that into our final calculation somehow. However, I think it's fine to leave the EDS as it is for now, and figure that out later if it actually becomes a problem.

As it stands now, the EDS roughly maps to the amount of money a donor is likely to provide based on all of their past donations.

The calulation of this score is critical to the functionality of converse crowdfunding, as it is what allows ICC to still work even though donors are allowed to retract their entire pledge after the work is published.

TODO

Consider the following: a fraudulent artist makes a proposal that they do not plan on fulfilling, and some donors declare pledges. In this example, the artist fraudulently "publishes" a trivial or low-quality work (say, a blank white image file rather than a page of a comic) just to claim the pledges. How can the system be built to minimally punish these donors? It's easy to say that the donors should have been smarter, and should either pay the amount they offered or retract their entire pledge and just take the hit to their EDS, but ideally, the system should try its best to nullify any incentive that would make the donors want to pay the fraudulent artist. In the long run, this type of fraudulent artist wouldn't last long, but one could easily imagine a washed-up one-hit-wonder artist making one last grand proposal, to which many donors offer pledges, just to run into the above situation where the work is low-quality or nonexistent, intended only to trigger the donation invoice.

Could the EDS be adjusted to mitigate these scenarios? Would it require a totally separate mechanism?

In this case, perhaps we could normalize the offerings? If almost every funder withholds part or all of their compensation, we should be able to use that to quantitatively measure the extent to which the producer "failed" to deliver.

This might be solved by making the EDS unique to each funder-creator relationship, since it's unlikely that the funder cares about their EDS when the creator has tanked trust. However, what about the case where there's plausible deniability, and there might be hope for the creator to make something legitimate in the future?

aliqot

Unknown — Fri, 13 Dec 2019 00:00:00 +0000

This was a project I did in my undergraduate studies to build a digital music controller abstractly based on the bass guitar. The main sensing mechanism was a long row of capacitive touch sensors, intended to sense where along the neck the player was touching, and how much of their finger was touching the surface. In the end, this barely worked, and was a bit clunky to use, and I therefore didn't end up building a full-scale version of the device.

Prior art:

Someone who made something cooler and more useful and more concretely similar to a bass: https://youtu.be/4m1YorzgxkY
A commercially available device that (I think) uses the same sensing technology as the previous example: https://maywadenki-os.stores.jp/items/5eef5b521829cd47b90668be

Capacitive touch

Front

Back

Capacitive touch is one of those things that I had heard a lot about, but never really tried myself. I've had a little capacitive sensing test PCB sitting around for a while, but I never got around to using it. The general idea is that a conductive pad and a finger of varying distance constitutes a capacitor, and by measuring the capacitance at the pad, you can find out how far the finger is from the pad, or how much of the finger is covering it. In retrospect, it was pretty straightforward, but I definitely feel much more comfortable now that I did in the earlier stages of this project.

555

My first approach to measuring the capacitance was an analog circuit. I am most definitely not an analog person. The only analog signals I feel comfortable with are those that either come out of a digital-to-analog converter or one coming into an analog-to-digital converter. However, since the goal of this project was to learn things, getting out of my comfort zone seemed like a good idea.

The idea behind this approach was to set up a 555 timer with a diode and some resistors such that it would pull up the voltage with some RC constant and pull it down with a different RC time constant. I thought that if my clock speed was high enough, I could get a pretty smooth continuous analog signal that I could measure with an ADC. While this did end up working, the range of voltages was too low to be useful, and led to a lot of extra circuitry that could have been avoided by using a different method.

Pulse and read

The more traditional approach to capacitive touch sensing is to connect the pad to an ADC, a GPIO output, and a pull-down resistor. By turning the GPIO on, then setting it to an input (floating), the voltage of the pad will decay at different speeds depending on the capacitance. I thought I was being clever by leaving the diode in from the previous approach, but it turned out to make my measurements a little less accurate, so I probably should have removed it. This is the approach I ended up using, and I think it's accurate enough for decent analog measurements.

Next steps

Something that I'm less than satisfied with is the response curve of the pad. It seems to basically max out as soon as the pad is touched, and I was hoping that it would be more of a gradual change depeding on how much of the pad was covered. To solve this, I could either change the shape and size of the pad or decrease the resistance of the pull-down resistor.

Sound generation

Front

Back

The rough acoustic equivalent of the digital instrument that I hope to design is a bass guitar. In my experience, the easiest way to acoustically simulate a bass guitar sound is to send a PWM waveform through a low-pass filter into a saturator. For now, the plan is to start with the PWM wave. A stretch goal was to design the sound processing in a music programming language called Faust, but like many of my stretch goals, I never really got to that point. I ended up learning Faust anyway for fun, and I think it's really cool, especially since it compiles to C++. Getting a variable pitch PWM output from the TM4C microcontroller was pretty straightforward, and I didn't really run into any huge problems setting that up.

A secondary benefit of using PWM rather than an ADC is that to amplify it, all I need is a single transistor. I eventually want to have more flexible audio outputs, so I'll need a real amplifier in the future, but for now, I've just arranged 2 2N2304 transistors in a Darlington pair configuration.

Switches

Front

Back

In the time I spent thinking about instrument interfaces and which ones work and which ones don't, one of the conclusions I came to was that while pitch control is generally easier to implement as a non-tactile experience, rhythm, or more generally, volume, is almost necessarily tactile. For example, a violin can be split into the fingerboard, which controls pitch, and the bow, which mostly controls volume. The fingerboard feels about the same at low pitches as it does at higher pitches. On the other hand (pun intended), the bow transmits the resistance of the hairs against the string, increasing as you apply more pressure or move the bow faster. The piano is similar in that different pitches mostly feel the same to play, but different volumes feel different (assuming you're only playing with one finger). This distinction is true to some extent for most instruments, though it is unclear if that is due to how instruments have evolved over time or if it is a physical restriction of acoustic instruments. Either way, what is most intuitive at this point in time is for rhythmic elements to be tactile, which is why I've included switches as the sound triggering element of the instrument.

Shift registers

I'm usually pretty good about reading datasheets. I'm not sure exactly what happened, but when I was making my PCB, I thought that the pin labelled DS (for Data Serial) was the serialized output of the shift register. It turns out that it's the input, which I figured out after not getting any output until accidentally probing the adjacent pin. I think if the serial in and serial out pins weren't next to each other, I would have spent much longer trying to figure out what was wrong.

QFN

The more keen-eyed readers will notice that the above PCB is unpopulated except for the switches and one integrated circuit. This is because it is a more recent revision that I haven't yet gotten to work. The main difference between this revision and the last one is that I swapped out the SOIC chip for a QFN one. This allowed me to make the board much smaller, but also much more difficult to debug. Because there is no way to probe whether the pad on the PCB is conducting to the pad on the IC, I have been having trouble figuring out why the boards are having issues being programmed. For now, I've decided to ignore it because I have a working board with essentially the same circuit.

Mechanical Design

Front

Back

Pictured above are two revisions of the 3D printed bracket part that I made to hold the capacitive sensing PCB, both made in FreeCAD. The part was built to fit onto a piece of 2020 aluminum extrusion. I'm a big fan of aluminum extrusion because it's very easy to use. In this case, all I have to do is cut it to an arbitrary length and attach stuff to it. I don't even need a second piece. I've had issues in the past where the structures I've build were too weak to hold their own weight, but because this is lighter and simpler, I didn't run into that problem. The main feature of the newer revision is that it has registration holes to align the loose end of the bracket with the bracket below. While the 3D printed part is very rigid (material is PETG), even a small change in alignment could tear the pads off one of the boards since they are soldered together on the back.

The framework

The goal was to create a framework that would allow hot-swappable modules to send continuous streams of low latency analog-to-digital converted data. The details of the communication framework are probably enough to fill an entire other blog post. In fact, I probably will write another one at some point that goes into why I made all the design decisions I did. For now, though, I'll just outline how it works.

When the modules are initially connected, they are detected by their parent module and registered with the main module (in this case, the TM4C that is generating the sound). This registration value is prepended to all of the communication from this module to tell the main module where each set of data is coming from.

The first byte of each communication from a child module to its parent is the number of modules that are sending data in a given set. Each module's data then follows one after another. The first byte of a module's data is its address, and the second byte is how many values are being sent as data. The switch modules send 1 byte and the capacitive sensing modules send 8 bytes.

The example below is what is sent to the TM4C from a capacitive sensing module, which is connected to a switch module such that TM4C <- capacitive_sensing <- switches.

byte #:               1    2    3    4    5    6    7    8    9   10   11   12   13   14
hexadecimal value: 0x02 0x01 0x08 0x01 0x01 0x01 0x01 0x01 0x01 0x01 0x01 0x02 0x01 0x0A

Byte descriptions:

1st byte: # of modules
2nd byte: Address of the first module
3rd byte: # of bytes of data in the first module
[4:11]th byte: Data
12th byte: Address of the second module
13th byte: # of bytes of data in the second module
14th byte: Data

Byte addresses are one-indexed (as opposed to zero-indexed)and all data has 1 added to it because a 0 byte indicates that data is not yet ready to be send. I wouldn't need to do this if I was using a multi-leader bus, but I'm not using one, so I do need to. Either that or I would have to somehow indicate whether or not a byte is ready to be sent.

Circular buffers!

The way the framework is set up, I need two buffers for input and output data. Because these buffers are continuously filled and emptied as a FIFO queue, it made sense to make it a circular buffer. In the repository, this is implemented in modport.c. One of the goofs that I ran into was that I was incrementing the position of the queue when I added elements to it rather than its length. Oops.

An addendum

While circular buffers are great, and worked fine for this application, I think it actually would have made more sense to make it a ping-pong buffer, as one way to implement the communication framework is to make the output buffer a concatenation of the input buffer and the additional data for the module, with one modification at the beginning of the input queue. I think I would also have to change the communication protocol to send the number of bytes rather than the number of modules, which limits throughput more than I would like. Also, I like the idea that the data packet can be indefinite, so I'll probably leave it as is until I hit a performance obstacle.

Obstacles

I spent much longer than I should have trying to figure out why the protocol was working with the switches, but not the capacitive sensing. A third of the time was because the initialization was commented out, and the remainder is because the initializations have to be in a particular order for some reason.

The only thing that I haven't figured out yet is why the TM4C (the main module that produces the sound) won't communicate over SPI with its child modules. Serial communications are definitely being initiated, but there is no data being transferred between the two microcontrollers. I suspect it has something to do with the fact that TI uses SSI, which has Rx and Tx, while the ATtiny uses SPI, which has LOMI and LIMO. Either that or it's a 3.3v vs 5v issue. Now that I think about it, it's almost certainly the latter.

an aside regarding the silly name

The goal of this project was to create a modular instrument framework that I could use in the future to more quickly produce digital instruments. I spent roughly 20 minutes jumping around on Wikipedia until I ended up on the entry for aliquot stringing, and after seeing the keywords "several" and "sympathetically", I figured it would be a good name for the project given the goals. I also took out a letter for better search engine optimization.

Closing thoughts

Though I didn't end up with a fully functional instrument, I achieved all but one of my goals. I have a thing that takes an input and a thing that makes sound, and now all I need to do is put them together. Based on my initial tests, the latency in communication between modules is pretty much negligible. I haven't tested it with more than 4 modules, but the results seemed negligible at a small scale, and I'm fairly certain that most of the observed latency was caused by communication with the LEDs rather than the communication between the modules themselves. One thing to test in the future is using a bus protocol like CAN or I2C (preferably CAN due to bidirectional multi-leader capabilities) rather than a serial protocol, as it could help with scalability.

HXCSTR

Unknown — Sun, 01 Dec 2019 00:00:00 +0000

The problem

This project came out of an interest in learning how to play isomorphic keyboard layouts and a personal wish to perform live electronic music. The primary product this is based on, the Novation Launchpad Mk II, is a square grid of 64 red/green LED backlit silicone dome keys. While this was a suitable setup for some cases, I often found myself needing more buttons, and didn't like using it as a pitched instrument. In addition, this time in my life was a pivotal point in my love for hexagons. In my research, I had discovered the sonome, a large (and expensive) isomorphic keyboard, and the C-thru Axis 49, a smaller (but still pretty expensive) isomorphic keyboard. I liked both of these, but my favorite thing about the Launchpad was the colored lights, as they not only provided visual feedback to the player, but also easily turned an audio-based performance into an audiovisual experience. Also, there's an entire industry built around putting lights with music, and I feel like that has to exist for some reason.

The solution

After seeing the viability of a hexagonally arranged set of keys, I sought to make a keyboard that was minimally expensive (below $500 per unit, optimally below $150 at large scales), RBG LED backlit, and user-reprogrammable. Other than these necessary elements, other design priorities included satisfying physical and visual response, ergonomics, and ease of manufacturing.

Potato for scale

Teensy

PJRC's Teensy seems ubiquitous in the hobbyist music technology scene nowadays, and I would attribute that to 2 factors. The first is that it's a very wholesome company that seems to only be able to do good things. The second is that the Teensy has supported MIDI over USB since the Teensy 2.0. My original prototype of the HXCSTR used the Arduino, which is a great teaching tool, but a pretty lackluster microcontroller. I think Arduino boards nowadays support MIDI, but it took them a loooong time to do it.

Keys

Inside the HXCSTR

Switches

I don't remember how exactly I came across the Cherry MX line of switches, but I had a friend around that time of my life who was really into mechanical keyboards, and I think I learned about them from him. I liked the keys because they had a pretty long travel distance, which most MIDI controllers didn't (other than piano-style keyboards). I also felt like building the HXCSTR using them made them feel more premium, though I'm not sure how accurate that is. For anyone who knows about mechanical keyboard switches, my choice of the black variety of Cherry MXs may seem like a terrible idea, but there was a very very good reason for it: they're much cheaper than other Cherry switches. For anyone not familiar, the Cherry MX line of keyswitches come in many colors, and each color indicates a different style of switch. Some have a tactile bump, others have an audible click, and there are many different actuation forces for each. Black Cherry MX switches have the highest actuation force and no tactile or audible enhancements. While a loud MIDI keyboard would probably be distracting, I think the tactile bump would have been helpful. It didn't really matter which style I chose anyway, since they all have the same PCB footprint and I could replace them if I ever felt the need to.

Shift registers

Most mechanical keyboards and MIDI controllers read their switches by using a diode matrix. The basic idea behind this is that you can index by rows and columns rather than attach a pin to each individual switch. This means for a 12x12 grid of switches, you only need 24 pins from a microcontroller to read all the switches rather than 144. A better solution (as far as I know), however, is to use shift registers. Though the way it works is very very different, a shift register is practically a digital multiplexer. You can send a signal to it to tell it to read all of its inputs (8 inputs per shift register in my case), then use a simplified verison of SPI to send that data to the microcontroller.

Velocity?

Unfortunately not. I saw a similar project at one point that also used Cherry MX switches, but they cut off the bottom of each switch to allow the stem to hit a second switch. I (foolishly) thought that velocity sensitivity wasn't worth cutting up 91 Cherry MX switches, designing and populating a whole extra PCB, and doubling the read time of each switch, so I went without velocity sensitivity. This project was less about being able to play expressively and more about learning the layout (and, to be honest, showing off).

Keycaps

The keycaps in my first prototype were laser cut, and I also experimented with resin casting a 3D printed part (a very smelly and sticky mistake), but once I got to the point where I could make these at larger volumes, I switched to injection molding. It was a huge hassle, but in the end, I think it was the right decision. The keycaps are made from polypropylene, and the diffusion is achieved by introducing a little bit of white pigment. I'm very satisfied with the appearance of the keycaps, but they add a lot of unnecessary weight, and the stems should have been round instead of rectangular.

Spacing

The key offset spacing was selected to be similar to that of a piano key. Additional spacing between keys is not something that existed in the Sonome or Axis-49, but I thought that it would be necessary in order to reduce friction between keys. It was not, and I definitely should not have included spacing between the keys. Hindsight is 20/20.

LEDs

In the first prototype, I hot-glued the LEDs to the keys. While that was all fine and dandy, it was definitely not the optimal way to add lights. In the final version, I ended up with two PCBs-- one for the keys and one for the lights. The lights PCB was essentially a glorified LED strip that snaked through the board. I ended up giving myself a few headaches by not indexing the lights in the same direction in every row (instead, the rows snaked back and forth, alternating direction), but nothing too terrible. I actually had to reorder the LED boards because I didn't leave enough clearance for the stems to pass through the holes in the board.

WS2812B

If you've ever worked with large sets of RGB LEDs, you've probably heard the part number 'WS2812B' before. This LED is individually addressable, meaning each LED can be a different color, and it only requires one data pin, as opposed to the usual 2. The way it achieves this is by using a synchronous communication protocol. This protocol uses a varying pulse-width signal to send digital data serially through the chain of LEDs. What this essentially amounts to is an LED strip that's super cheap and very easy to send data to, but also limited in its data transmission rate. A synchronous protocol is (almost?) always limited to a single clock rate, and to ensure compatibility with a wide range of microcontrollers, that clock rate is generally not the highest it can be. As a comparison, the WS2812B's data rate is one LED per 30 microseconds, while the APA102, which has a clock signal, only takes a little over 2 microseconds per LED at its fastest. While a 28 microsecond difference is small by itself, these LEDs are generally used in large numbers, usually hundreds in a chain (in this project, there were 91 in a single serial chain). The more important difference in timing, however, is the internal PWM oscillator rate. To allow a range of colors, each component color of the LED is controlled by a PWM signal, which can be modified to make the color seem brighter or dimmer. This brightness is more or less controlled by turning the LED on and off very very quickly, and if the speed that it's turning on and off is too slow, it can lead to weird artifacts in videos and pictures, or worse, eye strain (not a confirmed medical effect, just me guessing). According to Tim, the WS2812B is about 430 Hz while the APA102 runs at 19200 Hz. I've never had any issue with image artefacts with APA102s. If you leave this blog post with one takeway, it should be that APA102s are much better than WS2812Bs.

Power

One of the most annoying hardware problems with the initial prototype was dealing with the 3.3v and 5v conversion. I also ended up switching my power jack component when I didn't need to, which was a bummer. The fact that it was a different height than the USB jack was a little annoying. Plus, for the most part, the current is low enough that it can be powered by just USB, so if I designed it better, I could've avoided the barrel jack altogether, or at least made it optional.

Layouts

TODO

Tonnetz/Harmonic Table
Wicki-Hayden
Janko
Drum Flowers

Other hexagonal isomorphic keyboards

Roughly in chronological order

Starr Labs MicroZone U648

I know next to nothing abouth this one, and only came across it as I was writing this article. Seems fine.

C-Thru Axis-49

Mentioned earlier in the article, and probably the first commercial electronic isomorphic keyboard. They are now out of business, but their controllers are still floating around on resellers these days. In my opinion, the keys were way too close together, and felt terrible. At least they were velocity sensitive though. These were the primary inspiration for the HXCSTR, in the sense that I thought I could do a lot better.

Rainboard

https://youtu.be/blNM4tX_0gE

Very pretty, and I appreciate the transparent enclosure. It seems like the velocity is global though, and at that point, I would've opted to omit velocity sensitivity altogether. I also personally don't like how arcade buttons feel, but there are definitely people out there who really like them. The accompanying app also seems like a pretty convenient way to mess with the configuration. The pitchbend is also a nice feature that I wish I had on the HXCSTR.

I think shiverware fizzled out a long time ago, but someone else made their own rainboard in 2020, and they do not seem to be affiliated.

Unnamed keyboard

https://youtu.be/ItuyHjraXlg

Another one with mechanical switches. Reminds me of this rat maze: https://youtu.be/skcJc2KV4_Q?t=1722

BeeBoard

https://youtu.be/YEPOQTkfUn8

Also don't know much about this one.

Lumatone

One of the more recent iterations, and probably the biggest so far. And most expensive. They seem to be aiming pretty firmly at the microtonal crowd, which I think is clever because I think they tend to be more open to buying more esoteric and gimmicky gear than most other types of musicians.

dualo/equis

https://dualo.com/en/

The polyphonic expression is nice.

s-ol 0x pads

Designed to work as both a computer keyboard as well as a musical keyboard. Also the only one on this list that is OSHW certified. I'm personally really interested in this one because I saw a picture of an alternate case that lets 4 of them fit together to make a mega keyboard, and I think that's fun.

There's also a guide written by someone who works at Adafruit on making your own board with the same keycaps (which are available seperately).

Hexboard

3D-printed keys. Not sure how I feel about them. The firmware seems to have a lot of features though, and they are fellow sr.ht enjoyers.

This website

Unknown — Sun, 01 Dec 2019 00:00:00 +0000

So you want to make a website?

Make a text file, put whatever words you want in it ("Hello World!" are some popular first words), and put .html at the end of the filename. Congratulations! You've made a website!

Of course, this lacks many of the features widely considered important for most websites, such as being connected to the world via the internet.

But there are two pieces of advice that I have for any form of self-expression:

Put more things out into the world before they're done. One of the great things about digital media is that it's practically free to "release" something, so do it as often as you can, throughout the process.
You can put as much into a medium as you would like. Even if that amount is practically nothing.

Tools I've used to make websites

Plain HTML and CSS

In my opinion, very underrated. My [contact page] is made using just HTML and CSS, and I think it does an excellent job at conveying the information it needs to. It was easy to set up and easy to update and adjust. It doesn't scale up very well, but it scales down excellently.

Static site generators

The first iteration of this website was made using Jekyll, and I now use [Zola], but all static site generators work pretty much the same way:

pick a theme
write some markdown files
run the generator
upload the resulting files to a hosting service (or self-host!)

I like this a little more because it separates the actual content of the site from the minute details of how everything is going to look.

Hosting services

Any web service should be hosted. While you could host it yourself (I don't know exactly how, but I hear NGINX is involved), there are so many free (in both cost and source code) options out there that, in my opinion, it really doesn't make much sense to self host a static site.

GitLab - I had some issues getting the GitLab pages pipeline to work properly, and some redirection authentication shenanigans. I don't remember a lot about the process, but at the time, I found it to be smooth and simple. I'm not sure what my frame of reference was.
Codeberg - I had a few hiccups (that I've unfortunately forgotten the details of), but other than the fact that the compiled website has to be stored in a repository, I'm pretty happy with it.
pages.sr.ht - Very nice upload workflow that lets you just curl a .tar.gz file. The upload process is as easy as running a shell script, and when it comes to statically generated sites, I greatly prefer running a script over the Codeberg workflow, which requires two seperate repositories: one for the source files and one for the generated site output. The only caveat with sr.ht is that it doesn't allow third-party scripts. Which, frankly, makes sense, but I really want asciinema and KiCanvas and Sketchfab embeds, so I'm currently useing Codeberg for this site.

There are also some options that I haven't evaluated yet:

surge - The CLI-centric workflow is nice, but I don't want to install some random node.js program.
glitch - You have to use their editor; doesn't let you upload your own website (except through a GitHub import, after which you once again have to use their editor)
bunny - It seems like there's an FTP upload option, but I can't figure out how to use it. Also, it's not free.

Markdown shortcodes in Zola

Made a shortcode file, and I use it by adding the following snippet to a post:

{{card(
	title="↹lature",
	link="/mus-tec/tlature#chain-view",
	desc="devlog - Implementing a niri-like signal chain viewer"
)} }

It creates a little card for visiting the article.

Unfortunately, Zola doesn't provide the information to automatically generate the title and description from the markdown front matter (all available variables can be shown with {{ __tera_context | json_encode(pretty=true) }}), so next step is to see if that's a thing that can be forked in.

This information is available in the context of page templates, which is how the auto-generation of the "All pages" sections on group pages like the homepage or Music Technology page, but those variables store the output of the markdown -> html rendering process, which of course won't be available during the process itself. That being said, assuming the front matter is independent of the html output, it should be possible to have that information available during markdown rendering.

wiki/garden?

TODO: write a review of the following blog post: https://maggieappleton.com/garden-history#a-brief-history-of-digital-gardens

Trackballs

Unknown — Fri, 18 Oct 2019 00:00:00 +0000

Pros:

Very very space efficient
Related to the previous, but it can be used on any surface. I often place the trackball on my leg or on the windowsill of the bus. Even my massive trackball that's not intended for travel is easier to travel with than the most portable mice I've seen due to the freedom of placement.
Less arm movement. I use Dvorak for the same reason.
More thumb usage. It's the strongest finger, why don't we use it more?

Cons:

The muscles that you have to use to move the cursor a given amount in a given direction change depending on the current hand and finger position due to the spherical nature of the ball. Mice do not have this problem because they are usually used on a flat surface. Imagine using a mouse on a spherical surface.
Less selection

Recommendations:

Elecom HUGE

Best large trackball I have used. Better than the Kensington Expert in ergonomics, function buttons, and scroll mechanics. As much as I love scroll rings, they really aren't easy to use. Comes in both wired and wireless USB dongle varieties.

Elecom DEFT PRO

This is the trackball I use with my laptop. The Bluetooth option is a huge workflow improvement, but my favorite thing about it is that it allows for wired USB, wireless USB or Bluetooth in the same model, as opposed to the Elecom HUGE, which has two separate models for wired and wireless, and no Bluetooth on either. Also has one fewer function key than the HUGE.

Logitech M570

A good entry level trackball. I personally don't like thumb balls, but all of my friends seem to prefer them over finger balls, possibly due to the positioning of the left and right click. Finding left click seems to be the first issue that people have when they try to use my trackballs. I personally think it only takes about 30 seconds to get used to the positioning on a finger ball, but mileage may vary.

Logitech MX Ergo

I have never owned or used one of these, so I can't officially endorse it, but it seems to be the thumb ball equivalent of the Elecom DEFT PRO. Very pricey though.

`u`	`w`	`!u` (to `F`)	`u && w` (to `B`)	`u && !w` (to `D`)	node
❌	❌	✅	❌	❌	`F`
✅	❌	❌	❌	✅	`D`
❌	✅	✅	❌	❌	`F`
✅	✅	❌	✅	❌	`B`

`u`	`w`	`!u` (to `F`)	`u && w` (to `B`)	`u && !w` (to `D`)	node
❌	❌	✅	❌	❌	`F`
✅	❌	❌	❌	✅	`D`
❌	✅	✅	❌	❌	`F`
✅	✅	❌	✅	❌	`B`

`u`	`w`	`!u` (to `F`)	`u && w` (to `B`)	`u && !w` (to `D`)	node
❌	❌	✅	❌	❌	`F`
✅	❌	❌	❌	✅	`D`
❌	✅	✅	❌	❌	`F`
✅	✅	❌	✅	❌	`B`