pomice/docs/hdi/player.md

Use the Player class

The Player class is the class you will be interacting with the most within Pomice.

The Player class has a couple functions you will be using frequently:

• Player.add_filter()
• Player.destroy()
• Player.get_recommendations()
• Player.get_tracks()
• Player.play()
• Player.remove_filter()
• Player.reset_filters()
• Player.seek()
• Player.set_pause()
• Player.set_volume()
• Player.stop()

There are also properties the Player class has to access certain values:

:::{list-table} :header-rows: 1

• • Property
  • Type
  • Description
• • Player.bot
  • Client
  • Returns the bot associated with this player instance.
• • Player.current
  • Track
  • Returns the currently playing track.
• • Player.filters
  • Filters
  • Returns the helper class for interacting with filters.
• • Player.guild
  • Guild
  • Returns the guild associated with the player.
• • Player.is_connected
  • bool
  • Returns whether or not the player is connected.
• • Player.is_dead
  • bool
  • Returns whether the player is dead or not. A player is considered dead if it has been destroyed and removed from stored players.
• • Player.is_paused
  • bool
  • Returns whether or not the player has a track which is paused or not.
• • Player.is_playing
  • bool
  • Returns whether or not the player is actively playing a track.
• • Player.node
  • Node
  • Returns the node the player is connected to.
• • Player.position
  • float
  • Returns the player’s position in a track in milliseconds.
• • Player.adjusted_position
  • float
  • Returns the player’s position in a track in milliseconds, adjusted for rate if affected.
• • Player.adjusted_length
  • float
  • Returns the current track length in milliseconds, adjusted for rate if affected.
• • Player.rate
  • float
  • Returns the players current rate, which represents the speed of the currently playing track. This rate is affected by the Timescale filter.
• • Player.volume
  • int
  • Returns the players current volume.

:::

Getting tracks

To get tracks using Lavalink, we need to use Player.get_tracks()

You can also use Node.get_tracks() to do the same thing but without having a player.

await Player.get_tracks(...)

After you have initialized your function, we need to fill in the proper parameters:

:::{list-table} :header-rows: 1

• • Name
  • Type
  • Description
• • query
  • str
  • The string you want to search up
• • ctx
  • Optional[commands.Context]
  • Optional value which sets a Context object on the tracks you search.
• • search_type
  • SearchType
  • Enum which sets the provider to search from. Default value is SearchType.ytsearch
• • filters
  • Optional[List[Filter]]
  • Optional value which sets the filters that should apply when the track is played on the tracks you search.

:::

After you set those parameters, your function should look something like this:

await Player.get_tracks(
    query="<your query here>",
    ctx=<optional ctx object here>,
    search_type=<optional search type here>,
    filters=[<optional filters here>]
)

:::{important}

All querying of Spotify and Apple Music tracks or playlists is handled in this function if you enabled that functionality when creating your node. If you want to enable it, refer to

:::

You should get a list of Track in return after running this function for you to then do whatever you want with it. Ideally, you should be putting all tracks into some sort of a queue. If you would like to learn about how to use our queue implementation, you can refer to

Getting recommendations

To get recommendations using Lavalink, we need to use Player.get_recommendations()

You can also use Node.get_recommendations() to do the same thing without having a player.

await Player.get_recommendations(...)

After you have initialized your function, we need to fill in the proper parameters:

:::{list-table} :header-rows: 1

• • Name
  • Type
  • Description
• • track
  • Track
  • The track to fetch recommendations for
• • ctx
  • Optional[commands.Context]
  • Optional value which sets a Context object on the recommendations you fetch.

:::

After you set those parameters, your function should look something like this:

await Player.get_recommendations(
    track=<your track object here>,
    ctx=<optional ctx object here>,
)

You should get a list of Track in return after running this function for you to then do whatever you want with it. Ideally, you should be putting all tracks into some sort of a queue. If you would like to learn about how to use our queue implementation, you can refer to

Connecting a player

To connect a player to a channel you need to pass the Player class into your channel.connect() function:

await voice_channel.connect(cls=Player)

This will instance the player and make it available to your guild. If you want to access your player after instancing it, you must use either Guild.voice_client or Context.voice_client.

Controlling the player

There are a few functions to control the player:

• Player.destroy()
• Player.play()
• Player.seek()
• Player.set_pause()
• Player.set_volume()
• Player.stop()

Destroying a player

To destroy a player, we need to use Player.destroy()

await Player.destroy()

Playing a track

To play a track, we need to use Player.play()

await Player.play(...)

After you have initialized your function, we need to fill in the proper parameters:

:::{list-table} :header-rows: 1

• • Name
  • Type
  • Description
• • track
  • Track
  • The track to play
• • start
  • int
  • The time (in milliseconds) to start the track at. Default value is 0
• • end
  • int
  • The time (in milliseconds) to end the track at. Default value is 0
• • ignore_if_playing
  • bool
  • If set, ignores the current track playing and replaces it with this track. Default value is False

:::

After you set those parameters, your function should look something like this:

await Player.play(
    track=<your track object here>,
    start=<your optional start time here>,
    end=<your optional end time here>,
    ignore_if_playing=<your optional boolean here>
)

After running this function, it should return the Track you specified when running the function. This means the track is now playing.

Seeking to a position

To seek to a position, we need to use Player.seek()

await Player.seek(...)

After you have initialized your function, we need to include the position parameter, which is an amount in milliseconds:

await Player.seek(position=<your pos here>)

After running this function, your currently playing track should seek to your specified position

Pausing/unpausing the player

To pause/unpause the player, we need to use Player.set_pause()

await Player.set_pause(...)

After you have initialized your function, we need to include the pause parameter, which is a boolean:

await Player.set_pause(pause=<True/False>)

After running this function, your currently playing track should either pause or unpause depending on what you set.

Setting the player volume

To set the volume the player, we need to use Player.set_volume()

await Player.set_volume(...)

:::{important} Lavalink accept ranges from 0 to 500 for this parameter. Inputting a value either higher or lower than this amount will not work. :::

After you have initialized your function, we need to include the amount parameter, which is an integer:

await Player.set_volume(amount=<int>)

After running this function, your currently playing track should adjust in volume depending on the amount you set.

Stopping the player

To stop the player, we need to use Player.stop()

await Player.stop()

Moving the player to another channel

To move the player to another channel, we need to use Player.move_to()

await Player.move_to(...)

After you have initialized your function, we need to include the channel parameter, which is a VoiceChannel:

await Player.move_to(channel)

After running this function, your player should be in the new voice channel. All voice state updates should also be handled.

Controlling filters

Pomice has an extensive suite of filter management tools to help you make the most of Lavalink and it's filters.

Here are some of the functions you will be using to control filters:

• Player.add_filter()
• Player.remove_filter()
• Player.reset_filters()

Adding a filter

To add a filter, we need to use Player.add_filter()

await Player.add_filter(...)

After you have initialized your function, we need to fill in the proper parameters:

:::{list-table} :header-rows: 1

• • Name
  • Type
  • Description
• • filter
  • Filter
  • The filter to apply
• • fast_apply
  • bool
  • If set to True, the specified filter will apply (almost) instantly if a song is playing. Default value is False.

:::

After you set those parameters, your function should look something like this:

await Player.add_filter(
    filter=<your filter object here>,
    fast_apply=<True/False>
)

After running this function, you should see your currently playing track sound different depending on the filter you chose.

Removing a filter

To remove a filter, we need to use Player.remove_filter()

await Player.remove_filter(...)

After you have initialized your function, we need to fill in the proper parameters:

:::{list-table} :header-rows: 1

• • Name
  • Type
  • Description
• • filter
  • Filter
  • The filter to remove
• • fast_apply
  • bool
  • If set to True, the specified filter will be removed (almost) instantly if a song is playing. Default value is False.

:::

After you set those parameters, your function should look something like this:

await Player.remove_filter(
    filter=<your filter object here>,
    fast_apply=<True/False>
)

After running this function, you should see your currently playing track sound different depending on the filter you chose to remove.

Resetting all filters

To reset all filters, we need to use Player.reset_filters()

await Player.reset_filters()

After you have initialized your function, you can optionally include the fast_apply parameter, which is a boolean. If this is set to True, it'll remove all filters (almost) instantly if theres a track playing.

await Player.reset_filters(fast_apply=<True/False>)