Skip to main content

YouTubeEmbed

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

Example structures​

Basic​

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

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.

data.end (number, optional) End time in seconds, measured from the start of the video (not relative to start). The player stops at this point. If omitted, the video plays to the end.

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.
  • start and end are appended as query parameters, e.g. .../embed/VIDEO_ID?start=18&end=44.
  • 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 between two timestamps 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:

    // query = URLSearchParams built from nodeData.start and nodeData.end
    nodeData.url.replace('/watch?v=', '/embed/') + (query ? '?' + query : '');

  • 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 and end parameters are supported. If you need extra YouTube player options (autoplay, mute, controls), they would require extending the implementation.