SoundSystem Lib

The sound engine behind SoundSystem, for any Fabric 1.21.1 mod that wants music in the world: play a SoundCloud link, keep every player's sound in sync, and make it sound like it comes from the speakers around you.

The Lib adds no blocks and no items. On its own it does nothing you can see — it is a dependency. If a mod asks for it, put the jar in mods/ next to that mod (and Fabric API), on the server and on every client.

---

What it does

SoundCloud playback, with nothing to set up — Give it a public SoundCloud link (a track or a playlist). No API key, no account, no login. The Lib finds what it needs from SoundCloud's own site when the game asks, reads the stream, and decodes it.

No third-party library — The SoundCloud client and the audio decoder are the Lib's own code. Nothing like LavaPlayer is inside: when SoundCloud changes how it works, the fix is a new Lib release, and the mods on top of it are not touched.

One shared timeline — The server never carries audio. It only says which track plays, where it is and how fast. Every player's game downloads and decodes the track itself and keeps its sound on that timeline, so everyone hears the same beat at the same moment, and a big event stays light on the server.

A physical model of sound — What a player hears depends on the world: distance, which way the speaker faces, walls and obstacles in between, the time sound takes to travel (100 ms at 34 blocks), and the reverberation of the room. The music is split in three frequency bands, because bass wraps around and goes through walls where treble is focused and stopped. Optional distortion when a speaker is pushed past 100%.

Ponder inside — The animated 3D guide scenes (hold W over an item) are powered by Ponder, carried inside the jar together with Flywheel and Forge Config API Port. Nothing else to install; if you already have Ponder or Create, the newest version is the one used.

---

Which tracks can it play?

Almost all of them. In a survey of 647 public tracks (October 2026), 94.6% could be played. The Lib decodes AAC, the format SoundCloud serves for every track you can listen to in full.

• Tracks that SoundCloud protects with DRM (about 5% in the survey) can't be played, and neither can tracks that are only offered as a short preview. The game shows "This track's audio format is not supported."
• MP3 and Opus are not decoded: no track in the survey needed them. HE-AAC is not decoded yet either.

The decoder is checked against ffmpeg: on test files and on a real SoundCloud stream, the difference is at most one step of the 16-bit scale.

---

Requirements

• Minecraft 1.21.1, Fabric Loader 0.16.14+
• Fabric API
• Java 21 (the one Minecraft 1.21 already uses)

Nothing else: Ponder, Flywheel and Forge Config API Port are inside the jar.

Config

config/soundsystemlib.json, created on first start; missing fields get their default value. If you used SoundSystem 1.x, the Lib takes over the matching values from config/soundsystem.json the first time it starts.

• maxQueueSize (100) — most tracks a playlist link may hold, 1 to 100
• maxMediaVoices (16) — how many media players your game decodes and plays at once (the nearest ones)
• maxVirtualSources (12) — separately placed sound sources per media player (the loudest ones; the rest are merged)
• enableReverb (true) — the reverberation of the room you stand in
• enablePropagationDelay (true) — sound takes time to travel
• enableDistortion (true) — a speaker pushed past 100% saturates

Lower the two numbers first if a huge event is heavy on your computer.

---

For mod developers

The Lib knows no blocks: you describe your own with a few interfaces, and it does the rest.

• You choose which link plays, when and how fast, and send the state to nearby players in one packet type.
• You describe your speakers (range, how much of each band they reproduce, how they fuse together) and what is in the world around them.
• The Lib resolves the link, decodes it, keeps each client on the timeline and mixes what the listener hears.

Declare the dependency in your fabric.mod.json:

"depends": { "soundsystemlib": ">=0.0.1" }

Starting the client engine takes a few lines:

var engine = new PlaybackEngine<>(clock, EngineSettings.DEFAULT, scene);
ClientPlayNetworking.registerGlobalReceiver(MyState.ID, (packet, ctx) -> ctx.client().execute(() -> engine.receive(packet)));
ClientTickEvents.END_CLIENT_TICK.register(client -> { if (client.world != null) engine.tick(client); });
ClientPlayConnectionEvents.DISCONNECT.register((handler, client) -> engine.stopAll());

You can also read a track without the engine — decode any link to frames of 100 ms of 16-bit stereo at 44.1 kHz:

try (var resolver = new MusicResolver(100)) {
    Track track = resolver.resolve("" rel="noopener nofollow" target="_blank">https://soundcloud.com/some-artist/some-track").get(0);
    try (AudioDecoder decoder = resolver.decode(track, 30_000, 1.0)) {   // from 30 s, at normal speed
        // decoder.pollFrame() ...
    }
}

The public API is the package dev.soundsystemlib.api; dev.soundsystemlib.internal is not, and may change at any time. The API is young: until 1.0, a type may still be renamed between minor versions. The server side of the transport (the packet and its repetition) is yours for now; SoundSystem's is a working example.

---

Mods that use it

• SoundSystem — DJ tables, speakers, stage lighting and pyro (needs Lib 0.0.1 or newer since version 2.0.0)

---

MIT licence. Ponder, Flywheel and Forge Config API Port keep their own licences. The AAC code tables are transcribed from JAADec (public domain). The Lib doesn't ship or host any audio; music comes from public SoundCloud links.