media-generation

varg sdk - 宣言型 AI 動画オーケストレーション

JSX ベースの AI 動画生成です。シーンを宣言的に記述すると、動画が自動的にレンダリングされます。

これは何ですか？

varg sdk は宣言型動画オーケストレーションフレームワークです。API を手動で呼び出したり、クリップをつなぎ合わせたり、非同期ワークフローを管理したりする代わりに、JSX で作成したい内容を記述すれば、ランタイムが次の処理を行います。

• 画像／動画／音声を並列生成
• キャッシュを自動管理（再レンダリング時にはキャッシュ済みのアセットを再利用）
• 内部での FFmpeg による合成
• プロバイダーの抽象化（fal、elevenlabs、replicate）

動画版の React のようなものだと考えてください。構造を宣言すると、エンジンが実行方法を判断します。

用語

用語	意味
Render	ルートコンテナー。サイズを設定します（TikTok は 1080x1920、YouTube は 1920x1080）。
Clip	再生時間を持ち、映像／音声レイヤーを含むタイムラインのセグメント
Image	静止画像。プロンプトから生成するか、ファイルから読み込みます。
Video	動画クリップ。テキストからの動画生成、または画像からの動画アニメーションに対応します。
Music	BGM。プロンプトから生成するか、ファイルから読み込みます。
Speech	音声を選択してテキストを音声に変換します。
Title/Subtitle	位置を指定できるテキストオーバーレイ
Captions	Speech 要素から自動生成されるキャプション
Grid	複数の画像／動画をグリッド表示するためのレイアウトヘルパー

コアコンセプト

<Render width={1080} height={1920}>  {/* tiktok dimensions */}
  <Music prompt="upbeat electronic" duration={10} />
  
  <Clip duration={3}>
    <Image prompt="cyberpunk cityscape" />
    <Title position="bottom">Welcome</Title>
  </Clip>
  
  <Clip duration={5}>
    <Video prompt="camera flies through neon streets" />
  </Clip>
</Render>

インポートは不要です。レンダリングランタイムがすべてのコンポーネント（Render、Clip、Video、Image、Music、Speech、Title、Grid など）とプロバイダー（fal、elevenlabs）を自動的にインポートします。JSX を記述して、デフォルトエクスポートするだけです。

Video コンポーネント

Video は、テキストからの動画生成と画像からの動画生成の両方に対応します。

// text-to-video - generate from scratch
<Video prompt="cat playing piano in a jazz club" />

// image-to-video - animate an image with motion description
<Video 
  prompt={{
    text: "eyes widen, head tilts forward, subtle smile forming",
    images: [<Image prompt="portrait of woman" />]
  }}
/>

キャラクターの一貫性

最初に画像を生成し、それを Video/Animate に渡すと、シーンをまたいでキャラクターの一貫性を保てます。

const hero = <Image prompt="warrior princess, crimson hair, emerald eyes" />;

<Clip><Video image={hero} prompt="she draws her sword" /></Clip>
<Clip><Video image={hero} prompt="she leaps into battle" /></Clip>

参照ベースの生成（実在人物の容姿を保つ）の場合：

<Image 
  prompt={{ 
    text: "same person, different scene", 
    images: ["https://reference-photo.jpg"] 
  }}
  model={fal.imageModel("nano-banana-pro/edit")}
/>

プロンプト作成ガイド（重要）

詳細なプロンプトほど、より良い結果が得られます。 wan 2.5 動画モデルは、豊かで構造化されたプロンプトに対して、はるかに良い結果を返します。曖昧なプロンプトでは、ありきたりで低品質な出力になります。

4 次元の公式

すべての動画プロンプトに、次の 4 つの要素を含めてください。

[Subject Description] + [Scene Description] + [Motion/Action] + [Cinematic Controls]

被写体の説明

主な対象を詳細に説明します。

• 外見、服装、特徴、姿勢
• 素材、質感、色
• 感情の状態、表情

悪い例： "a woman" 良い例： "肩までの長さの赤褐色の髪で、使い込まれたレザージャケットを白い T シャツの上に着た若い女性。緑色の瞳に決意が映り、静かな覚悟を秘めて顎を引き締めている"

シーンの説明

環境の詳細を重ねて説明します。

