otoco コマンドツール コマンド仕様

書式

otoco [オプション...] MMLファイル名 [出力ファイル名]

記述例

# music (または music.mml か music.txt) を読み込み、music.mid を出力する。
otoco music
# music.txt (または music.txt.mml か music.txt.txt) を読み込み、smf.mid を出力する。
otoco music.txt smf.mid
# MIDI 音源のターゲットを SC-88 として、SMF と Postscript 形式の楽譜を出力する。
otoco -d vender=Roland module=SC-88 standard=GS -sp music

解説

MMLファイル名

• ファイル検索のシーケンスは以下の通り。
  1. 指定された名前をそのままファイル名として認識し、そのファイルがあれば開く。
  2. 指定された名前の末尾に拡張子 ".mml" を加えたファイル名のファイルがあれば開く (小文字".mml"→大文字".MML"→大文字から始まる小文字".Mml"の順で試す)。
  3. 指定された名前の末尾に拡張子 ".txt" を加えたファイル名のファイルがあれば開く (小文字".txt"→大文字".TXT"→大文字から始まる小文字".Txt"の順で試す)。
• 相対指定の場合は、カレントディレクトリからの相対位置として扱う。それ以外のディレクトリは検索しない。
• 指定されたファイルが見つからなかった場合は、コマンドエラーとなる。また、存在するが開けなかった場合は、解析エラーとなる。

出力ファイル名

• 省略された場合、MMLファイル名として指定された名前 (但し、有効な拡張子 ".mml" および ".txt" は除く) の末尾に、出力ファイルの種類に応じた拡張子 (SMF であれば ".mid"、PostScript 形式の楽譜であれば ".ps" など) を加えたファイル名で出力を行う。
• 指定されたファイル名の拡張子が、出力ファイルの種類として登録されているものであれば、環境変数やオプションによる指定に関係なく、その種類のファイルのみを指定された名前で出力する。それ以外の場合は、オプションによる指定に応じて適宜拡張子を付加し、ファイルを出力する。
• 出力ファイル名にディレクトリの指定を含み、かつ該当するディレクトリが存在しない場合は、コマンドエラーとなる。

オプション

指定できるオプションは、以下の通り。

• -s
• --smf
• --nosmf

SMF ファイルの出力を行う/行わない。-s および --smf を指定した場合は、出力を行う。--nosmf を指定した場合は、出力は行わない。何も指定しない場合、環境変数 OTOCO_OUTPUT_SMF による指定に従う。それも無い場合は、出力する。

• -p
• --ps
• --nops

PostScript 形式による楽譜ファイルの出力を行う/行わない。-p および --ps を指定した場合は、出力を行う。--nops を指定した場合は、出力は行わない。何も指定しない場合、環境変数 OTOCO_OUTPUT_PS による指定に従う。それも無い場合は、出力しない。

• -d 変数1=値1 [-d 変数2=値2 [...]]
• --define 変数1=値1 [--define 変数2=値2 [...]]

制御命令 #if 等で使用する条件分起用の変数を定義する。ここで定義した変数は、MML ファイル中での制御命令 #set によって再定義されることは無い (すなわち、#set による定義よりも優先される)。

• -i パス1 [-i パス2 [...]]
• --include パス1 [--include パス2 [...]]

制御命令 #include によって読み込まれる追加 MML ファイルの検索先ディレクトリを指定する。相対パスの場合は、カレントディレクトリからのパスとして扱う。

• -b 小節数[:拍数:分数]
• --begin 小節数[:拍数:分数]
• --begin-marker マーカー

MML の変換処理を開始する位置を指定する。何も指定しない場合は、最初から変換が行なわれる。 但し、楽譜以外の出力において、#score begin が記述されていれば、それより前の部分は変換を行う。この部分の変換も抑制したい場合は、--cut-before-score オプションを使用する。

• -e 小節数[:拍数:分数]
• --end 小節数[:拍数:分数]
• --end-marker マーカー

MML の変換処理を終了する位置を指定する。何も指定しない場合は、最後まで変換が行なわれる。 但し、楽譜以外の出力において、#score end が記述されていれば、それより後の部分は変換を行う。この部分の変換も抑制したい場合は、--cut-after-score オプションを使用する。

• --cut-before-score

#score begin の記述があれば、それより前の部分の変換が行われなくなる。

• --cut-after-score

#score end の記述があれば、それより後の部分の変換が行われなくなる。

• -w 警告レベル
• --warning 警告レベル

警告レベルを 0~5 で指定する。1を指定すると全ての警告を表示し、5を指定すると重要な警告以外は表示されなくなる。0を指定した場合は、警告は一切表示されない。指定しない場合は 4が指定されているものとして動作する。

• -h
• -?
• --help

コマンドヘルプを表示する。

• -v
• --version

バージョン情報を表示する。

振る舞いに関する仕様

• 出力しようとするファイルが既に存在する場合、警告等は表示せずに、上書き保存する。上書き保存に失敗した場合は、出力エラーとなる。
• 正常終了した場合は常に終了コード 0 を返す。エラーが発生した場合は、以下の終了コードを返す。
  • 1 ... オプションエラー
  • 2 ... MML 解析エラー
  • 3 ... 出力エラー
• エラーが発生すると、標準エラー出力にエラーの内容を出力する。出力される内容は以下の通り。
  • オプションエラーの場合、どのオプションが処理できなかったのかを説明するエラーメッセージ。
  • MML 解析エラーの場合、エラーが発生した MML ファイルとその行数、および内容に関する説明。
  • 出力エラーの場合は、何が起こったのかを伝えるエラーメッセージ。
  • otoco プログラムのどこでエラーが発生したのかを伝える情報 (ファイル名、行数)
  • オプションエラーの場合、コマンドヘルプ。
• 警告が発生した場合、その都度標準エラー出力にエラーの内容を出力する。出力される内容は以下の通り。
  • 警告が発生した MML ファイルとその行数。
  • 警告のレベル (1:宗教的なアドバイス、2:無意味な指定、3:無効な値、4:文法間違い、5:無効な制御行)。
  • 警告の内容。

警告レベルについて

警告レベルは以下の通りに分類される。

• 1: 宗教的なアドバイス

メンテナンス性やアクセシビリティに考慮してアドバイスが示されるべきケース。 システムエクスクルーシブに渡されるバイト列が 1 バイトごとに空白で区切られておらず見難い、などといったもの。

• 2: 無意味な指定

同じパラメタに対する同じ値の指定の繰り返しであるために、指定の意味が無いようなもの。SMF への変換時には、(それがトラックごとに固有の指定であっても)無視される。

• 3: 無効な値

引数の値が指定できる範囲外であるなどして、無視されるか動作が意図どおりにはならないかもしれないケース。

• 4: 文法間違い

演奏命令の文法が間違っている、存在しない演奏命令である、存在しないトラック名である、等。

• 5: 無効な制御行

制御命令の書式が間違っている、存在しない制御命令である、等。但し、一部のエラーになるケースを除く。