Metadata-Version: 2.4
Name: goh-music
Version: 0.2.0
Summary: Music effects library with 3 built-in effects + developer tools
Home-page: https://github.com/devdox-del/Goh-Music
Author: devdox-del
Author-email: warek2508@gmail.com
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydub>=0.25.1
Requires-Dist: numpy>=1.21.0
Requires-Dist: imageio-ffmpeg>=0.4.8
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<div align="center">

# 🎵 Goh Music Beta v0.2

[![Version](https://img.shields.io/badge/version-0.2.0--beta-blue?style=for-the-badge)](https://github.com/devdox-del/Goh-Music)
[![Python](https://img.shields.io/badge/python-3.7+-blue?style=for-the-badge&logo=python)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-black?style=for-the-badge)](LICENSE)

**Библиотека для обработки музыки с встроенными эффектами и инструментами для разработчиков**

[Установка](#-установка) • [Быстрый старт](#-быстрый-старт) • [Эффекты](#-эффекты) • [Документация](#-документация) • [Примеры](#-примеры)

</div>

---

## ✨ Возможности

<div align="center">

| 🎸 | 🔒 | 📦 | 🎧 | ⚡ | 🛠️ |
|:---:|:---:|:---:|:---:|:---:|:---:|
| **3 эффекта** | **Лимит** | **Интеграция** | **MP3** | **FFmpeg** | **Dev Tools** |
| Встроенные | Только 3 | В ботов | Поддержка | Включен | 3 функции |

</div>

---

## 📥 Установка

```bash
# Быстрая установка через Git
pip install git+https://github.com/devdox-del/Goh-Music.git
```

**Или вручную:**

```bash
git clone https://github.com/devdox-del/Goh-Music.git
cd Goh-Music
pip install -r requirements.txt
pip install -e .
```

> 💡 **FFmpeg устанавливается автоматически** — не нужно ничего дополнительно настраивать!

---

## 🚀 Быстрый старт

<div align="center">

```python
from goh_music import MusicProcessor

processor = MusicProcessor()

# Обрабатываем музыку
processor.process_audio(
    input_path="music.mp3",
    output_path="music_reverb.mp3",
    effect_name="reverb"
)
```

</div>

---

## 🎛️ Эффекты

<div align="center">

| Иконка | Эффект | Описание | Код |
|:------:|--------|----------|-----|
| 🌊 | **Reverb** | Реверберация (эхо эффект) | `"reverb"` |
| ⚡ | **Speed Up** | Ускорение (nightcore стиль) | `"speed_up"` |
| 🔊 | **Bass Boost** | Усиление басов | `"bass_boost"` |

</div>

```python
# Показать все эффекты
effects = processor.get_available_effects()
for key, desc in effects.items():
    print(f"🎵 {key} — {desc}")
```

---

## 🛠️ Инструменты для разработчиков

### 1️⃣ `get_audio_info()` — Информация об аудио

<div align="center">

╔═══════════════════════════════════════════════════════════╗
║  📊 Получает подробные данные о файле: длительность,      ║
║     каналы, битрейт, размер и многое другое               ║
╚═══════════════════════════════════════════════════════════╝

</div>

**Пример использования:**

```python
from goh_music import MusicProcessor

processor = MusicProcessor()

# Получаем информацию о файле
info = processor.get_audio_info("song.mp3")

if info:
    print(f"""
╔════════════════════════════════════════╗
║        📊 ИНФОРМАЦИЯ О ФАЙЛЕ           ║
╠════════════════════════════════════════╣
║ ⏱  Длительность: {info['duration_formatted']:>20} ║
║ 🔊 Каналов:     {info['channels']:>20} ║
║ 📈 Битрейт:     {info['bitrate']:>20} kbps║
║ 💾 Размер:      {info['file_size_bytes'] / 1024:>18.2f} KB ║
╚════════════════════════════════════════╝
    """)
```

**Возвращаемые данные:**

```python
{
    "duration_seconds": 180.5,      # Длительность в секундах
    "duration_formatted": "03:00",  # Формат MM:SS
    "channels": 2,                   # Количество каналов
    "sample_rate": 44100,            # Частота дискретизации
    "frame_rate": 44100,             # Частота кадров
    "bitrate": 128,                  # Битрейт в kbps
    "file_size_bytes": 2890000       # Размер в байтах
}
```

---

### 2️⃣ `batch_process()` — Пакетная обработка

<div align="center">

╔═══════════════════════════════════════════════════════════╗
║  📦 Обрабатывает несколько файлов одним вызовом           ║
║     с красивым прогрессом и статистикой                   ║
╚═══════════════════════════════════════════════════════════╝

</div>

**Пример использования:**

```python
from goh_music import MusicProcessor

processor = MusicProcessor()

# Список файлов для обработки
files = ["song1.mp3", "song2.mp3", "song3.mp3"]

# Обрабатываем все файлы с эффектом
results = processor.batch_process(
    input_files=files,
    output_dir="output/",
    effect_name="reverb",
    prefix="my_"
)

# Статистика
print(f"\n✅ Успешно: {sum(results.values())}/{len(results)}")
```

**Вывод в консоль:**

```
╔═══════════════════════════════════════════════════════════╗
║     ПАКЕТНАЯ ОБРАБОТКА: 3 файлов                          ║
╠═══════════════════════════════════════════════════════════╣
║  Эффект: reverb                                           ║
║  Директория: output/                                      ║
╚═══════════════════════════════════════════════════════════╝

[1/3] Обработка: song1.mp3...
  ✅ song1.mp3 → my_song1_reverb.mp3

[2/3] Обработка: song2.mp3...
  ✅ song2.mp3 → my_song2_reverb.mp3

[3/3] Обработка: song3.mp3...
  ❌ song3.mp3

╔═══════════════════════════════════════════════════════════╗
║  ГОТОВО: 2/3 файлов успешно обработано                    ║
╚═══════════════════════════════════════════════════════════╝
```

---

### 3️⃣ `preview_effect()` — Быстрое превью

<div align="center">

╔═══════════════════════════════════════════════════════════╗
║  ⚡ Создаёт короткий фрагмент (10 сек) с эффектом         ║
║     для быстрого прослушивания перед обработкой           ║
╚═══════════════════════════════════════════════════════════╝

</div>

**Пример использования:**

```python
from goh_music import MusicProcessor

processor = MusicProcessor()

# Создаём превью (15 секунд)
preview_file = processor.preview_effect(
    input_path="long_song.mp3",
    effect_name="reverb",
    duration=15
)

if preview_file:
    print(f"🎧 Превью готово: {preview_file}")
```

**Идеально для:**

<div align="center">

| 🤖 | 📱 | ⏱️ | 💾 |
|:---:|:---:|:---:|:---:|
| **Ботов** | **Мессенджеров** | **Экономии** | **Выбора** |
| Telegram | Discord | Времени | Эффекта |

</div>

---

## 🤖 Пример для Telegram бота

```python
from aiogram import Bot, Dispatcher, types
from goh_music import MusicProcessor

bot = Bot(token="YOUR_TOKEN")
dp = Dispatcher(bot)
processor = MusicProcessor()

@dp.message_handler(content_types=['audio', 'document'])
async def handle_music(message: types.Message):
    # Скачиваем файл
    file = await message.audio.get_file()
    file_path = f"downloads/{file.file_id}.mp3"
    await file.download(file_path)
    
    # Получаем информацию
    info = processor.get_audio_info(file_path)
    
    # Показываем пользователю
    await message.reply(
        f"🎵 **Трек загружен!**\n\n"
        f"⏱ Длительность: `{info['duration_formatted']}`\n"
        f"📊 Битрейт: `{info['bitrate']}` kbps\n"
        f"💾 Размер: `{info['file_size_bytes'] / 1024:.2f}` KB\n\n"
        f"Выберите эффект:",
        reply_markup=effects_keyboard()
    )

def effects_keyboard():
    """Клавиатура с эффектами"""
    keyboard = types.ReplyKeyboardMarkup(resize_keyboard=True)
    keyboard.add(
        types.KeyboardButton("🌊 Reverb"),
        types.KeyboardButton("⚡ Speed Up"),
        types.KeyboardButton("🔊 Bass Boost")
    )
    return keyboard

@dp.message_handler(lambda msg: msg.text in ["🌊 Reverb", "⚡ Speed Up", "🔊 Bass Boost"])
async def apply_effect(message: types.Message):
    effect_map = {
        "🌊 Reverb": "reverb",
        "⚡ Speed Up": "speed_up",
        "🔊 Bass Boost": "bass_boost"
    }
    
    effect = effect_map[message.text]
    
    # Создаём превью
    preview = processor.preview_effect(
        input_path=file_path,
        effect_name=effect,
        duration=15
    )
    
    if preview:
        await message.reply_audio(
            audio=types.InputFile(preview),
            caption=f"🎧 Превью: {effect}\n\nОбработать полностью?"
        )
```

---

## 📊 Сравнение функций

<div align="center">

| Функция | Назначение | Возвращает | Пример |
|:--------|:-----------|:-----------|:-------|
| `process_audio()` | Обработка 1 файла | `bool` | `True` / `False` |
| `get_audio_info()` | Информация о файле | `dict` | `{duration, bitrate...}` |
| `batch_process()` | Обработка N файлов | `dict` | `{file: True/False...}` |
| `preview_effect()` | Превью 10 сек | `str` | `"path/to/preview.mp3"` |

</div>

---

## ⚠️ Важно

<div align="center">

╔═══════════════════════════════════════════════════════════╗
║  🔒 Библиотека поддерживает ТОЛЬКО 3 эффекта              ║
║                                                           ║
║  ❌ Попытка добавить свои эффекты вызовет ошибку:         ║
║     `NotImplementedError`                                 ║
╚═══════════════════════════════════════════════════════════╝

</div>

---

## 📝 Требования

<div align="center">

| Библиотека | Версия | Описание |
|:-----------|:------:|:---------|
| **Python** | >= 3.7 | 🐍 Язык программирования |
| **pydub** | >= 0.25.1 | 🎵 Обработка аудио |
| **numpy** | >= 1.21.0 | 🔢 Математические операции |
| **imageio-ffmpeg** | >= 0.4.8 | ⚡ FFmpeg (автоматически) |

</div>

---

## 📄 Лицензия

<div align="center">

**MIT License** — свободное использование с указанием автора

[Посмотреть лицензию](LICENSE)

</div>

---

<div align="center">

## 👤 Автор

**devdox-del**

📧 warek2508@gmail.com  
🐙 [@devdox-del](https://github.com/devdox-del)

---

## 🐛 Баги и предложения

[Создать Issue](https://github.com/devdox-del/Goh-Music/issues) • [Форк](https://github.com/devdox-del/Goh-Music/fork) • [Звезда](https://github.com/devdox-del/Goh-Music/stargazers)

---

### 📦 Goh Music v0.2.0-beta

**Сделано с** ❤️ **для разработчиков**

[Наверх](#-goh-music-beta-v02)

</div>
