Music player for Discord
Project description
Документация
Навигация
Для пользователей библиотеки
Описание
dsplayer
- это библиотека для Discord ботов. Она позволяет подключаться к голосовым каналам, воспроизводить треки из различных источников и управлять очередью воспроизведения. Также она имеет плагины, которые способны расширить количество платформ.
Установка
Установить библиотеку с помощью pip из PyPi:
pip install dsplayer
Еще можно установить библиотеку с помощью pip из GitHub:
pip install git+https://github.com/FlacSy/dsplayer
Преймущества установки через PyPi это стабильность, на GitHub выкладываються последние изменения
Player
Класс Player
управляет воспроизведением аудиотреков, включая подключение к голосовым каналам, управление очередью треков, взаимодействие с плагинами. Он интегрируется с библиотекой disnake
для взаимодействия с Discord и использует собственную систему очереди и плагинов для расширения функциональности.
Атрибуты
-
queue (Queue):
Экземпляр классаQueue
, который управляет списком треков для воспроизведения в голосовом канале. -
plugin_loader (PluginLoader):
Отвечает за загрузку и взаимодействие с различными плагинами, которые могут расширять функциональность плеера. -
voice_channel (disnake.VoiceChannel):
Голосовой канал Discord, к которому подключен плеер. -
voice_client (disnake.VoiceClient):
Клиент, управляющий голосовыми соединениями в Discord. -
FFMPEG_OPTIONS (dict):
Словарь с опциями для настройки аудиопотока FFmpeg, используемого для воспроизведения треков. -
bot (commands.Bot):
Экземпляр Discord-бота, с которым связан плеер. -
deaf (bool):
Указывает, должен ли бот отключать звук у самого себя при подключении к голосовому каналу. -
engine (EngineInterface):
Поисковый движок, используемый для получения информации о треках. По умолчанию используетсяYTMusicSearchEngine
.
Методы
__init__(self, voice_channel: disnake.VoiceChannel, bot: commands.Bot, plugin_loader: PluginLoader, FFMPEG_OPTIONS: dict = {}, deaf: bool = True, engine: EngineInterface = YTMusicSearchEngine)
Инициализирует новый экземпляр Player
.
- Параметры:
voice_channel (disnake.VoiceChannel)
: Голосовой канал для подключения.bot (commands.Bot)
: Экземпляр Discord-бота.plugin_loader (PluginLoader)
: Экземпляр загрузчика плагинов.FFMPEG_OPTIONS (dict)
: Необязательно; опции FFmpeg для воспроизведения аудио.deaf (bool)
: Необязательно; указывает, должен ли бот отключать звук у самого себя.engine (EngineInterface)
: Необязательно; поисковый движок для информации о треках, по умолчаниюYTMusicSearchEngine
.
async connect(self)
Подключает плеер к указанному голосовому каналу. Если плеер уже подключен к другому каналу, он перемещается в новый.
- Вызывает: Событие
on_connect
после подключения.
async disconnect(self)
Отключает плеер от голосового канала и очищает клиент голосового канала.
- Вызывает: Событие
on_disconnect
после отключения.
async play_next(self)
Воспроизводит следующий трек в очереди. Если треков нет, вызывает ошибку.
- Исключения:
TrackNotFound
: Если очередь пуста или трек не найден.TrackError
: Если произошла ошибка во время воспроизведения.- Вызывает события
on_play
иon_error
.
asymc play_previous(self)
Воспроизводит преведущий трек в очереди. Если треков нет, вызывает ошибку.
- Исключения:
TrackNotFound
: Если очередь пуста или трек не найден.TrackError
: Если произошла ошибка во время воспроизведения.- Вызывает события
on_play
иon_error
.
track_ended(self, error)
Обрабатывает событие, когда трек завершает воспроизведение, и запускает следующий трек.
-
Параметры:
error (Exception)
: Необязательная ошибка, произошедшая во время воспроизведения.
-
Вызывает: События
on_error
иon_track_end
.
async get_player(self)
Возвращает текущий экземпляр disnake.VoiceClient
.
- Возвращает:
disnake.VoiceClient
: Текущий голосовой клиент.
async create_event(self, event_name, *args, **kwargs)
Динамически вызывает событие с указанным именем.
- Параметры:
event_name (str)
: Имя вызываемого события.*args, **kwargs
: Аргументы и именованные аргументы для события.
async add_and_play(self, track_info)
Добавляет трек в очередь и начинает его воспроизведение, если в данный момент ничего не воспроизводится.
-
Параметры:
track_info (dict)
: Информация о добавляемом треке.
-
Вызывает: Событие
on_add_to_queue
.
async stop(self)
Останавливает воспроизведение треков и очищает очередь.
- Вызывает: Событие
on_stop
.
async pause(self)
Приостанавливает текущий воспроизводимый трек.
- Вызывает: Событие
on_pause
.
async resume(self)
Возобновляет воспроизведение приостановленного трека.
- Вызывает: Событие
on_resume
.
async skip(self)
Пропускает текущий трек и начинает воспроизведение следующего в очереди.
- Вызывает: Событие
on_skip
.
async add_to_queue(self, track_info)
Добавляет трек в очередь без начала воспроизведения.
- Параметры:
track_info (dict)
: Информация о добавляемом треке.
async set_volume(self, volume: float)
Устанавливает громкость плеера.
-
Параметры:
volume (float)
: Уровень громкости (от 0.0 до 1.0).
-
Вызывает: Событие
on_volume_change
.
is_playing(self)
Проверяет, воспроизводит ли плеер в данный момент трек.
- Возвращает:
bool
:True
, если трек воспроизводится,False
в противном случае.
is_connected(self)
Проверяет, подключен ли плеер к голосовому каналу.
- Возвращает:
bool
:True
, если подключен,False
в противном случае.
update_plugin_settings(self, plugin_name: str, settings: dict) -> bool
Обновляет настройки для указанного плагина.
-
Параметры:
plugin_name (str)
: Имя плагина, для которого обновляются настройки.settings (dict)
: Новые настройки для плагина.
-
Возвращает:
bool
:True
, если настройки были успешно обновлены,False
в противном случае. -
Вызывает: Событие
on_update_plugin_settings
.
find_track_info(self, plugin_loader: PluginLoader, data: str)
Ищет информацию о треке на основе предоставленных данных с использованием доступных плагинов.
-
Параметры:
plugin_loader (PluginLoader)
: Экземпляр загрузчика плагинов.data (str)
: Поисковый запрос или URL для поиска трека.
-
Возвращает:
dict
илиlist
: Найденная информация о треке. -
Исключения:
TrackNotFound
: Если информация о треке не найдена.TrackError
: Если произошла ошибка при поиске трека.
-
Вызывает: События
on_track_search_start
,on_track_search_end
, иon_error
.
Подробный пример создания бота
В example.py вы найдете пример создания бота, использующего dsplayer
.
Плагины
В dsplayer
предусмотрены следующие плагины:
- Query - этот плагин позволяет производить поиск музыки по ее названию.
- Spotify - этот плагин позволяет искать треки, плейлисты и авторов из Spotify.
- YouTube - этот плагин позволяет искать треки из YouTube, YouTube Music, YouTube Shorts.
- SoundCloud - этот плагин позволяет искать треки, плейлисты и авторов из SoundCloud.
- Apple Music - этот плагин позволяет искать треки из Apple Music.
Поисковые движки
В dsplayer
предусмотрены следующие поисковые движки:
- YouTube Music - он имеет более низкую точность, но он быстрее, чем
SoundCloud
. - SoundCloud - он имеет точность выше, чем
YouTube Music
, но поиск может занимать 2-3+ секунды вместо 1-2. - Bandcamp - он имеет достаточно высокую точность и производительность как у
YouTube Music
⚠️ SoundCloud и Bandcamp работают на Selenium! Если вы хотите их использовать то вам нужно иметь Chrome браузер и chrome driver под ваш браузер!
Список событий
Класс Player
генерирует несколько событий через event_emitter
. Эти события можно использовать для выполнения пользовательских действий в ответ на различные состояния воспроизведения. Ниже приведен список событий и когда они генерируются:
-
on_connect
- Описание: Генерируется, когда бот успешно подключается к голосовому каналу.
- Метод:
connect
-
on_disconnect
- Описание: Генерируется, когда бот отключается от голосового канала.
- Метод:
disconnect
-
on_play
- Описание: Генерируется, когда начинается воспроизведение трека.
- Метод:
play_next
-
on_add_to_queue
- Описание: Генерируется, когда трек добавляется в очередь.
- Метод:
add_and_play
-
on_stop
- Описание: Генерируется, когда воспроизведение останавливается и очередь очищается.
- Метод:
stop
-
on_pause
- Описание: Генерируется, когда воспроизведение приостанавливается.
- Метод:
pause
-
on_resume
- Описание: Генерируется, когда воспроизведение возобновляется после паузы.
- Метод:
resume
-
on_skip
- Описание: Генерируется, когда текущий трек пропускается.
- Метод:
skip
-
on_update_plugin_settings
- Описание: Генерируется, когда настройки плагинов обновляются.
- Метод:
update_plugin_settings
-
on_track_end
- Описание: Генерируется, когда трек заканчивает воспроизводиться.
- Метод:
play_next
-
on_volume_change
- Описание: Генерируется при изменении уровня громкости.
- Метод:
set_volume
-
on_error
- Описание: Генерируется при возникновении ошибки.
- Метод:
play_next
,find_track_info
-
on_track_search_start
- Описание: Генерируется при начале поиска трека.
- Метод:
find_track_info
-
on_track_search_end
- Описание: Генерируется при завершении поиска трека.
- Метод:
find_track_info
-
on_play_previous
- Описание: Генерируеться при проигровании преведущего трека.
- Метод:
play_previous
Для разработчиков библиотеки и плагинов
Структура проекта
dsplayer/
├───engines_system
│ ├───engine_interface.py
│ ├───soundcloud.py
│ └───ytmusic.py
├───player_system
│ ├───player.py
│ ├───queue.py
│ └───__init__.py
├───plugins
│ ├───query_plugin.py
│ ├───spotify_plugin.py
│ ├───youtube_plugin.py
│ └───soundcloud_plugin.py
├───plugin_system
│ ├───plugin_interface.py
│ ├───plugin_loader.py
│ └───__init__.py
└───utils
├───user_agent.py
└───__init__.py
Создание плагинов
Для создания плагинов необходимо реализовать интерфейс PluginInterface
.
from dsplayer.plugin_system.plugin_interface import PluginInterface
from dsplayer.engines_system.engine_interface import EngineInterface
from typing import List, Dict, Any
class YourPlugin(PluginInterface):
def __init__(self):
self.name = "YourPlugin"
self.url_patterns = []
def on_plugin_load(self) -> None:
pass
def on_plugin_unload(self) -> None:
pass
def search(self, data: str, engine: EngineInterface) -> Dict[str, Any]:
# Ваша реализация
pass
def get_url_patterns(self) -> list:
return self.url_patterns
Создание поисковых движков
from dsplayer.engines_system.engine_interface import EngineInterface
class YourEngine(EngineInterface):
def get_url_by_query(query: str):
# Ваша реализация
pass
Обработка исключений
Для обработки различных ошибок используйте исключения из dsplayer.utils.exceptions.lib_exceptions
.
from dsplayer.utils.exceptions.lib_exceptions import VoiceChaneNotConnected, TrackNotFound, TrackError
try:
# Ваш код
except VoiceChaneNotConnected as e:
print(e)
except TrackNotFound as e:
print(e)
except TrackError as e:
print(e)
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.