Nomad Karaokeへのコントリビュート

2026-02-03

Nomad Karaoke

Nomad Karaokeはカラオケ関連のOSSを開発しているコミュニティだ
Hey! I'm a computer nerd who loves karaoke と自己紹介しているAndrewの個人プロジェクトに近いようだ

マッシュアップのDJ MIXを聞きながらボーカルとトラックの分離について調べていて nomadkaraoke/python-audio-separatorを見つけたのがきっかけだ
以前のBlog記事でふれた件だ

python-audio-separator: File-level Chunking

→ PR #256

python-audio-separatorは音声ファイルからボーカルとトラックを分離するCLIツールだ
MDXやDemucsといった機械学習モデルを使って分離処理を行う

長時間の音声ファイル（ポッドキャストや長尺のDJ MIXなど）を処理しようとするとOOMエラーが発生する問題があった
8時間のファイルだと100GB以上のメモリが必要になってしまう

コードの理解のために何かIssueに手をつけて見ようと思いissueを見ていたらメンテナが参照実装を示していたので、それを参考にチャンク分割機能を実装した
ファイルを指定した長さ（例：10分）ごとに分割して処理し、最後に結合する仕組みだ

主な変更点：

• AudioChunkerクラスで分割・結合処理を実装
• --chunk_durationオプションでチャンクサイズを指定可能に
• 2/4/6ステムモデル（MDX、Demucs）に対応
• チャンク間でGPUキャッシュをクリアしてメモリを解放

ステム、というのは分離する数である
2ステムだとボーカル/その他、4ステムだとボーカル/ドラム/ベース/その他、だ

このステムの仕組みに最後に気づいて実装を大きく修正した

karaoke-gen: --no-video Flag

→ PR #288

karaoke-genはカラオケ動画を生成するツールだ
音声分離、歌詞の書き起こし・同期、動画エンコードまでを一括で行える
先のpython-audio-separatorも使われている

動画エンコードはフルの曲で15-20分かかる重い処理だ
でもCDG（カラオケ機器用フォーマット）や歌詞の文字起こしを行うテキストファイルだけ欲しい場合もある

--no-videoフラグを追加して、動画エンコードをスキップできるようにした
音声分離と歌詞同期は実行されるが、最終的な動画エンコードはスキップされる

# CDGのみ生成
karaoke-gen --no-video --enable_cdg audio.flac "Artist" "Title"

# CDG + TXT
karaoke-gen --no-video --enable_cdg --enable_txt audio.flac "Artist" "Title"

karaoke-genはWebフロントエンドも含んだ複合的なApplicationだ
CLIを実行すると途中でローカルにFastAPIサーバーが起動してブラウザが開き、Web UI上でinstrumentalトラックを試聴・選択できる
選択が完了するとCLI処理が再開されて動画生成に進む、という仕組みになっている

コントリビュートの経緯

どちらのPRもClaude Codeを使ってリサーチ、実装した
Pythonはあまり書いたことがなかったが、既存のコードベースを読みながら実装できた
音声処理界隈はPythonが多いので書く機会が増えそうだ

OSSへのコントリビュートはこれまでしてきていなくて、ドキュメントの修正を少し、くらいだった
小規模なコミュニティだったこともあり、issueでの方針相談から実装 -> マージまで非常にすばやく進んだ
Claudeで書いた詳細なプランをはったら方針が違って「LLMで書いたその方針はNonsense」とコメントされたのもいい思い出だ