Developer API

Developer API Guide

DreamVoice exposes a comprehensive, high-performance API allowing external plugins, minigames, frameworks, and Fabric mods to interact with all voice and acoustic subsystems.

Starting with v2.0.1, DreamVoice features a unified multiplatform architecture: whether your code runs on Paper / Purpur or Fabric, the service locator, model classes, and core interfaces remain identical.

---

Dependency Setup

DreamVoice API is published to both JitPack and GitHub Packages.

1. Paper / Purpur Plugin Setup

Gradle Kotlin DSL (build.gradle.kts)

repositories {
    mavenCentral()
    maven("https://jitpack.io")
    maven("https://repo.papermc.io/repository/maven-public/")
}

dependencies {
    compileOnly("com.github.Dreamin-MC.DreamVoice:api:2.0.1")
}

Gradle Groovy (build.gradle)

repositories {
    mavenCentral()
    maven { url = "https://jitpack.io" }
    maven { url = "https://repo.papermc.io/repository/maven-public/" }
}

dependencies {
    compileOnly "com.github.Dreamin-MC.DreamVoice:api:2.0.1"
}

Maven (pom.xml)

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
    <repository>
        <id>papermc</id>
        <url>https://repo.papermc.io/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.Dreamin-MC.DreamVoice</groupId>
        <artifactId>api</artifactId>
        <version>2.0.1</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

---

2. Fabric Mod Setup (Fabric Loom)

If you are developing a Fabric mod that integrates with DreamVoice:

Gradle Groovy (build.gradle)

repositories {
    mavenCentral()
    maven { url = "https://jitpack.io" }
}

dependencies {
    // DreamVoice API
    modCompileOnly "com.github.Dreamin-MC.DreamVoice:api:2.0.1"

    // If you need direct access to Fabric network packet classes:
    // modCompileOnly "com.github.Dreamin-MC.DreamVoice:fabric:2.0.1"
}

---

Unified Service Locator (DreamVoiceAPI)

The primary and recommended entry point across both Paper and Fabric is DreamVoiceAPI.get():

import fr.dreamin.dreamvoice.api.DreamVoiceAPI;
import fr.dreamin.dreamvoice.api.speaker.service.VoiceSpeakerService;
import fr.dreamin.dreamvoice.api.wall.service.VoiceWallService;
import fr.dreamin.dreamvoice.api.room.service.VoiceRoomService;
import fr.dreamin.dreamvoice.api.recording.service.VoiceRecordingService;
import fr.dreamin.dreamvoice.api.radio.service.VoiceRadioService;
import fr.dreamin.dreamvoice.api.filter.service.VoiceFilterService;

public class MyVoiceExtension {

    private final VoiceSpeakerService speakers;
    private final VoiceWallService voiceWall;
    private final VoiceRoomService roomService;
    private final VoiceRecordingService recordingService;

    public MyVoiceExtension() {
        DreamVoiceAPI api = DreamVoiceAPI.get();

        this.speakers = api.speakerService();
        this.voiceWall = api.wallService();
        this.roomService = api.roomService();
        this.recordingService = api.recordingService();
    }
}

Paper Legacy Service Retrieval

On Paper / Bukkit servers, all services are also registered in the Bukkit ServicesManager on plugin startup:

VoiceSpeakerService speakers = Bukkit.getServicesManager().load(VoiceSpeakerService.class);

DreamAPI Service Retrieval

If your project utilizes the DreamAPI framework:

VoiceSpeechService speechService = DreamAPI.getAPI().getService(VoiceSpeechService.class);

---

Registered Services Registry

