• Part 1: Why did I need to build this?
• Part 2: Using AI to write software
• Part 3: The end product with source code and instructions for use

Why did I need to build this?

Todoist is a mobile and web-based task manager app. As a maker of lists, I love this service. A desktop web interface and snappy mobile app stay out of the way and assist my mind in the way only great software can. They’ve gracefully combined all the features you could want in a task list app without making it overly complicated to use. Hats off for that.

As much as I love Todoist, it’s a “software as a service” or cloud app. That means they store and control my data, ultimately deciding what data to retain and for how long, what data to make available and how. It’s a reasonable trade-off for a great app with seamless synchronization between desktop and mobile environments. That said, I pour considerable amounts of personal data that is valuable to me into this app. My access to that data outside the confines of a paid service is equally important to me.

Todoist provides a nice backup page where you can download daily zips of your data. Unfortunately, those backups lack much of the data you’ve put into the app. They do not include completed tasks, related sub-tasks, comments or attachments. The backup provided is a zip of CSV files, not easily viewable outside of a spreadsheet. That’s a lot of data and access they’re choosing not to make available to paying customers.

The motivation behind that decision is obvious. Many SaaS businesses are willing to shackle customer data in order to subtly force reliance on the monthly subscription. Making it a little bit harder to leave the service helps maintain the all-important MRR. Todoist is not alone in this. As subscription software services have become the norm, so has vendor lock-in via data access limitations. Customers who aren’t technically savvy or interested enough to host their own open source software apps are stuck with little recourse.

For some reason, all that missing data in Todoist backups is accessible if you’re a developer. Kudos to them for providing a nice stable API with — as far as I can tell — complete data access. But shame on them for significantly limiting the data paying customers can export unless they have software development skills. Come on, guys.

Faced with this conundrum, I decided to build a solution for exporting all the data from Todoist using their API, so customers without development skills can back up and access their own data outside the paid service.

Using AI to Write Software

And now for something completely different. The fear and loathing and unchecked optimism around AI in the software development community is rampant right now. As a developer wanting to remain relevant in this economy, it is a technology I need to be using. Would I have enjoyed writing this script on my own? Yes. Would it have taken substantially longer to do so? Yes.

A popular expression that describes what’s going on with AI and software development right now is that “English is the new programming language”. Software developers have traditionally spent their day writing code in some programming language like C# or JavaScript or Python. AI now does the programming well enough that it’s more efficient if developers become orchestrators, specification writers and code reviewers, telling the AI what to do and monitoring the results in a feedback loop until the job is done to satisfaction.

On one hand, I’m blown away by this technology. It’s really good. I love being able to whip up a quick shell script in the time it takes to describe what it should do. On the other hand I see the imminent death of software development as we know it. I love programming, so that’s sad.

After learning Todoist has a robust API that provides access to the data I wanted to backup, I decided to use Github Copilot to build it for me in Python. LLMs are really good at language, and programming is just another language to them. Copilot is implemented as a chat bot that sits in the IDE, the software developers use to write, build, run and test code. I used Visual Studio Code for this project.

I started with this basic prompt:

Create a command line script that exports all active and completed tasks from the Todoist API to a JSON file.
- Use the Todoist API documented at https://developer.todoist.com/api/v1/
- Use the Todoist python client documented at https://doist.github.io/todoist-api-python/
- Use a .venv to scope the python environment.
- Include tasks from all active and archived projects.
- Include all active and completed tasks available in the API. This may require paging through results.
- Save attachments to an ./attachments folder and reference the attachment name for each in the JSON output.
- Tasks are nested under project objects in the JSON result, with each project object containing all available project fields in the API.
- Include all task fields available in the API for each task.
- If a task has comments, nest them in an array under the task in the JSON output.
- Name the JSON file Todoist-Actual-Backup-YYYY-MM-DD.json where YYYY-MM-DD is the current date. Overwrite the file if it already exists. 
- Use the API key provided in the TODOIST_KEY environment variable.
- Run the export if the script is run with the "export" argument. Any other argument, or no argument, displays a description of what the script does and how to use it.
- After writing the JSON result, use its contents to create an attractive human readable version in a single file HTML document named Todoist-Actual-Backup-YYYY-MM-DD.html. This file groups tasks by project and includes all project and task details, including attachments (link to the locally downloaded files) and comments. Use a Jinja2 template to generate the HTML file.

