# Kandinsky S2V 1.0

Kandinsky S2V 1.0 gera um vídeo de avatar a partir de um quadro de referência e uma trilha de fala. A pessoa no quadro é animada para corresponder à fala — a figura inteira, não apenas a cabeça. A fala é uma condição, não uma saída: o modelo não gera áudio, e a trilha sonora do resultado é a trilha que você fornece.

As duas condições passam pelo [Qwen2.5-Omni-7B](https://huggingface.co/Qwen/Qwen2.5-Omni-7B): seus estados ocultos codificam o prompt e sua torre de áudio codifica a fala, que entra no transformer por meio de adaptadores de atenção cruzada alinhados quadro a quadro, de modo que cada quadro latente atenda apenas à fala que ele cobre. Um clipe é gerado em blocos de 5 s (125 quadros a 25 fps), cada um carregando a memória FramePack dos anteriores, para que faixas mais longas permaneçam consistentes entre as fronteiras dos blocos.

Kandinsky S2V 1.0 é integrado apenas como um [pipeline modular](../../modular_diffusers/overview); não há uma classe padrão `DiffusionPipeline` para ele.

## Checkpoints

| Checkpoint | Transformer | Blocos | Agendador | Etapas | Orientações |
|---|---|---|---|---|---|
| [Lite][lite] | 2B | [KandinskyS2VAutoBlocks](/docs/diffusers/v0.43.0/pt/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VAutoBlocks) | [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) | 50 | 3.0 |
| [Pro][pro] | 21B | [KandinskyS2VAutoBlocks](/docs/diffusers/v0.43.0/pt/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VAutoBlocks) | [FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler) | 50 | 3.0 |
| [Lite destilado][lite-distill] | 2B | [KandinskyS2VDistilledAutoBlocks](/docs/diffusers/v0.43.0/pt/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VDistilledAutoBlocks) | [PiflowScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/piflow#diffusers.PiflowScheduler) | 16 | off |
| [Pro destilado][pro-distill] | 21B | [KandinskyS2VDistilledAutoBlocks](/docs/diffusers/v0.43.0/pt/api/pipelines/kandinsky_s2v#diffusers.KandinskyS2VDistilledAutoBlocks) | [PiflowScheduler](/docs/diffusers/v0.43.0/pt/api/schedulers/piflow#diffusers.PiflowScheduler) | 16 | off |

Os checkpoints destilados configuram o `PiflowScheduler` com `shift=10.0` e `n_grid=5`, e não com os valores padrão.

[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` seleciona os blocos do checkpoint. Os passos padrão são os valores acima. A classifier-free guidance é o componente `guider`, não um argumento de chamada: os checkpoints base a incluem em 3.0. Os destilados não possuem guider nem `negative_prompt`, pois a guidance já faz parte do student.

## Uso

```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,
)
```

Os checkpoints Pro não cabem em uma GPU de 80 GB ao lado do codificador de fala e texto de 7B quando todos os componentes estão no dispositivo. Faça o offload deles por meio de um `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,
)
```

A margem é a memória mantida livre além dos pesos quando um modelo é movido para a GPU. Ela precisa acomodar o decodificação do VAE de um bloco, cerca de 33 GiB em 512x768: com o padrão de 3 GB, o transformer permanece na GPU durante a decodificação, o que resulta em falta de memória. Com 40 GiB, o pico é de aproximadamente 50 GiB em uma GPU de 80 GB. Ative o offload após `load_components`, para que ele se aplique a todos os componentes.

## Observações

- `image` é uma imagem PIL e `audio` é uma forma de onda mono em ponto flutuante em [-1, 1] a 16 kHz, como um tensor ou um array com a forma `(samples,)`; o pipeline não lê arquivos.
- Os blocos de nível superior (`text_encoder`, `vae_encoder`, `denoise`, `decode`) também são executados de forma independente; passe o mesmo `num_latent_frames` e `fps` para cada um quando executá-los separadamente.
- O número de chunks segue o comprimento da faixa de áudio, a menos que `num_chunks` seja passado. O vídeo é aparado para a faixa em qualquer caso, portanto, chunks além do seu final são calculados e descartados, com um aviso.
- Com o guidance, a passagem incondicional substitui o prompt negativo *e* silencia a fala, de modo que o guidance é conjunto sobre texto e fala.

## 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)
```

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

Uma ModularPipeline para geração de vídeo a partir de fala do Kandinsky S2V 1.0.

## KandinskyS2VAutoBlocks[[diffusers.KandinskyS2VAutoBlocks]]

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

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

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

Pipeline modular para geração de fala em vídeo com Kandinsky S2V 1.0: um vídeo de avatar a partir de um quadro de referência e uma trilha de fala, gerado em blocos.

Componentes: 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`, *opcional*, padrão é 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. ): O prompt para orientar a geração. negative_prompt (`str`, *opcional*): O prompt para a passagem incondicional da orientação. Padrão é `DEFAULT_NEGATIVE_PROMPT` quando a orientação precisa de um. audio (`Tensor | ndarray`): A trilha de fala que dirige a geração: uma forma de onda mono float em [-1, 1] a 16000 Hz, com formato (samples,). num_latent_frames (`int`, *opcional*, padrão é 32): Quadros latentes por bloco; 32 resulta em 125 quadros (5 s a 25 fps). fps (`int`, *opcional*, padrão é 25): A taxa de quadros na qual o comprimento do bloco é calculado. num_chunks (`int`, *opcional*): Número de blocos a serem gerados. Padrão é o número necessário para cobrir a trilha de fala; o vídeo é aparado para a trilha de qualquer forma. image (`Image`): O quadro de referência a ser animado. height (`int`, *opcional*): A altura em pixels do vídeo gerado. Padrão é o bucket 512 mais próximo do quadro de referência. width (`int`, *opcional*): A largura em pixels do vídeo gerado, escolhida junto com `height`. generator (`Generator`, *opcional*): Gerador Torch para geração determinística. num_inference_steps (`int`, *opcional*, padrão é 50): O número de etapas de remoção de ruído. scale_factor (`tuple`, *opcional*, padrão é (1.0, 2.0, 2.0)): Escala RoPE por eixo para o bucket de resolução. output_type (`str`, *opcional*, padrão é pil): Formato de saída: 'pil', 'np', 'pt'.

Saídas: vídeos (`list`): Os vídeos gerados.

## 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)
```

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

Uma ModularPipeline para os checkpoints destilados do pi-Flow do Kandinsky S2V 1.0.

O guidance é destilado no student, portanto seus blocos não possuem guider nem prompt negativo, e uma única forward pass é executada por segmento.

## KandinskyS2VDistilledAutoBlocks[[diffusers.KandinskyS2VDistilledAutoBlocks]]

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

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

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

Pipeline modular para geração de fala em vídeo com os checkpoints destilados do pi-Flow Kandinsky S2V 1.0: 16 segmentos por chunk e sem guidance, o que é destilado no student.

Componentes: 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`, *opcional*, padrão é 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. ): O prompt para orientar a geração. audio (`Tensor | ndarray`): A trilha de fala que impulsiona a geração: uma forma de onda mono float em [-1, 1] a 16000 Hz, com formato (samples,). num_latent_frames (`int`, *opcional*, padrão é 32): Quadros latentes por bloco; 32 resulta em 125 quadros (5 s a 25 fps). fps (`int`, *opcional*, padrão é 25): A taxa de quadros na qual o comprimento do bloco é calculado. num_chunks (`int`, *opcional*): Número de blocos a serem gerados. O padrão é o número necessário para cobrir a trilha de fala; o vídeo é aparado para a trilha de qualquer forma. image (`Image`): O quadro de referência a ser animado. height (`int`, *opcional*): A altura em pixels do vídeo gerado. O padrão é o bucket 512 mais próximo do quadro de referência. width (`int`, *opcional*): A largura em pixels do vídeo gerado, escolhida junto com `height`. generator (`Generator`, *opcional*): Gerador Torch para geração determinística. num_inference_steps (`int`, *opcional*, padrão é 16): O número de etapas de remoção de ruído. scale_factor (`tuple`, *opcional*, padrão é (1.0, 2.0, 2.0)): Escala RoPE por eixo para o bucket de resolução. output_type (`str`, *opcional*, padrão é pil): Formato de saída: 'pil', 'np', 'pt'.

Saídas: vídeos (`list`): Os vídeos gerados.