pytakt.mml module

このモジュールには、カスタマイズ可能な拡張 MML (Music Macro Language) に 関連した関数が定義されています。

mml(text, globals=None, locals=None, _safe_mode=False) → Score

引数 text の拡張 MML (Music Macro Language) 記述に従ったスコアを 返します。MML は文字列によって音楽フレーズを簡潔に表現します。

Parameters:

• text (str) – MML文字列

• globals (dict, optional) – MML文字列中のPython変数名やPython関数名に対する大域変数辞書。 デフォルトでは、mml関数を呼ぶ時点での globals() の値になって います。

• locals (dict, optional) – MML文字列中のPython変数名やPython関数名に対する局所変数辞書。 デフォルトでは、mml関数を呼ぶ時点での locals() の値になって います。

Examples

>>> mml('eefg gfed ccde e.d/d*').play()
>>> mml('L8 G~rD G~rD GDGB ^D~rr ^C~rA ^C~rA ^CAF#A D~rr').play()
>>> mml("L8 o=5 key=-3 $tempo(60) _B G~~~ F G F~~ E~  _B G~ {C Db C _B% C}/5 ^C~").play()
>>> mml("L8 {dr=30 E(L16) E(L=L8+L16) E(v+=5) E(dr=50 dt=10)} G/`> G/!? G/ G/!? G3*").show(True)
>>> mml('[ceg]@@').play()  # 停止するには Ctrl-C
>>> rh = newcontext(tk=1)
>>> lh = newcontext(tk=2)
>>> mml("""
... $tempo(160)
... $prog(gm.Harpsichord)
... [
...    $rh: { ^D {G A B ^C}/  ^D G G }
...    $lh: { [{_G* _A} _B*. D*.] _B*. }
... ]
... [
...    $rh: { ^E ^{C D E F#}/  ^G G G }
...    $lh: { C*. _B*. }
... ]
... """).play()
>>> mml('ch=10 [{$BD() r $SD() r} $HH()@4]').play()

本MMLの言語仕様

本MMLの記述全体は、コマンド の列から成ります。各コマンドは、 基本コマンド か 制御コマンド のいずれかです。 基本コマンド は、その前に任意個の 前置修飾子、およびその後に 任意個の 後置修飾子 を置くことができます。たとえば、CD#4^E は3つの 基本コマンドから成り、C, D, E がそれぞれ基本コマンド、# と 4 は D に対する後置修飾子、^ は E に対する前置修飾子です。

空白文字(スペース、タブ、改行)は、識別子、数値、2文字以上からなる 演算子の途中、およびフラットを表す b の前を除き、自由に挿入できます。 セミコロン (‘;’) から行の終わりまではコメントとみなされ、空白文字と同等に 扱われます。

基本コマンド一覧

デフォルト設定で使用可能な基本コマンドは以下の通りです。

A ～ G または a ～ g

note() 関数によって、指定された音名の音符を生成します。 B は C の長七度上の音を表します。 小文字も使用でき、大文字と意味は同じです。ただし、b は 英大文字の直後に置かれた場合はフラット (2個置かれた場合はダブル フラット) の意味になります (例えば、gab の b は１つの音符ですが、 G Ab の b はフラットの意味になります)。 オクターブ番号はコンテキストのo属性から取得されます。

r または R

rest() 関数によって休符を生成します。

{ 0個以上のコマンドの列 }

コピーされた別のコンテキストを用いて中括弧内のコマンドを実行し、 その結果のスコア群を逐次的に結合します。 これは一時的にコンテキスト属性値を変更する場合に使用でき、たとえば L4 C {L8 D E} F において、D, E音は8分音符になりますが、F音は 4分音符に戻ります。

[ 0個以上のコマンドの列 ]

コピーされた別のコンテキストを用いて角括弧内のコマンドを実行し、 その結果のスコア群を同時演奏するように併合します。 たとえば、[CEG] のように和音を表したり、 [C* {FE}] のように複数の声部を表現するために使用できます。