Create a command line script that exports all active and completed tasks from the Todoist API to a JSON file.
- Use the Todoist API documented at https://developer.todoist.com/api/v1/
- Use the Todoist python client documented at https://doist.github.io/todoist-api-python/
- Use a .venv to scope the python environment.
- Include tasks from all active and archived projects.
- Include all active and completed tasks available in the API. This may require paging through results.
- Save attachments to an ./attachments folder and reference the attachment name for each in the JSON output.
- Tasks are nested under project objects in the JSON result, with each project object containing all available project fields in the API.
- Include all task fields available in the API for each task.
- If a task has comments, nest them in an array under the task in the JSON output.
- Name the JSON file Todoist-Actual-Backup-YYYY-MM-DD.json where YYYY-MM-DD is the current date. Overwrite the file if it already exists. 
- Use the API key provided in the TODOIST_KEY environment variable.
- Run the export if the script is run with the "export" argument. Any other argument, or no argument, displays a description of what the script does and how to use it.
- After writing the JSON result, use its contents to create an attractive human readable version in a single file HTML document named Todoist-Actual-Backup-YYYY-MM-DD.html. This file groups tasks by project and includes all project and task details, including attachments (link to the locally downloaded files) and comments. Use a Jinja2 template to generate the HTML file.

From this prompt and after waiting a minute or two, I got a finished, but not working Python script. That AI produced what it did is impressive, but it’s still a lot like working with a junior developer who knows every programming language. It doesn’t make the best decisions if not provided with sufficient direction.

After several cycles of run, paste the error into chat, repeat, I had a working script that met the requirements I’d given. That initial process didn’t take more than a few hours.

I then tested and tweaked, adding several features along the way. For example, I realized I was only getting 90 days of completed tasks and that was a limitation imposed by Todoist. So I asked it to maintain a local file of completed tasks across runs to extend their storage beyond 90 days and include them in exports.

Adding features like this works a lot like the initial prompt. Just explain what the feature should do, and maybe provide some technical direction where needed. The AI comes back with detailed explanations of the logic its going through in planning and executing a solution, all in plain English. Source code control allows the developer to clearly see and review the changes the AI has made at each step.

Creating this script felt collaborative. In addition to generating and updating code, Copilot is great for discussing feature implementation options and providing recommendations that are backed with solid reasoning. For example, when I ran into API rate limits during testing, we had a good discussion over the pros and cons of caching API calls vs a more complex rate limiting mechanism. During that, I realized the issue was less that we needed to limit the rate and more that the initial implementation was highly inefficient in its use of the API. That led to a huge decrease in the number of API calls required to run the script.

Even though this is programming in English, someone who doesn’t understand software development would probably struggle with anything even marginally complicated. If you’re not careful, you can easily end up with software that seems to work but is a real mess under the hood. How much does that matter if AI is doing the coding? It’s a good question.

Sadly, developers today are helping to train AI to do this job with full autonomy. Tools like Google’s Jules can be assigned tasks via a ticketing system, which are then completed, tested and submitted for review by AI. As this becomes the norm, a team of 5 software developers and a team lead could easily be reduced to just the team lead. And how strong of a developer will that team lead be when they haven’t written their own code in years?

In any case, I spent maybe 8 hours total on this script. My direct code edits were limited to small visual changes to the HTML output that weren’t worth bothering with the AI to make. It would have taken me substantially longer to write this from scratch. So it’s a win for AI. I enjoyed working with Copilot to build it — it’s literally like assigning tasks to a developer and reviewing the results in a feedback loop.

The Todoist Actual Backup script

OK, enough with the blah bidy blah. You can grab the code at https://git.bagaag.com/matt/Todoist-Actual-Backup/. Here’s the README for the project:

Todoist Actual Backup

Todoist is a SaaS task manager. Todoist provides backups of current tasks, but they do not include completed tasks, subtask relationships, comments or attachments. Nor does it provide a human-readable backup in HTML. This Python script provides a command-line tool to export all available active and completed tasks from the Todoist API to a JSON file, including attachments, subtasks and comments, and generates a human-readable HTML backup.

