[Function]
(events objects destination [ahead] {keyword value}*)

Writes events from objects to destination. Objects can be a single object (i.e. an event, seq or process) or a list of objects. Destination can be a file, port, seq or plotter window. If ahead is supplied it sets the start time offset for objects added to destination. If ahead is a number it is applied to all objects. Otherwise, if ahead is a list of numbers, then each number in the list is matched in left to right order with its corresponding object in objects. Following ahead may come any number of initializations suitable for destination or to its post-processing hooks. events returns destination as its value.

Examples:

Example 1. The events function. 

(events (new midi :time 0) "test.midi")
⇒ "test.mid"

(define (test len knum rhy dur)
  ;; generate some random midi events
  (process repeat len
           output (new midi :time (now) 
                      :keynum (between knum (+ knum 12))
                      :duration dur)
           wait rhy))

(events (test 10 60 .1 .5) "test.mid")
⇒ "test.mid"

Example 2. Start time offsets. 

;;; generate into a new seq at time 30.
(events (test 5 60 .2 .5)
        (new seq :name 'catch) 
        30)
⇒ #<seq "catch">
(list-objects #&catch)
   0. #i(midi time 30.0 keynum 69 duration 0.5 amplitude 64 channel 0)
   1. #i(midi time 30.5 keynum 68 duration 0.5 amplitude 64 channel 0)
   2. #i(midi time 31.0 keynum 65 duration 0.5 amplitude 64 channel 0)
   3. #i(midi time 31.5 keynum 62 duration 0.5 amplitude 64 channel 0)
   4. #i(midi time 32.0 keynum 68 duration 0.5 amplitude 64 channel 0)
;;; three processes, each starting one second later.
(events (list (test 30 80 .1 .5)
              (test 20 60 .1 .5)
              (test 10 40 .1 .5))
        "test.mid"
        '(0 1 2) :timesig '(2 4))
⇒ "test.mid"

See also: