pytakt.effector module

このモジュールには、エフェクタ関連のクラスが定義されています。

class Effector

Bases: ABC

Effectorクラスは、すべてのエフェクタの基底となる抽象クラスです。

エフェクタとは、スコア変換を行う呼び出し可能オブジェクト (callable object) で、下の例のようにエフェクタオブジェクトに対して スコアを引数として呼び出すと、変換されたスコアを返します。

>>> eff = Transpose('M2')
>>> eff(note(C4))
EventList(duration=480, events=[
    NoteEvent(t=0, n=D4, L=480, v=80, nv=None, tk=1, ch=1)])

エフェクタによるスコア変換には次の性質があります。

• 元のスコアは破壊されずにそのまま残ります（ただし、EventStream の場合、 変換時に要素が読み出されることがあります）。

• 修正の必要のないイベントは、原則として元のスコアのものがそのまま出力 されます。そのようなイベントは元のスコアと変換後のスコアとで共有される ことになります。

• 変換後の各イベントリストにおけるイベントは時間順にソートされているとは 限りません。

特に断りのない限り、EventStream (無限長の場合を含む) に対しても適用でき ます。また、特に断りのない限り、分離したノートイベント (NoteOnEvent, NoteOffEvent) を含んだスコアに対しても適用できます。

各エフェクタクラスのコンストラクタは、Scoreクラスのメソッドとしても利用 できます。 その場合はエフェクタインスタンスの生成とスコア変換が連続して行われます (例: note(C4).Transpose('M2'))。

class EventEffector

Bases: Effector

EventEffector クラスは、各イベントに対して独立に変換を行うエフェクタの 抽象クラスです。

このクラスのエフェクタは、下の例のように、スコアだけでなく単独のイベントに 対しても変換を適用することができます。

>>> eff = Transpose('M2')
>>> eff(NoteOnEvent(0, C4))
NoteOnEvent(t=0, n=D4, v=80, tk=1, ch=1)

class CompositeEffector(first, second)

Bases: Effector

2つのエフェクタを合成したエフェクタのクラスです。 このエフェクタを適用すると、まず第1のエフェクタが適用された後に 第2のエフェクタが適用されます。

コンストラクタ引数

Parameters:

• first (Effector) – 第1のエフェクタのオブジェクト。

• second (Effector) – 第2のエフェクタのオブジェクト。

class Transpose(value, scale=None, transpose_keysig=True, instrument=False)

Bases: EventEffector

トランスポーズ操作 (ピッチを一定幅で上下させる操作) を適用します。 n属性を持つすべてのイベントに対して適用されます。

scale を指定しない場合、chromatic transposition になります。 value には Interval オブジェクトもしくは半音数を表す整数を 指定します (Interval オブジェクトの方が、異名同音を正しく処理するのに 有利です)。

scale を指定した場合、スケール上での transposition (diatonicスケールなら diatonic transposition) になります。value には、スケール上で何音上下 するかを表す整数を指定します。元のピッチを n とすると、 scale.pitch(scale.tonenum(n) + value) へ変換されます。

コンストラクタ引数

Parameters:

• value (Interval, str, or int) – 上下の幅。str型のときは Interval(value) と同じ意味になります。

• scale (Scale, optional) – スケールの指定。

• transpose_keysig (bool, optional) – この引数が Ture (デフォルト) で、 かつスケールの指定がない場合、KeySignatureEvent も移調の対象と します。それ以外の場合、KeySignatureEvent はそのまま出力されます。

• instrument (bool, optional) – この引数が True ならば、移調楽器について 正しい譜面が生成されるように XmlEvent (xtype=’transpose’) を出力に 挿入します。この引数が True のとき、scale は指定できません。 また、transpose_keysig は常に False に設定されます。

Examples

• mml("CDE").Transpose('M3') は mml("EF#G#") と等価なスコアを生成します。Transpose(E4-C4) でも同じ意味に なります。

• mml("CDE").Transpose(DEG(3), scale=Scale(C4)) は mml("EFG") と等価なスコアを生成します。

class Invert(center, scale=None)

Bases: EventEffector

反行形のスコアに変換します。具体的には、中心となるピッチ center を 指定し、n属性を持つ各イベントのピッチを、そのピッチと center との距離 の分だけ center から逆方向へ動かしたピッチへ変換します。

コンストラクタ引数

Parameters:

• center (Pitch or int) – 反転の中心となるピッチ。

• scale (Scale, optional) – スケールの指定。 省略時は chromatic inversion になり、指定した場合はそのスケール 上の inversion (diatonicスケールなら diatonic inversion) になり ます。

Examples

• mml("EFG*").Invert(E4) は mml("ED#C#*") と等価なスコアを 生成します。

• mml("EFG*").Invert(E4, scale=Scale(C4)) は mml("EDC*") と等価なスコアを生成します。

class ApplyScale(scale, round_mode='nearestup')

Bases: EventEffector

n属性を持つ各イベントのピッチを、Scale.get_near_scale_tone() を用いて、それに近いスケール上の音のピッチに変換します。

コンストラクタ引数

Parameters:

• scale (Scale) – スケール

• round_mode (str or function) – takt_roundx() へ渡す丸めモード。

Examples

• mml("C C# Db D E").ApplyScale(Scale(C4, 'minor')) は、 mml("C C D D Eb") と等価なスコアを生成します。’C#’ と ‘Db’ で 変換結果が違うのは、Scale.tonenum() の enharmonic_delta の 影響によるものです。

class ConvertScale(src_scale, dst_scale)

Bases: EventEffector

n属性を持つ各イベントについて、スケールの変換を行います。 元のピッチを n とすると、変換後のピッチは dst_scale.pitch(src_scale.tonenum(n)) になります。

コンストラクタ引数

Parameters:

• src_scale (Scale) – 元のスケール。

• dst_scale (Scale) – 変換後のスケール。 スケール構成音の数は、src_scale と同じでなければなりません。

Examples

• mml("C C# D E").ConvertScale(Scale(C4, 'major'), Scale(C4, 'minor')) は mml("C C# D Eb") と等価なスコアを生成します。

class ScaleVelocity(value)

Bases: EventEffector

ベロシティー(v属性)の値に value の値を乗じます。

コンストラクタ引数

Parameters:

value (float, int, or list) – ベロシティーの倍率。 float または int であるときは、その値がそのまま倍率となります。 list型であるときは、その値が Interpolator の コンストラクタへ渡され、それによって補間された値が倍率となります。

Examples

• note(C4, v=80).ScaleVelocity(1.2) は note(C4, v=96) と 等価なスコアを生成します。

• mml("v=80 CDEF").ScaleVelocity([1.0, (L1, 0.5)]) は mml("C(v=80) D(v=70) E(v=60) F(v=50)") と 等価なスコアを生成します。

class Repeat(rep=inf)

Bases: Effector

入力スコアを rep 回繰り返し演奏するスコアへ変換します。

コンストラクタ引数

Parameters:

rep (int, optional) – 繰り返し回数 (デフォルトは無限回)

class TimeStretch(stretch)

Bases: Effector

時間を stretch 倍に伸長します。

コンストラクタ引数

Parameters:

stretch (float or int) – 伸長の倍率。正の値で、1未満なら収縮になります。

Examples

mml("CDE*").TimeStretch(2) は mml("C*D*E**") と等価なスコアを 生成します。

class Retrograde

Bases: Effector

時間を逆行させたスコアへ変換します。

NoteEvent 以外のイベントについては時間の変換を行いません。

EventStreamに対しては適用できません。

Examples

• mml("CDE*").Retrograde() は mml("E*DC") と同じ演奏になる ようなスコアを生成します。

class Quantize(tstep, strength=1.0, window=1.0, keepdur=False, saveorg=False)

Bases: Effector

各イベントの時刻、およびスコアの演奏長に対して、クォンタイズ処理を 適用します。

コンストラクタ引数

Parameters:

• tstep (ticks) – クォンタイズのステップ時間。

• strength (float, optional) – クォンタイズの強さ (0～1)。1.0 (デフォルト) ならば、各イベントの 時刻は tstep の整数倍になるように修正されます。そうでないなら、 1.0 のときの修正量にこの値を乗じたものが実際の修正量になります。

• window (float, optional) – クォンタイズの対象となる時間区間の幅を、tstep に対する倍率で 指定します (0～1)。tstep の整数倍となる時刻を中心としたこの幅の 区間の中にあるイベントだけがクォンタイズの対象になります。 例えば、window=0.5 の場合、tstep * (N - 0.25) から tstep * (N + 0.25) が対象区間となります (N=0,1,2,…)。

• keepdur (bool, optional) – Trueならば、NoteEventのL属性の値を変更せずに、元の音価を保ちます（ NoteOffEventに対しては効果がありません）。 False (デフォルト) ならば、発音終了時刻もクォンタイズされるように L属性の値が調整されます。

• saveorg (bool, optional) – Trueならば、クオンタイズ前の時刻が演奏上の時刻として残るように dtとdu属性を設定します。もともと存在していたdtとdu属性の情報は 失われます。

Examples

• note(C4, 450).Quantize(120) は note(C4, 480) と等価なスコアを生成します。

• note(C4, 450).Quantize(120, strength=0.5) は note(C4, 465) と等価なスコアを生成します。

class TimeDeform(points, periodic=False, perf_only=False)

Bases: Effector

Interpolator によって記述された時間変換関数に従って、 各イベントの時刻、および演奏長を変換します。

コンストラクタ引数

Parameters:

• points (list of Point, etc.) – Interpolator に渡される引数。 これによって記述される時間変換関数は、単調非減少関数でなければ なりません。

• periodic (bool, optional) – Trueである場合、points のうちの最後の制御点の時刻を周期として、 同じパターンの時間変換関数が繰り返されることを仮定して時間変換が 行われます。

