New API footprint

api/pom.xml

@@ -55,4 +55,26 @@
         </resources>
     </build>
 
+    <dependencies>
+        <dependency>
+            <groupId>org.jetbrains</groupId>
+            <artifactId>annotations</artifactId>
+            <version>24.1.0</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok-maven</artifactId>
+            <version>1.18.20.0</version>
+            <type>pom</type>
+        </dependency>
+
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <version>1.18.22</version>
+            <scope>compile</scope>
+        </dependency>
+    </dependencies>
+
 </project>

api/src/main/java/com/craftmend/openaudiomc/api/ClientApi.java

@@ -0,0 +1,33 @@
+package com.craftmend.openaudiomc.api;
+
+import com.craftmend.openaudiomc.api.clients.Client;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.Collection;
+import java.util.UUID;
+
+public interface ClientApi {
+
+    /**
+     * Get a client by a player UUID, or null if the player is not online or not registered yet
+     * @param clientUuid the UUID of the player
+     * @return the client instance, or null if the client is not connected
+     */
+    @Nullable Client getClient(String clientUuid);
+
+    /**
+     * Get all clients that are currently known to the server
+     * @return All clients
+     */
+    @NotNull
+    Collection<Client> getAllClients();
+
+    /**
+     * Check if a client is registered, and has an active web connection
+     * @param uuid the UUID of the player
+     * @return true if the player is connected, false if not or not registered
+     */
+    boolean isConnected(UUID uuid);
+
+}

api/src/main/java/com/craftmend/openaudiomc/api/MediaApi.java

@@ -0,0 +1,68 @@
+package com.craftmend.openaudiomc.api;
+
+import com.craftmend.openaudiomc.api.clients.Client;
+import com.craftmend.openaudiomc.api.media.Media;
+import com.craftmend.openaudiomc.api.media.UrlMutation;
+import org.jetbrains.annotations.NotNull;
+
+public interface MediaApi {
+
+    /**
+     * Create a new media instance with a source, and automatically translate the source
+     * (if needed) and register a normalized time for the start instant.
+     *
+     * @param source the source of the media
+     * @return a new media instance
+     */
+    @NotNull
+    Media createMedia(@NotNull String source);
+
+    /**
+     * Translate server-sided aliases, playlists or other sources to a valid source.
+     * This is automatically done by createMedia, but you might want to do this manually.
+     *
+     * @param source the source to translate
+     * @return the translated source
+     */
+    @NotNull
+    String translateSource(@NotNull String source);
+
+    /**
+     * URL mutations can be used to register custom server-side media hooks or source translators.
+     * An example use case would be a custom media server aliased by hypixel:, which can be resolved
+     * to https://hypixel.com/media/* by a mutation.
+     *
+     * @param mutation the mutation to register
+     */
+    void registerMutation(@NotNull UrlMutation mutation);
+
+    /**
+     * Get the current epoch time, but normalized to the start of the current media.
+     * This timecodes is normalized based on heartbeats from an open audio server, to eliminate
+     * timezone changes between this server and the web-client (because the player might be in a different timezone)
+     *
+     * @return the current epoch time, but normalized to the start of the current media
+     */
+    long getNormalizedCurrentEpoch();
+
+    /**
+     * Play a media for a client
+     * @param client Target client
+     * @param media Media instance
+     */
+    void playFor(@NotNull Media media, @NotNull Client... clients);
+
+    /**
+     * Stop all media (except regions and speakers) for a client
+     * @param clients Target clients
+     */
+    void stopFor(@NotNull Client... clients);
+
+    /**
+     * Stop a specific media by ID for a client
+     * @param id Media ID
+     * @param clients Target clients
+     */
+    void stopFor(@NotNull String id, @NotNull Client... clients);
+
+}

api/src/main/java/com/craftmend/openaudiomc/api/VoiceApi.java

@@ -0,0 +1,61 @@
+package com.craftmend.openaudiomc.api;
+
+import com.craftmend.openaudiomc.api.clients.Client;
+import com.craftmend.openaudiomc.api.voice.VoicePeerOptions;
+
+import java.util.UUID;
+
+public interface VoiceApi {
+
+    /*
+     * The VoiceApi contains registry, as well as control endpoints for voice-chat related features.
+     * This implementation is only available on the Spigot instance, even if the plugin is running in a BungeeCord/Velocity or Vistas network.
+     * Accessing this API on a non-spigot instance will result in undefined behavior or runtime exceptions.
+     */
+
+    /**
+     * Register a client as a voice-chat peer
+     * @param haystack The client that will be the host
+     * @param needle The client that will be the peer
+     * @return true if the client was registered, false if the client was already registered
+     */
+    boolean hasPeer(Client haystack, Client needle);
+
+    /**
+     * Register a client as a voice-chat peer
+     * @param haystack The client that will be the host
+     * @param needle The client that will be the peer
+     * @return true if the client was registered, false if the client was already registered
+     */
+    boolean hasPeer(Client haystack, UUID needle);
+
+    /**
+     * Push new options for a peer, changing how its rendered in the client
+     * @param client The web client that should receive this update
+     * @param peerToUpdate The peer that should be updated
+     * @param options The new options
+     */
+    void updatePeerOptions(Client client, Client peerToUpdate, VoicePeerOptions options);
+
+    /**
+     * Add a peer (partner) to someone's voice chat.
+     * This would let the client hear the peerToAdd as a global voice (without spatial audio/distance) until it's removed.
+     * @param client The web client that should receive this update
+     * @param peerToAdd The peer that should be added
+     * @param visible Whether the peer should be visible in the client
+     * @param mutual Whether the peer should also hear the client (repeat the call for mutual)
+     */
+    void addStaticPeer(Client client, Client peerToAdd, boolean visible, boolean mutual);
+
+    /**
+     * Remove a global peer from someone's voice chat.
+     * This would remove a static peer if they have been added through addStaticPeer, but not
+     * if they have been added through the regular voice-chat system.
+     * @param client The web client that should receive this update
+     * @param peerToRemove The peer that should be removed
+     * @param mutual Whether the peer should also stop hearing the client (repeat the call for mutual)
+     */
+    void removeStaticPeer(Client client, Client peerToRemove, boolean mutual);
+
+
+}

