samophis.lavalink.client.entities

Interface LavaPlayer

public interface LavaPlayer

Represents a Guild-specific player instance similar to the default Lavalink Client's Link + IPlayer classes.

This is the second most important class in LavaClient after, well, LavaClient, and controls all playback/update methods + more.

Since:

0.1

Author:

SamOphis

Method Summary

Modifier and Type	Method and Description
void	addListener(samophis.lavalink.client.entities.events.AudioEventListener listener) Adds a listener to this player.
void	connect(java.lang.String session_id, java.lang.String token, java.lang.String endpoint) Sends a Voice Update to the currently set/connected AudioNode, setting the state to CONNECTED.
void	destroyPlayer() Requests the Lavalink-Server to destroy the player.
void	emitEvent(samophis.lavalink.client.entities.events.PlayerEvent event) Emits an event to all listeners attached to the player.
long	getChannelId() Fetches the ID of the Voice Channel this player is associated with.
LavaClient	getClient() Fetches the LavaClient instance this player is attached to.
AudioNode	getConnectedNode() Fetches the AudioNode this player will attempt to send data to.
java.lang.String	getEndpoint() The last Voice Server Endpoint previously used to connect to a Lavalink Node, stored by LavaClient for later use with re-connecting.
long	getGuildId() Fetches the ID of the Guild this player is associated with.
java.util.List<samophis.lavalink.client.entities.events.AudioEventListener>	getListeners() Retrieves an unmodifiable list of all the listeners attached to this player.
com.sedmelluq.discord.lavaplayer.track.AudioTrack	getPlayingTrack() Fetches the Lavaplayer AudioTrack currently playing, as updated internally by LavaClient.
long	getPosition() Fetches The position of the player.
java.lang.String	getSessionId() The last Session ID previously used to connect to a Lavalink Node, stored by LavaClient for later use with re-connecting.
State	getState() Returns the not-null current State of this player.
long	getTimestamp() Fetches the UNIX Timestamp as provided by the player update events from the Lavalink-Server.
java.lang.String	getVoiceToken() The last Voice Token previously used to connect to a Lavalink Node, stored by LavaClient for later use with re-connecting.
int	getVolume() Fetches the current volume of the player.
boolean	isPaused() Whether or not the player is currently paused.
AudioWrapper	loadTracks(java.lang.String identifier) Uses the AudioNode with the least load acting upon it to load the track(s) associated with an identifier.
void	loadTracksAsync(java.lang.String identifier, java.util.function.Consumer<AudioWrapper> callback) Asynchronously loads track(s) using the AudioNode with the least load acting upon it.
void	playTrack(com.sedmelluq.discord.lavaplayer.track.AudioTrack track) Plays a track using the best, available AudioNode.
void	playTrack(com.sedmelluq.discord.lavaplayer.track.AudioTrack track, long startTime, long endTime) Plays a track using the best, available AudioNode.
void	playTrack(java.lang.String identifier) Plays a track using the best, available AudioNode.
void	playTrack(java.lang.String identifier, long startTime, long endTime) Plays a track using the best, available AudioNode.
void	seek(long position) Skips to a certain position in a track.
void	setNode(AudioNode node) Sets the node to connect and send data to.
void	setPaused(boolean isPaused) Sets whether or not to pause playback.
void	setVolume(int volume) Sets the volume of playback.
void	stopTrack() Requests the Lavalink Server to stop playback

Method Detail

getConnectedNode

@Nullable
AudioNode getConnectedNode()

Fetches the AudioNode this player will attempt to send data to.

Returns:

The AudioNode this player will attempt to send all data to.

getPlayingTrack

@Nullable
com.sedmelluq.discord.lavaplayer.track.AudioTrack getPlayingTrack()

Fetches the Lavaplayer AudioTrack currently playing, as updated internally by LavaClient.

Returns:

The Lavaplayer AudioTrack currently playing.

getClient

@Nonnegative
LavaClient getClient()

Fetches the LavaClient instance this player is attached to.

Returns:

The LavaClient instance this player is associated with.

getListeners

@Nonnegative
java.util.List<samophis.lavalink.client.entities.events.AudioEventListener> getListeners()

Retrieves an unmodifiable list of all the listeners attached to this player.

Returns:

An unmodifiable view of every listener this player is aware of.

getState

@Nonnull
State getState()

Returns the not-null current State of this player.

Returns:

The current State of this player.

getGuildId

@Nonnegative
long getGuildId()

Fetches the ID of the Guild this player is associated with.

Returns:

The ID of the Guild this player sends and receives events for.

getChannelId

@Nonnegative
long getChannelId()

Fetches the ID of the Voice Channel this player is associated with.

Note: The Channel ID is never set internally by LavaClient as it relies on voice updates from the user. It's unreliable as it's easily forgotten to be set.

Returns:

The ID of the Voice Channel this player is connected to.

getTimestamp

@Nonnegative
long getTimestamp()

Fetches the UNIX Timestamp as provided by the player update events from the Lavalink-Server.

Returns:

The UNIX Timestamp given to the client by the Lavalink-Server.

getPosition

@Nonnegative
long getPosition()

Fetches The position of the player.

Returns:

The position of the player.

Throws:

java.lang.IllegalStateException - If the player isn't currently playing anything.

getVolume

@Nonnegative
int getVolume()

Fetches the current volume of the player.

Returns:

The current volume of the player which songs are played at.

isPaused

boolean isPaused()

Whether or not the player is currently paused.

Returns:

Whether or not the player is currently paused.

getSessionId

@Nullable
java.lang.String getSessionId()

The last Session ID previously used to connect to a Lavalink Node, stored by LavaClient for later use with re-connecting.

Returns:

The possibly-null last Session ID previously used to connect to a Lavalink Node.

getVoiceToken

@Nullable
java.lang.String getVoiceToken()

The last Voice Token previously used to connect to a Lavalink Node, stored by LavaClient for later use with re-connecting.

Returns:

The possibly-null last Voice Token previously used to connect to a Lavalink Node.

getEndpoint

@Nullable
java.lang.String getEndpoint()

The last Voice Server Endpoint previously used to connect to a Lavalink Node, stored by LavaClient for later use with re-connecting.

Returns:

The possibly-null last Voice Server Endpoint previously used to connect to a Lavalink Node.

addListener

void addListener(@Nonnull
                 samophis.lavalink.client.entities.events.AudioEventListener listener)

Adds a listener to this player.

Parameters:

listener - The non-null listener to add to the player.

Throws:

java.lang.NullPointerException - If the provided listener is null.

playTrack

void playTrack(@Nonnull
               com.sedmelluq.discord.lavaplayer.track.AudioTrack track)

Plays a track using the best, available AudioNode.

Note: Playing an AudioTrack directly saves a little bit of latency but also puts more load on the client and forces you to implement Lavaplayer on a wider scale.
It's your choice whether or not you wish to load songs remotely via an identifier or via a track. Both work perfectly and all methods do cache, removing some latency/load.
Additionally, all the playTrack methods will only play one track. Even if a search is done or a playlist is loaded, only one song is played due to the nature of music bots not being locked and uniform.

Parameters:

track - The non-null track to play.

Throws:

java.lang.NullPointerException - If the provided AudioTrack was null.

java.lang.IllegalStateException - If the player isn't currently connected to a AudioNode.

playTrack

void playTrack(@Nonnull
               com.sedmelluq.discord.lavaplayer.track.AudioTrack track,
               @Nonnegative
               long startTime,
               long endTime)

Plays a track using the best, available AudioNode.

Note: Playing an AudioTrack directly saves a little bit of latency but also puts more load on the client and forces you to implement Lavaplayer on a wider scale.
It's your choice whether or not you wish to load songs remotely via an identifier or via track. Both work perfectly and all methods do cache, removing some latency/load.

Parameters:

track - The non-null AudioTrack to play.

startTime - The starting time of the track, useful for playing only sections of a track. Leave as 0 (not negative one) to start from the beginning of the track.

endTime - The ending time of the track, useful for playing only sections of a track. Leave as -1 (not zero) to play what's left of the track from the start time.

Throws:

java.lang.NullPointerException - If the provided AudioTrack was null.

java.lang.IllegalArgumentException - If the ending time is smaller than the starting time.

java.lang.IllegalStateException - If the player isn't currently connected to a AudioNode.

playTrack

void playTrack(@Nonnull
               java.lang.String identifier)

Plays a track using the best, available AudioNode.

Note: Playing a track via an identifier adds a little bit of latency but also puts less load on the client and removes the need to implement Lavaplayer more widely.
It's your choice whether or not you wish to load songs remotely via an identifier or via a track. Both work perfectly and all methods do cache, removing some latency/load.

Parameters:

identifier - The non-null identifier from which to load an AudioTrack.

Throws:

java.lang.NullPointerException - If the provided identifier was null.

java.lang.IllegalStateException - If the player isn't currently connected to a AudioNode.

playTrack

void playTrack(@Nonnull
               java.lang.String identifier,
               @Nonnegative
               long startTime,
               long endTime)

Plays a track using the best, available AudioNode.

Note: Playing a track via an identifier adds a little bit of latency but also puts less load on the client and removes the need to implement Lavaplayer more widely.
It's your choice whether or not you wish to load songs remotely via an identifier or via a track. Both work perfectly and all methods do cache, removing some latency/load.
Additionally, all the playTrack methods will only play one track. Even if a search is done or a playlist is loaded, only one song is played due to the nature of music bots not being locked and uniform.

Parameters:

identifier - The non-null identifier from which to load an AudioTrack.

