Interface VoiceFilterService

public interface VoiceFilterService
Service managing DSP voice filters, active player filter stacks, and filter chains.

  • Method Details

    • registerFilter

      void registerFilter(@NotNull @NotNull VoiceFilter filter)
      Registers a custom DSP voice filter into the registry.
      Parameters:
      filter - the filter instance to register

    • unregisterFilter

      void unregisterFilter(@NotNull @NotNull String filterId)
      Unregisters a DSP voice filter by its ID.
      Parameters:
      filterId - the identifier of the filter

    • getFilter

      @Nullable @Nullable VoiceFilter getFilter(@NotNull @NotNull String filterId)
      Retrieves a registered voice filter by its ID.
      Parameters:
      filterId - the identifier of the filter
      Returns:
      the VoiceFilter, or null if not found

    • getAvailableFilters

      @NotNull @NotNull Collection<VoiceFilter> getAvailableFilters()
      Returns all currently registered voice filters.
      Returns:
      collection of available voice filters

    • addFilter

      void addFilter(@NotNull @NotNull UUID playerUuid, @NotNull @NotNull String filterId)
      Applies an active filter to a player's outgoing voice stream.
      Parameters:
      playerUuid - the UUID of the player
      filterId - the identifier of the filter

    • removeFilter

      void removeFilter(@NotNull @NotNull UUID playerUuid, @NotNull @NotNull String filterId)
      Removes an active filter from a player.
      Parameters:
      playerUuid - the UUID of the player
      filterId - the identifier of the filter

    • clearFilters

      void clearFilters(@NotNull @NotNull UUID playerUuid)
      Clears all active filters from a player.
      Parameters:
      playerUuid - the UUID of the player

    • getActiveFilters

      @NotNull @NotNull List<VoiceFilter> getActiveFilters(@NotNull @NotNull UUID playerUuid)
      Retrieves all active filters attached to a player, ordered by priority.
      Parameters:
      playerUuid - the UUID of the player
      Returns:
      list of active VoiceFilters

    • hasActiveFilters

      boolean hasActiveFilters(@NotNull @NotNull UUID playerUuid)
      Checks whether a player has any active filters (including environmental ones).
      Parameters:
      playerUuid - the UUID of the player
      Returns:
      true if at least one filter is active

    • hasExplicitFilters

      boolean hasExplicitFilters(@NotNull @NotNull UUID playerUuid)
      Checks whether a player has any manually configured filters (excluding auto-environmental filters).
      Parameters:
      playerUuid - the UUID of the player
      Returns:
      true if at least one explicit filter is attached

    • isAutoEnvironmentEnabled

      boolean isAutoEnvironmentEnabled(@NotNull @NotNull UUID playerUuid)
      Checks whether auto-environmental filtering (underwater, caves, etc.) is enabled for a player.
      Parameters:
      playerUuid - the UUID of the player
      Returns:
      true if auto-environment is enabled

    • setAutoEnvironmentEnabled

      void setAutoEnvironmentEnabled(@NotNull @NotNull UUID playerUuid, boolean enabled)
      Toggles auto-environmental filtering for a player.
      Parameters:
      playerUuid - the UUID of the player
      enabled - whether auto-environment should be enabled

    • registerAnnotatedFilters

      @NotNull @NotNull List<VoiceFilter> registerAnnotatedFilters(@NotNull @NotNull Collection<Class<?>> classes)
      Automatically discovers, instantiates, and registers all VoiceFilter classes annotated with AutoVoiceFilter from the given collection.
      Parameters:
      classes - collection of classes to scan
      Returns:
      list of successfully instantiated and registered filters

    • reloadFilters

      void reloadFilters()
      Reloads all filters from the configuration/file filter directory.

    • getFilterDirectory

      @NotNull File getFilterDirectory()
      Returns the directory where file-based filters (.yml, .json, .java) are located.
      Returns:
      directory file

    • loadFilterFromFile

      @Nullable @Nullable VoiceFilter loadFilterFromFile(@NotNull File file)
      Loads or compiles a voice filter from a file (.yml, .json, or .java).
      Parameters:
      file - the source file
      Returns:
      the loaded voice filter, or null if loading failed

    • exportFilter

      @Nullable File exportFilter(@NotNull @NotNull String filterId, @NotNull @NotNull String format)
      Exports an existing registered filter to disk in the specified format (yml, json, java).
      Parameters:
      filterId - the identifier of the filter to export
      format - target format ("yml", "json", "java")
      Returns:
      the exported File on disk, or null if export failed or filter was not found

    • applyFilters

      short[] applyFilters(@NotNull @NotNull UUID playerUuid, short @NotNull [] samples)
      Passes raw PCM samples through the player's active filter chain and returns processed audio.
      Parameters:
      playerUuid - the UUID of the player
      samples - raw 16-bit 48kHz audio samples
      Returns:
      processed audio samples