INSTALL

   1 ======================================================================
   2         TiMidity++ Installation guide
   3
   4                                         Masanao Izumo
   5                                         <iz@onicos.co.jp>
   6                                         Mar.01.2004
   7                                         version 2.13.0 or later
   8 ======================================================================
   9
  10 This document describes how to install TiMidity++ for your UNIX-like
  11 machine.
  12
  13 You can configure and make timidity.exe on the Cygwin environment of
  14 Windows 95/98/Me/NT/2000/XP/2003.  If you are in Windows, install
  15 Cygwin (or mingw) if you do not have them.
  16
  17 Today's Macintosh has FreeBSD userland, so things described here would
  18 fly.  Methods for older Macintosh ("Classic") are not described here.
  19
  20 ======================================================================
  21 Basic Installation
  22 ======================================================================
  23
  24 TiMidity++ uses GNU autotools to build.  So the simplest way to
  25 compile this package is:
  26
  27 1. "cd" to the directory containing TiMidity++'s source code and type
  28    "./configure" to configure the package for your system.  If you are
  29    using csh on an old version of System V, you might need to type
  30    "/bin/sh configure" instead to prevent csh from trying to execute
  31    configure itself.  Running configure takes a while.  While running,
  32    it prints some messages telling which features it is checking for.
  33 2. Type "make" to compile the package.
  34    NOTE: this make method requires GNU make.  So if your system has it
  35          as gamke, type "gmake" instead.
  36 3. Type "make install" to install the programs and any data files and
  37    documentation.
  38
  39 ======================================================================
  40 More complecated way
  41 ======================================================================
  42
  43 The full installation process is:
  44
  45 1. configre
  46 2. edit common.makefile, Makefile, timidity.h if necessery
  47 3. make
  48 4. installation
  49 5. set up voice data
  50
  51 Each processes are explained in following sections.  Note that % is
  52 the shell prompt.
  53
  54 ======================================================================
  55 Configure
  56 ======================================================================
  57
  58 First, execute the following command:
  59
  60 % /bin/sh configure --help
  61
  62 Many options of configure will be displayed.  Most of them, such as
  63 --help, --prefix=PREFIX, and so on are the regular ones.  They exisits
  64 on most package that uses autoconf and you do not have to worry about
  65 their behavior.
  66
  67 There also exists some options that is typical to TiMidity++.  Main of
  68 these are the following:
  69
  70 --enable-debug
  71   Enables debug.  Things will be compiled with debugging methods/
  72   informations.
  73
  74 --without-x
  75   TiMidity++ uses X by default.  So you must specify this option to
  76   prevent linker from linking X libraries.
  77
  78 --enable-audio[=audio_list]
  79   Enables TiMidity++ to play MIDI files.  If --enable-audio=no,
  80   TiMidity++ acts as a MIDI-to-WAVE converter.
  81
  82   You can specify one or more audio-device listed below.
  83
  84   * default: Automatically select audio device.
  85   * oss: OSS /dev/dsp
  86   * sun: SunOS /dev/audio
  87   * hpux: hp-ux /dev/audio
  88   * irix: IRIX audio library
  89   * mme: OSF/1 MME
  90   * sb_dsp: BSD/OS 2.0 /dev/sb_dsp
  91   * w32: Windows MMS
  92   * darwin: darwin(Mac OS X)'s CoreAudio frameowrk
  93   * alsa: ALSA pcm device
  94   * alib: hp-ux network audio (Alib)
  95   * nas: NAS
  96   * portaudio: PortAudio
  97   * jack: JACK
  98   * arts: aRts
  99   * esd: EsounD
 100   * vorbis: ogg vorbis
 101   * gogo: mp3 Gogo-No-Coder (Windows only)
 102
 103 --enable-interface[=interface_list]
 104 --enable-dynamic[=interface_list]
 105   Specify which interface to use.  If you use --enable-dynamic instead
 106   of --enable-interface, the interfaces specified will be linked
 107   dynamically and the binary size would become a bit smaller.
 108
 109   You can select one or more interfaces listed below.
 110
 111   * ncurses: ncurses interface.
 112   * slang: S-Lang interface.
 113   * motif: Motif interface.  Motif interface also works under Lestiff.
 114   * tcltk: Tcl/Tk interface.
 115   * emacs: Emacs front-end.  Type M-x timidity to invoke.
 116   * vt100: The full-screen interface using vt100 terminal control codes.
 117   * xaw: X Athena Widget interface.
 118   * xskin: X skin interface.
 119   * gtk: GTK+ interface.
 120   * w32gui: Build as Windows GUI binary.
 121   * winsyn: Build as TiMidity++ Windows Synthesizer server.
 122   * alsaseq: Build as ALSA sequencer client.
 123
 124   Note that
 125   --enable-interface=INTERFACE1,INTERFACE2,...
 126   equals as
 127   --enable-INTERFACE1=yes --enable-INTERFACE2=yes ...
 128   and for the same way,
 129   --enable-dynamic=INTERFACE1,INTERFACE2,...
 130   equals as
 131   --enable-INTERFACE1=dynamic --enable-INTERFACE2=dynamic ...
 132
 133 --enable-network
 134   Enables network support.  This will allow TiMidity++ to open a MIDI
 135   file via network.  You can specify the location of MIDI files by
 136   http://foo.com.tw/bar/baz.mid - like format.
 137
 138 --enable-spectrogram
 139   With this option specified, TiMidity++ can open a window on X and
 140   show sound-spectrogram there.
 141
 142 --enable-wrd
 143   WRD is a Japanese local lyric-contents format.  This option enables
 144   WRD interface.
 145
 146 * Environment variables and flags to pass to configure
 147
 148 Some MIDI files eat too much CPU power.  If you choose correct
 149 optimizing method, TiMidity++ can play such MIDI files smoothly.
 150
 151 You can tell configure which optimizing method to use by following
 152 environmental variables:
 153
 154 CC
 155   the C compiler command e.g. "/usr/bin/gcc"
 156
 157 CFLAGS
 158   flags to pass to ${CC} e.g. "-O2 -pipe"
 159
 160 LDFLAGS
 161   flags to pass to linker e.g. "-L/usr/gnu/lib"
 162
 163 CPPFLAGS
 164   flags to pass to preprocessor e.g. "-traditional-cpp"
 165
 166 Your compiler may have many optimization flags.  For example, in case
 167 of ultrasparc/gcc, you can specify:
 168
 169 % env CFLAGS='-O3 -Wall -mv8 -funroll-all-loops -fomit-frame-pointer \
 170         -mcpu=ultrasparc' /bin/sh configure [configure-options]...
 171
 172 and the binary will (hopefully) run faster.
 173
 174 ======================================================================
 175 Edit some files
 176 ======================================================================
 177
 178 If make fails, or if you want to change some parameters, edit
 179 common.makefile, Makefile, or timidity.h manually.
 180
 181 * Parameters in timidity.h
 182
 183 There are some options that are hard-coded into timidity binary.  They
 184 are # define-ed in timidity.h.  You have to change things there if you
 185 want to change these flags.
 186
 187 ** CONFIG_FILE
 188
 189 Edit CONFIG_FILE to your convenience.  By default,
 190
 191 #define CONFIG_FILE DEFAULT_PATH "/timidity.cfg"
 192
 193 are recommended.  DEFAULT_PATH is the same as TIMID_DIR in Makefile.
 194
 195 If you want to place it to another path, specify as the following:
 196
 197 #define CONFIG_FILE "/etc/timidity.cfg"
 198
 199 ** DECOMPRESSOR_LIST
 200
 201 The file extractor (please ignore in Windows).  By default:
 202
 203 #define DECOMPRESSOR_LIST { \
 204                 ".gz", "gunzip -c %s", \
 205                 ".bz2", "bunzip2 -c %s", \
 206                 ".Z", "zcat %s", \
 207                 ".zip", "unzip -p %s", \
 208                 ".lha", "lha -pq %s", \
 209                 ".lzh", "lha -pq %s", \
 210                 ".shn", "shorten -x %s -", \
 211                 0 }
 212
 213 TiMidity++ can handle some of archive format directly.  But other
 214 format will use this extractor.
 215
 216 ** PATCH_CONVERTERS
 217
 218 Configuration of of patch file converter (please ignore in Windows).
 219 By default:
 220
 221 #define PATCH_CONVERTERS { \
 222                 ".wav", "wav2pat %s", \
 223                 0 }
 224
 225 ** PATCH_EXT_LIST
 226
 227 Configuration of extensions of GUS/patch file.  If specified in this
 228 configuration, the extension can omit in all *.cfg.  By default:
 229
 230 #define PATCH_EXT_LIST { \
 231                 ".pat", \
 232                 ".shn", ".pat.shn", \
 233                 ".gz", ".pat.gz", \
 234                 ".bz2", ".pat.bz2", \
 235                 0 }
 236
 237 ** DEFAULT_PROGRAM
 238
 239 Configuration of default instrument.  By default:
 240
 241 #define DEFAULT_PROGRAM 0
 242
 243 If no Program Change event, this program name are adopted.  Usually 0
 244 is Piano.
 245
 246 ** DEFAULT_DRUMCHANNELS
 247
 248 Configuration of drum channel.  By default:
 249
 250 #define DEFAULT_DRUMCHANNELS {10, -1}
 251
 252 Numbers are the list of drum channels, and -1 is the terminator.  For
 253 example, if you wish to default drum channel be 10 and 16,
 254
 255 #define DEFAULT_DRUMCHANNELS {10, 16, -1}
 256
 257 This channel can change in command line option.
 258
 259 ** FLOAT_T
 260
 261 Type of floating point number.  Choose one of these:
 262
 263 * typedef double FLOAT_T;
 264 * typedef float FLOAT_T;
 265
 266 Many machine which has FPU results faster operations with double than
 267 that with float.  But some machine results contrary.
 268
 269 ** (MAX|MIN)_OUTPUT_RATE
 270
 271 Minimum/maximum range of playing sample rate.  By default:
 272
 273 #define MIN_OUTPUT_RATE 4000
 274 #define MAX_OUTPUT_RATE 65000
 275
 276 ** DEFAULT_AMPLIFICATION
 277
 278 Default value of master volume.  By default:
 279
 280 #define DEFAULT_AMPLIFICATION 70
 281
 282 This number is the percentage of max volume.  This default value will
 283 be nice in any occasions.  This number can specify in command line
 284 option (-A).
 285
 286 ** DEFAULT_RATE
 287
 288 Default sampling rate.  By default:
 289
 290 #define DEFAULT_RATE 44100
 291
 292 If you have much CPU power, DAT quality GUS/patch and want to listen
 293 funny sound,
 294
 295 #define DEFAULT_RATE 48000
 296
 297 is good solution.
 298
 299 ** DEFAULT_VOICES
 300
 301 Configuration of default polyphony numbers.  By default:
 302
 303 #define DEFAULT_VOICES 256
 304
 305 DEFAULT_VOICE is the polyphony number in boot-time.  This value is
 306 configurable by the command line option (-p) from 1 to until memory is
 307 allowed.  If your machine has much CPU power,
 308
 309 #define DEFAULT_VOICES 512
 310
 311 enables good harmony.
 312
 313 ** AUDIO_BUFFER_BITS
 314
 315 Size of internal buffer.  By default:
 316
 317 #define AUDIO_BUFFER_BITS 12
 318
 319 I guess this values no need to change.
 320
 321 ** CONTROLS_PER_SECOND
 322
 323 TiMidity++ do not calculate every envelope changes, but calculate some
 324 samples at one time.  Small controls yields better quality sound, but
 325 also eat much CPU time.  By default:
 326
 327 #define CONTROLS_PER_SECOND 1000
 328
 329 This can be changed from command line.  Leave as it is.
 330
 331 ** DEFAULT_RESAMPLATION
 332
 333 Type of interpolation engine.  By default:
 334
 335 #define DEFAULT_RESAMPLATION resample_gauss
 336
 337 This definition cause TiMidity++ to Gauss-like interpolation in re-
 338 sampling, and the quality of sound would be nice.  But it eats CPU
 339 powers.  I recommend define it if your machine has much power.  Other
 340 choices are (sorted by their speed):
 341
 342 #define DEFAULT_RESAMPLATION resample_none
 343 #define DEFAULT_RESAMPLATION resample_linear
 344 #define DEFAULT_RESAMPLATION resample_lagrange
 345 #define DEFAULT_RESAMPLATION resample_cspline
 346 #define DEFAULT_RESAMPLATION resample_gauss
 347 #define DEFAULT_RESAMPLATION resample_newton
 348
 349 Interpolation methods are changeable from the command line.  If you
 350 want to prevent users from doing so, uncomment next line and define as
 351 this:
 352
 353 #define FIXED_RESAMPLATION
 354
 355 ** USE_DSP_EFFECT
 356
 357 Configuration of USE_DSP_EFFECT to refine chorus, delay, EQ and
 358 insertion effect.  Default enabled.
 359
 360 ** LOOKUP_HACK
 361
 362 Configuration of LOOKUP_HACK.  By default, this features are undefined
 363 like this:
 364
 365 /* #define LOOKUP_HACK */
 366 /* #define LOOKUP_INTERPOLATION */
 367
 368 This option saves a little CPU power, but sound quality would decrease
 369 noticeably.  If your machine suffers from lack of CPU power, enable
 370 it.
 371
 372 ** SMOOTH_MIXING
 373
 374 Defining this greatly reduces popping due to large volume/pan changes.
 375 This is definitely worth the slight increase in CPU usage.
 376
 377 ** FAST_DECAY
 378
 379 Configuration of FAST_DECAY.  By default:
 380
 381 /* #define FAST_DECAY */
 382
 383 This option makes envelopes twice as fast and saves CPU power.  But
 384 since the release time of voices is shorten, the sound would be poor.
 385 This feature is controllable in command line option.
 386
 387 ** FRACTION_BITS
 388
 389 TiMidity++ uses fixed-point calculation.  Its default is
 390
 391 #define FRACTION_BITS 12
 392
 393 and you don't have to change this value.
 394
 395 ** ADJUST_SAMPLE_VOLUMES
 396
 397 Configuration of adjusting amplitude of GUS/patch.  By default:
 398
 399 #define ADJUST_SAMPLE_VOLUMES
 400
 401 This option makes TiMidity to adjust amplitudes of each GUS/patch to
 402 same volume.
 403
 404 ** DENGEROUS_RENICE
 405
 406 By default this feature is disabled:
 407
 408 /* #define DANGEROUS_RENICE -15 */
 409
 410 If you want to increase process priority of TiMidity++ by using setuid
 411 root enable this option.  This option is only available in UNIX.  Once
 412 you enabled this option, you should install timidity with the follow-
 413 ing procedure:
 414
 415 # chown root /usr/local/bin/timidity
 416 # chmod u+s /usr/local/bin/timidity
 417
 418 Note: You should not set setuid to timidity if DANGEROUS_RENICE isn't
 419       enabled.
 420
 421 ** MAX_DIE_TIME
 422
 423 If this value is too small, click noise would be come.  Default is:
 424
 425 #define MAX_DIE_TIME 20
 426
 427 and I recommend this value leave to this.
 428
 429 ** LOOKUP_SINE
 430
 431 #define LOOKUP_SINE
 432
 433 On some machines (especially PCs without math coprocessors), looking
 434 up sine values in a table will be significantly faster than computing
 435 them on the fly.  I recommend define it.
 436
 437 ** PRECALC_LOOPS
 438
 439 Configuration of optimizing re-sampling.  By default:
 440
 441 #define PRECALC_LOOPS
 442
 443 These may not in fact be faster on your particular machine and
 444 compiler.
 445
 446 ** USE_LDEXP
 447
 448 Configuration of use of ldexp().  By default this feature is disabled:
 449
 450 /* #define USE_LDEXP */
 451
 452 If your machine can multiply floating point number with ldexp() faster
 453 than other method, enable this option.
 454
 455 ** DEFAULT_CACHE_DATA_SIZE
 456
 457 Size of pre-re-sampling cache.  By default:
 458
 459 #define DEFAULT_CACHE_DATA_SIZE (2*1024*1024)
 460
 461 This can be changed from command line, so you don't have to change
 462 here.
 463
 464 * Configurations about network
 465
 466 TiMidity++ can access any files via networks with URL.  This feature
 467 are configurable in Makefile.  If you have enabled this feature in
 468 Makefile (configure --enable-network), configure the following macros:
 469
 470 ** MAIL_DOMAIN
 471
 472 specifies domain name of your name address.  If your name address is
 473 "iz@onicos.co.jp" set the macro:
 474
 475 #define MAIL_DOMAIN "@onicos.co.jp"
 476
 477 ** MAIL_NAME
 478
 479 specifies mail name of yours if in Windows.  In UNIX, uncomment it.
 480 For example, your name address is "iz@onicos.co.jp" set the macro:
 481
 482 #define MAIL_NAME "iz"
 483
 484 ** TMPDIR
 485
 486 Configuration of temporary directory.  By default, this option is
 487 disabled:
 488
 489 /* #define TMPDIR "/var/tmp" */
 490
 491 In UNIX, if this option is disabled TiMidity++ creates temporary files
 492 in the path specified by the environment variable TMPDIR.  If environ-
 493 ment variable TMPDIR also isn't defined, TiMidity++ creates temporary
 494 files in /tmp.  In Windows, TMPDIR variable are ignored.  So you
 495 should specify the temporary path with this macro.
 496
 497 ** GS_DRUMPART
 498
 499 Recognizing GS drum part by GS exclusive message.
 500
 501 #define GS_DRUMPART
 502
 503 enables to recognize GS exclusive message to set drum part.
 504
 505 /* #define GS_DRUMPART */
 506
 507 disables this feature.
 508
 509 * Japanese-text-handling related options
 510
 511 There are some options for Japanese handling.
 512
 513 ** JAPANESE
 514
 515 If your system is in Japanese environment, define
 516
 517 #define JAPANESE
 518
 519 otherwise comment it out like
 520
 521 /* #define JAPANESE */
 522
 523 ** OUTPUT_TEXT_CODE
 524
 525 specifies output text code (in Japanese environment).  You should
 526 specify appropriate code name to OUTPUT_TEXT_CODE macro.  The follow-
 527 ing strings are available:
 528
 529 AUTO
 530   Auto conversion by `LANG' environment variable (UNIX only)
 531 ASCII
 532   Convert unreadable characters to '.' (0x2e)
 533 NOCNV
 534   No conversion
 535 1251
 536   Convert from windows-1251 to koi8-r
 537 EUC
 538   eucJP
 539 JIS
 540   JIS
 541 SJIS
 542   shift-JIS
 543
 544 In Japanized UNIX system, all of above are available.  In Windows,
 545 "ASCII", "NOCNV", "SJIS" are available.  If your environment cannot
 546 handle Japanese, specify "ASCII" or "NOCNV" alternatively.
 547
 548 ** MODULATION_WHEEL_ALLOW
 549 ** PORTAMENTO_ALLOW
 550 ** NRPN_VIBRATO_ALLOW
 551 ** REVERB_CONTROL_ALLOW
 552 ** FREEVERB_CONTROL_ALLOW
 553 ** CHORUS_CONTROL_ALLOW
 554 ** SURROUND_CHORUS_ALLOW
 555 ** GM_CHANNEL_PRESSURE_ALLOW
 556 ** VOICE_CHAMBERLIN_LPF_ALLOW
 557 ** VOICE_MOOG_LPF_ALLOW
 558 ** MODULATION_ENVELOPE_ALLOW
 559 ** ALWAYS_TRACE_TEXT_META_EVENT
 560 ** OVERLAP_VOICE_ALLOW
 561 ** TEMPER_CONTROL_ALLOW
 562
 563 Controllers of MIDI actions.  By default:
 564
 565 #define MODULATION_WHEEL_ALLOW
 566 #define PORTAMENTO_ALLOW
 567 #define NRPN_VIBRATO_ALLOW
 568 /* #define REVERB_CONTROL_ALLOW */
 569 #define FREEVERB_CONTROL_ALLOW
 570 #define CHORUS_CONTROL_ALLOW
 571 /* #define SURROUND_CHORUS_ALLOW */
 572 /* #define GM_CHANNEL_PRESSURE_ALLOW */
 573 #define VOICE_CHAMBERLIN_LPF_ALLOW
 574 /* #define VOICE_MOOG_LPF_ALLOW */
 575 /* #define MODULATION_ENVELOPE_ALLOW */
 576 /* #define ALWAYS_TRACE_TEXT_META_EVENT */
 577 #define OVERLAP_VOICE_ALLOW
 578 #define TEMPER_CONTROL_ALLOW
 579
 580 These values are configurable in command line options.  So you may
 581 leave these in default value.
 582
 583 ======================================================================
 584 Make
 585 ======================================================================
 586
 587 Make section has nothing particular to write.  Just say "make"
 588
 589 ...Oops, almost forgot, TiMidity++'s Makefile needs GNU version of
 590 make.  If you do not have, get one first.  If you have one in a
 591 different name than "make", type its true name instead.
 592
 593 Installation
 594
 595 On UNIX and clones, you can type "make install" to install all files.
 596 Or you can select following targets:
 597
 598 install.bin
 599   installs executable filles
 600 install.tk
 601   installs Tcl/Tk interface
 602 install.el
 603   installs Emacs interface
 604 install.man
 605   installs man files
 606 install
 607   installs everything
 608
 609 I strongly recommend you to check the install destinations and files
 610 by setteing -n flag like
 611
 612 % make -n
 613
 614 ======================================================================
 615 Search for voice data
 616 ======================================================================
 617
 618 TiMidity++ uses Either GUS/patch, or SoundFont(, or both) as the voice
 619 data to play.  You must get a SoundFont or GUS/patch files, and make
 620 the configuration file.  You must make the configuration file (*.cfg).
 621 By default, timidity.cfg is /usr/local/share/timidity/timidity.cfg (or
 622 C:\WINDOWS\TIMIDITY.CFG on Windows).  And please check the following
 623 sites for many voice(patch) data:
 624
 625 * http://www.onicos.com/staff/iz/timidity/link.html#gus
 626 * http://www.onicos.com/staff/iz/timidity/dist/cfg/ (Some sample *.cfg's)
 627 * http://www.i.h.kyoto-u.ac.jp/~shom/timidity/ (10M and 4M patches)
 628 * ftp://ftp.cdrom.com/pub/gus/sound/patches/files/ (GUS site)
 629
 630 If you got funny voice archive, extract it to appropriate directory
 631 and configure *.cfg files with the name and path of these voice datas.