Package com.craftmend.openaudiomc.api

Interface MediaApi

public interface MediaApi
The MediaApi is a collection of methods to interact with media, and get information about them

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    clearPreloadedMedia(Client client)
    Clear all preloaded media for a client, including entries with keepCopy set to true
    @NotNull Media
    createMedia(@NotNull String source)
    Create a new media instance with a source, and automatically translate the source (if needed) and register a normalized time for the start instant.
    static MediaApi
    getInstance()
    Get an instance of the media api.
    long
    getNormalizedCurrentEpoch()
    Get the current epoch time, but normalized to the start of the current media.
    void
    playFor(@NotNull Media media, @NotNull Client... clients)
    Play a media for a client
    void
    preloadMedia(Client client, Media media, boolean keepCopy)
    Force a client to preload a media, so it's ready to play when needed.
    void
    preloadMediaSource(Client client, String mediaSource, boolean keepCopy)
    Force a client to preload a media source, so it's ready to play when needed.
    void
    registerMutation(@NotNull String prefix, @NotNull UrlMutation mutation)
    URL mutations can be used to register custom server-side media hooks or source translators.
    void
    stopFor(int fadeTime, @NotNull Client... clients)
    Stop all media (except regions and speakers) for a client
    void
    stopFor(@NotNull Client... clients)
    Stop all media (except regions and speakers) for a client
    void
    stopFor(@NotNull String id, int fadeTime, @NotNull Client... clients)
    Stop a specific media by ID for a client
    void
    stopFor(@NotNull String id, @NotNull Client... clients)
    Stop a specific media by ID for a client
    @NotNull String
    translateSource(@NotNull String source)
    Translate server-sided aliases, playlists or other sources to a valid source.

  • Method Details

    • getInstance

      static MediaApi getInstance()
      Get an instance of the media api. May be null if the plugin is not loaded yet
      Returns:
      instance

    • createMedia

      @NotNull @NotNull Media createMedia(@NotNull @NotNull String source)
      Create a new media instance with a source, and automatically translate the source (if needed) and register a normalized time for the start instant.
      Parameters:
      source - the source of the media
      Returns:
      a new media instance

    • preloadMediaSource

      void preloadMediaSource(Client client, String mediaSource, boolean keepCopy)
      Force a client to preload a media source, so it's ready to play when needed. This will force the client to download the entire file and cache it. Once a media is played (through any method) it will look in the cache and take it from there if it's available. This method is useful for preloading media sources that are not played often, but should be ready to play at any time (like a sound effects, shows, etc). You can also make the client make a new copy after being taken by the pool so there'll always be a copy in the cache, which can be useful for frequently played media as long as you take really good care of clearing it too (to prevent memory leaks)
      Parameters:
      client - the client to preload the media for
      mediaSource - the media source to preload
      keepCopy - if the client should keep a copy of the media after being taken by the pool

    • preloadMedia

      void preloadMedia(Client client, Media media, boolean keepCopy)
      Force a client to preload a media, so it's ready to play when needed. This will force the client to download the entire file and cache it. Once a media is played (through any method) it will look in the cache and take it from there if it's available. This method is useful for preloading media sources that are not played often, but should be ready to play at any time (like a sound effects, shows, etc). You can also make the client make a new copy after being taken by the pool so there'll always be a copy in the cache, which can be useful for frequently played media as long as you take really good care of clearing it too (to prevent memory leaks)
      Parameters:
      client - the client to preload the media for
      media - the media to preload
      keepCopy - if the client should keep a copy of the media after being taken by the pool

    • clearPreloadedMedia

      void clearPreloadedMedia(Client client)
      Clear all preloaded media for a client, including entries with keepCopy set to true
      Parameters:
      client - the client to clear the preloaded media for

    • translateSource

      @NotNull @NotNull String translateSource(@NotNull @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.
      Parameters:
      source - the source to translate
      Returns:
      the translated source

    • registerMutation

      void registerMutation(@NotNull @NotNull String prefix, @NotNull @NotNull UrlMutation mutation)
      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.
      Parameters:
      prefix - the prefix to register the mutation for, the mutation will only be called for media sources starting with this prefix
      mutation - the mutation to register

    • getNormalizedCurrentEpoch

      long getNormalizedCurrentEpoch()
      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)
      Returns:
      the current epoch time, but normalized to the start of the current media

    • playFor

      void playFor(@NotNull @NotNull Media media, @NotNull @NotNull Client... clients)
      Play a media for a client
      Parameters:
      clients - Target clients
      media - Media instance

    • stopFor

      void stopFor(@NotNull @NotNull Client... clients)
      Stop all media (except regions and speakers) for a client
      Parameters:
      clients - Target clients

    • stopFor

      void stopFor(@NotNull @NotNull String id, @NotNull @NotNull Client... clients)
      Stop a specific media by ID for a client
      Parameters:
      id - Media ID
      clients - Target clients

    • stopFor

      void stopFor(@NotNull @NotNull String id, int fadeTime, @NotNull @NotNull Client... clients)
      Stop a specific media by ID for a client
      Parameters:
      id - Media ID
      fadeTime - Fade time in milliseconds
      clients - Target clients

    • stopFor

      void stopFor(int fadeTime, @NotNull @NotNull Client... clients)
      Stop all media (except regions and speakers) for a client
      Parameters:
      fadeTime - Fade time in milliseconds
      clients - Target clients