Package net.dv8tion.jda.api.audio.factory

Interface IPacketProvider

  • @NotThreadSafe
public interface IPacketProvider
    Represents the connection between a IAudioSendSystem and JDA's internal audio system, providing access to audio packets built from data provided from AudioSendHandlers.

    Note that this provider is not thread-safe!

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      VoiceChannel getConnectedChannel()
      Provides the current channel that this connection is transmitting to.
      java.lang.String getIdentifier()
      Provides a unique String identifier for the connection.
      java.net.DatagramPacket getNextPacket​(boolean changeTalking)
      Used to retrieve an audio packet to send to Discord.
      java.nio.ByteBuffer getNextPacketRaw​(boolean changeTalking)
      Used to retrieve an audio packet to send to Discord.
      java.net.InetSocketAddress getSocketAddress()
      The connected socket address for this audio connection.
      java.net.DatagramSocket getUdpSocket()
      The UDP connection for this audio connection.
      void onConnectionError​(ConnectionStatus status)
      This method is used to indicate a connection error to JDA so that the connection can be properly shutdown.
      void onConnectionLost()
      This method is used to indicate to JDA that the UDP connection has been lost, whether that be due internet loss or some other unknown reason.

    • Method Detail

      • getIdentifier

        @Nonnull
java.lang.String getIdentifier()
        Provides a unique String identifier for the connection.
        Uses shard information and specific audio connection information to build string.
        Returns:
        Never-null String unique to this audio connection.

      • getConnectedChannel

        @Nonnull
VoiceChannel getConnectedChannel()
        Provides the current channel that this connection is transmitting to.
        Returns:
        The VoiceChannel that this connection is sending to.

      • getUdpSocket

        @Nonnull
java.net.DatagramSocket getUdpSocket()
        The UDP connection for this audio connection. The DefaultSendSystem uses this socket to send audio packets to discord, and this is also the socket used to receive audio packets from discord.
        If you are implementing your own system, it is recommended that you used this connection as it is part of JDA's internal system that JDA monitors for errors and closures. It should be noted however that using this is not required to send audio packets if the developer wishes to open their own UDP socket to send from.
        Returns:
        The UDP socket connection used for audio sending.

      • getSocketAddress

        @Nonnull
java.net.InetSocketAddress getSocketAddress()
        The connected socket address for this audio connection. This can be useful for developers to open their own socket for datagram sending and allows to avoid using getNextPacket(boolean).
        Returns:
        InetSocketAddress of the current UDP connection

      • getNextPacketRaw

        @Nullable
java.nio.ByteBuffer getNextPacketRaw​(boolean changeTalking)
        Used to retrieve an audio packet to send to Discord. The packet provided is already converted to Opus and encrypted, and as such is completely ready to be sent to Discord. The changeTalking parameter is used to control whether or not the talking indicator should be changed if the AudioSendHandler cannot provide an audio packet.
        The Buffer.position() will be positioned on the start of the packet to send and the Buffer.limit() at the end of it. Use Buffer.remaining() to check the length of the packet.

        Use case for this parameter would be front-loading or queuing many audio packets ahead of send time, and if the AudioSendHandler did not have enough to fill the entire queue, you would have changeTalking set to false until the queue was empty. At that point, you would switch to true when requesting a new packet due to the fact that if one was not available, the developer would not have a packet to send, thus the logged in account is no longer "talking".

        Note: When the AudioSendHandler cannot or does not provide a new packet to send, this method will return null.

        The buffer used here may be used again on the next call to this getter, if you plan on storing the data copy it. The buffer was created using ByteBuffer.allocate(int) and is not direct.

        Parameters:
        changeTalking - Whether or not to change the talking indicator if the AudioSendHandler cannot provide a new audio packet.
        Returns:
        Possibly-null ByteBuffer containing an encoded and encrypted packet of audio data ready to be sent to discord.

      • getNextPacket

        @Nullable
java.net.DatagramPacket getNextPacket​(boolean changeTalking)
        Used to retrieve an audio packet to send to Discord. The packet provided is already converted to Opus and encrypted, and as such is completely ready to be sent to Discord. The changeTalking parameter is used to control whether or not the talking indicator should be changed if the AudioSendHandler cannot provide an audio packet.

        Use case for this parameter would be front-loading or queuing many audio packets ahead of send time, and if the AudioSendHandler did not have enough to fill the entire queue, you would have changeTalking set to false until the queue was empty. At that point, you would switch to true when requesting a new packet due to the fact that if one was not available, the developer would not have a packet to send, thus the logged in account is no longer "talking".

        Note: When the AudioSendHandler cannot or does not provide a new packet to send, this method will return null.

        Parameters:
        changeTalking - Whether or not to change the talking indicator if the AudioSendHandler cannot provide a new audio packet.
        Returns:
        Possibly-null DatagramPacket containing an encoded and encrypted packet of audio data ready to be sent to discord.

      • onConnectionError

        void onConnectionError​(@Nonnull
                       ConnectionStatus status)
        This method is used to indicate a connection error to JDA so that the connection can be properly shutdown.
        This is useful if, during setup or operation, an unrecoverable error is encountered.
        Parameters:
        status - The ConnectionStatus being reported to JDA indicating an error with connection.