Features

• Exports all active and completed tasks from all projects (active and archived)
• Nests tasks under their respective projects, including all available fields
• Includes comments for each task
• Downloads attachments to output/attachments/ and references them in the JSON and HTML output
• JSON and HTML files are named with the current date when the script is run
• Maintains Todoist-Completed-History.json so completed tasks older than Todoist’s 90-day API window stay in future exports
• Reuses archived comments for completed tasks to avoid unnecessary API calls (assumes no new comments after completion)

Setup

• Ensure you have Python 3.8 or newer installed. Check with python --version on the command line.
• The script uses a .venv for dependencies. Run the following in a terminal from an empty project folder:
  python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
• Get your API key from Todoist
• Optionally set your Todoist API key in the TODOIST_KEY environment variable. If the environment variable is not set, the script will prompt for it.

Usage

1. In a terminal, run source .venv/bin/activate if needed to enter the virtual environment.
2. Run the script with the export argument: python export_todoist.py export

This will create output/Todoist-Actual-Backup-YYYY-MM-DD.json and output/Todoist-Actual-Backup-YYYY-MM-DD.html, and it will update output/attachments/ with any downloaded files while leaving Todoist-Completed-History.json in the project root. Keep Todoist-Completed-History.json somewhere safe (e.g., in source control or a backup location); it is the only way the exporter can retain completed tasks older than Todoist’s 90-day API retention window.

I’ve incorporated this script into my weekly backup process. It was fun to build and hopefully it will be useful to others. I may explore providing a stand-alone executable for it so folks who aren’t comfortable installing Python can use it. Let me know in the comments if that would be useful to you.

My requirements were fairly straightforward:

1. Generate unique keys that are as short as possible.
2. Simple web interface to shorten a URL.
3. Redirect requests for generated keys to the corresponding URL.
4. Secure against external abuse.
5. Build the simplest thing that works.

While I generally prefer Python, setting it up on a web server is something of a bother. My server already supports PHP, so I created a one-letter subdomain on bagaag.com and started with an empty PHP file. I coded in Visual Studio Code connected to the server via SSH. ♫ It’s my server and I’ll code on production if I want to! ♫

The first requirement was the most interesting to me. I’ve often wondered about the algorithm that sites like tinyurl.com use. I thought about the problem, what kind of keys I’d like to see, and came up with this algorithm:

Given a unique set of characters, iterate through each in order, adding characters as required to retain uniqueness.

I implemented this in a function that takes as input any string the algorithm might generate and returns the next string in the sequence.

// Unique set of characters for generating keys
$charset = 'acr8mqbs7di4tuh6e9fjv2gwx0nlk5poy1z3'; 

// Provides the next key by incrementing the previous key.
// Start with empty string and then feed the return value 
// back into this function to get the next key, and repeat.
function increment_string($s) {
    global $charset;
    // convert the charset to an array of characters
    $chars = str_to_chars($charset);
    // if the string is empty, return the first character
    if ($s === '') {
        return $chars[0];
    }
    // convert the input string to an array of characters
    $string = str_to_chars($s);
    // iterate over the input string characters from end to beginning
    for ($index = count($string) - 1; $index >= 0; $index--) {
        // find and validate the position of the character in the charset
        $char = $string[$index];
        $pos = array_search($char, $chars);
        if ($pos === false) {
            return "Character not in set: $char";
        }
        // if the character is not the last in the charset, increment 
        //it and break
        if ($pos < count($chars) - 1) {
            $string[$index] = $chars[$pos + 1];
            break;
        } 
        // character is the last in the charset; wrap around to the 
        // first character
        $string[$index] = $chars[0];
        // if we are at the beginning of the string, prepend the first 
        // character and break
        if ($index === 0) {
            array_unshift($string, $chars[0]);
            break;
        }
    }
    return join('', $string);
}

// Unique set of characters for generating keys
$charset = 'acr8mqbs7di4tuh6e9fjv2gwx0nlk5poy1z3'; 

