pytakt.context module

This module defines the Context class and its associated functions.

class Context(dt=0, L=480, v=80, nv=None, duoffset=0, durate=100, tk=1, ch=1, o=4, key=0, effectors=[], **kwargs)

Bases: object

The Context class object (context) is a collection of parameters that are referenced by functions defined in the sc module as well as the mml() function.

Contexts can be switched by using the ‘with’ syntax. For example:

mycontext = Context(ch=2, v=50)
with mycontext:
    ...

will activate mycontext within the ‘with’ block, and return to the original context upon exiting the block.

It is possible to change the value of the context’s attribute by mycontext.ch=3 for example, but you must use the addattr() method to add a new attribute.

The functions defined in the sc module and the mml() function can also be used as methods of the Context class, allowing context-specific score generation (e.g. mycontext.note(C4), mycontext.mml('CDE'), etc.).

To ensure safe use in multi-threaded environments, the currently active context is managed separately for each thread. When a new thread is created, its context is always the default context (the context obtained by Context()).

Attributes

dt

Specifies the value of the dt attribute (difference between the notated time and played time) of generated events.

Type:

ticks

tk

Specifies the value of the tk attribute (track number) of generated events.

Type:

int

ch

Specifies the value of the ch attribute (MIDI channel number) of generated events.

Type:

int

v

Specifies the value of the v attribute (velocity) of generated NoteEvent events.

Type:

int

nv

Specifies the value of the nv attribute (note-off velocity) of generated NoteEvent events.

Type:

int or None

L

Specifies the value of the L attribute of generated NoteEvent events. This corresponds to the note value in ticks in the score. It is also used to specify the length of rests in the rest() function.

Type:

ticks

duoffset

Holds the offset value of the playing duration of the note (the difference between note-on and note-off times in the performance, aka. gate time). Optionally, a function to get that value from the value of the L attribute can be specified. Together with durate below, it is used to determine the playing duration of a note.

Type:

ticks or function

durate

The value added to the playing duration as a percentage of the note value. The playing duration is determined by the following equation together with the duoffset above.

note duration at play = duoffset + L * durate / 100 (when duoffset is an int/float)

note duration at play = duoffset(L) + L * durate / 100 (when duoffset is a function)

If the note duration at play is negative, it is corrected to 0.

The note() function sets the above value to the du attribute of NoteEvent (or omitted if the value is the same as the L attribute value).

Type:

int or float

o

An integer representing the octave (4 being the octave starting from the middle C). This is used only by the mml() function.

Type:

int

key

Specifies the key for automatic sharpening or flattening. It can be a Key object or the first argument of the Key() constructor. This is only used by the mml() function.

Type:

Key, int, or str

effectors

A list of callable objects for score conversion; callables (typically Effector instances) in this list are applied to the return value of the mml() function or that of the functions in the sc module, in sequence from the first element of the list to the last.

Type:

list of callable objects

Pseudo-attributes

In order to facilitate the specification of the playing duration of notes, the following two pseudo-attributes are provided. These can be read and written in the same way as normal instance attributes, but they are not registered as attributes.

du

Represents the note duration at play. Reading du yields the note duration at play (see the expression shown in the durate item above). Writing a value x to du sets duoffset to x and simultaneously sets durate to 0 (or 100 if x is negative).

Examples:

note(C4, du=120): Fixes the note duration at play to 120 ticks.

note(C4, du=-30): sets the playing duration to 30 ticks less than the L attribute value and thus keeps the gap between notes to 30 ticks.

Type:: ticks

dr

Represents the percentage of the duration at play to the note value. Reading dr yields the value of the durate attribute. Writing a value to dr sets durate to that value and simultaneously sets duoffset to 0.

Examples:

note(C4, dr=50) : sets the playing duration to 50% of the note value (simulating so-called “staccato” playing).

Type:: int or float

Constructor

Parameters:

• dt – Specifies attribute values of the same name.

• L – Specifies attribute values of the same name.

• v – Specifies attribute values of the same name.

• nv – Specifies attribute values of the same name.

• duoffset – Specifies attribute values of the same name.

• durate – Specifies attribute values of the same name.

• tk – Specifies attribute values of the same name.

• ch – Specifies attribute values of the same name.

• o – Specifies attribute values of the same name.

• key – Specifies attribute values of the same name.

• effectors – Specifies the value of the ‘effectors’ attribute. A copy of the list is assigned to the attribute.

• kwargs – specifies additional attributes for the context.

copy() → Context

Returns a duplicated context. For the ‘effectors’ attribute value, the list is duplicated. For other attributes, a shallow copy is made.

addattr(name, value=None) → None

Adds a new attribute to the context.

Parameters:

• name (str) – name of the attribute

• value (any) – initial value of the attribute

has_attribute(name) → bool

Returns true if name is an attribute of the context. Differs from hasattr(self, name) in that it does not target method names.

Parameters:

name (str) – name of the attribute

reset() → None

Returns all the attribute values to their initial values (i.e., default constructor argument values).

keys() → List[str]

Returns a list of attribute names.

items() → List[Tuple[str, Any]]

Returns a list of attribute name/value pairs.

update(**kwargs) → Context

Change attribute values according to the assignment description in kwargs.

Returns:

self

do(func, *args, **kwargs) → Any

Execute the function func in this context and return its return value.

Parameters:

• args – arguments passed to func.

• kwargs – arguments passed to func.

Examples

somecontext.do(lambda: note(C4) + note(D4))

attach(func) → Context

Inserts the score conversion function func at the beginning of the list in the ‘effectors’ attribute.

Returns:

self

Examples

>>> horn_in_F = newcontext().attach(Transpose(-Interval('P5')))
>>> horn_in_F.note(C4)
EventList(duration=480, events=[
    NoteEvent(t=0, n=F3, L=480, v=80, nv=None, tk=1, ch=1)])

detach() → Context

Deletes the first element of the list in the ‘effectors’ attribute.

Returns:

self

context() → Context

Returns the currently active context.

newcontext(**kwargs) → Context

Returns a copy of the currently active context with attribute values changed according to the assignment description in kwargs. Equivalent to context().copy().update(**kwargs).