manifest.json for Livedeck widgets: fields, permissions and error codes

Every field, permission and setting type of manifest.json, and what each error code means.

8 min read Updated Nov 4, 2026

manifest.json describes your widget. Livedeck reads it on upload, builds the editor settings from it and gives the widget only the permissions listed in it. Unknown fields are an error so typos never hide.

json
{
  "manifestVersion": 1,
  "name": "Gift Goal",
  "version": "1.0.0",
  "sdk": "1",
  "entry": "index.html",
  "description": "A bar that fills up with gifts.",
  "formats": ["9:16", "16:9"],
  "size": { "default": [600, 160], "min": [300, 80], "max": [1080, 400] },
  "permissions": ["events.gift", "media.play"],
  "settings": [
    { "key": "goal", "type": "number", "label": { "de": "Ziel", "en": "Goal" }, "default": 100, "min": 1 },
    { "key": "giftId", "type": "gift", "label": { "de": "Nur dieses Geschenk", "en": "Only this gift" } },
    { "key": "accent", "type": "color", "label": { "de": "Farbe", "en": "Colour" }, "default": "#22c55e" },
    { "key": "doneSound", "type": "media", "label": { "de": "Ton bei Ziel", "en": "Goal sound" }, "accept": "audio" }
  ],
  "locales": ["de", "en"]
}

Fields

manifestVersion

Required: yes

Meaning: Always 1

name

Required: yes

Meaning: Name of the widget, at most 60 characters

version

Required: yes

Meaning: Version number x.y.z, for example 1.2.0

sdk

Required: yes

Meaning: SDK version, "1" today

entry

Required: no

Meaning: Start file, index.html by default. Must end in .html.

description

Required: no

Meaning: Short description, at most 300 characters

formats

Required: no

Meaning: ["9:16"], ["16:9"] or both (default: both)

size

Required: yes

Meaning: Size in pixels on the overlay canvas: default, min and max as [width, height]

permissions

Required: no

Meaning: Which data the widget gets (see below)

settings

Required: no

Meaning: Settings users change in the editor (at most 40)

locales

Required: no

Meaning: Languages your widget supports, for example ["de", "en"]

The canvas is 1080 × 1920 pixels in 9:16 and 1920 × 1080 in 16:9. Sizes go from 16 to 3840 pixels. min and max are the limits when users resize the widget in the editor. Without them, default applies. Build the widget in fixed pixels for default: when users resize it, Livedeck zooms the whole page with the box (text, pictures and spacing grow together). If the box gets another shape than default, the page gets the extra room in that direction, so use 100% widths/heights, flexbox or grid where it should fill. livedeck.context.size is the page size in CSS pixels and livedeck.context.scale the zoom.

Permissions

Buyers see this list before buying, and the editor shows it under "Gets access to". Only ask for what you really need.

events.gift

Gifts (event gift)

events.chat

Chat messages (chat)

events.like

Likes, bundled (like)

events.follow

New followers (follow)

events.share

Shares of the LIVE (share)

events.join

A viewer joins the LIVE (join)

events.fanclub

Fan club joins (fanclub)

events.viewers

Viewer count (viewers)

stream.status

Live, offline or being checked (stream)

media.play

May play sounds from media settings through Livedeck

host.profile

The streamer's name and profile picture (livedeck.host)

Settings

Every setting has a key, a type and a label. The key starts with a lowercase letter followed by letters, digits or _ (at most 32 characters). A label is text or an object with languages such as {"de": "Farbe", "en": "Colour"}, at most 80 characters. The widget reads the values from livedeck.settings.

text

Fields: default, maxLength (at most 200)

Value in the widget: Text

number

Fields: default, min, max, step (all optional)

Value in the widget: Number

range

Fields: default, min and max (required), step

Value in the widget: Number, shown as a slider in the editor

boolean

Fields: default

Value in the widget: true or false

color

Fields: default as #rrggbb

Value in the widget: Colour as #rrggbb

select

Fields: options (1 to 50, each with value and label), default

Value in the widget: value of the chosen option

gift

Fields: default (gift ID or null)

Value in the widget: Gift ID as a number, or null

media

Fields: accept: audio, image or video. No default.

Value in the widget: true when the user picked a file of their own, otherwise false

Note: Media settings never give the widget the file's address. Play sounds with livedeck.media.play(key); get pictures and clips with livedeck.media.url(key).

When a value is missing or invalid, the widget gets the default. That way updates with new settings work for everyone who already uses your widget.

Errors in manifest.json

When the check fails with "manifest.json is invalid", the code and the place are listed below it, for example settings[2].default.

manifest_not_object

The file is not a JSON object.

manifest_too_large

The file is larger than 64 KB.

manifest_invalid_json

Not valid JSON (often one comma too many or too few).

unknown_field

This field does not exist. Usually a typo.

required

A required field is missing.

wrong_type

Wrong type, for example text instead of a list.

unsupported_manifest_version

manifestVersion is not 1.

unsupported_sdk

sdk is not "1".

invalid_name

Name empty, longer than 60 characters or with invisible control characters.

invalid_text

Text empty, too long or with invisible control characters.

invalid_version

Version not in the form x.y.z (for example 1.0.0).

invalid_entry

entry is not a relative path to an .html file.

invalid_format

Format is not "9:16" or "16:9".

duplicate

Duplicate entry.

invalid_size

Size outside 16 to 3840 pixels, or default is not between min and max.

unknown_permission

This permission does not exist.

too_many_settings

More than 40 settings.

invalid_setting_key

key does not match the pattern (see above).

unknown_setting_type

This setting type does not exist.

invalid_default

default does not fit the type or is outside the bounds.

invalid_bounds

min, max, step or maxLength is invalid.

invalid_options

options are missing, empty, more than 50, or an option has no value.

invalid_media_kind

accept is not audio, image or video.

invalid_locale

This language does not exist. Allowed: en, de, tr, fr, es, it, ru, ar, zh-CN, ja, he, pt, nl, pl, uk, ko, hi, id, vi, th.

Was this article helpful?