> ## 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`, `settings.style`, `settingsOverride` 필드 맵은 [Render settings reference](/en/render-settings-reference)를 참고하세요.

## `client.projects.getSettings(projectId, options?)`

프로젝트의 활성 설정을 가져옵니다.

```ts theme={null}
const config = await client.projects.getSettings("prj_abc123");
console.log(
  config.settings.trim,
  config.settings.style?.background,
  config.settings.displayLanguages,
);
```

## `client.projects.updateSettings(projectId, body, options?)`

활성 프로젝트 설정을 패치합니다. 프리셋을 적용하거나, 원시 설정을 전달하거나, 둘 다 할 수 있습니다(프리셋이 먼저 적용된 다음 그 위에 설정 오버라이드가 병합됩니다).

```ts theme={null}
const updated = await client.projects.updateSettings("prj_abc123", {
  presetId: "preset_abc123",
  settings: {
    trim: { startSeconds: 5, endSeconds: 180 },
  },
});
```

### Fields

<ParamField path="presetId" type="string">
  재사용 가능한 프리셋을 적용합니다. 현재 프리셋을 변경하지 않으려면 생략하세요.
</ParamField>

<ParamField path="settings" type="object">
  프리셋 위에 적용되는 패치입니다. 프리셋 형태의 오버라이드를 위해 `style`을 사용하고,
  `displayLanguages`, `chordSettings`, `duetSingerFilter` 같은 프로젝트 로컬 필드도 함께 사용하세요.
</ParamField>

### 유효한 필드 찾기

업데이트 스키마를 런타임에 JSON Schema로 변환하여 모든 유효 필드를 확인하세요:

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

const schema = RestUpdateProjectSettingsRequestSchema.toJSONSchema();
console.log(JSON.stringify(schema, null, 2));
```

<Tip>
  에이전트는 프로젝트 설정을 변경하기 전에 이를 호출해 항상 현재 스키마 형태를 알 수 있어야 합니다.
</Tip>

## 일반적인 패턴

<Tabs>
  <Tab title="트림">
    ```ts theme={null}
    await client.projects.updateSettings("prj_abc123", {
      settings: {
        trim: { startSeconds: 5.0, endSeconds: 180.0 },
      },
    });
    ```
  </Tab>

  <Tab title="배경색">
    ```ts theme={null}
    await client.projects.updateSettings("prj_abc123", {
      settings: {
        style: {
          background: { type: "color", color: "#101010" },
        },
      },
    });
    ```
  </Tab>

  <Tab title="표시 언어">
    ```ts theme={null}
    await client.projects.updateSettings("prj_abc123", {
      settings: {
        displayLanguages: ["en", "es"],
      },
    });
    ```
  </Tab>

  <Tab title="프리셋 적용">
    ```ts theme={null}
    await client.projects.updateSettings("prj_abc123", {
      presetId: "preset_abc123",
    });
    ```
  </Tab>
</Tabs>

## 프로젝트 설정 vs 프리셋

| 질문                         | 사용            |
| -------------------------- | ------------- |
| 많은 프로젝트에서 동일한 룩이 필요한가요?    | 프리셋           |
| 단일 프로젝트에서 일회성 트림/색상 조정인가요? | 프로젝트 설정       |
| 기본 룩 + 소규모 프로젝트별 오버라이드인가요? | 프리셋 + 프로젝트 설정 |

## 다음 단계

* [Render settings reference](/en/render-settings-reference) — 모든 공유 필드 경로와 enum 값
* [Presets](/ko/sdk/presets) — 재사용 가능한 구성
* [Media](/ko/sdk/media) — 배경과 로고 업로드
* [API project settings](/ko/api/project-settings) — 원시 HTTP로 동일한 흐름
* [CLI projects](/ko/cli/projects) — 터미널에서 동일한 흐름
* [Exports](/ko/sdk/exports) — 내보내기 전용 미세 조정에는 `settingsOverride` 사용