> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Predefinições

> Gerencie configurações de renderização reutilizáveis a partir do SDK

Uma predefinição é uma configuração de renderização reutilizável — fundo, estilo de legenda, layout — que você pode aplicar a qualquer projeto ou exportação. Use predefinições quando você tiver um visual consistente em muitas faixas.

Veja [Render settings reference](/en/render-settings-reference) para o formato completo de
`preset` e todas as opções baseadas em enum.

## `client.presets.list(options?)`

Liste todas as predefinições pertencentes à conta autenticada.

```ts theme={null}
const presets = await client.presets.list();
presets.forEach((p) => console.log(p.id, p.name, p.isDefault));
```

## `client.presets.get(presetId, options?)`

Busque uma única predefinição.

```ts theme={null}
const preset = await client.presets.get("preset_abc123");
```

## `client.presets.create(body, options?)`

Crie uma nova predefinição.

```ts theme={null}
const preset = await client.presets.create({
  name: "Neon Night",
  preset: {
    background: {
      type: "gradient",
      colors: ["#12001f", "#2f0a57"],
      angle: 90,
    },
    singerTextStyles: {
      0: {
        fontFamily: "Inter",
        textColor: "#00f5ff",
        effectColor: "#ff4fd8",
      },
    },
  },
  isDefault: false,
});
```

<ParamField path="name" type="string" required>
  Nome de exibição mostrado na UI do Youka.
</ParamField>

<ParamField path="preset" type="KaraokePreset" required>
  O corpo completo da predefinição. Use [`Render settings
      reference`](/en/render-settings-reference) para o mapa de campos legível para humanos,
  ou `KaraokePresetSchema.toJSONSchema()` para o schema legível por máquina.
</ParamField>

<ParamField path="isDefault" type="boolean">
  Marque a nova predefinição como padrão da conta. Apenas uma predefinição pode ser a padrão
  por vez.
</ParamField>

Combine com uma chave de idempotência para novas tentativas seguras:

```ts theme={null}
const preset = await client.presets.create(body, {
  idempotencyKey: "create-neon-night-v1",
});
```

## `client.presets.update(presetId, body, options?)`

Aplique um patch em uma predefinição existente. Passe qualquer subconjunto de `name`, `preset` e `isDefault`.

```ts theme={null}
const updated = await client.presets.update("preset_abc123", {
  name: "Neon Night v2",
  preset: {
    singerTextStyles: {
      0: { textColor: "#ff2a2a" },
    },
  },
});
```

## `client.presets.delete(presetId, options?)`

Exclua uma predefinição.

```ts theme={null}
await client.presets.delete("preset_abc123", {
  idempotencyKey: "delete-preset_abc123",
});
```

<Warning>
  Excluir uma predefinição não exclui projetos nem exportações que foram anteriormente
  renderizados com ela. Exportações futuras que referenciem a predefinição excluída falharão.
</Warning>

## `client.presets.setDefault(presetId, options?)`

Marque uma predefinição como padrão para novos projetos. Este é um wrapper de conveniência em torno de `client.presets.update(presetId, { isDefault: true })`.

```ts theme={null}
await client.presets.setDefault("preset_abc123");
```

Definir um novo padrão remove automaticamente o padrão anterior.

## Descobrindo campos válidos

O SDK exporta o schema Zod que valida corpos de predefinição. Converta-o para JSON Schema em runtime para agentes e construtores de formulários:

```ts theme={null}
import { KaraokePresetSchema } from "@youka/sdk";

const jsonSchema = KaraokePresetSchema.toJSONSchema();
console.log(jsonSchema);
```

<Tip>
  Autores de agentes: chame este schema antes de modificar predefinições para que o modelo saiba os
  nomes exatos dos campos e os tipos de valores.
</Tip>

Referência legível para humanos:

* [Render settings reference](/en/render-settings-reference)
* [CLI presets](/pt/cli/presets)
* [API presets](/pt/api/presets)

## Aplicando uma predefinição

Aplique predefinições em três pontos:

<Tabs>
  <Tab title="Ao criar um projeto">
    ```ts theme={null}
    await client.projects.create({
      source: { type: "path", path: "./song.mp3" },
      presetId: "preset_abc123",
    });
    ```
  </Tab>

  <Tab title="Nas configurações do projeto">
    ```ts theme={null}
    await client.projects.updateSettings("prj_abc123", {
      presetId: "preset_abc123",
    });
    ```
  </Tab>

  <Tab title="Na exportação">
    ```ts theme={null}
    await client.exports.create("prj_abc123", {
      presetId: "preset_abc123",
      resolution: "1080p",
    });
    ```
  </Tab>
</Tabs>

## Próximos passos

* [Render settings reference](/en/render-settings-reference) — todos os caminhos de campos compartilhados e valores de enum
* [Media](/pt/sdk/media) — referenciado em corpos de predefinição
* [Project settings](/pt/sdk/project-settings) — aplique predefinições a um projeto
* [API presets](/pt/api/presets) — o mesmo fluxo via HTTP puro
* [CLI presets](/pt/cli/presets) — o mesmo fluxo pelo terminal
* [Exports](/pt/sdk/exports) — renderize com uma predefinição