I have accumulated so much musical-code ideas so I’ve finally resolved to clean it up, reorganise it and publish it somewhere. Github seemed the best option, these days:

Turns out that just the code by itself won’t do it. Especially considering that the environments I use to ‘run it’ (and to make sounds) can rapidly disappear (become obsolete, or get out of fashion!).

Hence there’s a YouTube channel as well, where one can find a screencast recording of each of the ‘musical codes’.

Hope someone will find something of interest in there. Comments and feedback totally welcome!

Impromptu is a scheme-based OSX programming language and environment for composers, sound artists, VJ’s and graphic artists with an interest in live or interactive programming.

As part of its original website, Impromptu included a wiki containing documentation and examples. Unfortunately the wiki isn’t available online anymore, which is a real shame so the other day I’ve decided to replace it with a simple searchable index of the programming language functions. This is based on the documentation file coming with the latest Impromptu release (2.5); so, in theory, it shouldn’t be too different from the original wiki site.

For those of you who are new to all of this, it’s worth mentioning that Impromptu is now being superseded by the Extempore programming language.

Extempore is much more solid and feature rich; also, it is less dependent on the OS X platform APIs. Still, many of the original Impromptu scheme functions are still available, so this documentation could turn out to be useful too.

Enjoy!

The script assumes that your audio graph includes a mixer object called *mixer*. The UI controllers are tied to that mixer’s input buses gain value.

The objc bridge commands are based on the silly-synth example that comes with the default impromptu package.

Being able to control volumes manually rather than programmatically made a great difference for me. Both in live coding situations and while experimenting on my own, it totally speeds up the music creation process and the ability of working with multiple melodic lines.

The next step would be to add a midi bridge that lets you control the UI using an external device, in such a way that the two controllers are kept in sync too. Enjoy!

P.s.: this is included in the https://github.com/lambdamusic/ImpromptuLibs

The make-metroclick function returns a closure that can be called with a specific time in beats, so that it plays a sound for each beat and marks the downbeat using a different sound.

Possibly useful in order to keep track of the downbeats while you compose, or just to experiment a little with some rhythmic figures before composing a more complex drum kit section.

Here’s a short example of how to use it:

Make-metronome relies on the standard libraries that come with Impromptu, in particular make-metro, which is described in this tutoriale and on this video. Essentially, it requires you to define a metro object first, e.g. (define *metro* (make-metro 120)).

Here’s the source code:

The interpreter will now throw to an error hook providing you with greater control over exception handling. You initiate the livecoding error hook by calling (sys:livecoding-error-hook #t). Errors are then passed to the *livecoding-error-hook* function – which you may rebind. By default the function simply returns 1 but can be modified for more specialised behaviour.

This is extremely useful, to say the least, if you are performing live and want to avoid situations in which a (stupid) typo or parenthesis error will mess up your entire gig. The error hook in many cases will prevent your looping function from crashing, giving you time to fix the error. Really neat.

Here’s an example from the official release notes:

;; turn on livecoding error hook
(sys:livecoding-error-hook #t)

;; with livecoding-error-hook on   
;; this temporal recursion will continue
;; to play the second note even though 'pitch
;; is an unbound symbol
(define loop
   (lambda (beat) 
      ;; symbol a is not bound but loop continues to function
      (play piano pitch 80 1)
      (play piano 63 80 1)
      (callback (*metro* (+ beat (* 1/2 1))) 'loop (+ beat 1))))

(loop (*metro* 'get-beat 4))

;; by redefining the error hook we can provide
;; additional specialisation - such as replacing
;; any unbound symbol with 60!
;; 
;; eval below and both notes will play
;; 'pitch being replaced by 60
(define *livecoding-error-hook* 
   (lambda (msg a) 
      (cond ((symbol? a) 60)
            (else 0))))

Happy (and safer) livecoding!

Let me clarify this with an example. Let’s set up the standard Apple’s DLS-synth audiounit and the metronome:

(au:clear-graph)
(define dls     (au:make-node "aumu" "dls " "appl"))
(au:connect-node dls 0 *au:output-node* 0)
(au:update-graph)
(au:print-graph)
(define *metro* (make-metro 100))

Now imagine that we want to play some (dumb) melody with Apple’s DLS. We can use the usual play macro to achieve this quite easily (that’s because above we set up the metronome, which is needed in order to use play – check out the docs if this sounds odd to you).

Sequencing a bunch of notes is thus just a matter of sequencing play macros:

(define the-usual-play
   (lambda (beat) 
      (play dls 60 90 1)
      (play dls 64 90 1)
      (play 1/2 dls 72 90 1)
      (play 3/2 dls 67 90 1)
      (callback (*metro* (+ beat (* 1/2 2))) 'the-usual-play (+ beat 2))))

(the-usual-play (*metro* 'get-beat 4))

That’s where I started getting nervous (so to say). Having to write ‘dls’ each time I play a new note seemed to me redundant and illogical; I know that it’s dls the instrument I want to play – I heard my mind screaming – why can’t I focus on the music instead of making sure I type in the instrument name all the time?

Taking advantage of Scheme, the self-modifying language

Luckily though we’re using Scheme, which differently from most other computer languages allows you to change the language grammar as you like, thanks to macros. So here we go, we can create a new macro similar to play that lets you omit the instrument you’re playing. We’ll call it iplay (shortcut for instrument-play, not itunes :-)):

(macro (iplay args)  
   (cond ((equal? (length (cdr args)) 3)
          `(let ((note ,(cadr args))
                 (vol ,(caddr args))
                 (dur ,(cadddr args))
                 )
              (play my-inst note vol dur)))
         ((equal? (length (cdr args)) 4)
          `(let ((offset ,(cadr args))
                 (note ,(caddr args))
                 (vol ,(cadddr args))
                 (dur ,(cadddr (cdr args))))               
           (play (eval offset) my-inst note vol dur)))
         (#t (print "Error: the function only accepts 3 or 4 argument"))))

Essentially what we’re telling the interpreter here is that every time iplay is used, the original play should be called and the symbol my-inst should be passed as the variable representing our instrument. Now we can modify the simple loop defined above like this:

(define the-usual-play-modified
   (lambda (beat) 
      (let ((my-inst dls))
         (iplay 60 90 1)
         (iplay 64 90 1))
      (play 1/2 dls 72 90 1)
      (play 3/2 dls 67 90 1)
      (callback (*metro* (+ beat (* 1/2 2))) 'the-usual-play-modified (+ beat 2))))

(the-usual-play-modified (*metro* 'get-beat 4))

If you run that, you’ll see that this loop sounds exactly the same as the previous one, although the first two play calls are now iplay macro calls. The whole thing works because we introduced a local variable my-inst and bound that to the dls audio instrument (created at the beginning). Notice that the new macro iplay knows nothing about what instrument is playing: it’s just using blindly the my-inst variable, under the assumption that we’ve associated it to a valid audio instrument.

Some more syntactic sugar

The only hassle now is that each time we want to use iplay we are forced to use the (let ((my-inst dls)).. form. Typing this stuff doesn’t feel very natural too. Rather, in my head, I tend to see things like this: get an instrument first, then play a bunch of notes with it.

So, let’s create some syntactic sugar for the ‘let‘ form, by defining another macro, ‘with-instrument‘:

(macro (with-instrument args)
   `(let ((my-inst ,(cadr args)))
       ,@(cddr args)))

As you can see, this macro doesn’t do much: it just rephrases the let form above in a way that is probably more natural to me (and to others too I believe..).

For example, now we can use iplay like this:

(define justatest
   (lambda (beat)      
      (with-instrument dls 
          (iplay 48 40 1)  ;; iplay with 3 args: pitch, vol and dur
          (iplay (random (list 1/2 1/4 1/8)) (random 60 80) 40 1))  ;; 4 arguments: offset
      (callback (*metro* (+ beat (* 1/2 1))) 'justatest (+ beat 1))))

(justatest (*metro* 'get-beat 4))

Finally, let’s remember that because of the way we defined iplay above, we can pass it 3 or 4 arguments: in the first case, the macro assumes that we’re providing a pitch, a volume, and a duration. In the second case instead the first argument is assumed to be an offset value (while the others remain unchanged).

The original play macro can take another argument too: the channel (or midi port). I haven’t included here cause I normally don’t need it, but if you do I’m sure you can fiddle a bit with the code above and make it do whatever you want!

Conclusion: here is the code you need to evaluate within Impromptu if you want to use the with/iplay constructs (all the source code is also available on BitBucket):

(macro (with-instrument args)
   `(let ((my-inst ,(cadr args)))
       ,@(cddr args)))


(macro (iplay args)
   (cond ((equal? (length (cdr args)) 3)
          `(let ((note ,(cadr args))
                 (vol ,(caddr args))
                 (dur ,(cadddr args))
                 )
              ;(print inst beat note vol dur)
              (play my-inst note vol dur)))
         ((equal? (length (cdr args)) 4)
          `(let ((offset ,(cadr args))
                 (note ,(caddr args))
                 (vol ,(cadddr args))
                 (dur ,(cadddr (cdr args))))
           ;(print inst beat note vol dur)
           (play (eval offset) my-inst note vol dur)))
         (#t (print "Error: the function only accepts 3 or 4 argument"))))

Finally.. a ‘pastebin’ function

Also, here is a pastebin function similar to pb:cb (check out this video tutorial if you don’t know what I’m talking about) that returns a template with the with-instrument macro:

(define pb:iplay (lambda (name dur inst) '()))  ;; fake function definition, useful for autocompletion!

;; macro wrapper for pb-iplay
(define-macro (pb:iplay name dur inst . args)
   `(pb-iplay (sexpr->string (quote ,name)) 
              (sexpr->string (quote ,dur))
              (sexpr->string (quote ,inst))
              ,@(map (lambda (expr)
                        (sexpr->string expr))
                     args)))


(define pb-iplay
   (lambda (name dur inst . args)
      (let ((a (apply string-append (map (lambda (e) (string-append "n      " e)) args))))
         (sys:set-pasteboard
         (string-append 
"(define " name "
   (lambda (beat) 
      (with-instrument " inst "
          " a "
     (callback (*metro* (+ beat (* 1/2 " dur "))) '" name " (+ beat " dur ")))))nn(" name " (*metro* 'get-beat 4))")))))



;;;;;;;;;;;;;;;;
;; call it like this: 
;(pb:iplay myloop 1/4 dls)
;;

;;;;;;;;;;;;;;;;;
;; returns: 
;;;;;;;;;;;;;;;;

;
;(define myloop
;   (lambda (beat) 
;      (with-instrument dls
;
;     (callback (*metro* (+ beat (* 1/2 1/4))) 'myloop (+ beat 1/4)))))
;
;(myloop (*metro* 'get-beat 4))

Kontakt 4 is an aaward winning sampler from Native Instrument; I was just going through the docs the other day to figure out what it does or doesn’t do and in the section that explain the various ettings parameters I found the description of the ‘latency optimization’ very useful (2.1.2 Latency Optimization [KONTAKT 4 Getting Started – page 11 – get the pdf of the manual here).

The Latency slider controls the size of the playback buffer.

And here is the explanation of that setting:

The load that typical digital audio calculations generate on your processor is often not constant and predictable; parameter changes, additional voices or other processes can all cause mo- mentary peaks in the load, which can result in drop-outs or other audio artifacts if not properly compensated for. That is why audio programs do not send the audio signals they generate directly to the hardware, but write them to a short buffer in memory instead, whose contents are in turn being sent to the actual hardware. This concept allows the program to bridge short irregularities in the stream calculation and thus be more resistant to processing peaks.
Of course, this “safety net” comes at a price–the buffering causes a delay, known as latency, between the triggering of a note and the actual sound. This delay gets longer with increas- ing buffer sizes. Hence, it’s vital to tune the buffer size in order to find a good compromise between latency and playback reliability. The optimal value depends on such diverse factors as your CPU, memory and hard disk access times, your audio hardware and drivers, and your operating system environment.
In order to find the optimal buffer size for your system, we recommend that you begin by setting the Latency slider described in the previous section to a healthy middle value between 384 and 512 samples, then gradually decrease the value during your normal work. When you begin to notice drop-outs, increase the buffer again by a small amount.
Generally, it’s a good idea to have as few other applications as possible running in the back- ground when working with audio software. Also, if you can’t get below a certain buffer size without getting drop-outs, consult the documentation of your audio hardware to find out whether you can access it via an alternate driver architecture, as some architectures allow more efficient low-level access to the hardware than others.

I spent some time trying to figure this out, and the answer is yes! Quite a nice learning experience… although it came with a surprise at the end.

Originally I thought, let’s do it via impromptu’s ObjC bridge. I don’t know much about ObjC but after a bit of googling it seemed evident that the quickest way to accomplish this is by writing ObjC code that, in turns, runs a simple applescript command that opens a window:

So I translated the bottom part of the code above into impromptu/scheme:

That is a generic script-running function, that is, you can pass any script and it’ll run it, eg:

Now, back to the original problem: in order to open a Finder’s window at a specified location we need to pass the location variable to our function run_applescript; also, we want to be able to pass unix path expressions (eg ‘/Users/mike/music/’), so we’ve got to transform that path syntax into the semicolon-delimited macintosh syntax (“Macintosh HD:Users:mike:music”) needed by the applescript function we’re using. That’s easily done with string-replace, so here we go:

That’s pretty much it really… now we can easily open OsX Finder’s windows from within Impromptu.

But as I said above, there’s a surprise: after getting this far I thought I’d search impromptu’s mailing list for more examples of obj:call …. and guess what, there’s already a system function that runs applescripts, it’s called sys:run-applescript !

Too bad, it’s been a rewarding learning experience anyways…

Good news for livecoders: a new version of Impromptu is available (direct link to the 2.5 dmg package).

Apart from various bug fixes, it looks like as if the major development is the ICR (impromptu compiler runtime), a new set of scheme functions that facilitate the creation of faster bytecode, so that computationally-intensive tasks such as real time audio processing or open-gl can perform more efficiently.

The new compiler is a far more robust and serious attempt at providing low level, but completely dynamic programming support within the Impromptu ecosystem. It is designed for situations which require low-level systems style programming. Two primary examples are audio signal processing and opengl programming – both of which require the production of highly efficient code. While attempting to achieve runtime efficiency the ICR also tries to maintain Impromptu’s love of all things dynamic and is designed to coexist with the rest of Impromptu’s infrastructure (Scheme, Objective-C, AudioUnits etc..).

It is important to state from the outset that the new Impromptu compiler is NOT a scheme compiler. It is really its own language. This language looks like scheme (sexpr’s and alike) but is in many ways semantically closer to C (a nice functional version of C :-). This is because the ICR is designed for purposes that are not suitable for the standard scheme interpreted environment. Low level tasks that require efficient processing – such as audio signal processing, graphics programming, or general numerical programming.

Unlike Scheme the Impromptu compiler is statically typed. You may not always see the static typing but it is always there in the background. The reason that you won’t always see the typing is that the compiler includes a type-inferencer that attempts to guess at your types based on static analysis of your code. Sometimes this works great, sometimes it doesn’t. When things fail, as they surely will, you are able to explicitly specify types to the compiler.

A big thanks to Andrew Sorensen for keeping up (and free) this great work!

So you’ve decided to know everything about scheme and rock the world using fast-paced programming environments like Impromptu.
Well, I confess I did think that on several occasions, but still I haven’t made it even half way through the schemer pilgmim’s path. But I’ve collected quite a few useful resources in the process, and those I can certainly share!

So in what follows I’ve put together a list of learning resources about Scheme that I found useful.. First off, two links that might be useful in all situations:

Now, why don’t we start with the definition offered by the self-regulating wikipedia collective intelligence? Here we go:

Scheme is one of the two main dialects of the programming language Lisp. Unlike Common Lisp, the other main dialect, Scheme follows a minimalist design philosophy specifying a small standard core with powerful tools for language extension. Its compactness and elegance have made it popular with educators, language designers, programmers, implementors, and hobbyists, and this diverse appeal is seen as both a strength and, because of the diversity of its constituencies and the wide divergence between implementations, one of its weaknesses

If this blurb hasn’t made you proud of learning such a slick language, you’ll surely find more interesting ideas in what follows. I divided up the list in two sections, generic learning materials about scheme, and tutorials about specific topics (for now, only macros are included).
———————————-

1. Learning Resources About Scheme:

———————-

2. Specific topics:

On Macros and metaprogramming:

———————-

That’s all for now… I’ll be adding more stuff as I run into it!