StemLab — timing and loops for Shorts

StemLab

Kieran Simkin による · DanceFlow エコシステム · ベクターロゴと使用ガイド。

Shorts 向けに、ステム、タイミング、ビート、ハーモニー、歌詞、MIDI、ループ可能なセクションをローカルで音楽分析します。 https://kieransimkin.co.uk/

StemLab（Kieran Simkin 提供） · 楽曲ポートフォリオ · Arcadians EPK · ソース

パッケージの名称について： 正式なプロジェクト名は StemLab です。StemLab は Dance Flow プロジェクトの一部です。PyPI ディストリビューション名が danceflow-stemlab なのは、Python パッケージレジストリの名前がグローバルに一意である必要があるためだけです。Python のインポート名、CLI、GitHub リポジトリ、コンテナーイメージ名は引き続き stemlab です。

エージェントとコントリビューター

StemLab を使用するエージェントは、利用可能な機能を調べ、タスクに適する場合は最大限活用し、可能な限り有用な改善点を探してください。必要な機能がない場合や、再利用可能な信頼性、ユーザビリティ、パフォーマンス、ドキュメント上の不足が見つかった場合は、別の回避策を維持するのではなく、このツールを改善してください。価値のある変更がない場合は、その理由を説明してください。

改善はすべて、関連するテスト、ドキュメント、再現可能な例とともに、stemlab へのプルリクエストとして提出してください。コントリビューションと検証のワークフローについては、CONTRIBUTING.md と AGENTS.md に従ってください。

プロジェクトのウェブサイト：https://kieransimkin.co.uk/danceflow/。

概要

StemLab は、マスターレコーディングから検証可能なステム、タイミング、構成、ハーモニー、歌詞、音響の根拠を抽出し、Shorts などのショート動画向けに小節の完全なループ可能セクションを見つける、ローカルで実行できる根拠重視の音楽分析ツールキットです。

単一のモデルを唯一の答えとみなすのではなく、独立した分離手法と音楽情報検索手法を組み合わせています。ソースハッシュ、マニフェスト、JSON/TSV/NPZ アーティファクト、移植可能な Sonic Visualiser セッション、再生と比較に対応した共有 React タイムラインを通じて、結果の追跡が可能です。StemLab は CLI、Python ライブラリ、ウェブサービス、コンテナー、ローカル Codex MCP プラグインとして実行できます。Kieran Simkin の DanceFlow ワークフローにおける音楽理解レイヤーであり、WordPress DanceMoves プラグインなどの下流のモーションシステムにデータを提供しつつ、単独でも有用です。

このプロジェクトではモデルの重みを再配布しません。 初回使用時に、上流のレジストリまたはリリースから取得します。これにより、ソースコードのライセンスと異なる可能性のあるライセンスを持つチェックポイントを、知らないうちに再公開することを避けられます。また、利用可能な場合は上流の整合性メタデータを使用できます。

DanceFlow と DanceMoves

DanceFlow は、より広範な BPM およびモーション応答ワークフローです。StemLab はその音楽理解レイヤーであり、WordPress DanceMoves プラグインは関連する下流のモーション応答コンポーネントです。StemLab は WordPress に依存せず、通常の分析アーティファクトとサービス API を介して連携するため、独立して有用であり、再現性も保たれます。

コンポーネントの境界については、docs/danceflow.md を参照してください。

StemLab のブラウザーワークスペースは、音声再生、共有プレイヘッド、シーク、ズーム、汎用シーケンスレーン向けに、再利用可能な react-timeline-sequence コントロールをインポートします。アップロードと分析に固有のアダプターは StemLab が保持します。

厳選されたデフォルトモデルセット（2026年9月）

StemLab id	役割	出力	含まれる理由
bs_roformer_sw	高性能	ボーカル、ドラム、ベース、ギター、ピアノ、その他（＋上流のインストゥルメンタル）	現行の本番運用向け BS-RoFormer 推論パッケージでは、この6ステムのチェックポイントが推奨されています。
mvsep_mega53	高性能／幅広い分類体系	生のステム53種類（動的に検出）	後続の評価に向けた、単一チェックポイントとしては非常に幅広いステムの構成です。上流ではメモリ消費が大きいと警告しており、少なくとも16 GBのVRAMを推奨しています。
scnet_xl_ihf	高性能	ボーカル、ドラム、ベース、その他	MSSTの公開チェックポイント表によると、このモデルはMUSDBテストの平均SDRが10.08 dB、Multisongの平均が9.92 dBです。
htdemucs_ft	確立された高性能ベースライン	ドラム、ベース、その他、ボーカル	ファインチューニング済みのHTDemucsは、RoFormerの別バリアントを追加するのではなく、独立したアーキテクチャ／ベースラインとして引き続き有用です。
openunmix_umxhq	コンパクト／低レイテンシ候補	ボーカル、ドラム、ベース、その他	コンパクトなPyTorch/Open-Unmixベースラインです。StemLabではレイテンシを優先するため、niter=0で実行します。「リアルタイム」かどうかはハードウェアとバッファーに依存するため、対象環境でベンチマークしてください。

