Render settings reference

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	CLI projects	CLI exports	`youka preset schema --json` for preset bodies
SDK	SDK presets	SDK project settings	SDK exports	`KaraokePresetSchema.toJSONSchema()` and `RestUpdateProjectSettingsRequestSchema.toJSONSchema()`
API	API presets	API project settings	API exports	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`

{
  "aspectRatio": "16:9",
  "layout": {},
  "background": { "type": "auto" },
  "singerTextStyles": {
    "0": {},
  },
  "languageTextStyles": {
    "en": {},
  },
  "chordTextStyle": {},
  "overlays": {},
  "trim": {
    "startSeconds": 0,
    "endSeconds": 0,
  },
}

`project settings` / export `settingsOverride`

{
  "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<number, TextStyle>`	Keys are singer indexes such as `"0"` or `"1"`.
`languageTextStyles`	`Record<string, TextStyle>`	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.
`fontSource`	`object`	`{ "type": "catalog" }` by default, or a custom-font reference created in Youka Online.
`fontSize`	`number`	Font size.
`fontWeight`	`number`	Numeric font weight. Custom fonts require a real imported face or variable-font weight.
`fontStyle`	`string`	`normal` or `italic`. Custom fonts require a matching imported face.
`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.

Custom-font upload and management are currently available only in Youka Online. Select the font there and Youka stores its immutable ID in fontSource. Existing presets that omit fontSource and fontStyle remain catalog-font presets and continue to render as before. The public API and SDK do not currently provide custom-font upload endpoints.

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`, `appearance`, `beats`, `minGap`, `useNextSingerStyle`, `style`, `width`, `fadeTailWidth`, `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.leadIn.appearance`	`classic`, `fade-tail`
`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:

youka preset schema --json

import {
  KaraokePresetSchema,
  RestUpdateProjectSettingsRequestSchema,
} from "@youka/sdk";

const presetSchema = KaraokePresetSchema.toJSONSchema();
const projectSettingsSchema =
  RestUpdateProjectSettingsRequestSchema.toJSONSchema();

Overview

How To

Customization

Audio

Settings

Exporting

Account

Render settings reference

Where this shape is used

Core rule

Object shapes

`preset`

`project settings` / export `settingsOverride`

Top-level fields

`preset` and `settings.style`

`settings` and export `settingsOverride`

Common text-style fields

Background shape

Overlay objects

Allowed values and ranges

Schema commands

​Where this shape is used

​Core rule

​Object shapes

​preset

​project settings / export settingsOverride

​Top-level fields

​preset and settings.style

​settings and export settingsOverride

​Common text-style fields

​Background shape

​Overlay objects

​Allowed values and ranges

​Schema commands

Where this shape is used

Core rule

Object shapes

`preset`

`project settings` / export `settingsOverride`

Top-level fields

`preset` and `settings.style`

`settings` and export `settingsOverride`

Common text-style fields

Background shape

Overlay objects

Allowed values and ranges

Schema commands