Web Analytics

Mapperatorinator

⭐ 381 stars Japanese by OliBomby

Mapperatorinator

ジェネレーティブモデルをこちらで、またはMaiModをこちらで試せます。動画デモはこちらをご覧ください。

Mapperatorinatorはスペクトログラム入力を使用して、全ゲームモード向けの完全な機能を備えたosu!ビートマップを生成し、アシストモッディングビートマップを行うマルチモデルフレームワークです。 このプロジェクトの目標は、任意の楽曲から高いカスタマイズ性を持つランク可能な品質のosu!ビートマップを自動生成することです。

このプロジェクトはosuT5とosu-diffusionをベースにしています。開発には、私の4060 Tiとvast.aiでレンタルした4090インスタンスを用いて、142回の実行で約2500時間のGPU計算を費やしました。

#### このツールは責任を持って使用してください。ビートマップにAIの使用を必ず明示してください。

インストール

以下の手順でローカルマシンでビートマップを生成できます。代わりにColabノートブックでクラウド上で実行することも可能です。

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. 依存関係のインストール

pip install -r requirements.txt

Web GUI（推奨）

よりユーザーフレンドリーな体験のために、Web UIの使用を検討してください。生成パラメータの設定、プロセスの開始、出力の監視を行うグラフィカルインターフェースを提供します。

GUIの起動

ターミナルでクローンした Mapperatorinator ディレクトリに移動し、以下を実行します：

python web-ui.py

これはローカルのウェブサーバーを起動し、新しいウィンドウでUIを自動的に開きます。

GUIの使用方法

Web UIはinference.pyスクリプトの便利なラッパーとして機能します。高度なオプションやトラブルシューティングにはコマンドラインの説明を参照してください。

python_u3zyW0S3Vs

コマンドライン推論

コマンドラインを好むユーザーや高度な設定が必要な場合は、以下の手順に従ってください。注：より簡単なグラフィカルインターフェースについては、上記のWeb UI（推奨）セクションを参照してください。

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スクリプトがWeb UIの優れた代替手段です。

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と同様にすべての生成パラメータを設定するための一連のプロンプトを案内します。

わかりやすさのために色分けされたインターフェースを使用します。 矢印キーとスペースバーを使ってスタイル記述子を選択する高度なマルチセレクトメニューを提供します。 すべての質問に答えると、最終的なコマンドを表示して確認できます。 その後、直接実行を確認するか、キャンセルして手動で使用するためにコマンドをコピーできます。

生成のヒント

MaiMod：AI駆動のモッディングツール

MaiModは、Mapperatorinatorの予測を使用して、Mapset Verifierのような他の自動モッディングツールでは検出できない潜在的な欠陥や不整合を見つけるosu!ビートマップ用のモッディングツールです。 検出可能な問題例：

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スクリプトを実行します。これによりローカルのウェブサーバーが起動し、新しいウィンドウでUIが自動的に開きます：

python mai_mod_ui.py
afbeelding

概要

トークン化

Mapperatorinatorはosu!のビートマップを、中間のイベント表現に変換します。これにより、直接トークンに変換したり、トークンから復元したりできます。 この表現にはヒットオブジェクト、ヒットサウンド、スライダー速度、新しいコンボ、タイミングポイント、キアイタイム、太鼓/マニアのスクロール速度が含まれます。

トークン化プロセスの簡単な例を示します：

mapperatorinator_parser

語彙サイズを節約するために、時間イベントは10ms間隔に量子化され、位置座標は32ピクセルのグリッドポイントに量子化されます。

モデルアーキテクチャ

このモデルは基本的にHF Transformers Whisperモデルのラッパーであり、カスタムの入力埋め込みと損失関数を備えています。 モデルのサイズは2億1900万パラメータに相当します。 このモデルはこのタスクにおいて、T5よりも高速かつ高精度であることが判明しました。

モデルの入出力の大まかな概要は次のとおりです：

Picture2

モデルはエンコーダの入力としてメルスペクトログラムのフレームを使用し、1フレームが1入力位置に対応します。デコーダの出力は各ステップで事前定義された離散的なイベント語彙に対するソフトマックス分布です。出力は疎で、ヒットオブジェクトが発生したときのみイベントが必要であり、全てのオーディオフレームに注釈を付ける必要はありません。

マルチタスク学習フォーマット

Multitask training format