ギター／ピアノとの比較用に、オプションのhtdemucs_6sモデルも登録されていますが、デフォルトの上位4モデルには含まれません。

関連する上流プロジェクト：

• https://github.com/openmirlab/bs-roformer-infer
• https://github.com/ZFTurbo/Music-Source-Separation-Training
• https://github.com/adefossez/demucs
• https://github.com/sigsep/open-unmix-pytorch

実施した分析

正常に完了したセパレーターが出力するすべての WAVを保持します。ステム名はファイルから検出するため、ハードコードされた4ステムのスキーマに切り詰められることはありません。これは MVSep Mega 53 で重要です。マスターと各ステムについて、StemLab は PNG スペクトログラムと圧縮された .npz 形式のスペクトログラムデータ（時間軸、周波数軸、dB 行列、FFT メタデータ）の両方を書き出します。

フル解像度のスペクトログラムデータは .npz に保持します。PNG の描画では時間フレーム数を8,192に制限するため、長いトラックによって Matplotlib の数 GB に及ぶ RGBA バッファーが生成されることはありません。以前の実行で NPZ は保持できたものの PNG の描画に失敗した場合は、モデルを再実行せずにその場で修復できます。

stemlab repair-spectrograms "path\to\analysis-results"

推奨するボーカルステムを、faster-whisper に同梱された Silero VAD の実装に渡します。音声区間を使って、タイムラインを保持した spoken_word.wav を作成します（音声以外の区間は連結せず、無音にします）。その後、Whisper を単語単位のタイムスタンプ付きで実行します。出力には whisper.json、speech_regions.json、transcript.txt、transcript.srt、words.tsv が含まれます。

Whisper はデフォルトで反復に安全なモード（condition_on_previous_text=False）で実行し、あるウィンドウ内で繰り返された音節が後続のウィンドウに影響するのを防ぎます。whisper.json にはこの設定が記録され、反復トークンの診断情報も含まれます。--whisper-condition-on-previous-text は、明示的な比較実行に限って使用してください。フラグが付いた文字起こしは、区間ごとの復元や聴取による QA が必要な証拠であり、信頼できる歌詞の情報源ではありません。

ビート分析では、次を実行します。

• StemLab のチェックサム検証済みランタイムブートストラップを通じて、オフライン／DBN モードの BeatNet を実行します。StemLab はメンテナンスされている madmom-prebuilt ホイールを使用し、BeatNet 1.1.3 の古い NumPy／Numba パッケージメタデータのみを回避します。
• final0 チェックポイントと最小限の後処理プロセッサを使用して、Beat This! を実行します。
• オリジナルとしてリリースされたモデルのコード／チェックポイントを使用して、Beat Transformer を実行します。このモデルは5つのディミキシング済みメルストリームで学習されているため、StemLab は BS-RoFormer-SW をボーカル、ドラム、ベース、ピアノ、other + guitar に対応付けます。また、オリジナルの 44.1 kHz／4096 FFT／1024ホップ設定で128ビンのメルパワースペクトログラムを作成し、デフォルトではリリース済みの8つの全フォールドチェックポイントの平均を使用します。madmom をインポートできる場合はオリジナルの madmom DBN デコーダーを使用し、使用できない場合は、文書化された SciPy のピーク検出フォールバックを使用します。

ビートの出力は JSON、TSV、および（Beat Transformer の場合）アクティベーション NPZ データとして保存されます。

StemLab は、公式の Vamp Plugin Pack にも対応しており、 Sonic Annotator を通じて実行します。厳選した Vamp の処理では、音楽的に役立つ次の出力に重点を置いています。 Chordino によるコードの文字起こしとハーモニー変化の尤度、NNLS クロマとベースクロマ、 Queen Mary によるキーと調性変化の検出、コンサートピッチのチューニング、 推奨する分離済みボーカルステム上での pYIN によるメロディー／F0 と単旋律の音符の文字起こし、 Silvet による多声音符の文字起こし、Segmentino による曲構成のセグメンテーション、 Queen Mary Vamp によるビート／小節トラッカーです。生の CSV、固定した変換ファイル、JSON、NPZ、プロットは vamp/ の下に保持され、最も有用なメロディー／ハーモニーのレイヤーは Sonic Visualiser のセッションにも埋め込まれます。

音響、ハーモニー、リズム、意味を包括的に分析

StemLab 1.0 では、既存の低レベル出力をすべて保持したまま、より高レベルのエビデンス統合パスを導入しています。デフォルトの詳細分析には、次の項目が含まれるようになりました。

