The music-spelling Reference Manual

This is the music-spelling Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sat Dec 03 22:35:57 2022 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 music-spelling

Automatic pitch and rhythm spelling.

Author

Nuno Trocado

License

Apache 2.0

Version

0.1

Dependency

alexandria (system).

Source

music-spelling.asd.

Child Components

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 music-spelling/music-spelling.asd

Source

music-spelling.asd.

Parent Component

music-spelling (system).

ASDF Systems

music-spelling.


3.1.2 music-spelling/package.lisp

Source

music-spelling.asd.

Parent Component

music-spelling (system).

Packages

music-spelling.


3.1.3 music-spelling/pitch-spelling.lisp

Dependency

package.lisp (file).

Source

music-spelling.asd.

Parent Component

music-spelling (system).

Public Interface
Internals

3.1.4 music-spelling/rhythm-spelling.lisp

Dependency

pitch-spelling.lisp (file).

Source

music-spelling.asd.

Parent Component

music-spelling (system).

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 music-spelling

Source

package.lisp.

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *chord-penalties*

Penalties used when spelling chords.

Package

music-spelling.

Source

pitch-spelling.lisp.

Special Variable: *default-parsimony*
Package

music-spelling.

Source

pitch-spelling.lisp.

Special Variable: *default-penalties*
Package

music-spelling.

Source

pitch-spelling.lisp.

Special Variable: *natural-parsimony*
Package

music-spelling.

Source

pitch-spelling.lisp.


5.1.2 Ordinary functions

Function: make-parsimony (&rest letter-accidental-pairs)

Make a parsimony hash table from LETTER-ACCIDENTAL-PAIRS, each a cons of a ‘pitch-letter’ char and on of :natural, :flat, :sharp, :double-flat or :double-sharp.

Package

music-spelling.

Source

pitch-spelling.lisp.

Function: make-parsimony-ht-from-notes (notes)

Returns a parsimony hash table produced from the accidentals in the list of ‘note’ objects NOTES.

Package

music-spelling.

Source

pitch-spelling.lisp.