SOSトークンの前には条件付き生成を促進する追加トークンがあります。これらのトークンにはゲームモード、難易度、マッパーID、年、その他のメタデータが含まれます。 学習時にはこれらのトークンには対応するラベルがないため、モデルはこれらを出力しません。 また、学習中にはランダムにメタデータトークンが「不明」トークンに置き換えられることがあり、推論時にはこの「不明」トークンを使ってモデルに与えるメタデータの量を減らせます。

シームレスな長時間生成

モデルのコンテキスト長は8.192秒です。これは完全なビートマップを生成するには明らかに不十分なので、曲を複数のウィンドウに分割し、小さな部分ごとにビートマップを生成します。 生成されたビートマップがウィンドウ間で目立つ継ぎ目を持たないように、90%の重複を使い、ウィンドウを順次生成します。 最初のウィンドウを除き、各生成ウィンドウは前のウィンドウからのトークンで生成ウィンドウの最大50%までデコーダが事前に埋められた状態で始まります。

生成ウィンドウの最初の50%にある時間トークンをモデルが生成できないようにするために、ロジットプロセッサを使用しています。 さらに、生成ウィンドウの最後の40%は次のウィンドウのために予約されています。その範囲内で生成された時間トークンはEOSトークンとして扱われます。 これにより、各生成トークンは少なくとも4秒の前のトークンと3.3秒の将来のオーディオを条件として生成されることが保証されます。

長時間の生成中のオフセットのずれを防ぐために、トレーニング中のデコーダの時間イベントにランダムなオフセットが追加されています。 これにより、タイミングエラーをオーディオのオンセットを聞くことで修正するよう強制され、一貫して正確なオフセットが得られます。

拡散による座標の洗練

デコーダによって生成された位置座標は32ピクセルのグリッドポイントに量子化されるため、その後に拡散を用いて座標を最終位置にデノイズします。 これには、ノイズスケジュールの最後の10%のみに特化し、Mapperatorinatorが条件付き生成のために使用するより高度なメタデータトークンを受け入れる改良版のosu-diffusionをトレーニングしました。

MapperatorinatorモデルはスライダーのSVを出力するため、コントロールポイント経路の形状に関係なく必要なスライダーの長さは固定されます。 したがって、拡散プロセスをガイドして必要なスライダー長に合う座標を作成するようにしています。 これは拡散プロセスの各ステップ後に、必要な長さと現在のコントロールポイント経路に基づいてスライダーの終端位置を再計算することで実現しています。 つまり、拡散プロセスはスライダーの終端位置を直接制御できませんが、コントロールポイント経路を変更することで影響を与えることができます。

ポストプロセッシング

Mapperatorinatorは生成されたビートマップの品質を向上させるためにいくつかの追加のポストプロセッシングを行います：

スーパータイミングジェネレーター

スーパータイミングジェネレーターは、曲全体のタイミングを20回推論し結果を平均化することで、生成されたタイミングの精度と正確さを向上させるアルゴリズムです。 これは可変BPMの曲やBPM変更のある曲に有効で、結果はほぼ完璧で、時折手動調整が必要なセクションがある程度です。

トレーニング

以下の手順はローカルマシン上にトレーニング環境を作成します。

1. リポジトリをクローンする 

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

2. データセットの作成

Mapperatorコンソールアプリを使って独自のデータセットを作成してください。ビートマップの検証と追加メタデータの取得には、osu! OAuthクライアントトークンが必要です。データセットはMapperatorinatorディレクトリの隣にあるdatasetsディレクトリに配置してください。

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内でのトレーニングも可能ですが、パフォーマンス向上のためにWSL上のDocker使用を推奨します。 
docker compose up -d --force-recreate
docker attach mapperatorinator_space
cd Mapperatorinator

5. パラメータの設定とトレーニング開始

すべての設定は ./configs/train/default.yaml にあります。 train_dataset_path と test_dataset_path をデータセットに合わせて正しく設定し、トレイン/テスト分割の開始および終了のマップセットインデックスも設定してください。 パスは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パラメータ: 推論時には、lora_path引数で使用するLoRA重みを指定可能。 これはローカルパスかHugging Faceリポジトリのいずれか。

関連資料

クレジット

特別な感謝:

関連作品

--- Tranlated By Open Ai Tx | Last indexed: 2025-12-28 ---

Original README: View on GitHub

Translated by OpenAiTx | Last updated: 2025-12-28