Mapperatorinator

Попробуйте генеративную модель здесь или MaiMod здесь. Посмотрите видео-презентацию здесь.

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

Этот проект построен на базе osuT5 и osu-diffusion. В процессе разработки я потратил около 2500 часов вычислений на GPU в 142 прогонах на своей 4060 Ti и арендованных экземплярах 4090 через vast.ai.

#### Используйте этот инструмент ответственно. Всегда указывайте использование ИИ в ваших битмапах.

Установка

Инструкция ниже позволяет генерировать битмапы на вашем локальном компьютере, либо вы можете запустить её в облаке с помощью colab notebook.

1. Клонируйте репозиторий

git clone https://github.com/OliBomby/Mapperatorinator.git
cd Mapperatorinator

2. (Опционально) Создайте виртуальное окружение

Используйте Python 3.10, более поздние версии могут быть несовместимы с зависимостями.

python -m venv .venv
In cmd.exe
.venv\Scripts\activate.bat
In PowerShell
.venv\Scripts\Activate.ps1
In Linux or MacOS
source .venv/bin/activate

3. Установите зависимости

• Python 3.10
• Git
• ffmpeg
• CUDA (для видеокарт NVIDIA) или ROCm (для видеокарт AMD на Linux)
• PyTorch: Обязательно следуйте руководству Get Started, чтобы установить torch и torchaudio с поддержкой GPU. Выберите правильную версию Compute Platform, которую вы установили на предыдущем этапе.
• и остальные зависимости Python:

pip install -r requirements.txt

Веб-интерфейс (рекомендуется)

Для более удобного использования рекомендуется воспользоваться веб-интерфейсом. Он предоставляет графический интерфейс для настройки параметров генерации, запуска процесса и мониторинга результата.

Запуск графического интерфейса

Перейдите в склонированную директорию Mapperatorinator в вашем терминале и выполните:

python web-ui.py

Это запустит локальный веб-сервер и автоматически откроет пользовательский интерфейс в новом окне.

Использование графического интерфейса

• Настроить: Укажите пути для входных/выходных данных с помощью полей формы и кнопок "Обзор". Отрегулируйте параметры генерации, такие как игровой режим, сложность, стиль (год, ID маппера, дескрипторы), тайминг, специфические функции (звуки ударов, супер-тайминг) и другие, аналогично опциям командной строки. (Примечание: если вы укажете beatmap_path, интерфейс автоматически определит audio_path и output_path, поэтому эти поля можно оставить пустыми)
• Запуск: Нажмите кнопку "Запустить инференс", чтобы начать генерацию карты.
• Отмена: Вы можете остановить текущий процесс, используя кнопку "Отменить инференс".
• Открыть выходные данные: После завершения используйте кнопку "Открыть папку с результатами" для быстрого доступа к сгенерированным файлам.

Веб-интерфейс служит удобной оболочкой вокруг скрипта inference.py. Для расширенных опций или устранения неполадок обратитесь к инструкциям для командной строки.

Инференс через командную строку

Для пользователей, предпочитающих командную строку или нуждающихся в расширенных настройках, выполните следующие шаги. Примечание: для более простого графического интерфейса смотрите раздел Веб-интерфейс (Рекомендуется) выше.

Запустите inference.py и передайте аргументы для генерации карт. Для этого используйте синтаксис переопределения Hydra. Все доступные параметры смотрите в configs/inference_v29.yaml.

python inference.py \
  audio_path           [Path to input audio] \
  output_path          [Path to output directory] \
  beatmap_path         [Path to .osu file to autofill metadata, and output_path, or use as reference] \
  
  gamemode             [Game mode to generate 0=std, 1=taiko, 2=ctb, 3=mania] \
  difficulty           [Difficulty star rating to generate] \
  mapper_id            [Mapper user ID for style] \
  year                 [Upload year to simulate] \
  hitsounded           [Whether to add hitsounds] \
  slider_multiplier    [Slider velocity multiplier] \
  circle_size          [Circle size] \
  keycount             [Key count for mania] \
  hold_note_ratio      [Hold note ratio for mania 0-1] \
  scroll_speed_ratio   [Scroll speed ratio for mania and ctb 0-1] \
  descriptors          [List of beatmap user tags for style] \
  negative_descriptors [List of beatmap user tags for classifier-free guidance] \
  
  add_to_beatmap       [Whether to add generated content to the reference beatmap instead of making a new beatmap] \
  start_time           [Generation start time in milliseconds] \
  end_time             [Generation end time in milliseconds] \
  in_context           [List of additional context to provide to the model [NONE,TIMING,KIAI,MAP,GD,NO_HS]] \
  output_type          [List of content types to generate] \
  cfg_scale            [Scale of the classifier-free guidance] \
  super_timing         [Whether to use slow accurate variable BPM timing generator] \
  seed                 [Random seed for generation] \

