Merge pull request #390 from Mindgamesnl/feature/api-and-channels

Add base api (voicechat)

api/.gitignore

@@ -0,0 +1,5 @@
+target/
+target/*
+.DS_Store
+test-storage/
+test-server/

api/dependency-reduced-pom.xml

@@ -0,0 +1,55 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <parent>
+    <artifactId>OpenAudioMc-Parent</artifactId>
+    <groupId>com.craftmend.openaudiomc</groupId>
+    <version>1.2</version>
+  </parent>
+  <modelVersion>4.0.0</modelVersion>
+  <artifactId>openaudiomc-api</artifactId>
+  <name>openaudiomc-api</name>
+  <version>${oa.version}</version>
+  <build>
+    <resources>
+      <resource>
+        <filtering>true</filtering>
+        <directory>src/main/resources</directory>
+      </resource>
+    </resources>
+    <finalName>openaudiomc-api</finalName>
+    <plugins>
+      <plugin>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.8.1</version>
+        <configuration>
+          <source>${java.version}</source>
+          <target>${java.version}</target>
+        </configuration>
+      </plugin>
+      <plugin>
+        <artifactId>maven-shade-plugin</artifactId>
+        <version>3.2.4</version>
+        <executions>
+          <execution>
+            <phase>package</phase>
+            <goals>
+              <goal>shade</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </plugins>
+  </build>
+  <dependencies>
+    <dependency>
+      <groupId>org.projectlombok</groupId>
+      <artifactId>lombok</artifactId>
+      <version>1.18.30</version>
+      <scope>provided</scope>
+    </dependency>
+  </dependencies>
+  <properties>
+    <java.version>1.8</java.version>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+  </properties>
+</project>

api/pom.xml

@@ -0,0 +1,73 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+    <modelVersion>4.0.0</modelVersion>
+
+    <artifactId>openaudiomc-api</artifactId>
+    <version>${oa.version}</version>
+    <packaging>jar</packaging>
+    <name>openaudiomc-api</name>
+
+    <parent>
+        <groupId>com.craftmend.openaudiomc</groupId>
+        <artifactId>OpenAudioMc-Parent</artifactId>
+        <relativePath>../pom.xml</relativePath>
+        <version>1.2</version>
+    </parent>
+
+    <properties>
+        <java.version>1.8</java.version>
+        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    </properties>
+
+    <build>
+        <finalName>openaudiomc-api</finalName>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-compiler-plugin</artifactId>
+                <version>3.8.1</version>
+                <configuration>
+                    <source>${java.version}</source>
+                    <target>${java.version}</target>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-shade-plugin</artifactId>
+                <version>3.2.4</version>
+                <executions>
+                    <execution>
+                        <phase>package</phase>
+                        <goals>
+                            <goal>shade</goal>
+                        </goals>
+                    </execution>
+                </executions>
+            </plugin>
+        </plugins>
+        <resources>
+            <resource>
+                <directory>src/main/resources</directory>
+                <filtering>true</filtering>
+            </resource>
+        </resources>
+    </build>
+
+    <dependencies>
+        <dependency>
+            <groupId>org.jetbrains</groupId>
+            <artifactId>annotations</artifactId>
+            <version>24.1.0</version>
+        </dependency>
+
+        <dependency>
+            <groupId>org.projectlombok</groupId>
+            <artifactId>lombok</artifactId>
+            <version>1.18.30</version>
+            <scope>provided</scope>
+        </dependency>
+    </dependencies>
+
+</project>

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

@@ -0,0 +1,24 @@
+package com.craftmend.openaudiomc.api;
+
+public class ApiHolder {
+
+    static ClientApi clientApiInstance;
+    static WorldApi worldApiInstance;
+    static VoiceApi voiceApiInstance;
+    static MediaApi mediaApiInstance;
+
+    public static void initiate(
+            ClientApi clientApi,
+            WorldApi worldApi,
+            VoiceApi voiceApi,
+            MediaApi mediaApi
+    ) {
+        if (clientApiInstance != null) throw new IllegalStateException("Api already initiated");
+
+        clientApiInstance = clientApi;
+        worldApiInstance = worldApi;
+        voiceApiInstance = voiceApi;
+        mediaApiInstance = mediaApi;
+    }
+
+}

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

@@ -0,0 +1,41 @@
+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 an instance of the client api. May be null if the plugin is not loaded yet
+     * @return instance
+     */
+    static ClientApi getInstance() {
+        return ApiHolder.clientApiInstance;
+    }
+
+    /**
+     * 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(UUID 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,78 @@
+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 {
+
+    /**
+     * Get an instance of the media api. May be null if the plugin is not loaded yet
+     * @return instance
+     */
+    static MediaApi getInstance() {
+        return ApiHolder.mediaApiInstance;
+    }
+
+    /**
+     * 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 prefix the prefix to register the mutation for,
+     *               the mutation will only be called for media sources starting with this prefix
+     * @param mutation the mutation to register
+     */
+    void registerMutation(@NotNull String prefix, @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,69 @@
+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 {
+
+    /**
+     * Get the voice api instance, or null if the plugin is not loaded yet
+     * @return instance
+     */
+    static VoiceApi getInstance() {
+        return ApiHolder.voiceApiInstance;
+    }
+
+    /*
+     * 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,42 @@
+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 an instance of the world api. May be null if the plugin is not loaded yet
+     * @return instance
+     */
+    static WorldApi getInstance() {
+        return ApiHolder.worldApiInstance;
+    }
+
+    /**
+     * 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);
+
+}