🎵 MSOC - Библиотека для быстрого и асинхронного поиска музыки

✨ Особенности

• ⚡ Асинхронный поиск музыки
• 🔍 Поддержка нескольких источников
• 🛠️ Простое расширение новыми движками
• 📦 Легкая интеграция в проекты
• 🚀 Быстрая установка через pip
• 🖥️ TUI (Terminal User Interface) с поиском, прослушиванием и скачиванием

---

📦 Установка

Для установки библиотеки можно использовать pip:

pip install msoc

Так же можно установить из исходников:

git clone https://github.com/paranoik1/msoc.git

cd MSOC

pip install .

🚀 Использование

🖥️ TUI (Textual User Interface)

Запустите TUI для интерактивного поиска, прослушивания и скачивания музыки:

msoc --tui
# or
python -m msoc --tui

TUI позволяет:

• Искать треки по запросу
• Прослушивать треки через ffmpeg (автоопределение PulseAudio/PipeWire)
• Скачивать треки в текущую директорию
• Видеть продолжительность треков

Требование: для работы TUI нужен ffmpeg в системе. При разработке использовался ffmpeg version n8.1.2.

Эксперименты с оптимизацией

В процессе разработки я экспериментировал с тем, как уменьшить количество сетевых запросов при проигрывании. Для тестов использовал wondershaper — под Linuх он позволяет искусственно резать пропускную способность интерфейса, что удобно симулировать слабый интернет.

Сейчас воспроизведение выглядит так:

1. ffmpeg скачивает трек во временную папку (-c:a copy — без перекодирования, просто сохраняет поток как есть).
   • Для получения некоторых данных об аудио файле раньше использовался ffprobe по url аудио, что было удобно, однако присутствовала неприятная задержка. Этот метод был заменен чтением stderr ffmpeg процесса, который скачивает файл. Таким образом удается избежать дополнительной задержки
2. Второй ffmpeg читает уже локальный файл, декодирует в PCM и отправляет в sounddevice.

Загрузка и воспроизведение работают в разных потоках, поэтому не блокируют друг друга — можно начать слушать, не дожидаясь полной загрузки.

Как работает скачивание

Когда пользователь нажимает Download, логика такая:

• Если трек уже загружен во временную папку (докачался во время прослушивания) — просто копируем оттуда в текущую директорию. Никаких новых запросов в сеть.
• Если трек прямо сейчас играет, но ещё не докачался — ждём, пока фоновый ffmpeg закончит, и копируем. Пользователь видит ... на кнопке.
• Если трек не играл и не загружался — ffmpeg скачивает напрямую (-c:a copy), сохраняя в текущую папку.

💻 В консоле

usage: msoc [-h] [--tui] [--mode {fast,full}] [query]

Быстрый асинхронный поиск музыки

positional arguments:
  query               Поисковый запрос

options:
  -h, --help          show this help message and exit
  --tui               Запустить графический интерфейс (TUI)
  --mode {fast,full}  Режим поиска: fast (только первые
                      страницы) или full (все страницы)

При запуске будет выведена информация о найденных треках: Name, Artist, URL, Engine (название движка) и Meta (дополнительные метаданные).

⌨️ В коде

Импортируйте модуль msoc и используйте функцию search() для поиска музыки:

from msoc import search
import asyncio


async def main():
    query = input("Запрос: ")

    async for sound in search(query):
        print(f"Name: {sound.title}\nArtist: {sound.artist}\nURL: {sound.url}")
        print("================================================")


asyncio.run(main())

Функция search() принимает поисковый запрос и опциональный параметр mode (по умолчанию SearchMode.Fast):

• SearchMode.Fast — каждый движок выполняет только первый запрос (одна страница результатов).
• SearchMode.Full — движок пытается собрать все страницы результатов через функцию search_full. Если движок не реализует search_full, используется обычный search с предупреждением.

from msoc import search, SearchMode

async for sound in search("query", mode=SearchMode.Full):
    ...

🎶 Класс Sound

Класс Sound содержит информацию о песне.

