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

# Preset

> Quản lý các cấu hình render có thể tái sử dụng từ SDK

Preset là một cấu hình render có thể tái sử dụng — nền, kiểu phụ đề, bố cục — mà bạn có thể áp dụng cho bất kỳ project hoặc export nào. Hãy dùng preset khi bạn muốn có giao diện nhất quán trên nhiều track.

Xem [Render settings reference](/en/render-settings-reference) để biết đầy đủ
hình dạng `preset` và mọi tùy chọn được hỗ trợ bởi enum.

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

Liệt kê mọi preset thuộc về tài khoản đã xác thực.

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

Lấy một preset duy nhất.

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

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

Tạo một preset mới.

```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>
  Tên hiển thị trong UI của Youka.
</ParamField>

<ParamField path="preset" type="KaraokePreset" required>
  Toàn bộ nội dung preset. Dùng [`Render settings
      reference`](/en/render-settings-reference) để xem bản đồ trường dễ đọc cho con người,
  hoặc `KaraokePresetSchema.toJSONSchema()` để lấy schema dễ đọc cho máy.
</ParamField>

<ParamField path="isDefault" type="boolean">
  Đặt preset mới làm mặc định cho tài khoản. Mỗi lần chỉ có thể có một preset
  là mặc định.
</ParamField>

Kết hợp với idempotency key để retry an toàn:

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

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

Patch một preset hiện có. Truyền bất kỳ tập con nào của `name`, `preset`, và `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?)`

Xóa một preset.

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

<Warning>
  Việc xóa một preset không xóa các project hoặc export đã từng được render bằng preset đó. Các export trong tương lai tham chiếu đến preset đã bị xóa sẽ thất bại.
</Warning>

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

Đặt một preset làm mặc định cho các project mới. Đây là một wrapper tiện lợi quanh `client.presets.update(presetId, { isDefault: true })`.

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

Khi đặt mặc định mới, mặc định trước đó sẽ tự động bị bỏ đặt.

## Khám phá các trường hợp lệ

SDK export Zod schema dùng để validate nội dung preset. Hãy chuyển nó sang JSON Schema khi chạy để phục vụ agents và trình dựng form:

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

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

<Tip>
  Tác giả agent: hãy gọi schema này trước khi mutate preset để model biết chính xác tên trường và kiểu giá trị.
</Tip>

Tài liệu tham chiếu dễ đọc cho con người:

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

## Áp dụng một preset

Bạn có thể áp dụng preset tại ba thời điểm:

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

  <Tab title="Trong cài đặt project">
    ```ts theme={null}
    await client.projects.updateSettings("prj_abc123", {
      presetId: "preset_abc123",
    });
    ```
  </Tab>

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

## Tiếp theo

* [Render settings reference](/en/render-settings-reference) — tất cả các đường dẫn trường dùng chung và giá trị enum
* [Media](/vi/sdk/media) — được tham chiếu từ nội dung preset
* [Project settings](/vi/sdk/project-settings) — áp dụng preset cho một project
* [API presets](/vi/api/presets) — cùng luồng đó qua HTTP thô
* [CLI presets](/vi/cli/presets) — cùng luồng đó từ terminal
* [Exports](/vi/sdk/exports) — render với một preset