home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / apps / sound / players / maplay_t.z / maplay_t / INSTALL < prev    next >
Encoding:
Text File  |  1994-02-21  |  8.7 KB  |  178 lines
  1. /*
  2.  *  @(#) MPEG Audio Player maplay 1.1, last edit of this file: 2/21/94 18:10:24
  3.  *  @(#) Copyright (C) 1993, 1994 Tobias Bading (bading@cs.tu-berlin.de)
  4.  *  @(#) Berlin University of Technology
  5.  *
  6.  *  This program is free software; you can redistribute it and/or modify
  7.  *  it under the terms of the GNU General Public License as published by
  8.  *  the Free Software Foundation; either version 2 of the License, or
  9.  *  (at your option) any later version.
  10.  *
  11.  *  This program is distributed in the hope that it will be useful,
  12.  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  13.  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14.  *  GNU General Public License for more details.
  15.  *
  16.  *  You should have received a copy of the GNU General Public License
  17.  *  along with this program; if not, write to the Free Software
  18.  *  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  19.  */
  20.  
  21.  
  22. 0) Already tested platforms
  23.  
  24. The source code of this first release of maplay has been successfully tested
  25. with the following configurations:
  26.  
  27.  - SPARCstations with SunOS 4.1.3 or Solaris 2.2 (SunOS 5.2),
  28.    GNU C++ 2.5.1, GCC 2.5.4
  29.  - SGI with IRIX 4.0.5F, GNU C++ 2.5.1, GCC 2.5.4
  30.  - DECstation with ULTRIX 4.2, GNU C++ 2.5.1, GCC 2.5.8
  31.  
  32.  
  33. 1) Compiling the sources
  34.  
  35. First of all, take a look at the shell script configuration.sh. This script
  36. specifies values for the following environment variables:
  37.  
  38.   COMPILER        Put the name of your C++ compiler in here, "g++" for
  39.             example. You may specify the full path for your
  40.             compiler if the makefile doesn't find the compiler.
  41.   COMPILERFLAGS        This variable contains compiler flags for your
  42.             compiler. The -D flags together with #ifdefs in the
  43.             sources create the (hopefully) correct program for your
  44.             machine. You should not change these defines.
  45.             Other flags are for optimizations, like "-O2" for the
  46.             GNU g++, warning output control    etc.
  47.             What the define "-DDAMN_INTEL_BYTE_ORDER" does
  48.             should be obvious. It has to be defined on machines
  49.             which use the same byte    order as Intel processors.
  50.             (Intel byte order is lowest-byte-first)
  51.   INCLUDEDIRS        Put -I options for include file paths for your compiler
  52.             in here. The options are used by makedepend and make.
  53.   LIBRARIES        This variable should contain -l options needed by
  54.             your compiler for linking the program. The math
  55.             library is automatically included in the makefile.
  56.   AUDIO_INCLUDES    Audio include files, like audio.h or audioio.h, are
  57.             often placed in different directories on different
  58.             machines. Put the correct include directive for your
  59.             machine in here, for example "#include <sys/audio.h>".
  60.  
  61. The script configuration.sh contains a big switch statement, which tests the
  62. output of the command "uname -sr". This command should return the name and
  63. release of your operating system. You should enter this command in a shell
  64. first, to see if the output matches one of the already existing case entries.
  65. If so, you can modify the environment settings of this entry according to your
  66. needs. If your operating system and/or release hasn't been tested by now,
  67. you may enter your own entry according to the "uname -sr" output and put in
  68. your environment settings then (see 1.1: Compiling on new platforms).
  69. If your operating system does not know a uname command, you may write a shell
  70. script named "uname" containing
  71. "echo Your_System 1.23"
  72. and add an entry in the configuration.sh file. Or you can throw away the switch
  73. statement and leave only your environment settings in the script file.
  74.  
  75. After you have modified configuration.sh, you can run "make" to start
  76. compiling. I hope you will be rewarded with an executable after doing so.
  77. If the compilation process didn't make it till the end, you may try to
  78. fix the problem. If you need to adjust the environment settings mentioned
  79. above, you should execute "make clean" thereafter and then "make" again.
  80. If you don't get the problem fixed, you can send me an email (to
  81. bading@cs.tu-berlin.de) wherein you describe your problem. You can also sent
  82. me an email, if you successfully compiled the program, but needed to do
  83. some changes to the sources. These changes may also be useful for other users,
  84. so I can include your changes in the next release.
  85.  
  86. I am interested in any expiriences in compiling the program on other machines,
  87. because I can't test the program on any existing type of machine myself.
  88. Bug reports etc. should be send to bading@cs.tu-berlin.de, too.
  89.  
  90.  
  91. 1.1) Compiling on new platforms
  92.  
  93. Due to the fact that you are using a computer on which I have not tested the
  94. program by now, everthing can happen while compiling the program (who knows?).
  95. Besides, even if your computer has an audio device with CD quality, the program
  96. cannot use it, because each device has a different programming interface, like
  97. a library, or ioctls etc. and I wrote only routines for Indigos and SPARC 10
  98. by now. But if you have enough informations about your device and some knowledge
  99. in C/C++, who can write your own output class. If you are interested, take a
  100. look at chapter 1.2. If you want to use the program as a decoder only, you do
  101. not have to worry about this.
  102.  
  103. Ok, now here is what you should do to get the program running on your machine:
  104. a) Create a new entry in configuration.sh according to your "uname -sr" output.
  105. b) Set the environment variables COMPILER, INCLUDEDIRS and LIBRARIES to values
  106.    usefull on your machine.
  107. c) Leave AUDIO_INCLUDES empty. If you want to write your own output class, you
  108.    may need this variable.
  109. d) Include the following options into the variable COMPILERFLAGS:
  110.    - the best possible optimization option(s) for your compiler
  111.      (-O2 for example)
  112.    - -DDAMN_INTEL_BYTE_ORDER, if your machine uses Intel byte order.
  113.      If you do not know which byte order is used by your machine, try it
  114.      without this define first. If the program    creates warnings like
  115.      "WARNING: stream contains illegal ...", you should add the define, execute
  116.      "make clean ; make" and try it again.
  117.    Do not insert the defines "-DIRIX", "-DIndigo", "-DSolaris", "-DSunOS",
  118.    "-DSPARC", "-DULTRIX" or "-DDEC" into COMPILERFLAGS. But you can create
  119.    new define names for your machine.
  120.  
  121. I hope you get a working executable after modifying configuration.sh and
  122. running make. If that is not the case, you have two options:
  123. 1. Try to fix the problem yourself with new #ifdefs in the sources.
  124. 2. Send me an email describing your problems.
  125.  
  126.  
  127. 1.2) Writing a new output class
  128.  
  129. First of all, I have to remind you of the computational effort the program
  130. needs in this first version. Currently mono streams need a half Indigo or
  131. SPARC 10 for realtime playback. Stereo stream need the whole machine.
  132. So it might be possible that you are not able to play any streams even
  133. if you have written a new output class for your device, because your computer
  134. (or the program ;-) is too slow for realtime decoding. You should know the
  135. power of your machine or ask someone who knows it before you start writing
  136. a new output class.
  137.  
  138. Ok, you want to write a new output class?
  139. Then take a look at the file obuffer.h first. The Class Obuffer is an
  140. abstract base class for all audio output classes. Currently implemented
  141. derived classes are:
  142. - class ShortObuffer for raw PCM output to a filedescriptor
  143. - class IndigoObuffer for audio playback on Silicon Graphics Indigo machines
  144. - class SparcObuffer for audio playback on Sun SPARC 10 machines with the
  145.   dbri device
  146.  
  147. To access your audio device, the program needs a new class derived from
  148. Obuffer specifically for this device. The new class has to implement the
  149. following methods:
  150. - a constructor
  151.   The constructor has configure the audio device. It should set the
  152.   number of channels (mono or stereo) and the sample frequency (32, 44.1 or
  153.   48 kHz) according to the mode of the audio stream. These informations should
  154.   be included in the parameters of the constructor. The sample format is
  155.   always 16 bit signed PCM.
  156. - void append (uint32 channel, int16 value)
  157.   This function takes a channel number (0 for left or 1 for right) and a
  158.   PCM sample. The sample should be stored in an array for later output.
  159. - void write_buffer (int fd)
  160.   This function should transfer samples from previous calls to append() to the
  161.   audio device. Samples are not written to the audio device in append(),
  162.   because a syscall takes too much time. The parameter is a dummy in this case.
  163.  
  164. You can take the implementations in obuffer.c as a guideline.
  165. To use your class, the main function in maplay.c has to be modified. Simply
  166. remove the //s in lines 216-226 and fill in your class name, parameters etc.
  167.  
  168. If you have implemented a new output class, you will be rewarded with the
  169. great audio quality of MPEG audio. And if you think that other users might
  170. like your class too, sent me a copy of your sources and I will include it
  171. in the next release.
  172.  
  173.  
  174.  
  175. Enjoy MPEG audio,
  176. bye,
  177.      Tobias Bading  (email: bading@cs.tu-berlin.de)
  178.