Service Getter	Service Interface	Package	Responsibility
api.speakerService()	VoiceSpeakerService	fr.dreamin.dreamvoice.api.speaker.service	3D positional speakers, dual-channel audio, and entity attachment.
api.wallService()	VoiceWallService	fr.dreamin.dreamvoice.api.wall.service	Wall occlusion physics, aperture diffraction, and particle debugging.
api.roomService()	VoiceRoomService	fr.dreamin.dreamvoice.api.room.service	Soundproof rooms, Cuboid spatial zones, reverb, and room filters.
api.recordingService()	VoiceRecordingService	fr.dreamin.dreamvoice.api.recording.service	Raw Opus streaming, cassette item creation, MP3/OGG export, and slicing.
api.radioService()	VoiceRadioService	fr.dreamin.dreamvoice.api.radio.service	Walkie-talkie frequency channels and analog DSP filters.
api.wiretapService()	VoiceWiretapService	fr.dreamin.dreamvoice.api.wiretap.service	Covert bugs, remote eavesdropping, and direct cassette recording.
api.projectionService()	VoiceProjectionService	fr.dreamin.dreamvoice.api.projection.service	Voice projection anchors, CCTV feeds, and bilateral listening.
api.transmitterService()	VoiceTransmitterService	fr.dreamin.dreamvoice.api.transmitter.service	Point-to-point directional voice transmitters.
api.filterService()	VoiceFilterService	fr.dreamin.dreamvoice.api.filter.service	File-first DSP voice filter registry, compilation, and stack management.
api.speechService()	VoiceSpeechService	fr.dreamin.dreamvoice.api.speech.service	Realtime keyword spotting, Vosk model management, and transcription stations.
api.playerService()	PlayerService	fr.dreamin.dreamvoice.api.player.service	Voice player state management and metadata wrappers (VPlayer).
api.persistenceService()	VoicePersistenceService	fr.dreamin.dreamvoice.api.persistence.service	Async auto-saving and manual disk flushes across modules.
api.broadcastService()	VoiceBroadcastService	fr.dreamin.dreamvoice.api.broadcast.service	Global announcements and audio alerts.
api.voiceService()	VoiceService	fr.dreamin.dreamvoice.api.voice.service	Direct Simple Voice Chat bridge and packet dispatch.

---

Multiplatform Coordinates (VoiceLocation)

To ensure complete compatibility across Paper (Bukkit Location) and Fabric (net.minecraft.core.BlockPos / Vec3), DreamVoice provides VoiceLocation:

import fr.dreamin.dreamvoice.api.model.VoiceLocation;

// Creating a location independently of server platform:
VoiceLocation loc = new VoiceLocation("minecraft:overworld", 128.5, 64.0, -250.5);

// With rotation:
VoiceLocation locWithRot = new VoiceLocation("minecraft:overworld", 128.5, 64.0, -250.5, 90.0f, 0.0f);

---

DreamAPI ItemRegistry Integration (VoiceItemHandler)

DreamVoice provides native voice handlers designed for DreamAPI custom items:

import fr.dreamin.dreamvoice.api.item.VoiceItemHandler;
import fr.dreamin.dreamapi.api.item.model.ItemAction;
import java.time.Duration;

// Gas Mask: apply gasmask filter while worn
ItemDefinition.builder("gas_mask")
    .handler(ItemAction.SET_ARMOR, VoiceItemHandler.addFilter("gasmask"))
    .handler(ItemAction.REMOVE_ARMOR, VoiceItemHandler.removeFilter("gasmask"))
    .build();

// Stealth Device: temporary disguise filter for 30 seconds
ItemDefinition.builder("stealth_cloak")
    .handler(ItemAction.RIGHT_CLICK, VoiceItemHandler.timedFilter("disguise", Duration.ofSeconds(30)))
    .build();

// Police Walkie-Talkie: tune into frequency 142.5 on right-click
ItemDefinition.builder("walkie_talkie")
    .handler(ItemAction.RIGHT_CLICK, VoiceItemHandler.connectRadio("142.5"))
    .build();

---

Events & Inter-Mod Communication

Depending on whether you are writing a Paper plugin or a Fabric mod, you can intercept or react to events:

• Paper / Purpur: Standard Bukkit @EventHandler annotations.
• Fabric: Fabric event hook DreamVoiceEvents.VOICE_EVENT.register(...).
• Network Packets: Send and receive JSON custom payloads over dreamvoice:* channels without hard dependencies.

For detailed event guides, see Events & Hooks Reference and Network Packets & Protocols.