GBSPLAY(1)                    Gameboy sound player                    GBSPLAY(1)

NAME
     gbsplay - Gameboy sound player

SYNOPSIS
     gbsplay [OPTION]...  [--] GBS-FILE [START-AT-SUBSONG [STOP-AFTER-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, lit-
            tle 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.

     -O pattern
            Set the output filename pattern used by some sound output plugins to
            pattern.  The pattern may contain these placeholders  that  will  be
            replaced when generating the actual filename:

            %s     current subsong number

            %S     current subsong number with leading zeroes (always 3 digits)

            %e     default  filename  extension  based on sound output plugin in
                   use

            %%     a literal %

            Default value is gbsplay-%s.%e.

     -q     Be quieter, reduce verbosity.  Can be applied multiple  times.   De-
            fault 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, reac-
            tions to keypresses and the on-screen display will be delayed.   De-
            fault 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 con-
            tains  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.

     --     Marks the end of options.  The next argument will be  treated  as  a
            filename, even when starting with a -.

     GBS-FILE
            The sound file to play.  Must be in uncompressed .GBS format.

     START-AT-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 num-
            ber will be clipped to the possible range of subsongs.

     STOP-AFTER-SUBSONG
            The last subsong to be played.  See LOOP MODES below for further de-
            tails.

KEYBOARD CONTROL
     gbsplay supports basic keyboard control.  The following commands are recog-
     nized:

     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.

     l      Cycle through the available loop modes.  See LOOP  MODES  below  for
            further details.

LOOP MODES
     gbsplay  supports different loop modes that govern what happens when a sub-
     song 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-AT-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-AFTER-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-AFTER-SUBSONG parameter will be ignored as  no
            subsong change can occur.  The subsong-timeout parameter will be ig-
            nored as well, allowing the selected subsong to play endlessly with-
            out any forced restarts.

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 be-
            low).  Should export more accurate note off events (the length  reg-
            ister  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 Win-
            dows.

     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.  See -O for the filenames used; the  extension  placeholder
            %e expands to mid.  The files are created in the current working di-
            rectory  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_AUDIO-
            DRIVER 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 au-
            dio 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.  See -O for the file-
            names used; the extension placeholder %e expands to mid.  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.  See -O  for
            the  filenames  used;  the  extension placeholder %e expands to wav.
            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/gb-
     splay/issues

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

COPYRIGHT
     gbsplay is licensed under GNU GPL v1 or, at your option, any later version.

SEE ALSO
     gbsinfo(1), gbsplayrc(5)

Tobias Diedrich                      0.0.103                          GBSPLAY(1)