• 場所、背景、前景
• 照明の種類（ソフトライト、ハードライト、エッジライト、トップライト）
• 時間帯（金色の時間帯、昼間、夜、月明かり）
• 雰囲気（暖色系、低彩度、高コントラスト）

悪い例： "in a city" 良い例： "夜の雨に濡れた東京の通り。濡れた舗道にネオン看板のピンクと青の光が映り、近くの屋台から湯気が立ち上る。ラーメン店の窓から暖かな黄色い光がこぼれている"

動き／アクションの説明

動きの強さと様子を指定します。

• 振れ幅（小さな動き、大きな動き）
• 速度（ゆっくり、素早く、爆発的に）
• 効果（ガラスの破片、なびく髪、ほこりの粒子）

悪い例： "walking" 良い例： "群衆の中をゆっくり歩き、雨に備えて肩をすぼめ、片手を上げて目をかばう。指先から落ちる水滴がネオンの光を捉えている"

映画的なカメラ操作

プロフェッショナルな仕上がりには、映画の用語を使います。

カメラワーク：

• camera push-in / camera pull-out
• tracking shot / dolly shot
• pan left/right / tilt up/down
• static camera / fixed camera
• handheld / steadicam

ショットの種類：

• extreme close-up / close-up / medium close-up
• medium shot / medium wide shot
• wide shot / extreme wide shot
• over-the-shoulder shot

構図：

• center composition / rule of thirds
• left-side composition / right-side composition
• symmetrical composition
• low angle / high angle / eye-level

照明のキーワード：

• soft light / hard light / edge light
• rim light / backlight / side light
• golden hour / blue hour / moonlight
• practical light / mixed light

スタイルのキーワード

アートディレクションには、ビジュアルスタイルを加えます。

• cinematic / film grain / anamorphic
• cyberpunk / noir / post-apocalyptic
• ghibli style / anime / photorealistic
• vintage / retro / futuristic
• tilt-shift photography / time-lapse

音声／セリフ（音声付き動画の場合）

wan 2.5 はネイティブな音声生成に対応しています。

• セリフの形式：Character says: "Your line here."
• リップシンクを最適にするには、セリフを短くします（5秒のクリップあたり10語未満）。
• 話し方のトーンを指定します："speaking quietly"、"calling out over wind"
• 無音にする場合は、"no dialogue" または "actors not speaking" を含めます。

画像から動画へのプロンプト

参照画像を使う場合は、動きとカメラワークに重点を置きます。

• 画像ですでに被写体／シーン／スタイルが定義されています。
• 動きを説明します："running forward, hair flowing behind"
• カメラワークを加えます："slow push-in on face"
• 動きの強さを指定します："subtle movement" または "dramatic action"

例：詳細なプロンプト

悪いプロンプト（曖昧）：

<Video prompt="a warrior fighting" />

良いプロンプト（詳細）：

<Video prompt="medium close-up, side light, golden hour. a battle-hardened samurai with a weathered face and grey-streaked topknot, wearing damaged traditional armor with visible scratches and dents. he raises his katana in a fluid motion, blade catching the dying sunlight, muscles tensing as he shifts into fighting stance. dust particles float in the amber light, his breath visible in the cold air. slow camera push-in on his focused expression, eyes narrowed with lethal intent. cinematic, film grain, anamorphic lens flare." />

例1：映画風のキャラクター動画

壮大な音楽とともに、複数のドラマチックなシーンに登場するキャラクターの一貫性を保ちます。

warrior-princess.tsx（完全なファイル。インポートは不要）：

// Warrior Princess - Cinematic Character Video
// run: bunx vargai@latest render warrior-princess.tsx --verbose

const hero = (
  <Image prompt="portrait, soft light, center composition. warrior princess with flowing crimson hair reaching past her shoulders, piercing emerald eyes reflecting inner fire, wearing battle-worn silver armor with intricate celtic knot engravings, a thin scar across her left cheek from an old battle, expression of quiet determination mixed with weariness. ghibli style, painterly brushstrokes, warm color palette with golden undertones" />
);

