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

对当前生效的项目设置进行补丁更新。你可以应用一个预设、传入原始 settings，或两者同时使用（会先应用预设，然后将 settings 覆盖合并到其上）。

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

### 字段

<ParamField path="presetId" type="string">
  应用一个可复用的预设。不传则保持当前预设不变。
</ParamField>

<ParamField path="settings" type="object">
  在预设之上应用的补丁。使用 `style` 来进行与预设形状一致的覆盖，
  以及使用项目本地字段，例如 `displayLanguages`、`chordSettings` 和
  `duetSingerFilter`。
</ParamField>

### 发现可用字段

在运行时将更新 schema 转换为 JSON Schema，以发现每一个可用字段：

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

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

<Tip>
  Agent 在修改项目设置之前应该先调用这个方法，这样就能始终了解
  当前的字段结构。
</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) — 所有共享字段路径与枚举值
* [Presets](/zh/sdk/presets) — 可复用配置
* [Media](/zh/sdk/media) — 上传背景与 logo
* [API project settings](/zh/api/project-settings) — 通过原始 HTTP 实现相同流程
* [CLI projects](/zh/cli/projects) — 在终端中实现相同流程
* [Exports](/zh/sdk/exports) — 使用 `settingsOverride` 进行仅导出时的微调