doc/README.sound

   1
   2 ===========================================================================
   3  Sound Support
   4 ===========================================================================
   5
   6 The server sends the client a list of primary and secondary sound tags
   7 for certain events. The 'primary' tags are those preferred by the
   8 current modpack. The client does not need to have these sounds. The
   9 'secondary' tags should refer to standard sounds that all
  10 installations of Freeciv should have.
  11
  12 Tags are used to give an easy way to change sounds. A specfile is used
  13 to indicate which tags refer to which sound files. A change of spec
  14 file, given as an option at startup, will change sounds. For example,
  15
  16         freeciv-gtk3 --Sound mysounds.spec
  17
  18 will read sound files from "mysounds.spec". You will need to download
  19 or copy or link those sounds into whichever directory is mentioned in this
  20 file first, or edit it to refer to the right files. All references are by
  21 default relative to the data/ directory. Soundpacks can be downloaded from
  22 the Freeciv website in the tar format. You will either need to unpack them
  23 with eg "tar -xzvf stdsoundsX.tar.gz" or use 7-Zip (for Windows etc.), and
  24 put the files in the data directory mentioned above.
  25
  26 You can get additional soundsets (sound files and a spec file)
  27 from <http://files.freeciv.org/contrib/audio/soundsets>. At this
  28 address you find also extra sound files to change an existing soundset or
  29 create a new one.
  30
  31 ================================
  32  Plugins
  33 ================================
  34
  35 The output of the sounds at the client side are done by plugins. The
  36 set of available plugins depend on the libraries found on the host
  37 system. You can choose the plugin the client should use via the
  38 command line:
  39
  40         freeciv-gtk3 --Plugin sdl
  41
  42 You can choose "none" to mute the client. Freeciv currently supports
  43 the following plugins:
  44   - dummy (none)
  45   - SDL with SDL_mixer library (sdl)
  46
  47 To add support for a new plugin, change these files (where "whatever"
  48 is the name of the new plugin):
  49         configure.ac                    /* add new test */
  50         client/audio.c                  /* link in new plugin */
  51         client/Makefile.am              /* add the files below */
  52         client/audio_whatever.c         /* audio plugin */
  53         client/audio_whatever.h         /* audio plugin's header */
  54
  55 ================================
  56  Tags
  57 ================================
  58
  59 There are two kinds of sound tags:
  60  - defined in the rulesets
  61  - defined in the program code
  62
  63 While the former can be chosen freely the latter can't be changed.
  64
  65 The sound tags associated with improvements (wonders and normal
  66 buildings), unit movements and unit fights have to be set in the
  67 rulesets. Freeciv just hand these sound tags over to the client where
  68 they are translated into the filenames of the sound files via the
  69 soundspec file. Every soundspec should have generic sound tags for
  70 wonders ("w_generic"), normal buildings ("b_generic"), unit movements
  71 ("m_generic") and unit fights ("f_generic").
  72
  73 Sound tags associated with certain events are generated in the Freeciv
  74 code and can't be configured from outside. The soundspec file also has
  75 to have mapping for these tags. The complete list of such tags can be
  76 found in data/stdsounds.spec. The name of the tag is enum name (see
  77 common/events.h) in lowercase. So E_POLLUTION becomes the tag
  78 "e_pollution". There is no generic event tag and no alternate tags are
  79 used.
  80
  81 ================================
  82  TODO
  83 ================================
  84
  85 There are a few things that can be done to get better sound support in
  86 Freeciv still:
  87   * add more plugins (gstreamer, arts, windows, etc)
  88   * add a sound tag for each technology, as for buildings/units
  89   * always add more event tags
  90   * find or create better sound samples and make better spec-file
  91
  92 ================================
  93  Misc
  94 ================================
  95
  96 Sound creators: Please name sound files intelligibly. Include a README
  97 where you present the licensing terms used (if public domain, say so)
  98 for the sound files.
  99
 100 Modpack makers: Please give secondary tags that refer to standard tags
 101 so that those who have not downloaded the latest & greatest sound pack
 102 can still enjoy the game.