• perf_only (bool, optional) – Trueである場合、楽譜上の時間 (t属性とL属性) は元のまま保たれ、 演奏上の時間だけ変換されるように dt属性と du属性の値を調節します。 Falseの場合は、楽譜上の時間も変換されます。

Examples

• TimeDeform([(0, 0), (480, 482), (1920, 1950)]) を適用した場合、 元のスコアにおける時刻 0, 240, 480, 1920, 2000 は、それぞれ 0, 241, 482, 1950, 1950 に変換されます。

• TimeDeform([0, (240, 360), (480, 480)], periodic=True) を適用 した場合、元のスコアにおける時刻 0, 240, 480, 720, 960 は、それぞれ 0, 360, 480, 840, 960 に変換されます。この種の変換は、下の Swing エフェクタによってより簡潔に表現できます。

class Swing(period, rate=0.6666666666666666, perf_only=True)

Bases: TimeDeform

周期 period の各時間区間において、その中央の時刻が区間開始から period * rate 経過した時刻になるように時間変換を行います。

コンストラクタ引数

Parameters:

• period (ticks) – 周期

• rate (float) – スウィング効果の調節値 (0～1。0.5なら効果なし)

• perf_only (bool, optional) – Trueである場合、楽譜上の時間 (t属性とL属性) は元のまま保たれ、 演奏上の時間だけ変換されるように dt属性と du属性の値を調節します。 Falseの場合は、楽譜上の時間も変換されます。

Examples

mml("CDEF").Swing(L2, 0.75, False) は mml("C.D/E.F/") と等価な スコアを生成します。

class ToMilliseconds

Bases: TimeDeform

スコア中のすべて時間をミリ秒へ変換した上で、テンポイベントを取り除きます。

Examples

