SupoClip入門:長尺動画を自動で縦型ショートに変換

SupoClip が解決する問題は非常に直接的です。ポッドキャスト、インタビュー、ライブ配信などの長尺動画から、最も拡散力が高いと思われる3〜7個のクリップを自動で見つけ出し、魅力度でスコアリングし、単語単位の字幕、顔の中央トリミング、タイトルフックを備えた9:16の縦型ショート動画にレンダリングします。プロセス全体は自分のハードウェア上で実行され、透かしやプラットフォームへのロックインはありません。

技術スタックは5つの部分に分かれています。AssemblyAI または Whisper が音声文字起こしを行い、単語レベルのタイムスタンプを取得します。LLM が文字起こしからハイライトクリップを選択し、スコアを提供します。顔検出が縦型フレームで誰を中央に配置するかを決定します。字幕は単語タイムラインに基づいて単語ごとに表示されます。最後に FFmpeg が連結してエクスポートします。フロントエンドは Next.js、バックエンドは FastAPI、バックグラウンドタスクは ARQ ワーカーが Redis からキューを取得して実行し、PostgreSQL がユーザーとタスクデータを保存します。

コア依存関係と環境

まず、基本要件を確認します。

  • Git
  • Docker Engine または Docker Desktop(Compose プラグイン付き)
  • 少なくとも10GBの空きディスク容量(動画ファイル、モデルキャッシュ、レンダリング中間ファイルが必要です)
  • CPU でも動作しますが、文字起こしとレンダリング段階は遅くなります。NVIDIA GPU がある場合は、BACKEND_CPU_ONLY をオフにして高速化できます

必要な2つのAPIキー:

  • AssemblyAI APIキー:文字起こし用(デフォルトパス)
  • LLM プロバイダーのキー:Google、OpenAI、Anthropic、OpenRouter のいずれか

完全にローカルで実行したい場合は、文字起こしを Whisper に、クリップ選択モデルを Ollama に切り替えることができ、APIキーは一切不要です。

プロジェクト構造ツリー

supoclip/
├── frontend/          # Next.js フロントエンド、ポート3107、認証リクエストをバックエンドにプロキシ
├── backend/           # FastAPI バックエンド、ポート8000、/docs インタラクティブ API ドキュメント含む
├── worker/            # ARQ バックグラウンドタスクプロセス、文字起こし、分析、レンダリングを処理
├── mcp/               # MCP サーバー、Claude/Cursor から呼び出し可能
├── docs/              # セットアップ、設定、トラブルシューティングなどのドキュメント
├── scripts/           # データベース修復などの運用スクリプト
├── docker-compose.yml # 5サービス構成:frontend/backend/worker/postgres/redis
└── .env.example       # 環境変数テンプレート

データは名前付きボリュームに保存されます:postgres_data、redis_data、uploads、clips。バックエンドはさらに、字幕フォントとトランジション素材用に backend/fonts と backend/transitions の2つのローカルディレクトリをマウントします。

ステップバイステップのデプロイ手順

1. リポジトリをクローンして環境ファイルを準備

git clone https://github.com/FujiwaraChoki/supoclip.git
cd supoclip
cp .env.example .env

.env を編集し、少なくとも次の3項目を入力します。

ASSEMBLY_AI_API_KEY=あなたの_assemblyai_key
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=あなたの_google_key

2. ハイライト選択モデルの設定

LLM 変数は、クリップを選択するモデルを決定します。Gemini、GPT、Claude などのクラウドモデルに加えて、ollama: プレフィックスを使用して、v1/chat/completions プロトコルをサポートする任意のサービスを指定できます。たとえば、Defapi をローカルモデルに使用します:

LLM=ollama:あなたのモデルID
OLLAMA_BASE_URL=https://api.defapi.org/v1
OLLAMA_API_KEY=あなたの_defapi_key

SupoClip の ollama: プレフィックスはクライアントタイプを選択するだけで、ローカルでの Ollama の実行を強制するものではありません。コード内の OllamaProvider は AsyncOpenAI を使用して base_url と APIキーを受け取るため、ターゲットサービスが OpenAI のチャット補完プロトコルと互換性があれば機能します。Defapi はそのようなサービスの1つで、価格は公式チャネルの約半分で、ほとんどのモデルが3つのプロトコル(v1/chat/completions、v1/messages、v1beta/models/)と互換性があります。選択が機能するかどうかは、実際のテストに依存します。文字起こしと編集スタジオの AI 編集は引き続き独立したパスです。

3. ビルドと起動

./start.sh

スクリプトを待てない場合は、手動で行うこともできます:

docker-compose up -d --build

初回ビルドではイメージのプルと依存関係のインストールが必要で、CPU マシンでは数分かかる場合があります。次のコマンドで進捗を監視します:

docker-compose logs -f

5つのサービスすべてが healthy になれば起動完了です:

docker-compose ps

4. サービスヘルスステータスの確認

次のアドレスを開いて確認します:

docker-compose ps の出力には、supoclip-frontend、supoclip-backend、supoclip-worker、supoclip-postgres、supoclip-redis の5つのコンテナが含まれているはずです。