api/src/main/java/com/craftmend/openaudiomc/api/WorldApi.java

@@ -0,0 +1,34 @@
+package com.craftmend.openaudiomc.api;
+
+import com.craftmend.openaudiomc.api.regions.AudioRegion;
+import com.craftmend.openaudiomc.api.spakers.BasicSpeaker;
+import org.jetbrains.annotations.NotNull;
+import org.jetbrains.annotations.Nullable;
+
+import java.util.Collection;
+
+public interface WorldApi {
+
+    /**
+     * Get all regions at a location
+     * @param x x
+     * @param y y
+     * @param z z
+     * @param world world
+     * @return regions
+     */
+    @NotNull
+    Collection<AudioRegion> getRegionsAt(int x, int y, int z, @NotNull String world);
+
+    /**
+     * Get a speaker at a location, or null if invalid
+     * @param x x
+     * @param y y
+     * @param z z
+     * @param world world
+     * @return speaker
+     */
+    @Nullable
+    BasicSpeaker getSpeakerAt(int x, int y, int z, @NotNull String world);
+
+}

api/src/main/java/com/craftmend/openaudiomc/api/basic/Actor.java

@@ -0,0 +1,44 @@
+package com.craftmend.openaudiomc.api.basic;
+
+import java.util.UUID;
+
+public interface Actor {
+
+    /*
+     * An actor is a further abstraction of a User<?> from within OpenAudioMc.
+     * A user is an object representing a platform specific user whose type is given as a parameter to the user class itself.
+     * An actor is a more abstract version of this, and is used to represent any user, regardless of platform.
+     */
+
+    /**
+     * Get the name of the actor (usually the player name)
+     * @return the name of the actor
+     */
+    String getName();
+
+    /**
+     * Get the unique id of the actor (usually the player uuid)
+     * @return the unique id of the actor
+     */
+    UUID getUniqueId();
+
+    /**
+     * If the actor is an administrator (usually a player with OP if we're running on a spigot host, otherwise determined by the platform)
+     * @return if the actor is an administrator
+     */
+    boolean isAdministrator();
+
+    /**
+     * Check if the actor has a certain permission node. This uses the underlying platform's permission system if available.
+     * @param permissionNode the permission node to check for
+     * @return if the actor has the permission node
+     */
+    boolean hasPermission(String permissionNode);
+
+    /**
+     * Make the actor execute a command. This is usually a wrapper around the platform's command sender system.
+     * @param command the command to execute
+     */
+    void sendMessage(String message);
+
+}

api/src/main/java/com/craftmend/openaudiomc/api/clients/Client.java

@@ -0,0 +1,47 @@
+package com.craftmend.openaudiomc.api.clients;
+
+import com.craftmend.openaudiomc.api.basic.Actor;
+
+public interface Client {
+
+    /*
+     * A player session represents the state of an online player and its corresponding web client connection.
+     * It's used to interact with the webclient, determine and change state and hook back into the platform specific user object.
+     */
+
+    /**
+     * Get the actor of the underlying User (usually a player)
+     * @return the actor
+     */
+    Actor getActor();
+
+    /**
+     * If this client currently has the web session open
+     * @return if the client is connected
+     */
+    boolean isConnected();
+
+    /**
+     * If this session has an active voice chat instance
+     * @return if the client is in a voice chat
+     */
+    boolean hasVoicechatEnabled();
+
+    /**
+     * If this the actor's microphone is muted, false if the actor is not in a voice chat
+     * @return if the microphone is muted
+     */
+    boolean isMicrophoneMuted();
+
+    /**
+     * Get the volume of the client (media volume, 0-100, -1 if unknown or not applicable)
+     * @return the volume
+     */
+    int getVolume();
+
+    /**
+     * If the actor is currently in moderation mode
+     * @return if the actor is moderating
+     */
+    boolean isModerating();
+}