EmbedKing · embed library

Configuration reference

How to load embed.js and configure the carousel with window.EmbedKingYtWidgetConfig and optional EmbedKingYoutube.init().

Quick links

/embed.jsProduction bundle
widgets.htmlExamples
/playgroundLive JSON + preview

Loading the embed

Set configuration on window before the script runs, then load embed.js from the same base URL you pass as apiBaseUrl (or a copy you host):

<!-- Set config before the script loads -->
<script>
  window.EmbedKingYtWidgetConfig = {
    apiBaseUrl: "https://embedking-youtube.ego-348.workers.dev",
    apiToken: "YOUR_TOKEN",
    // …see EmbedKingYtWidgetConfig below
  };
</script>
<script src="https://embedking-youtube.ego-348.workers.dev/embed.js" async></script>

After load, you can merge or override options programmatically:

window.EmbedKingYoutube?.init({
  carouselBreakpoints: [768, 1024],
});

init merges into the existing config, re-injects carousel CSS when relevant, and updates window.EmbedKingYtWidgetConfig.

`EmbedKingYtWidgetConfig`

All fields are optional unless a mode requires them. Set this object before loading the script, or pass a partial object to EmbedKingYoutube.init().

Property	Type	Default	Description
`apiBaseUrl`	`string`	`origin of script URL`	Base URL of the EmbedKing deployment (no trailing slash). The script loads data from this host.
`apiToken`	`string`	—	Token included with data requests from the embed. Use the value issued for your deployment.
`youtubeApiKey`	`string`	—	YouTube Data API key for playlist blocks and legacy stats UI when not using the RSS-only carousel path.
`channelId`	`string`	—	Channel id for the default single-channel carousel when you are not using carouselSources.
`playlistIds`	`string[]`	—	Playlist ids for legacy #playlist-1 … #playlist-n rows when not using carouselSources.
`carouselSources`	`EmbedKingCarouselSource[]`	—	When set, the carousel loads merged feeds from multiple channels/playlists. When omitted or empty, the carousel uses the default single-channel feed from the deployment.
`carouselFeedMode`	`EmbedKingCarouselFeedMode`	`"mixed"`	How multiple sources are merged when layout is single. Ignored when carouselLayout is multiRow.
`carouselLayout`	`EmbedKingCarouselLayout`	`"single"`	single: one carousel with merged ordering. multiRow: one horizontal row per carouselSources entry (three videos per row, separate arrows).
`statsChannelId`	`string`	—	Channel id used for subscriber / view / video counts when using carouselSources (if not set, the first channel source is used).
`carouselBreakpoints`	`number[]`	`[768]`	Viewport widths (px) where layout may change. On resize, the carousel re-renders only when crossing a boundary — not on every pixel. Single-column mobile carousel when innerWidth ≤ max(breakpoints).
`carouselRoot`	`string \| HTMLElement`	—	Container for the widget: CSS selector or element. If omitted, the first .ytw-container in the document.
`carouselMode`	`EmbedKingCarouselMode`	`"manual"`	manual: you provide markup. html: set carouselHtml. default: generated from defaultWidget.
`carouselHtml`	`string`	—	Full HTML when carouselMode is html.
`defaultWidget`	`EmbedKingDefaultWidgetContent`	—	Channel links, labels, logo when carouselMode is default.
`carouselFocusOnPlay`	`boolean`	`true`	If true, loads the IFrame API and on play dims the page and focuses the video. Not used when carouselLayout is multiRow.
`injectCarouselStyles`	`boolean`	`true`	If false, default .ytw-* CSS is not injected — you style the widget yourself.
`carouselStyles`	`EmbedKingCarouselStyles`	—	Replaces the entire built-in theme. patchCarouselStyles is ignored when set.
`patchCarouselStyles`	`(theme) => EmbedKingCarouselStyles`	—	Receives a deep clone of the default theme; return the object to inject. Not used when carouselStyles is set.

Read-only on window: EmbedKingCarouselDefaultStyles — reference the built-in theme (clone before mutating).

`EmbedKingCarouselSource`

One entry per channel or playlist feed. Used in carouselSources.

Property	Type	Default	Description
`key`required	`string`	—	Stable id for this source (config only).
`kind`required	`"channel" \| "playlist"`	—	RSS source type.
`id`required	`string`	—	Channel id (UC…) or playlist id (PL… / FL…).
`label`	`string`	—	Optional display label.

`EmbedKingDefaultWidgetContent`

URLs and copy for the generated header when using default mode.

Property	Type	Default	Description
`channelUrl`required	`string`	—	Main channel URL (logo + title area).
`subscribeUrl`	`string`	—	Subscribe button; defaults to channel URL with sub_confirmation if omitted.
`channelVideosUrl`	`string`	—	“Videos” / channel page link.
`logoSrc`	`string`	—	Logo image URL.
`logoAlt`	`string`	—	Alt text for logo.
`titleText`	`string`	—	Heading text.
`subscribeLabel`	`string`	—	Subscribe button label.
`channelButtonLabel`	`string`	—	Secondary channel button label.
`statsLoadingText`	`string`	—	Shown in the stats line until numbers load.

`EmbedKingCarouselStyles`

Structured theme object serialized to a stylesheet. Replace or patch via carouselStyles / patchCarouselStyles.

Property	Type	Default	Description
`fontImport`	`string \| null`	—	Injected first (e.g. @import for webfonts).
`rules`	`EmbedKingCssRuleMap`	—	Map of selector → CSS properties (camelCase or kebab-case keys).
`media`	`Record<string, EmbedKingCssRuleMap>`	—	Media query condition without @media — e.g. key "(max-width: 768px)" → nested rules.

Enumerations

`EmbedKingCarouselMode`

manual — You supply markup; container must match expected .ytw-* structure.
html — carouselHtml is set as innerHTML.
default — Markup built from defaultWidget.

`EmbedKingCarouselFeedMode`

mixed — Concatenate sources in order; global dedupe by video id.
interleaved — Round-robin one pick per source; global dedupe.
roundRobin — Each carousel “page” is filled by round-robin pulls from sources; no duplicate within a view.

`EmbedKingCarouselLayout`

single — One carousel; merged list from carouselFeedMode.
multiRow — One row per carouselSources entry; requires multiple sources in carouselSources and matching markup (e.g. playlist rows).