INSTALL.ja

======================================================================
	TiMidity++インストールガイド

					出雲正尚
					<iz@onicos.co.jp>
					2004年03月01日
					バージョン2.13.0以降
======================================================================

この文章では，TiMidity++をUNIXライクな環境にインストールするための方法
について説明しています。

Windows 95/98/Me/NT/2000/XP/2003上では，Cygwinを使うことで，この文章の
手順に従いtimidity.exeを生成できます。Windows環境の人は，まずCygwin(ま
たはmingw)を入手してください。

今日のMacintoshはユーザーランドがFreeBSDなので，この文章の通りにやれば
上手くいくはずです。古いMacintosh("Classic")でのインストールの仕方は，
この文章には説明されていません。

======================================================================
基本的な手順
======================================================================

TiMidity++は，GNU autotoolsを使っています。したがって，一番簡単なインス
トール方法は:

1. ソースコードのあるディレクトリに“cd”して“./configure”と入力して
   パッケージを設定します(この作業はしばらく時間がかかります)。System V
   の古いバージョンを使っている場合は“/bin/sh configure”としないとい
   けないかもしれません。
2. “make”とタイプするとコンパイルが始まります(GNU makeが必要です。
   GNU makeが“gmake”という名前でインストールされている環境では，代わ
   りに“gmake”とタイプしてください)。
3. makeが終わったら“make install”とタイプして，所定の場所にTiMidity++
   をインストールしてください。

======================================================================
より詳細な説明
======================================================================

インストールの完全な手順は

1. configreを実行する
2. 必要があればcommon.makefile，Makefile，timidity.hを編集する
3. コンパイル
4. インストール
5. 音源ファイルの設定

です。以下，順に説明します。以下の説明では“%”をプロンプトとして使って
いますので注意してください。

======================================================================
configure
======================================================================

まず，以下のコマンドを実行してみてください。

% /bin/sh configure --help

configureのオプションがたくさん表示されたと思います。このうち，--helpや
--prefix=PREFIXのような多くのオプションは，典型的な他のプロジェクトにお
けるものと同じ意味/用法です。一方，TiMidity++独自のオプションもあります。

--enable-debug
  デバッグフラグが有効になります

--without-x
  TiMidity++は，標準状態でXを利用するようになっていますので，Xのライブ
  ラリとリンクしたくない場合は，明示的に--without-xを指定しないといけま
  せん。

--enable-audio[=audio_list]
  オーディオ出力の形式を指定します。--enable-audio=noの場合は，TiMidity++
  はただのMIDI-to-WAVE変換機となります。

  このオプションに指定できる値は，

  * default: 自動判別
  * oss: OSS /dev/dsp
  * sun: SunOS /dev/audio
  * hpux: hp-ux /dev/audio
  * irix: IRIX audio library
  * mme: OSF/1 MME
  * sb_dsp: BSD/OS 2.0 /dev/sb_dsp
  * w32: Windows MMS
  * darwin: darwin(Mac OS X)のCoreAudio frameowrk
  * alsa: ALSA pcm device
  * alib: hp-ux network audio (Alib)
  * nas: NAS
  * portaudio: PortAudio
  * jack: JACK
  * arts: aRts
  * esd: EsounD
  * vorbis: ogg vorbis
  * gogo: mp3午後のこーだ(Windows only)

  です。

--enable-interface[=interface_list]
--enable-dynamic[=interface_list]
  使用するインタフェースを指定します。--enable-dynamicを使うと，インタ
  フェースは動的リンクモジュールとしてコンパイルされます(生成されるバイ
  ナリのサイズが小さくなります)。

  このオプションに指定できる値は，

  * ncurses: ncursesインタフェース
  * slang: S-Langインタフェース
  * motif: Motifインタフェース(Lestiffでも動きます)
  * tcltk: Tcl/Tkインタフェース
  * emacs: Emacsフロントエンド(M-x timidity)
  * vt100: vt100インタフェース
  * xaw: X Athena Widgetインタフェース
  * xskin: X skinインタフェース
  * gtk: GTK+インタフェース
  * w32gui: Windows GUI版としてコンパイル
  * winsyn: TiMidity++ Windowsシンセサイザサーバとしてコンパイル
  * alsaseq: ALSAシーケンサインタフェース

  です。ここで，

  --enable-interface=INTERFACE1,INTERFACE2,...
  という指定が
  --enable-INTERFACE1=yes --enable-INTERFACE2=yes ...
  という指定と同じ意味で，同様に
  --enable-dynamic=INTERFACE1,INTERFACE2,...
  という指定が
  --enable-INTERFACE1=dynamic --enable-INTERFACE2=dynamic ...
  という指定と同じ意味だということに注意してください。