5. アカウント作成と動画アップロード

ブラウザでフロントエンドのホームページを開き、アカウントを登録します。ホームページは2つの入力方法をサポートしています:YouTube/Twitch/Kick リンクを貼り付けるか、ローカル動画ファイルを直接アップロードします。デフォルトのアップロード上限は4GBで、通常のビットレートの1080pフル動画であれば十分です。

6. 縦型ショートのプレビュー、編集、エクスポート

タスクを送信すると、タスクページにリアルタイムの進捗が表示されます:文字起こし、AI分析、レンダリングの各段階のステータスがプッシュされます。完了すると、各クリップの長さ、文字起こしの抜粋、AIの選択理由、バイラリティスコアを確認できます。

編集スタジオに入ると、次の調整が可能です:

  • クリップの端をドラッグして先頭と末尾をトリミング
  • 長いクリップを複数の小さなクリップに分割
  • 複数のクリップを結合
  • 字幕テキストを書き直す
  • 字幕スタイルを変更(フォント、アニメーション、サイズ、色)
  • プラットフォームプリセットでエクスポート:TikTok、Reels、Shorts

エクスポート時に「Vertical output」を選択すると、顔を中央にトリミングし、単語ごとの字幕がすでに焼き込まれた9:16の縦型ビデオが得られます。

一般的な問題のトラブルシューティング

フロントエンドページが開かない

ホストのポートを確認します。テンプレートのデフォルトは FRONTEND_PORT=3107 ですが、古いバージョンからアップグレードした場合、.env にこの変数がないと3001にフォールバックします。docker-compose port frontend 3107 を使用して実際のマッピングを確認します。

ログイン時に Invalid origin エラー

NEXT_PUBLIC_APP_URL と BETTER_AUTH_URL は、プロトコルとポートを含めてブラウザのアドレスと完全に一致している必要があります。localhost と 127.0.0.1 は異なるオリジンです。別のドメインやポートにアクセスする場合は、BETTER_AUTH_TRUSTED_ORIGINS にカンマ区切りの明示的なリストを設定する必要があります。ワイルドカードはサポートされていません。

タスクが queued のまま動かない

まずワーカーログを確認します。docker-compose logs -f worker でエラー情報が直接表示されます。次に curl -f http://localhost:8000/health/worker でワーカーのハートビートを確認します。503が返ってきた場合、ワーカーが失われているか Redis に接続できていません。ARQ のハートビートは約31秒で期限切れになります。

文字起こしが30%で止まる

この段階では AssemblyAI を呼び出しています。バックエンドログで APIキーが有効か、アカウントのクォータが十分かを確認します。ステータスポーリングには全体的なタイムアウト予算があり、デフォルトは900秒です。タイムアウトすると同じ文字起こしタスクが再試行されますが、二重請求はありません。長い動画の場合は、ASSEMBLY_AI_HTTP_TIMEOUT_SECONDS を適宜増やします。

クリップ選択モデルがエラーまたは不正な出力形式

LLM プレフィックスとプロバイダーキーが一致している必要があります:ollama: には OLLAMA_BASE_URL と OLLAMA_API_KEY、google-gla: には GOOGLE_API_KEY など。ローカルモデルが構造的に不正な JSON を返した場合、エージェントは最大2回再試行します(output_retries=2)。命令追従能力が高いモデルに切り替えると通常解決します。

アカウント登録時に Failed to create account エラー

おそらくデータベーススキーマがコードより古いです。冪等修復スクリプトを実行します。列を追加するだけで既存データには触れません:

docker compose exec -T postgres psql -U supoclip -d supoclip < scripts/selfhost-schema-repair.sql

このデータベースに対して prisma db push や prisma migrate deploy を実行しないでください。バックエンドは Prisma が認識しないテーブルを管理しており、db push はそれらを削除します。

追加情報 / 高度なトピック

  • 完全ローカルルート:TRANSCRIPTION_PROVIDER を whisper に変更し、クリップ選択には LLM=ollama:... でローカルの Ollama サービスを使用します。Docker 内のデフォルトの Ollama アドレスは http://host.docker.internal:11434/v1 で、ホストの Ollama が対応するポートでリッスンしている必要があります。
  • MCP 統合:リポジトリの mcp/ ディレクトリには MCP サーバーが用意されており、Claude、Cursor などのクライアントから SupoClip の編集機能を直接呼び出すことができます。
  • REST API:/settings/api-keys で APIキーを生成し、バックエンド API を直接呼び出せます。スクリプトによるバッチ処理に適しています。
  • B-roll 素材:PEXELS_API_KEY を設定すると、AI がクリップを選択した後、Pexels の無料ストックビデオを自動的に挿入カットとしてマッチングします。
  • ライセンスの境界:現在のバージョンは SupoClip Noncommercial Source License 1.1 です。非商用利用および個人クリエイターのソーシャルメディアでの収益化は無料ですが、企業、組織、チーム、または代行編集サービスは書面による許可を申請する必要があります。始める前に LICENSE ファイル、特に「Individual Creators」の定義を読んでください。