INSTALL

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