--enable-network
  ネットワークサポートを有効にします。TiMidity++にURLを渡すと，ネットワ
  ーク越しのMIDIファイルを演奏することが可能になります。

--enable-spectrogram
  生成したPCM音声のスペクトログラムを，リアルタイム表示できるようにする
  オプションです。

--enable-wrd
  WRD対応を有効にします。

* configureと環境変数

MIDIファイルによっては，レンダリングにとってもCPUパワーが必要な場合があ
ります。適切な最適化方法が指定できれば，そのようなMIDIファイルもスムー
ズに演奏できるようになるかもしれません。

configureは，以下の環境変数を(設定されていれば)認識します。

CC
  Cコンパイラ。例“/usr/bin/gcc”
CFLAGS
  ${CC}に渡すフラグ。例“-O2 -pipe”
LDFLAGS
  リンカに渡すフラグ。例“-L/usr/gnu/lib”
CPPFLAGS
  プリプロセッサに渡すフラグ。例“-traditional-cpp”

コンパイラには，たくさんの最適化フラグがあると思います。たとえば
ultrasparc/gccの場合だと:

% env CFLAGS='-O3 -Wall -mv8 -funroll-all-loops -fomit-frame-pointer \
	-mcpu=ultrasparc' /bin/sh configure [configure-options]...

などと指定することで(多分)高速なバイナリが生成されると思います。

======================================================================
ファイルの編集
======================================================================

このままの状態ではコンパイルが通らないときがあります。そんなときには，
手動でcommon.makefileやMakefile，あるいはtimidity.hを編集するとうまくい
く場合があります。

* timidity.hに記載されているパラメータ

TiMidity++には，バイナリにハードコードされているオプションがいくつかあ
ります。これらのパラメータは，timidity.hに#defineで記述されています。

以下の記述で「コマンドラインから変更できますから」と書いてあるものもあ
ります。それらのオプションはコマンドラインで指定されなかった場合のデフ
ォルト値を指定しています。いずれにしろ，これらをわざわざ変更する必要性
は薄いと思いますので，放っておいてもいいんじゃないでしょうか。 -- mput

** CONFIG_FILE

必要に応じてCONFIG_FILEを定義してください。デフォルトでは

#define CONFIG_FILE DEFAULT_PATH "/timidity.cfg"

となっています。DEFAULT_PATHは，Makefileで定義したTIMID_DIRと同じです。
もし，どうしても他の場所に置きたいなら

#define CONFIG_FILE "/etc/timidity.cfg"

のように定義します。

** DECOMPRESSOR_LIST

ファイル展開コマンドの設定です。この設定はWindowsでは無視してください。
デフォルトでは

#define DECOMPRESSOR_LIST { \
		".gz", "gunzip -c %s", \
		".bz2", "bunzip2 -c %s", \
		".Z", "zcat %s", \
		".zip", "unzip -p %s", \
		".lha", "lha -pq %s", \
		".lzh", "lha -pq %s", \
		".shn", "shorten -x %s -", \
		0 }

となっています。オリジナルのTiMidityでは，上記で指定した拡張子に対応し
たコマンドを利用して，ファイルを展開して読み込むことができます。一方，
TiMidity++では幾つかの形式については，TiMidityが自前で展開してファイル
を読み込みます。しかし，すべての形式はサポートしていないので，サポート
されていない形式には，上記で指定したコマンドが利用されます。

** PATCH_CONVERTERS

パッチファイルの変換コマンドに関する設定です。この設定はWindowsでは無視
してください。デフォルトでは

