Skip to content

Performance tuning

The defaults work for most servers. Read this page if the music stutters or cuts out for a moment now and then, especially on a small VPS or a busy computer.

Short stutters usually come from Java pausing to clean up memory. The fix is a garbage collector with very short pauses, plus enough audio buffered ahead to cover any pause that still happens.

Java flags

Start the bot with ZGC, Java's low-pause garbage collector:

java -Dfile.encoding=UTF-8 \
     -XX:+UseZGC \
     -XX:+AlwaysPreTouch \
     -Dnogui=true \
     --enable-native-access=ALL-UNNAMED \
     -jar JMusicBot-0.8.0.jar
Flag What it does
-XX:+UseZGC Uses ZGC, whose pauses are well under a millisecond.
-XX:+AlwaysPreTouch Sets up all memory at startup, so the bot doesn't stall to grab more later.
-Xms / -Xmx Optional. Fixes or limits memory, for example -Xms256m -Xmx512m.
-Dfile.encoding=UTF-8 Shows non-English song titles correctly.
--enable-native-access=ALL-UNNAMED Lets the audio libraries load without warnings.

On Windows PowerShell, quote each -D option, for example "-Dfile.encoding=UTF-8". See First run.

Docker

The Docker image already uses ZGC and AlwaysPreTouch. To add a memory limit, set JAVA_OPTS:

environment:
  - JAVA_OPTS=-Xms256m -Xmx512m -XX:+UseZGC -XX:+AlwaysPreTouch

Audio buffers

Two settings in config.txt control how much audio the bot keeps ready:

performance {
  nasBufferMs = 800      # audio ready to send; covers Java pauses up to this long
  frameBufferMs = 2000   # decoded audio kept ahead of playback
}

Raise them if you still hear stutters after switching to ZGC. Higher values add a little delay when you skip, pause or change the volume. The defaults suit most setups.

Other things to check

  • Memory. If the computer is low on memory, other programs can push the bot into swap, which causes long stalls. Give it a few hundred MB to itself.
  • CPU. A shared VPS with "burstable" CPU can run out of credits and slow down. Check your provider's dashboard if stutters come at busy times.
  • Network. Stutters on every song, from every source, can be a slow or unstable connection on the bot's side.

Still stuttering? See Troubleshooting.