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