sc/cm [ Modules ]

[ Top ] [ Modules ]

NAME

 cm

 File:             cm.lsp

 Class Hierarchy:  none (no classes defined)

 Version:          1.0.10

 Project:          slippery chicken (algorithmic composition)

 Purpose:          Definition of common-music related and other functions
                   like transposition of notes/chords, enharmonic
                   equivalents etc.   

 Author:           Michael Edwards: m@michael-edwards.org

 Creation date:    1st March 2001

 $$ Last modified:  16:49:14 Sat Jun 22 2019 CEST

 SVN ID: $Id$

cm/degree-to-note [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Get the specified scale degree number as a note-name pitch symbol within
 the current scale. An optional argument allows the user to specify that the
 scale degree number should be used to get the note-name pitch from a
 different scale. 

ARGUMENTS

 An integer that is a scale degree number.

OPTIONAL ARGUMENTS

 - The scale from which the note-name pitch symbol associated with the
   specified scale degree is to be drawn.

RETURN VALUE

 A note-name pitch symbol.

EXAMPLE

(degree-to-note 127 'chromatic-scale)

=> G9

(degree-to-note 127 'twelfth-tone)

=> ATS0

(degree-to-note 127 'quarter-tone)

=> EQF4

SYNOPSIS

(defun degree-to-note (degree &optional (scale cm::*scale*))

cm/degrees-per-octave [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Return the number of scale degrees in the span of one octave within the
 current tuning system.

ARGUMENTS

 - No arguments.

RETURN VALUE

 - An integer that is the number of scale degrees in each octave.

EXAMPLE

(in-scale :chromatic)
(degrees-per-octave)

=> 12

(in-scale :quarter-tone)
(degrees-per-octave)

=> 24

SYNOPSIS

(defun degrees-per-octave (&optional (scale cm::*scale*))

cm/degrees-per-semitone [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Get the number of scale degrees per equal-tempered semitone in the current
 tuning scale. 

ARGUMENTS

 - No arguments

OPTIONAL ARGUMENTS

 - The scale for which the number of degrees per semitone is to be
   retrieved.

RETURN VALUE

 An integer.

EXAMPLE

(degrees-per-semitone 'chromatic-scale)

=> 1

(degrees-per-semitone 'twelfth-tone)

=> 6

(degrees-per-semitone 'quarter-tone)

=> 2

SYNOPSIS

(defun degrees-per-semitone (&optional (scale cm::*scale*))

cm/degrees-to-notes [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 NB: If the specified scale-degree number within the current scale would
     result in pitch outside of the maximum MIDI pitch range for that tuning
     (chromatic: C-1 to B10; quarter-tone: C-1 to BQS10; twelfth-tone: C-1
     to CTF11), the function will return an error.

ARGUMENTS

 An integer that is a scale degree number in the current tuning.

RETURN VALUE

 A list of note-name pitch symbols.

EXAMPLE

(in-scale :chromatic)
(degrees-to-notes '(0 143 116 127 38))

=> (C-1 B10 AF8 G9 D2)

(in-scale :twelfth-tone)
(degrees-to-notes '(0 144 116 127 38 287 863))

=> (C-1 C1 GSS0 ATS0 FSSS-1 CTF3 CTF11)

(in-scale :quarter-tone)
(degrees-to-notes '(0 144 116 127 38 287))

=> (C-1 C5 BF3 EQF4 G0 BQS10)

SYNOPSIS

(defun degrees-to-notes (degrees)

cm/event-list-to-midi-file [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Write the events in a list to a mid-file.

ARGUMENTS

 - A list of events objects
 - the path to the midi-file
 - the starting tempo (integer: BPM)
 - a time-offset for the events (seconds)

OPTIONAL ARGUMENTS

 - whether to overwrite events' amplitude slots and use a single
 velocity/amplitude value given here (0-1.0 (float) or 0-127 (integer) 

RETURN VALUE

 The MIDI file path

SYNOPSIS

(defun event-list-to-midi-file (event-list 
                                &key (midi-file "/tmp/tmp.mid")
                                  (start-tempo 120) (time-offset 0)
                                  (auto-open (get-sc-config
                                              'midi-play-auto-open))
                                  force-velocity)

cm/freq-to-degree [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Get the scale degree of the specified frequency in Hertz within the current
 scale. 
 
 NB: This method will return fractional scale degrees.

ARGUMENTS

 A frequency in Hertz.

OPTIONAL ARGUMENTS

 - The scale in which to find the corresponding scale degree.

RETURN VALUE

 A scale degree number. This may be a decimal number.

EXAMPLE

(freq-to-degree 423 'chromatic-scale)

=> 68.317856

(freq-to-degree 423 'twelfth-tone)

=> 409.9071

(freq-to-degree 423 'quarter-tone)

=> 136.63571

SYNOPSIS

(defun freq-to-degree (freq &optional (scale cm::*scale*))

cm/freq-to-midi [ Functions ]

[ Top ] [ cm ] [ Functions ]

DATE

 10th July 2016, Essen Werden

DESCRIPTION

 convert a frequency in Hertz to a MIDI note number (possibly floating
 point, indicating microtonality).  

ARGUMENTS

 a frequency in Hertz

RETURN VALUE

 a floating point value representing the MIDI note number of the given frequency

EXAMPLE

(freq-to-midi 260) --> 59.892094
(freq-to-midi (midi-to-freq 60)) --> 60.0

SYNOPSIS

(defun freq-to-midi (freq)

cm/freq-to-note [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Get the note-name pitch equivalent of the specified frequency, rounded to
 the nearest scale degree of the current scale.

ARGUMENTS

 A number that is a frequency in Hertz.

OPTIONAL ARGUMENTS

 - The scale in which the note-name pitch equivalent is to be sought (Common
 Music scale object or symbol). If a symbol, then 'chromatic-scale,
 'twelfth-tone, or 'quarter-tone only at present.

RETURN VALUE

 A note-name pitch symbol.

EXAMPLE

(freq-to-note 423 'chromatic-scale)

=> AF4

(freq-to-note 423 'twelfth-tone)

=> GSSS4

(freq-to-note 423 'quarter-tone)

=> AQF4

SYNOPSIS

(defun freq-to-note (freq &optional (scale cm::*scale*))

cm/get-pitch-bend [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Get the MIDI pitch-bend value necessary for application to a MIDI pitch in
 order to achieve the specified frequency.

 NB: This will always return a positive value between 0.0 and 1.0, as
     slippery-chicken always applies pitch-bends upwards from the nearest
     chromatic note below the specified frequency. 

 NB: This value will be the same in all tuning scales.

ARGUMENTS

 A frequency in Hertz.

RETURN VALUE

 A two-digit decimal number that is the pitch-bend value required to achieve
 the specified frequency in MIDI.

EXAMPLE

(get-pitch-bend 423)

=> 0.32

SYNOPSIS

(defun get-pitch-bend (freq)

cm/in-scale [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Set the global scale (tuning) for the current slippery-chicken
 environment. Current options are :chromatic, :quarter-tone or
 :twelfth-tone. See the file cm-load.lsp for specifications and the html
 manual page "More about note-names and scales" for more details on use.

ARGUMENTS

 - A scale (tuning) designation.

RETURN VALUE

 the (new) Common Music scale object

EXAMPLE

(in-scale :chromatic)

=> #<tuning "chromatic-scale">

(in-scale :quarter-tone)

=> #<tuning "quarter-tone">

(in-scale :twelfth-tone)

=> #<tuning "twelfth-tone">

SYNOPSIS

(defun in-scale (scale)

cm/midi-file-high-low [ Functions ]

[ Top ] [ cm ] [ Functions ]

DATE

 30-Dec-2010

DESCRIPTION

 Print the highest and lowest pitch in a specified MIDI file as a MIDI note
 number. 

 NB: This is a Common Music function and as such must be called with the
     package qualifier cm:: if used within slippery chicken.

ARGUMENTS

 - The path (including the name) to the MIDI file.

OPTIONAL ARGUMENTS

 - An integer or NIL to indicate which track in the specified MIDI file is
   to be accessed. If NIL, all tracks will be accessed. NB: CM (and
   therefore slippery-chicken too) generates some MIDI files by writing each
   channel to a different track, so the "track" would seem synonymous with
   "channel" here. 

RETURN VALUE

 Two integer values (using the values function) that are the highest and
 lowest pitches in the specified MIDI file.

EXAMPLE

(cm::midi-file-high-low "/tmp/multi-ps.mid")

=> 72, 60

SYNOPSIS

(defun midi-file-high-low (file &optional track)

cm/midi-file-one-note [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Write all midi notes in the file out to a new one-channel file using the
 single pitch <note> and channel number <channel>.

ARGUMENTS

 - A string that is the file path, including file-name and extension.
 - A note-name symbol or MIDI-note integer that is the pitch to write.
 - An integer that is the channel to which the output should be written
   (1-based) 

OPTIONAL ARGUMENTS

 - An integer that is the an existing MIDI channel in the original file. If
   this argument is given, only notes on this channel of the original file
   will be written (1-based).

RETURN VALUE

 The path to the new file.

EXAMPLE

(cm::midi-file-one-note "/tmp/multi-ps.mid" 'c4 1)

SYNOPSIS

(defun midi-file-one-note (file note channel &optional old-channel)

cm/midi-file-to-events [ Functions ]

[ Top ] [ cm ] [ Functions ]

DATE

 28/6/16, Edinburgh

DESCRIPTION

 Read in a MIDI file and convert notes to event objects.

ARGUMENTS

 the path to the midi file

OPTIONAL ARGUMENTS

 keyword arguments:
 - :track. The track number to read. Default = NIL which means read all
 tracks.
 - :tempo. The tempo of the track in crotchets (quarter notes) per
 minute. Default, q = 120.

RETURN VALUE

 a list of event objects

SYNOPSIS

(defun midi-file-to-events (file &key track (tempo 120.0))

cm/midi-to-degree [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Convert the specified MIDI note number to the degree number of the current
 scale. 

ARGUMENTS

 - A MIDI note number.

RETURN VALUE

 - An integer that is the scale-degree equivalent of the specified MIDI note
   number in the current scale.

EXAMPLE

(in-scale :chromatic)
(midi-to-degree 64)

=> 64

(in-scale :twelfth-tone)
(midi-to-degree 64)

=> 384

(in-scale :quarter-tone)
(midi-to-degree 64)

=> 128

SYNOPSIS

(defun midi-to-degree (midi-note &optional (scale cm::*scale*))

cm/midi-to-freq [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Get the frequency equivalent in Hertz to the specified MIDI note number. 

ARGUMENTS

 - A number (can be a decimal) that is a MIDI note number.

RETURN VALUE

 A decimal number that is a frequency in Hertz.

EXAMPLE

(midi-to-freq 67)

=> 391.99542

(midi-to-freq 67.9)

=> 412.91272

SYNOPSIS

(defun midi-to-freq (midi-note)

cm/midi-to-note [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Get the note-name pitch symbol equivalent of the specified MIDI note
 number. 

ARGUMENTS

 - a MIDI note number: integer or float. If float, appropriate microtones
 will be returned if the current scale is microtonal (e.g. (in-scale
 :quarter-tone)) 

RETURN VALUE

 A note-name pitch symbol.

EXAMPLE

(midi-to-note 67)
=> G4
(midi-to-note 60.5)
=>CQS4

SYNOPSIS

(defun midi-to-note (midi-note &optional (scale cm::*scale*))

cm/midi2qlist [ Functions ]

[ Top ] [ cm ] [ Functions ]

DATE

 10th November 2016, Edinburgh

DESCRIPTION

 Convert a midi-file to qlist text format, for sequencing in PD or MaxMSP.
 If you don't want specific tracks from the file, just pass two arguments so
 <tracks> remains nil.

ARGUMENTS

 - the path to the midi file you want to convert (string)
 - the path to the qlist text file you'd like to write (string). If this is
   nil then we'll write to the same patch as the midi file with the extension
   .txt added. NB If this file exists it will be overwritten, no questions
   asked.
 - (&rest) the numbers of the tracks you'd like to convert, starting from 1.

RETURN VALUE

 The number of notes written (integer)

SYNOPSIS

(defun midi2qlist (midi-file qlist-file &rest tracks)

cm/note-to-degree [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Get the scale degree number of the specified note-name pitch symbol within
 the current scale. 

ARGUMENTS

 - A note-name pitch symbol.

OPTIONAL ARGUMENTS

 - The scale in which to find the scale-degree of the specified pitch.

RETURN VALUE

 An integer that is a scale degree in the current scale.

EXAMPLE

(note-to-degree 'AF4 'chromatic-scale)

=> 68

(note-to-degree 'AF4 'twelfth-tone)

=> 408

(note-to-degree 'AF4 'quarter-tone)

=> 136

SYNOPSIS

(defun note-to-degree (note &optional (scale cm::*scale*))

cm/note-to-freq [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Get the frequency in Hertz of the specified note-name pitch symbol.

ARGUMENTS

 - A note-name pitch symbol.

RETURN VALUE

 A frequency in Hertz.

EXAMPLE

(in-scale :chromatic)
(note-to-freq 'AF4)

=> 415.3047

(in-scale :twelfth-tone)
(note-to-freq 'GSSS4)

=> 423.37845

(in-scale :quarter-tone)
(note-to-freq 'AQF4)

=> 427.47403

SYNOPSIS

(defun note-to-freq (note)

cm/note-to-midi [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Get the MIDI note number equivalent for a chromatic note-name pitch
 symbol. 

ARGUMENTS

 - A chromatic note-name pitch symbol.

RETURN VALUE

 An integer.

EXAMPLE

(note-to-midi 'g4)

=> 67

SYNOPSIS

(defun note-to-midi (midi-note)

cm/parse-midi-file [ Functions ]

[ Top ] [ cm ] [ Functions ]

DESCRIPTION

 Return Common Music MIDI events in the specified file as a list.

 NB: This is a Common Music function and as such must be called with the
     package qualifier cm:: if used within slippery chicken.

ARGUMENTS

 - The path (including the file name) to the MIDI file.

OPTIONAL ARGUMENTS

 - An integer or NIL to indicate which track in the specified MIDI file is
   to be accessed. If NIL, all tracks will be accessed. NB: CM (and
   therefore slippery-chicken too) generates some MIDI files by writing each
   channel to a different track, so the "track" would seem synonymous with
   "channel" here. 

RETURN VALUE

 The CM data for the MIDI events in the specified file, and the number of
 events. 

EXAMPLE

(cm::parse-midi-file "/tmp/multi-ps.mid")

=>
(#i(midi-tempo-change time 0.0 usecs 357142)
 #i(midi-time-signature time 0.0 numerator 2 denominator 4 clocks 24 32nds 8)
 #i(midi time 0.0 keynum 36 duration 0.357142 amplitude 0.09448819 channel 15)
 #i(midi-tempo-change time 0.0 usecs 357142)
 #i(midi-time-signature time 0.0 numerator 2 denominator 4 clocks 24 32nds 8)
 #i(midi-tempo-change time 0.0 usecs 357142)
 #i(midi time 0.178571 keynum 66 duration 0.178571 amplitude 0.09448819 channel 15)
 #i(midi time 0.357142 keynum 68 duration 0.0892855 amplitude 0.09448819 channel 15)
 #i(midi time 0.357142 keynum 40 duration 0.357142 amplitude 0.09448819 channel 15)
 #i(midi time 0.6249985 keynum 66 duration 0.0892855 amplitude 0.09448819 channel 15)
 #i(midi-time-signature time 0.714284 numerator 3 denominator 4 clocks 24 32nds 8)

SYNOPSIS

(defun parse-midi-file (file &optional track)