# Kandinsky S2V 1.0

Kandinsky S2V 1.0은 참조 프레임과 음성 트랙을 입력받아 아바타 영상을 생성합니다. 프레임 속 인물은 음성に合わせて 애니메이션 처리되며, 머리뿐만 아니라 전체 인물이 움직입니다. 음성은 출력물이 아닌 조건으로 작용합니다. 즉, 모델은 오디오를 생성하지 않으며, 결과물의 사운드트랙은 사용자가 전달한 트랙 그대로입니다.

두 조건 모두 [Qwen2.5-Omni-7B](https://huggingface.co/Qwen/Qwen2.5-Omni-7B)를 통해 처리됩니다. 이 모델의 hidden states는 프롬프트를 인코딩하고, 오디오 타워는 음성(스피치)을 인코딩합니다. 이 음성 인코딩 결과는 프레임별로 정렬된 크로스 어텐션 어댑터를 통해 트랜스포머에 입력되며, 각 잠재(latent) 프레임은 자신이 커버하는 음성에만 어텐션을 수행합니다. 클립은 5초(25 fps 기준 125프레임) 단위의 청크로 생성되며, 각 청크는 이전 청크들의 FramePack 메모리를 포함하므로 더 긴 트랙도 청크 경계에서 일관성을 유지합니다.

Kandinsky S2V 1.0은 [모듈형 파이프라인](../../modular_diffusers/overview)으로만 통합되어 있으며, 이를 위한 표준 `DiffusionPipeline` 클래스는 없습니다.

## 체크포인트

| 체크포인트 | Transformer | 블록 | 스케줄러 | 단계 | 가이드 |
|---|---|---|---|---|---|
| [Lite][lite] | 2B | [KandinskyS2VAutoBlocks](/docs/diffusers/main/ko/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VAutoBlocks) | [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) | 50 | 3.0 |
| [Pro][pro] | 21B | [KandinskyS2VAutoBlocks](/docs/diffusers/main/ko/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VAutoBlocks) | [FlowMatchEulerDiscreteScheduler](/docs/diffusers/main/ko/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) | 50 | 3.0 |
| [Lite 디스틸드][lite-distill] | 2B | [KandinskyS2VDistilledAutoBlocks](/docs/diffusers/main/ko/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VDistilledAutoBlocks) | [PiflowScheduler](/docs/diffusers/main/ko/api/schedulers/piflow#diffusers.PiflowScheduler) | 16 | off |
| [Pro 디스틸드][pro-distill] | 21B | [KandinskyS2VDistilledAutoBlocks](/docs/diffusers/main/ko/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VDistilledAutoBlocks) | [PiflowScheduler](/docs/diffusers/main/ko/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,
)
```

margin은 모델이 GPU로 이동할 때 가중치 외에 비워 두는 메모리입니다. 이 영역에는 청크의 VAE 디코딩 결과가 저장되어야 하며, 512x768 해상도에서는 약 33 GiB가 필요합니다. 기본값인 3 GB를 사용하면 디코딩이 진행되는 동안에도 transformer가 GPU에 머물러 있어 메모리가 부족해집니다. 40 GiB로 설정하면 80 GB GPU에서 피크 메모리는 약 50 GiB가 됩니다. 모든 구성 요소에 적용되도록 `load_components` 호출 후에 offload를 활성화하세요.

## The input is a single word "Notes".

참고

- `image`는 PIL 이미지이고, `audio`는 16 kHz의 [-1, 1] 범위를 가지는 모노 float 웨이브폼으로, `(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/main/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/main/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'.

Outputs: videos (`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/main/src/diffusers/modular_pipelines/kandinsky_s2v/modular_pipeline.py#L109)

pi-Flow에서 증류된 Kandinsky S2V 1.0 체크포인트를 위한 ModularPipeline.

Guidance는 student로 증류되므로, 해당 블록에는 guider와 negative prompt가 없으며 세그먼트당 단일 forward pass만 실행됩니다.

## KandinskyS2VDistilledAutoBlocks[[diffusers.KandinskyS2VDistilledAutoBlocks]]

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

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

[소스](https://github.com/huggingface/diffusers/blob/main/src/diffusers/modular_pipelines/kandinsky_s2v/modular_blocks_kandinsky_s2v_distilled.py#L103)

pi-Flow distilled Kandinsky S2V 1.0 체크포인트를 활용한 음성-비디오 생성을 위한 모듈형 파이프라인: 16개 세그먼트를 1개 청크당 사용하고, 학생 모델로 증류되는 무가이던스 설정

구성 요소: 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'.

Outputs: videos (`list`): 생성된 비디오.