#define PATCH_CONVERTERS { \
		".wav", "wav2pat %s", \
		0 }

となっています。

** PATCH_EXT_LIST

GUS/patchファイルの拡張子の指定です。ここに指定した拡張子は*.cfg内のフ
ァイル名で省略できます。デフォルトでは

#define PATCH_EXT_LIST { \
		".pat", \
		".shn", ".pat.shn", \
		".gz", ".pat.gz", \
		".bz2", ".pat.bz2", \
		0 }

となっています。

** DEFAULT_PROGRAM

デフォルトのinstrumentの設定です。

#define DEFAULT_PROGRAM 0

となっています。MIDIのProgram Changeイベントがない場合に，この値が利用
されます。通常，0番はピアノです。

このオプションはコマンドラインから指定できるので，このままでよいでしょ
う。

** DEFAULT_DRUMCHANNELS

ドラムチャンネルの設定です。デフォルトでは

#define DEFAULT_DRUMCHANNELS {10, -1}

となっています。これは，コマンドラインオプションで変更できるので，この
ままで良いと思います。変更する場合は，ドラムチャンネルのリストを複数指
定し，-1で終了します。もし，10と16チャンネルをデフォルトでドラムチャン
ネルにしたいならば，

#define DEFAULT_DRUMCHANNELS {10, 16, -1}

とします。

** FLOAT_T

浮動小数点数の型の指定です。

 ・ typedef double FLOAT_T;
 ・ typedef float FLOAT_T;

のどちらかを選んでください。double精度のFPUを搭載しているマシンでは，
floatよりdoubleの方が高速です。sparcやSGI/IPなどは，doubleの方が高速で
す。最近のFPUは，たいていの場合はdouble精度の方が高速です。ただし，一部
のマシンやパソコンでは，floatの方が高速になるかも知れません。

** (MAX|MIN)_OUTPUT_RATE

再生サンプルレートの下限，上限の設定です。デフォルトでは

#define MIN_OUTPUT_RATE 4000
#define MAX_OUTPUT_RATE 65000

となっています。これは特に変更する必要はないでしょう。

** DEFAULT_AMPLIFICATION

マスターボリュームのデフォルト値の設定です。デフォルトでは

#define DEFAULT_AMPLIFICATION 70

となっています。この値はパーセント値で指定します。デフォルトの70%はわり
と良い値なので，これも特に変更しなくても良いでしょう。コマンドラインオ
プションで変更することもできます。

** DEFAULT_RATE

デフォルトの再生サンプルレートの設定です。デフォルトでは

#define DEFAULT_RATE 44100

となっています。この値は，コンパイラオプション-DDEFAULT_RATE=<rate>のよ
うに指定しても良いです。パワーのあるマシンで，DAT品質並みのGUS/patchを
使って快適な音を聞きたい場合は

#define DEFAULT_RATE 48000

とするのも良いです。

** DEFAULT_VOICES

同時発音数に関する設定です。デフォルトでは

#define DEFAULT_VOICES 256

となっています。DEFAULT_VOICESは起動時の同時発音数で，この値は-pオプシ
ョンを用いて1からメモリが許されるまでの数を設定することができます。-in
インタフェースでは，実行時に変化させることもできます。パワーのあるマシ
ンなら，デフォルトの同時発音数を増やして

#define DEFAULT_VOICES 512

のようにするのも良いです。しかしながら，経験上128重音あれば，大抵のMIDI
ファイルが快適に聞けます。また，256重音を越えるMIDIファイルはほとんど存
在しなく(極希にありますが)，256重音以上を処理するにはかなり高性能なCPU
(例えばR10000とか)であっても負荷が高いです。そのため，DEFAULT_VOICESは
極端に増やしてもあまり意味がないので，256くらいを上限にするのが妥当です。

** AUDIO_BUFFER_BITS

内部バッファの大きさの設定です。デフォルトでは

#define AUDIO_BUFFER_BITS 12

となっています。ここは特に変更することはないでしょう。

** CONTROLS_PER_SECOND

