Video Controls, Autoplay Policies & Picture-in-Picture

Technical Deep Dive & Specifications

The controls Attribute & User-Agent Shadow DOM

When you add the boolean controls attribute to <video controls>, the browser injects a complex, pre-built interactive user interface directly inside the element's User-Agent Shadow DOM:

+---------------------------------------------------------------------------------------+
|                       USER-AGENT SHADOW DOM (UA SHADOW ROOT)                          |
+---------------------------------------------------------------------------------------+
|  <video controls>                                                                     |
|    #shadow-root (user-agent)                                                          |
|      <div class="media-controls-container">                                           |
|        <button class="play-button" aria-label="Play"></button>                        |
|        <input type="range" class="timeline-slider" aria-label="Seek">                 |
|        <div class="time-display">0:00 / 3:45</div>                                    |
|        <button class="mute-button" aria-label="Mute"></button>                        |
|        <input type="range" class="volume-slider" aria-label="Volume">                 |
|        <button class="pip-button" aria-label="Picture in Picture"></button>           |
|        <button class="fullscreen-button" aria-label="Fullscreen"></button>            |
|      </div>                                                                           |
|  </video>                                                                             |
+---------------------------------------------------------------------------------------+

Restricting Native UI with controlsList & disablePictureInPicture

Chromium browsers support fine-grained controls customization via the controlsList attribute and boolean UI toggles:

<video 
  controls 
  controlslist="nodownload nofullscreen noremoteplayback" 
  disablepictureinpicture 
  disableremoteplayback 
  src="lesson.mp4">
</video>

Handling Autoplay Rejections in JavaScript

Because HTMLMediaElement.play() returns a JavaScript Promise, attempting to trigger unmuted playback on page load results in a caught or uncaught NotAllowedError:

const video = document.querySelector('video');

// ❌ DANGEROUS: Unhandled promise rejection if autoplay is blocked
video.play(); // Throws Uncaught (in promise) NotAllowedError

// ✅ PRODUCTION PATTERN: Resilient Autoplay with Muted Fallback
async function startAutoplayWithFallback(mediaElement) {
  try {
    // Attempt standard playback
    await mediaElement.play();
    console.log('Autoplay succeeded with full audio.');
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      console.warn('Unmuted autoplay blocked. Retrying in muted mode...');
      mediaElement.muted = true;
      try {
        await mediaElement.play();
        console.log('Muted autoplay succeeded.');
        showUnmuteNotification(mediaElement);
      } catch (mutedErr) {
        console.error('Even muted autoplay was blocked by user settings:', mutedErr);
      }
    }
  }
}

The Picture-in-Picture (PiP) API

The W3C Picture-in-Picture API allows websites to detach a playing video into a floating, resizable window pinned on top of all other operating system applications:

+---------------------------------------------------------------------------------------+
|                              PICTURE-IN-PICTURE (PiP) FLOW                            |
+---------------------------------------------------------------------------------------+
|  1. Check Availability:   document.pictureInPictureEnabled === true                   |
|                                                   |                                   |
|  2. Check Element State:  video.disablePictureInPicture === false                     |
|                                                   |                                   |
|  3. Request PiP Window:   const pipWin = await video.requestPictureInPicture()        |
|                                                   |                                   |
|  4. Track Lifecycle:      video.addEventListener('enterpictureinpicture', ...)        |
|                           video.addEventListener('leavepictureinpicture', ...)        |
|                                                   |                                   |
|  5. Exit Programmatically:await document.exitPictureInPicture()                       |
+---------------------------------------------------------------------------------------+

// Toggle Picture-in-Picture Window
async function togglePictureInPicture(videoElement) {
  if (!document.pictureInPictureEnabled) {
    alert('Picture-in-Picture is not supported in this browser.');
    return;
  }

  try {
    if (document.pictureInPictureElement) {
      // If a video is already in PiP, close it
      await document.exitPictureInPicture();
    } else {
      // Open this video in floating PiP window
      const pipWindow = await videoElement.requestPictureInPicture();
      console.log(`PiP window dimensions: ${pipWindow.width}x${pipWindow.height}`);
      
      pipWindow.addEventListener('resize', () => {
        console.log(`User resized PiP window to: ${pipWindow.width}x${pipWindow.height}`);
      });
    }
  } catch (error) {
    console.error('PiP request failed:', error);
  }
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

• Line 38 (controlslist="nodownload"):
  • Directs Chromium to hide the "Download Video" menu item inside the native three-dot menu.
• Line 58 (pipBtn.addEventListener('click', async () => ...):
  • Checks if another element is already in PiP via document.pictureInPictureElement. If so, exits; otherwise, spawns the floating window using player.requestPictureInPicture().
• Lines 73–84 (autoplayBtn.addEventListener(...)):
  • Demonstrates the try/catch cascade: attempts full-audio playback first, catching NotAllowedError and gracefully falling back to player.muted = true.

Expected Browser Render Output

+-------------------------------------------------------------+
| Picture-in-Picture & Autoplay Controller                    |
| +---------------------------------------------------------+ |
| |                    [ VIDEO CANVAS ]                     | |
| | [ > ] [===o=========================] 0:00 / 0:15 [🔊][⛶]| |
| +---------------------------------------------------------+ |
| [ 📺 Toggle Picture-in-Picture ] [ ▶️ Trigger Resilient Autoplay ] |
|                                                             |
| Log: Entered floating Picture-in-Picture mode.              |
+-------------------------------------------------------------+