// Provides the next key by incrementing the previous key.
// Start with empty string and then feed the return value 
// back into this function to get the next key, and repeat.
function increment_string($s) {
    global $charset;
    // convert the charset to an array of characters
    $chars = str_to_chars($charset);
    // if the string is empty, return the first character
    if ($s === '') {
        return $chars[0];
    }
    // convert the input string to an array of characters
    $string = str_to_chars($s);
    // iterate over the input string characters from end to beginning
    for ($index = count($string) - 1; $index >= 0; $index--) {
        // find and validate the position of the character in the charset
        $char = $string[$index];
        $pos = array_search($char, $chars);
        if ($pos === false) {
            return "Character not in set: $char";
        }
        // if the character is not the last in the charset, increment 
        //it and break
        if ($pos < count($chars) - 1) {
            $string[$index] = $chars[$pos + 1];
            break;
        } 
        // character is the last in the charset; wrap around to the 
        // first character
        $string[$index] = $chars[0];
        // if we are at the beginning of the string, prepend the first 
        // character and break
        if ($index === 0) {
            array_unshift($string, $chars[0]);
            break;
        }
    }
    return join('', $string);
}

I like this algorithm because it can be easily customized in terms of the characters it uses in the keys. The value for $charset came from randomizing “abcdefghijklmnopqrstuvwxyz0123456789”. I did that so the keys look meaningless to the casual observer. If you change $charset to 'abc' the sequence of keys looks like this: a b c aa ab ac ba bb bc ca cb cc aaa aab aac.… So by giving it a whole bunch of characters to choose from and randomizing them, you get seemingly meaningless and unique keys that are as short as possible.

I could have included capital letters and exponentially increased the key capacity, but mixed case keys look messy to me and I don’t need the capacity. Without them, I’m only waist deep in four character keys at the one million mark. I’m not building a SaaS product — this is just for personal use.

After writing this, I did some research on how this is generally done to see how far off I was. A base-62 encoder seems like the obvious path among the various implementations I found. Instead of math, I used fairly efficient string manipulation to achieve a similar result.

With the fun part over, I whipped up storage for the last key generated and a mapping of keys to URLs. Again, simple as possible. Even SQLite would be massive overkill here.

$last_file = 'last.txt'; // file to store the last incremented key
$urls_file = 'urls.txt'; // file to store the URLs with their keys

// Returns the contents of $last_file, or empty string if the file 
// does not exist
function get_last() {
    global $last_file;
    if (file_exists($last_file)) {
        return trim(file_get_contents($last_file));
    }
    return '';
}

// Writes to $last_file
function set_last($s) {
    global $last_file;
    file_put_contents($last_file, $s);
}

// Reads the last key, increments it, saves it, and returns it
function next_key() {
    $last = get_last();
    $next = increment_string($last);
    set_last($next);
    return $next;
}

// Adds a URL to urls.txt and returns the generated key
function add_url($url) {
    global $urls_file;
    $key = next_key();
    // append the key and url to urls.txt
    file_put_contents($urls_file, $key . ' ' . $url . "\n", FILE_APPEND);
    return $key;
}

