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

# 프리셋

> SDK에서 재사용 가능한 렌더 구성 관리

프리셋은 어떤 프로젝트나 내보내기에 적용할 수 있는 재사용 가능한 렌더 구성(배경, 자막 스타일, 레이아웃)입니다. 여러 트랙에서 일관된 룩을 유지하고 싶을 때 프리셋을 사용하세요.

전체 `preset` 형태와 모든 enum 기반 옵션은 [Render settings reference](/en/render-settings-reference)를 참고하세요.

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

인증된 계정이 소유한 모든 프리셋을 나열합니다.

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

단일 프리셋을 가져옵니다.

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

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

새 프리셋을 생성합니다.

```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>
  Youka UI에 표시되는 표시 이름입니다.
</ParamField>

<ParamField path="preset" type="KaraokePreset" required>
  전체 프리셋 본문입니다. 사람이 읽기 쉬운 필드 맵은 [`Render settings
      reference`](/en/render-settings-reference)를 사용하고, 기계 판독용 스키마는 `KaraokePresetSchema.toJSONSchema()`를 사용하세요.
</ParamField>

<ParamField path="isDefault" type="boolean">
  새 프리셋을 계정 기본값으로 지정합니다. 기본 프리셋은 한 번에 하나만 설정할 수 있습니다.
</ParamField>

안전한 재시도를 위해 멱등성 키와 함께 사용하세요:

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

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

기존 프리셋을 패치합니다. `name`, `preset`, `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?)`

프리셋을 삭제합니다.

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

<Warning>
  프리셋을 삭제해도 이전에 해당 프리셋으로 렌더링된 프로젝트나 내보내기가 삭제되지는 않습니다. 삭제된 프리셋을 참조하는 향후 내보내기는 실패합니다.
</Warning>

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

새 프로젝트의 기본값으로 프리셋을 지정합니다. 이는 `client.presets.update(presetId, { isDefault: true })`를 편의상 감싼 래퍼입니다.

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

새 기본값을 설정하면 이전 기본값은 자동으로 해제됩니다.

## 유효한 필드 찾기

SDK는 프리셋 본문을 검증하는 Zod 스키마를 내보냅니다. 에이전트와 폼 빌더를 위해 런타임에 JSON Schema로 변환하세요:

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

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

<Tip>
  에이전트 작성자: 프리셋을 변경하기 전에 이 스키마를 호출해 모델이 정확한 필드 이름과 값 타입을 알 수 있도록 하세요.
</Tip>

사람이 읽기 쉬운 참고 자료:

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

## 프리셋 적용하기

프리셋은 다음 세 지점에서 적용할 수 있습니다:

<Tabs>
  <Tab title="프로젝트 생성 시">
    ```ts theme={null}
    await client.projects.create({
      source: { type: "path", path: "./song.mp3" },
      presetId: "preset_abc123",
    });
    ```
  </Tab>

  <Tab title="프로젝트 설정에서">
    ```ts theme={null}
    await client.projects.updateSettings("prj_abc123", {
      presetId: "preset_abc123",
    });
    ```
  </Tab>

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

## 다음 단계

* [Render settings reference](/en/render-settings-reference) — 모든 공통 필드 경로와 enum 값
* [Media](/ko/sdk/media) — 프리셋 본문에서 참조됨
* [Project settings](/ko/sdk/project-settings) — 프로젝트에 프리셋 적용
* [API presets](/ko/api/presets) — raw HTTP에서의 동일한 흐름
* [CLI presets](/ko/cli/presets) — 터미널에서의 동일한 흐름
* [Exports](/ko/sdk/exports) — 프리셋으로 렌더링