> ## 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.
# Render settings reference
> Reference for preset bodies, project settings patches, export overrides, and enum-backed render options
Use this page when you need the exact shape of a preset, a project settings
patch, or an export `settingsOverride`.
## Where this shape is used
| Surface | Presets | Project settings | Export overrides | Machine-readable schema |
| ------- | ------------------------------ | ------------------------------------------------ | --------------------------------- | ------------------------------------------------------------------------------------------------ |
| CLI | [CLI presets](/en/cli/presets) | [CLI projects](/en/cli/projects) | [CLI exports](/en/cli/exports) | `youka preset schema --json` for preset bodies |
| SDK | [SDK presets](/en/sdk/presets) | [SDK project settings](/en/sdk/project-settings) | [SDK exports](/en/sdk/exports) | `KaraokePresetSchema.toJSONSchema()` and `RestUpdateProjectSettingsRequestSchema.toJSONSchema()` |
| API | [API presets](/en/api/presets) | [API project settings](/en/api/project-settings) | [API exports](/en/api/quickstart) | Same request bodies as this page |
## Core rule
* `preset` is the reusable account-wide render configuration.
* `settings.style` uses the exact same object shape as `preset`, but applies only
to one project.
* `settingsOverride` on an export uses the same object shape as `settings`.
* Backgrounds, logos, intros, and outros are referenced by `url`, not by a
media ID.
## Object shapes
### `preset`
```jsonc theme={null}
{
"aspectRatio": "16:9",
"layout": {},
"background": { "type": "auto" },
"singerTextStyles": {
"0": {},
},
"languageTextStyles": {
"en": {},
},
"chordTextStyle": {},
"overlays": {},
"trim": {
"startSeconds": 0,
"endSeconds": 0,
},
}
```
### `project settings` / export `settingsOverride`
```jsonc theme={null}
{
"presetId": "preset_abc123",
"settings": {
"style": {},
"trim": {
"startSeconds": 5,
"endSeconds": 180,
},
"displayLanguages": ["en", "es"],
"chordSettings": {
"displayMode": "inline",
"notation": "chord_simple_pop",
"transpose": 0,
"capo": 0,
"showLayer": true,
},
"duetSingerFilter": {
"enabled": true,
"selectedSingerIds": [0],
"includeSharedLines": true,
},
},
}
```
`settings.style` is just a project-local `preset`. If you already know the
`preset` shape, you also know the `settings.style` shape.
## Top-level fields
### `preset` and `settings.style`
| Path | Type | Notes |
| -------------------- | --------------------------- | ------------------------------------------------------------ |
| `aspectRatio` | `string` | One of the aspect ratios listed below. |
| `layout` | `object` | Layout mode, line count, alignment, and transition behavior. |
| `background` | `object` | Discriminated union keyed by `type`. |
| `singerTextStyles` | `Record` | Keys are singer indexes such as `"0"` or `"1"`. |
| `languageTextStyles` | `Record` | Keys are language codes such as `"en"` or `"es"`. |
| `chordTextStyle` | `TextStyle` | Optional style used for chord overlays. |
| `overlays` | `object` | Title card, lead-in, breaks, and branding. |
| `trim` | `object` | Optional trim window with `startSeconds` and `endSeconds`. |
### `settings` and export `settingsOverride`
| Path | Type | Notes |
| --------------------------- | --------------- | ------------------------------------------------------------------ |
| `presetId` | `string` | Optional preset to apply first. |
| `settings.style` | `KaraokePreset` | Project-local render style override. |
| `settings.trim` | `object` | Project-local trim override. |
| `settings.displayLanguages` | `string[]` | Languages to show and the order to show them in multilingual mode. |
| `settings.chordSettings` | `object` | Chord display mode, notation, transpose, capo, and visibility. |
| `settings.duetSingerFilter` | `object` | Practice-mode duet filter for singer-specific lines. |
## Common text-style fields
These fields apply to `singerTextStyles.*`, `languageTextStyles.*`, and
`chordTextStyle`.
| Field | Type | Notes |
| ----------------- | -------- | --------------------------------- |
| `fontFamily` | `string` | Font family name. |
| `fontSize` | `number` | Font size. |
| `fontWeight` | `number` | Numeric font weight. |
| `textColor` | `string` | Fill color. |
| `outlineColor` | `string` | Stroke color. |
| `outlineWidth` | `number` | Stroke width. |
| `textEffect` | `string` | See allowed values below. |
| `activeLineColor` | `string` | Active lyric line color. |
| `effectColor` | `string` | Karaoke highlight/effect color. |
| `backgroundColor` | `string` | Background fill behind text. |
| `letterSpacing` | `number` | Letter spacing adjustment. |
| `lineSpacing` | `number` | Line-height multiplier. |
| `textCase` | `string` | See allowed values below. |
| `textDirection` | `string` | See allowed values below. |
| `shadowColor` | `string` | Shadow color. |
| `shadowBlur` | `number` | Shadow blur. |
| `shadowOffsetX` | `number` | Shadow X offset. |
| `shadowOffsetY` | `number` | Shadow Y offset. |
| `shadowOpacity` | `number` | Optional shadow opacity override. |
| `duetPosition` | `string` | See allowed values below. |
## Background shape
`background` is selected by `background.type`.
| `background.type` | Required fields | Optional fields |
| ----------------- | --------------- | -------------------------- |
| `auto` | none | none |
| `color` | `color` | none |
| `gradient` | `colors` | `angle` |
| `image` | `url` | `objectFit`, `blur`, `dim` |
| `video` | `url` | `objectFit`, `dim` |
## Overlay objects
| Path | Fields |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `overlays.titleCard` | `enabled`, `duration`, `titleStyle`, `artistStyle` |
| `overlays.leadIn` | `enabled`, `beats`, `minGap`, `useNextSingerStyle`, `style`, `width`, `height`, `offsetX`, `offsetY` |
| `overlays.instrumentalBreak` | `hideLyrics`, `minGap`, `displayDuration` |
| `overlays.breakCountdown` | `enabled`, `maxDuration`, `animation`, `useNextSingerStyle`, `style`, `textSize`, `hideBeforeEnd` |
| `overlays.breakProgressBar` | `enabled`, `maxDuration`, `useNextSingerStyle`, `style`, `width`, `height`, `position`, `cornerRadius`, `hideBeforeEnd` |
| `overlays.branding.logo` | `enabled`, `url`, `position`, `paddingX`, `paddingY`, `scale`, `opacity` |
| `overlays.branding.intro` | `enabled`, `url`, `durationSeconds`, `effect`, `effectDuration` |
| `overlays.branding.outro` | `enabled`, `url`, `durationSeconds`, `effect`, `effectDuration` |
## Allowed values and ranges
| Path | Allowed values |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aspectRatio` | `16:9`, `9:16`, `4:3`, `1:1` |
| `layout.type` | `single`, `duet`, `karaoke`, `scrolling`, `multilingual`, `chords` |
| `layout.linesPerScreen` | `2`, `3`, `4`, `5`, `6`, `7`, `8` |
| `layout.alignment` | `top`, `center`, `bottom` |
| `layout.lineTransition` | `none`, `fade`, `slide`, `dim` |
| `layout.duetSettings.overlapBehavior` | `both`, `all-style` |
| `layout.languageSpacing` | Number from `0` to `10` |
| `layout.containerHeight` | Number from `20` to `100` |
| `layout.anticipationBuffer` | Number from `0` to `10` |
| `background.type` | `auto`, `color`, `gradient`, `image`, `video` |
| `background.objectFit` | `contain`, `cover`, `fill` |
| `*.textEffect` | `none`, `karaoke`, `highlight` |
| `*.textCase` | `none`, `uppercase`, `lowercase`, `capitalize` |
| `*.textDirection` | `auto`, `ltr`, `rtl` |
| `*.duetPosition` | `top`, `center`, `bottom` |
| `overlays.breakCountdown.animation` | `spring`, `fade` |
| `overlays.breakProgressBar.position` | `top`, `center`, `bottom` |
| `overlays.breakProgressBar.cornerRadius` | Number from `0` to `50` |
| `overlays.branding.logo.position` | `top-left`, `top-right`, `bottom-left`, `bottom-right` |
| `overlays.branding.intro.effect` and `overlays.branding.outro.effect` | `fade`, `crossfade`, `slide-left`, `slide-right`, `slide-up`, `slide-down`, `zoom-in`, `zoom-out`, `blur` |
| `settings.chordSettings.displayMode` | `inline`, `grid` |
| `settings.chordSettings.notation` | `chord_complex_pop`, `chord_simple_pop`, `chord_basic_pop`, `chord_complex_jazz`, `chord_simple_jazz`, `chord_basic_jazz`, `chord_complex_nashville`, `chord_simple_nashville`, `chord_basic_nashville`, `chord_majmin` |
| `settings.chordSettings.transpose` | Integer from `-12` to `12` |
| `settings.chordSettings.capo` | Integer from `0` to `12` |
| `settings.duetSingerFilter.selectedSingerIds[]` | Non-negative integers |
## Schema commands
Use the human-readable tables above for docs, and the machine-readable schema
below when you need every field with exact defaults:
```bash cli theme={null}
youka preset schema --json
```
```ts sdk theme={null}
import {
KaraokePresetSchema,
RestUpdateProjectSettingsRequestSchema,
} from "@youka/sdk";
const presetSchema = KaraokePresetSchema.toJSONSchema();
const projectSettingsSchema =
RestUpdateProjectSettingsRequestSchema.toJSONSchema();
```