> ## 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.

# Presets

> Manage reusable render configurations from the SDK

A preset is a reusable render configuration — background, subtitle style, layout — that you can apply to any project or export. Use presets when you have a consistent look across many tracks.

See [Render settings reference](/en/render-settings-reference) for the full
`preset` shape and every enum-backed option.

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

List every preset owned by the authenticated account.

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

Fetch a single preset.

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

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

Create a new preset.

```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>
  Display name shown in the Youka UI.
</ParamField>

<ParamField path="preset" type="KaraokePreset" required>
  The full preset body. Use [`Render settings
      reference`](/en/render-settings-reference) for the human-readable field map,
  or `KaraokePresetSchema.toJSONSchema()` for the machine-readable schema.
</ParamField>

<ParamField path="isDefault" type="boolean">
  Mark the new preset as the account default. Only one preset can be the default
  at a time.
</ParamField>

Pair with an idempotency key for safe retries:

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

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

Patch an existing preset. Pass any subset of `name`, `preset`, and `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?)`

Delete a preset.

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

<Warning>
  Deleting a preset does not delete projects or exports that were previously
  rendered with it. Future exports that reference the deleted preset will fail.
</Warning>

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

Mark a preset as the default for new projects. This is a convenience wrapper around `client.presets.update(presetId, { isDefault: true })`.

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

Setting a new default automatically unsets the previous one.

## Discovering valid fields

The SDK exports the Zod schema that validates preset bodies. Convert it to JSON Schema at runtime for agents and form builders:

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

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

<Tip>
  Agent authors: call this schema before mutating presets so the model knows the
  exact field names and value types.
</Tip>

Human-readable reference:

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

## Applying a preset

Apply presets at three points:

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

  <Tab title="On project settings">
    ```ts theme={null}
    await client.projects.updateSettings("prj_abc123", {
      presetId: "preset_abc123",
    });
    ```
  </Tab>

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

## What's next

* [Render settings reference](/en/render-settings-reference) — all shared field paths and enum values
* [Media](/en/sdk/media) — referenced from preset bodies
* [Project settings](/en/sdk/project-settings) — apply presets to a project
* [API presets](/en/api/presets) — the same flow over raw HTTP
* [CLI presets](/en/cli/presets) — the same flow from the terminal
* [Exports](/en/sdk/exports) — render with a preset