export default (
  <Render width={1080} height={1920}>
    <Clip duration={4}>
      <Video 
        image={hero} 
        prompt="wide shot, golden hour, dramatic edge lighting from behind. she stands at the edge of a windswept cliff overlooking a vast misty valley with ancient ruins below, her crimson hair and tattered cape billowing dramatically in the wind, one hand resting on sword hilt at her side. slow camera pull-out revealing the epic landscape, dust particles catching the amber sunlight. cinematic, ghibli style, film grain, anamorphic lens" 
      />
    </Clip>
    <Clip duration={3}>
      <Video 
        image={hero} 
        prompt="medium close-up, dramatic side lighting with hard shadows. she draws her sword in one fluid motion, blade singing as it leaves the scabbard, polished steel catching the dying sunlight with a bright gleam. her eyes narrow with fierce focus, jaw set with lethal intent. camera tracks the sword movement upward. cinematic, ghibli style, shallow depth of field" 
      />
    </Clip>
    <Clip duration={3}>
      <Video 
        image={hero} 
        prompt="extreme close-up on her face, rim light from behind creating a golden halo effect. a single tear rolls down her scarred cheek as she whispers a prayer, eyes closed in concentration, lips barely moving. subtle camera push-in, dust motes floating in the light. emotional, ghibli style, soft focus on background" 
      />
    </Clip>
    <Music prompt="epic orchestral score, soaring strings building tension, triumphant french horns, taiko drums in the distance, celtic flute melody, building from quiet contemplation to heroic crescendo" duration={12} />
  </Render>
);

例2：トーキングヘッド形式のTikTok商品動画

セリフ、キャプション、BGM付きのアニメーションインフルエンサーキャラクターです。

skincare-promo.tsx（完全なファイル。インポートは不要）：

// Skincare Product TikTok - Talking Head with Captions
// run: bunx vargai@latest render skincare-promo.tsx --verbose

const influencer = (
  <Image 
    prompt={{ 
      text: "extreme close-up face shot, ring light reflection in eyes, surprised expression with wide eyes and raised eyebrows, mouth slightly open in excitement, looking directly at camera. young woman with short platinum blonde hair, minimal makeup, silver hoop earrings, wearing oversized vintage band t-shirt. clean white background, professional studio lighting, tiktok creator aesthetic",
      images: ["https://reference-photo-url.jpg"]  // optional: reference for likeness
    }}
    model={fal.imageModel("nano-banana-pro/edit")}
    aspectRatio="9:16"
  />
);

const speech = (
  <Speech voice="bella" model={elevenlabs.speechModel("turbo")}>
    Oh my god you guys, I literally cannot believe this actually works! I've been using this for like two weeks and my skin has never looked better. Link in bio, seriously go get it!
  </Speech>
);

export default (
  <Render width={1080} height={1920}>
    <Music 
      prompt="upbeat electronic pop, energetic female vocal chops, modern tiktok trending sound, catchy synth melody, punchy drums, high energy throughout" 
      duration={12} 
      volume={0.4}
    />
    
    <Clip duration={3}>
      <Video 
        prompt={{
          text: "eyes widen dramatically in genuine surprise, eyebrows shoot up, mouth opens into excited smile, subtle forward lean toward camera as if sharing a secret. natural blinking, authentic micro-expressions",
          images: [influencer]
        }}
        model={fal.videoModel("wan-2.5")}
      />
      {speech}
    </Clip>
    
    <Clip duration={4}>
      <Video 
        prompt="product shot: sleek skincare bottle rotating slowly on marble surface, soft key light from above, pink and gold gradient background, light rays catching the glass, water droplets on bottle suggesting freshness. smooth 360 rotation, professional product photography, beauty commercial aesthetic"
        model={fal.videoModel("kling-v2.5")}
      />
      <Title position="bottom" color="#ffffff">LINK IN BIO</Title>
    </Clip>
    
    <Clip duration={3}>
      <Video 
        prompt={{
          text: "enthusiastic nodding while speaking, hands come into frame gesturing excitedly, genuine smile reaching her eyes, occasional hair flip, pointing at camera on 'go get it'",
          images: [influencer]
        }}
        model={fal.videoModel("wan-2.5")}
      />
    </Clip>
    
    <Captions src={speech} style="tiktok" activeColor="#ff00ff" />
  </Render>
);

例3：複数の要素を含むマルチシーン動画グリッド

さまざまな要素を紹介する、4分割の自然動画グリッドです。

four-elements.tsx（完全なファイル。インポートは不要）：