// Looks up a key in urls.txt and returns the corresponding URL, 
// or null if not found
function get_url($key) {
    global $urls_file;
    $lines = file($urls_file, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
    foreach ($lines as $line) {
        list($k, $url) = explode(' ', $line, 2);
        if ($k === $key) {
            return $url;
        }
    }
    return null;
}

$last_file = 'last.txt'; // file to store the last incremented key
$urls_file = 'urls.txt'; // file to store the URLs with their keys

// Returns the contents of $last_file, or empty string if the file 
// does not exist
function get_last() {
    global $last_file;
    if (file_exists($last_file)) {
        return trim(file_get_contents($last_file));
    }
    return '';
}

// Writes to $last_file
function set_last($s) {
    global $last_file;
    file_put_contents($last_file, $s);
}

// Reads the last key, increments it, saves it, and returns it
function next_key() {
    $last = get_last();
    $next = increment_string($last);
    set_last($next);
    return $next;
}

// Adds a URL to urls.txt and returns the generated key
function add_url($url) {
    global $urls_file;
    $key = next_key();
    // append the key and url to urls.txt
    file_put_contents($urls_file, $key . ' ' . $url . "\n", FILE_APPEND);
    return $key;
}

// Looks up a key in urls.txt and returns the corresponding URL, 
// or null if not found
function get_url($key) {
    global $urls_file;
    $lines = file($urls_file, FILE_IGNORE_NEW_LINES | FILE_SKIP_EMPTY_LINES);
    foreach ($lines as $line) {
        list($k, $url) = explode(' ', $line, 2);
        if ($k === $key) {
            return $url;
        }
    }
    return null;
}

For security, I started by limiting the domains that can be shortened to a defined list. Then I decided I’d rather just have that be unlimited for my personal use and added a hard-coded password. You can use either or both of these options by tweaking the configuration at the top.

// list of allowed domains for URL shortening
$allowed_domains = []; 
// password to shorten a URL, leave empty to disable password protection
$password = 'open sesame'; 

// list of allowed domains for URL shortening
$allowed_domains = []; 
// password to shorten a URL, leave empty to disable password protection
$password = 'open sesame'; 

With all the necessary functions out of the way, I focused on the HTTP request handling to tie them all together. get_input just looks for a variable in either _GET or _POST.

// read input parameters
$url = get_input('url');
$input_password = get_input('password');
$key = get_input('key');

// If a URL is provided, attempt to shorten it
if ($url) {
    // if a password is set, check it
    if ($password !== '' && $input_password !== $password) {
        http_response_code(401); // Unauthorized
        echo "Unauthorized: Incorrect password.\n";
        exit;
    }
    // return 422 if the URL is longer than max_url_length
    if (strlen($url) > $max_url_length) {
        http_response_code(422); // Unprocessable Entity
        echo "Invalid URL.\n";
	    exit;
    }
    // return 403 if the URL's domain is not in the allowed list
    $parsed_url = parse_url($url);
    if ($parsed_url === false || 
            !isset($parsed_url['host']) || 
            !test_host($parsed_url['host'])) {
        http_response_code(403);
        echo "Forbidden: Domain not allowed.\n";
        exit;
    }
    // validate the URL and shorten it
    if (filter_var($url, FILTER_VALIDATE_URL)) {
        $key = add_url($url);
        $shortened_url = "https://$_SERVER[HTTP_HOST]/$key";
        echo "$shortened_url\n";
    } else {
        http_response_code(422); // Unprocessable Entity
        echo "Invalid URL.\n";
    }
    exit;
}

// Otherwise, assume the request URI is a key to look up
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$key = trim($path, '/');

// If the key is valid, look up the URL and redirect
if ($key !== '') {
    $url = get_url($key);
    if ($url !== null) {
        header("Location: $url", true, 301);
        exit;
    } else {
        http_response_code(404);
        echo "Not Found.\n";
        exit;
    }
}

// read input parameters
$url = get_input('url');
$input_password = get_input('password');
$key = get_input('key');

// If a URL is provided, attempt to shorten it
if ($url) {
    // if a password is set, check it
    if ($password !== '' && $input_password !== $password) {
        http_response_code(401); // Unauthorized
        echo "Unauthorized: Incorrect password.\n";
        exit;
    }
    // return 422 if the URL is longer than max_url_length
    if (strlen($url) > $max_url_length) {
        http_response_code(422); // Unprocessable Entity
        echo "Invalid URL.\n";
	    exit;
    }
    // return 403 if the URL's domain is not in the allowed list
    $parsed_url = parse_url($url);
    if ($parsed_url === false || 
            !isset($parsed_url['host']) || 
            !test_host($parsed_url['host'])) {
        http_response_code(403);
        echo "Forbidden: Domain not allowed.\n";
        exit;
    }
    // validate the URL and shorten it
    if (filter_var($url, FILTER_VALIDATE_URL)) {
        $key = add_url($url);
        $shortened_url = "https://$_SERVER[HTTP_HOST]/$key";
        echo "$shortened_url\n";
    } else {
        http_response_code(422); // Unprocessable Entity
        echo "Invalid URL.\n";
    }
    exit;
}

// Otherwise, assume the request URI is a key to look up
$path = parse_url($_SERVER['REQUEST_URI'], PHP_URL_PATH);
$key = trim($path, '/');

// If the key is valid, look up the URL and redirect
if ($key !== '') {
    $url = get_url($key);
    if ($url !== null) {
        header("Location: $url", true, 301);
        exit;
    } else {
        http_response_code(404);
        echo "Not Found.\n";
        exit;
    }
}

And finally, the bare minimum HTML to make it usable.

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Bagaag.com Micro URL Shortener</title>
</head>
<body>
    <h1>Bagaag.com Micro URL Shortener</h1>
    <form method="post" action="">
        <label for="url">Enter URL to shorten:</label><br>
        <input type="text" id="url" name="url" size="50" required><br><br>
        <?php if ($password !== ''): ?>
            <label for="password">Enter the password:</label><br>
            <input type="password" id="password" name="password" size="20"   
              required><br><br>
        <?php endif; ?>
        <input type="submit" value="Shorten">
    </form>
</body>
</html>

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Bagaag.com Micro URL Shortener</title>
</head>
<body>
    <h1>Bagaag.com Micro URL Shortener</h1>
    <form method="post" action="">
        <label for="url">Enter URL to shorten:</label><br>
        <input type="text" id="url" name="url" size="50" required><br><br>
        <?php if ($password !== ''): ?>
            <label for="password">Enter the password:</label><br>
            <input type="password" id="password" name="password" size="20"   
              required><br><br>
        <?php endif; ?>
        <input type="submit" value="Shorten">
    </form>
</body>
</html>

Anyway, I had fun with this. It’s up and running for me at r.bagaag.com. Here is a shortened link to see it working: https://r.bagaag.com/j

Here is the full source.

To run it yourself, just host it on a domain of your choosing, like r.yourdomain.com. Make sure PHP has write access to the files named at the top. I recommend placing the text files outside the site root, or configure your web server to block requests to them.

If you just want to test it locally, use the terminal to run it like this from the directory that contains index.php:

$ php -S localhost:3000

Then browse to http://localhost:3000. You’ll need to change “https” to “http” in the script if you’re not going to use HTTPS.

mido is a midi library for Python that wraps the lower-level midi library python-rtmidi in a friendlier API. It can do a lot of things, but I was primarily interested in using code to control a synth in Bitwig Studio. I ended up writing a little step sequencer API. I used to love playing with Seq 303 back in the 90s, and that’s sort of what I had in mind in terms of how to model midi notes into a song.

I started by defining a Note class.

# note.py
import mido

class Note:

    # http://bradthemad.org/guitar/tempo_explanation.php
    LENGTHS = {
        'w': 240,
        'h': 120,
        'q': 60,
        'e': 30,
        's': 15,
        't': 7.5,
        'dq': 90,
        'de': 45,
        'ds': 22.5,
        'tq': 40,
        'te': 20,
        'ts': 10
    }

    # what is the equivalent of '1' numeric duration value
    DURATION_MULTIPLIER = LENGTHS['q']

    def __init__(self, value:int, duration, multiplier=1, velocity:int=64):
        self.value = value
        self.duration = duration
        self.multiplier = multiplier
        self.velocity = velocity

    # Converts a note length value like dotted eighth to a value 
    # in seconds based on default or provided bpm tempo. 
    # Length abbrs: w, h, q, e, s, t, dq, de, ds, tq, te, ts 
    # (whole/half/quarter/eight/sixteenth/32nd, dotted/triplet)
    def seconds(self, tempo:int):
        if  type(self.duration) == str:
            if self.duration in Note.LENGTHS:
                len = Note.LENGTHS[self.duration]
                return len * self.multiplier / tempo
            else:
                return 0
        else:
            return self.duration * Note.DURATION_MULTIPLIER / tempo
        
    # Returns mido "note_on" message
    def get_on(self):
        print(f"On {self.value} {self.duration}")
        return mido.Message('note_on', note=self.value, 
          velocity=self.velocity)

    # Returns mido "note_off" message
    def get_off(self):
        print(f"Off {self.value} {self.duration}")
        return mido.Message('note_off', note=self.value)

# note.py
import mido

class Note:

    # http://bradthemad.org/guitar/tempo_explanation.php
    LENGTHS = {
        'w': 240,
        'h': 120,
        'q': 60,
        'e': 30,
        's': 15,
        't': 7.5,
        'dq': 90,
        'de': 45,
        'ds': 22.5,
        'tq': 40,
        'te': 20,
        'ts': 10
    }

    # what is the equivalent of '1' numeric duration value
    DURATION_MULTIPLIER = LENGTHS['q']

    def __init__(self, value:int, duration, multiplier=1, velocity:int=64):
        self.value = value
        self.duration = duration
        self.multiplier = multiplier
        self.velocity = velocity

    # Converts a note length value like dotted eighth to a value 
    # in seconds based on default or provided bpm tempo. 
    # Length abbrs: w, h, q, e, s, t, dq, de, ds, tq, te, ts 
    # (whole/half/quarter/eight/sixteenth/32nd, dotted/triplet)
    def seconds(self, tempo:int):
        if  type(self.duration) == str:
            if self.duration in Note.LENGTHS:
                len = Note.LENGTHS[self.duration]
                return len * self.multiplier / tempo
            else:
                return 0
        else:
            return self.duration * Note.DURATION_MULTIPLIER / tempo
        
    # Returns mido "note_on" message
    def get_on(self):
        print(f"On {self.value} {self.duration}")
        return mido.Message('note_on', note=self.value, 
          velocity=self.velocity)

    # Returns mido "note_off" message
    def get_off(self):
        print(f"Off {self.value} {self.duration}")
        return mido.Message('note_off', note=self.value)

And then a basic sequencer to play them.

# sequencer.py
import concurrent
from concurrent.futures import ThreadPoolExecutor
import mido
from threading import Thread
import time

from note import Note

class Step: 
    def __init__(self, value:int, duration:int=1, start_tick:int=0):
        self.enabled = True
        self.start_tick = start_tick
        self.adjust_duration_for_start_tick = True
        self.note = Note(value, duration)

class Sequencer:
    def __init__(self): 
        self.tick_count = 16
        self.tempo = 100
        self.step_length = 60
        self.step_seconds = self.step_length / self.tempo
        # an array of steps played in sequence,
        # nested arrays are chords
        self.steps = []
        # this is system specific
        port_id = 'Virtual Raw MIDI 0-0:VirMIDI 0-0 16:0'
        self.port = mido.open_output(port_id)

    def play(self):
        # using a thread for each note feels heavy-handed,
        # an interesting optimization problem
        with ThreadPoolExecutor(max_workers=5) as executor:
            for ix in range(len(self.steps)):
                step = self.steps[ix]
                if type(step) == Step and step.enabled:
                    print(f"Step {ix+1}: {step.note.value}")
                    self.play_step(executor, step)
                elif type(step) == list:
                    print(f"Step {ix+1}: {self.chord_str(step)}")
                    for substep in step:
                        self.play_step(executor, substep)
                time.sleep(self.step_seconds)

    def play_step(self, executor, step):
        future = executor.submit(note_player, self, step)
        future.add_done_callback(note_finished)

    def chord_str(self, steps):
        return [step.note.value for step in steps]

def note_player(seq:Sequencer, step:Step):
    applied_length = seq.step_length / seq.tempo
    delay_seconds = step.start_tick * ( applied_length ) / seq.tick_count
    note_seconds = step.note.seconds(seq.tempo)
    if delay_seconds > 0:
        time.sleep(delay_seconds)
        if step.adjust_duration_for_start_tick:
            note_seconds = note_seconds - delay_seconds
    seq.port.send(step.note.get_on());
    time.sleep(note_seconds)
    seq.port.send(step.note.get_off());
    return step

def note_finished(future:concurrent.futures.Future):
    print(f"Finished: {future.result().note.value}")

# sequencer.py
import concurrent
from concurrent.futures import ThreadPoolExecutor
import mido
from threading import Thread
import time

from note import Note

class Step: 
    def __init__(self, value:int, duration:int=1, start_tick:int=0):
        self.enabled = True
        self.start_tick = start_tick
        self.adjust_duration_for_start_tick = True
        self.note = Note(value, duration)

class Sequencer:
    def __init__(self): 
        self.tick_count = 16
        self.tempo = 100
        self.step_length = 60
        self.step_seconds = self.step_length / self.tempo
        # an array of steps played in sequence,
        # nested arrays are chords
        self.steps = []
        # this is system specific
        port_id = 'Virtual Raw MIDI 0-0:VirMIDI 0-0 16:0'
        self.port = mido.open_output(port_id)

    def play(self):
        # using a thread for each note feels heavy-handed,
        # an interesting optimization problem
        with ThreadPoolExecutor(max_workers=5) as executor:
            for ix in range(len(self.steps)):
                step = self.steps[ix]
                if type(step) == Step and step.enabled:
                    print(f"Step {ix+1}: {step.note.value}")
                    self.play_step(executor, step)
                elif type(step) == list:
                    print(f"Step {ix+1}: {self.chord_str(step)}")
                    for substep in step:
                        self.play_step(executor, substep)
                time.sleep(self.step_seconds)

    def play_step(self, executor, step):
        future = executor.submit(note_player, self, step)
        future.add_done_callback(note_finished)

    def chord_str(self, steps):
        return [step.note.value for step in steps]

def note_player(seq:Sequencer, step:Step):
    applied_length = seq.step_length / seq.tempo
    delay_seconds = step.start_tick * ( applied_length ) / seq.tick_count
    note_seconds = step.note.seconds(seq.tempo)
    if delay_seconds > 0:
        time.sleep(delay_seconds)
        if step.adjust_duration_for_start_tick:
            note_seconds = note_seconds - delay_seconds
    seq.port.send(step.note.get_on());
    time.sleep(note_seconds)
    seq.port.send(step.note.get_off());
    return step

def note_finished(future:concurrent.futures.Future):
    print(f"Finished: {future.result().note.value}")

And finally, a little celebratory tune.

# tada.py
from sequencer import Sequencer, Step

step1 = Step(60, 1)
step2 = Step(64, 1)
step3 = Step(67, 1)
step4 = Step(72, 1)

step1a = Step(60, 4, 1)
step2a = Step(64, 4, 2)
step3a = Step(67, 4, 3)
step4a = Step(72, 4, 4)

steps = [step1, step2, step3, step4 ]
steps.append([step1a, step2a, step3a, step4a])

seq = Sequencer()
seq.steps = steps
seq.play()

# tada.py
from sequencer import Sequencer, Step

step1 = Step(60, 1)
step2 = Step(64, 1)
step3 = Step(67, 1)
step4 = Step(72, 1)

step1a = Step(60, 4, 1)
step2a = Step(64, 4, 2)
step3a = Step(67, 4, 3)
step4a = Step(72, 4, 4)

steps = [step1, step2, step3, step4 ]
steps.append([step1a, step2a, step3a, step4a])

seq = Sequencer()
seq.steps = steps
seq.play()

Here’s the output of python tada.py.

Step 1: 60
On 60 1
Off 60 1
Finished: 60
Step 2: 64
On 64 1
Step 3: 67
Off 64 1
Finished: 64
On 67 1
Step 4: 72
On 72 1
Off 67 1
Finished: 67
Step 5: [60, 64, 67, 72]
Off 72 1
Finished: 72
On 60 4
On 64 4
On 67 4
On 72 4
Off 60 4
Finished: 60
Off 64 4
Finished: 64
Off 67 4
Finished: 67
Off 72 4
Finished: 72

And here’s what it sounds like running through the Bitwig Organ.

If you want to run this locally, you’ll need a midi device to convert the midi notes into sound. For me, that is Bitwig Studio. It might just work using the built-in software synth on Windows, but I haven’t tried it.

You’ll also need to install some python packages. Here’s the requirements.txt.

mido
python-rtmidi
importlib_metadata

And here are shell commands to create a virtual environment, install these requirements, and run the program (I’m using bash).

mkdir midosequencer
cd midosequencer
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python song.py

This was a fun little project. It was interesting to realize how conceptual music time has to be converted into literal time, down to when each note should stop and start, calculated from tempo and note length — something humans do without thinking about it. It also makes me curious how real sequencers like Bitwig handle concurrency and timing.

This topic reminds of my favorite poem by Frank O’Hara: Why I Am Not a Painter.