All posts by jpb-admin

Reading CSV/TSV files in Kyma (part 2 of 2)

In the previous article (part 1 of 2), we explored how to get a single column CSV [comma-separated-values] file working with Kyma. We used this single stream of numbers to generate MIDI messages that controlled pitch, amplitude, timbre, location, and note duration. This article builds upon that knowledge, adding multi-column CSV/TSV [tab-separated-values] files as parameter arrays inside Kyma.

The following article will tackle four CSV/TSV data topics.
1. Importing TSV files into the Sample Editor (data as waveform)
2. TSV controls MIDI messages (MIDI Script)
3. TSV controls EventValues (MIDI Script)
4. TSV controls spectra (MIDI Script)

Quick terminology. CSV and TSV files structure data similarly, but each use a different delimiter (comma vs. tab) within the file. It is important to note that Kyma works extremely well with TSV files. If you use multi-column CSV files, you’ll need to either convert your file to TSV (I recommend csvkit), or specify Capytalk to ignore comma characters. For purposes of this article, all example files will use TSV format.

Now’s a good time to download [link to Community Library] [but for now, download is on jpbellona] the example files. Of course, feel free to continue reading without the examples.

1. Importing TSV files in the Sample Editor (data as waveform)

Figure 1. Kyma Sample Editor with Generate tab open
Figure 1. Kyma Sample Editor with Generate tab open

The Sample Editor in Kyma 7, (File > New > Sample file), allows you to generate audio from a variety of inputs (zero, connect points, fourier, polynomial, impulse response, and data file). Using the “from data file” selection in the Generate tab (Figure 1), we can import data from a TSV file, translating our TSV data into samples of amplitude data (e.g. an audio waveform).

Figure 2. Generate Tab of Kyma Sample Editor.
Figure 2. Generate Tab of Kyma Sample Editor.

The column number input (Figure 2) selects which column to import, and clicking on “Insert” translates this single column into amplitude data. In the included file, ‘BobJames_1-10000.tsv’ there are two columns, each column contains 5000 points of data. To understand how TSV data is translated into amplitude information (-1 to +1), this .tsv file contains amplitude data from an audio file–the first column contain the first 5000 samples, and the second column contain another 5000 samples of audio. Click “Insert” on column 1 and watch as how the audio waveform is recreated in front of our eyes.

Figure 3. 5000 points of amplitude data imported in one click.
Figure 3. 5000 points of amplitude data imported in one click.

Listening back, we hear a kick drum.

Regardless of information from the TSV file, data is normalized between -1 and +1 in the Sample Editor. Because one data point is translated into one sample of audio, treating these files as short wavetables may be best (4096 samples anyone?)

009 sample after 2nd import
Figure 4. Importing column 2 of data file with 5000 points of amplitude data.

Column 2 contains another 5000 values. Below is Figure 4 playback, with loop on.

Other non-audio data can also be imported. The next two examples use ‘grid_74_73_61_60_59_48_47_46_36_35.tsv’, which represents Palmer Drought Severity Index (PDSI) for grids within California over the last 2000 years. Each line (data point) represents a single year, and each column accounts for a different grid in California. There are 2003 data point arrays. Each array has ten values. As we import different columns of like data, we can see and hear how the PDSI index for different locations in California change, especially listening with loop on. Looped continuously, each file generates a nice, sonic texture. PDSI grids 61 and 36 (TSV columns 3 and 9) are included below.

012 PDSI column 3
Figure 5. Palmer Drought Severity Index (PDSI) data from Grid 61 (near San Diego, CA)
013 PDSI column 9
Figure 6. Palmer Drought Severity Index (PDSI) Grid 36 (near San Francisco, CA)

2. TSV controls MIDI messages
Sections 2-4 describe how TSV data control different sound parameters (MIDI message, EventValues, spectra tracks) within Kyma. All three sections use the MIDI Script. While this article is not dedicated to Scripts per se, variables (?var), EventValues (!Pan), and MIDI messages, all may be controlled by TSV data from within the MIDI Script using CapyTalk. I certainly do not profess to know much about Scripts; however, we can use Scripts to translate our data arrays into sound event controls over time.

Building from the first article, we convert our entire TSV data line into an array (instead of one-column, single value variables). The conversion to data array variables takes two steps. First, we open the file and call textFileStream when we declare our file variable.

f := 'SanFran1990-2015_rows2-5.tsv' asFilename textFileStream.

We cannot use readStream as we want to utilize CapyTalk that will allow us to save an array of parameters in one function call. The function we want to utilize is nextParameters.

