Welcome to sjkabc’s documentation!¶

Tutorial¶

sjkabc provides a set of functions that parses ABC music notation. There are currently three major types of functions:

• strip functions: These all begin with strip_. The strip functions return the passed string stripped from, for example, ornaments or accidentals. These functions can be used to create simplified notation suitable for searching.
• expand functions: These functions will expand repeats, multiple endings, and ‘long notes’. These functions are also valuable for creating searchable ABC.
• parse functions: These are helper functions which use Parser to parse files and directories.

The two core classes in sjkabc are Parser and Tune, which are used to parse and describe pieces of ABC music.

from sjkabc import Parser

abc_string = """
X: 37
T: Apples In Winter
C: Trad.
R: Jig
M: 6/8
L: 1/8
K: Em
BEE BEE|Bdf edB|BAF FEF|DFA BAF|
BEE BEE|Bdf edB|BAB dAF|1FED EGA:|2FED EAc||
|:e2f gfe|eae edB|BAF FEF|DFA BAF|
e2f gfe|eae edB|BAB dAF|1FED EAc:|2FED E3|]
"""
for tune in Parser(abc_string):
    print tune.title[0]

from sjkabc import parse_file

for tune in parse_file('test.abc'):
    print('Parsed {} with index number {}.'.format(tune.title[0], tune.index[0])

from sjkabc import parse_dir

for tune in parse_dir('/data/music/abc/'):
    print('Parsed {} with index number {}.'.format(tune.title[0], tune.index[0])

sjkabc¶

sjkabc.sjkabc

This module provides functionality for parsing ABC music notation.

sjkabc.HEADER_KEYS¶

Supported ABC notation header keys. This dict is used to populate the attributes of Tune.

sjkabc.DECORATIONS = ['!trill!', '!trill(!', '!trill)!', '!lowermordent!', '!uppermordent!', '!mordent!', '!pralltriller!', '!roll!', '!turn!', '!turnx!', '!invertedturn!', '!invertedturnx!', '!arpeggio!', '!>!', '!accent!', '!emphasis!', '!fermata!', '!invertedfermata!', '!tenuto!', '!0!', '!1!', '!2!', '!3!', '!4!', '!5!', '!+!', '!plus!', '!snap!', '!slide!', '!wedge!', '!upbow!', '!downbow!', '!open!', '!thumb!', '!breath!', '!pppp!', '!ppp!', '!pp!', '!p!', '!mp!', '!mf!', '!f!', '!ff!', '!fff!', '!ffff!', '!sfz!', '!crescendo(!', '!<(!', '!crescendo)!', '!<)!', '!diminuendo(!', '!>(!', '!diminuendo)!', '!>)!', '!segno!', '!coda!', '!D.S.!', '!D.C.!', '!dacoda!', '!dacapo!', '!fine!', '!shortphrase!', '!mediumphrase!', '!longphrase!', '.', '~', 'H', 'L', 'M', 'O', 'P', 'S', 'T', 'u', 'v']¶

List of decoration symbols according to the ABC notation standard v2.1.

class sjkabc.Parser(abc=None)[source]¶

This class provides iterable parsing capabilities.

Parser must be initialised with a string containing ABC music notation. This class is iterable and will return a Tune object for every tune found in the provided ABC notation.

Example:

>>> for tune in Parser(abc):
...     print('Parsed ', tune.title)

See also

Tune

parse(abc)[source]¶

Parse ABC notation.

This function will append found ABC tunes to self.tunes.

Parameters:	abc – string containing abc to parse

class sjkabc.Tune(**kwargs)[source]¶

This class represents a parsed tune.

Its attributes are generated from HEADER_KEYS, with the addition of abc and expanded_abc().

Example:

>>> t = Tune()
>>> t.title = 'Example tune'
>>> t.abc = '|:abc abc:|'
>>> t.expanded_abc
'abcabcabcabc'

See also

HEADER_KEYS, Parser

abc = None¶

Tune body.

expanded_abc¶

Expanded ABC suitable for searching

Returns:	expanded abc
Return type:	str

format_abc()[source]¶

Format ABC tune

This will return the current Tune as a properly formatted string, including header fields and ABC.

Returns:	ABC string suitable for writing to file
Return type:	str

sjkabc.expand_abc(abc)[source]¶

Create searchable abc string

This runs all the stripping and expanding functions on the input string, and also makes it lowercase.

Parameters:	abc (str) – string of abc to expand
Returns:	string of expanded abc
Return type:	str

See also

strip_octave(), strip_accidentals(), strip_triplets(), strip_chords() strip_ornaments(), expand_notes(), expand_parts(), strip_whitespace() strip_bar_dividers(), strip_extra_chars(), strip_slurs()

sjkabc.expand_notes(abc)[source]¶

Expand notes, so that E2 becomes EE et.c.

Parameters:	abc (str) – abc to expand
Returns:	expanded abc
Return type:	str

sjkabc.expand_parts(abc)[source]¶

Expand repeats with support for (two) alternate endings.

Example:

>>> print(expand_parts('aaa|bbb|1ccc:|2ddd|]'))
aaa|bbb|ccc|aaa|bbb|ddd|

Parameters:	abc (str) – abc to expand
Returns:	expanded abc
Return type:	str

sjkabc.get_field_from_id(id)[source]¶

Get long field name from id char.

Parameters:	id (str) – id char, for example ‘T’
Returns:	long field name, like ‘title’
Return type:	str
Raises:	KeyError – if key does not exist.

sjkabc.get_id_from_field(field)[source]¶

Get id char from field name

Parameters:	field (str) – ‘long’ name of field, for example ‘title’
Returns:	id character, for example ‘T’
Return type:	str
Raises:	KeyError – if key does not exist.

sjkabc.parse_dir(dir)[source]¶

Run Parser on every file with .abc extension in dir

Parameters:	dir – Directory of abc files
Returns:	Tune object for every found file
Return type:	Tune

See also

parse_file(), Parser, Tune

sjkabc.parse_file(filename)[source]¶

Run Parser on file contents

This function is iterable.

Example:	>>> for tune in parse_file('test.abc'): ... print(tune.title)
Parameters:	filename – Name of file to parse
Returns:	Tune object for every found tune.
Return type:	Tune

See also

parse_dir(), Parser, Tune

sjkabc.strip_accidentals(abc)[source]¶

Remove accidentals from string.

Example:

>>> from sjkabc import strip_accidentals
>>> stripped = strip_whitespace('abc ^c=de|_e^fg _g=fe')
>>> stripped
'abc cde|efg gfe'

Parameters:	abc (str) – abc to filter
Returns:	abc with accidentals removed
Return type:	str

sjkabc.strip_bar_dividers(abc)[source]¶

Strip bar dividers from string

This function can safely be run before expand_parts, as it won’t remove repeats.

Example:

>>> from sjkabc import strip_bar_dividers
>>> stripped = strip_bar_dividers('abcd bcde|bcde abcd|defg abcd|bebe')
>>> stripped
'abcd bcdebcde abcddefg abcdbebe'

Parameters:	abc (str) – abc to filter
Returns:	abc without bar dividers
Return type:	str

sjkabc.strip_chords(abc)[source]¶

Strip chords and ‘guitar chords’ from string.

Example:

>>> from sjkabc import strip_chords
>>> stripped = strip_chords('"G" abc|"Em" bcd|[GBd] cde')
>>> stripped
' abc| bcd | cde'

Parameters:	abc (str) – abc to filter
Returns:	abc with chords stripped
Return type:	str

sjkabc.strip_decorations(abc)[source]¶

Remove decorations

Removes decorations defined in the v2.1 ABC notation standard.

Parameters:	abc (str) – ABC notation to process
Returns:	stripped ABC
Return type:	str

See also

DECORATIONS

New in version 1.2.0.

sjkabc.strip_extra_chars(abc)[source]¶

Strip misc extra chars (/<>)

Parameters:	abc (str) – abc to filter
Returns:	filtered abc
Return type:	str

sjkabc.strip_gracenotes(abc)[source]¶

Remove gracenotes

Example:

>>> stripped = strip_gracenotes('abc bcd|c3 def|{/def}efg abc|')
>>> stripped
'abc bcd|c3 def|efg abc|'

Parameters:	abc (str) – abc to strip
Returns:	abc stripped from gracenotes
Return type:	str

sjkabc.strip_octave(abc)[source]¶

Remove octave specifiers from string.

Example:

>>> from sjkabc import strip_octave
>>> stripped = strip_octave("A,B,C,d'e'f'")
>>> stripped
'ABCdef'

Parameters:	abc (str) – abc to filter
Returns:	abc with octave specifiers removed
Return type:	str

sjkabc.strip_ornaments(abc)[source]¶

Remove gracenotes, tildes, trills, turns and fermatas from string.

Example:

>>> from sjkabc import strip_ornaments
>>> stripped = strip_ornaments('abc bcd|~c3 def|{/def}efg !trill(!ab|')
>>> stripped
'abc bcd|c3 def|efg ab|'

Parameters:	abc (str) – abc to filter
Returns:	filtered abc
Return type:	str

Deprecated since version 1.2.0: Use strip_gracenotes() and strip_decorations() instead.

sjkabc.strip_slurs(abc)[source]¶

Remove slurs from string.

Example:

>>> strip_slurs('|:ab(cd) (a(bc)d):|')
|:abcd abcd:|

Warning

Don’t use this before strip_decorations() as it may change certain decorations so that they wont be recognized. One example would be !trill(!.

Parameters:	abc (str) – abc to manipulate
Returns:	abc stripped from slurs
Return type:	str

sjkabc.strip_triplets(abc)[source]¶

Remove duplets, triplets, quadruplets, etc from string.

Please note that this simply removes the (n and leaves the following notes.

Example:

>>> from sjkabc import strip_triplets
>>> stripped = strip_triplets('AB(3cBA Bcde|fd(3ddd (4efed (4BdBF')
>>> stripped
'ABcBA Bcde|fdddd efed BdBF'

Parameters:	abc (str) – abc to filter
Returns:	abc without triplets
Return type:	str

sjkabc.strip_whitespace(abc)[source]¶

Remove whitespace and newlines from string.

Parameters:	abc (str) – abc to filter
Returns:	abc with whitespace removed
Return type:	str

sjkabc.wrap_line(string, id, max_length=78, prefix='+')[source]¶

Wrap header line.

Parameters:	string (str) – string to wrap id (str) – character id of header line max_length (int) – maximum line length prefix (str) – Line prefix for wrapped lines (first line exempted)
Returns:	wrapped line
Return type:	str

See also

get_id_from_field()

Limitations¶

Please note that sjkabc does not currently fully conform to the ABC music standard as it does not implement all features and header keys. This is the future goal, however, and contributions are very welcome.

Contributing to the sjkabc project¶

$ git clone https://github.com/sjktje/sjkabc.git

$ mkvirtualenv --python=python3 sjkabc

$ cd path/to/sjkabc
$ workon sjkabc
$ git checkout develop
$ python setup.py develop

Change Log¶