# API Reference The Amplifier API allows other plugins to read and modify voice player properties, listen to voice events, and play positional audio. All public interfaces live in the `gg.lode.amplifierapi` package within the **Amplifier-API** module. --- ## Dependency Setup ### Maven Add the JitPack repository and the Amplifier-API dependency to your `pom.xml`: ```xml <repositories> <repository> <id>jitpack.io</id> <url>https://jitpack.io</url> </repository> </repositories> <dependencies> <dependency> <groupId>com.github.Lodestones</groupId> <artifactId>Amplifier-API</artifactId> <version>1.0.13</version> <scope>provided</scope> </dependency> </dependencies> ``` ### Gradle ```groovy repositories { maven { url 'https://jitpack.io' } } dependencies { compileOnly 'com.github.Lodestones:Amplifier-API:1.0.13' } ``` Add `Amplifier` as a dependency in your `plugin.yml`: ```yaml depend: - Amplifier ``` --- ## Accessing the API The static `AmplifierAPI` class provides the entry point. Call `AmplifierAPI.getApi()` to retrieve the `IAmplifierAPI` instance. ```java import gg.lode.amplifierapi.AmplifierAPI; import gg.lode.amplifierapi.IAmplifierAPI; IAmplifierAPI api = AmplifierAPI.getApi(); ``` The API instance is set by the Amplifier plugin during startup. Ensure your plugin loads after Amplifier. --- ## Core Interfaces ### IAmplifierAPI The root API interface. Provides access to the voice manager and global voice distance. ```java package gg.lode.amplifierapi; public interface IAmplifierAPI { IVoiceManager getVoiceManager(); float getVoiceDistance(); void setVoiceDistance(float distance); VoicechatServerApi getVoicechatApi(); } ``` | Method | Return Type | Description | |---|---|---| | `getVoiceManager()` | `IVoiceManager` | Returns the voice manager for player lookups and sound playback. | | `getVoiceDistance()` | `float` | Returns the current global voice distance in blocks. | | `setVoiceDistance(float)` | `void` | Sets the global voice distance in blocks. | | `getVoicechatApi()` | `VoicechatServerApi` | Returns the Simple Voice Chat server API instance. | --- ### IVoiceManager Manages voice player instances and provides methods for playing positional audio. ```java package gg.lode.amplifierapi.api.manager; public interface IVoiceManager { void cleanup(); CompletableFuture<IVoicePlayer> fetchOrCreateVoicePlayer(Player player); @Nullable IVoicePlayer getVoicePlayer(UUID uniqueId); @Nullable IVoicePlayer getVoicePlayer(Player player); boolean isEnabled(); void setEnabled(boolean enabled); void playSound(Location location, byte[] data); void playSound(Location location, byte[] data, float volume); void playSound(Location location, byte[] data, float volume, float distance); void playSound(Location location, byte[] data, float volume, float pitch, float distance); CompletableFuture<Void> resetPlayer(Player player); CompletableFuture<Void> resetAll(); } ``` | Method | Description | |---|---| | `fetchOrCreateVoicePlayer(Player)` | Retrieves or creates a voice player record from storage. Returns a `CompletableFuture` since storage may be asynchronous. | | `getVoicePlayer(UUID)` | Returns a cached voice player by UUID, or `null` if not loaded. | | `getVoicePlayer(Player)` | Returns a cached voice player by Bukkit `Player`, or `null` if not loaded. | | `isEnabled()` | Returns whether global voice chat is currently enabled. | | `setEnabled(boolean)` | Enables or disables global voice chat. | | `playSound(Location, byte[])` | Plays raw PCM audio at a world location with default volume and distance. | | `playSound(Location, byte[], float)` | Plays audio at a location with a specified volume. | | `playSound(Location, byte[], float, float)` | Plays audio at a location with specified volume and distance. | | `playSound(Location, byte[], float, float, float)` | Plays audio at a location with specified volume, pitch, and distance. | | `resetPlayer(Player)` | Resets all voice properties for a player back to defaults. Returns a `CompletableFuture`. | | `resetAll()` | Resets all voice player data for every player. Returns a `CompletableFuture`. | | `cleanup()` | Releases resources held by the voice manager. Called during plugin shutdown. | --- ### IVoicePlayer Represents a player's voice chat state. Properties set on this interface affect how the player's voice is processed and transmitted. ```java package gg.lode.amplifierapi.api.data; public interface IVoicePlayer { UUID getUniqueId(); void setPitch(float pitch); float getPitch(); void setVolume(float volume); float getVolume(); void setDistance(float distance); float getDistance(); void setBroadcasting(boolean isBroadcasting); boolean isBroadcasting(); void setReverbIntensity(float intensity); float getReverbIntensity(); void setReverbRoomSize(float roomSize); float getReverbRoomSize(); @Deprecated void setShouldReverb(boolean shouldReverb); @Deprecated boolean shouldReverb(); void setDeafened(boolean deafened); boolean isDeafened(); @Nullable Set<UUID> getWhoCanHear(); void setWhoCanHear(@Nullable Set<UUID> whoCanHear); void addWhoCanHear(UUID uuid); void removeWhoCanHear(UUID uuid); void resetWhoCanHear(); void reset(); } ``` | Method | Description | |---|---| | `getUniqueId()` | Returns the player's UUID. | | `setPitch(float)` / `getPitch()` | Controls the pitch shift applied to this player's voice. Range: -10 to 10. | | `setVolume(float)` / `getVolume()` | Controls the volume multiplier for this player's voice. Range: 0 to 10. | | `setDistance(float)` / `getDistance()` | Controls the per-player voice distance in blocks. | | `setBroadcasting(boolean)` / `isBroadcasting()` | Controls whether the player's voice is broadcast server-wide. | | `setReverbIntensity(float)` / `getReverbIntensity()` | Controls reverb wet/dry mix (0.0–1.0). `0` = off, `1.0` = full reverb. | | `setReverbRoomSize(float)` / `getReverbRoomSize()` | Controls reverb decay length (0.0–1.0). `0.7` = medium hall. | | ~~`setShouldReverb(boolean)`~~ / ~~`shouldReverb()`~~ | **Deprecated.** Use `setReverbIntensity`/`getReverbIntensity` instead. `setShouldReverb(true)` maps to intensity `0.5`. | | `setDeafened(boolean)` / `isDeafened()` | Controls whether the player is deafened (cannot hear others). | | `getWhoCanHear()` | Returns the set of UUIDs that can hear this player. `null` means everyone can hear. An empty set means no one can hear (muted). | | `setWhoCanHear(Set<UUID>)` | Sets the explicit listener set. Pass `null` to allow everyone. | | `addWhoCanHear(UUID)` / `removeWhoCanHear(UUID)` | Adds or removes a specific player from the listener set. | | `resetWhoCanHear()` | Resets the listener set to the default (everyone). | | `reset()` | Resets all voice properties (pitch, volume, distance, broadcasting, reverb, deafened, whoCanHear) back to defaults. | --- ## Events ### PlayerMicrophoneEvent Fired each time a player transmits a voice packet through their microphone. This is an async event. ```java package gg.lode.amplifierapi.api.event; public class PlayerMicrophoneEvent extends BaseEvent { public Player player(); public VoicechatConnection connection(); public MicrophonePacketEvent event(); } ``` | Method | Return Type | Description | |---|---|---| | `player()` | `Player` | The player whose microphone is transmitting. | | `connection()` | `VoicechatConnection` | The player's voice chat connection. | | `event()` | `MicrophonePacketEvent` | The underlying Simple Voice Chat microphone packet event. | **Listening to the event:** ```java import gg.lode.amplifierapi.api.event.PlayerMicrophoneEvent; import org.bukkit.event.EventHandler; import org.bukkit.event.Listener; public class MyListener implements Listener { @EventHandler public void onMicrophone(PlayerMicrophoneEvent event) { Player player = event.player(); // Handle microphone transmission } } ``` --- ## Utility Classes ### AudioUtil Provides conversion between `float[]` and `short[]` PCM sample formats. | Method | Description | |---|---| | `floatToShort(float[])` | Converts 32-bit float PCM samples (range -1.0 to 1.0) to 16-bit short PCM samples. | | `shortToFloat(short[])` | Converts 16-bit short PCM samples to 32-bit float PCM samples. | ### SoundUtil Provides audio processing utilities. | Method | Description | |---|---| | `applyVolume(short[], float)` | Scales 16-bit PCM samples by a volume multiplier. | | ~~`applyReverb(float[], float, float)`~~ | **Deprecated.** Stateless reverb — delay lines are allocated fresh each call, causing reverb tails to cut off at packet boundaries. Use `ReverbProcessor` instead. | | `calculateLoudness(byte[])` | Calculates RMS loudness (0-100) from raw 16-bit PCM byte data. | | `calculateLoudness(byte[], boolean)` | Calculates loudness with an optional modified flag. Unmodified audio returns 0-100. Modified audio returns 101-1000. | ### ReverbProcessor Stateful Schroeder/Freeverb reverb processor that persists delay line state between audio frames. Each player should have their own instance (~23 KB memory). | Method | Description | |---|---| | `ReverbProcessor()` | Creates a new processor with zeroed delay line buffers. | | `process(float[], float, float)` | Processes a mono float PCM frame with reverb. `roomSize` (0-1) controls decay length. `wetMix` (0-1) controls reverb blend. State carries across calls for smooth tails. | | `reset()` | Zeros all delay line state. Call on player reset or cleanup. | --- ## Example: Modifying a Player's Voice ```java import gg.lode.amplifierapi.AmplifierAPI; import gg.lode.amplifierapi.api.data.IVoicePlayer; import gg.lode.amplifierapi.api.manager.IVoiceManager; public void setPlayerVoiceEffects(Player player) { IVoiceManager manager = AmplifierAPI.getApi().getVoiceManager(); manager.fetchOrCreateVoicePlayer(player).thenAccept(voicePlayer -> { voicePlayer.setPitch(2.0f); // Raise pitch voicePlayer.setVolume(1.5f); // Slightly louder voicePlayer.setReverbIntensity(0.5f); // Medium reverb voicePlayer.setReverbRoomSize(0.7f); // Medium hall voicePlayer.setDistance(100.0f); // Audible up to 100 blocks }); } ``` ## Example: Playing Positional Audio ```java import gg.lode.amplifierapi.AmplifierAPI; import org.bukkit.Location; public void playSoundAtLocation(Location location, byte[] pcmData) { AmplifierAPI.getApi().getVoiceManager().playSound( location, pcmData, 1.0f, // volume 1.0f, // pitch 48.0f // distance in blocks ); } ```