studio-setup

Studio のセットアップ

2 つの質問、2 つのスクリプトです。今すぐ使えるものは何ですかには、同梱の、scripts/doctor.pyが答えます。*残りを使えるようにするにはどうすればよいですか*には、video-studio setup`が答えます。目の前にあるマシンについて、両方に答えてください。インストール済みのツールを見つからないと説明すれば、ユーザーの時間を無駄にし、それ以外の説明まで疑わしくなります。

必要なもの

scripts/doctor.py はこのスキルに同梱されています。標準ライブラリのみを使うため、スキルをインストールすればすぐにステータスレポートが機能します。現在のプロジェクト内の.env、次に~/.config/video-studio/.env、最後にシェルからキーを読み込みます。

setup.pyはここには同梱されていません。エンジン独自のcomposerディレクトリにインストールされるため、単独のファイルではないからです。pip install 'video-studio-engine @ https://github.com/scrollmark/social-skills/archive/refs/heads/master.tar.gz'が必要で、video-studio setupとして実行します。このインストールがなければ、インストール計画もauto/system/manualの分類もありません。到達可能なものを確認するdoctorのレポートは引き続き使えますが、エージェントが頼まれてもいないパッケージマネージャーのインストールを実行するのを防ぐ唯一の機能が失われ、結局、手作業で不足分を解消することになります。このスキルのreferences/tooling-inventory.mdが全体像を示します。状態を把握しているのはdoctorだけです。

環境を確認する

python3 scripts/doctor.py           # 現在到達可能なもの
python3 scripts/doctor.py --json    # 同じ内容を機械可読形式で出力

Doctorはカテゴリごとにレポートします。パブリックドメインのアーカイブ、ストック、生成動画、生成画像、生成音声、音声に加えて、必須バイナリも確認します。キーが存在することは確認しますが、使えることまでは確認しません。使用量の上限超過やモデルの提供終了により、呼び出し時にキーが拒否されることもあります。その場合は個々のスクリプトが報告します。

ワークフローを説明するのではなく、実際に教えるには、video-studio tutor --listで同梱チュートリアルの一覧を表示します。--step <name> <n>は1つのステップだけを提示します。これが設計方針です。チュートリアル全体を一度に貼り付けても、単なる文書にすぎません。途中を読む人はおらず、何が伝わったかも分かりません。ステップを提示し、試してもらい、うまくいったか確認してから次に進みます。--showは計画を立てるために使うもので、貼り付けてはいけません。まずgetting-startedから始めてください。ここでは、このリポジトリに同梱されていないcomposerが必要なステップが明示されています。

調達方法を提案する前に実行してください。キーがないソースを提案すると、見積もりも提案内容も誤ったものになります。

動かないものを修正する

video-studio setup                  # レポートと正確な計画を表示。変更は行いません
video-studio setup --yes            # 実行可能な修正を実際に実行
video-studio setup --yes --only composer,voice

不足している各コンポーネントは分類されます。この分類が重要です。

• auto — ツールチェーンのディレクトリ内に限定され、何度実行しても安全です。composerのnpmパッケージのインストール、ローカル音声モデルのウォームアップ、.env.exampleから.envへのコピーなどが該当します。
• system — パッケージマネージャーによるffmpegやnodeのインストールなど、そのディレクトリの外側にあるマシンを変更します。実行は可能ですが、それは誰かのコンピューターです。
• manual — 人が対応する必要があります。APIキーの取得、課金の有効化、規約への同意、ネットワークアクセスを許可したサンドボックスホストの再起動などが該当します。実行はできません。マシンでは実行できないことに対して「このコマンドを実行してください」と表示すると、ほかの出力への信頼まで損ないます。

毎回、まず確認してください。安全なものでも例外ではありません。--yesがなければ何も実行されず、--yesを付けるとシステムレベルのインストールも実行されます。何が不足しているかをユーザーに分かる言葉で伝え（「レンダラーがインストールされていません」など）、自分で修正できるかどうかを説明してから、確認を求めてください。

すべて揃っている場合は何も言わず、そのまま作業を進めてください。問題がないことを逐一伝えるのはノイズです。

Tier-0 の最低条件

3つの要素があり、どれか1つでも欠けると何も動きません。ffmpeg と ffprobe（すべての尺の計測、トリミング、ラウドネス調整、キーイング）、node 18+（コンポーザーはこれを通じてレンダリングとプレビューを行います）、そして uv（同梱スクリプトをそれぞれ固定された依存関係で実行します）。ほかの要素は利用範囲を広げますが、パイプラインが成り立つかどうかを決めるのはこの3つです。

その次に価値の高い追加要素は、無料のPexelsキーです。「あれの映像を探して」という依頼に、運任せではなく通常どおり応えられるようになり、費用もかかりません。全項目、ティア、費用、権利については references/tooling-inventory.md を参照してください。

ライセンス

このスキルから利用できるすべての外部サービスについて、費用と出力の利用条件を、このファイルと同じ場所にある SERVICES.md に記載しています。公開する前に確認してください。特に注意が必要なのは音楽の項目です。無料バックエンドの再配布権は不明確ですが、有料のものはライセンス済みカタログです。

showwatcher は利用できず、ステップ8はもう待つ必要がありません

showwatcher は内部用アナライザーで、どこにも公開されていません。インストールできるパッケージもリポジトリもありません。video-studio setup にはインストールコマンドなしで表示され、doctor.py は見つからないと報告します。これは正確な挙動です。「専用リポジトリからインストールする」という指示は古いものとして扱ってください。

ステップ8はこれに依存しません。video-production スキルには独自の qc_render スクリプトが含まれており、build_props が書き出した plan.json とレンダリング結果を照合します。具体的には、尺、プラン自体の整合性、黒い末尾、フリーズした終端、解像度、fpsを確認します。ffmpeg／ffprobe を使う標準ライブラリのみの処理なので、インストールは一切不要です。

同梱スクリプトでは、映像の見た目を判断できません。ぼけ、字幕の重なり、パレットから外れた色、テキストの見切れを確認するには、デコードしたフレームとモデルが必要です。そのため、確認手順は今でも2段階です。まずそのスクリプトを実行し、次にフレームを取り出して、実際に確認し、確認したことを声に出して伝えてください。手動確認を黙って省略するくらいなら、確認工程がないほうがまだましです。

アンチパターン

• 実際の環境を確認せず、ドキュメントの記述を引用する。 インベントリーは案内図であり、現在の状態ではありません。ツールが利用可能だと言う前に doctor を実行してください。
• 許可を得ずにインストールする。 --yes はシステム全体に変更を加えます。毎回、それは相手のコンピューターです。
• 手作業をコマンドのように装う。 APIキーや請求アカウントは brew install できません。該当するリンクを具体的に案内してください。
• キーが存在すれば使えると思い込む。 doctor が確認できるのは存在の有無だけです。クォータ、請求、提供終了したモデルは、呼び出し時に失敗します。
• サンドボックスにネットワークがあると思い込む。 素材の検索も生成の呼び出しも、すべてネットワークが必要です。ネットワークなしで起動したホストでは、プロバイダー障害に見えるタイムアウトが発生します。