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

# Project settings

> Read and update a project's active settings

Every project has active settings — trim, background, subtitle style, layout — that control how exports are rendered.

Use project settings when you want project-local overrides that aren't worth bundling into a shared preset.

See [Render settings reference](/en/render-settings-reference) for the shared
`preset`, `settings.style`, and `settingsOverride` field map.

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

Fetch a project's active settings.

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

Patch the active project settings. You can apply a preset, pass raw settings, or both (the preset is applied first, then settings overrides are merged on top).

```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">
  Apply a reusable preset. Omit it to leave the current preset unchanged.
</ParamField>

<ParamField path="settings" type="object">
  Patch applied on top of the preset. Use `style` for preset-shaped overrides,
  plus project-local fields such as `displayLanguages`, `chordSettings`, and
  `duetSingerFilter`.
</ParamField>

### Discovering valid fields

Convert the update schema to JSON Schema at runtime to discover every valid field:

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

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

<Tip>
  Agents should call this before mutating project settings so they always know
  the current shape.
</Tip>

## Common patterns

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

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

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

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

## Project settings vs presets

| Question                                         | Use                       |
| ------------------------------------------------ | ------------------------- |
| Same look across many projects?                  | Presets                   |
| One-off trim or color tweak on a single project? | Project settings          |
| Base look + small project-specific overrides?    | Preset + project settings |

## What's next

* [Render settings reference](/en/render-settings-reference) — all shared field paths and enum values
* [Presets](/en/sdk/presets) — reusable configurations
* [Media](/en/sdk/media) — upload backgrounds and logos
* [API project settings](/en/api/project-settings) — the same flow over raw HTTP
* [CLI projects](/en/cli/projects) — the same flow from the terminal
* [Exports](/en/sdk/exports) — use `settingsOverride` for export-only tweaks