Пример:

python inference.py beatmap_path="'C:\Users\USER\AppData\Local\osu!\Songs\1 Kenji Ninuma - DISCO PRINCE\Kenji Ninuma - DISCOPRINCE (peppy) [Normal].osu'" gamemode=0 difficulty=5.5 year=2023 descriptors="['jump aim','clean']" in_context=[TIMING,KIAI]

Интерактивный CLI

Для тех, кто предпочитает работу в терминале, но хочет получить пошаговую настройку, интерактивный скрипт CLI является отличной альтернативой веб-интерфейсу.

Запуск CLI

Перейдите в склонированную директорию. Возможно, сначала потребуется сделать скрипт исполняемым.

# Make the script executable (only needs to be done once)
chmod +x cli_inference.sh

# Run the script
./cli_inference.sh

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

Скрипт проведет вас через серию подсказок для настройки всех параметров генерации, так же, как и Web UI.

Он использует цветовую кодировку для удобства восприятия. Предоставляет расширенное многоуровневое меню для выбора дескрипторов стиля с помощью стрелок и пробела. После ответа на все вопросы, он покажет итоговую команду для вашего просмотра. Далее вы можете подтвердить выполнение команды напрямую или отменить и скопировать команду для ручного использования.

Советы по генерации

• Вы можете редактировать configs/inference_v29.yaml и добавлять свои аргументы туда, вместо того чтобы вводить их в терминале каждый раз.
• Все доступные дескрипторы можно найти здесь.
• Всегда указывайте год в диапазоне от 2007 до 2023. Если оставить его неизвестным, модель может сгенерировать неконсистентный стиль.
• Всегда указывайте сложность. Если оставить ее неизвестной, модель может сгенерировать неконсистентную сложность.
• Увеличьте параметр cfg_scale, чтобы повысить эффективность аргументов mapper_id и descriptors.
• Можно использовать аргумент negative_descriptors, чтобы направить модель в сторону от определённых стилей. Это работает только при cfg_scale > 1. Убедитесь, что число негативных дескрипторов равно числу обычных дескрипторов.
• Если стиль вашей песни и желаемый стиль карты плохо совпадают, модель может не следовать вашим указаниям. Например, сложно сгенерировать карту с высоким SR и SV для спокойной песни.
• Если у вас уже готовы тайминги и моменты кайаи для песни, вы можете передать это модели для значительного ускорения и повышения точности вывода: используйте аргументы beatmap_path и in_context=[TIMING,KIAI].
• Чтобы перемапить только часть карты, используйте beatmap_path, start_time, end_time и add_to_beatmap=true.
• Для генерации гостевой сложности для карты используйте beatmap_path и in_context=[GD,TIMING,KIAI].
• Для генерации hitsounds для карты используйте beatmap_path и in_context=[NO_HS,TIMING,KIAI].
• Для генерации только тайминга для песни используйте super_timing=true и output_type=[TIMING].

MaiMod: инструмент моддинга на базе ИИ

MaiMod — это инструмент моддинга для osu! карт, который использует предсказания Mapperatorinator для поиска потенциальных ошибок и несоответствий, которые не могут быть найдены другими автоматическими инструментами, такими как Mapset Verifier. Он может обнаруживать такие проблемы, как:

• Неправильная привязка или ритмические паттерны
• Неточные тайминговые точки
• Неконсистентные позиции объектов и новые комбо
• Странные формы слайдеров
• Неконсистентные hitsounds или громкости

Вы можете попробовать MaiMod здесь или запустить его локально: Для локального запуска MaiMod вам нужно установить Mapperatorinator. Затем запустите скрипт mai_mod.py, указав путь к вашей карте с помощью аргумента beatmap_path.

python mai_mod.py beatmap_path="'C:\Users\USER\AppData\Local\osu!\Songs\1 Kenji Ninuma - DISCO PRINCE\Kenji Ninuma - DISCOPRINCE (peppy) [Normal].osu'"

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

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

MaiMod GUI

Чтобы запустить MaiMod Web UI, вам потребуется установить Mapperatorinator. Затем запустите скрипт mai_mod_ui.py. Это запустит локальный веб-сервер и автоматически откроет интерфейс в новом окне:

python mai_mod_ui.py

Обзор

Токенизация

