Parser (All-in-One Editor and Analyser)¶

class chordparser.Parser¶

A class that acts as a central collection for Editors and Analysers.

The Parser inherits all the various Editors and Analysers. As such, all the examples using the Editors and Analysers can also use the Parser to create and interact with musical objects. This makes it more convenient to initialise the various musical classes without having to initialise many different Editors for each class beforehand.

Examples

>>> cp = Parser()
>>> cp.create_note("D#")
D♯ note
>>> c_chord = cp.create_chord("Cmaj7/G")
>>> c_chord
Cmaj7/G chord
>>> c_scale = cp.create_scale("C", "major")
>>> cp.analyse_diatonic(c_chord, c_scale)
[(IM43 roman chord, 'major', None)]

analyse_all(chord, scale, incl_submodes=False, allow_power_sus=False, default_power_sus='M')¶

Analyse if a Chord is diatonic to a Scale for any mode.

The Chord is analysed against the Scale as well as the other modes of the Scale.

Parameters:	chord (Chord) – The Chord to be analysed. scale (Scale) – The Scale to check against. incl_submodes (boolean, Optional) – Selector to include the minor submodes if scale is minor. Default False when optional. allow_power_sus (boolean, Optional) – Selector to allow power and sus chords when analysing them. Default False when optional. default_power_sus ({"M", "m"}, Optional) – The default quality to convert power and sus chords to if analysing them. “M” is major and “m” is minor.
Returns:	A list of information on the Chord if it is diatonic. The first str is the mode of the scale it is diatonic to and the second str is the submode. The list is empty if the Chord is not diatonic.
Return type:	list of (Roman, str, str)

Examples

>>> CE = ChordEditor()
>>> SE = ScaleEditor()
>>> CA = ChordAnalyser()

Diatonic chords

>>> c_scale = SE.create_scale("C", "minor")
>>> degree_1 = CE.create_diatonic(c_scale, 1)
>>> CA.analyse_all(degree_1, c_scale)
[(i roman chord, 'minor', 'natural'), (i roman chord, 'dorian', None), (i roman chord, 'phrygian', None)]

Checking against minor submodes

>>> degree_7 = CE.create_chord("G")
>>> CA.analyse_diatonic(degree_7, c_scale)
[(V roman chord, 'major', None), (V roman chord, 'lydian', None)]
>>> CA.analyse_diatonic(degree_7, c_scale, incl_submodes=True)
[(V roman chord, 'minor', 'harmonic'), (V roman chord, 'minor', 'melodic'), (V roman chord, 'major', None), (V roman chord, 'lydian', None)]

Analysing power/sus chords

>>> power = CE.create_chord("C5")
>>> CA.analyse_diatonic(power, c_scale)
[]
>>> CA.analyse_diatonic(power, c_scale, allow_power_sus=True, default_power_sus="m")
[(I roman chord, 'major', None), (I roman chord, 'mixolydian', None), (I roman chord, 'lydian', None)]

analyse_diatonic(chord, scale, incl_submodes=False, allow_power_sus=False, default_power_sus='M')¶

Analyse if a Chord is diatonic to a Scale.

There may be multiple tuples in the returned list if submodes are included.

Parameters:	chord (Chord) – The Chord to be analysed. scale (Scale) – The Scale to check against. incl_submodes (boolean, Optional) – Selector to include the minor submodes if scale is minor. Default False when optional. allow_power_sus (boolean, Optional) – Selector to allow power and sus chords when analysing them. Default False when optional. default_power_sus ({"M", "m"}, Optional) – The default quality to convert power and sus chords to if analysing them. “M” is major and “m” is minor.
Returns:	A list of information on the Chord if it is diatonic. The first str is the Scale’s mode and the second str is the Scale’s submode. The list is empty if the Chord is not diatonic.
Return type:	list of (Roman, str, str)

Examples

>>> CE = ChordEditor()
>>> SE = ScaleEditor()
>>> CA = ChordAnalyser()

