GBSPLAY(1)

📦
version 0.0.102 · 6 versions
, in ubuntu resolute, ubuntu stonking

💖 GBSPLAY(1) 💖

okay bestie, so this is gbsplay, the Gameboy sound player — it's a manual page from the Gameboy sound player section of the manual, and it's genuinely iconic. come sit, we're gonna go through it together 🎀

✨ NAME ✨

gbsplay — Gameboy sound player 🎮🔊

🌸 SYNOPSIS 🌸

gbsplay [OPTION]...  [--] GBS-FILE [START-AT-SUBSONG
[STOP-AFTER-SUBSONG] ]

🦋 DESCRIPTION 🦋

so gbsplay emulates the sound hardware of the Nintendo Gameboy. that's the whole vibe. it plays the sounds from a Gameboy module dump (.GBS format) and pushes them out over /dev/dsp and other sound drivers. no cap, it's just Gameboy music, but make it your computer's problem 💅

💅 OPTIONS 💅

  • -E endian — sets endianness to endian. the valid values are b, l and n, for big, little and native endian respectively. pick your fighter ✨
  • -f fadeout-time — sets fadeout time to fadeout-time seconds. instead of cutting the subsong off hard (rude), it does a soft fadeout (gentle, demure). default is 3 seconds 💖
  • -g subsong-gap — sets the subsong gap to subsong-gap seconds. before playing the next subsong after the subsong timeout, subsong-gap seconds of silence play first. like a lil breather between songs. default is 2 seconds 🫶
  • -h — displays short help and dips. bye bestie 👋
  • -H filter — sets the output high-pass type to filter. valid values are dmg (Gameboy Classic), cgb (Gameboy Color) and off (no filter at all). default is dmg 🎀
  • -l — sets loop mode to range (go read LOOP MODES below, iykyk).
  • -L — sets loop mode to single (again, LOOP MODES below).
  • -o plugin — selects the sound output plugin plugin. pass list and it'll show you a list of every available output plugin. the default depends on compilation options ⭐
  • -q — be quieter, reduce verbosity. you can stack this multiple times. default verbosity is 3 🤫
  • -r samplerate — sets the samplerate to samplerate Hz. default is 44100Hz 🔥
  • -R refresh-delay — sets the refresh delay to refresh-delay milliseconds. bigger values = lower CPU usage, but it's giving delayed subsong changes, delayed fadeouts, delayed reactions to keypresses, and a delayed on-screen display. default is 33 milliseconds 💀
  • -t subsong-timeout — sets subsong timeout to subsong-timeout seconds. once a subsong has played for that long, the player skips to the next subsong. a timeout of 0 seconds disables automatic subsong changes entirely. default is 120 seconds ⏳
  • -T silence-timeout — sets silence timeout to silence-timeout seconds. if a subsong contains silence for that long, the player skips to the next subsong. default is 2 seconds 🔇
  • -v — increase verbosity, print more info. stackable too. default verbosity is 3 🗣️
  • -V — displays the version number and exits. slay 👑
  • -z — plays subsongs in shuffle mode. every subsong gets played once, in random order 🔀
  • -Z — plays subsongs in random mode. it's like shuffle mode (-z), except a subsong can be played multiple times. chaos mode, honestly 🌀
  • -1 — mutes channel 1 on start.
  • -2 — mutes channel 2 on start.
  • -3 — mutes channel 3 on start.
  • -4 — mutes channel 4 on start. (yes bestie, all four, one flag each, that's the whole bit 🎚️)
  • -- — marks the end of options. the next argument gets treated as a filename, even if it starts with a -. very important for files with attitude ✋
  • GBS-FILE — the sound file to play. must be in uncompressed .GBS format. no zip, no vibes-based compression, just .GBS 📁
  • START-AT-SUBSONG — the subsong from the sound file to play first. if you don't specify it, the default song declared in the sound file plays — unless shuffle (-z) or random mode (-Z) are active. an out-of-bounds number gets clipped to the possible range of subsongs, so no worries 🎯
  • STOP-AFTER-SUBSONG — the last subsong to be played. see LOOP MODES below for the deets 🛑

⌨️ KEYBOARD CONTROL ⌨️

gbsplay supports basic keyboard control. these are the commands it recognizes:

  • 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 subsong has finished playing. the default loop mode is none. when multiple loop modes are set, the last mode set wins. periodt.

before we go further, some vocabulary, because these terms come up a lot:

  • the term first subsong means the START-AT-SUBSONG parameter if it's set, or the first subsong in the file otherwise.
  • the term next subsong means the next subsong in numerical order — unless shuffle mode (-z) or random mode (-Z) are active.
  • the term last subsong means the STOP-AFTER-SUBSONG parameter if it's set and not out-of-bounds, or the last subsong in the file otherwise.

got it? good. now the modes:

  • none — when a subsong has finished playing, the next subsong starts to play. when the last subsong has finished playing, gbsplay exits. simple, clean, no notes 🌈
  • range — when a subsong has finished playing, the next subsong starts to play. when the last subsong has finished playing, the fist subsong starts to play again. (yes, the original says "fist" — we're keeping it, it's iconic 💀) circular queen behavior 🔄
  • single — when a subsong has finished playing, the same subsong starts to play again. heads up: the STOP-AFTER-SUBSONG parameter will be ignored, because no subsong change can occur. the subsong-timeout parameter will be ignored as well, which lets the selected subsong play endlessly without any forced restarts. truly endless main character energy 🎧

🎛️ OUTPUT PLUGINS 🎛️

output plugins are sometimes called plugouts because that's shorter, so don't be confused, bestie. also — not all of the plugins listed here may be available, so check with gbsplay -o list first 🧚

  • alsa — use the ALSA sound driver for sound output 🐧
  • altmidi — alternative implementation of the MIDI output plugin (see midi below). it should export more accurate note off events (the length register is taken into account), but the generated MIDI files will be more complicated and fine grained, and probably not suitable for editing or printing a score. trades pretty files for accuracy, basically 💅
  • 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. it's giving raw data chaos 📊
  • 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. it's doing its best 🎹
  • 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 the 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 just switch to the dsound plugout instead). fix it, bestie 🛠️
  • 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 — so 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 — the devs wanna know, fr fr 🫶

👑 AUTHORS 👑

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

gbsplay is licensed under GNU GPL v1 or, at your option, any later version. open source royalty 👑

🌈 SEE ALSO 🌈

gbsinfo(1), gbsplayrc(5) — go read those too, bestie 📚

and that's the whole page!! this one's version 0.0.102, dated 0.0.102, and it came from Tobias Diedrich — literally the author himself put his name on the footer, king behavior 👑. it's GBSPLAY(1), it's iconic, it's a wrap. go play some Gameboy music 💖✨🎀🦋🌸💅

📦 where this page comes from