YouTube 音源を解析して、セクション・小節・拍情報を確認するための個人用ツールです。

このリポジトリは次の 2 モードで使います。

1. ローカル解析サーバー YouTube URL を投げて mp3 と解析結果を作る。
2. 静的ビューア 解析済みの mp3 / json を public/ から読むだけの閲覧用サイト。

• public/ 静的ビューア本体と、公開する成果物。
• data/ ローカルサーバー実行時のランタイムデータ。
• music_structure/ FastAPI アプリ、解析サービス、ストレージ処理。
• main.py ASGI エントリポイント。
• export_static.py data/ から public/ へ成果物を同期する。
• check_env.py ローカル解析環境の依存チェック。
• refresh_public.bat public/ の再生成だけを行う。
• publish_pages.bat public/ の再生成と gh-pages 公開をまとめて行う。

• YouTube 音源を mp3 として取得して解析する
• セクション、拍、ダウンビート、小節数を確認する
• 解析済み音源を波形つきで再生する
• セクション単位のジャンプ、範囲ループ、クリック再生を使う
• public/ を静的ホスティングして外から閲覧する

• Python 3.10 系を推奨
• ffmpeg, ffprobe, node が使えること
• Python 依存を専用 venv に入れてあること

allin1 と natten の組み合わせで環境差分が出やすいので、Python 3.12 ではなく Python 3.10 の専用 venv を前提にした方が安定します。

py -3.10 -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements-py310.txt
python check_env.py

requirements.txt は緩めの依存指定、requirements-py310.txt はこのリポジトリを動かすための固定寄り設定です。

python -m uvicorn main:app --reload

Windows では start.bat でも起動できます。start.bat は .venv310, .venv, py -3, python の順に使える Python を探します。

1. アプリを起動する
2. ブラウザから YouTube URL を投げる
3. 結果は data/results/*.json と data/audio/*.mp3 に保存される
4. 同じ成果物が public/results/*.json と public/audio/*.mp3 に同期される

public/ をそのまま静的ホスティングに載せると、既存の results/*.json と audio/*.mp3 を閲覧できます。

ここでは解析機能は動きません。静的配信だけです。

python -m http.server 8080 -d public

その後、http://localhost:8080 を開きます。

data/ から public/ に成果物を同期したいときは次を実行します。

python export_static.py

音源を公開せず、解析結果 JSON だけ公開したいときは次です。

python export_static.py --metadata-only

Windows では次でも同じです。

refresh_public.bat
refresh_public.bat --metadata-only

静的ビューアだけを GitHub Pages へ公開できます。解析機能は公開されません。

このリポジトリでは、public/ の中身だけを gh-pages ブランチへ公開します。

1. GitHub のリポジトリ設定を開く
2. Settings > Pages を開く
3. Build and deployment > Source を Deploy from a branch にする
4. Branch を gh-pages / / (root) にする

1. ローカルで解析する
2. main をコミットして push する
3. publish_pages.bat を実行する
4. 数分待ってから Pages の URL を開く

publish_pages.bat

音源を公開しないなら次です。

publish_pages.bat --metadata-only

• 自分だけが解析して、結果だけ外から見たい
• 過去セッションをスマホや別PCから開きたい

• 公開先で YouTube URL を投げてその場で解析したい
• サーバーなしで動的処理まで完結させたい

• public/audio の mp3 はサイズが大きくなりやすい
• GitHub Pages は静的配信だけなので、音源数が増えるとリポジトリも重くなる
• 外部へ出すなら、まず --metadata-only で音源を含めない運用を推奨
• 音源を公開する場合は著作権と公開範囲を自分で判断すること
• 依存環境が崩れるとローカル解析が止まるので、仮想環境の固定を推奨