User Manual/Configuring ScummVM

From ScummVM :: Wiki
< User Manual
Revision as of 23:00, 21 December 2007 by Spookypeanut (talk | contribs) (→‎MIDI tab: Filled in from the music drivers section (I feel it's more suited to be here))
Jump to navigation Jump to search
If you want to contribute, send us a sample of text you'd write for the new manual, and we will consider adding you an account. You can work on the manual in the Wiki, but if you prefer, supplying us with HTML or TeX sources is fine, too (we will then translate them for the Wiki).

You can have a look at our TODO page for a list of tasks that need to be done.

Using the Launcher to configure ScummVM

The ScummVM Launcher gives us a graphical method for changing the settings that it uses to run games. There are two ways to do this: firstly by changing the default settings (which games will follow unless told otherwise), secondly by overriding an individual game to use settings that are different from the defaults. To begin with we will look at changing the default settings. To do this, click on the "Options" button on the right-hand side of the Launcher window. There are many options, and they are separated into tabs: we shall look at each tab in turn.

Graphics tab

The Graphics tab of the ScummVM options

The graphics tab allows us to change various things about the way the games are displayed on screen when played.

Control Description
Graphics mode This allows us to change the graphic filter that ScummVM uses. See the Graphic filters section of the manual for more detail
Render mode For games that could be played on various different systems / graphics cards, this control allows us to decide which system we want ScummVM to reproduce. The options are <default> (which tries to choose the most sensible option), Hercules Green, Hercules Amber (monochrome), CGA (4 colors), EGA (16 colors), and Amiga (32 colors))
Fullscreen mode Switches between playing games in a window, or playing them in fullscreen mode. Switch between the two using Alt-F5 while in a game.
Aspect ratio correction Most games supported by ScummVM were designed to be played at a screen resolution of 320x200. Most modern systems, when displaying this size image, will display it in a window that is not 1.33:1 (as the designers intended), but 1.6:1 or even 1.7:1. This results in the game appearing stretched and the characters looking wider than they should. If this option is checked, ScummVM corrects for this by stretching the game window down by a similar amount, and the game can be played without distortion. Like Graphic filters, this takes a little processing power to achieve.

Audio tab

The Audio tab

The audio tab in the options allows us to change various things about the way that sound is outputted in ScummVM games.

Control Description
Music driver This is the method that ScummVM uses to output MIDI music. For more details, see the section on music drivers.
Output rate This is the sample rate at which ScummVM plays back sounds (including music if using an emulation music driver, such as the Adlib music driver). For more information, see the Output sample rate section
Text and Speech For games with digitized speech, this control allows the user to decide whether to play the game with speech and without any subtitles, with subtitles displaying the words spoken in the digitized speech but not the speech, or with both.
Subtitle speed This allows the user to adjust the length of time that the subtitles are displayed on screen: the lower the speed is set, the longer the subtitles appear for.

Volume tab

The Volume tab

The volume tab allows us to set the relative volumes for the various different types of sound that ScummVM plays.

Control Description
Music volume The volume of the music played back in games. This is usually MIDI music played back with one of the music drivers, but some games use digitized music.
SFX volume The volume of the sound effects within the games.
Speech volume The volume of the digitized speech in the game, if it has any.

MIDI tab

The MIDI tab

The MIDI tab lets us change various settings about the MIDI music played back in games.

Control Description
Soundfont Some music drivers require you to provide them with a Soundfont, which contains samples of instruments for the device to play back. This setting allows you to choose one.
Mixed Adlib/MIDI mode Some games contain sound effects that are exclusive to the Adlib soundtrack. For these games, you may wish to use this mode in order to combine MIDI music with Adlib sound effects.
True Roland MT-32 (disable GM emulation) ScummVM will treat your device as a real MT-32. Because the instrument mappings and system exclusive commands of the MT-32 vary from those of General MIDI devices, you should only enable this option if you are using an actual Roland MT-32, LAPC-I, CM-64, CM-32L, CM-500, or GS device with an MT-32 map.
Enable Roland GS Mode ScummVM will initialize your GS-compatible device with settings that mimic the MT-32's reverb, (lack of) chorus, pitch bend sensitivity, etc. If it is specified in conjunction with True Roland MT-32 (above), ScummVM will select the MT-32-compatible map and drumset on your GS device. This setting works better than default GM or GS emulation with games that do not have custom instrument mappings (Loom and Monkey Island 1). You should only specify both settings if you are using a GS device that has an MT-32 map, e.g. SC-55, SC-88, SC-8820, etc. Please note that Roland GS Mode is automatically disabled in both DOTT and Samnmax, since they use General MIDI natively.
MIDI gain The relative volume of the general MIDI music. This is only supported by some of the music drivers.

Paths tab

The Paths tab

This part of the options lets the user tell ScummVM where to look for particular files

Control Description
Save Path This is the default folder in which ScummVM will store saved games. If this is not set, saved games will generally be stored in the current directory. Exceptions to this include Mac OS X ($HOME/Documents/ScummVM Savegames/) and other UNIX variants ($HOME/.scummvm/).
Extra Path This is the folder that ScummVM will look in for various "extra" files. These could include one or more of:
  • Additional datafiles required for certain games (e.g. kyra.dat)
  • Soundfonts (see MIDI tab)
  • MT-32 ROMs (see MT-32 emulation)
Theme Path The folder that additional themes for the ScummVM Launcher are stored in.

Misc tab

The Misc tab

The Misc tab contains options that don't belong on any of the other tabs.

Control Description
Theme Click on this button to change the visual appearance of the ScummVM Launcher
Autosave In some games (namely Beneath a Steel Sky, Flight of the Amazon Queen and all SCUMM games), ScummVM will automatically save the game every few minutes. For the SCUMM engine, it will save in Slot 0. This saved game can be loaded again using Ctrl-0 or the F5 menu. Use this control to adjust the time period that ScummVM waits between saves; the default setting is 5 minutes.

Using the configuration file to configure ScummVM

When you change a setting in the ScummVM Launcher (see Using the Launcher to configure ScummVM), all it does is add a line to the configuration file. This is a plain text file which stores all the settings for ScummVM. It is possible to edit this file directly, and some settings can only be changed this way.

The name of the config file and the location in which it is stored depend on the system you are running ScummVM on:

Operating System Location of config file
Windows Vista \Users\username\AppData\Roaming\ScummVM\scummvm.ini
Windows 2000/XP \Documents and Settings\username\Application Data\ScummVM\scummvm.ini
Windows NT4 <windir>\Profiles\username\Application Data\ScummVM\scummvm.ini
Windows 95/98/ME <windir>\scummvm.ini
Unix $HOME/.scummvmrc
Mac OS X $HOME/Library/Preferences/ScummVM Preferences
Others scummvm.ini in the current directory

Note: all Windows versions will use <windir>\scummvm.ini if it already exists.

General config file settings

These parameters can either be set in the "ScummVM" section of the config file, in which case they specify the default setting, or in the section for a particular game, in which case they override the default setting for that game.

Keyword Type Description
path string The path in which a game's data files are stored
autosave_period number Number of seconds between autosaves (default: 300)
save_slot number The savegame number to load on startup
savepath string The path to which a game will store its savegames
versioninfo string The version of ScummVM that created the configuration file
gameid string The real id of a game. Useful if you have several versions of the same game, and want different aliases for them
description string The description of the game as it will appear in the launcher
language string Specify language (en, us, de, fr, it, pt, es, jp, zh, kr, se, gb, hb, cz, ru)
speech_mute bool If true, speech is muted
subtitles bool Set to true to enable subtitles
talkspeed number Text speed
fullscreen bool Fullscreen mode
aspect_ratio bool Enable aspect ratio correction
gfx_mode string Graphics mode (see Graphic filters)
confirm_exit bool Ask for confirmation by the user before quitting (SDL backend only)
cdrom number Number of CD-ROM unit to use for audio. If negative, don't even try to access the CD-ROM
joystick_num number Number of joystick device to use for input
music_driver string The music engine to use
output_rate number The output sample rate to use, in Hz (see Output sample rate)
alsa_port string Port to use for output when using the ALSA music driver
music_volume number The music volume setting (0-255)
multi_midi bool If true, enable combination Adlib and native MIDI
soundfont string The SoundFont to use for MIDI playback (only supported by some MIDI drivers)
native_mt32 bool If true, disable GM emulation and assume that there is a true Roland MT-32 available
enable_gs bool If true, enable Roland GS-specific features to enhance GM emulation. If native_mt32 is also true, the GS device will select an MT-32 map to play the correct instruments
sfx_volume number The sfx volume setting (0-255)
tempo number The music tempo (50-200) (default: 100)
speech_volume number The speech volume setting (0-255)
midi_gain number The MIDI gain (0-1000) (default: 100) (only supported by some MIDI drivers)
copy_protection bool Enable copy protection in certain games, in those cases where ScummVM disables it by default.
demo_mode bool Start demo in Maniac Mansion
alt_intro bool Use alternative intro for CD versions of Beneath a Steel Sky and Flight of the Amazon Queen
boot_param number Pass this number to the boot script

Game specific settings

These parameters will only have any effect in the section of the config file devoted to specific games.

Music & sound effects mute settings

Broken Sword 2, Flight of the Amazon Queen and Simon the Sorcerer 1 & 2 all allow use of the following settings:

Keyword Type Description
music_mute bool If true, music is muted
sfx_mute bool If true, sound effects are muted

Broken Sword 2 specific settings

Keyword Type Description
gfx_details number Graphics details setting (0-3)
object_labels bool If true, object labels are enabled
reverse_stereo bool If true, stereo channels are reversed

The Legend of Kyrandia specific settings

Keyword Type Description
walkspeed int The walk speed (0-4)

Graphic filters

ScummVM offers several anti-aliasing filters to attempt to improve visual quality. These filters take the original game graphics, and scale it by a certain fixed factor (usually 2x or 3x) before displaying them to you. So for example, if the game originally ran at a resolution of 320x200 (typical for most of the SCUMM games), then using a filter with a scale factor of 2x will effectively yield 640x400 graphics. Likewise a 3x filter will give 960x600.

ScummVM uses the following graphic filters:

Name Factor Description
1x 1x No filtering, no scaling, fastest
2x 2x No filtering, simple pixel duplication (default for non 640x480 games)
3x 3x No filtering, simple pixel duplication
2xsai 2x SAI filter
super2xsai 2x Enhanced 2xSAI filtering
supereagle 2x Less blurry than 2xSAI, but slower
advmame2x 2x Doesn't rely on blurring like 2xSAI, fast
advmame3x 3x Doesn't rely on blurring like 2xSAI, fast
hq2x 2x Very nice high quality filter but slow
hq3x 3x Very nice high quality filter but slow
tv2x 2x Interlace filter, tries to emulate a TV
dotmatrix 2x Dot matrix effect

To select a graphics filter from the command line, use the '-g' option (see Command line options), e.g.:

scummvm -gadvmame2x monkey2

There is always a speed impact when using any form of anti-aliasing/linear filtering. Filters can be especially slow when ScummVM is compiled in a debug configuration without optimizations. For these reasons, not all backends support all (or even any) of the filters listed above; some may support additional ones. The filters listed above are those supported by the default SDL backend.

NB: The final resolution depends on the original resolution of the game you are playing. For example, the FM-TOWNS version of Zak McKracken uses an original resolution of 320x240, hence for this game the final resolution with a scaler will be 640x480 (2x) or 960x720 (3x). Likewise, games that were originally 640x480 (such as Curse of Monkey Island or the Broken Sword games) will be scaled to 1280x960 (2x) and 1920x1440 (3x).

Music and Sound

On most operating systems and for most games, ScummVM will by default use Adlib emulation for music playback. MIDI may not be available on all operating systems or may need manual configuration. If you want to use MIDI, you have several different choices of output, depending on your operating system and configuration.

Name Description
null Null output: don't play any music
adlib Internal Adlib emulation (default)
fluidsynth FluidSynth MIDI emulation
mt32 Internal MT-32 emulation
pcjr Internal PCjr emulation (only usable in SCUMM games)
pcspk Internal PC Speaker emulation
towns Internal FM-TOWNS YM2612 emulation (only usable in SCUMM FM-TOWNS games)
alsa Output using ALSA sequencer device.
core CoreAudio sound (Mac OS X only)
coremidi CoreMIDI sound (Mac OS X only). Use only if you have a hardware MIDI synthesizer
qt Quicktime sound (Macintosh only)
seq Use /dev/sequencer for MIDI (Unix only)
timidity Connect to TiMidity++ MIDI server
windows Windows MIDI (Windows only). Uses built-in sequencer

To select a sound driver, select it in the Launcher, or run ScummVM with the the '-e' option (see Command line options), for example:

   scummvm -eadlib monkey2

Music drivers

Adlib emulation

By default an Adlib card will be emulated and ScummVM will output the music as sampled waves. This is the default mode for most games, and offers the best compatibility between machines and games.

FluidSynth MIDI emulation

If ScummVM was build with libfluidsynth support it will be able to play MIDI music through the FluidSynth driver. You will have to specify a SoundFont to use, however. Since the default output volume from FluidSynth can be fairly low, ScummVM will set the gain by default to get a stronger signal. This can be further adjusted using the --midi-gain command-line option, or the "midi_gain" config file setting.

The setting can take any value from 0 through 1000, with the default being 100. (This corresponds to FluidSynth's gain settings of 0.0 through 10.0, which are presumably measured in decibel.)

NOTE: The processor requirements for FluidSynth can be fairly high in some cases. A fast CPU is recommended.

MT-32 emulation

Some games which contain MIDI music data also have improved tracks designed for the MT-32 sound module. ScummVM can now emulate this device, however you must provide original MT-32 ROMs to make it work:

MT32_PCM.ROM - IC21 (512KB) MT32_CONTROL.ROM - IC26 (32KB) and IC27 (32KB), interleaved byte-wise

Place these ROMs in the game directory, in your extrapath, or in the directory where your ScummVM executable resides.

You don't need to specify --native-mt32 with this driver, as it automatically gets turned on.

NOTE: The processor requirements for the emulator are quite high; a fast CPU is strongly recommended.

MIDI emulation

Some games (such as Sam & Max) only contain MIDI music data. This once prevented music for these games from working on platforms that do not support MIDI, or soundcards that do not provide MIDI drivers (e.g. many soundcards will not play MIDI under Linux). ScummVM can now emulate MIDI mode using sampled waves and Adlib, FluidSynth MIDI emulation or MT-32 emulation using the -eadlib, -efluidsynth or -emt32 options respectively. However, if you are capable of using native MIDI, we recommend using one of the MIDI modes below for best sound.

Native MIDI

Use the appropriate -e<mode> command line option from the list above to select your preferred MIDI device. For example, if you wish to use the Windows MIDI driver, use the -ewindows option.

Using MIDI options to customize Native MIDI output

ScummVM supports a variety of MIDI modes, depending on the capabilities of your MIDI device.

If --native-mt32 is specified, ScummVM will treat your device as a real MT-32. Because the instrument mappings and system exclusive commands of the MT-32 vary from those of General MIDI devices, you should only enable this option if you are using an actual Roland MT-32, LAPC-I, CM-64, CM-32L, CM-500, or GS device with an MT-32 map.

If --enable-gs is specified, ScummVM will initialize your GS-compatible device with settings that mimic the MT-32's reverb, (lack of) chorus, pitch bend sensitivity, etc. If it is specified in conjunction with --native-mt32, ScummVM will select the MT-32-compatible map and drumset on your GS device. This setting works better than default GM or GS emulation with games that do not have custom instrument mappings (Loom and Monkey1). You should only specify both settings if you are using a GS device that has an MT-32 map, such as an SC-55, SC-88, SC-88 Pro, SC-8820, SC-8850, etc. Please note that --enable-gs is automatically disabled in both DOTT and Samnmax, since they use General MIDI natively.

If neither of the above settings is enabled, ScummVM will initialize your device in General MIDI mode and use GM emulation in games with MT-32 soundtracks.

Some games contain sound effects that are exclusive to the Adlib soundtrack. For these games, you may wish to specify --multi-midi in order to combine MIDI music with Adlib sound effects.

Sequencer MIDI (Unix only)

If your soundcard driver supports a sequencer, you may set the environment variable "SCUMMVM_MIDI" to your sequencer device -- for example, to /dev/sequencer

If you have problems with not hearing audio in this configuration, it is possible you will need to set the "SCUMMVM_MIDIPORT" variable to 1 or 2. This selects the port on the selected sequencer to use. Then start scummvm with the -eseq parameter. This should work on several cards, and may offer better performance and quality than Adlib emulation. However, for those systems where sequencer support does not work, you can always fall back on Adlib emulation.

ALSA sequencer (Unix only)

If you have installed the ALSA driver with the sequencer support, then set the environment variable SCUMMVM_PORT or the config file parameter alsa_port to your sequencer port. The default is "65:0".

Here is a little howto on how to use the ALSA sequencer with your soundcard. In all cases, to have a list of all the sequencer ports you have, try the command

aconnect -o -l

This should give output similar to:

client 64: 'External MIDI 0' [type=kernel]
    0 'MIDI 0-0        '
client 65: 'Emu10k1 WaveTable' [type=kernel]
    0 'Emu10k1 Port 0  '
    1 'Emu10k1 Port 1  '
    2 'Emu10k1 Port 2  '
    3 'Emu10k1 Port 3  '
client 128: 'Client-128' [type=user]
    0 'TiMidity port 0 '
    1 'TiMidity port 1 '

This means the external MIDI output of the sound card is located on the port 64:0, four WaveTable MIDI outputs in 65:0, 65:1, 65:2 and 65:3, and two TiMidity ports, located at 128:0 and 128:1.

If you have a FM-chip on your card, like the SB16, then you have to load the SoundFonts using the sbiload software. Example:

 sbiload -p 65:0 /etc/std.o3 /etc/drums.o3

If you have a WaveTable capable sound card, you have to load a sbk or sf2 SoundFont using the sfxload software. Example:

 sfxload /path/to/8mbgmsfx.sf2

If you don't have a MIDI capable soundcard, there are two options: FluidSynth and TiMidity. We recommend FluidSynth, as on many systems TiMidity will 'lag' behind music. This is very noticeable in iMUSE-enabled games, which use fast and dynamic music transitions. Running TiMidity as root will allow it to setup real time priority, which may reduce music lag.

Asking TiMidity to become an ALSA sequencer:

 timidity -iAqqq -B2,8 -Os1S -s 44100 &

(If you get distorted output with this setting, you can try dropping the -B2,8 or changing the value.)

Asking FluidSynth to become an ALSA sequencer (using SoundFonts):

 fluidsynth -m alsa_seq /path/to/8mbgmsfx.sf2

Once either TiMidity or FluidSynth are running, use the 'aconnect -o -l' command as described earlier in this section.

Using TiMidity++ MIDI server

If you system lacks any MIDI sequencer, but you still want better MIDI quality than default Adlib emulation can offer, you can try TiMidity++ MIDI server. See for download and install instructions.

First, you need to start a daemon:

   timidity -ir 7777

Now you can start scummvm and try selection TiMidity music output. By default, it will connect to localhost:7777, but you can change host/port by defining "TIMIDITY_HOST" environment variable.

Using compressed audio files

Output sample rate

The output sample rate tells ScummVM how many sound samples to play per channel per second. There is much that could be said on this subject, but most of it is beyond the scope of this document. The short version is that for most games 22050 Hz is fine, but in some cases 44100 Hz is preferable. On extremely low-end systems you may want to use 11025 Hz, but it’s unlikely that you will have to worry about that.

To elaborate, most of the sounds that ScummVM has to play were sampled at either 22050 Hz or 11025 Hz. Using a higher sample rate will not magically improve the quality of these sounds, thus 22050 Hz is fine.

Some games use CD audio. If you use compressed files for this, they are probably sampled at 44100 Hz, so for these games that may be a better choice of sample rate.

When using the Adlib, FM Towns, PC Speaker or IBM PCjr music drivers, ScummVM is responsible for generating the samples. Usually 22050 Hz will be plenty for these, but there is at least one piece of Adlib music in Beneath a Steel Sky that will sound a lot better at 44100 Hz.

Using frequencies in between is not recommended. For one thing, your sound card may not support it. In theory, ScummVM should fall back on a sensible frequency in that case, but don’t count on it. More importantly, ScummVM has to resample all sounds to its output frequency. This is much easier to do well if the output frequency is a multiple of the original frequency.