Mapperatorinator преобразует beatmap-ы osu! в промежуточное представление событий, которое может быть напрямую преобразовано в токены и обратно. Включает объекты попадания, звуки попадания, скорости слайдеров, новые комбо, точки тайминга, времена кияи, а также скорости прокрутки для taiko/mania.

Вот небольшой пример процесса токенизации:

Для уменьшения размера словаря временные события квантованы с шагом 10 мс, а координаты позиции — по сетке с шагом 32 пикселя.

Архитектура модели

Модель представляет собой оболочку вокруг HF Transformers Whisper, с пользовательскими входными встраиваниями и функцией потерь. Размер модели составляет 219M параметров. Эта модель оказалась быстрее и точнее, чем T5 для данной задачи.

Высокоуровневый обзор входа-выхода модели следующий:

В качестве входа энкодера модель использует кадры Mel-спектрограммы, по одному кадру на позицию входа. На каждом шаге выход декодера — это softmax распределение по дискретному, предопределённому, словарю событий. Выходы разрежены, события нужны только при появлении hit-object, вместо аннотирования каждого аудиокадра.

Формат мультизадачного обучения

Перед SOS-токеном идут дополнительные токены, которые способствуют условному порождению. Эти токены включают игровой режим, сложность, ID маппера, год и другую метаинформацию. Во время обучения эти токены не имеют соответствующих меток, поэтому модель никогда их не выводит. Также во время обучения есть случайная вероятность замены мета-токена на токен 'unknown', чтобы во время инференса можно было использовать эти 'unknown'-токены для уменьшения объёма метаинформации, которую нужно передавать модели.

Бесшовная длинная генерация

Длина контекста модели составляет 8.192 секунды. Этого явно недостаточно для генерации полного beatmap-а, поэтому песню приходится делить на несколько окон и генерировать beatmap частями. Чтобы в сгенерированном beatmap-е не было заметных швов между окнами, мы используем перекрытие 90% и генерируем окна последовательно. Каждое окно генерации, кроме первого, начинается с декодера, предварительно заполненного до 50% окна токенами из предыдущих окон. Мы используем процессор логитов, чтобы убедиться, что модель не может генерировать временные токены, находящиеся в первых 50% окна генерации. Кроме того, последние 40% окна генерации зарезервированы для следующего окна. Любые сгенерированные временные токены в этом диапазоне рассматриваются как токены EOS. Это гарантирует, что каждый сгенерированный токен зависит как минимум от 4 секунд предыдущих токенов и 3,3 секунд будущего аудио для предсказания.

Чтобы предотвратить смещение оффсета при длительной генерации, случайные смещения были добавлены к временным событиям в декодере во время обучения. Это заставляет его корректировать ошибки синхронизации, ориентируясь на появления в аудио, и приводит к стабильно точному оффсету.

Уточнённые координаты с помощью диффузии

Координаты позиций, генерируемые декодером, квантуются по сетке из 32 пикселей, поэтому после этого мы используем диффузию для удаления шума из координат до финальных положений. Для этого мы обучили модифицированную версию osu-diffusion, специализированную только на последних 10% расписания шума, и поддерживающую более сложные метаданные токены, которые использует Mapperatorinator для условной генерации.

Поскольку модель Mapperatorinator выдаёт SV слайдеров, требуемая длина слайдера фиксирована вне зависимости от формы траектории управляющих точек. Поэтому мы пытаемся направлять процесс диффузии так, чтобы создавать координаты, соответствующие требуемым длинам слайдеров. Мы делаем это, пересчитывая конечные позиции слайдера после каждого шага диффузии на основе требуемой длины и текущей траектории управляющих точек. Это означает, что процесс диффузии не имеет прямого контроля над конечными позициями слайдера, но всё ещё может влиять на них, изменяя траекторию управляющих точек.

Постобработка

Mapperatorinator выполняет дополнительную постобработку для повышения качества сгенерированной карты битов:

• Уточнение координат позиции с помощью диффузии.
• Привязка временных событий к ближайшему тиканью с использованием snap-делителей, сгенерированных моделью.
• Привязка почти идеальных позиционных наложений.
• Преобразование событий колонок mania в X-координаты.
• Генерация путей слайдеров для таико-драмроллов.
• Исправление больших расхождений между требуемой длиной слайдера и длиной пути управляющих точек.

Генератор супер-синхронизации

Генератор супер-синхронизации — это алгоритм, который повышает точность и аккуратность сгенерированного тайминга, вычисляя тайминг для всей песни 20 раз и усредняя результаты. Это полезно для песен с переменным BPM или с изменениями BPM. Результат практически идеален, лишь иногда требуется ручная корректировка отдельного участка.