lineValArray := f nextParameters.

nextParameters creates an array of elements for the entire line. Since commas are considered elements within nextParameters, be sure to only use TSV files.

Figure 7. First line of TSV file saved as data array.
Figure 7. First line of four-column TSV file saved as data array.
Figure 8.
Figure 8. First line of four-column CSV file saved as data array. Notice how commas are treated as values within the array.

The rest of the code in the Sound uses the data array to construct a MIDI message. Instead of one variable, however, there are multiple data points we may utilize within each MIDI message. To access a data point, use (ArrayName at: Index) syntax. For example,

register := ((lineValArray at: 2) roundTo: 12).

The TSV array, lineValArray, gets the second index value (2nd column of TSV) and rounds to the closest multiple of 12. In the example, we use this value for octave transposition within our MIDI note-on message. Open up the Sound “TSV_file temperature data as MIDI message” to see more examples of how the TSV values were used in the script. Audio of San Francisco Weather Data 1990-2015 is below.

3. TSV controls EventValues

Any Sound passing through a MIDI Script has its parameters available for mapping. This is especially important for mapping TSV data onto control parameters within other Sounds. One way to control parameters is to use EventValues. Inside the Sound “TSV_file controls EventValues” the MIDI Script uses two TSV data values (TSV columns 1 and 2) to control EventValues !Reverb and !Pan separately. EventValues !Reverb and !Pan reference HotValues in the Eugenio Reverb Sound passing through the MIDI Script. Here is how a data value is used to control the EventValue !Pan.