Diatonic chords

>>> c_scale = SE.create_scale("C", "minor")
>>> degree_1 = CE.create_diatonic(c_scale, 1)
>>> CA.analyse_diatonic(degree_1, c_scale)
[(i roman chord, 'minor', 'natural')]

Checking against minor submodes

>>> degree_7 = CE.create_chord("G")
>>> CA.analyse_diatonic(degree_7, c_scale)
[]
>>> CA.analyse_diatonic(degree_7, c_scale, incl_submodes=True)
[(VII roman chord, 'minor', 'harmonic'), (VII roman chord, 'minor', 'melodic')]

Analysing power/sus chords

>>> power = CE.create_chord("C5")
>>> CA.analyse_diatonic(power, c_scale)
[]
>>> CA.analyse_diatonic(power, c_scale, allow_power_sus=True, default_power_sus="m")
[(i roman chord, 'minor', 'natural')]

analyse_secondary(prev_chord, next_chord, scale, incl_submodes=False, allow_power_sus=False, default_power_sus='M', limit=True)¶

Analyse if a Chord has a secondary function.

Check if a Chord is a secondary chord. By default, only secondary dominant and secondary leading tone chords are checked for.

Parameters:	prev_chord (Chord) – The Chord to be analysed for secondary function. next_chord (Chord) – The Chord to be tonicised. scale (Scale) – The Scale to check against. incl_submodes (boolean, Optional) – Selector to include the minor submodes if scale is minor. Default False when optional. allow_power_sus (boolean, Optional) – Selector to allow power and sus chords when analysing them. Default False when optional. default_power_sus ({"M", "m"}, Optional) – The default quality to convert power and sus chords to if analysing them. “M” is major and “m” is minor. limit (boolean, Optional) – Selector to only check for secondary dominant and leading tone chords. Default True when optional.
Returns:	The secondary chord notation `prev_roman`/`next_roman`.
Return type:	str

Examples

>>> CE = ChordEditor()
>>> SE = ScaleEditor()
>>> CA = ChordAnalyser()

Diatonic chords

>>> c_scale = SE.create_scale("C")
>>> g = CE.create_diatonic(c_scale, 5)
>>> d = CE.create_chord("D")
>>> CA.analyse_secondary(d, g, c_scale)
'V/V'

Checking against minor submodes

>>> vii = CE.create_chord("C#dim7")
>>> degree_2 = CE.create_diatonic(c_scale, 2)
>>> CA.analyse_secondary(vii, degree_2, c_scale)
''
>>> CA.analyse_secondary(vii, degree_2, c_scale, incl_submodes=True)
'vii°7/ii'

Analysing power/sus chords

>>> power = CE.create_chord("D5")
>>> g = CE.create_diatonic(c_scale, 5)
>>> CA.analyse_secondary(power, g, c_scale)
''
>>> CA.analyse_secondary(power, g, c_scale, allow_power_sus=True)
'V/V'

Analysing other secondary chords

>>> e = CE.create_chord("Em")
>>> CA.analyse_secondary(e, g, c_scale)
''
>>> CA.analyse_secondary(e, g, c_scale, limit=False)
'vi/V'

change_chord(chord, root=None, quality=None, add=None, remove=None, bass=None, inplace=True)¶

Change a Chord’s attributes.

Alter parts of the Chord by specifying the standard chord notation for each attribute.

Parameters:	chord (Chord) – The Chord to be changed. root (str, Optional) – The root of the Chord. quality (str, Optional) – The quality of the Chord. add (str, Optional) – The added notes of the Chord. remove (str, Optional) – The added notes of the Chord that are to be removed. bass (str or boolean, Optional) – The bass note of the Chord. Specify False to remove the bass note. inplace (boolean, Optional) – Selector to change the current Chord or to return a new Chord. Default True when optional.
Returns:	The changed Chord.
Return type:	Chord

Examples