アクション	エビデンス／モデル	主な出力
音響プロファイル	pyloudnorm BS.1770 + librosa DSP	LUFS、ダイナミクス、トゥルーピーク推定値、音色、ステレオ
グルーヴ／拍子	成功したすべてのビートグリッド + オンセット分析	テンポの安定性、拍子、スウィング、裏拍のエネルギー、量子化誤差
テンポの区分	ビートグリッドの BIC モデル + 固定グリッドの残差	安定したセクション、緩やかな変化、急激な変化、同一 BPM での位相スキップ、セクションごとの精度
ハーモニー	Chordino + NNLS クロマ + QM のキー／チューニング	コード進行、ハーモニーのリズム、キーのエビデンス、調性の変化
機能的構成	All-In-One-Infer 3.1	BPM、ビート／ダウンビート、イントロ／ヴァース／コーラス／ブリッジ／アウトロ形式のセクション
ライム／韻律	CMU Pronouncing Dictionary + タイミング	ライムスキーム、内部ライム、音節、反復、歌唱速度
歌詞の意味	SentenceTransformers	テーマの類似性、連続性、教師なしの歌詞行クラスタ
楽曲マップ	StemLab のエビデンス統合	1 つのタイムライン上にまとめた、セクション単位の音響／リズム／コード／歌詞の要約

オプションのアクションには、分離した楽器ステムに対する Basic Pitch のポリフォニック MIDI／音符のトランスクリプションと、MuQ-MuLan によるゼロショットの音声／テキスト意味分析があります。MuQ-MuLan の公開済み重みは CC-BY-NC 4.0 のため、この処理は意図的にオプトイン方式とし、ライセンスをすべての結果に埋め込んでいます。埋め込みの類似度は類似度として示し、確率として示すことはありません。

ルートとその依存関係を確認するには、次を実行します。

stemlab analysis-actions

便利なスイッチには、--no-structure、--no-text-semantics、--audio-semantics、--basic-pitch、--all-in-one-embeddings があります。

派生アーティファクトは deep/ 以下に保存されます（sonic/、rhythm/、harmony/、structure/、lyrics/、semantic_text/、オプションの semantic_audio/ と basic_pitch/、および song_map/song_map.json と summary.json）。

各ステムからDanceRudimentsの一致候補を検索

別途メンテナンスされているオプションのネイティブパッケージを、python -m pip install -e ".[rudiments]" でインストールします。StemLab は dancerudiments.catalogue() and dancerudiments.sample() を直接呼び出します。クローンしたモーション関数や同梱のカタログは使用しません。ステムごとの RMS アタックピークを抽出して検出済みのビートに対応付け、実際のネイティブモーションサンプルの位置／速度／加速度の顕著性と照合して、16 ビートのウィンドウをランク付けします。スコアは比較上の類似度であり、確率や、良いモーションになる保証ではありません。

# Match the mix plus every saved stem without running separation again.
stemlab rudiments ./analysis-master --top 20
# Limit an existing analysis to two stems, or choose one of six official collections.
stemlab rudiments ./analysis-master --stem drums --stem bass --collection club
# Include matching as an opt-in part of a new full analysis.
stemlab analyze master.wav --output ./analysis-master --rudiments
# The bundled Arcadians MP3 has a documented BPM but no pre-separated stems.
stemlab rudiments 'examples/arcadians/Arcadians - 320kbps.mp3' \
  --bpm 145 --collection initial --top 28 --output ./arcadians-rudiments

Measured Arcadians ベンチマーク

ミックスのみを対象としたオフラインベンチマークでは、DanceRudiments の真正な 28 パターンからなる初期コレクションで、エネルギー上昇ピークが 1,821 件検出され、類似度 0.68 以上の候補パターンが 15 件見つかりました。上位は groove_b_played（0.739）、groove_b_grid（0.737）、lfo_morph（0.724）でした。このベンチマークでは、DanceRudiments の公式コンパイル済みサンプルテーブルをオフラインアダプター経由で読み込みました。ネイティブの C++ 拡張機能テストは別途実施され、オプションのパッケージがインストールされていない場合はスキップされます。BPM グリッドはゼロから開始し、ビート位相は未検証です。ステム分離を行ったとは主張していません。

以下は、測定結果を表示したローカル HTML レポートの実際の Chromium スクリーンショットであり、模式図やメインの React タイムラインのキャプチャではありません。

分析結果は deep/rudiments/report.json、index.html、overview.png に書き込まれます。 **手法、スコアに関する注意事項、出典、例、スクリーンショットの再現方法**を参照してください。

ネイティブ CI のカバレッジ： メインの GitHub Actions CI ワークフローには、公式の DanceRudiments バイナリホイールをインストールし、実際の C++ モジュールを必須としたうえで、スキップを無効にして Arcadians テストを実行する、専用の Python 3.10/3.11 ジョブが追加されました。実音声とのマッチ数が 12 件未満の場合、CI は失敗します。テストに合格すると、JSON、HTML、測定結果を重ねた PNG がダウンロード可能な CI アーティファクトとして公開されます。ネイティブ CI の検証手順を参照してください。

タイムライン分析ギャラリー