$<Python変数名>:{ 0個以上のコマンドの列 }

<Python変数名>にコンテキストが格納されている変数の名前を指定すると、 そのコンテキストのコピーを用いて中括弧内のコマンドを実行し、 その結果のスコア群を逐次的に結合します。 <Python変数名> はドット(‘.’)を含んでいても構いません。

$(<Python式>) および $<Python関数名>(<Python引数>, … )

ともに $ に続く文字列を Pythonのコードとみなして評価し、その値を スコアとして挿入します (ただし、Noneの場合は挿入されません)。 <Python関数名> はドット(‘.’)を含んでいても構いません。 なお、次のモジュールで定義されている名前は、MML文字列の中では パッケージ名やモジュール名を指定せずに使えます: pytakt.pitch, pytakt.sc, pytakt.constants, pytakt.gm.drums, pytakt.scale, pytakt.effector。また、単純式で利用できるコンテキスト属性はPython コードの中で変数として参照可能です。

制御コマンド一覧

L<整数>, L<整数>DOT, L<整数>DOTDOT

音価を設定します。<整数>は 1, 2, 4, 8, 16, 32, 64, 128 のいずれかです。 このコマンドの実行により、コンテキストのL属性の値が pytakt.constants モジュールに定義されている同名の定数の値に なります。たとえば、L8 は以降の音符・休符を8分音符の長さに設定 します。

<コンテキスト属性名> = <単純式>

コンテキスト属性（単純式で利用できるものに限る）の値を変更します (例: v=100)。単純式については下を見てください。

<コンテキスト属性名> op= <単純式>

<コンテキスト属性名> = <コンテキスト属性名> op <単純式> と 等価です。opは単純式の中で使える演算子のいずれかです。

$<Python変数名> = <単純式>

<Python変数名>を、<単純式>の値を持つ変数として定義します。定義された 変数は MML 文字列の中でのみで有効です。

$<Python関数名>(<Python仮引数リスト>) = <単純式>

<単純式>の値を戻り値とする関数を、<Python関数名>の名前で定義します。 <Python仮引数リスト>において、= に続けられたデフォルト値を含める ことは可能ですが、* や ** は使用できません。定義された関数は MML 文字列の中でのみで有効です。

$if(<Python式1>) { コマンド列1 } [ $elif(<Python式2>) { コマンド列2 } … ] [ $else { コマンド列N } ]

<Python式1> が真であればコマンド列1を実行し、そうでなくて <Python式2> が真であればコマンド列2を実行し（<Python式3>以降があればそれも同様)、 どのPython式も偽であればコマンド列Nを実行します。$elif および $else 以降は省略可能です。

$for(<Python変数名> in <Python式>) { コマンド列 }

<Python式> で指定されたイテラブルから順に値を取り出して <Python変数名> に代入しながら、各値について１回ずつコマンド列を実行します。

単純式

<単純式> は、整数、浮動小数点数、音価定数(L4など)、コンテキスト属性名、 " または ' で囲まれた文字列、括弧で囲んだ単純式、$( と ) で囲まれたPythonの式、$ に続くPythonの関数呼び出し、${ と } で囲まれたコマンドの列、またはこれらを演算子(+, -, *, /, //, % のいずれか) で結合したものです。使用できるコンテキスト属性 名は、dt, tk, ch, v, nv, L, duoffset, du, durate, dr, o, key のみです。 ${ と } で囲まれたコマンドの列は、コピーされた別のコンテキストを 用いてコマンド列を実行し、その結果のスコア群を逐次的に結合したものが値と なります。

前置修飾子

デフォルト設定で使用可能な前置修飾子は以下の通りです。 修飾子によるコンテキスト属性値の変更は、修飾されるコマンドにのみ有効で、 後続のコマンドの実行には影響を与えません。