Обучение

Инструкция ниже создаёт среду для обучения на вашем локальном компьютере.

1. Клонируйте репозиторий

git clone https://github.com/OliBomby/Mapperatorinator.git
cd Mapperatorinator

2. Создайте набор данных

Создайте свой собственный набор данных с помощью консольного приложения Mapperator. Для этого потребуется OAuth-токен клиента osu! для проверки битмапов и получения дополнительных метаданных. Поместите набор данных в каталог datasets рядом с каталогом Mapperatorinator.

Mapperator.ConsoleApp.exe dataset2 -t "/Mapperatorinator/datasets/beatmap_descriptors.csv" -i "path/to/osz/files" -o "/datasets/cool_dataset"

3. (Необязательно) Настройка Weight & Biases для логирования

Создайте аккаунт на Weight & Biases и получите ваш API-ключ в настройках аккаунта. Затем установите переменную окружения WANDB_API_KEY, чтобы процесс обучения знал, куда логировать.

export WANDB_API_KEY=

4. Создайте контейнер Docker

Обучение в вашем venv также возможно, но мы рекомендуем использовать Docker на WSL для лучшей производительности.

docker compose up -d --force-recreate
docker attach mapperatorinator_space
cd Mapperatorinator

5. Настройте параметры и начните обучение

Все конфигурации находятся в ./configs/train/default.yaml. Убедитесь, что правильно указали train_dataset_path и test_dataset_path для вашего набора данных, а также начальные и конечные индексы mapset для разделения на обучающую и тестовую выборки. Путь является локальным для контейнера Docker, поэтому если вы поместили свой набор данных с именем cool_dataset в директорию datasets, то путь должен быть /workspace/datasets/cool_dataset.

Рекомендую создать собственный файл конфигурации, который будет переопределять настройки по умолчанию, чтобы у вас была запись вашей конфигурации обучения для воспроизводимости.

data:
  train_dataset_path: "/workspace/datasets/cool_dataset"
  test_dataset_path: "/workspace/datasets/cool_dataset"
  train_dataset_start: 0
  train_dataset_end: 90
  test_dataset_start: 90
  test_dataset_end: 100

Begin training by calling python osuT5/train.py or torchrun --nproc_per_node=NUM_GPUS osuT5/train.py for multi-GPU training.

python osuT5/train.py -cn train_v29 train_dataset_path="/workspace/datasets/cool_dataset" test_dataset_path="/workspace/datasets/cool_dataset" train_dataset_end=90 test_dataset_start=90 test_dataset_end=100

6. Дообучение с помощью LoRA

Вы также можете дообучить предварительно обученную модель с помощью LoRA, чтобы адаптировать её к определённому стилю или режиму игры. Для этого адаптируйте configs/train/lora.yaml под свои нужды и запустите конфигурацию обучения lora:

python osuT5/train.py -cn lora train_dataset_path="/workspace/datasets/cool_dataset" test_dataset_path="/workspace/datasets/cool_dataset" train_dataset_end=90 test_dataset_start=90 test_dataset_end=100

Важные параметры LoRA, которые следует учитывать:

• pretrained_path: Путь или HF-репозиторий базовой модели для дообучения.
• r: Ранг матриц LoRA. Более высокие значения увеличивают ёмкость модели, но также потребление памяти.
• lora_alpha: Масштабирующий коэффициент для обновлений LoRA.
• total_steps: Общее количество шагов обучения. Балансируйте в зависимости от размера вашего датасета.
• enable_lora: Использовать LoRA или полноценно дообучать модель.

Во время инференса вы можете указать веса LoRA с помощью аргумента lora_path. Это может быть локальный путь или репозиторий Hugging Face.

См. также

• Mapper Classifier
• RComplexion

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

Особая благодарность:

• Авторам osuT5 за их обучающий код.
• Команде Hugging Face за их инструменты.
• Jason Won и Richard Nagyfi за обмен идеями.
• Marvin за предоставление кредитов на обучение.
• Сообществу osu! за битмапы.

Связанные работы

• osu! Beatmap Generator от Syps (Nick Sypteras)
• osumapper от kotritrona, jyvden, Yoyolick (Ryan Zmuda)
• osu-diffusion от OliBomby (Olivier Schipper), NiceAesth (Andrei Baciu)
• osuT5 от gyataro (Xiwen Teoh)
• Beat Learning от sedthh (Richard Nagyfi)
• osu!dreamer от jaswon (Jason Won)

--- Tranlated By Open Ai Tx | Last indexed: 2026-01-24 ---