Package de.mrjulsen.dragnsounds.api

Class ClientApi

java.lang.Object
de.mrjulsen.dragnsounds.api.ClientApi
public final class ClientApi extends Object
Contains useful methods to play and manipulate custom sounds on the client side. For server-side sound management see ServerApi.
See Also:

  • Constructor Details

    • ClientApi

      public ClientApi()

  • Method Details

    • playSound

      public static long playSound(SoundFile file, PlaybackConfig playback, Consumer<Long> responseCallback)
      Send a playSound request to the server for the given custom sound.
      Parameters:
      file - Information about the sound file. Do not create your own instance of SoundFile. Use getAllSoundFiles() instead.
      playback - Playback configuration with information such as position, volume, pitch and more.
      responseCallback - Called after the server responds with the sound id.
      Returns:
      The id of the request. (NOT the id of the sound!)

    • getSound

      public static Optional<ChannelContext> getSound(long soundId)
      Returns the current sound channel instance of the given sound.
      Parameters:
      soundId - The id of the custom sound.
      Returns:
      An optional containing the ChannelContext if available.

    • setDoppler

      public static void setDoppler(long soundId, float dopplerValue, net.minecraft.world.phys.Vec3 velocity)
      Enable the doppler effect for the given sound if the custom sound is available. If not, nothing happens.
      Parameters:
      soundId - The id of the cusotm sound.
      dopplerValue - The doppler factor.
      velocity - The velocity of the sound source.

    • setCone

      public static void setCone(long soundId, net.minecraft.world.phys.Vec3 direction, float angleA, float angleB, float outerGain)
      Define the cone in which the sound can be heard. Nothing happens if the given sound does not exist.
      Parameters:
      soundId - The id of the cusotm sound.
      direction - The doppler factor.
      angleA - The first angle of the cone.
      angleB - The second angle of the cone.
      outerGain - The gain at the outside of the cone.

    • setDirection

      public static void setDirection(long soundId, net.minecraft.world.phys.Vec3 direction)
      Set the direction of the sound source. Nothing happens if the sound does not exist.
      Parameters:
      soundId - The id of the custom sound.
      direction - The direction of the sound source.

    • setVolume

      public static void setVolume(long soundId, float volume)
      Changes the volume of the sound.
      Parameters:
      soundId - The id of the custom sound.
      volume - The new volume.

    • setPitch

      public static void setPitch(long soundId, float pitch)
      Changes the pitch of the sound.
      Parameters:
      soundId - The id of the custom sound.
      pitch - The new pitch.

    • setAttenuationDistance

      public static void setAttenuationDistance(long soundId, float distance)
      Changes the attenuation distance of the sound.
      Parameters:
      soundId - The id of the custom sound.
      distance - The new distance.

    • setPosition

      public static void setPosition(long soundId, net.minecraft.world.phys.Vec3 pos)
      Changes the position of the sound.
      Parameters:
      soundId - The id of the custom sound.
      pos - The new position.

    • isPlaying

      public static boolean isPlaying(long soundId)
      Checks if the sound is still playing.
      Parameters:
      soundId - The id of the custom sound.
      Returns:
      true when a sound with the given id is playing.

    • isAnyPlaying

      public static boolean isAnyPlaying(SoundFile file)
      Checks if the sound is still playing.
      Parameters:
      file - The custom sound file object.
      Returns:
      true when a instance of this sound is playing.

    • seek

      public static void seek(long soundId, int ticks)
      Starts playing the sound at the given number of ticks.
      Parameters:
      soundId - The id of the custom sound.
      ticks - The amount of time in ticks to skip.

    • getPlaybackData

      public static Optional<SoundPlaybackData> getPlaybackData(long soundId)
      Gets the sound playback data for the given sound id.
      Parameters:
      soundId - The sound id to get the data from.
      Returns:
      The playback data if available.

    • stopSound

      public static void stopSound(long soundId)
      Stops the currently playing sound. This method will also send a notification to the server.
      Parameters:
      soundId - The id of the custom sound.

    • stopAllSoundInstances

      public static void stopAllSoundInstances(SoundFile file)
      Stops all playing instances the given sound. This method will also send a notification to the server.
      Parameters:
      file - The sound file object of the sound.

    • uploadSound

      public static long uploadSound(String srcFilePath, SoundFile.Builder builder, AudioSettings settings, Consumer<Optional<SoundFile>> callback, BiConsumer<ClientApi.UploadProgress,ClientApi.UploadProgress> progress, Consumer<de.mrjulsen.mcdragonlib.data.StatusResult> error)
      Converts the given sound file into the ogg format and uploads it to the server.
      Parameters:
      srcFilePath - The path to the source audio file.
      builder - A Builder to define how the sound file should look like on the server (contains information such as the location, the name and more)
      settings - Settings for the sound conversion.
      callback - Called after the server returns that the upload was successfull.
      progress - Called when the progress changes. The first value is the client-side progress, the second value is the server-side progress. Both values may differ a bit.
      error - Called when an error occurs, either on the client or the server side.or if the upload was cancelled.
      Returns:
      The id of the upload. Use it to cancel the upload.

    • canCancelUpload

      public static boolean canCancelUpload(long uploadId)
      Checks if the upload can be cancelled at this moment.
      Parameters:
      uploadId - The id of the upload.
      Returns:
      true if the upload can be cancelled.

    • cancelUpload

      public static boolean cancelUpload(long uploadId)
      Cancels an active file upload. Does nothing if the upload cannot be cancelled at the moment.
      Parameters:
      uploadId - The id of the upload.
      Returns:
      true if the cancellation was successfull.

    • getAllSoundFiles

      public static void getAllSoundFiles(Collection<IFilter<SoundFile>> filters, Consumer<SoundFile[]> callback)
      Get a list of all sound files.
      Parameters:
      filters - Filter for the result.
      callback - Contains the response of the server.
      See Also:
      Impl Note:
      All used custom filters MUST be registered in the FilterRegistry first!

    • getSoundFilesAt

      public static void getSoundFilesAt(SoundLocation location, Collection<IFilter<SoundFile>> filters, Consumer<SoundFile[]> callback)
      Get a list of all sound files at the given location.
      Parameters:
      location - The location to get the sounds from.
      filters - Filter for the result.
      callback - Contains the response of the server.
      See Also:
      Impl Note:
      All used custom filters MUST be registered in the FilterRegistry first!

    • getSoundFile

      public static void getSoundFile(SoundLocation location, String id, Consumer<Optional<SoundFile>> callback)
      Get a SoundFile from the server at the given location.
      Parameters:
      location - The location where the sound is saved at.
      id - The id of the custom sound.
      callback - Contains the response of the server.

    • deleteSound

      public static void deleteSound(SoundLocation location, String id, Consumer<de.mrjulsen.mcdragonlib.data.StatusResult> callback)
      Deletes the sound at the given location.
      Parameters:
      location - The location where the sound is saved at.
      id - The id of the custom sound.
      callback - Called after the server has responded.

    • deleteSound

      public static void deleteSound(SoundFile file, Consumer<de.mrjulsen.mcdragonlib.data.StatusResult> callback)
      Deletes the sound at the given location.
      Parameters:
      file - The sound file to delete.
      callback - Called after the server has responded.

    • getFileMetadata

      public static void getFileMetadata(SoundFile file, Consumer<Map<String,String>> callback)
      Reads all metadata from the sound file.
      Parameters:
      file - The custom sound file.
      callback - Contains all the metadata from the server response.

    • showFileDialog

      public static void showFileDialog(boolean multiselect, Consumer<Optional<Path[]>> callback)
      Opens a file dialog to select one or more audio files which can then be uploaded to the server.
      Parameters:
      multiselect - Whether one or more files can be selected at once. Please note that only one file can be uploaded at once!
      callback - Called after the user has closed the dialog. If the user selected some files, their paths are then available. Otherwise the Optional is empty.