>>> mml("$tempo(120) c $tempo(240) d").ToMilliseconds()
EventList(duration=750.0, events=[
    NoteEvent(t=0.0, n=C4, L=500.0, v=80, nv=None, tk=1, ch=1),
    NoteEvent(t=500.0, n=D4, L=250.0, v=80, nv=None, tk=1, ch=1)]

class Randomize(time=10, veloc=10, adjust_ctrl=True)

Bases: Effector

各音符に対して、その演奏時刻 (実際には dt属性値) とベロシティに 乱数値を加えます。デフォルトでは、平均0、標準偏差は引数で指定された値の ガウス分布に従った乱数が使われます。

コンストラクタ引数

Parameters:

• time (int, float or function, optional) – int または float の場合、時刻に加える乱数値の標準偏差を 指定します（ティック単位）。生成された乱数値の絶対値が 標準偏差の3倍を超える場合は、3倍以内へ修正されます。 この引数が関数の場合は、その関数によって乱数値が生成されます。

• veloc (int, float or function, optional) – int または float の場合、ベロシティに加える乱数値の標準偏差を 指定します。関数の場合は、その関数によって乱数値が生成されます。

• adjust_ctrl (bool, optional) – Trueの場合、NoteEvent あるいは NoteOnEvent の演奏時刻に加えられる 乱数値が負であった場合で、修正された演奏時刻から元の演奏時刻までの 区間に、同じトラック、同じチャネル、同じピッチ (KeyPressureEventの ときのみ) の CtrlEvent が存在するときは、その CtrlEvent の演奏時刻 も NoteEvent あるいは NoteOnEvent の演奏時刻と同じ値に 修正されます。

class Clip(start, end=inf, initializer=True, split_notes=True)

Bases: Effector

時刻が start 以上、end 未満の部分だけ切り出します。 スコアの構造は保たれます。

コンストラクタ引数

Parameters:

• start (ticks or str) – 開始時刻。 スコア先頭からのティック数を表す数値、もしくは TimeSignatureMap.mbt2ticks() が受けつける文字列で指定します。

• end (ticks or str, optional) – 終了時刻。 スコア先頭からのティック数を表す数値、もしくは TimeSignatureMap.mbt2ticks() が受けつける文字列で指定します。 小節番号だけの文字列を与えたときは、その小節の終わりまでという 意味になります。

• initializer (bool, optional) – Trueの場合、start の時点でアクティブ (active_events_at() を参照) な CtrlEvent, TempoEvent, KeySignatureEvent, TimeSignatureEvent を冒頭でまとめて出力します。

• split_notes (bool, optional) – Trueの場合、start または end あるいはその両方の境界に またがったnoteは分割されて、結果にはその断片が格納されます。 Falseの場合は分割は行われずに、発音開始時刻(t属性値)が範囲内にある noteのみがそのまま結果に格納されます。 この機能は NoteEvent にのみ有効で、NoteOnEventやNoteOffEventに 対しては無効です。

Examples

Clip(960)

960ティック以降のスコアを切り出します。

Clip('3:2', '7')

小節番号3、拍番号2の位置から、小節番号7の小節の終わりまで を切り出します。拍番号は0から始まります。

class RemoveInitialSilence

Bases: Clip

冒頭の無音区間 (NoteEventやNoteOnEventが無い区間）を取り除きます。 無音区間終わりの時点でアクティブな CtrlEvent, TempoEvent, KeySignatureEvent, TimeSignatureEvent は冒頭でまとめて出力されます。 スコアの構造は保たれます。

class Arpeggio(delay=60)

Bases: Effector

スコア中のコード（同時に発音される音符のグループ）に対して、アルペジオ 演奏が行われるように、コードの各構成音に対してピッチに順番に応じた値を dt属性に加えます。また、ノートオフの時刻が変わらないようにdu属性の値を 調整します。デフォルトでは、下から上への (つまり、最高音が最も遅れる) アルペジオになります。

コンストラクタ引数

Parameters:

delay (ticks) – コード構成音間の時間のずれ幅を指定します。負の数を指定すると、 上から下へのアルペジオになります。

class Filter(*conds, negate=False, globals=None, locals=None)

Bases: Effector

条件を満たした（あるいは満たさない）イベントのみ含むスコアへ変換します。 スコアの構造は保存され、従って、空のイベントリストが残ることがあります。 各イベントはコピーされません。

コンストラクタ引数

Parameters:

• conds (class, str, or function, each) –

  各引数は基本条件を表し、 それらすべての論理和が最終的な条件となります。 各引数は次のいずれかです。

  • イベントクラス – そのクラス (またはそのサブクラス) に属する イベントならば真となります。

  • eval() によって評価可能な文字列 – bool値を与える Python の式を 含んだ文字列によって条件を指定します。文字列の中で、’ev’ は イベント自身、また、’t’, ‘tk’, ‘dt’, ‘n’, ‘v’, ‘nv’, ‘ch’, ‘L’, ‘du’, ‘ctrlnum’, ‘mtype’, ‘xtype’, ‘value’ はイベントの 属性値を表す定数として使用できます。 イベントが持っていない属性については、これらの定数の値は None になります (ただし、NoteEventに対する’du’については ‘L’と同じ値となります)。式の評価において TypeError 例外が 発生した場合は、式の値をFalseだとみなして処理を続けます。

  • bool値を返す関数 – イベントを引数として呼び出され、その戻り値が 条件の真偽になります。

• negate (bool, optional) – False(デフォルト)の場合、条件を満たすイベントからなるスコアを 出力します。Trueの場合、条件を満たさないイベント（つまり、デフォル トの場合に出力されないイベント）からなるスコアを出力します。

• globals (dict, optional) – conds が文字列のときに、その中に出現する大域変数の辞書を指定 します。 デフォルトでは、コンストラクタを呼ぶ時点での globals() の値に なっています。

• locals (dict, optional) – conds が文字列のときに、その中に出現する局所変数の辞書を指定 します。 デフォルトでは、コンストラクタを呼ぶ時点での locals() の値に なっています。

Examples

Filter(NoteEventClass, TempoEvent)

ノート関連イベント (NoteEvent、NoteOnEvent、および、NoteOffEvent) とテンポイベントを抜き出します。

Filter('ctrlnum == 7')

7番のコントロールチェンジイベントを抜き出します。

Filter(lambda ev: hasattr(ev, 'ctrlnum') and ev.ctrlnum == 7)

上の例と等価な操作を関数で記述した例です。

Filter('ctrlnum == C_PROG', negate=True)

プログラムチェンジイベントを取り除きます。 Filter('ctrlnum != C_PROG') あるいは Reject('ctrlnum == C_PROG') でも同じ意味になります。

Filter('n >= C4')

ピッチがC4以上のノート関連イベントおよびKeyPressureEventを抜き出し ます (n属性の無いイベントは TypeError例外を生じるため結果として 出力されません)。

Filter('n < C4', negate=True)

ピッチがC4未満のノート関連イベントおよびKeyPressureEventを取り除き ます（つまり、ピッチがC4以上のそれらのイベントと、n属性を持たない その他のイベントを抜き出します)。Reject('n < C4') とも 書けます。この例のように TypeError例外が生じるケースでは、 Filter('...') と Reject('not ...') は等価ではありません。

Filter('n >= C5 and L == L4')

ピッチがC5以上、かつ音価が4分音符と等しいNoteEventを抜き出します。

Filter('ch in (1,2,4)', MetaEvent)

MIDIチャネルが1,2,4のいずれかであるイベント、および すべてのメタイベントを抜き出します。

Filter('isinstance(ev, SysExEvent) and value[0] != 0xf0')

最初のバイトが 0xf0 でないシステムエクルシーブメッセージのイベント を抜き出します。

class Reject(*conds, globals=None, locals=None)

Bases: Filter

条件を満たさないイベントのみ含むスコアへ変換します。 Reject(…) は Filter(…, negate=True) と等価です。

class Cond(cond, effector, globals=None, locals=None)

Bases: Effector

条件を満たしたイベントにのみ指定されたエフェクタを適用します。 条件を満たさないイベントはそのまま出力されます。

出力において、エフェクタを適用したものとそうでない同時刻のイベントが 存在するときは、エフェクタを適用したイベントの方が必ず後になります。

コンストラクタ引数

Parameters:

• cond (class, str, or function) – 条件を Filter の conds 引数と 同じ形式（ただし１つの基本条件のみ）で指定します。

• effector (Effector) – 適用するエフェクタのオブジェクト。

• globals (dict, optional) – Filter の globals 引数と同じ意味です。

• locals (dict, optional) – Filter の locals 引数と同じ意味です。

Examples

Cond('n >= C5', ScaleVelocity(1.2))

ピッチが C5 以上 NoteEvent および NoteOnEvent に対して、 ベロシティを1.2倍します。

class Modify(operation, globals=None, locals=None)

Bases: EventEffector

各イベントに対して、operation で指定された文の列を実行し、それに従って 更新したイベントを出力します。これにより、Score.mapev() に代わる 簡易的なイベント更新の手段を提供します。

イベントは常にコピーされてから更新されます（コピーを避けたい場合は Score.mapev() を使用して下さい）。

コンストラクタ引数

Parameters:

• operation (str) – exec() によって評価可能な文字列を指定します。 文字列の中で、’ev’ はイベント自身を表す変数として使用できます。 また、’t’, ‘tk’, ‘dt’, ‘n’, ‘v’, ‘nv’, ‘ch’, ‘L’, ‘du’, ‘ctrlnum’, ‘mtype’, ‘xtype’, ‘value’ はイベントの属性値を表す変数として使用で き、それらを書き換えることによってイベントの属性値を変更できます。 ‘ev’ を通じて属性の追加・変更をすることは可能ですが、上に挙げた 変数に対応する属性についは、その変数の値の方が優先します。 文字列の評価中に TypeError 例外が発生した場合は、そのイベント に対する更新は行われません。

• globals (dict, optional) – operation 文字列中に出現する大域変数の辞書。 デフォルトでは、コンストラクタを呼ぶ時点での globals() の値に なっています。

• locals (dict, optional) – operation 文字列中に出現する局所変数の辞書。 デフォルトでは、コンストラクタを呼ぶ時点での locals() の値に なっています。

Examples

Modify('ch=3')

MIDIチャネル番号をすべて3に変更したものを出力します。ch 属性を 持たないイベントについては何も変更せずに出力します。

Modify('v*=0.8; nv=30')

ノート関連イベントについて、ベロシティを0.8倍し、ノートオフ ベロシティを30に設定して出力します。それ以外のイベントは何も変更 せずに出力します。

Modify('if tk==2: v*=1.1')

トラック番号が2である NoteEvent, NoteOnEvent について、 ベロシティを1.1倍して出力します。それ以外のイベントは何も変更 せずに出力します。

Modify('ev.voice=2')

すべてのイベントに対し、’voice’ という属性を無ければ追加し、 値を2に設定して出力します。

class Product(pattern, *, tail=None, scale=None, globals=None, locals=None)

Bases: Effector

入力スコア中の各音符をパターンとなるスコアで置き換えます。 これは、オクターブ演奏、ロール演奏、装飾音、トリル演奏など様々な用途に 応用できます。パターンは、MML文字列 (mml() を参照)、もしくは スコアを返す関数の形で与えます。

デフォルトの場合、出力される音符のピッチは、入力スコアでの音符のピッチに、 パターン中のピッチの C4 から音程を加えたものとなります。例えば、 mml('CD').Product('[CE]') は、元のそれぞれの音符を完全1度 と長3度からなる和音に置き換える意味になり、その結果 mml('[CE][DF#]') と等価なスコアになります。

出力中の各パターンの開始時刻は、元になる入力スコア中の音符の開始時刻と 常に同一です。また、全体の演奏長は変わりません。 各音符に対応するパターンの演奏期間がその音符の音価より長い場合は、 通常、その音価の長さで打ち切られます。ただし、パターンに演奏長 が 0 である EventList または Tracks を指定している場合は (例えば、 Product('{CDEF}&') のような場合) は、この打ち切りが行われません (その場合、そのパターンと次の音符に対するパターンとのオーバーラップを 許すことになります）。

このエフェクタは入力デバイスからの RealTimeStream に対して適用することも できます。

コンストラクタ引数

Parameters:

• pattern (str or function) – パターンのスコアを生成する MML 文字列、またはスコアを返す関数を を指定します。無限長のスコアであっても構いません。 この文字列や関数を評価するときのコンテキストは 入力スコア中の NoteEvent または NoteOnEvent によって各音符ごとに 設定され、それによって入力スコア中の音符のパラメータをパターンに 反映することが可能です。v、nv、L、tk、ch、dt 属性は（あれば） 元のイベントと同じ値に設定されます。元のイベントがNoteOnEventだった 場合、L属性は無限大に設定されます。一方 NoteEventだった場合、 dr 疑似属性が元の音符と同じになるように設定されます。 o属性は常に4に設定されます。

• tail (str or function, optional) – パターンの終了部分のスコアを生成する MML 文字列、またはスコアを 返す関数を指定します。tail によるスコアの演奏長の分だけ pattern によるスコアは短くなります。これは、 トリル演奏の最後に装飾音を挿入する場合などに利用できます。 tail によって生成されるスコアは無限長であってはなりません。 また、入力スコアに含まれるイベントが NoteOnEvent の場合は 使用できません。コンテキストは pattern と同様に設定されます。

• scale (Scale, optional) – この引数でスケールを指定した場合、そのスケール上のトーン番号 (Scale を参照) に基づいて出力される音符のピッチを決定 します。具体的には、出力される音符のトーン番号は、 入力スコアでの音符のトーン番号に、パターン中のピッチのトーン番号を 加えたものとなります。

• globals (dict, optional) – MML文字列を評価する際の大域変数の辞書を指定します。

• locals (dict, optional) – MML文字列を評価する際の局所変数の辞書を指定します。

Examples

Product("[C ^C]")

各音符に対して、１オクターブ上の音を付加します。

Product(lambda: note(C4) & note(C5))

上と等価の処理を関数を使って記述したものです。

Product("[[v*=0.9 CE]G]")

各音符を、それを根音とした長3和音へ変換します。最高音以外の音に 対してはベロシティを0.9倍しています。

Product("{CDEF}//", scale=Scale(C4))

各音符に対して、C major scale上の連続する4音を、元の1/4の音価 で演奏します。例えば、 mml("CDE").Product("{CDEF}//", scale=Scale(C4)) は mml("{CDEF DEFG EFGA}//") と等価なスコアを生成します。

Product("{L16 CDEFGAB^C}&")

各音符に対して、それを開始音とした1オクターブの長音階スケールを 16分音符で演奏します。元の音符の音価にかかわらず、常に最後まで スケールが演奏されます。(もしMML最後の ‘&’ がない場合は、 元の音符の音価に相当する長さに切り詰められます。）

Product("G(L32)F", scale=Scale(F4, 'minor'))

各音符に対して、F natural minor scale における1つ上の音の前打音を 付加します。後の音符の音価は、元の音符の音価より32音符の分だけ短く なります。

Product("L32 C@@")

各音符に対して、32分音符で同じピッチの音を繰り返す演奏 (いわゆるドラムロール演奏) を行います。

Product("L32 {CD}@@", tail="L=L8/5 CDC_BC")

各音符に対して、32分音符でその全音上の音と交互に繰り返す 演奏 (いわゆるトリル演奏) を行います。音符の終わりの部分には tail で指定した演奏が挿入されます。

class Apply(pattern, globals=None, locals=None)

Bases: Effector

入力スコアに対して、別のスコア（パターン）のリズムおよび表情付け情報を 適用します。ピッチは異なるが共通のリズムや表情付けを持ったフレーズが多く 出現するような曲の記述に特に有効です。

変換は次のように行われます。入力スコアの音符とパターンの音符との間で 照合が行われ、入力スコアの各音符について、それに対応するパターン中の音符の 情報が次のように適用されます。

• ピッチは入力スコアのものが使われ、パターンのものは無視されます。

• dtは入力スコアのものとパターンのものの和になります。

• vは、パターンのものに、入力スコアのものとコンテキストが持つ値との 差分を加えた値になります。

• t, Lを含むそれ以外の属性はパターンのものが使われます。

照合は、同時発音される音符をまとめたグループ（単音の場合を含めて以下では コードと呼ぶ）を単位として行われます。 コード内における各音符の照合は、出現順に行われます。入力スコアの方が コード構成音が少ない時は、パターンの最初の方の音が無視されます。 入力スコアの方がコード構成音が多い時は、パターンの最初のコード構成音が 重複して利用されます。

入力スコアの方がパターンより短い (コード数が少ない) 場合、パターンにおける 余ったコードは捨てられます。入力スコアの方がパターンよりコード数が 多い場合は、例外が送出されます。

入力スコア中に n属性が Noneである NoteEvent を含まれている場合、 これも１つの音符として照合の対象になりますが、出力はされません。

パターン中のノート以外のイベントはそのまま出力されます。一方、入力スコア中 の NoteEvent 以外のイベントは無視されます。NoteOnEvent および NoteOffEvent を含んだ入力スコアに対しては使用できません。

コンストラクタ引数

Parameters:

• pattern (Score or str) – パターンとなるスコアを指定します。文字列の場合は MMLだと 見なされます。無限長であっても構いません。

• globals (dict, optional) – MML文字列を評価する際の大域変数の辞書を指定します。

• locals (dict, optional) – MML文字列を評価する際の局所変数の辞書を指定します。

Examples

mml("CDEF`").Apply("{C!C`>C/C/}")

mml("C!D`>E/F`/") と等価なスコアを生成します。

mml("CDEF").Apply("{C.C/}@@")

付点のリズムに変換され、mml("C.D/E.F/") と等価なスコアを 生成します。

mml("[CE] [EG] [EGB]").Apply("C [C? C] [C? C]")

mml("[CE] [E? G] [E? G? B]") と等価なスコアを生成します。

class ToTracks(set_tk_by_ch=False, limit=2000000.0)

Bases: Effector

スコアをトラック番号 (tk属性の値) ごとに仕分けした構造に変換します。 変換されたスコアは Tracks オブジェクトであり、i番目のイベント リストにはトラック番号がiのイベントが格納されます (i>=0). 各トラックのイベントは時間順にソートされます。

コンストラクタ引数

Parameters:

• set_tk_by_ch (bool) – 仕分ける前に各イベントのtk属性にch属性の値をセット します。結果的に、MIDIチャネル番号で仕分けすることになります。 ch属性のないイベントのトラック番号は0になります。

• limit (ticks) – スコアの長さを制限します。 制限の詳細については、Score.stream() の同名の引数 の項目を見てください。

class Render(swap=False)

Bases: Effector

楽譜上の時間を演奏上の時間で置きかえたスコアに変換します。具体的には、 t属性にdt属性の値を加え、L属性に(あれば)du属性の値を設定します。 その後、swap指定がない限り、dt属性は0に変更され、du属性は削除されます。

スコアだけでなく、単独のイベントに対しても変換を適用することができます。

コンストラクタ引数

Parameters:

swap (bool, optional) – Trueの場合、楽譜上の時間と演奏上の時間を 入れ替えます。2回適用すると元へ戻ります。

class Tie

Bases: EventEffector

スコア中の NoteEvent に対して、タイの開始を表す属性を 付加します。

class EndTie

Bases: EventEffector

スコア中の NoteEvent に対して、タイの終了を表す属性を 付加します。タイの開始かつ終了となる音符に対しては、このエフェクタと Tie() エフェクタの両方を適用してください。

class ConnectTies(errhdr='')

Bases: Effector

スコア中のタイで結ばれた NoteEvent を統合して１つの NoteEvent に します。正しく結ばれるためには、前の NoteEvent の終了時刻 (t属性と L属性の値の和) と後の NoteEvent の開始時刻 (t属性値) が一致していなくては なりません。

コンストラクタ引数

Parameters:

errhdr (str, optional) – エラー、警告メッセージの先頭文字列

class Dump

Bases: EventEffector

class Voice(voice)

Bases: EventEffector

スコアに含まれる NoteEventClass に属するイベントに対して、 voice属性を追加します。voice属性は Score.music21() で利用されます。

コンストラクタ引数

Parameters:

voice (int) – voice属性の値

class Mark(mark)

Bases: EventEffector

スコアに含まれる NoteEventClass に属するイベントに対して、 mark属性の追加（すでにmark属性が存在すればそれへの値の追加) を行います。 mark属性は Score.music21() で利用されます。

コンストラクタ引数

Parameters:

mark (str or tuple of str) – mark属性として追加する文字列またはそのタプル

class PairNoteEvents(ref_links=False, errhdr='')

Bases: Effector

スコアに含まれる NoteOnEvent と NoteOffEvent を対にして、 NoteEvent へ変換します。このエフェクタ適用後は NoteOnEvent と NoteOffEvent を含まないことが保証されます。

NoteOnEventとNoteOffEventの対応づけは、tk属性、ch属性、n属性が すべて一致するものの間で行われますが、複数の可能性がある場合はFIFOの ルールに従った、すなわちより早い時刻のNoteOnEventが優先的にNoteOffEventと 組になるような対応づけが行われます。なお、異なる EventList あるいは EventStream にまたがった対応づけは行われません。

対応する NoteOnEvent が無い NoteOffEvent を含む場合は、警告とともに 削除されます。 対応する NoteOffEvent が無い NoteOnEvent を含む場合は、警告が出されると ともに、スコアの演奏長まで続く音符として NoteEvent が生成されます。

コンストラクタ引数

Parameters:

• ref_links (bool) – Trueにすると、生成された各NoteEventについて、その元となった NoteOnEventおよびNoteOffEventへの参照を、それぞれnoteonev, noteoffevという名の属性として追加します。

• errhdr (str, optional) – エラー、警告メッセージの先頭文字列

class UnpairNoteEvents(ref_links=False)

Bases: Effector

スコア中に含まれる NoteEvent を、NoteOnEvent と NoteOffEvent の 対に変換します。NoteOffEvent の時刻は、元の NoteEvent のt属性値に L属性値を加えたものになります。

コンストラクタ引数

Parameters:

ref_links (bool) – Trueにすると、生成された各NoteOnEventおよびNoteOffEventについて、 その元となったNoteEventへの参照を、noteevという名の属性として 追加します。

class RetriggerNotes

Bases: Effector

ノート衝突に対してリトリガー処理を施して衝突を回避します。 ノート衝突とは、同じトラック、同じMIDIチャネルの同じピッチに対して、 2つ以上の発音期間 (NoteEvent の t属性値から始まる L属性値の長さの期間 もしくは NoteOnEvent から NoteOffEvent までの期間）が重なる状況を 意味します。ノート衝突が起きた場合、シンセサイザーによっては発音時間が 期待されるものより短くなってしまうことがあります。 リトリガー処理では、先の音符の発音区間を適宜減らすことにより 衝突を回避します。

class Microtone(channels=4, base_channel=None, bender_range=2)

Bases: Effector

微分音 (すなわち、0でないcents属性をもつピッチの音符) が指定通りの 高さで発音されるように、MIDIピッチベンドイベントを挿入します。 同時に複数の発音がある場合は、各音に異なるチャネルを、与えられた MIDIチャネルの集合の中から自動的に割り当てます。割り当てに使うチャネルが 不足した場合は、警告を出力した上で、正しい高さでの発音を断念します。

入力スコアにおける微分音を取扱う対象の単一チャネルはベースチャネルと 呼ばれます。ベースチャネル以外に送られたイベントは、それが割り当てに 使うMIDIチャネルの集合に含まれている場合は例外を発生させ、そうでない 場合はそのまま出力されます。ベースチャネルに送られたCtrlEventは、 割り当てに使うすべてのチャネルに複製されて送られます。これに加えて、 そのCtrlEventがピッチベンドであった場合は、その値が微分音によって 生成される後続のピッチベンドの値に加算されます。

コンストラクタ引数

Parameters:

• channels (int or collection of int, optional) – 割り当てに使うチャネルの集合を、整数のコレクション (list, tuple, set 等)もしくは単一の整数で指定します。単一の整数の場合、 ベースチャネルから始まるその整数個のチャネル (つまり、ベース チャネルを b、この引数値を n としたとき range(b, b+n) に相当する チャネル) を割り当てに使用します。

• base_channel (int, optional) – ベースチャネルの番号を指定します。省略すると、現在のコンテキスト が持つ ch属性の値となります。

• bender_range (int, optional) – 使用するシンセサイザのピッチベンド範囲を半音数で指定します。 例えば、+-1オクターブなら 12 とします。

Examples

>>> mml('[C E|MT(-25) G]').Microtone()
EventList(duration=480, events=[
    CtrlEvent(t=0, ctrlnum=C_BEND, value=0, tk=1, ch=1),
    NoteEvent(t=0, n=C4, L=480, v=80, nv=None, tk=1, ch=1),
    CtrlEvent(t=0, ctrlnum=C_BEND, value=-1024, tk=1, ch=2),
    NoteEvent(t=0, n=64, L=480, v=80, nv=None, tk=1, ch=2),
    CtrlEvent(t=0, ctrlnum=C_BEND, value=0, tk=1, ch=3),
    NoteEvent(t=0, n=G4, L=480, v=80, nv=None, tk=1, ch=3),
    CtrlEvent(t=480, ctrlnum=C_BEND, value=0, tk=1, ch=2)])

上の例では C major の三和音のうち、E音について 25セントピッチを 下げています (MTエフェクタについては MT を参照)。 ベースチャネルは1, 割り当てに使うチャネルは1から4までに設定されています。

class MT(cents)

Bases: EventEffector

すべての音符イベントに対し、そのピッチに cents の値を加えます。 変更されたピッチに従って演奏するためには、このエフェクタの後に Microtone エフェクタを適用する必要があります。

コンストラクタ引数

Parameters:

cents (int or float) – セント(半音の1/100)単位でのピッチ増分

class Temperament(temperament=(0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0), stretch=0)

Bases: EventEffector

すべての音符イベントに対し、そのMIDIノート番号に応じた cents の値をピッチに加えることによって、12等分平均律とは異なる音律を シミュレートします。変更されたピッチに従って演奏するためには、この エフェクタに加えて Microtone エフェクタを適用する必要があります。

コンストラクタ引数

Parameters:

• temperament (sequence of int or float, optional) – 12要素からなるセント値のシーケンスを指定します。各要素は 該当するクロマ値 (pitch.chroma()) における平均律 からのずれを表します。

• stretch (int or float, optional) – A4音からの音程について、それを stretch 倍した分だけ音程を 広げます。例えば、stretch が 0.01 の場合、E5音については、 E5とA4の音程が7半音から7.07半音に拡大されることを意味し、 そのため7セントがピッチに加えられます。

Examples

下の例は、”file.mid” をハ長調の純正律を用いて演奏します。

>>> readsmf('file.mid').Temperament(
        [0, 0, 3.91, 0, -13.686, -1.955,
         0, 1.955, 0, -15.641, 0, -11.731]).Microtone(8).play()