NAME

       gbsplay - Gameboy sound player

SYNOPSIS

       gbsplay [options] gbs-file [start-subsong [stop-subsong] ]

DESCRIPTION

       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.

OPTIONS

       -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     Enable loop mode.  After the last subsong has been played, playback starts again  with  the  first
              subsong.  Default is no loop.

       -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 and reactions to XEvents 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
              gbsplay exits after this subsong has been played.  If not specified or out-of-bounds, gbsplay will
              exit after playing the last subsong, unless in loop mode (-l).

OUTPUT PLUGINS

       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.

FILES

       /etc/gbsplayrc
              Default location of the global configuration file.

       ~/.gbsplayrc
              User configuration file.

BUGS

       If you encounter bugs, please report them via https://github.com/mmitch/gbsplay/issues

AUTHORS

       gbsplay  was written by Tobias Diedrich <ranma+gbsplay@tdiedrich.de> (with contributions from others, see
       README).

COPYRIGHT

       gbsplay is licensed under GNU GPL.

SEE ALSO

       gbsplay(1), gbsinfo(1), gbsplayrc(5)

Tobias Diedrich                                     0.0.97ish                                         GBSPLAY(1)