Interface VoiceRecordingService

public interface VoiceRecordingService
Service managing live voice recording capture, playback to connections, audio file/URL conversion, segment slicing, and interactive physical Cassette item creation.

  • Method Details

    • init

      void init(@NotNull @NotNull de.maxhenkel.voicechat.api.VoicechatServerApi api)
      Initializes the recording service with the Simple Voice Chat server API.
      Parameters:
      api - the VoicechatServerApi instance

    • getAPI

      de.maxhenkel.voicechat.api.VoicechatServerApi getAPI()
      Gets the underlying VoicechatServerApi instance.
      Returns:
      the active API instance

    • getVoiceRecordings

      Collection<VoiceRecording> getVoiceRecordings()
      Returns all recorded voice sessions.
      Returns:
      collection of VoiceRecordings

    • getVoiceRecording

      @Nullable @Nullable VoiceRecording getVoiceRecording(@NotNull @NotNull UUID uuid)
      Retrieves a recording by its UUID.
      Parameters:
      uuid - the recording UUID
      Returns:
      the VoiceRecording, or null if not found

    • register

      void register(@NotNull @NotNull VoiceRecording voiceRecording)
      Registers a voice recording into the service registry.
      Parameters:
      voiceRecording - the recording instance

    • unregister

      void unregister(@NotNull @NotNull VoiceRecording voiceRecording)
      Unregisters a voice recording.
      Parameters:
      voiceRecording - the recording instance

    • unregister

      void unregister(@NotNull @NotNull UUID uuid)
      Unregisters a voice recording by its UUID.
      Parameters:
      uuid - the recording UUID

    • unregisterAll

      void unregisterAll()
      Clears and unregisters all voice recordings.

    • playRecordingTo

      void playRecordingTo(@NotNull @NotNull de.maxhenkel.voicechat.api.VoicechatConnection connection, @NotNull @NotNull VoiceRecording recording)
      Plays a recording to a single Simple Voice Chat connection.
      Parameters:
      connection - the target voice connection
      recording - the recording to play

    • playRecordingTo

      default void playRecordingTo(@NotNull @NotNull Collection<de.maxhenkel.voicechat.api.VoicechatConnection> connections, @NotNull @NotNull VoiceRecording recording)
      Plays a recording to multiple Simple Voice Chat connections simultaneously.
      Parameters:
      connections - target voice connections
      recording - the recording to play

    • startRecording

      VoiceRecording startRecording(@NotNull @NotNull UUID uuid)
      Starts a new live voice recording session for a speaker.
      Parameters:
      uuid - the UUID of the speaker
      Returns:
      the started VoiceRecording

    • stopRecording

      void stopRecording(@NotNull @NotNull UUID uuid)
      Stops the active voice recording session for a speaker.
      Parameters:
      uuid - the UUID of the speaker

    • linkItem

      @NotNull @NotNull org.bukkit.inventory.ItemStack linkItem(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull VoiceRecording recording)
      Binds an existing ItemStack to a voice recording.
      Parameters:
      item - the item stack to modify
      recording - the recording instance
      Returns:
      the modified ItemStack

    • linkItem

      @NotNull @NotNull org.bukkit.inventory.ItemStack linkItem(@NotNull @NotNull org.bukkit.inventory.ItemStack item, @NotNull @NotNull UUID recordingUuid)
      Binds an existing ItemStack to a voice recording UUID.
      Parameters:
      item - the item stack to modify
      recordingUuid - the recording UUID
      Returns:
      the modified ItemStack

    • createCassette

      @NotNull @NotNull org.bukkit.inventory.ItemStack createCassette(@NotNull @NotNull VoiceRecording recording)
      Generates a physical playable Cassette item for a recording.
      Parameters:
      recording - the recording instance
      Returns:
      the created Cassette ItemStack

    • createRecordingFromPcm

      CompletableFuture<VoiceRecording> createRecordingFromPcm(short @NotNull [] pcm, @NotNull @NotNull UUID speakerUuid)
      Converts raw PCM audio samples into an Opus-encoded VoiceRecording.
      Parameters:
      pcm - the 16-bit 48kHz audio samples
      speakerUuid - the author speaker UUID
      Returns:
      CompletableFuture containing the resulting VoiceRecording

    • createRecordingFromFile

      CompletableFuture<VoiceRecording> createRecordingFromFile(@NotNull @NotNull File file, @Nullable @Nullable String name)
      Asynchronously converts an external audio file into a VoiceRecording.
      Parameters:
      file - the audio file
      name - optional display name
      Returns:
      CompletableFuture containing the resulting VoiceRecording

    • createRecordingFromFile

      CompletableFuture<VoiceRecording> createRecordingFromFile(@NotNull @NotNull String fileName)
      Converts a file from the plugin `sounds/` directory into a VoiceRecording.
      Parameters:
      fileName - the filename relative to sounds directory
      Returns:
      CompletableFuture containing the resulting VoiceRecording

    • createRecordingFromUrl

      CompletableFuture<VoiceRecording> createRecordingFromUrl(@NotNull @NotNull String url, @Nullable @Nullable String name)
      Asynchronously downloads and converts an audio file from a web URL into a VoiceRecording.
      Parameters:
      url - the audio URL
      name - optional display name
      Returns:
      CompletableFuture containing the resulting VoiceRecording

    • sliceRecording

      @Nullable @Nullable VoiceRecording sliceRecording(@NotNull @NotNull UUID recordingUuid, @NotNull @NotNull Instant timestamp, @NotNull @NotNull Duration duration)
      Slices an audio segment from a recording starting at a specific timestamp.
      Parameters:
      recordingUuid - the recording UUID
      timestamp - start timestamp
      duration - duration of the slice
      Returns:
      sliced VoiceRecording, or null if not found

    • sliceRecording

      @Nullable @Nullable VoiceRecording sliceRecording(@NotNull @NotNull UUID recordingUuid, long startOffsetMs, long durationMs)
      Slices an audio segment from a recording by start offset and length in milliseconds.
      Parameters:
      recordingUuid - the recording UUID
      startOffsetMs - start offset in milliseconds
      durationMs - slice duration in milliseconds
      Returns:
      sliced VoiceRecording, or null if not found

    • sliceLastRecording

      @Nullable @Nullable VoiceRecording sliceLastRecording(@NotNull @NotNull UUID recordingUuid, @NotNull @NotNull Duration duration)
      Extracts the last duration segment of a recording.
      Parameters:
      recordingUuid - the recording UUID
      duration - duration to extract
      Returns:
      sliced VoiceRecording, or null if not found

    • sliceLastRecording

      @Nullable @Nullable VoiceRecording sliceLastRecording(@NotNull @NotNull UUID recordingUuid, long durationMs)
      Extracts the last duration in milliseconds of a recording.
      Parameters:
      recordingUuid - the recording UUID
      durationMs - milliseconds to extract
      Returns:
      sliced VoiceRecording, or null if not found

    • exportRecording

      CompletableFuture<File> exportRecording(@NotNull @NotNull UUID recordingUuid, @NotNull @NotNull AudioExportFormat format)
      Asynchronously exports a recording into an external audio file (MP3, OGG, WAV).
      Parameters:
      recordingUuid - the recording UUID to export
      format - the target audio export format
      Returns:
      CompletableFuture containing the exported File

    • exportRecording

      CompletableFuture<File> exportRecording(@NotNull @NotNull UUID recordingUuid, @NotNull @NotNull AudioExportFormat format, @Nullable @Nullable String fileName)
      Asynchronously exports a recording into an external audio file (MP3, OGG, WAV) with an optional custom filename.
      Parameters:
      recordingUuid - the recording UUID to export
      format - the target audio export format
      fileName - optional custom file name (without extension), or null to use the recording UUID
      Returns:
      CompletableFuture containing the exported File

    • exportRecording

      CompletableFuture<File> exportRecording(@NotNull @NotNull VoiceRecording recording, @NotNull @NotNull AudioExportFormat format)
      Asynchronously exports a recording into an external audio file (MP3, OGG, WAV).
      Parameters:
      recording - the recording instance to export
      format - the target audio export format
      Returns:
      CompletableFuture containing the exported File

    • exportRecording

      CompletableFuture<File> exportRecording(@NotNull @NotNull VoiceRecording recording, @NotNull @NotNull AudioExportFormat format, @Nullable @Nullable String fileName)
      Asynchronously exports a recording into an external audio file (MP3, OGG, WAV) with an optional custom filename.
      Parameters:
      recording - the recording instance to export
      format - the target audio export format
      fileName - optional custom file name (without extension), or null to use the recording UUID
      Returns:
      CompletableFuture containing the exported File

    • decodeToPcm

      short @Nullable [] decodeToPcm(@NotNull @NotNull VoiceRecording recording)
      Decodes all Opus frames of a recording into continuous 48kHz mono 16-bit PCM samples.
      Parameters:
      recording - the recording session
      Returns:
      decoded PCM samples array, or null if empty/failed