Communitygithub.com

puntorigen/skills

ローカルファーストのエージェントスキル群 — Cursor やその他のAIコーディングエージェント向け。完全にあなたのマシン上で動作し、クラウド也不要、APIキー不要。Apple Silicon対応(MLX/Metal):ローカル画像生成、音声クローン、BGM、トーキングヘッド動画、動画→3Dスプラット&印刷可能STL、Webアクション記録、Word .docx編集。

skills とは?

このスキルセットは、AIコーディングエージェント(Cursor、Claude Code、Codexなど)がローカルマシン上で完全にオフラインで実行できる制作タスクを提供します。特にApple Silicon(Mシリーズ)に最適化されており、MLX/Metalフレームワークを活用して高速な推論を実現。画像生成、音声クローン、BGM作成、トーキングヘッド動画、3DスプラットやSTLモデル生成、Web操作の記録と再生、Word文書編集などをカバーします。クラウドやAPIキーが不要なため、機密データが外部に漏れるリスクがなく、インターネット接続が不安定な環境でも安定して動作します。各スキルは独立したスクリプトと設定で構成され、エージェントがユーザーの指示に基づいて適切なツールを呼び出します。例えば、BGM生成スキルではACE-Step 1.5モデルを使い、テキストの指示からオリジナルのロイヤリティフリー音楽を生成し、ナレーションと自動ミックスできます。

対応✓Claude Code~Codex CLI✓Cursor
npx skills add puntorigen/skills

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

BGM(背景音楽)

リール動画やデモ動画用のオリジナル・ロイヤリティフリーのインストゥルメンタル音楽を、テキストの簡単な指示から生成します。完全オフラインで動作。ラッパースクリプトがACE-Step 1.5(音楽モデル)を駆動します。**あなた(モデル)**は、簡単な指示を適切なプロンプトに整形し、2~3の候補を生成し、ユーザーに選択させ、必要に応じてナレーションの下にミックスします。

voice-clone-narrationスキルと連携:ナレーションはそちらで生成し、音楽はこちらで生成。その後mix_voiceover.shでナレーションの下に音楽を自動でダッキング(音量低下)し、完成したリール音声トラックを作成します。

flowchart LR
  Brief["指示: ジャンル、雰囲気、BPM、長さ"] --> Gen["generate_music.py<br/>ACE-Step 1.5 (MLX), インストゥルメンタル"]
  Gen --> Mp3["候補mp3"]
  Nar["narration.mp3 (任意)"] -.-> Mix["mix_voiceover.sh<br/>ffmpeg サイドチェイン・ダッキング"]
  Mp3 -.-> Mix
  Mix -.-> Reel["reel-audio.mp3"]

すべてのファイルはリポジトリの外、~/.bg-music/ に保存されます(ACE-Stepのチェックアウト、モデル重み、生成された音声ファイル)。

前提条件

  • uv(パッケージマネージャー)とgit — モデルはuv syncアプリケーションであり、単純なpipインストールではありません。セットアップにより、隔離された環境にインストールされます。
  • ffmpegがPATH上にあること(MP3エンコード+ミキシング)。ない場合はユーザーにbrew install ffmpegを実行するよう促してください。
  • 約10 GBの空きディスク(コード+モデル重み用。Hugging Faceから匿名で1回ダウンロード。トークン不要)。より大きなモデルバリアントを使用する場合は、さらに容量を確保してください。
  • Apple Silicon Mac(高速なネイティブパスであるMLX用)。CUDA/CPUではPyTorchにフォールバックします(CPUでは低速)。16 GBの統合メモリでデフォルトの2B-turbo + 0.6B-LMティアを十分に実行できます。
  • 初回実行時のみインターネット接続が必要(コードと重みを取得するため)。生成はオフラインで行われます。

セットアップ

スキルのディレクトリを確認し、セットアップを1回実行します(ACE-Step 1.5をクローンし、その環境を同期します。初回は依存関係のダウンロードに数分かかる場合があります):

SKILL_DIR="<このSKILL.mdが置かれているフォルダ>"   # 例: .cursor/skills/bg-music
bash "$SKILL_DIR/scripts/setup_env.sh"

次に、生成で使用するハンドルを設定します(セットアップ時にもこれらの内容が表示されます):

BG_HOME="${BG_MUSIC_HOME:-$HOME/.bg-music}"
PY="$BG_HOME/ACE-Step-1.5/.venv/bin/python"

ワークフロー

以下のチェックリストをコピーして進捗を追跡してください:

- [ ] 1. 指示を確認: ジャンル、雰囲気、テンポ(BPM)、長さ、主要な楽器
- [ ] 2. セットアップ: setup_env.shを実行(初回のみ)
- [ ] 3. 具体的なプロンプトを作成し、2つの候補を生成
- [ ] 4. 候補を再生/リンク表示し、ユーザーに選択させる(必要に応じて再生成)
- [ ] 5. (任意)選択された曲をナレーションmp3にダッキングしてミックス
- [ ] 6. mp3ファイルを納品

ステップ 1: 指示を確定する

音楽の品質は具体的なプロンプトに依存します。以下の情報をユーザーから引き出すか、または推測して選択肢を提示してください:

  • ジャンル/スタイル: ローファイヒップホップ、シネマティックオーケストラ、コーポレートアンビエント、シンセウェーブ、アコースティックフォーク、アップビートポップ...
  • 雰囲気: 穏やか、高揚感、緊張感、夢想的、エネルギッシュ、メランコリック。
  • テンポ: 遅い / 中程度 / 速い、または明確なBPM(例: 90)。
  • 長さ: 秒数(10~600秒。リール動画は通常30~120秒)。
  • 主要な楽器(任意): Rhodesピアノ、暖かいパッド、ソフトなドラム、ナイロンギター。

