# Kandinsky S2V 1.0

Kandinsky S2V 1.0 は、参照フレームと音声トラックからアバター動画を生成します。フレーム内の人物は音声に合わせてアニメーション化され、頭部だけでなく全身が動きます。音声は出力ではなく条件であり、モデルはオーディオを生成しません。生成結果のサウンドトラックは、入力として渡したトラックそのものです。

両方の条件は[Qwen2.5-Omni-7B](https://huggingface.co/Qwen/Qwen2.5-Omni-7B)を介して処理されます。その隠れ状態がプロンプトをエンコードし、音声タワーがスピーチをエンコードします。音声はフレームごとに整列されたクロスアテンションアダプターを通じてトランスフォーマーに入力されるため、各潜在フレームは自身がカバーするスピーチにのみアテンションを向けます。クリップは5秒（25 fpsで125フレーム）のチャンク単位で生成され、各チャンクはそれ以前のチャンクのFramePackメモリを保持するため、長いトラックでもチャンク境界をまたいで一貫性が保たれます。

Kandinsky S2V 1.0 は [モジュラーパイプライン](../../modular_diffusers/overview) としてのみ統合されており、標準的な `DiffusionPipeline` クラスは存在しません。

## チェックポイント

| チェックポイント | Transformer | ブロック | スケジューラー | 手順 | ガイダンス |
|---|---|---|---|---|---|
| [Lite][lite] | 2B | [KandinskyS2VAutoBlocks](/docs/diffusers/v0.43.0/ja/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VAutoBlocks) | [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) | 50 | 3.0 |
| [Pro][pro] | 21B | [KandinskyS2VAutoBlocks](/docs/diffusers/v0.43.0/ja/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VAutoBlocks) | [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/ja/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) | 50 | 3.0 |
| [Lite 蒸留][lite-distill] | 2B | [KandinskyS2VDistilledAutoBlocks](/docs/diffusers/v0.43.0/ja/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VDistilledAutoBlocks) | [PiflowScheduler](/docs/diffusers/v0.43.0/ja/api/schedulers/piflow#diffusers.PiflowScheduler) | 16 | off |
| [Pro distilled][pro-distill] | 21B | [KandinskyS2VDistilledAutoBlocks](/docs/diffusers/v0.43.0/ja/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VDistilledAutoBlocks) | [PiflowScheduler](/docs/diffusers/v0.43.0/ja/api/schedulers/piflow#diffusers.PiflowScheduler) | 16 | off |

蒸留済みチェックポイントは、`PiflowScheduler`をデフォルト値ではなく、`shift=10.0`および`n_grid=5`で設定します。

[lite]: https://huggingface.co/kandinskylab/Kandinsky-S2V-1.0-Lite-Diffusers [pro]: https://huggingface.co/kandinskylab/Kandinsky-S2V-1.0-Pro-Diffusers [lite-distill]: https://huggingface.co/kandinskylab/Kandinsky-S2V-1.0-Lite-distill-Diffusers [pro-distill]: https://huggingface.co/kandinskylab/Kandinsky-S2V-1.0-Pro-distill-Diffusers

`ModularPipeline.from_pretrained` は、チェックポイントからブロックを選択します。各ステップは、上記の値がデフォルトとして使用されます。Classifier-free guidance は呼び出し引数ではなく、`guider` コンポーネントです。ベースのチェックポイントでは 3.0 が同梱されています。蒸留済みモデルには guider も `negative_prompt` も含まれていません。これは、guidance がすでに student に組み込まれているためです。

## 使用方法

```py
import librosa
import torch
from diffusers import ModularPipeline
from diffusers.utils import encode_video, load_image

pipe = ModularPipeline.from_pretrained("kandinskylab/Kandinsky-S2V-1.0-Lite-distill-Diffusers")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")

image = load_image("reference.png")
audio, _ = librosa.load("speech.wav", sr=16000)  # a mono waveform at 16 kHz, for the model
speech, sample_rate = librosa.load("speech.wav", sr=None)  # the original track, added to the output video

video = pipe(image=image, audio=audio, output="videos")[0]
encode_video(
    video,
    fps=25,
    output_path="avatar.mp4",
    audio=torch.from_numpy(speech)[None],
    audio_sample_rate=sample_rate,
)
```

すべてのコンポーネントをデバイス上に配置した場合、Pro チェックポイントは 7B の音声エンコーダーおよびテキストエンコーダーと 80 GB の GPU に収まりません。`ComponentsManager` を介してオフロードしてください。

```py
import librosa
import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.utils import encode_video, load_image

manager = ComponentsManager()
pipe = ModularPipeline.from_pretrained("kandinskylab/Kandinsky-S2V-1.0-Pro-Diffusers", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)
manager.enable_auto_cpu_offload(device="cuda", memory_reserve_margin="40GiB")

image = load_image("reference.png")
audio, _ = librosa.load("speech.wav", sr=16000)
speech, sample_rate = librosa.load("speech.wav", sr=None)

video = pipe(image=image, audio=audio, output="videos")[0]
encode_video(
    video,
    fps=25,
    output_path="avatar.mp4",
    audio=torch.from_numpy(speech)[None],
    audio_sample_rate=sample_rate,
)
```

マージンとは、モデルを GPU に移動した際に、重みのほかに確保しておくメモリ量です。この領域にはチャンクの VAE デコードを保持する必要があり、512x768 の場合で約 33 GiB になります。デフォルトの 3 GB では、デコード中も transformer が GPU に留まるため、メモリ不足が発生します。40 GiB に設定すると、80 GB の GPU 上でピークは約 50 GiB になります。`load_components` の後にオフロードを有効にしてください。これにより、すべてのコンポーネントに適用されます。

## 注記

- `image` は PIL 画像、`audio` は 16 kHz のモノラル浮動小数点波形（[-1, 1] の範囲）であり、テンソルまたは `(samples,)` の形状を持つ配列です。このパイプラインはファイルを読み込みません。
- トップレベルのブロック（`text_encoder`、`vae_encoder`、`denoise`、`decode`）は、それぞれ単体でも実行できます。個別に実行する場合は、各ブロックに同じ `num_latent_frames` と `fps` を渡してください。
- `num_chunks` が渡されない限り、チャンクの数は音声トラックの長さに従います。いずれの場合も動画はトラックに合わせてトリミングされるため、トラックの終了以降のチャンクは計算されますが、警告とともに破棄されます。
- ガイダンスを用いる場合、無条件パスではネガティブプロンプトに*置き換え*られ、音声はサイレンスされるため、ガイダンスはテキストと音声の両方にまたがるものになります。

## KandinskyS2VModularPipeline[[diffusers.KandinskyS2VModularPipeline]]

#### diffusers.KandinskyS2VModularPipeline[[diffusers.KandinskyS2VModularPipeline]]

```python
diffusers.KandinskyS2VModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/kandinsky_s2v/modular_pipeline.py#L91)

Kandinsky S2V 1.0 の音声から動画への生成を行う ModularPipeline。

## KandinskyS2VAutoBlocks[[diffusers.KandinskyS2VAutoBlocks]]

#### diffusers.KandinskyS2VAutoBlocks[[diffusers.KandinskyS2VAutoBlocks]]

```python
diffusers.KandinskyS2VAutoBlocks()
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/kandinsky_s2v/modular_blocks_kandinsky_s2v.py#L108)

Kandinsky S2V 1.0 による音声から動画への生成のためのモジュール型パイプライン: 参照フレームと音声トラックから、チャンクごとに生成されるアバター動画。

コンポーネント: text_encoder (`Qwen2_5OmniThinkerForConditionalGeneration`) tokenizer (`Qwen2_5OmniProcessor`) text_encoder_2 (`CLIPTextModel`) tokenizer_2 (`CLIPTokenizer`) vae (`AutoencoderKLHunyuanVideo`) video_processor (`VideoProcessor`) transformer (`KandinskyS2VTransformer3DModel`) scheduler (`FlowMatchEulerDiscreteScheduler`) guider (`ClassifierFreeGuidance`)

Inputs: prompt (`str`, *optional*, defaults to The video presents a stable medium close-up of a subject facing the camera directly. The subject exhibits natural, lifelike body dynamics: the head and shoulders move fluidly with the rhythm of speech. The lighting is even, maintaining a balanced natural exposure to clearly define facial features without washout. Throughout the sequence, the subject engages in continuous speech marked by precise, high-fidelity articulation. The lips move in a rhythmic, natural pattern: alternating between brief firm closures and relaxed openings. During these openings, the tips of the upper teeth are momentarily and realistically visible, exhibiting natural enamel texture. The upper lip lifts subtly over the teeth during enunciation, while the jaw performs minimal vertical oscillations synchronized with the speech cadence. Facial micro-expressions are active yet restrained; eyebrows rise and lower slightly with minute asymmetry. The eyes maintain a steady, engaged gaze forward, punctuated by smooth, deliberate blinks. ): The prompt to guide the generation. negative_prompt (`str`, *optional*): The prompt for the unconditional pass of the guidance. Defaults to `DEFAULT_NEGATIVE_PROMPT` when the guidance needs one. audio (`Tensor | ndarray`): The speech track that drives the generation: a mono float waveform in [-1, 1] at 16000 Hz, shaped (samples,). num_latent_frames (`int`, *optional*, defaults to 32): Latent frames per chunk; 32 gives 125 frames (5 s at 25 fps). fps (`int`, *optional*, defaults to 25): Frame rate the chunk length is computed at. num_chunks (`int`, *optional*): Number of chunks to generate. Defaults to however many cover the speech track; the video is trimmed to the track either way. image (`Image`): The reference frame to animate. height (`int`, *optional*): The height in pixels of the generated video. Defaults to the 512 bucket closest to the reference frame. width (`int`, *optional*): The width in pixels of the generated video, chosen together with `height`. generator (`Generator`, *optional*): Torch generator for deterministic generation. num_inference_steps (`int`, *optional*, defaults to 50): The number of denoising steps. scale_factor (`tuple`, *optional*, defaults to (1.0, 2.0, 2.0)): Per-axis RoPE scale for the resolution bucket. output_type (`str`, *optional*, defaults to pil): Output format: 'pil', 'np', 'pt'.

出力: 動画 (`list`): 生成された動画。

## KandinskyS2VDistilledModularPipeline[[diffusers.KandinskyS2VDistilledModularPipeline]]

#### diffusers.KandinskyS2VDistilledModularPipeline[[diffusers.KandinskyS2VDistilledModularPipeline]]

```python
diffusers.KandinskyS2VDistilledModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/kandinsky_s2v/modular_pipeline.py#L109)

pi-Flow の蒸留済み Kandinsky S2V 1.0 チェックポイント用の ModularPipeline。

Guidance は student に蒸留されるため、そのブロックには guider も negative prompt も存在せず、セグメントごとに 1 回の forward pass が実行されます。

## KandinskyS2VDistilledAutoBlocks[[diffusers.KandinskyS2VDistilledAutoBlocks]]

#### diffusers.KandinskyS2VDistilledAutoBlocks[[diffusers.KandinskyS2VDistilledAutoBlocks]]

```python
diffusers.KandinskyS2VDistilledAutoBlocks()
```

[ソース](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/kandinsky_s2v/modular_blocks_kandinsky_s2v_distilled.py#L103)

pi-Flow 蒸留 Kandinsky S2V 1.0 チェックポイントを用いた音声から動画生成へのモジュール化パイプライン: チャンクあたり16セグメント、ガイダンスなし。これは学生モデルに蒸留されます。

コンポーネント: text_encoder (`Qwen2_5OmniThinkerForConditionalGeneration`) tokenizer (`Qwen2_5OmniProcessor`) text_encoder_2 (`CLIPTextModel`) tokenizer_2 (`CLIPTokenizer`) vae (`AutoencoderKLHunyuanVideo`) video_processor (`VideoProcessor`) transformer (`KandinskyS2VTransformer3DModel`) scheduler (`PiflowScheduler`)

Inputs: prompt (`str`, *optional*, defaults to The video presents a stable medium close-up of a subject facing the camera directly. The subject exhibits natural, lifelike body dynamics: the head and shoulders move fluidly with the rhythm of speech. The lighting is even, maintaining a balanced natural exposure to clearly define facial features without washout. Throughout the sequence, the subject engages in continuous speech marked by precise, high-fidelity articulation. The lips move in a rhythmic, natural pattern: alternating between brief firm closures and relaxed openings. During these openings, the tips of the upper teeth are momentarily and realistically visible, exhibiting natural enamel texture. The upper lip lifts subtly over the teeth during enunciation, while the jaw performs minimal vertical oscillations synchronized with the speech cadence. Facial micro-expressions are active yet restrained; eyebrows rise and lower slightly with minute asymmetry. The eyes maintain a steady, engaged gaze forward, punctuated by smooth, deliberate blinks. ): The prompt to guide the generation. audio (`Tensor | ndarray`): The speech track that drives the generation: a mono float waveform in [-1, 1] at 16000 Hz, shaped (samples,). num_latent_frames (`int`, *optional*, defaults to 32): Latent frames per chunk; 32 gives 125 frames (5 s at 25 fps). fps (`int`, *optional*, defaults to 25): Frame rate the chunk length is computed at. num_chunks (`int`, *optional*): Number of chunks to generate. Defaults to however many cover the speech track; the video is trimmed to the track either way. image (`Image`): The reference frame to animate. height (`int`, *optional*): The height in pixels of the generated video. Defaults to the 512 bucket closest to the reference frame. width (`int`, *optional*): The width in pixels of the generated video, chosen together with `height`. generator (`Generator`, *optional*): Torch generator for deterministic generation. num_inference_steps (`int`, *optional*, defaults to 16): The number of denoising steps. scale_factor (`tuple`, *optional*, defaults to (1.0, 2.0, 2.0)): Per-axis RoPE scale for the resolution bucket. output_type (`str`, *optional*, defaults to pil): Output format: 'pil', 'np', 'pt'.

出力: 動画 (`list`): 生成された動画。