startTime - The starting time of the track, useful for playing only sections of a track. Leave as 0 (not negative one) to start from the beginning of the track.

endTime - The ending time of the track, useful for playing only sections of a track. Leave as -1 (not zero) to play what's left of the track from the start time.

Throws:

java.lang.NullPointerException - If the provided identifier was null.

java.lang.IllegalArgumentException - If the ending time is smaller than the starting time.

java.lang.IllegalStateException - If the player isn't currently connected to a AudioNode.

loadTracks

@Nonnull
AudioWrapper loadTracks(@Nonnull
                                 java.lang.String identifier)

Uses the AudioNode with the least load acting upon it to load the track(s) associated with an identifier.

Returns an AudioWrapper object which wraps search results, playlists or normal tracks into one object.

Parameters:

identifier - The not-null identifier used to actually load the tracks.

Returns:

An AudioWrapper object which contains the loaded tracks.

Throws:

java.lang.NullPointerException - If the provided identifier was null.

java.lang.IllegalStateException - If the player isn't currently connected to a AudioNode.

loadTracksAsync

void loadTracksAsync(@Nonnull
                     java.lang.String identifier,
                     @Nonnull
                     java.util.function.Consumer<AudioWrapper> callback)

Asynchronously loads track(s) using the AudioNode with the least load acting upon it.

Follow up code depending on the result MUST be run in the callback to ensure linear and properly working code. For small bots you can use the blocking loadTracks(String) method which blocks the calling thread until the response is received, allowing you to avoid callbacks at the sake of performance!

Parameters:

identifier - The not-null identifier used to actually load the tracks.

callback - The not-null callback used to actually do something with the loaded tracks.

Throws:

java.lang.NullPointerException - If the provided identifier or callback were null.

java.lang.IllegalStateException - If the player isn't currently connected to a AudioNode.

stopTrack

void stopTrack()

Requests the Lavalink Server to stop playback

Throws:

java.lang.IllegalStateException - If the player isn't currently connected to a AudioNode.

setPaused

void setPaused(boolean isPaused)

Sets whether or not to pause playback.

Fires a PlayerPauseEvent or a PlayerResumeEvent.

Parameters:

isPaused - If the player should pause.

Throws:

java.lang.IllegalStateException - If the player isn't currently connected to a AudioNode.

destroyPlayer

void destroyPlayer()

Requests the Lavalink-Server to destroy the player.

Note: It's VERY important to realize that the LavaPlayer object will maintain its state, allowing for future reconnects at the same position.

Throws:

java.lang.IllegalStateException - If the player isn't currently connected to a AudioNode.

seek

void seek(@Nonnegative
          long position)

Skips to a certain position in a track.

This method will return early if the provided position was larger than the duration of the track.

Parameters:

position - The position, in milliseconds, to skip to.

Throws:

java.lang.IllegalStateException - If the player isn't currently connected to a AudioNode.

java.lang.IllegalArgumentException - If the provided position was negative.

setVolume

void setVolume(@Nonnegative
               int volume)

Sets the volume of playback.

Note: If the provided volume is over 150, this method will return early instead of sending a volume update.

Parameters:

volume - The volume to set playback to, automatically bounded from 0 to 150 inclusive.

Throws:

java.lang.IllegalStateException - If the player isn't currently connected to a AudioNode.

java.lang.IllegalArgumentException - If the provided volume was negative.

setNode

void setNode(@Nonnull
             AudioNode node)

Sets the node to connect and send data to.

This player will attempt to disconnect from its currently-connected node if the specified node is null.

Parameters:

node - the non-null AudioNode to connect and send data to.

Throws:

java.lang.NullPointerException - If the provided AudioNode was null.

emitEvent

void emitEvent(@Nonnull
               samophis.lavalink.client.entities.events.PlayerEvent event)

Emits an event to all listeners attached to the player.

Note: This uses reflection to determine the method to fire and thus shouldn't be used quickly/abusively.

Parameters:

event - The non-null event to fire.

Throws:

java.lang.NullPointerException - If the event provided is null.

connect

void connect(@Nonnull
             java.lang.String session_id,
             @Nonnull
             java.lang.String token,
             @Nonnull
             java.lang.String endpoint)

Sends a Voice Update to the currently set/connected AudioNode, setting the state to CONNECTED.

This method shouldn't be called unless you know what you're doing. Use an EventWaiter wherever possible.

Parameters:

session_id - The not-null Session ID from the Discord VOICE_STATE_UPDATE Event.

token - The not-null Voice Token from the Discord VOICE_SERVER_UPDATE Event.

endpoint - The not-null Endpoint from the Discord VOICE_SERVER_UPDATE Event.

Throws:

java.lang.IllegalStateException - If this player is already connected to a node.

java.lang.NullPointerException - If any of the provided parameters were null.