ブラウザのワークスペースは、分析結果をダウンロードできるだけでなく、内容を確認できるように設計されています。以下の図は、フロントエンドと共通のタイムライン用語、つまり一つのクロック、一つの再生ヘッド、ズーム可能なレーン、スペクトログラム、ビート、歌詞、ディープ分析の各レイヤー間で一貫して位置合わせされたセクションを使って、主な分析機能の種類を説明しています。

図であり、フロントエンドのスクリーンショットではありません。 これらの SVG は scripts/render_readme_analysis_gallery.py によって生成されています。このスクリプトは React タイムラインコンポーネントを実行せず、音声をデコードせず、分離やニューラル推論も行いません。 Arcadians のセクションラベル、歌詞のテキストとタイミング、参照 BPM のみ、収録されているアーティスト作成のメタデータに基づいています。ほかのプロットパターンとコードの例示ラベルは模式的なものであり、Arcadians の測定結果ではありません。特に、これらの図はボーカルのないカット、測定されたテンポの安定性、コード／キーの推定値、ラウドネス値を示す証拠ではありません。実際のフロントエンドのキャプチャは未取得です。

1. 分離、スペクトログラム、ビート、セクション

これは中心となる確認ビューです。StemLab が次の項目をどのように位置合わせするかを説明します。

