pytakt.sc module

This module defines functions for generating note and other primitive scores. Functions other than note and rest are not imported to the namespace of the upper module (pytakt module), and therefore call them with submodule names like sc.ctrl.

note(pitch, L=None, step=None, **kwargs) → EventList

Generates an EventList containing one NoteEvent as a score consisting of a single note. The time (t attribute value) of the generated NoteEvent will always be 0.

Parameters:

  • pitch (Pitch or int) – Specifies the pitch of the note. The n attribute of the generated NoteEvent will have this value.

  • L (ticks, optional) – Specifies the note value (note length). If omitted, it takes the value from the L attribute of the context. The L attribute of the generated NoteEvent will have this value.

  • step (ticks, optional) – Specifies the value of the ‘duration’ attribute of the generated event list (i.e., the duration of the generated score). If omitted, it is the same as the note value.

  • kwargs – Additional keyword arguments. For each keyword argument, if the context has a (pseudo)attribute of the same name, it specifies a temporary change (override) of the context value; otherwise, it produces an additional attribute in the generated NoteEvent.

Referenced context attributes

dt, tk, ch, v, nv, L, duoffset, durate, effectors

Examples

>>> note(C4)
EventList(duration=480, events=[
    NoteEvent(t=0, n=C4, L=480, v=80, nv=None, tk=1, ch=1)])
>>> note(C4, L8, step=120)
EventList(duration=120, events=[
    NoteEvent(t=0, n=C4, L=240, v=80, nv=None, tk=1, ch=1)])
>>> note(Db5, ch=3, dt=30, dr=50)  # modifying context
EventList(duration=480, events=[
    NoteEvent(t=0, n=Db5, L=480, v=80, nv=None, tk=1, ch=3, dt=30, du=240)])
rest(L=None) → EventList

Generates an EventList with no events as a score of a rest.

Parameters:

L (ticks, optional) – Specifies the length of the rests. The duration attribute of the generated EventList will be this value. If omitted, it will be the value of the L attribute of the context.

Referenced context attributes

L, effectors

ctrl(ctrlnum, value, *, n=None, word=False, duration=0, tstep=30, ystep=1, _rpc=None, **kwargs) → EventList

Generates an EventList containing CtrlEvent(s) or TempoEvent(s). In addition to a single control value, it is possible to generate incrementally changing multiple control values using Interpolator.

Parameters:

  • ctrlnum (int) – Specifies the controller number (see CtrlEvent). If this value is C_TEMPO (192), TempoEvent(s) are generated.

  • value (int, float, 2-tuple, or list) – Specifies the control value. If it is an int or float, a CtrlEvent/TempoEvent is generated based on a single control value. If it is a 2-tuple, the word argument is assumed to be implicitly True, and the upper and lower bytes are specified separately in (MSB, LSB) format. If it is a list, the value is passed to the constructor of Interpolator to generate a stepwise sequence of CtrlEvent/TempoEvent’s.

  • n (int or Pitch, optional) – For key-pressure events (i.e., when ctrlnum is C_KPR), it specifies the MIDI note number. Not applicable for other types of events.

  • word (bool, optional) – In the case of a control change when ctrlnum is 31 or less, setting this argument to True will cause a 14-bit control value to be generated in two separate CtrlEvents with different controller numbers. In the case of the stepwise control, two CtrlEvents will be generated for each output value.

  • duration (ticks or str, optional) – Specifies the value of the ‘duration’ attribute of the output event list. If ‘auto’ is specified, the duration will be 0 for a single control value and the time of the last CtrlEvent/TempoEvent for a stepwise control.

  • tstep (ticks, optional) – Specifies the time step value for a stepwise control (see Interpolator.iterator()).

  • ystep (int or float, optional) – Specifies the threshold of the output value changes for a stepwise control (see Interpolator.iterator()).

  • kwargs – Additional keyword arguments. For each keyword argument, if the context has an attribute of the same name, it specifies a temporary change (override) of the context value; otherwise, it produces an additional attribute for each of the output CtrlEvent/TempoEvent’s.

Referenced context attributes

dt, tk, ch, effectors

Examples

>>> sc.ctrl(7, 60, ch=2)  # volume control: value=60  MIDI_channel=2
EventList(duration=0, events=[
    CtrlEvent(t=0, ctrlnum=C_VOL, value=60, tk=1, ch=2)])