>>> CE = ChordEditor()
>>> c = CE.create_chord("C7add4/G")
>>> CE.change_chord(c, root="D#", quality="maj7", add="b6", remove="4", bass=False)
D♯maj7♭6 chord
>>> CE.change_chord(c, root="E", quality="m", bass="C#", inplace=False)
Em♭6/C♯ chord
>>> c
D♯maj7♭6 chord

change_key(key, root=None, mode=None, submode=None, inplace=True)¶

Change a Key’s root, mode and/or submode attributes.

The root note must be a valid Note notation if type str. The submode refers to the different types of ‘minor’/ ‘aeolian’ mode, i.e. ‘natural’, ‘harmonic’ and ‘melodic’. Hence, other than the ‘minor’/ ‘aeolian’ mode, the submode must be None.

Parameters:	key (Key) – The Key which attributes you want to change. root (Note, Optional) – The root of the Key to be changed. mode ({None, 'major', 'minor', 'ionian', 'dorian', 'phrygian', 'lydian', 'mixolydian', 'aeolian', 'locrian'}, Optional) – The mode of the Key to be changed. submode ({None, 'natural', 'harmonic', 'melodic'}, Optional) – The submode of the Key to be changed. Default ‘natural’ for the ‘minor’/ ‘aeolian’ mode and None for the other modes when optional. inplace (boolean, optional) – Selector to change the notation of current Key or to return a new Key. Default True when optional.
Returns:	The Key with the new attributes.
Return type:	Key

Examples

>>> KE = KeyEditor()
>>> c = KE.create_key("C", "dorian")
>>> KE.change_key(c, root="D", mode="minor", submode="harmonic")
D harmonic minor
>>> KE.change_key(c, mode="major", inplace=False)
D major
>>> c
D harmonic minor

change_note(note, notation, inplace=True)¶

Change a Note’s notation.