TiMidityでは，エンベロープの音量計算を1サンプルごとに計算するのではなく，
ある程度まとめて計算します。この値を大きくすればするほど細かく計算する
ため，音の質はよくなりますが，逆にCPU負荷が高くなります。デフォルトでは

#define CONTROLS_PER_SECOND 1000

となっています。コマンドラインオプションで変更もできるので，このままに
しときましょう。

** DEFAULT_RESAMPLATION

リサンプル時における補完の設定です。デフォルトでは，

#define DEFAULT_RESAMPLATION resample_gauss

となっています。これを定義すると，リサンプル時にガウス風補完を行い，音
質が向上します。その反面，CPU負荷が上がります。非力なマシンでない限り定
義しておきましょう。補完アルゴリズムとして，下記のものが使用可能です(処
理の軽い順)。

#define DEFAULT_RESAMPLATION resample_none
#define DEFAULT_RESAMPLATION resample_linear
#define DEFAULT_RESAMPLATION resample_lagrange
#define DEFAULT_RESAMPLATION resample_cspline
#define DEFAULT_RESAMPLATION resample_gauss
#define DEFAULT_RESAMPLATION resample_newton

補完アルゴリズムは，コマンドラインオプションで変更もできます。ユーザに
よって変更できなくするには

#define FIXED_RESAMPLATION

のコメントアウトを外してください。

** USE_DSP_EFFECT

DSPエフェクトに関する設定です。デフォルトでは

#define USE_DSP_EFFECT

となっています。コーラス，ディレイ，EQおよびインサーションエフェクトの
性能を向上させるもので，これは特に変更する必要はないでしょう。

** LOOKUP_HACK

デフォルトでは

/* #define LOOKUP_HACK */
/* #define LOOKUP_INTERPOLATION */

と未定義になっています。このマクロを定義すると，多少高速に動作します。
ただし，16ビットのサンプルを8ビットで計算するので音質が劣化します。非力
なマシンで演奏処理が追い付かないなら定義してみましょう。

** SMOOTH_MIXING

ミキシングの段階で，急激な音量変化がおこると，ポッピング・ノイズが発生
することがあります。これを指定しておくとポッピング・ノイズの軽減に効果
があります。デフォルトは

#define SMOOTH_MIXING

で有効です。コメントアウトすると若干高速になります。

** FAST_DECAY

エンベロープの変化速度を設定します。デフォルトでは

/* #define FAST_DECAY */

と未定義になっています。これを定義するとエンベロープステージを2倍速く進
めるようになります。結果として，高速化につながるのですが，その反面，音
の長さが短くなり，迫力に欠けてきます。この設定はコマンドラインからon/
offできるので，これは未定義のままで良いでしょう。

** FRACTION_BITS

TiMidityでは，音の音程変換に浮動小数点数を用いずに，32ビット固定小数点
数を用いて計算しています。デフォルトでは

#define FRACTION_BITS 12

となっており，これはこのままで良いでしょう。

** ADJUST_SAMPLE_VOLUMES

自動GUS/patch音量調節の設定です。デフォルトでは

#define ADJUST_SAMPLE_VOLUMES

と定義されています。これを定義しておくと，GUS/patchの音量を自動的に調節
して同じ音の大きさにします。もし，小さい音のGUS/patchは小さいままに，大
きい音のGUS/patchは大きいままにしたいなら未定義にしてください。正確にチ
ューニングされているGUS/patchセットのみを用いるなら未定義でも良いです。
しかし，他の様々なGUS/patchを利用する場合に，音量が不揃いになってしまう
ので，このマクロは定義しておく方が良いでしょう。

** DENGEROUS_RENICE

UNIX系システムでevilモードを有効にする設定です。デフォルトでは

/* #define DANGEROUS_RENICE -15 */

と未定義になっています。setuid rootのTiMidityで，プロセスのプライオリテ
ィを上げて実行したい場合は，このマクロを定義してください。UNIXのみで有
効です。このマクロを定義してTiMidityをインストールした後は，

# chown root /usr/local/bin/timidity
# chmod u+s /usr/local/bin/timidity

のようにします。

