gbsplay - Gameboy sound player
gbsplay [options] gbs-file
[start-subsong [stop-subsong] ]
gbsplay emulates the sound hardware of the Nintendo
Gameboy. It is able to play the sounds from a Gameboy module dump (.GBS
format) over /dev/dsp and other sound drivers.
- -E endian
- Set endianness to endian. Valid values are b, l and
n for big, little and native endian respectively.
- -f
fadeout-time
- Set fadeout time to fadeout-time seconds. Instead of cutting the
subsong off hard, do a soft fadeout. Default value is 3 seconds.
- -g
subsong-gap
- Set subsong gap to subsong-gap seconds. Before playing the next
subsong after the subsong timeout, subsong-gap seconds of silence
will be played. Default value is 2 seconds.
- -h
- Display short help and exit.
- -H filter
- Set output high-pass type to filter. Valid values are dmg
(Gameboy Classic), cgb (Gameboy Color) and off (no filter).
Default value is dmg.
- -l
- Set loop mode to range (see LOOP MODES below).
- -L
- Set loop mode to single (see LOOP MODES below).
- -o plugin
- Select sound output plugin plugin. Select list to view a
list of all available output plugins. Default value depends on compilation
options.
- -q
- Be quieter, reduce verbosity. Can be applied multiple times. Default
verbosity is 3.
- -r samplerate
- Set the samplerate to samplerate Hz. Default value is 44100Hz.
- -R
refresh-delay
- Set the refresh delay to refresh-delay milliseconds. Larger values
will lower CPU usage, but things as subsong changes, fadeouts, reactions
to keypresses and the on-screen display will be delayed. Default value is
33 milliseconds.
- -t
subsong-timeout
- Set subsong timeout to subsong-timeout seconds. When a subsong has
been played for the given time, the player will skip to the next subsong.
A timeout of 0 seconds disables automatic subsong changes. Default value
is 120 seconds.
- -T
silence-timeout
- Set silence timeout to silence-timeout seconds. When a subsong
contains silence for the given time, the player will skip to the next
subsong. Default value is 2 seconds.
- -v
- Increase verbosity, print more information. Can be applied multiple times.
Default verbosity is 3.
- -V
- Display version number and exit.
- -z
- Play subsongs in shuffle mode. Every subsong will be played once in random
order.
- -Z
- Play subsongs in random mode. Like shuffle mode (-z), but a subsong
can be played multiple times.
- -1
- Mute channel 1 on start.
- -2
- Mute channel 2 on start.
- -3
- Mute channel 3 on start.
- -4
- Mute channel 4 on start.
- gbs-file
- The sound file to play. Must be in uncompressed .GBS format.
- start-subsong
- The subsong from the sound file to play first. If not specified, the
default song declared in the sound file will be played unless shuffle
(-z) or random mode (-Z) are active. An out-of-bounds number
will be clipped to the possible range of subsongs.
- stop-subsong
- The last subsong to be played. See LOOP MODES below for further
details.
gbsplay supports basic keyboard control. The following
commands are recognized:
- p
- Skip to the previous subsong.
- n
- Skip to the next subsong.
- q or Esc
- Quit gbsplay.
- Space
- Toggle play/pause.
- 1
- Mute/unmute channel 1.
- 2
- Mute/unmute channel 2.
- 3
- Mute/unmute channel 3.
- 4
- Mute/unmute channel 4.
gbsplay supports different loop modes that govern what
happens when a subsong has finished playing. The default loop mode is
none. When multiple loop modes are set, the last mode set wins. The
term first subsong refers to the parameter start-subsong if it
is set, or the first subsong in the file otherwise. The term next
subsong refers to next subsong in numerical order unless shuffle mode
(-z) or random mode (-Z) are active. The term last
subsong refers to the parameter stop-subsong if it is set and not
out-of-bounds, or the last subsong in the file otherwise.
- none
- When a subsong has finished playing, the next subsong will start to play.
When the last subsong has finished playing, gbsplay will exit.
- range
- When a subsong has finished playing, the next subsong will start to play.
When the last subsong has finished playing, the fist subsong will start to
play again.
- single
- When a subsong has finished playing, the same subsong will start to play
again. The stop-subsong parameter will be ignored as no subsong
change can occur. The subsong-timeout parameter will be ignored as
well, allowing the selected subsong to play endlessly without any forced
restarts.
Output plugins are sometimes called plugouts because that's
shorter, so don't be confused. Not all of the plugins listed here may be
available, see `gbsplay -o list'.
- alsa
- Use the ALSA sound driver for sound output.
- altmidi
- Alternative implementation of the MIDI output plugin (see midi
below). Should export more accurate note off events (the length register
is taken into account), but generated MIDI files will be more complicated
and fine grained and probably not suitable for editing or printing a
score.
- devdsp
- Use the OSS sound driver for sound output via /dev/dsp.
- dsound
- Use the DirectSound sound driver for sound output on Microsoft
Windows.
- iodumper
- Dump IO calls to the Gameboy sound hardware to stdout. This reduces the
verbosity to 0 (see -q) because stdout is used for the dumped
data.
- midi
- Write a simple MIDI conversion of the song into a separate file per
subsong. The files are called gbsplay-%d.mid, where %d is
replaced with the subsong number. The files are created in the current
working directory and existing files are silently overwritten. Only
channels 1 to 3 are converted to MIDI, because channel 4 contains noise
data that can't be converted into MIDI note events. Every GBS channel is
exported to a separate MIDI channel. When multiple voices share a channel,
they will not be separated in the output. The conversion is rather basic
and complicated GBS files using tricks and hacks will not be converted
properly.
- nas
- Use the NAS sound driver for sound output to a Network Audio Server.
- pipewire
- Use the PipeWire sound driver for sound output.
- pulse
- Use the Pulseaudio sound driver for sound output.
- sdl
- Use SDL sound driver for sound output. On Microsoft Windows, libSDL might
use the wasapi audio backend by default which can result in choppy
sound. To fix this, set the environment variable SDL_AUDIODRIVER to
directsound to select a different libSDL audio backend (or switch
to the dsound plugout instead).
- stdout
- Dump the raw audio stream to stdout. This reduces the verbosity to 0 (see
-q) because stdout is used for the dumped data. The raw audio is
always stereo (2 channels), 16 bit signed PCM. Sample rate and endianness
can be set via -r and -E.
- vgm
- Write separate VGM files for every subsong. The files are called
gbsplay-%d.vgm, where %d is replaced with the subsong
number. The files are created in the current working directory and
existing files are silently overwritten.
- wav
- Write separate WAV files (RIFF WAVE) for every subsong. The files are
called gbsplay-%d.wav, where %d is replaced with the subsong
number. The files are created in the current working directory and
existing files are silently overwritten. The output is always encoded as
stereo (2 channels), 16 bit signed PCM in little endian (the -E
switch is ignored). Sample rate can be set via -r.
- /etc/gbsplayrc
- Default location of the global configuration file.
- ~/.gbsplayrc
- User configuration file.
If you encounter bugs, please report them via
https://github.com/mmitch/gbsplay/issues
gbsplay was written by Tobias Diedrich
<ranma+gbsplay@tdiedrich.de> (with contributions from others,
see README.md).
gbsplay is licensed under GNU GPL v1 or, at your option,
any later version.