HuskyMusic — Автоматический тегер музыки

📋 Описание проекта

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

✨ Основной функционал

1. Распознавание музыки через Shazam

• Высокоточное определение треков с помощью официального Shazam API
• Автоматическое извлечение метаданных:
  • Исполнитель (artist)
  • Название композиции (title)
  • Альбом (album)
  • Обложка альбома (высокое качество)

2. Интеллектуальный поиск обложек

• Первичный поиск через Shazam
• Резервный поиск через iTunes API
• Загрузка обложек в высоком разрешении (600×600)
• Автоматическое встраивание в аудиофайл

3. Запись метаданных

• Поддержка форматов: MP3, M4A (AAC), FLAC
• Запись всех тегов: исполнитель, название, альбом
• Встраивание обложек во все поддерживаемые форматы
• Сохранение оригинального качества аудио

4. Автоматическое переименование

• Гибкие шаблоны имен файлов
• Переменные: {artist}, {title}, {album}
• Автоматическая очистка недопустимых символов
• Сохранение оригинального расширения

5. Рекурсивная обработка

• Сканирование всех вложенных папок
• Обработка больших музыкальных библиотек
• Сохранение не распознанных файлов без изменений

6. Удобный интерфейс

• Темная тема оформления (Arc theme)
• Детальный лог выполнения
• Прогресс-бар для отслеживания процесса
• Сохранение настроек между запусками
• Контекстное меню для работы с текстом

🚀 Установка и запуск

🎯 Быстрый старт (Windows)

Проект имеет автоматизированную систему развертывания:

1. Установка (один раз):

setup.bat

Скрипт автоматически:

• Проверит наличие Python 3.8+
• Создаст виртуальное окружение
• Установит все зависимости

2. Запуск:

run.bat

💡 Подсказка: Просто дважды кликните на setup.bat для первичной установки, затем используйте run.bat для запуска.

Требования

• Python 3.8 или выше (указано в runtime.txt)
• Windows / Linux / macOS
• Подключение к интернету (для распознавания треков)

Установка зависимостей (альтернативный способ)

1. Убедитесь, что Python установлен на вашем компьютере
2. Откройте командную строку (терминал) в папке проекта
3. Установите необходимые библиотеки:

pip install -r requirements.txt

Файл requirements.txt содержит все необходимые зависимости:

• mutagen — библиотека для работы с аудио метаданными
• requests — HTTP-запросы для загрузки обложек
• ttkthemes — темы оформления для GUI
• shazamio — асинхронная библиотека для распознавания через Shazam

Запуск программы

python music_tagger_gui_2.py

📖 Инструкция по использованию

Шаг 1: Настройка путей

1. Исходная папка:

   • Нажмите кнопку "Выбрать…" рядом с "Исходная папка"
   • Выберите директорию с вашими аудиофайлами
   • Программа просканирует все вложенные папки

2. Папка для вывода:

   • Нажмите кнопку "Выбрать…" рядом с "Папка для вывода"
   • Выберите директорию, куда будут сохранены обработанные файлы
   • Можно указать ту же папку, что и исходная

Шаг 2: Настройка шаблона имени

Шаблон по умолчанию: {artist} - {title}

Вы можете создать собственный шаблон, используя переменные:

• {artist} — исполнитель
• {title} — название композиции
• {album} — альбом

Примеры шаблонов:

{artist} - {title}                          # Coldplay - Fix You.mp3
{title} ({artist})                          # Fix You (Coldplay).mp3
{artist} - {album} - {title}                # Coldplay - X&Y - Fix You.mp3
[{artist}] {title}                          # [Coldplay] Fix You.mp3

Шаг 3: Сохранение настроек

1. Нажмите кнопку "Сохранить настройки"
2. Настройки сохранятся в файл config.json
3. При следующем запуске программа загрузит сохраненные параметры

Шаг 4: Запуск обработки

1. Нажмите кнопку "Начать обработку"
2. Наблюдайте за прогрессом в окне лога
3. Прогресс-бар показывает общий процент выполнения
4. Дождитесь завершения обработки

