DOCSEARCHbyAlgolia
Submit Docs

Media Chrome Documentation

website·Indexed 35 days ago

https://www.media-chrome.org

A library of customizable Web Components for building media player interfaces. It includes a comprehensive set of UI components like <media-controller>, <media-control-bar>, and <media-volume-range>, as well as support for React via specialized hooks and <MediaProvider>. The documentation covers theme creation, responsive controls, CSS variable styling, and integration with various media elements such as <dash-video>, <vimeo-video>, and <cloudflare-video>.

Tokens
68K
Snippets
318
Records
386
Agent score
71%

What's inside Media Chrome

  1. Overview of Media Chrome

    Media Chrome is a collection of fully customizable web components used to build media players from scratch. It separates the UI from the media playback engine, allowing the underlying playback engine to be swapped without affecting the UI. It is compatible with standard <video> and <audio> elements, as well as any element conforming to the HTMLMediaElement API. It works across various frameworks including React, Angular, VueJS, and Svelte.

  2. Overview of <media-controller>

    The <media-controller> element acts as the orchestrator for a media player, managing the communication of state and state change requests between a media element and its associated control elements. It also provides built-in sizing and layout to simplify player styling.

  3. Media Chrome architectural goals

    Media Chrome is built on several core architectural goals to ensure developer flexibility:

    • Native HTML Feel: Components align with native HTML element design to provide an intuitive interface for those familiar with web standards.
    • Independent Usability: Each UI element is designed to be usable independently of the rest of the project, similar to how a native <button> works independently of a <form>.
    • Unidirectional Data Flow: The architecture is compatible with modern JS frameworks (like React) that utilize unidirectional data flow, ensuring the components are not blocked or overly complex to integrate into such environments.

  4. Use the <media-mute-button> component

    The <media-mute-button> component toggles the sound of the media. It automatically updates its displayed content based on the current audio volume level: 'off' (muted/0%), 'low' (0-50%), 'medium' (50-75%), and 'high' (75-100%).
    <media-controller>
  <video slot="media" src="video.mp4"></video>
  <media-control-bar>
    <media-mute-button></media-mute-button>
    <media-volume-range></media-volume-range>
  </media-control-bar>
</media-controller>

  5. Use the <media-pip-button> to toggle picture-in-picture

    The <media-pip-button> component provides a toggle for a video's picture-in-picture (PiP) mode. It automatically updates its displayed content based on whether the media is currently in PiP mode and whether the browser supports the feature.
    <media-controller defaultsubtitles>
  <video
    playsinline muted crossorigin
    slot="media"
    src="https://stream.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/low.mp4"
  ></video>
  <media-pip-button></media-pip-button>
</media-controller>

  6. Integrate MediaStore state management in React

    Media Chrome provides a React Context provider and hooks to integrate with its MediaStore state management API. This allows developers to build custom React components that can read media state and request state changes. All necessary tools are exported from the media-chrome/react/media-store module.
    import {
  MediaProvider,
  useMediaDispatch,
  useMediaSelector,
  useMediaRef,
  useMediaFullscreenRef,
  MediaActionTypes,
} from 'media-chrome/react/media-store';

  7. Media Chrome v1.0 New Features Overview

    Key additions in v1.0 include:

    • Getter/setter properties for all attributes on control/display components.
    • Improved TypeScript definitions.
    • <media-controller> now dispatches a breakpointchange event.
    • A new mediaended state attribute applied to <media-play-button>.
    • A generic icon slot for all components with customizable icons.

  8. Manage media state and user actions with media-controller

    Media Chrome uses a centralized controller architecture to handle interactions and state:

    1. User Actions: UI elements emit events to request state changes. These events bubble up the DOM to a parent <media-controller> element.
    2. Media Execution: The <media-controller> catches these events and calls the appropriate API on a child media element (such as <video> or <audio>) that is designated with the attribute slot="media".
    3. State Updates: Media state is reflected on UI elements via HTML attributes (e.g., <media-ui-element mediapaused>).
    4. Automatic Sync: If a UI element is a child of or associated with a <media-controller>, the controller updates these attributes automatically.
    5. Manual Association: UI elements not nested within a controller can be associated via the mediacontroller="" attribute or a JavaScript function.
    <media-controller>
  <!-- The media element being controlled -->
  <video slot="media" src="video.mp4"></video>
  
  <!-- UI elements that emit events and receive state attributes -->
  <media-play-button></media-play-button>
</media-controller>

  9. Toggle captions and subtitles with <media-captions-button>

    The <media-captions-button> component is used to toggle captions and subtitles on and off. It prefers captions tracks over subtitles tracks when enabling. The button's state is driven by the text track media state: it displays the on slot when any captions/subtitles are enabled, and the off slot when all are disabled.
    <media-controller defaultsubtitles>
  <video
    playsinline muted crossorigin
    slot="media"
    src="https://stream.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/low.mp4"
  >
    <track label="English" kind="captions" srclang="en" src='https://media-chrome.mux.dev/examples/vanilla/vtt/en-cc.vtt' />
  </video>
  <media-captions-button></media-captions-button>
</media-controller>

  10. Use media-control-bar for automatic layout and scaling

    The <media-control-bar> container component provides automatic layout capabilities when used within a <media-controller>:

    1. Flexible Sizing: Components like <media-time-range> automatically expand to fill available space.
    2. Auto-Scaling: Components scale down based on available real estate.
    3. Full Width: The bar automatically grows to fill the entire width of the controller.

  11. Display media playback time with <media-time-display>

    The <media-time-display> component shows the current or remaining time of media playback. By default, it displays the elapsed time. Users can click the component to toggle between showing the current time and the remaining time.
    <media-controller>
  <video
    slot="media"
    src="https://stream.mux.com/A3VXy02VoUinw01pwyomEO3bHnG4P32xzV7u1j1FSzjNg/low.mp4"
    playsinline
    muted
  >
  </video>
  <media-control-bar>
    <media-play-button></media-play-button>
    <media-time-display></media-time-display>
  </media-control-bar>
</media-controller>

  12. Replace default component icons with custom icons

    Components with icons allow you to override the default graphics by passing child elements into specific slots. Use the slot attribute to identify which state the icon represents (e.g., slot="play" or slot="pause"). You can use SVGs, images, or font icons.
    <media-play-button>
  <svg slot="play" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
    <path d="..."/>
  </svg>
  <svg slot="pause" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
    <path d="..."/>
  </svg>
</media-play-button>