Function: make-penalties (&key accidentals augmented diminished direction double-accidentals e#-fb-b#-cb other-intervals parsimony default)

Returns a hash table with the following cumulative penalties used in pitch scoring:

ACCIDENTALS: note is sharp or flat;
AUGMENTED: augmented interval between two consecutive notes;
DIMINISHED: diminished interval between two consecutive notes;
DIRECTION: ascending with flats or descending with sharps;
DOUBLE-ACCIDENTALS: note is double sharp or double flat;
E#-Fb-B#-Cb: specific penalty for these spellings;
OTHER-INTERVALS: intervals between two consecutive notes other than major, minor, perfect, augmented or diminished (e.g. doubly augmented interval); PARSIMONY: occurrence of an accidental different from previous used ones (or pre-defined on a given parsimony table).

Unsupplied values are taken from DEFAULT.

Penalty values are summed when scoring each spelling try. A lower score is better.

Package

music-spelling.

Source

pitch-spelling.lisp.

Function: metric-subdivision (d)
Package

music-spelling.

Source

rhythm-spelling.lisp.

Function: min-subdivision-quantize (d subdivision)
Package

music-spelling.

Source

rhythm-spelling.lisp.

Function: pitch-spell (midi-note-numbers &key split penalties parsimony)

Spell notes in MIDI-NOTE-NUMBERS, a list of midi note values, Returning a list of ‘note’ objects.

For longer sequences, computing the n-fold cartesian product of all spelling possibilites becomes dramatically time-intensive. Therefore, the sequence is split in blocks of SPLIT elements, which are calculated separately. However, maintaining previous choices of accidentals across blocks is preferred (divergences receive the ’parsimony’ penalty). PENALTIES is a hash table with the penalties for various situations, summed when scoring spelling tries (see ‘make-penalties’). PARSIMONY is a hash table with the chars for the letters from ’a’ to ’g’ as keys and their preferred initial spelling (:natural, :sharp, :flat, etc.) as values.

Example:
(pitch-spell ’(48 50 52 53 55 57 59 60 61 64 65 68 69))

–> (#<NOTE C3> #<NOTE D3> #<NOTE E3> #<NOTE F3> #<NOTE G3> #<NOTE A3> #<NOTE B3>
#<NOTE C4> #<NOTE C#4> #<NOTE E4> #<NOTE F4> #<NOTE Ab4> #<NOTE A4>)

Package

music-spelling.

Source

pitch-spelling.lisp.

Function: pitch-spell-chords (chord-seq &key penalties parsimony)

Spell chords in CHORD-SEQ, a list of chords, where each chord is a list of midi note values, returning a similarly structured list with the values replaced by ‘note’ objects.
PENALTIES is a hash table with the penalty values for various situations, summed when scoring spelling tries (see ‘make-penalties’). PARSIMONY is a hash table with the chars for the letters from ’a’ to ’g’ as keys and their preferred initial spelling (:natural, :sharp, :flat, etc.) as values.

Example:
(pitch-spell-chords ’((60 64 67) (61 65 68) (62 66 69)))

–> ((#<NOTE C4> #<NOTE E4> #<NOTE G4>) (#<NOTE Db4> #<NOTE F4> #<NOTE Ab4>)
(#<NOTE D4> #<NOTE F#4> #<NOTE A4>))

Package

music-spelling.

Source

pitch-spelling.lisp.

Function: rest-p (x)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: rhythm-spell (pitches durations &optional beats-per-bar offset min-subdivision)
Package

music-spelling.

Source

rhythm-spelling.lisp.


5.1.3 Generic functions

Generic Reader: accidental (object)
Generic Writer: (setf accidental) (object)
Package

music-spelling.

Methods
Reader Method: accidental ((note note))
Writer Method: (setf accidental) ((note note))

Accidentals are :natural, :double-flat, :flat, :sharp, :double-sharp

Source

pitch-spelling.lisp.

Target Slot

accidental.

Generic Reader: letter (object)
Generic Writer: (setf letter) (object)
Package

music-spelling.

Methods
Reader Method: letter ((note note))
Writer Method: (setf letter) ((note note))

One of c, d, e, f, g, a or b

Source

pitch-spelling.lisp.

Target Slot

letter.

Generic Reader: octave (object)
Generic Writer: (setf octave) (object)
Package

music-spelling.

Methods
Reader Method: octave ((note note))
Writer Method: (setf octave) ((note note))

The octave. Middle C is on the fourth octave.

Source

pitch-spelling.lisp.

Target Slot

octave.


5.1.4 Standalone methods

Method: print-object ((object note) stream)
Source

pitch-spelling.lisp.


5.1.5 Classes

Class: note
Package

music-spelling.

Source

pitch-spelling.lisp.

Direct methods
Direct slots
Slot: letter

One of c, d, e, f, g, a or b

Type

music-spelling::pitch-letter

Initform

#\c

Initargs

:letter

Readers

letter.

Writers

(setf letter).

Slot: accidental

Accidentals are :natural, :double-flat, :flat, :sharp, :double-sharp

Type

keyword

Initform

:natural

Initargs

:accidental

Readers

accidental.

Writers

(setf accidental).

Slot: octave

The octave. Middle C is on the fourth octave.

Type

integer

Initform

4

Initargs

:octave

Readers

octave.

Writers

(setf octave).


5.2 Internals


5.2.1 Ordinary functions

Function: %pitch-spell (midi-note-numbers penalties parsimony)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: abs-interval-in-semitones (note1 note2)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: augmented-interval-p (note1 note2)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: common-enharmonics-p (note)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: count-accidentals (notes)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: count-augmented-intervals (notes)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: count-diminished-intervals (notes)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: count-double-accidentals (notes)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: count-penalties (notes-vec best-score-so-far &optional penalties parsimony-ht)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: crosses-bars-p (duration onset &optional beats-per-bar)
Package

music-spelling.

Source

rhythm-spelling.lisp.

Function: crosses-beats-p (duration onset)
Package

music-spelling.

Source

rhythm-spelling.lisp.

Function: diminished-interval-p (note1 note2)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: distance-from-major-or-perfect (note1 note2)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: dots (int-part frac-part)
Package

music-spelling.

Source

rhythm-spelling.lisp.

Function: ends-a-beat-p (end)
Package

music-spelling.

Source

rhythm-spelling.lisp.

Function: funny-interval-p (note1 note2)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: int-frac (d)
Package

music-spelling.

Source

rhythm-spelling.lisp.

Function: interval-in-semitones (note1 note2)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: interval-number (note1 note2)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: interval-quality (note1 note2)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: letter-value (letter)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: major-or-perfect-interval-size (interval-number)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: make-chord-penalties ()
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: make-default-penalties ()
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: make-natural-parsimony ()
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: map-product (function list &rest more-lists)

Non-collecting version of the function in Alexandria.

Package

music-spelling.

Source

pitch-spelling.lisp.

Function: note->midi-note-number (note)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: parsimony (note)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: pitch-letter-p (letter)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: possible-spellings (midi-note-number)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: post-half-bar (duration onset beats-per-bar)
Package

music-spelling.

Source

rhythm-spelling.lisp.

Function: rest-of-bar (onset &optional beats-per-bar)
Package

music-spelling.

Source

rhythm-spelling.lisp.

Function: rest-of-beat (onset)
Package

music-spelling.

Source

rhythm-spelling.lisp.

Function: score-spelling (notes best-score-so-far penalties parsimony)
Package

music-spelling.

Source

pitch-spelling.lisp.

Function: ties (p d tie-from beats-per-bar offset)
Package

music-spelling.

Source

rhythm-spelling.lisp.


5.2.2 Types

Type: pitch-letter ()
Package

music-spelling.

Source

pitch-spelling.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   %   (  
A   C   D   E   F   G   I   L   M   N   O   P   R   S   T  
Index Entry  Section

%
%pitch-spell: Private ordinary functions

(
(setf accidental): Public generic functions
(setf accidental): Public generic functions
(setf letter): Public generic functions
(setf letter): Public generic functions
(setf octave): Public generic functions
(setf octave): Public generic functions

A
abs-interval-in-semitones: Private ordinary functions
accidental: Public generic functions
accidental: Public generic functions
augmented-interval-p: Private ordinary functions

C
common-enharmonics-p: Private ordinary functions
count-accidentals: Private ordinary functions
count-augmented-intervals: Private ordinary functions
count-diminished-intervals: Private ordinary functions
count-double-accidentals: Private ordinary functions
count-penalties: Private ordinary functions
crosses-bars-p: Private ordinary functions
crosses-beats-p: Private ordinary functions

D
diminished-interval-p: Private ordinary functions
distance-from-major-or-perfect: Private ordinary functions
dots: Private ordinary functions

E
ends-a-beat-p: Private ordinary functions

F
Function, %pitch-spell: Private ordinary functions
Function, abs-interval-in-semitones: Private ordinary functions
Function, augmented-interval-p: Private ordinary functions
Function, common-enharmonics-p: Private ordinary functions
Function, count-accidentals: Private ordinary functions
Function, count-augmented-intervals: Private ordinary functions
Function, count-diminished-intervals: Private ordinary functions
Function, count-double-accidentals: Private ordinary functions
Function, count-penalties: Private ordinary functions
Function, crosses-bars-p: Private ordinary functions
Function, crosses-beats-p: Private ordinary functions
Function, diminished-interval-p: Private ordinary functions
Function, distance-from-major-or-perfect: Private ordinary functions
Function, dots: Private ordinary functions
Function, ends-a-beat-p: Private ordinary functions
Function, funny-interval-p: Private ordinary functions
Function, int-frac: Private ordinary functions
Function, interval-in-semitones: Private ordinary functions
Function, interval-number: Private ordinary functions
Function, interval-quality: Private ordinary functions
Function, letter-value: Private ordinary functions
Function, major-or-perfect-interval-size: Private ordinary functions
Function, make-chord-penalties: Private ordinary functions
Function, make-default-penalties: Private ordinary functions
Function, make-natural-parsimony: Private ordinary functions
Function, make-parsimony: Public ordinary functions
Function, make-parsimony-ht-from-notes: Public ordinary functions
Function, make-penalties: Public ordinary functions
Function, map-product: Private ordinary functions
Function, metric-subdivision: Public ordinary functions
Function, min-subdivision-quantize: Public ordinary functions
Function, note->midi-note-number: Private ordinary functions
Function, parsimony: Private ordinary functions
Function, pitch-letter-p: Private ordinary functions
Function, pitch-spell: Public ordinary functions
Function, pitch-spell-chords: Public ordinary functions
Function, possible-spellings: Private ordinary functions
Function, post-half-bar: Private ordinary functions
Function, rest-of-bar: Private ordinary functions
Function, rest-of-beat: Private ordinary functions
Function, rest-p: Public ordinary functions
Function, rhythm-spell: Public ordinary functions
Function, score-spelling: Private ordinary functions
Function, ties: Private ordinary functions
funny-interval-p: Private ordinary functions

G
Generic Function, (setf accidental): Public generic functions
Generic Function, (setf letter): Public generic functions
Generic Function, (setf octave): Public generic functions
Generic Function, accidental: Public generic functions
Generic Function, letter: Public generic functions
Generic Function, octave: Public generic functions

I
int-frac: Private ordinary functions
interval-in-semitones: Private ordinary functions
interval-number: Private ordinary functions
interval-quality: Private ordinary functions

L
letter: Public generic functions
letter: Public generic functions
letter-value: Private ordinary functions

M
major-or-perfect-interval-size: Private ordinary functions
make-chord-penalties: Private ordinary functions
make-default-penalties: Private ordinary functions
make-natural-parsimony: Private ordinary functions
make-parsimony: Public ordinary functions
make-parsimony-ht-from-notes: Public ordinary functions
make-penalties: Public ordinary functions
map-product: Private ordinary functions
Method, (setf accidental): Public generic functions
Method, (setf letter): Public generic functions
Method, (setf octave): Public generic functions
Method, accidental: Public generic functions
Method, letter: Public generic functions
Method, octave: Public generic functions
Method, print-object: Public standalone methods
metric-subdivision: Public ordinary functions
min-subdivision-quantize: Public ordinary functions

N
note->midi-note-number: Private ordinary functions

O
octave: Public generic functions
octave: Public generic functions

P
parsimony: Private ordinary functions
pitch-letter-p: Private ordinary functions
pitch-spell: Public ordinary functions
pitch-spell-chords: Public ordinary functions
possible-spellings: Private ordinary functions
post-half-bar: Private ordinary functions
print-object: Public standalone methods

R
rest-of-bar: Private ordinary functions
rest-of-beat: Private ordinary functions
rest-p: Public ordinary functions
rhythm-spell: Public ordinary functions

S
score-spelling: Private ordinary functions

T
ties: Private ordinary functions