^

オクターブ・アップ。コンテキストのo属性の値を1増やします。

_

オクターブ・ダウン。コンテキストのo属性の値を1減らします。

後置修飾子

デフォルト設定で使用可能な後置修飾子は以下の通りです。 修飾子によるコンテキスト属性値の変更は、修飾されるコマンドにのみ有効で、 後続のコマンドの実行には影響を与えません。

<整数>

数値によってオクターブを指定します (4が中央ハを含むオクターブ)。

+ または #

シャープ。ピッチを半音上げます。

-

フラット。ピッチを半音下げます。

%

ナチュラル。keyコンテキスト属性の値が0以外のときのみ有効で、シャープや フラットのないピッチへ戻します。

'

オクターブ・アップ。^ と同じ意味です。

,

オクターブ・ダウン。_ と同じ意味です。

*

音価を2倍にします。

/

音価を0.5倍にします。

/<整数>

音価を <整数> 分の1にします。連符の表現に使用できます。

.

付点。1つ置くと音価が1.5倍、2つ置くと1.75倍になります。

~

複数の（空を含む）音価指定を結合してその和をとります。たとえば、 *~/ は音価を2.5倍、~ は2倍、~~ は3倍、~.. は 2.75倍にすることを意味します。

`

ベロシティを 10 増やします。(v+=10) と等価です。

?

ベロシティを 10 減らします。(v-=10) と等価です。

!

drコンテキスト属性の値を 0.5倍します。(dr*=0.5) と等価です。 いわゆるスタッカートに相当します。

>

dtコンテキスト属性の値を 30ティック (64分音符相当) 増やして、 演奏タイミングを少し遅らせます。(dt+=30) と等価です。

<

dtコンテキスト属性の値を 30ティック (64分音符相当) 減らして、 演奏タイミングを少し早めます。(dt-=30) と等価です。

&

演奏長を 0 にして以降の演奏に重ねます。

@<整数>

<整数>回演奏を繰り返します。|Repeat(<整数>) と等価です。

@@

無限回演奏を繰り返します。|Repeat() と等価です。

( 0個以上のコマンドの列 )

修飾される基本コマンドが作成するコンテキストにおいて、 その基本コマンドを実行する前に、列に含まれる各コマンドを実行します。 主に、一時的にコンテキストを変更する目的に使われます。 例: C(v=30 dt+=10)

|<Python識別子>(<Python引数>, … )

エフェクタを適用します。 例: {CDE}|Transpose('M2')

safe_mml(text) → Score

セキュリティ面を考慮したバージョンの mml() です。これは、信頼でき ないソースから入手したMML文字列や対話的にユーザが入力したMML文字列を 評価するのに適しています。

safe_mmlでは、MML中で使用できる Python変数名やPython関数名を、下のものだけ に限定しています。

• pytakt.pitch, pytakt.sc, pytakt.constants, pytakt.gm.drums, pytakt.scale に登録されている名前

• pytakt.gm に登録されている名前 (gm.Piano1 のようにモジュール名をつけて 使用する必要があります)

• 一部の組み込み関数名 (abs, len など)

• 一部のエフェクタ名 (Transpose, Product など)

さらに、MML中のPython式において、’.’ 演算子、lambda式、*、** を 前置した式, 内包表記, プレフィックスつき文字列 (r’abc’ など), 3重クオート 文字列は使用できません（gm.Piano1 のように予め登録された名前に含まれる ‘.’ は演算子ではないため、使用できます)。

Parameters:

text (str) – MML文字列

mmlconfig(translate=('', ''), *, add_prefixes='', add_suffixes='', del_prefixes='', del_suffixes='', actions={}, octave_number_suffix=None, accent_amount=None, timeshift_amount=None, staccato_amount=None) → None

MMLに関する設定を行います。引数無しで呼ぶと、現在の設定を表示します。

この関数で変更できる設定は以下の4つです。

• 文字クラスの変更

  各文字(unicode文字)は次のどれかのクラスに属しています。

  1. 予約済み

     次の文字は予約されていて、クラスを変更したり機能を変更することが できません。

     L n ( ) [ ] { } = $ | & / \ : ; @ 数字 空白文字

  2. prefix文字

     前置修飾子となる文字です。

  3. suffix文字

     後置修飾子となる文字です。

  4. その他の文字

     基本コマンドとして使用できる文字です。

  予約済みの文字を除き、各文字のクラスを変更することができます。

• 文字に割り当てられている機能の変更

  予約済みでない文字は、その意味を変更することができます。

• “<整数>” 後置修飾子の意味の変更

  下の octave_number_suffix の項目を参照。

• パラメータ変化量の変更

  下の accent_amount, timeshift_amount, staccato_amount の項目を参照。

MML文字列の中でmmlconfigを呼び出して文字クラスの変更を行った場合、それが 有効になるのは、トップレベルの次のコマンドからです。

Parameters:

• translate ((str, str), optional) – 長さの等しい2つの文字列からなるタプルを指定し、 第1の文字列の各文字に対して、第2の文字列中の同位置にある文字の 機能 (’ ‘ なら空の機能) を割り当てます。文字を無効にしたいときには 第2の文字列で未定義の文字を指定します。

• add_prefixes (str, optional) – この引数に含まれている各文字のクラスを、”prefix文字” に変更します。

• add_suffixes (str, optional) – この引数に含まれている各文字のクラスを、”suffix文字” に変更します。

• del_prefixes (str, optional) – この引数に含まれている各文字のクラスを、”prefix文字” から “その他の文字” に変更します。

• del_suffixes (str, optional) – この引数に含まれている各文字のクラスを、”suffix文字” から “その他の文字” に変更します。

• actions (dict, optional) – キーが文字(1文字文字列)、値が関数(callable object)であるような dictオブジェクトを与えることで、各文字に対するアクション関数を 指定します。アクション関数の記述法についてはソースコードの MMLActionクラスを参考にして下さい。

• octave_number_suffix (bool, optional) – 後置演算子としての <整数> の意味を指定します。 True (default) ならばオクターブ番号を指定する意味、 Falseなら音価を全音符のその整数分の1に設定する意味になります。

• accent_amount (int or float, optional) – 標準設定で ` および ? に割り当てられている機能に ついて、ベロシティの増減の大きさを指定します。(デフォルト値: 10)