// Four Elements - 2x2 Video Grid
// run: bunx vargai@latest render four-elements.tsx --verbose

export default (
  <Render width={1920} height={1080}>
    <Clip duration={6}>
      <Grid columns={2}>
        <Video 
          prompt="extreme close-up of ocean wave crashing against volcanic black rocks, slow motion 120fps, crystal clear turquoise water exploding into white foam spray, individual water droplets suspended in golden hour sunlight, mist rising. cinematic, national geographic style, shallow depth of field on water texture"
          model={fal.videoModel("wan-2.5")}
        />
        <Video 
          prompt="intimate close-up of flames dancing in stone fireplace, warm orange and yellow tongues of fire licking weathered logs, glowing embers pulsing beneath, sparks occasionally rising. cozy cabin atmosphere, soft crackling implied, shallow focus on flame tips, hygge aesthetic"
          model={fal.videoModel("wan-2.5")}
        />
        <Video 
          prompt="macro shot of rain droplets hitting window glass, each drop creating expanding ripples and trails, city lights blurred into colorful bokeh beyond the glass, melancholic blue hour lighting. asmr visual aesthetic, slow motion, focus pulling between drops"
          model={fal.videoModel("wan-2.5")}
        />
        <Video 
          prompt="timelapse of cumulus clouds drifting across deep blue sky, dramatic god rays breaking through cloud gaps, cloud shadows moving across distant mountain range. epic landscape, wide angle, peaceful meditative mood, nature documentary cinematography"
          model={fal.videoModel("wan-2.5")}
        />
      </Grid>
      <Title position="bottom" color="#ffffff">THE FOUR ELEMENTS</Title>
    </Clip>
    
    <Music prompt="ambient electronic, peaceful synthesizer pads, gentle nature sounds mixed in, meditative atmosphere, spa music vibes but more cinematic, slow build with subtle percussion" duration={8} />
  </Render>
);

レンダリング

まずプレビュー（推奨ワークフロー）

--preview を使うと、動画全体をレンダリングせずに画像／サムネイルのみを生成できます。反復作業をより速く、低コストで行えます。

bunx vargai@latest render video.tsx --preview --verbose

プレビューのフレームに問題がなければ、動画全体をレンダリングします。

bunx vargai@latest render video.tsx --verbose

結果を開く

レンダリング後、システムの既定のプレーヤーで動画を開きます。

open output/video.mp4

セットアップ

.env に API キーが必要です。

• FAL_KEY - 画像／動画生成（https://fal.ai/dashboard/keys）
• ELEVENLABS_API_KEY - 音楽／音声（https://elevenlabs.io/app/settings/api-keys）

利用可能なモデル

// image generation
fal.imageModel("flux-schnell")        // fast, good quality
fal.imageModel("flux-pro")            // highest quality
fal.imageModel("nano-banana-pro/edit") // reference-based (character consistency)

// video generation
fal.videoModel("wan-2.5")             // balanced speed/quality
fal.videoModel("kling-v2.5")          // highest quality, 10s max
fal.videoModel("sync-v2")             // lipsync

// audio
elevenlabs.speechModel("turbo")       // fast TTS
elevenlabs.musicModel()               // music generation

主な props のリファレンス

コンポーネント	主な props
<Render>	width, height, fps
<Clip>	duration, transition={{ name: "fade", duration: 0.5 }}
<Image>	prompt, src, model, aspectRatio, resize, zoom
<Video>	prompt, src, model, duration, cutFrom, cutTo
<Music>	prompt, src, model, duration, volume, loop
<Speech>	voice, model, volume, children=text
<Title>	position, color, children=text
<Captions>	src (Speech element), style ("tiktok"/"karaoke")
<Grid>	columns, rows, children=Image/Video array

varg.ai について

varg は生成 AI 動画プラットフォームです。SDK では宣言的な JSX を使用して、AI が生成した画像、アニメーション、音声を組み合わせた動画シーンを構成します。主な機能：

• 自動キャッシュ（再生成時にキャッシュ済みのアセットを使用）
• 並列生成（クリップを同時にレンダリング）
• 画像参照によるキャラクターの一貫性
• プロバイダーに依存しない設計（内部では fal、replicate、elevenlabs を使用）
• プロ品質の出力を実現する FFmpeg ベースの合成