注意：DANGEROUS_RENICEを定義していない場合は，setuidプログラムにしない
      でください。

** MAX_DIE_TIME

モノラルパートの音程がA→Bと移るとき，Aの音を瞬時に消してしまうとクリッ
クノイズが出てしまいます。このパラメータで，瞬時に消すべき音にクリック
ノイズが出ないようにコントロールします。デフォルトでは

#define MAX_DIE_TIME 20

となっています。あまり小さな数にすると，クリックノが顕著になります。こ
の値はこのままで良いでしょう。

** LOOKUP_SINE

正弦関数テーブル参照に関する設定です。デフォルトでは

#define LOOKUP_SINE

となっています。幾つかの環境(特に数値演算プロセッサを持たないPCなど)で
は，正弦関数値をテーブル参照した方が，その都度計算するよりかなり高速に
なります。

今日のPCは，CPUの演算速度がどんどん速くなる一方で，メインメモリのアクセ
ス時間はさして高速化されていません(容量は増えたけど)。テーブルを引くと
いう行為は当然メインメモリへのアクセスを生じるので，ここでかなりのキャ
ッシュミスヒット，ひいてはパイプラインストールが発生します。現在の段階
ですと，テーブル参照をするのとしないのでは，ほとんど速度的な差が生じて
いません(少なくとも私の環境では -- mput)。数年後には，毎回計算した方が
高速になると予想されます。

** PRECALC_LOOPS

リサンプリング最適化に関する設定です。デフォルトでは

#define PRECALC_LOOPS

となっています。が，この最適化は環境によって効いたり効かなかったりしま
すので，場合によっては未定義にした方が高速かもしれません。

** USE_LDEXP

ldexp()を使うかどうかの設定です。デフォルトでは

/* #define USE_LDEXP */

と未定義になっています。浮動小数点数の掛け算が，ldexp()を用いた方が速い
マシンの場合は定義してください。どっちにしろ大差ないとは思いますが。

** DEFAULT_CACHE_DATA_SIZE

キャッシュの大きさです。デフォルトでは

#define DEFAULT_CACHE_DATA_SIZE (2*1024*1024)

と2Mになっています。TiMidity++では，MIDIイベントを演奏前にスキャンして，
一部の音をあらかじめリサンプリングします。そのリサンプリングのバッファ
の大きさを指定してください。大きくするほど高速になりますが，その分メモ
リを浪費します。2M以上に増やしても，あまり顕著に高速化しなく，またコマ
ンドラインオプションからも変更できるので，ここはデフォルトのままで良い
でしょう。

* ネットワーク関連設定群

TiMidity++では，URLを用いてネットワークを介してファイルにアクセスするこ
とが可能になっています(configure で --enable-network を指定した場合)。
以下のマクロを設定してください。

** MAIL_DOMAIN

メールアドレスのドメイン名を指定してください。例えば，メールアドレスが
iz@onicos.co.jpだとすると，

#define MAIL_DOMAIN "@onicos.co.jp"

と記述します。

** MAIL_NAME

UNIXでは未定義にしてください。Windowsではメール名を定義してください。例
えば，メールアドレスがiz@onicos.co.jpだとすると，

#define MAIL_NAME "iz"

と記述します。

** TMPDIR

一時ファイルの置場所を指定します。デフォルトでは

/* #define TMPDIR "/var/tmp" */

と未定義になっています。UNIXでは，このマクロを未定義にしておくとTMPDIR
環境変数で定義されているディレクトリに一時ファイルを作成します。TMPDIR
マクロもTMPDIR環境変数もどちらとも未定義の場合は，/tmpに一時ファイルが
作成されます。Windowsでは，TMPDIR環境変数は無視されますので，TMPDIRマク
ロを定義してください。

** GS_DRUMPART

GSのドラムパートの認識に関する設定です。

#define GS_DRUMPART

と定義すれば，GSのエクスクルーシッブメッセージからドラムパートを認識し
ます。

/* #define GS_DRUMPART */

と未定義にすればこの機能は無効になります。

* 日本語処理関連

日本語処理のためのオプションがいくつかあります。