>>> sc.ctrl(7, [0, (L4, 100)], tstep=120)  # linearly increasing volume
EventList(duration=480, events=[
    CtrlEvent(t=0, ctrlnum=C_VOL, value=0.0, tk=1, ch=1),
    CtrlEvent(t=120, ctrlnum=C_VOL, value=25.0, tk=1, ch=1),
    CtrlEvent(t=240, ctrlnum=C_VOL, value=50.0, tk=1, ch=1),
    CtrlEvent(t=360, ctrlnum=C_VOL, value=75.0, tk=1, ch=1),
    CtrlEvent(t=480, ctrlnum=C_VOL, value=100, tk=1, ch=1)])
>>> sc.ctrl(1, 80, duration=120)
EventList(duration=120, events=[
    CtrlEvent(t=0, ctrlnum=C_MOD, value=80, tk=1, ch=1)])
>>> sc.ctrl(0, (2, 3))  # specifying the value with (MSB,LSB) pair
EventList(duration=0, events=[
    CtrlEvent(t=0, ctrlnum=C_BANK, value=2, tk=1, ch=1),
    CtrlEvent(t=0, ctrlnum=C_BANK_L, value=3, tk=1, ch=1)])
bank(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for bank selects (#0 and #32 control changes). Equivalent to ctrl(0, value, **kwargs).

mod(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for modulation depth (#1 and #33 control changes). Equivalent to ctrl(1, value, **kwargs).

breath(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for the breath controller (#2 and #34 control changes). Equivalent to ctrl(2, value, **kwargs).

foot(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for the foot controller (#4 and #36 control changes). Equivalent to ctrl(4, value, **kwargs).

porta(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for portamento time (#5 and #37 control changes). Equivalent to ctrl(5, value, **kwargs).

vol(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for the main (channel) volume (#7 and #39 control changes). Equivalent to ctrl(7, value, **kwargs).

pan(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for pan control (#10 and #42 control changes). Equivalent to ctrl(10, value, **kwargs).

expr(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for expression control (#11 and #43 control changes). Equivalent to ctrl(11, value, **kwargs).

reverb(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for Effect 1 (reverb) depth (#91 control change). Equivalent to ctrl(91, value, **kwargs).

ped(value=127, **kwargs) → EventList

Generate an EventList containing CtrlEvent that turns on the damper pedal. Equivalent to ctrl(64, value, **kwargs).

pedoff(**kwargs) → EventList

Generates an EventList containing a CtrlEvent that turn off the damper pedal. Equivalent to ctrl(64, 0, **kwargs).

ped2(value=127, **kwargs) → EventList

Generate an EventList containing CtrlEvent that turn on the soft pedal. Equivalent to ctrl(67, value, **kwargs).

ped2off(**kwargs) → EventList

Generate an EventList containing a CtrlEvent that turn off the soft pedal. Equivalent to ctrl(67, 0, **kwargs).

ped3(value=127, **kwargs) → EventList

Generates an EventList containing CtrlEvent that turn on the sostenuto pedal. Equivalent to ctrl(66, value, **kwargs).

ped3off(**kwargs) → EventList

Generates an EventList containing a CtrlEvent that turn off the sostenuto pedal. Equivalent to ctrl(66, 0, **kwargs).

portaon(value=127, **kwargs) → EventList

Generates an EventList containing CtrlEvent that turn portamento on. Equivalent to ctrl(65, value, **kwargs).

portaoff(**kwargs) → EventList

Generates an EventList containing a CtrlEvent that turn portamento off. Equivalent to ctrl(65, 0, **kwargs).

all_sound_off(**kwargs) → EventList

Generates an EventList containing an all-sound-off CtrlEvent. Equivalent to ctrl(120, 0, **kwargs).

reset_all_ctrls(**kwargs) → EventList

Generates an EventList containing a reset-all-controllers CtrlEvent. Equivalent to ctrl(121, 0, **kwargs).

all_notes_off(**kwargs) → EventList

Generates an EventList containing an all-note-off CtrlEvent. Equivalent to ctrl(123, 0, **kwargs).

bend(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for pitch bending. Values must be in the range of -8192 to 8191. Equivalent to ctrl(C_BEND, value, **kwargs).

cpr(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for channel pressure. Equivalent to ctrl(C_CPR, value, **kwargs).

prog(value, **kwargs) → EventList

Generates an EventList containing CtrlEvent for program change. The value must be in the range of 1-128. Equivalent to ctrl(C_PROG, value, **kwargs).

kpr(pitch, value, **kwargs) → EventList

Generate an EventList containing KeyPressureEvent for polyphonic key pressure.. Equivalent to ctrl(C_KPR, value, n=pitch, **kwargs).

rpc(rpn, data, nrpc=False, **kwargs) → EventList

Generates an EventList for RPC (Registered Parameter Control) or NRPC (Non-Registered Parameter Control).

Parameters:

  • rpn (int or 2-tuple) – Specifies the parameter number (RPN or NRPN). It is either a 16-bit number (upper 8 bits are MSB, lower 8 bits are LSB) or a 2-tuple (MSB, LSB).

  • data (int, float, 2-tuple, or list) – Specifies the data to be sent with the data entry (#6 and #36 control changes).

  • nrpc (bool, optional) – False for NPC, True for NRPC.

  • kwargs – Other arguments passed to the ctrl() function.

Referenced context attributes

dt, tk, ch, effectors

Examples

>>> sc.rpc((0, 1), 8835, word=True)  # Fine tuning to A=442Hz
EventList(duration=0, events=[
    CtrlEvent(t=0, ctrlnum=C_RPCL, value=1, tk=1, ch=1),
    CtrlEvent(t=0, ctrlnum=C_RPCH, value=0, tk=1, ch=1),
    CtrlEvent(t=0, ctrlnum=C_DATA, value=69, tk=1, ch=1),
    CtrlEvent(t=0, ctrlnum=C_DATA_L, value=3, tk=1, ch=1)])
bender_range(semitones, **kwargs) → EventList

Generates an EventList for setting pitch bend sensitivity using rpc().

Parameters:

  • semitones (int) – Specifies the pitch bend range in semitones.

  • example (For) –

  • octaves. (12 for +-1) –

  • kwargs – Other arguments passed to the ctrl() function.

fine_tune(*, freq=None, cents=None, **kwargs) → EventList

Generates an EventList for fine tuning using rpc().

Parameters:

  • freq (int or float) – Specifies the frequency of the A4 tone. Cannot be specified at the same time with cents.

  • cents (int or float) – Specifies the deviation from the standard tuning (A4=440Hz) in cents (1/100 of a semitone). Must be ranged such that -100 <= cents < 100. Cannot be specified at the same time with freq.

  • kwargs – Other arguments passed to the ctrl() function.

coarse_tune(semitones, **kwargs) → EventList

Generates an EventList for course tuning using rpc().

Parameters:

  • semitones (int) – Deviation from standard tuning in semitones (signed).

  • kwargs – Other arguments passed to the ctrl() function.

tempo(value, **kwargs) → EventList

Generates an EventList containing TempoEvent. The track number (tk attribute) is 0 regardless of context unless explicitly specified. Equivalent to ctrl(C_TEMPO, value, **kwargs).

Parameters:

  • value (int or float) – Tempo value in BPM (minimum value is 4)

  • kwargs – Other arguments passed to the ctrl() function.

sysex(data, arbitrary=False, *, duration=0, **kwargs) → EventList

Generates an EventList containing a SysExEvent.

Parameters:

  • data (bytes, bytearray, or iterable of int) – Contents of the system-exclusive message. The 0xf0 at the beginning of the message and the 0xf7 at the end of the message need to be explicitly included. The value of each byte except those must be less than or equal to 0x7f (127).

  • arbitrary (bool, optional) – When this value is true, the event list is successfully generated even if the data does not start with 0xf0 and end with 0xf7 or contains data bytes larger than 0x7f (by default, an exception is raised for such cases). This is used to split a system-exclusive message into multiple events or to send arbitrary messages to the synthesizer.

  • duration (ticks, optional) – Specifies the ‘duration’ attribute value of the event list.

  • kwargs – Additional keyword arguments. For each keyword argument, if the context has an attribute of the same name, it specifies a temporary change (override) of the context value; otherwise, it produces an additional attribute in the output event.

Referenced context attributes

dt, tk, effectors

Examples

sc.sysex((0xf0, 0x7e, 0x7f, 0x09, 0x01, 0xf7)) # GM On

sc.sysex((0xf0, 0x7f, 0x7f, 4, 1, 0, 0, 50, 0xf7)) # Master volume = 50

meta(mtype, data, *, duration=0, **kwargs) → EventList

Generates an EventList containing a MetaEvent.

Parameters:

  • mtype (int) – Type of the meta-event (0-127)

  • data (bytes, bytearray, str, Key, or iterable of int) – Value of the ‘value’ attribute of MetaEvent

  • duration (ticks, optional) – Value of the ‘duration’ attribute of the event list.

  • kwargs – Additional keyword arguments. For each keyword argument, if the context has an attribute of the same name, it specifies a temporary change (override) of the context value; otherwise, it produces an additional attribute in the output event.

Referenced context attributes

dt, tk, effectors

seqno(value, **kwargs) → EventList

Generates an EventList containing a sequence-number event (a MetaEvent with mtype=0).

Parameters:

  • value (int) – Sequence number (0-65535)

  • kwargs – Other arguments passed to the meta() function.

Referenced context attributes

dt, effectors

title(string, **kwargs) → EventList

Generates an EventList containing a generic text event (a MetaEvent with mtype=1). Often used to describe song titles. The track number (tk attribute) is 0 regardless of the context unless explicitly specified.

Parameters:

  • string (str) – Text string

  • kwargs – Other arguments passed to the meta() function.

Referenced context attributes

dt, effectors

comment(string, **kwargs) → EventList

Generate an EventList containing a generic text event (a MetaEvent with mtype=1). Unlike title(), the track number is the value of the tk attribute in the context. Equivalent to meta(1, string, **kwargs).

copyright(string, **kwargs) → EventList

Generates an EventList containing a copyright notice event (a MetaEvent with mtype=2). The track number (tk attribute) will be 0 regardless of the context unless explicitly specified.

Parameters:

  • string (str) – Text string

  • kwargs – Other arguments passed to the meta() function.

Referenced context attributes

dt, effectors

trackname(string, **kwargs) → EventList

Generate an EventList containing a track name event (a MetaEvent with mtype=3). Equivalent to meta(3, string, **kwargs).

instname(string, **kwargs) → EventList

Generates an EventList containing an instrument name event (a MetaEvent with mtype=4). Equivalent to meta(4, string, **kwargs).

lyric(string, **kwargs) → EventList

Generates an EventList containing a lyrics event (a MetaEvengt with mtype=5). Equivalent to meta(5, string, **kwargs).

marker(string, **kwargs) → EventList

Generates an EventList containing a marker event (a MetaEvent with mtype=6). The track number (tk attribute) is 0 regardless of the context unless explicitly specified.

Parameters:

  • string (str) – Marker string

  • kwargs – Other arguments passed to the meta() function.

Referenced context attributes

dt, effectors

chprefix(value, **kwargs) → EventList

Generate an EventList containing a MIDI channel prefix event (a MetaEvent with mtype=0x20). Equivalent to meta(0x20, bytes((value,))), **kwargs).

devno(value, **kwargs) → EventList

Generate an EventList containing a device (port) number event (a MetaEvent with mtype=0x21). Equivalent to meta(0x21, bytes((value,))), **kwargs).

trackend(**kwargs) → EventList

Generates an EventList containing an end-of-track event (a MetaEvent with mtype=0x2f). Equivalent to meta(0x2f, b'', **kwargs).

timesig(num, den, cc=None, *, duration=0, **kwargs) → EventList

Generates an EventList containing a time signature event (a MetaEvent with mtype=0x58). The track number (tk attribute) is 0 regardless of the context unless explicitly specified.

Parameters:

  • num (int) – Numerator value

  • den (int) – Denominator value

  • cc (int, optional) – Interval between metronome clicks (see KeySignatureEvent).

  • duration (ticks, optional) – Specifies the ‘duration’ attribute value of the event list.

  • kwargs – Additional keyword arguments. For each keyword argument, if the context has an attribute of the same name, it specifies a temporary change (override) of the context value; otherwise, it produces an additional attribute in the output event.

Referenced context attributes

dt, effectors

Examples

sc.timesig(4,4) sc.timesig(5,8)

keysig(keydesc, minor=0, **kwargs) → EventList

Generates an EventList containing a key signature event (a MetaEvent with mtype=0x59). The track number (tk attribute) is 0 regardless of the context unless explicitly specified.

Parameters:

  • keydesc (int, str, or Key) – Description of the key (see Key)

  • minor (int, optional) – Mode (see Key)

  • kwargs – Other arguments passed to the meta() function.

Referenced context attributes

dt, effectors

Examples

sc.keysig('Eb-major') sc.keysig(0)

xml(xtype, value, *, duration=0, **kwargs) → EventList

Generates an EventList containing an XmlEvent (additional information event for staff notation). See XmlEvent for a list of information types.

Parameters:

  • xtype (str) – String representing the information type

  • value – Data content of the information

  • duration (ticks, optional) – Specifies the ‘duration’ attribute value of the event list.

Referenced context attributes

dt, tk, effectors