params := f nextParameters.
pan := ((params at: 1) into: #({-2.341@0} {1.758@1}) ) abs.
self controller: !Pan slideTo: pan byTime: (line * 100) ms.

Like before, nextParameters converts the TSV line into an array (params). The next line normalizes the data (TSV column 1) to between 0 and 1. (note: I used the first column of data’s maximum and minimum (-2.341 and 1.758) to achieve this linear mapping). The data is stored into a variable (pan). The last line of code points to the EventValue !Pan and algorithmically sets its value to our variable, pan, within 100 ms. Consecutive data points are interpolated by Kyma. Listening back, we hear how the Reverb and Pan are independently controlled by the data.

In the VCS window, !Reverb and !Pan are absent from view. (Figure 9)

Figure 8. Controlling EventValues with MIDI Script removes them from the VCS.
Figure 9. Controlling EventValues with MIDI Script removes them from the VCS.

This is because the MIDI Script grabbed these EventValues before they got to the VCS…. (C&K:::: Is this true? How would one display the algorithmically controlled data (e.g. EventValue) if one wanted to view values while running the Sound???)

4. TSV controls Spectra

This last example is a bit more complex. A TSV data array controls an array of spectra over time. The mapping seems pretty straight-forward, but during my initial research, I got a little over my head in CapyTalk. (A big thank you to Carla and Kurt for helping out.) In the Sound “TSV_PDSI_CA controls spectra amplitude” navigate to the SpectrumModifier Sound. The AmpScale parameter field contains the CapyTalk

TrackNumber of: {!Fader copies: 20}

The first 20 spectral tracks are copied into an array of EventValues {!Faders}. Every time point, we loop through our params array (10 points of data) and set the value for each !Fader. Our ten TSV values are used twice, once for spectra !Fader 0-9 and a second loop for spectra !Fader 10-19.

1 to: params size do: [ :i |
self controller: (i - 1 of: {!Fader copies: 20}) slideTo: ((params at: i) into: #({-3.617@0} {0@0.1} {2.186@1}) ) abs byTime: (line * 100) ms. "each line is 100 ms"
"reloop and use params for next 10 Faders too"
self controller: (i + 9 of: {!Fader copies: 20}) slideTo: ((params at: i) into: #({-3.617@0} {0@0.1} {2.186@1}) ) abs byTime: (line * 100) ms].

The Script only utilizes the first 20 spectra tracks from the OscillatorBank, even though more spectra are available. The TSV data is the Palmer Drought Severity Index (PDSI) for CA, and we are tying the data to spectral amplitudes of the sound of rain.  Lower rainfall levels equate to quieter sound (lower spectral amplitudes), while the increased sound of rain equates to higher levels of rainfall.

Going a step further, the next Sound “TSV_PDSI_CA controls spectra on/off and amplitude” not only control 40 spectral tracks of amplitude, but also turns these tracks on/off depending on a threshold. As we can see inside the Script, I am reusing ten data points a bit much. However, now that one can control individual spectra with a Script, larger arrays of data points could easily be assimilated within Kyma. (e.g. 128 columns of TSV data for 128 spectral tracks)

As the article outlines, TSV files are just a single click (or a line of code) away from integration with Kyma. Whether data is used to algorithmically control MIDI events, EventValues, or any other type of parameter inside Kyma, one can quickly listen to data in new and interesting ways. Feel free to populate the example files [add link to Community Library] with your own data, or try inserting your data directly into Kyma’s Sample Editor (File > New > Sample File). Please leave a Reply with a link to your own TSV data sound!  #csvkyma


Max/MSP Package: Korg Nano

Ever since Cycling 74 introduced the idea of packages in Max 6.1, I’ve been pretty excited. Previously, there wasn’t a great way to distribute and install tools, objects, externals, media. And if you wanted to use anyone else’s tools, you had to wade through the murky collection of application directories and dump in single files–an unfailing way to ensure that you’d have to re-install these tools after a Max/MSP update.

With packages, Cycling 74 got rid of the mess. Tool creation, installation, and for me, distribution is clear and simple. Even if I’m developing my own set of abstractions for nobody’s computer but my own, packages provide a platform for a confident working-practice with long-term benefits. This post is meant to outline the pros of Max packages by walking through a working example of how one can set up her/his own Max package.

While I have created several Max packages since 2014, the post will outline my latest Max package, Korg Nano.  It’s a basic example, two objects that comprise a software implementation of the Korg nanoKontrol USB controller, certainly enough to get one started.

After downloading the Korg Nano package, unzip the file and place the unzipped folder directly into the ‘packages’ directory.  For Mac users, the folder is Applications > Max 6.1 > packages.  Or, you can read a short article by Cycling 74 on packages for installation.

What It Is
In short, packages provide global access. Autocompletion, media in global search paths, extras in the top Extras dropdown menu, option clicking helpfiles, it’s all there. What the Korg Nano package provides is a software listener for the 151 controls on the Korg nanoKontrol USB controller. The package is meant to be a plug ‘n play solution for this hardware device (and I use it for prototyping all the time).

After installation of Korg Nano in the Max packages directory (make sure you restart Max), navigate to the folder.  You will see four folders inside (docs, help, media, patchers) and a README file. Each folder has a unique purpose, and there are many more one can add (extras, javascript, clippings, templates, etc). If you’re curious, there is an “about packages.txt” file in the packages directory that outlines the finer points of Max packages. For now, we’ll unpack these four folders (docs, help, media, patchers).

Max/MSP Autocomplete feature for Korg Nano package.
Max/MSP Autocomplete feature for Korg Nano package.

The patchers folder is where you throw your abstractions and objects (not externals), including any additional bpatchers that you may have used to create your objects. Of course, if your package depends upon third-party objects, you can place them here (and within any named subfolder). For Korg Nano, there are two main objects, korgnano and korgnano.inputmenu.  korgnano is built from several bpatchers, which one will see listed in a subfolder (“patchers > korg_nanoKontrol”).

The media folder allows one to place images, audio, and video. This folder becomes global (after restarting Max), so you can also use packages as a way to manage media instead of worrying about “filepath” when you move from computer to computer. Since Korg Nano is a software implementation of the USB hardware controller, I used image buttons that simulate the look and feel of the hardware controller. Placing images in the media folder ensures they will be found, regardless of what computer I am using.

The help folder is exactly what one would expect. Help files ending with the extension .maxhelp.  While help files are useful (e.g. option-click an object to access its help file), Max packages allows one to provide some serious help to the help files. This helpful power boost comes by way of the docs folder.

Korg Nano help file that looks like a standard Max help file.
Korg Nano help file that looks like a standard Max help file.

The docs folder contains reference files that enable hover tooltips, documentation window text, uniform descriptions, and fancy descriptive break downs and object links from within the reference window. To understand what is happening in the help file screenshot above, let’s dig into the docs folder.  Navigate to the “korgnano-0.0.1 > docs > refpages > korgnano > korgnano.inputmenu.maxref.xml” file.  This xml file contains all the descriptions that get pulled for the help file. While this file contains confusing html/xml style tags, one need only look to two examples to see their power.

The first example comes from the first two xml tags <digest> and <description>.  These two description tags show up in the Autocomplete menu, the documentation window, the reference window (outside any help file), and the help file’s title object (actually, a jsui object that uses an application Max script “helpdetails.js” to parse these xml tags and display them for clean documentation).

The second example of documentation power comes from the <seealsolist> tag near the bottom of the .xml file.  One only needs to place additional object names here (e.g. “<seealso name=’korgnano’/>”) and links automatically appear in the reference documentation window, linking to your objects’ help files. This is handy here, as I want to link the korgnano object and the korgnano.inputmenu object together since these objects are symbiotic. The korgnano object grabs data from your Korg hardware controller and then sends the controller data direct to korgnano.inputmenu objects.

Docs, Help, Media, Patchers. That’s it.  A Max package that enables software listening for the Korg nanoKontrol, neatly bundled for distribution. Clear documentation files to help anyone navigate the tools, even me! when I revisit my tool a few months down the line. However, I do not need to distribute to reap the benefits.  Clippings, templates, patchers, or even externals that I use often in my own work have a place within a Max package, easily searchable and documented so I have a working practice that is efficient and scalable. For anyone working in Max, packages offer a clean way to keep your sh** together.

Korgnano object help file
Korgnano object help file


Korg Nano Max package

Packages also work with Max 7. While my example was built using Max 6.1, there is no reason why it shouldn’t work in Max 7. Email me if you have issues.

Speaking of issues… if you’re having trouble with autocomplete, try creating a message object in a Max window with the text “; max db.reset”.  This will refresh Max’s preferences, but may take 60 seconds+ to reload. Here’s the original forum post where I found this fix.

Photoresistor Theremin in a cigar box.

Photoresistor Theremin

Tired of software, longing for the touch and feel of circuits, I’ve been looking for something to satiate my sonic hunger. And, I wanted to get my hands dirty. So, I placed a small order of electronic parts with Additionally, ever since having discovered that the cigar store in Staunton, VA sells nice wooden cigar boxes between $3 and $5 (size and quality), I’ve been itching to put a nice piece of analog circuitry inside.

Thanks to Nic Collins (Handmade Electronic Music: The Art of Hardware Hacking p.161), I found a nice schematic on controlling pitch and volume with photo-resistors. (note: instead of throwing up the schematic as an image, I have posted a pic of my breadboard circuit based upon his schematic below. Regardless, I urge you to support Nic by buying his book. It’s really good).

After wiring the circuit up on a bread-board, I noticed how quiet the theremin sounded. To boost the signal, I needed an audio amplifier, so I turned to the good, old Radioshack project book, Timer Op Amp and Optoelectronic Circuits and Projects Vol. 1 (p.43). Forrest Mims is completely straight-forward on schematic, use, and example.

Forrest Mims diagram for the 386 audio amplifier
Forrest Mims diagram for the 386 audio amplifier (another must-have book for audio applications).

Taking the output of the photo-resistor theremin into the 386 seriously boosted the audio signal, even though I did not have any 220uF capacitors (as shown above). Later, I learned from talking with University of Virginia’s Tech Director, Travis Thatcher, that the capacitor on the output signal is to remove any DC offset that could damage the speaker. A 10uF cap would work fine, or the 220uF as shown. While no capacitor worked for me on this project, I did add a 220uF cap to my parts list for next time.

Breadboard of the Photoresistor Theremin circuit + 386 audio amplifier
Breadboard of the Photoresistor Theremin circuit + 386 audio amplifier

Above is the circuit. The top, 14 position IC circuit is a Hex Schmitt trigger, which is used as the oscillator. The 10k photo-resistor on positions 1 and 2 control pitch, while the other resistor controls volume (one could use a potentiometer instead of a photo-resistor for either control). The audio outs feed into the smaller, 8 position, 386 amplifier. Everything is driven on a 9V battery.

What is not shown in the breadboard schematic above are three simple, but useful additions. I added an on/off switch for power, a LED indicator light, and a mono audio jack output for sending the signal to an amplifier (e.g. guitar amp). Since this was my first project using a power switch, I scoured the internet on wiring and definitions. I learned a lot from this SparkFun article on switches.

Transferring bread board to soldered circuit board.
Transferring bread board to soldered circuit board.

While the breadboard took less than ten minutes, the soldering transfer took a few hours… yes, I am slow. “Measure twice, cut once”, thank you Grandpa Overholt. Methodical work can have its benefits, however (no re-soldering on this job!). After completing the circuit board, I set the board on stand-offs in the cigar box.

Partially complete cigar box instrument.
Partially complete cigar box instrument.

With the parts that I ordered, I found I had little clearance on my connectors. I had to remove the front piece of wood in the cigar box so my washers would tighten up on all the connectors (switch, LED, and audio jack). While soldering, I also found my heat sink to be a great tool, especially while working on the LED and photoresistors (I was concerned about damage due to heat transfer from both the soldering iron and the heat shrink gun).

Completed photoresistor theremin.
Completed photoresistor theremin.

I drilled small 1/16″ holes to stick the photo-resistors through, bent the leads, and used electrical tape on the back to help support. I also drilled holes above the speaker, although this box design utilizes the speaker as a monitor and not as the main audio output. I used a small piece of velcro to affix the mylar speaker to the cigar box.

In the end, I was pretty happy with the product and the sound. If I had to redo, which is certainly possible for me to make another, I would include a volume knob (10k variable resistor), as the audio amplifier is almost too good! My guitar amplifier is set at near 0 currently (0.0001?), and I can turn up the amp (to 1.1, not necessarily 11, but sounds like it), if I run my signal through a compressor (e.g. MXR M102 Dyna Comp).

I would additionally add a resistor on the LED, so it won’t burn out. My LED burnt out after two days, and I found a good article on Adafruit explaining why. All I needed was to add a simple 250ohm resistor on the negative lead. Both of these items (10k pot and 250ohm resistor) are included on my parts list, for anyone wanting to cook one up.

Article Reference:

Photoresistor Theremin Parts (on

Figure 1. Spectral Analysis File (original)

Spectral Smoothing inside Kyma

Lately I’ve been having fun with the spectral analysis tool inside Kyma. This post is to document a quick introduction to Kyma’s Analysis Tool. Specifically, I will document how basic smoothing of frequency and amplitude augments the sonic character of a slow playback via an analysis file.

After performing an initial analysis using Kyma’s Analysis Tool (Cmd-1), and in my case, I’m doing a 256 band analysis, I look to smooth out frequencies and amplitudes separately.

Figure 1. Spectral Analysis File (original)

The Analysis Toolbar provides many options, but the main tool we are concerned with is the Filter function.

Figure 2. Kyma Analysis Toolbar with Filter Function highlighted
Figure 2. Kyma Analysis Toolbar with Filter Function highlighted

There are several filtering options within the Filter function.

Figure 3. Functions of Kyma Analysis Filter tool
Figure 3. Functions of Kyma Analysis Filter tool

The main filter function we are concerned with is smoothFrequency and smoothAmplitude. Notice, how with two separate filters, we will have to apply one filter at a time.

The process for this exercise is simple. Apply 10 frames smoothing to Frequency, then 100 frames. Afterward, apply 10 frames smoothing to Amplitude, then 100 frames. Of course, one may try different combinations. The goal is to smooth frequencies and amplitudes in anticipation of playing the file back at a very slow playback rate.

Figure 4. Analysis with smoothed frequency over 10 frames
Figure 4. Analysis with smoothed frequency over 10 frames

Ten frames for smoothing is not a lot of change; one can hear subtle flutters on the low and low-mid frequencies.

Figure 5. Analysis with frequencies smoothed 10+100 frames
Figure 5. Analysis with frequencies smoothed 10+100 frames

110 frames smoothing of frequency begins to sound like vari-speed delay in the system, like a clean version of wow and flutter from a tape deck. If you look closely at the lower frequencies, you can see larger sinusoids developing as a result of the smoothing, which results in some audible vari-speed sound. But we are not finished yet. Onto the smoothing of amplitudes.

Figure 6. Analysis with smoothed frequencies over 110 frames, and smoothed amplitudes over 10 frames.

Amplitudes help the sonic character a lot. I cannot explain it. The sound is good. If I had to ultimately choose between smoothing frequencies or smoothing out amplitudes, I would choose amplitudes, hands down.

Figure 7. Analysis with smoothed frequencies over 110 frames, and smoothed amplitudes over 10+100 frames.

Now, after these five steps, we’re ready to pitch our audio and slowdown playback. The next two audio examples demonstrate pitch shift down one octave, and the second example demos both the pitch shift with slowing playback by 10x.

I understand that in this blog post, I’ve failed to demonstrate why smoothing augments the sonic character. In order to juxtapose this last audio file played above, which is in part the end product of the smoothing process, I’ve made one last recording. Below is an audio file of an analysis, without smoothing, played back down an octave at 10x the length. Everything is the same to the audio above, except for no smoothing.

Because the audio is slowed down but the analysis has no smoothing, you’ll hear that frequencies and amplitudes develop at a faster rate and causes, to my ear, digitization noise. By smoothing out frequencies and amplitudes in advance of the slowed playback, we create frequencies and amplitudes that develop at the speed of our playback, thus decreasing the potential to hear unnatural spectral bands, or what I would call digitization noise.

Ref: Source material comes from my piece #Carbonfeed, a work that is driven by tweets in real time.

wireless keypad

Qwerty keyboard as Kyma Tool controller

Tools help us carry out particular tasks and functions. Hammers drive in nails. Saws cut wood. In the digital realm, we also use tools. Faders control volume, buttons trigger sounds. However, in software, things are not always so clear cut. Faders don’t have to control volume, and buttons don’t have to trigger sounds. The examples of faders and buttons acknowledge the two types of fundamental control: continuous (faders) and discrete (button). Our digital tools are built upon these two paradigms of continuous and discrete control.

In Kyma, the Virtual Control Surface (VCS) lets us control sounds in real time. The VCS is  a tool that displays virtual faders and buttons (controlled by using a computer mouse or app). Since I don’t own an iPad, I am unable to take advantage of the VCS Kyma Control iPad app. I desired a non-mouse control inside Kyma that would let me get away from mousing and clicking. Thus, I wanted to take advantage of the controller most available to me and other users. The discrete control of the Qwerty keyboard.

Figure 1. Virtual Control Surface (VCS) inside Kyma.
Figure 1. Virtual Control Surface (VCS) inside Kyma.

This blog post covers my foray into Kyma Tools (a largely untapped resource of Kyma) and the result: an open source qwerty keyboard controller built in and for Kyma. One is process and the other is product.

Why Kyma Tool?
But let’s start off with the why. I could have easily created a Max patch that accepts ‘key’ control and then port off my ASCII values as Open Sound Control (OSC) messages to Kyma. Actually, I did. See Figure 1.

Figure 2. Qwerty control in Max/MSP sent as OSC message.
Figure 2. Qwerty control in Max/MSP sent as OSC message.

Yet, this is not as simple as it sounds. Not only do I have to open Max/MSP in order to run this patch, but I have to get the IP address of the Paca(rana), copy the IP address here… each and every time I start the Paca(rana). Not very fast for performance setup.

I wanted to see if I could embed this type of discrete, keyboard control inside of Kyma itself, cutting out third party software and reducing setup time. Hence, my foray into the Kyma Tool (aka. state machine that can read and write EventValues)

Kyma Tool Process
The Kyma Tool is where one can write a patch to carry out multi-step processes (Spectral Analysis Tool), process batch files or a folder of files, create a controller (my keypad tool), or create a virtual interactive environment (think CataRT if you wrote this in Kyma). The Kyma Tool does use SmallTalk and offers a bit different coding experience, but the Tool environment is a pretty powerful editor. I knew that if I wanted to get access to the qwerty keyboard and create a controller, I would need to dive into the Kyma Tool. (For further reference to the Kyma Tool, please see the Kyma X Manual, pp. 309-333).

Figure 3. Keypad.pci backend tool layout
Figure 3. Keypad.pci backend tool layout

Like javascript or php, there are global and local variables, and like Flash, there are event based actions, or rather “triggers” and “responses”. A huge thank you to Carla Scaletti for tipping me to the global variable LastCharacterTyped, where the initial value, $a, stores the last character value of the qwerty keyboard based upon user input. For example, typing ‘f’ becomes $f, or typing a ’1′ becomes $1. LastCharacterTyped gets you access to the user typing on the keyboard, but only the character value of the user’s action.

The first step of my Keypad Tool is to convert each character into ASCII. Since each value is a character, I convert the character into an ASCII integer using the Capytalk “asInteger”.

keyboard := LastCharacterTyped asInteger.

The Capytalk above stores the ASCII integer into the local variable keyboard. The local variable ‘keyboard’ writes/outputs its value to the HotValue !KeyBoard. Writing the control to a HotValue provides access. !KeyBoard, the ASCII integer of a user’s keyboard, is now accessible, in real time, by any Kyma Sound that references the variable !KeyBoard. So long as one uses the Keypad Tool, !KeyBoard can be used by any Kyma Sound at any time, anywhere, just like the Max patch above.

Figure 4. keyboard variable as !KeyBoard HotValue.
Figure 4. keyboard variable as !KeyBoard HotValue.

The next function I desired, beyond accessing the Qwerty keyboard values as a Kyma HotValue, was to specifically address the number pad 0-9 (in ASCII, 0-9 equal 48-57). For these ten keys, I wanted 0-9 keypad values to store as their actual numbers inside a different HotValue. Below is the Kyma Tool code.

(keyboard between: 48 and: 57)
ifTrue: [keypadNumber := keyboard-48]
ifFalse: [keypadNumber := -1].

Here’s the English version. If the ‘keyboard’ variable (this is our ASCII value) is between 48 and 57 (inclusive so would react to 0-9 on the keyboard), then store your value into variable ‘keypadNumber’. If not, store a -1. In Kyma, we usually write Capytalk true: () false: ().  In Kyma Tool land, I had to learn that we need ifTrue: [] ifFalse: []. Subtle syntax, but one that I lost an hour over. You’ll see in the example files how we’ll utilize the Capytalk true: () false: () in a SoundToGlobalController.

The ‘keypadNumber’ variable also outputs its value to a HotValue, !KeyPad. !KeyPad outputs 0-9 when qwerty keys 0-9 are pressed. Otherwise, any other key value outputs -1.

Kyma Tool in Action
Ok. So how does one use this Kyma Tool?  Similar to the Tools > Fake Keyboard or Tools > Spectral Analysis tool inside Kyma, all one needs to do is open the Tool (‘keypad.pci’) inside Kyma (File > Open) and start typing on the keyboard to output values. No external software or OSC setup necessary. Of course, however, you’ll need to download the tool.

Figure 5. Two states of keypad Tool. Shows lastCharacter, ASCII value (!KeyBoard), and !KeyPad hot value.
Figure 5. Two states of keypad Tool. Shows lastCharacter, ASCII value (!KeyBoard), and !KeyPad hot value.

The only note about Kyma Tools is that their window needs to be highlighted (in front) in order to work properly. This is not a new software concept, but one that users of Kyma Tools should be aware of.

Download the keypad.pci Kyma Tool and example files to help you get started.


max msp audio selection

Sample Selection in XY Space

Selecting a portion of an audio sample is something that we do often. Digital Audio Workstations (DAWs) like Logic and ProTools or even Sample Track Editors like Peak and Audacity allow users to select a portion of audio.

Figure 1. Selection of Audio in Audacity.
Figure 1. Selection of Audio in Audacity.

The process of selecting audio with a mouse for out-of-real-time control (and in the comfort of one’s studio) isn’t a bad paradigm. However, what about live performance contexts? What other paradigms exist, may be altered, or can be created to benefit live performance?

In conversations with Ted Coffey one such idea came up. With the Wacom tablet, one may alter the start and end selection times of an audio sample based upon the pen’s position in XY space. This idea, sample selection times in XY space, is entirely Ted’s and I can take no credit. Still, I was and am excited about his control idea and I really wanted to listen to a sound using the XY control paradigm. This blog post documents my implementation of sample selection times in XY space based upon Ted’s description.

The What

In order to control sample selection times we need to control three things:
a. sample selection start
b. sample selection end
c. start/stop sample

Figure 2. Sketch of sample selection control on the XY axis
Figure 2. Sketch of sample selection control on the XY axis

Using the Wacom tablet, we map XY space onto  the sample selection start and end times (Y-axis is selection start, X-axis is selection end) and use !PenDown to trigger the sample start/release.

So, what does this sound like? Here are two examples.
The first example uses to pen to scrub different locations of the tablet. Source material is the opening theme to Beverly Hills Cop.

The second example uses grid quantization for the Pen location. Dividing the sample start location and end location times by a beat factor (e.g. 32), we can quantize the length of the selection by a fraction of a beat. Match the playback of this fraction to the !BPM of a drumbeat, and voila! Instant gratification. Source material: Beverly Hills Cop theme + Bob James “Take Me To The Mardi Gras”

To sum up, using XY space to dynamically alter start/end selection times of a sample has strong performance possibilities. For those interested, I’ve shot a quick video of the controls inside Kyma and placed my source Kyma 7 files here.

Quick Kyma notes to no-one but myself:
a. use SampleWithTimeIndex.
b. for Beat quantization,

  • Duration must be ‘audioFileNameOfDrum’ sampleFileDuration s.
  • Rate must be !Rate * (!BPM / (‘audioFileNameOfDrum’ closestBPMTo: !BPM forBeats: 64))
  • Start, End, etc. must use this syntax… ((!PenY * 64.0) rounded / 64.0)

c. for On-the-beat triggers, use Capytalk

((1 bpm: !BPM) hasChangedReset: 0) trackAndHold: !PenDown

This means that the value starts at 0, PenDown will trigger 1 when next beat occurs.


Wacom tablet: data zooming function

Over the last few months, I’ve been interested in data zooming, where a finite range of data (say 0-1) can be magnified and explored in greater detail. We are all familiar with the paradigm. In Microsoft Word or Photoshop, for example, you zoom the view (e.g. 125%) and in the same amount of screen real estate, you see a smaller region (of words or pixels) in greater detail.

dream-caused-by-the-flight-of-a-bee copy
Figure 1. Zoom in of a portion of Salvador Dali’s Dream Caused by the Flight of a Bee Around a Pomegranate a Second Before Awakening painting reveals more detail in same amount of screen real estate.

Zooming is also true for any stream of numbers. In software we can map a fader to move between 0-1 and on a similar fader (or the same fader), map the range to 0.0-0.1 (1/10 of its original range).

Max/MSP fader ranges
Figure 2. Max/MSP fader mapped to different scaling factors.

While a simple concept, data zooming can be a powerful tool. Magnification embodies focus, detail, and exploration. If sound is data or controlled by data, then magnification enables us to literally ‘zoom in’ on audio. Data zooming, then, becomes a way to explore sound space.

Inspired by Palle Dahlstedt [1], I set out to rapid prototype a way to zoom in on a data stream for live performance. I chose the Wacom tablet since I use this often in live performance with Kyma. I was most fascinated with !PenX (0-1 range), which I often map to the TimeIndex of a sound (0@start of sound, 1@end of sound). Regardless of audio sample length, PenX can be set so 0 will always be the beginning of the sample and 1 will always be the end of the sample. (note: TimeIndex range expects -1 to 1, but PenX range can be easily shifted to fit)

Figure 3. Wacom tablet.

The basic gist of data zooming is that we need two controllers to do the job: a continuous fader (e.g. !PenX) and a button to trigger the zoom (e.g. !PenButton2). The pen/fader equates to the values that we read and in our case, the values that we map onto the TimeIndex of an audio sample.

Data zoom works like this: whenever the zoom button is depressed, we take the current location of the fader and “zoom” in to the location. With zoom enacted, the fader moves at a smaller scale around this location point. The magnitude of zoom can be altered, but for the purposes of this example, I worked with a 10x zoom magnitude. Before jumping into Capytalk and Kyma, let’s walk through my initial prototype inside Max/MSP. The math is the same.

The range of initial values (!PenX) are between 0-1. When the zoom button is depressed, we need to save the current location of !PenX and use as our new zoom location (offset). In addition, we need to alter the range in which !PenX moves through data (scale). I’ve uploaded the Max prototype patch and Kyma file here.

max zoom prototype
Figure 4. Max/MSP patch prototyping data zooming function.

In order to take into account the centering of the Pen at the current zoom level, I had to add an additional offset that shifts the offset to the actual point of the pen on the tablet. The Max prototype includes multiple zoom levels at powers of 10.

With Kyma, I used the same basic concept. When a button is pressed (!PenButton2), we zoom to the current value of X (sampleAndHold) and magnify the boundaries of !PenX from 0-1 to the zoom order (exponent of 10). Because 10^0 = 1, we can use a button’s press (binary 0 and 1) to create a simple on/off zoom in Kyma.

kyma data zoom
Figure 5. Simple zoom for data values using the !PenX and !PenButton2.

Here’s the Capytalk that achieves data zooming:

(!PenX / (10 ** !PenButton2)) + ((((!PenButton2) sampleAndHold: !PenX) – (((!PenButton2) sampleAndHold: !PenX) / (10 ** !PenButton2))) * !PenButton2)

First, !PenX is scaled down when !PenButton2 is depressed (power of 10). We then add back (offset) PenX’s location from when PenButton2 was pressed. In order to take account of the actual pen location on the tablet, we have to subtract PenX’s sampled location at the same order of the zoom. Lastly, we multiply this offset by !PenButton2 so that when the button becomes 0 (zoom off), the zoom offset no longer effects PenX’s initial, non-zoom state. Thus, with PenButton2 off, the Capytalk is just (!PenX / 1) + 0. Below is a short video sounding the process.

Download the Kyma and Max files.

[1] Palle Dahlstedt. “Dynamic Mapping Strategies for Expressive Synthesis Performance and Improvisation.” in Computer Music Modeling and Retrieval. Genesis of Meaning in Sound and Music. 5th International Symposium, CMMR 2008 Copenhagen, Denmark, May 19-23, 2008.