Процесс обработки каждого файла

1. Распознавание: Shazam определяет трек
2. Копирование: Файл копируется с новым именем
3. Поиск обложки: Сначала Shazam, затем iTunes (если нужно)
4. Запись тегов: Метаданные и обложка встраиваются в файл
5. Логирование: Все действия записываются в лог

📁 Структура проекта

HuskyMusic/
├── music_tagger_gui_2.py  # Основной исполняемый файл (актуальная версия)
├── music_tagger_gui.py    # Предыдущая версия
├── config.json            # Файл конфигурации (создается автоматически)
├── ffmpeg/                # Папка с FFmpeg (если требуется)
├── requirements.txt       # Список зависимостей
└── README.md             # Данная документация

⚙️ Поддерживаемые форматы

Аудиоформаты

• MP3 (.mp3) — ID3v2 теги
• M4A (.m4a) — AAC теги
• FLAC (.flac) — Vorbis теги

Форматы обложек

• JPEG (наиболее распространенный)
• PNG (поддерживается)

🔧 Технические детали

Обработка метаданных

• MP3: Использование ID3v2.4 с кодировкой UTF-8
• M4A: Поддержка атомов MP4
• FLAC: Vorbis Comments и Picture блоки

Асинхронная обработка

• Использование asyncio для работы с Shazam API
• Многопоточность для GUI (интерфейс не зависает)
• Очередь событий для безопасного обновления интерфейса

Обработка ошибок

• Автоматический пропуск нераспознанных треков
• Копирование проблемных файлов без изменений
• Подробное логирование всех ошибок

📊 Статусы в логе

⚠️ Возможные проблемы и решения

Проблема: Ошибка "ModuleNotFoundError"
Решение: Установите зависимости: pip install -r requirements.txt

Проблема: "Трек не распознан Shazam"
Решение:

• Качество аудиофайла может быть низким
• Трек редкий или локальный
• Файл будет скопирован без изменений

Проблема: "Обложка НЕ найдена"
Решение:

• Это нормально для редких треков
• Теги будут записаны без обложки
• Можно добавить обложку вручную позже

Проблема: Программа долго обрабатывает файлы
Решение:

• Это нормально — каждый файл отправляется в Shazam
• Скорость зависит от интернет-соединения
• Для 100 треков требуется примерно 10-15 минут

Проблема: Не сохраняются настройки
Решение: Проверьте права на запись в папке программы

💡 Советы по использованию

1. Сортировка результатов: Используйте шаблон {artist}/{album}/{title} для автоматической сортировки по папкам (потребуется дополнительная настройка)

2. Резервное копирование: Всегда сохраняйте копию оригинальных файлов перед обработкой

3. Интернет-соединение: Убедитесь в стабильном подключении к интернету

4. Форматы файлов: Для лучшего качества используйте FLAC

5. Пакетная обработка: Обрабатывайте файлы партиями по 50-100 штук

🎵 Примеры использования

Пример 1: Обработка новой коллекции

Исходная папка: D:/Music/Unsorted
Папка вывода: D:/Music/Tagged
Шаблон: {artist} - {title}

Пример 2: Переименование существующей библиотеки

Исходная папка: D:/Music/Library
Папка вывода: D:/Music/Library_New
Шаблон: {artist} - {album} - {title}

📄 Версии файлов

В папке находятся две версии:

• music_tagger_gui.py — базовая версия
• music_tagger_gui_2.py — актуальная версия (с Shazam)

Рекомендуется использовать music_tagger_gui_2.py

🔐 Конфиденциальность

• Программа не собирает личные данные
• Файлы обрабатываются только локально
• Сетевые запросы отправляются только к Shazam и iTunes API

📄 Лицензия

Этот проект создан для личного использования.

👤 Автор

Разработано для автоматизации тегирования музыкальных коллекций

🙏 Благодарности

• ShazamIO — за отличную асинхронную библиотеку
• Mutagen — за универсальную работу с аудио тегами
• Apple iTunes API — за доступ к базе обложек