Skip to main content

YouTubeEmbed

Embeds a YouTube video with optional start time and basic fullscreen support.

Example structures​

Basic​

{
  "type": "YouTubeEmbed",
  "data": {
    "url": "https://www.youtube.com/....",
    "start": 0
  }
}

With background sound (host only)​

{
  "type": "YouTubeEmbed",
  "sound": {
    "url": "/sound/testbg.wav",
    "volume": 0.5,
    "repeat": true,
    "hostonly": true
  },
  "data": {
    "url": "https://www.youtube.com/....",
    "start": 60
  }
}

Properties​

data.url (string, required) YouTube watch URL in the form https://www.youtube.com/watch?v=VIDEO_ID. The component converts this to an embed URL internally.

data.start (number, optional) Start time in seconds (non-negative integer). If omitted, the video starts at 0.

sound (object, optional; inherited from base node) Optional background audio that plays alongside the video. Fields: url (string), volume (0–1), repeat (boolean), hostonly (boolean).

Visual design​

  • The player is centered and constrained by an aspect-video container.
  • A black background fills the remaining space.
  • When the app is in browser fullscreen, a subtle clickable area appears in the bottom-right corner (used to toggle the component’s “fake fullscreen” class).

Behavior​

URL handling​

  • The code transforms .../watch?v=VIDEO_ID into .../embed/VIDEO_ID.
  • If start is provided, the player src becomes .../embed/VIDEO_ID?start=SECONDS.
  • Additional YouTube query parameters are not supported by this implementation. Use a clean watch URL without extra query items.

Fullscreen​

  • Native fullscreen state is detected via the fullscreenchange event and mirrored into component state.
  • A “fake fullscreen” CSS class (coverFullscreen) can be toggled when native fullscreen is active; it adjusts sizing but does not programmatically exit OS/browser fullscreen.
  • The listener does not catch F11 toggling in all browsers (browser limitation).

Autoplay​

  • The iframe includes allow="autoplay" but no autoplay=1 query parameter is set. Playback typically requires a user gesture due to browser policies.

Audio​

  • Default node sound is disabled in the Scoreboard example, but here you can optionally define sound in the node config. The engine handles playback (e.g., host-only background track that loops during the video).

Host/participants​

  • No special host controls in the component itself. Navigation (next/back) is handled by the standard workshop UI.
  • All participants see the same embedded player.

Use cases​

  • Play an intro or explainer video between quiz rounds.
  • Show a clip starting at a specific timestamp while a subtle host-only background loop plays.
  • Embed short tutorials or instructions before an activity.

Technical notes​

  • Props:

    interface Props {
      workshop: WorkshopPayload;
      node: NodePayload;
    }

  • The iframe src is built as:

    nodeData.url.replace('/watch?v=', '/embed/') +
    (nodeData.start != undefined ? '?start=' + nodeData.start : '')

  • The iframe has allowFullScreen and allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share".

tip
  • Use full youtube.com/watch?v= links. Short links like youtu.be/VIDEO_ID or already-embedded URLs may not transform correctly.
  • Only the start parameter is supported. If you need extra YouTube player options (autoplay, mute, controls), they would require extending the implementation.