Поле	Тип	Описание
title	str	Название песни
url	str	Ссылка на скачивание
artist	str | None	Исполнитель (опционально)
meta	dict[str, Any]	Дополнительные метаданные (по умолчанию {})
_engine	str | None	Движок-источник, заполняется автоматически

🔌 Реализованные движки поиска

В настоящее время библиотека MSOC поддерживает следующие движки поиска:

• zaycev_net: Поиск на сайте zaycev.net
• hitmo: Поиск на сайте rus.hitmotop.com - реализован на основе данного кода от Ushiiro82
• muzbomb: Поиск на сайте muzbomb.net - создан takilow

Движки загружаются автоматически при импорте пакета msoc.

❌ Exceptions

Библиотека MSOC определяет следующие исключения:

• LoadedEngineNotFoundError: Выбрасывается, когда движок поиска не был найден в загруженных движках.

🛠️ Создание своих поисковых движков

Для создания собственных поисковых движков на Python вы можете использовать следующий подход:

1. Создайте новый Python-файл для вашего поискового движка:

   • Например, создайте файл my_search_engine.py.

2. Определите асинхронную функцию search(query), которая будет реализовывать поисковый алгоритм:

   • Реализуйте логику поиска, взаимодействуя с API или веб-страницами источников, которые вы хотите использовать.
   • Можете использовать библиотеки, такие как aiohttp, beautifulsoup4 и другие, для выполнения HTTP-запросов и парсинга HTML-страниц.

Для поддержки режима Mode.Full движок может реализовать функцию search_full(query) с той же сигнатурой, что и search. Она должна проходить по всем страницам результатов. Если search_full не определена, Mode.Full просто использует search (одна страница).

Функция search внутри движка должна возвращать генератор объектов Sound.
Пример реализации функции search(query) в my_search_engine.py:

import aiohttp
from bs4 import BeautifulSoup

from msoc.sound import Sound


async def search(query: str):
    async with aiohttp.ClientSession() as session:
        async with session.get(f"https://example.com/search?q={query}") as response:
            html = await response.text()

    soup = BeautifulSoup(html, "html.parser")

    for item in soup.find_all("div", class_="search-result"):
        name = item.find("h3").get_text(strip=True)
        artist = item.find("span", class_="artist").get_text(strip=True)
        url = item.find("a").get("href")
        yield Sound(name, url, artist)

3. Подключите ваш поисковый движок к системе:

from msoc import register_engine, get_engines

import my_search_engine


register_engine("my_search_engine", my_search_engine)
print(get_engines())

• Замените my_search_engine на название вашего python файла.
• Далее вызываем get_engines(), чтобы удостовериться, что движок был успешно загружен

4. Теперь при запуске основной search функции, ваш движок будет автоматически загружен и использован для поиска песен

ℹ️ P.S 1

Если вам нужно подключить поисковой движок, файл которого находится не в текущей папке проекта, можете воспользоваться встроенным python пакетом importlib

from msoc import register_engine
from importlib import util

spec = util.spec_from_file_location("my_search_engine", "/path/to/python/file/my_search_engine.py")
module = util.module_from_spec(spec)

spec.loader.exec_module(module)


register_engine("my_search_engine", module)

ℹ️ P.S 2

Если вам не нужен какой либо поисковой движок, используй unload_search_engine для его удаления из загруженных:

from msoc import unload_search_engine, engines

unload_search_engine("my_search_engine")
print(engines())

ℹ️ P.S 3 — Проверка доступности сервиса

Проверка доступности теперь лежит на самом движке. Если сайт недоступен, движок должен сам обработать ошибку в search() (логирование, возврат пустого результата и т.д.). msoc не делает отдельного запроса для проверки — лишний сетевой вызов только замедляет поиск. Переменная URL в модуле движка теперь используется только как константа внутри самого движка.

🤝 Contribution

Если вы хотите внести свой вклад в развитие библиотеки MSOC, вы можете:

• 🐞 Сообщить об ошибках или предложить новые функции
• 🎛️ Разработать и добавить новые движки поиска
• 📖 Улучшить документацию
• 🔧 Исправить существующие проблемы