Accepts a-g or A-G and optional accidental symbols (b, bb, #, ##, or their respective unicode characters ♭, ♯, 𝄫, or 𝄪).

Parameters:	note (Note) – The Note which value you want to change. notation (str) – The new notation for the Note. inplace (boolean, optional) – Selector to change the notation of current Note or to return a new Note. Default True when optional.
Returns:	The Note with the new notation.
Return type:	Note

Examples

>>> NE = NoteEditor()
>>> a = NE.create_note("A")
>>> NE.change_note(a, "Bb")
B♭ note
>>> NE.change_note(a, "C#", inplace=False)
C♯ note
>>> a
B♭ note

change_scale(scale, *args, inplace=True, **kwargs)¶

Change a Scale based on its Key.

The parameters accepted are the same parameters accepted for changing a Key: the root, mode and submode. The root must be a valid Note notation if type str. The submode refers to the different types of ‘minor’/ ‘aeolian’ mode, i.e. ‘natural’, ‘harmonic’ and ‘melodic’. Hence, other than the ‘minor’/ ‘aeolian’ mode, the submode must be None.

Parameters:	scale (Scale) – The Scale which key you want to change. args (iterable) – The parameters for changing the Scale’s Key. inplace* (boolean, Optional) – Selector to change the current Scale or to return a new Scale. Default True when optional. *kwargs (dict*) – The keyword parameters for changing the Scale’s Key.
Returns:	The Scale with the new Key.
Return type:	Scale

Examples

>>> SE = ScaleEditor()
>>> c = SE.create_scale("C", "major")
>>> SE.change_scale(c, "D", "lydian")
D lydian scale
>>> SE.change_scale(c, "E", "dorian", inplace=False)
E dorian scale
>>> c
D lydian scale

create_chord(notation)¶

Create a Chord.

Parameters:	notation (str) – The Chord notation. Standard chord notation [1] is accepted.
Returns:	The created Chord.
Return type:	Chord
Raises:	`SyntaxError` – If the notation is invalid. `SyntaxError` – If the string of added notes is invalid.

References

[1]	‘Chord letters’ (2020) Wikipedia. Available at https://en.wikipedia.org/wiki/Chord_letters (Accessed: 28 July 2020)

Examples

>>> CE = ChordEditor()
>>> CE.create_chord("C#dim7addb4/E")
C♯dim7add♭4/E chord
>>> CE.create_chord("Ebsus4add#9/G")
E♭sus♯9/G chord

create_diatonic(scale_key, degree=1)¶

Create a diatonic Chord from a Scale or Key.

Parameters:	scale_key (Scale or Key) – The Scale or Key to create the diatonic Chord from. degree (int, Optional) – The scale degree of the diatonic Chord. Default 1 when optional.
Returns:	The created diatonic Chord.
Return type:	Chord
Raises:	`ValueError` – If degree is not in the range [1, 7].

Examples

>>> KE = KeyEditor()
>>> SE = ScaleEditor()
>>> c_key = KE.create_key("C", "major")
>>> c_scale = SE.create_scale(c_key)
>>> CE = ChordEditor()
>>> CE.create_diatonic(c_key, 3)
Em chord
>>> CE.create_diatonic(c_scale, 7)
Bdim chord

create_key(root, mode='major', submode=None)¶

Create a Key from a root note, mode and submode.

The root note must be a valid Note notation if type str. The submode refers to the different types of minor/aeolian mode, i.e. natural, harmonic and melodic. Hence, other than the ‘minor’/ ‘aeolian’ mode, the submode must be None.

Parameters:	root (Note or str) – The root note of the Key. mode ({'major', 'minor', 'ionian', 'dorian', 'phrygian', 'lydian', 'mixolydian', 'aeolian', 'locrian'}, Optional) – The mode of the Key. submode ({None, 'natural', 'harmonic', 'melodic'}, Optional) – The submode of the Key. Default ‘natural’ for the ‘minor’/ ‘aeolian’ mode and None for the other modes when optional.
Returns:	The created Key.
Return type:	Key
Raises:	`ModeError` – If the mode is not ‘minor’/ ‘aeolian’ and the submode has been specified. `SyntaxError` – If the mode is ‘minor’/ ‘aeolian’ and the submode is invalid.

Examples

>>> KE = KeyEditor()
>>> KE.create_key("C")
C major
>>> KE.create_key("D", "dorian")
D dorian
>>> KE.create_key("E", "minor")
E natural minor
>>> KE.create_key("F", "minor", "harmonic")
F harmonic minor

create_note(notation)¶

Create a Note from its notation.

Accepts a-g or A-G and optional accidental symbols (b, bb, #, ##, or their respective unicode characters ♭, ♯, 𝄫, or 𝄪).

Parameters:	notation (str) – The notation of the Note.
Returns:	A Note object with value equal to its notation.
Return type:	Note
Raises:	`SyntaxError` – If the notation does not follow accepted notation.

Examples

>>> NE = NoteEditor()
>>> NE.create_note("C")
C note
>>> NE.create_note("D#")
D♯ note

create_scale(value, *args, **kwargs)¶

Create a Scale.

Specify either a Key or the parameters necessary to create a Key.

Parameters:	value – Either a Key or the first parameter for creating a Key (i.e. the root). args (iterable) – The parameters for creating a Key. kwargs (dict*) – The keyword parameters for creating a Key.
Returns:	The created Scale.
Return type:	Scale

See also

chordparser.KeyEditor.create_key(): See the necessary parameters for creating a Key.

Examples

>>> SE = ScaleEditor()
>>> KE = KeyEditor()
>>> c_key = KE.create_key("C", "minor")
>>> SE.create_scale(c_key)
C natural minor scale
>>> SE.create_scale("C", "major")
C major scale

get_intervals(*notes)¶

Get the semitone intervals between Notes.

Multiple Notes as arguments are accepted. The interval for each Note is relative to the previous Note.

Parameters:	notes (Note*) – Any number of Notes.
Returns:	The tuple of semitone intervals between all adjacent Notes.
Return type:	tuple of int

Examples

>>> NE = NoteEditor()
>>> c = NE.create_note("C")
>>> f = NE.create_note("F")
>>> a = NE.create_note("A")
>>> NE.get_intervals(c, f, a)
(5, 4)

get_letter_intervals(*notes)¶

Get the letter intervals between Notes.

Multiple Notes as arguments are accepted. The interval for each Note is relative to the previous Note.

Parameters:	notes (Note*) – Any number of Notes.
Returns:	The tuple of letter intervals between all adjacent Notes.
Return type:	tuple of int

Examples

>>> NE = NoteEditor()
>>> c = NE.create_note("C")
>>> f = NE.create_note("F")
>>> a = NE.create_note("A")
>>> NE.get_letter_intervals(c, f, a)
(3, 2)

get_min_intervals(*notes)¶

Get the shortest semitone distance between Notes.

Multiple Notes as arguments are accepted. The distance for each Note is relative to the previous Note.

Parameters:	notes (Note*) – Any number of Notes.
Returns:	The tuple of the shortest semitone distances between all adjacent Notes.
Return type:	tuple of int

Examples

>>> NE = NoteEditor()
>>> c = NE.create_note("C")
>>> b = NE.create_note("B")
>>> NE.get_intervals(c, b)
(11,)
>>> NE.get_min_intervals(c, b)
(-1,)

get_tone_letter(*notes)¶

Get the semitone and letter intervals between Notes.

Multiple Notes as arguments are accepted. The intervals for each Note are relative to the previous Note.

Parameters:	notes (Note*) – Any number of Notes.
Returns:	The nested tuple of semitone and letter intervals between all adjacent Notes. The inner tuple is the semitone and letter intervals between two adjacent Notes.
Return type:	tuple of (int, int)

Examples

>>> NE = NoteEditor()
>>> c = NE.create_note("C")
>>> f = NE.create_note("F")
>>> a = NE.create_note("A")
>>> NE.get_tone_letter(c, f, a)
((5, 3), (4, 2))

relative_major(key)¶

Change a Key to its relative major.

The Key’s mode must be ‘minor’/ ‘aeolian’.

Parameters:	key (Key) – The Key to be changed.
Raises:	`ModeError` – If the Key is not ‘minor’/ ‘aeolian’.

Examples

>>> KE = KeyEditor()
>>> key = KE.create_key("D", "minor")
>>> KE.relative_major(key)
D major

relative_minor(key, submode='natural')¶

Change a Key to its relative minor.

The Key’s mode must be ‘major’/ ‘ionian’.

Parameters:	key (Key) – The Key to be changed. submode ({'natural', 'harmonic', 'melodic'}, Optional) – The new submode of the relative minor Key.
Raises:	`ModeError` – If the Key is not ‘major’/ ‘ionian’. `SyntaxError` – If the submode is invalid.

Examples

>>> KE = KeyEditor()
>>> key = KE.create_key("D", "major")
>>> KE.relative_minor(key)
D natural minor
>>> key2 = KE.create_key("E", "major")
>>> KE.relative_minor(key, "melodic")
E melodic minor

to_roman(chord, scale_key)¶

Converts a Chord to Roman.

Creates the Roman based on the Chord and a Scale or Key.

Parameters:	chord (Chord) – The Chord to be converted. scale_key (Scale or Key) – The Scale or Key to base the Roman on.
Returns:	The Roman of the Chord.
Return type:	Roman
Warns:	UserWarning – If the Chord is a power or sus chord.

Examples

>>> KE = KeyEditor()
>>> SE = ScaleEditor()
>>> CE = ChordEditor()
>>> CRC = ChordRomanConverter()
>>> c_key = KE.create_key("C")
>>> c_scale = SE.create_scale(c_key)
>>> d = CE.create_diatonic(c_scale, 2)
>>> CRC.to_roman(d, c_key)
ii roman chord
>>> f = CE.create_diatonic(c_scale, 4)
>>> CRC.to_roman(f, c_scale)
IV roman chord