3D Spatial Speakers

3D Spatial Speakers

The 3D Spatial Speakers module provides high-fidelity locational audio channels capable of playing prerecorded audio, web streams, or live player microphone relays in the 3D Minecraft world across both Paper / Purpur and Fabric.

---

Architectural Highlights

1. Dual-Channel Architecture

Every speaker manages two concurrent, non-interfering audio channels:

• voiceChannel: Relays live player speech when linked with /speaker link.
• speakerChannel: Plays background music, siren alarms, or physical cassette recordings concurrently. Both channels mix seamlessly without Opus decoder corruption or channel drops.

2. Static & Dynamic Entity Attachment

Speakers can be anchored to fixed world coordinates, or attached to moving entities:

• Attach to an Armor Stand, NPC, vehicle, or Minecart.
• The 3D audio source updates its position dynamically every tick with the host entity.

3. Self-Echo & Comb-Filter Protection

When a player speaks into a speaker they are standing next to, DreamVoice automatically excludes the speaker's own client connection from the broadcast. This eliminates latency echo and comb-filtering artifacts.

4. Bulk Operations (all Operator)

All speaker commands support all as the speaker identifier:

• /speaker play all siren.wav - Plays an emergency siren on every speaker across the server simultaneously.
• /speaker stop all - Stops all active playback across the world.
• /speaker link all <player> - Connects a player to the server-wide public address (PA) system.

---

In-Game Commands

Command	Permission	Description
/speaker create <name> [dist] [mode]	dreamvoice.speaker.create	Creates a speaker at your location. Default: 16 blocks, PUBLIC.
/speaker remove <name|all>	dreamvoice.speaker.remove	Removes target speaker(s).
/speaker list	dreamvoice.speaker.list	Lists all active speakers and their coordinates.
/speaker attach <name> [entity]	dreamvoice.speaker.attach	Binds speaker to an entity or target player.
/speaker detach <name>	dreamvoice.speaker.detach	Detaches speaker, locking coordinates in place.
/speaker link <name|all> [player]	dreamvoice.speaker.link	Routes player microphone through the speaker.
/speaker unlink <name|all> [player]	dreamvoice.speaker.unlink	Disconnects player from the speaker.
/speaker play <name|all> <source>	dreamvoice.speaker.play	Plays a recording name, sounds/ file, or URL.
/speaker playloop <name|all> <source>	dreamvoice.speaker.play	Loops playback infinitely.
/speaker stop <name|all>	dreamvoice.speaker.stop	Halts any active audio playback.

---

Java API & Integration (Paper & Fabric)

Service Retrieval

import fr.dreamin.dreamvoice.api.DreamVoiceAPI;
import fr.dreamin.dreamvoice.api.speaker.service.VoiceSpeakerService;
import fr.dreamin.dreamvoice.api.speaker.model.Speaker;
import fr.dreamin.dreamvoice.api.speaker.model.SpeakerMode;
import fr.dreamin.dreamvoice.api.model.VoiceLocation;
import java.util.UUID;

VoiceSpeakerService speakerService = DreamVoiceAPI.get().speakerService();

Creating & Registering Speakers

Speaker speaker = Speaker.builder()
    .uuid(UUID.randomUUID())
    .name("Auditorium_PA")
    .location(new VoiceLocation("minecraft:overworld", 100.5, 65.0, -200.5))
    .distance(24.0f)
    .mode(SpeakerMode.RESTRICTED)
    .build();

speakerService.register(speaker);

Linking Player Microphone to Speaker

// Link player to broadcast their voice through the speaker:
speaker.linkSpeaker(playerUuid);

// Later unlink:
speaker.unlinkSpeaker(playerUuid);

Playing Audio Files & Web Streams

// Play a sound file located in <root>/sounds/alarm.wav:
speakerService.playSoundFile(speaker, "alarm.wav", false);

// Stream web audio across all speakers:
speakerService.playSoundUrl(speakerService.getSpeakers(), "https://example.com/stream.ogg", true);

// Stop playback:
speakerService.stopSound(speaker);

Unregistering on Shutdown

speakerService.unregister(speaker);
// Or unregister all:
// speakerService.unregisterAll();

---

Inter-Mod & Network Integration (Fabric)

On Fabric, other mods can trigger speaker actions without compile-time coupling via custom packets:

• ServerBoundSpeakerCreatePacket
• ServerBoundSpeakerPlaySoundPacket
• ServerBoundSpeakerLinkPacket

For packet details, see Network Packets & Protocols.