** JAPANESE

日本語環境では

#define JAPANESE

と定義してください。日本語環境でない場合は，

/* #define JAPANESE */

とコメントアウトしてください。

** OUTPUT_TEXT_CODE

出力コードを指定します。以下の文字列が有効です。

AUTO
  LANG環境変数から自動的に決定
ASCII
  非印字文字をピリオドに変換
NOCNV
  無変換モード
1251
  windows-1251からkoi8-rに変換
EUC
  eucJPで出力
JIS
  JISで出力
SJIS
  shift-JISで出力

UNIX上の日本語環境では，上記すべて有効です。Windows日本語環境では，
"ASCII"，"NOCNV"，"SJIS" のどれかを指定してください。日本語環境でない場
合は，"ASCII"，"NOCNV"のどちらかを指定してください。

この設定はコマンドラインからも可能です。

** MODULATION_WHEEL_ALLOW
** PORTAMENTO_ALLOW
** NRPN_VIBRATO_ALLOW
** REVERB_CONTROL_ALLOW
** FREEVERB_CONTROL_ALLOW
** CHORUS_CONTROL_ALLOW
** SURROUND_CHORUS_ALLOW
** GM_CHANNEL_PRESSURE_ALLOW
** VOICE_CHAMBERLIN_LPF_ALLOW
** VOICE_MOOG_LPF_ALLOW
** MODULATION_ENVELOPE_ALLOW
** ALWAYS_TRACE_TEXT_META_EVENT
** OVERLAP_VOICE_ALLOW
** TEMPER_CONTROL_ALLOW

MIDIの制御に関する設定です。デフォルトは

#define MODULATION_WHEEL_ALLOW
#define PORTAMENTO_ALLOW
#define NRPN_VIBRATO_ALLOW
/* #define REVERB_CONTROL_ALLOW */
#define FREEVERB_CONTROL_ALLOW
#define CHORUS_CONTROL_ALLOW
/* #define SURROUND_CHORUS_ALLOW */
/* #define GM_CHANNEL_PRESSURE_ALLOW */
#define VOICE_CHAMBERLIN_LPF_ALLOW
/* #define VOICE_MOOG_LPF_ALLOW */
/* #define MODULATION_ENVELOPE_ALLOW */
/* #define ALWAYS_TRACE_TEXT_META_EVENT */
#define OVERLAP_VOICE_ALLOW
#define TEMPER_CONTROL_ALLOW

となっています。これらは，コマンドラインオプションで変更することができ
ますので，このままで良いと思います。

======================================================================
make
======================================================================

コンパイルは単に“make”とタイプするだけです。GNU makeが“make”以外の
名前で導入されている環境では，そちらを使ってください。

======================================================================
インストール
======================================================================

“make install”でインストールされます。また，以下のターゲットが指定で
きます。

install.bin
  実行ファイルだけインストール
install.tk
  Tcl/Tkインタフェースだけインストール
install.el
  Emacsインタフェースだけインストール
install.man
  manページだけインストール
install
  全部インストール

インストールの際には-nオプションを渡して，何が起こるか確認してからの方
がいいと思います。

% make -n install

======================================================================
音源データを探す
======================================================================

TiMidity++は，単体では音を鳴らすことができません。必ず音源データが必要
になります。音源データとしては，GUS/patchかSoundFont(か両方)が使えます。
なので，まずこれらのファイルを入手して，設定ファイルに指定する必要があ
ります。TiMidity++の設定ファイルは，デフォルトでは
/usr/local/share/timidity/timidity.cfg
(WindowsではC:\WINDOWS\TIMIDITY.CFG)にあります。

音源ファイルは，インターネット上にたくさん存在しています。一部は以下の
URLからたどることができるでしょう。

* http://www.onicos.com/staff/iz/timidity/link.html#gus
* http://www.onicos.com/staff/iz/timidity/dist/cfg/ (Some sample *.cfg's)
* http://www.i.h.kyoto-u.ac.jp/~shom/timidity/ (10M and 4M patches)
* ftp://ftp.cdrom.com/pub/gus/sound/patches/files/ (GUS site)