• timeshift_amount (ticks, optional) – 標準設定で < および > に割り当てられている機能について、 dtコンテキスト属性値の増減の大きさを指定します。(デフォルト値: 30)

• staccato_amount (float or int, optional) – 標準設定で ! に割り当てられている機能について、 drコンテキスト属性値に乗じる係数を指定します。(デフォルト値: 0.5)

Examples

下の設定は、日本語仮名文字による音符、休符、および音価を伸ばす操作の記述を可能にします (このような表記はストトン表記として知られています):

mmlconfig(translate=("ドレミファソラシッどれみふぁそらしっー",
          "CDEF GABrCDEF GABr~"),
          add_suffixes="ァぁー")

下の設定は、^ と _ の文字を、以降のオクターブを上下する基本コマンドとして再定義します:

mmlconfig(del_prefixes="^_",
          actions={'^': MMLAction.cmd_octaveup,
                   '_': MMLAction.cmd_octavedown})

readmml(filename, safe_mode=True) → Score

ファイルからMML文字列を読み、それに従ったスコアを返します。 ファイルに $mmlconfig が含まれている場合、その設定はファイル内だけで 有効になります。

Parameters:

• filename (str) – ファイル名

• safe_mode (bool) – Trueの場合 safe_mml()、Falseの場合 mml() がMMLの 評価に使われます。

exception MMLError(message, source=None)

Bases: Exception