ステップ 3: 生成

"$PY" "$SKILL_DIR/scripts/generate_music.py" \
  --prompt "warm lo-fi hip hop, mellow Rhodes piano, soft vinyl crackle, laid-back drums, loopable, instrumental" \
  --bpm 80 --duration 60 --count 2 \
  --out "$BG_HOME/out/lofi.mp3"
  • デフォルトでインストゥルメンタル(ボーカルなし)。
  • --count 2 で2つのバリエーションを生成し、選択できるようにします(lofi-1.mp3、lofi-2.mp3)。
  • MP3ファイルを出力し、そのパスと長さを表示します。初回実行時にモデル重みをダウンロードし、以降の実行は大幅に高速化されます。

優れたプロンプトは具体的でカンマ区切りです。ジャンル+雰囲気+2~3の楽器+テンポの単語+"instrumental"/"loopable"を含めてください。例:

  • "cinematic inspiring orchestral, soft strings, piano, subtle percussion building to a warm swell, instrumental"
  • "clean corporate ambient, gentle synth pads, light plucks, optimistic, minimal, instrumental"
  • "driving synthwave, analog bass, retro arpeggios, punchy drums, night-drive energy, instrumental"

ステップ 5: ナレーションの下にミックス(任意)

ユーザーがボイスオーバーも持っている場合(例: voice-clone-narrationスキルで生成したもの)、音楽をその下に自動的にダッキングします:

bash "$SKILL_DIR/scripts/mix_voiceover.sh" \
  --voice ~/.voice-clone-narration/out/test-en.mp3 \
  --music "$BG_HOME/out/lofi-1.mp3" \
  --out ~/Desktop/reel-audio.mp3

音声が話している間は音楽が自動的に下がり(サイドチェイン圧縮)、間隙では戻ります。音楽はナレーションの長さに合わせてループされ、フェードイン/アウトされます。--music-gain(基本レベル、デフォルト -8 dB)、--duck(ダッキングの強さ、デフォルト 8)、--fade で調整できます。

ステップ 6: 納品

選択されたmp3を埋め込むかリンクとして提供します。生成されたファイルは ~/.bg-music/out/ に残ります。

主要オプション(generate_music.py)

オプションデフォルト目的
--prompt(必須)音楽の説明: ジャンル、雰囲気、楽器、雰囲気。
--duration60長さ(秒)10~600。
--bpm自動テンポ(BPM)30~300。省略するとモデルが自動選択。
--count2生成するバリエーションの数。
--outout/music-<ts>.mp3出力パス(--count > 1 の場合はプレフィックス)。
--seedランダム再現性のために固定。
--keyscale自動音楽のキー(例: "A minor")。
--vocalsオフ(インストゥルメンタル)ボーカルを許可(BGMではほとんど不要)。
--steps8拡散ステップ数(ターボデフォルト。多くすると遅いがわずかに品質向上)。
--mp3-quality2ffmpegのlibmp3lame -q:a(0=最高..9=最小)。
--keep-wavオフ中間wavファイルを保持。

主要オプション(mix_voiceover.sh)

オプションデフォルト目的
--voice(必須)ナレーションmp3/wav(フルレベルを維持)。
--music(必須)BGM mp3/wav(ダッキングされ、ナレーションに合わせてループ)。
--out(必須)出力ミックスmp3。
--music-gain-8BGMの基本レベル(dB)。低いほど音量が小さい。
--duck8ダッキングの強さ(コンプレッサーのレシオ)。高いほど音声時に音楽が下がる。
--fade2音楽のフェードイン/アウト時間(秒)。
--mp3-quality2ffmpegのlibmp3lame -q:a。

安全性

  • AI生成音楽であることを開示してください。プラットフォームや状況に応じて必要です。
  • 商用利用: ACE-Step 1.5はMITライセンスであり、ライセンス・ロイヤリティフリー・合成データで学習されています。そのため、生成されたトラックは広く安全に使用できます。ただし、モデル自体の免責事項に従い、特定のアーティストやトラックのアイデンティティをコピーするようなプロンプトは避け、商用リリース前にオリジナルであることを確認してください。
  • 指示、プロンプト、生成された音声を外部サービスにアップロードしないでください。 すべては~/.bg-music/のローカルに留まります。

アンチパターン

  • 曖昧な一言プロンプト("曲"、"かっこいいやつ") — 汎用的な出力になります。ジャンル+雰囲気+楽器+テンポを指定してください。
  • BGMだけ必要なのにボーカルを要求する — インストゥルメンタル(デフォルト)のままにし、ナレーションの下でクリーンに配置できるようにします。
  • 1テイクだけ生成して納品する — --count 2で生成し、ユーザーに選択させてください。
  • ボイスオーバーの下に音楽を手動で重ねる — mix_voiceover.shを使用し、音楽が音声の下で自動的にダッキングされるようにします。
  • 「<アーティスト/曲>にそっくりな曲」をプロンプトで要求する — オリジナリティとライセンスのリスクがあります。
  • ~/.bg-music/の内容をリポジトリにコミットする。

リソース

  • モデル一覧(なぜ16 GBで2B-turboなのか)、完全なパラメータ早見表、雰囲気別プロンプトパターン、ライセンスの根拠、トラブルシューティング: REFERENCE.md
  • 音楽にミックスするナレーションの生成: voice-clone-narrationスキル。
  • 最終音声を動画で確認: review-mp4スキル。

関連スキル