Musebot Getting Started

So you want to create a musebot – fantastic! Here are some things that you should know…

Here is some basic information as a PDF…

Here is a 40 minute (!) video – originally created for a Kadenze course on Generative Art – covering everything you need to know to getting musebots to run and interact, as well as developing your own musebot.

Getting Started Collection

Here are some musebots to get you up and running (note that it is over 300 MB). The same musebots if you are running Windows 32 bit or Windows 64 bit.

If you are on Mac OS 10.12 (Sierra), please read this guide to downloading and running the musebots.

Here is the source code for a Max musebot to add to the above collection, to get started on creating your own musebot.

The Musebot Specification

This is a collaborative document (found here) that describes how to make a musebot in general terms. You can comment on it, and make suggestions.

The Musebot Developer Kit

This is a GIT repository, hosted on Bitbucket, containing the source code and examples related to the musebot project: https://bitbucket.org/obown/musebot-developer-kit. It provides the source code in some different environments (Max, Java); however, due to its limitations on size, no working musebots (i.e. applications) can be found here.

The Musebot Test Suite

A complete listing of current musebots can be found under the “Complete Musebot Listing” menu.

These are ZIP archives of existing, functioning musebots. Some contain source code; others do not. They are meant as working bots for experimentation and re-combination. Try them out!

It’s a good idea to check back here regularly, as these often get updated.

Running JackAudio

An original goal of the musebot specification included using Jack to route audio between musebots, for those that wanted to interact on the audio level. In order to do so, you need to be running the latest version of JackAudio, found here.

Ollie Bown has written a Java script that will allow Jack to send every audio input to every audio output. Run this jar before starting the Conductor, and those musebots that require Jack (i.e. _derivationsBOT, Chichichi, ob_DeciderMusebot, and ob_prockRockBeadsBot) will function properly.

Musebot Templates

Find them here (WebDAV).

Using these example musebots:

  1. On your computer, create a folder, and name it something like “Musebot Test”
  2. Copy the “Musebot Conductor Application” folder into this folder. Don’t change name of the folder.
  3. Create a new folder beside it (inside your test folder), and name it “Musebots”. It must have this exact name.
  4. Copy a few of the zipped musebots into this folder (i.e. _derivationsBOT.zip is the first of these).
  5. Unzip all the archives, then trash the archives.
  6. Double-click either one of the Conductor applications.
  7. The musebots (found within the Musebot folder) should appear in the drop-down menu to the far right. Select one, and that musebot application will launch. Continue to launch musebots until you’ve found an interesting ensemble.
  8. Kill musebots by clicking on the “Kill” button beside the musebots slider in the Conductor.
    • Alternatively, you can quit the musebot itself (command-Q), as it is an application. Within five seconds, that musebot will disappear from the conductor (since the musebot’s heartbeat will have disappeared).

Developing and testing musebots

Create a new folder in the Musebot folder. From an existing musebot source, copy the following files:

  1. config.txt file;
  2. run.command file;
  3. info.txt file.

The config.txt file

When the Conductor first launches, it finds the Musebots directory, and, in each of the directories inside that directory, it rewrites the config.txt file with unique port numbers. Therefore, any time you add a new musebot to this directory, you will need to relaunch the Conductor.

The config.txt must have the following lines:

id name_of_your_musebot
mc_hostname localhost
mc_listen_port 4747
my_listen_port xxxx
output_channels 2

Note that the id should not include the .app extension. Also, the my_listen_port values will be rewritten by the Conductor, so whatever number you put here doesn’t matter.

The run.command file

This file is used by some Conductors to launch the musebot applications using the terminal. Edit the last line in this file to reference the name of your musebot:

open name_of_your_musebot.app

The run.command file can be edited by control-clicking on the file, and selecting a text-editor.

The info.txt file

This file is mainly there for other developers and curators to understand what your musebot is doing. However, current development includes scanning this file for relevant keywords, so please include at least the following information:

## instrumentation ##

(description of what your musebot does, using keywords (i.e. “generates beats”, “plays bass”, “makes melodies”, etc.).

It’s a good idea to list the messages your musebot is listening for, and what messages it is sending.

We are building a taxonomy of musebot types, so adding a few types to your instrumentation will help. For example, a sample-based beat generating drum bot might be described as:

type:
@beat
@drums
@sample-based

## messages ##

List any non-standard messages that the musebot sends or receives and how agent responds to such messages.

sends:
@send_message_1 …
@send_message_2 …

receives:
@receive_message_1 …
@receive_message_2 …

Your musebot application

Your musebot should be a double-clickable application that can launch on its own. For musebots created in Max, this means building a standalone application.

Developing Musebots in Max

Some example musebots and their source code can be found in the Max Musebot Examples folder, found here.

The example patches (Max_Lead, Max_Keys, Max_Drums) are three examples to show three different types of musebots.

The blank_BOT gives an example that includes lots of comments.

ae_RhodesBOT is an example of a working musebot, showing how I do the following:

  • receive specific messages,
  • load samples into a rudimentary sample player,
  • react to both incoming pitch information (via notepool) and rhythmic information (via tala).

All  of my musebots are available as source code in MaxMSP in the Musebot test suit, found here. My musebots all begin with ae_ (for example, ae_BeatBOT.zip). Source code is in the src folder.

In all cases, the bulk of the heavy-lifting (the OSC communication) is handled by the musebot_config.maxpat bpatcher. You don’t need to edit this in any way, as it reads the config.txt file in the folder to communicate with the Conductor.

A few important points to remember while developing in Max:

  • The name of your musebot application/config.txt file must match the name of its parent folder in the Musebots folder.
  • You can make a separate src folder to hold your source code, but the config.txt file must be in the parent folder. Make an alias of this file and drag the alias into your src folder in order for the Conductor to control your musebot.
  • You can easily run the conductor and any musebots while you are developing your musebot in Max. However, this will only work with one musebot in Max at a time, due to the way the existing Max patchers and the musebot_config.maxpat patcher are using replaceable arguments in their sends and receives.
  • You do not need to include any files while building the application in Max.

Bug alerts (known issues that break the system)

  • Every folder in the Musebots directory must have a config.txt file, which contains the name of the application in that same folder.
  • To use Ollie Bown’s bots, you will need the latest version of Java Runtime Environment (JRE), and the JDK to develop.

Any problems with getting started (using MaxMSP) should be sent to Arne Eigenfeldt; any problems with Java musebots should be sent to Ollie Bown.