• AI／参照セクションマップ（deep/structure/ および deep/song_map/）、
• BeatNet、Beat This!、Beat Transformer のビートおよび小節グリッド（beats/*.json、beats/*.tsv）、
• マスタースペクトログラム、および
• spectrograms/ 以下に書き込まれる各ステムのスペクトログラム。

実際には、セパレーター、ビートモデル、セクションモデルが、音楽的に納得できる出力を生成したかどうかを確認するとき、まずこのビューを使います。

2. 歌詞、音声区間、トランスクリプトの品質確認

StemLab では、歌詞と音声の分析をオーディオと同じ時間軸上で行います。

• 正解の歌詞タイミング：正確性が確認された LRC または JSON ソースに基づきます。
• Whisper の単語タイミング：優先するボーカルステムに基づきます。
• 音声区間／VAD の証拠：検出された音声の活動を示しますが、これだけでは歌唱が存在しないことを証明できません。
• 時間軸を維持した音声分離ファイル、派生物の spoken_word.wav。
• speech/ および deep/lyrics/ 以下の、韻、韻律、反復の安全性に関する下流診断。

重要なのは、モデルが聞き取った内容とアーティストが提供した内容を比較し、さらにその両方をループの境界、振り付けのキュー、歌詞シートの品質確認とすぐに関連付けられることです。

3. 和声、メロディー、楽曲マップの統合

StemLab の和声および構造分析は、単一のコードトラックにとどまりません。和声／楽曲マップの分析群は、次の要素を統合します。

• キュレーションされた Vamp パスによるコードと和声変化の証拠。
• キー、調性変化、チューニングの出力。
• ボーカル分析から導出されるメロディー／F0 のスタイルレーン。
• 構造、リズム、和声、歌詞の証拠を、読みやすいひとつのストーリーに統合するセクション単位の楽曲マップ。

これらの出力は主に vamp/、deep/harmony/、deep/song_map/ 以下に保存されます。これらは、低レベルの DSP 出力を音楽的な観点から解釈しやすくするレイヤーです。

4. 音響プロファイル、リズムの傾向、意味分析

上位レベルのディープパスでは、楽曲が時間とともにどのように感じられるかも追跡します。

• 音響プロファイルの要約（ラウドネス、ピーク、ダイナミクス、音色、ステレオの挙動）。
• スウィング傾向、裏拍のエネルギー、量子化誤差などのグルーヴ／リズム指標。
• 安定区間、ランプ、急激な変化を対象としたテンポ傾向の検出。
• 歌詞／テキスト分析による意味の要約と、オプションのゼロショット音響意味分析。

この分析群によって、StemLab は単純な BPM とステムのツールから、DanceFlow や後続のモーション応答システム向けの、より豊かな音楽理解レイヤーへと進化します。

5. ループの位置付け

ループ検出のパッチは、これまでの分析を置き換えるものではなく、それらを利用します。ループの選定では、次のものを使用します。

• 候補となるヴァースとコーラスの範囲を特定するセクションラベル。
• カット位置を完全な小節に合わせるビートグリッド。
• 検出された発声を避けるためのフルボーカルステムと利用可能なタイミングの証拠。VAD だけでは不十分です。
• 不連続を減らす波形の継ぎ目チェック。採用された接続も、試聴による確認が必要です。

つまり、ループレーンは、StemLab にすでに備わっている構造、リズム、ボーカルの各分析を応用して統合したものと捉えるのが最適です。

ループの検出と再生

StemLab は、識別された各ヴァースおよびコーラスの出現箇所について、少なくとも1つの小節全体を含むループを試みるようになりました。ビートグリッド、ボーカルのないカット周辺、各オーディオチャンネルの波形の継ぎ目を確認します。安全でないセクションや未対応のセクションは、無理に採用せず報告されます。開始／終了サンプルフレーム、品質診断、出所情報は、デフォルトで deep/loops/loops.json と loops.tsv に書き込まれます。

# New analysis: loop metadata is included in the default deep pass.
stemlab analyze master.wav -o analysis-master --profile practical

# Also save exact native-rate WAV slices.
stemlab analyze master.wav -o analysis-master --profile practical --export-loops

# Reuse existing separation, structure and beat results; no models rerun.
stemlab loops analysis-master --export-loops

# Keep all candidates within a chosen short-video edit budget, in seconds.
stemlab loops analysis-master --max-seconds 30 --per-section 3

# Audition possible new cut pairs anywhere in the song, even where the passage
# does not already repeat. These near-misses are NOT accepted seamless loops.
stemlab loops analysis-master --mode exploratory --search-scope whole_song \
  --max-seconds 30 --per-section 20 --exploratory-algorithm spectral_context

既存の解析フロントエンドで、ハイライトされたループ範囲または Loop セレクターを選択し、Enable loop にチェックを入れてから、Play を押します。再生ヘッド、シーク、ズーム、スペクトログラムのタイムラインはそのまま使用できます。ループのプレビューに WAV のエクスポートは不要で、ファイルも書き込まれません。Zoom to loop を選ぶと、共通タイムラインがループにフォーカスします。

両方のパッチのインストール、サンプルのインデックス作成、しきい値、制限事項、再現可能なスクリーンショット例については、ループワークフローの全容をご覧ください。

音楽的に納得できる再開位置を目指す場合は、各ラインを最後まで含む代替案として、stemlab phrase-loops analysis-master --feedback artist-ratings.json --export-audio を使用します。このオプトイン検索では、両方のカット周辺の音楽的な文脈を比較し、正規の歌詞出現箇所を保持し、明示的なアーティストのフィードバックを使用して、多様なパッセージを選びます。候補は、厳密に採用されたループとは別に扱われます。フレーズループの方法、フィードバック形式、合成例をご覧ください。より長い抜粋には、--min-seconds 20 --max-seconds 30 を追加します。オプションの --max-bar-phase-error 0.125 を指定すると、測定された小節位置が一致しない候補も除外できます。これらのフィルターは試聴候補を提案するものであり、シームレスな再生や聴感上の承認を保証するものではありません。

オーディオから MIDI へのモデル比較

MIDI 抽出は任意の独立したモデルパスです。Spotify Basic Pitch に加え、Transkun V2 と高解像度のノート／ペダルのピアノ採譜、さらに複数楽器の採譜を行う MR-MT3 と YourMT3 が追加されます。自動ソース選択では、ピアノ特化モデルにはピアノ／キーボードのステム、Basic Pitch にはピッチのあるステム、MT3 系モデルにはミックスを使用します。ステムがない場合は報告され、黙って別のソースに置き換えられることはありません。従来の --basic-pitch コマンドも引き続きサポートされます。

# Install the chosen runtime; the standard profiles do not install MIDI models.
python -m pip install -e ".[midi-transkun]"
stemlab midi-models

# Use an existing separated piano, without rerunning any earlier analysis.
stemlab midi analysis-master --model transkun

# Or transcribe a directly supplied piano recording to a new folder.
stemlab midi piano.wav -o midi-piano --model transkun

# Full mix comparison requires the separately installed midi-mt3 extra.
# Both requested checkpoints need explicit first-use download consent.
stemlab midi mix.wav -o midi-comparison --model mr_mt3 --model yourmt3 --allow-model-downloads

各モデル／ソースについて、元の .mid、テンポを考慮した notes.json と notes.csv、実際のノートを示す任意の piano-roll.png、ソース／チェックポイントのハッシュ、パッケージのバージョン、ワーカーログが保存されます。ネイティブ MIDI コントローラー、ピッチベンド、テンポ変更、ドラムは保持されます。ノートのサンプル番号は元のサンプルレートにおける推定値であり、サンプル単位で正確な正解データであることを示すものではありません。MIDI クロックを使って StemLab の測定済みビートグリッドを上書きすることはありません。

新しい解析では、--midi-model スイッチを繰り返し指定し、--midi-allow-downloads を指定することでオプトインできます。既存の Codex インストールでは、Python のインストールを更新してセッションを再起動すると、ワークスペースのスコープに限定されたジョブツール stemlab_start_midi_scan が追加されます。モデルは引き続き任意であり、Python 依存関係が自動的にインストールされることはありません。互換性のない研究用ランタイムでは、個別の --backend-python MODEL=PATH インタープリターを使用できます。

すべてのモデル、インストール方法、チェックポイントとライセンスに関する注意事項、保存済みステムの指定、Codex の使用方法、出力の厳密な意味、実際の推論を使ったスモークコマンド、テストの制限事項については、MIDI ガイドをご覧ください。React のタイムラインは引き続き解析インスペクターとして使用されます。このパッチでは、MIDI シンセサイザーや、新たに操作可能なピアノロールレーンは追加されません。静的なノートプロットはフロントエンドのスクリーンショットではありません。

検出されたビートにタイミング付きの音楽キューを合わせる

保存済みの分析を使って、モデルを再実行したり音声を編集したりせずに、LRC キューファイルをスナップします。

stemlab snap-cues analysis-master "musical cues.lrc" -o cue-review
stemlab snap-cues analysis-master "musical cues.lrc" -o cue-review-100ms --tolerance-ms 100
stemlab generate-cues analysis-master -o generated-cues --title "Song title"

変更されるのはタイムスタンプのみです。[DROP: CHORUS 1] などの角括弧付きラベル、メタデータ、エンコーディング、行のレイアウトは保持されます。±150 ms 以内に検出されたビートがないキューは、最も近いビートとの間隔とともに要確認として強調表示され、デフォルトでは変更されません。--force-snap を指定すると、遠いキューも移動しますが、警告は保持されます。--downbeats を指定すると、対象は報告された小節の開始位置に限定されます。--beat-model では特定の検出器を選択できます。検出の空白を埋めるために、一定テンポのビートが作られることはありません。

新しい出力フォルダーには、書き換え後の .beat-snapped.lrc、report.json、色分けされた review.html、review.txt が含まれます。正確モードでは保存済みのビートタイムスタンプが保持されます。ミリ秒／センチ秒の互換モードを明示的に指定した場合は、丸めが報告されます。サンプルレートが判明している場合は、ソースのサンプルレートに基づくサンプルフレーム推定値も含まれます。確認が必要な場合に結果を出力して終了コード 2 で終了するには、--fail-on-review を指定します。 生成されたセクションキューファイルには、タイトル固有の WordPress 対応ファイル名が使われるため、複数のリリースを曖昧な重複名なしでアップロードして対応付けられます。2026 年 10 月 3 日の、保持対象となっている将来リリースのバッチでは、scripts/run-upcoming-full-cues.ps1 が不完全なディレクトリを上書きせずに完全分析を再開し、scripts/summarize-upcoming-cues.ps1 がクローズ済みの各マニフェスト／レポートを読み取り、リリースごとに再現可能なハッシュ、キューの処理内容、エラー数をまとめた 1 行を出力します。サマリースクリプトは、生成された LRC が見つからない場合や、候補が複数あって特定できない場合には処理を拒否します。

新しい分析では、--snap-cues "musical cues.lrc" を追加し、必要に応じて --cue-tolerance-ms 100 を指定します。キューの位置合わせには、その実行で検出されたイベントが使われ、結果は analysis.json に表示されます。精度、オフセット、すべてのスイッチ、安全規則、警告の解釈については、キュー位置合わせガイドを参照してください。

補完的なエビデンスモデル

StemLab には、通常の分離や MIDI バックエンドと重複するのではなく、異なる種類の音楽的エビデンスを追加するモデル向けの、オプションのエビデンスモデルレイヤーが追加されました。通常のプロファイルでは、このレイヤーの機能は何も有効になりません。

stemlab evidence-models

# Singing/speech/music activity + continuous pitch on saved vocals.
stemlab evidence analysis-master -o evidence-vocals \
  --model firered_aed --model swift_f0 \
  --model-path firered_aed=/models/FireRedVAD/AED

# Align approved lyrics without replacing them.
stemlab evidence analysis-master -o evidence-align \
  --model qwen_forced_aligner --canonical-text lyrics.txt --allow-model-downloads

# Independent harmony evidence.
stemlab evidence analysis-master -o evidence-chords --model lv_chordia

組み込みレジストリには、FireRed AED、HeartTranscriptor、Qwen3 ForcedAligner、SwiftF0、SongFormer、lv-chordia、ADTOF PyTorch が登録されています。また、GAME、SheetSage2、MOSS-Music、AudioSep 用の外部ランタイムブリッジも明示的に用意されているため、大規模または利用制限のある研究用依存関係が StemLab に気付かれないままバンドルされることはありません。出力は個別に保たれます。歌唱アクティビティ、強制アラインメント、ピッチ、構成、コード、ドラムヒットは確認用エビデンスであり、隠れた統合正解スコアではありません。

保存済みの分析では、ボーカルモデルには優先されるフルボーカルステム、ドラムの書き起こしにはドラムステム、連続ピッチには有音ステム、構成／ハーモニーモデルにはマスターが自動的に割り当てられます。専門ステムが見つからない場合は報告されます。競合する研究環境を使うには、--backend-python MODEL=/path/to/python を指定します。

モデルの用語、ルーティング、外部ブリッジ、解釈規則については、エビデンスモデルガイドを参照してください。scripts/benchmark_evidence_corpus.py は、許可された評価用コレクションを調査します。音声をリポジトリにコピーすることはありません。

インストール

幅広いオプションモデルのエコシステムを利用するには、Python 3.11 を推奨します。beats と all の追加機能をインストールすると、Beat This! と互換性のある madmom-prebuilt デコーダーがインストールされます。BeatNet 1.1.3 自体は今も古い NumPy／Numba の依存関係のバージョン指定を公開しているため、StemLab は公式の純粋な Python ホイールを個別にダウンロードし、公開されている SHA-256 を検証して、キャッシュから BeatNet のコードと同梱モデルの重みのみを利用します。この方法は Python 3.11～3.13 でサポートされています。BeatNet の結果がない場合、検出器が正常に実行されたと判断してはいけません。

PyPI から、リリース済みの StemLab ディストリビューションを次のようにインストールします。

pip install danceflow-stemlab

インストールされる Python パッケージ名とコマンド名は、引き続き stemlab です。ソースをチェックアウトして開発する場合：

python -m venv .venv
. .venv/bin/activate              # Windows: .venv\Scripts\activate
python -m pip install -U pip
pip install -e ".[all]"

SCNet と Beat Transformer は、安定した pip 推論 API ではなく研究用リポジトリです。必要に応じて個別にダウンロードし、分離して利用します。すべてを事前に準備するには：

stemlab bootstrap all

BeatNet のみを準備する場合：

pip install "danceflow-stemlab[beats]"
stemlab bootstrap beatnet
stemlab doctor

stemlab doctor は、通常のパッケージまたは検証済みの StemLab キャッシュが実際に見つかった場合に限り、BeatNet を準備完了として報告します。analyze --no-bootstrap は BeatNet をダウンロードせず、利用できないバックエンドとして記録します。

Vamp 分析スタックのみを準備するには：

stemlab bootstrap vamp

bootstrap vamp は、固定バージョンの Sonic Annotator ランタイムをダウンロードし、公式 Vamp Plugin Pack インストーラーを起動します。インストーラーの実行を一度完了してから、必要に応じてコマンドを再実行し、要求したプラグインの出力が利用可能であることを確認します。

CLI

要求された分析をすべて実行する場合：

stemlab analyze master.wav --output ./analysis-master --profile full --device auto

便利な代替方法：

# Skip the 53-stem model for a materially lighter run
stemlab analyze master.wav -o ./analysis-master --profile practical

# Run only selected separators
stemlab analyze master.wav -o ./analysis-master \
  --model bs_roformer_sw --model scnet_xl_ihf --model openunmix_umxhq

# Fail immediately rather than recording a backend failure and continuing
stemlab analyze master.wav -o ./analysis-master --strict

# Skip Vamp if the plugin pack is intentionally not installed
stemlab analyze master.wav -o ./analysis-master --no-vamp

stemlab models
stemlab doctor

デフォルトでは、モデルの重みと外部の研究用コードは出力フォルダーの外にキャッシュされます。生成された分析アーティファクトとデータセットはすべて出力フォルダー内に書き込まれます。Sonic Visualiser のセッションを単一のディレクトリとして持ち運べるよう、コピーされたマスターも input/ に配置されます。

出力レイアウト

analysis-master/
  input/master.wav
  stems/
    bs_roformer_sw/*.wav
    mvsep_mega53/*.wav
    scnet_xl_ihf/*.wav
    htdemucs_ft/*.wav
    openunmix_umxhq/*.wav
  spectrograms/
    master.png
    master.npz
    <model>/<stem>.png
    <model>/<stem>.npz
    speech/spoken_word.png
    speech/spoken_word.npz
  speech/
    spoken_word.wav
    speech_regions.json
    whisper.json
    transcript.txt
    transcript.srt
    words.tsv
  beats/
    beatnet.json / beatnet.tsv
    beat_this.json / beat_this.tsv
    beat_transformer.json / beat_transformer.tsv
    beat_transformer_activations.npz
  vamp/
    report.json
    transforms/*.n3
    raw/*.csv
    data/*.json
    data/*.npz
    plots/*.png
  deep/
    sonic/
    rhythm/
    harmony/
    structure/
    lyrics/
    semantic_text/
    song_map/
    rudiments/             # optional native DanceRudiments candidate report
      report.json
      index.html
      overview.png
    summary.json
  sonic_visualiser/
    session.sv
    session.xml
    open_sonic_visualiser.bat
    open_sonic_visualiser.sh
  analysis.json
  manifest.json

session.sv は、Sonic Visualiser の実際の bzip2 圧縮セッション XML です。マスターペインにはビート／ダウンビート／Whisper の時間インスタントレイヤーが含まれ、分離された各ステムには、同期された波形ペインと Sonic Visualiser のスペクトログラムペインが 1 つずつ含まれます。展開済みの session.xml は、確認やデバッグ用に保持されます。Windows の .bat は、PATH と標準的な Program Files の場所を検索します。

Web サービス

StemLab には、アップロード／タイムラインの Web UI と、コンテンツアドレス方式の分析ジョブ向け HTTP および Socket.IO API が含まれています。起動方法、エンドポイント、イベント、Arcadians のリファレンスワークフローについては、docs/web.md を参照してください。

ドキュメント

• DanceFlow のワークフローと DanceMoves との関係
• Web サービス
• コンテナー
• 公開とリリース
• BeatNet の互換性
• 変更履歴

Codex プラグインと MCP サーバー

まず実際の React タイムラインで確認してください。 Codex プラグインは、StemLab に同梱された react-timeline-sequence フロントエンドで保存済みの結果を表示するために、 stemlab_open_timeline を公開するようになりました。利用可能なローカルブラウザーを使って、 波形、スペクトログラム、ビート、セクションのレーンを比較し、ループを選択・有効化し、 ズームして繰り返しを試聴してください。数値に関する主張には正確な JSON レポートを使用し、 ブラウザーにアクセスできない場合は保存済みの PNG を代替として使用してください。 スクリーンショットは、再描画したものではなく、必ずレンダリングされたコンポーネントから取得してください。 stemlab_close_timeline は、結果を変更せずに非公開の読み取り専用ビューアーを閉じます。 確認ワークフローを参照してください。

Codex から StemLab を使用して、タイミングを分析し、実際の証拠を確認し、 Shorts 動画向けにループ可能な音楽セクションを見つけて書き出してください。 これはローカルの stdio MCP サーバーとインストール可能なスキルバンドルであり、 リモートの音声アップロードサービスや動画エディターではありません。 既存のパイプラインを再利用し、以前の結果フォルダーを保持します。

# From this patched checkout, in an activated environment:
python -m pip install -e ".[codex]"
stemlab-codex configure --workspace "/absolute/path/to/music-workspace"
stemlab-codex doctor
codex plugin marketplace add .

サポート対象の Codex ホストでは、ローカルのプラグインディレクトリから StemLab をインストールしてください。 CLI のみで使用する場合は、MCP コマンドを直接登録してください。 Windows のパス、モデルの追加要素、同意、ポーリング、正確なサンプル規約については、 セットアップとツールを参照してください。

リリースビルドでは MCP 統合を検証し、バージョン付きプラグイン ZIP、 チェックサム、MCP Registry のメタデータを GitHub リリースに添付します。 リリース専用の codex-plugins ブランチにより、PyPI 公開後にマーケットプレイスの配布経路を利用できます。 これは OpenAI の公開 Plugins Directory への自動申請を意味するものではありません。 配布と任意の MCP Registry 公開では、 個別の配布経路と承認要件について説明しています。

Codex スキル

このリポジトリには、再利用可能な Codex スキル skills/use-and-improve-stemlab が含まれています。 このスキルは StemLab をデフォルトの分析エンジンとし、適切なプロファイルを選択して、 証拠の境界を保持します。また、文書化されていない並行スタックを作成するのではなく、 再利用可能な機能の不足をテストとともに StemLab に反映します。

Python API

from pathlib import Path
from stemlab.models import FULL_PROFILE
from stemlab.pipeline import run_pipeline
from stemlab.types import PipelineConfig

result = run_pipeline(PipelineConfig(
    input_wav=Path("master.wav"),
    output_dir=Path("analysis-master"),
    models=FULL_PROFILE,
    device="auto",
))

外部ランタイム／キャッシュの詳細

BS-RoFormer アダプターは bs-roformer-infer を使用します。このツールは独自のチェックポイントレジストリと SHA-256 検証を管理します。SCNet は v1.0.15 の SCNet XL IHF リリースアセット URL に固定されており、StemLab はダウンロード後に計算したハッシュを記録します。Beat Transformer は元の上流リポジトリからクローンされ、そのリポジトリで公開されている fold チェックポイントを使用します。StemLab の外部キャッシュの場所を変更するには、STEMLAB_CACHE=/some/path を設定してください。

フル実行は、意図的に高負荷です。Mega-53 は VRAM とストレージを最も多く消費する処理であり、数十個のステムを処理すると、追加のスペクトログラムファイルと Sonic Visualiser のペインも数十個必要になります。反復作業には --profile practical を、網羅的な分析には --profile full を使用してください。

リリース

バージョンタグは、検証後に StemLab を GitHub Releases、PyPI（danceflow-stemlab）、 GHCR、Docker Hub に公開します。リリース契約と Trusted Publishing の設定については、 docs/publishing.mdを参照してください。

再現性とライセンス

analysis.json にはモデル／バックエンドのメタデータとエラーが記録され、manifest.json にはすべての出力アーティファクトのハッシュが記録されます。モデルのチェックポイント、研究コード、データセットには、それぞれ上流の利用条件が適用されます。特に、MIT ライセンスの推論ラッパーであっても、それがダウンロードできるすべてのチェックポイントの再配布権が自動的に付与されると想定しないでください。