@mux/mux-player-astro 0.0.1

package/README.md

@@ -0,0 +1,238 @@
+<p align="center">
+  <h1 align="center">&lt;MuxPlayer/&gt;</h1>
+  <a href="https://npmcharts.com/compare/@mux/mux-player-astro?interval=30"><img src="https://img.shields.io/npm/dm/@mux/mux-player-astro.svg?sanitize=true" alt="Downloads"></a>
+    <a href="https://www.npmjs.com/package/@mux/mux-player-astro"><img src="https://img.shields.io/npm/v/@mux/mux-player-astro.svg?sanitize=true" alt="Version"></a>
+    <a href="https://www.npmjs.com/package/@mux/mux-player-astro"><img src="https://img.shields.io/npm/l/@mux/mux-player-astro.svg?sanitize=true" alt="License"></a>
+</p>
+
+# Introduction
+
+`<MuxPlayer />` is a Mux-flavored Astro video player component, built on top of our [mux-player web component](../mux-player) and [Media Chrome](https://media-chrome.org).
+
+# Installation
+
+```shell
+npm install @mux/mux-player-astro
+```
+
+or
+
+```shell
+yarn add @mux/mux-player-astro
+```
+
+# Usage
+
+## Basic Usage
+
+```astro
+---
+import { MuxPlayer } from '@mux/mux-player-astro';
+---
+
+<MuxPlayer
+  playbackId="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
+  metadata={{
+    video_title: 'Big Buck Bunny',
+    viewer_user_id: 'user-id-1234',
+  }}
+/>
+```
+
+## With Styling
+
+```astro
+---
+import { MuxPlayer } from '@mux/mux-player-astro';
+---
+
+<MuxPlayer
+  playbackId="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
+  style={{
+    display: 'block',
+    aspectRatio: '16/9',
+    backgroundColor: '#000',
+  }}
+  autoplay
+  muted
+  streamType="on-demand"
+  proudlyDisplayMuxBadge
+/>
+```
+
+## With Themes
+
+You can use one of the built-in themes by passing the theme name as a string to the `theme` prop:
+
+```astro
+---
+import { MuxPlayer } from '@mux/mux-player-astro';
+---
+
+<MuxPlayer
+  playbackId="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
+  theme="classic"
+  style={{
+    display: 'block',
+    aspectRatio: '16/9',
+  }}
+/>
+```
+
+Available themes:
+- `classic` - Classic player theme
+- `minimal` - Minimal player theme
+- `microvideo` - Microvideo theme for short-form content
+- `gerwig` - P, pretty, I, intelligent, N, never sad, K, cool
+- `news` - News theme
+
+Alternatively you can use a [Media Chrome theme](https://www.mux.com/docs/guides/player-themes#media-chrome-themes) by passing the theme name as a string and including the theme `<template>` element with that ID in your page:
+
+```astro
+---
+import { MuxPlayer } from '@mux/mux-player-astro';
+---
+<template id="tiny-theme">
+  <media-controller>
+    <slot name="media" slot="media"></slot>
+    <media-control-bar>
+      <media-play-button></media-play-button>
+    </media-control-bar>
+  </media-controller>
+</template>
+<MuxPlayer
+  playbackId="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
+  theme="tiny-theme"
+/>
+```
+
+## With Event Handling
+
+To add event listeners to the component you can use [a client-side script](https://docs.astro.build/en/guides/client-side-scripts/). You can get the correct types for the player element by importing `MuxPlayerElement` from `@mux/mux-player-astro` and casting the element to that type.
+
+```astro
+---
+import { MuxPlayer } from '@mux/mux-player-astro';
+---
+
+<MuxPlayer
+  id="my-player"
+  playbackId="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
+/>
+
+<script>
+  import type { MuxPlayerElement } from '@mux/mux-player-astro';
+
+  const player = document.getElementById('my-player') as MuxPlayerElement;
+
+  player.addEventListener('play', (event) => {
+    console.log('Player started playing!');
+  });
+
+  player.addEventListener('pause', (event) => {
+    console.log('Player paused!');
+  });
+
+  player.addEventListener('timeupdate', (event) => {
+    console.log('Current time: ', player.currentTime);
+  });
+
+  player.addEventListener('ended', (event) => {
+    console.log('Video ended!');
+  });
+</script>
+```
+
+## Audio Content
+
+```astro
+---
+import { MuxPlayer } from '@mux/mux-player-astro';
+---
+
+<MuxPlayer
+  playbackId="your-audio-playback-id"
+  audio
+  metadata={{
+    video_title: 'My Podcast Episode',
+  }}
+/>
+```
+
+## Live Streams
+
+```astro
+---
+import { MuxPlayer } from '@mux/mux-player-astro';
+---
+
+<MuxPlayer
+  playbackId="your-live-playback-id"
+  streamType="live"
+  targetLiveWindow={Infinity}
+  title="Live Stream"
+/>
+```
+
+## Custom Colors
+
+```astro
+---
+import { MuxPlayer } from '@mux/mux-player-astro';
+---
+
+<MuxPlayer
+  playbackId="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe"
+  primaryColor="#ff6b35"
+  secondaryColor="#ffffff"
+  accentColor="#0066cc"
+/>
+```
+
+# Props
+
+All props from the underlying `mux-player` web component are supported, including:
+
+## Core Props
+- `playbackId` - Mux playback ID for the video
+- `src` - Direct video URL (alternative to playbackId)
+- `poster` - Poster image URL
+- `audio` - Enable audio-only mode
+
+## Playback Props
+- `autoplay` - Auto-start playback
+- `muted` - Start muted
+- `loop` - Loop the video
+- `playsInline` - Play inline on mobile
+- `currentTime` - Set initial playback position
+- `playbackRate` - Playback speed (1.0 = normal)
+
+## Stream Props
+- `streamType` - Type of stream ('on-demand', 'live', 'll-live')
+- `targetLiveWindow` - Live stream window duration
+
+## Metadata Props
+- `metadata` - Object with video_id, video_title, viewer_user_id
+- `envKey` - Environment key for Mux Data
+- `customDomain` - Custom domain for video delivery
+
+## UI Props
+- `theme` - Player theme component
+- `primaryColor` - Primary UI color
+- `secondaryColor` - Secondary UI color
+- `accentColor` - Accent UI color
+- `proudlyDisplayMuxBadge` - Show Mux badge
+
+## Advanced Props
+- `tokens` - Signed tokens for private videos
+- `storyboardSrc` - Custom storyboard/thumbnail track
+- `chapters` - Chapter markers
+- `renditionOrder` - Quality selection ordering
+- `maxResolution` - Maximum playback resolution
+- `minResolution` - Minimum playback resolution
+
+# Docs
+
+Docs and guides live on [docs.mux.com](https://docs.mux.com/guides/video/mux-player?utm_source=github-mux-player).
+
+API reference lives [on Github](../mux-player/REFERENCE.md).

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@mux/mux-player-astro",
+  "version": "0.0.1",
+  "description": "An open source Mux player for Astro that Just Works™",
+  "homepage": "https://mux.com/player",
+  "keywords": [
+    "video",
+    "mux",
+    "player",
+    "hls",
+    "astro",
+    "astro-component"
+  ],
+  "type": "module",
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./ads": "./src/ads/index.ts"
+  },
+  "peerDependencies": {
+    "astro": "^4.0.0 || ^5.0.0"
+  },
+  "dependencies": {
+    "@mux/mux-player": "3.5.1",
+    "@mux/playback-core": "0.30.1"
+  },
+  "devDependencies": {
+    "astro": "^5.11.0",
+    "vite": "^6.0.0"
+  }
+}

package/src/MuxPlayer.astro

@@ -0,0 +1,13 @@
+---
+import type { MuxPlayerProps } from './types';
+import { getThemeObject, toNativeAttributes } from './utils';
+type Props = MuxPlayerProps;
+const { theme, ...props } = Astro.props;
+const { component: Theme, name: themeName } = await getThemeObject(theme);
+---
+
+<mux-player {...toNativeAttributes(props)} theme={themeName}><slot /></mux-player>
+{Theme && <Theme />}
+<script>
+  import '@mux/mux-player';
+</script>

package/src/ads/MuxPlayer.astro

@@ -0,0 +1,13 @@
+---
+import type { MuxPlayerAdsProps } from '../types';
+import { getThemeObject, toNativeAttributes } from '../utils';
+type Props = MuxPlayerAdsProps;
+const { theme, ...props } = Astro.props;
+const { component: Theme, name: themeName } = await getThemeObject(theme);
+---
+
+<mux-player {...toNativeAttributes(props)} theme={themeName}><slot /></mux-player>
+{Theme && <Theme />}
+<script>
+  import '@mux/mux-player/ads';
+</script>

package/src/ads/index.ts

@@ -0,0 +1,3 @@
+export { default as MuxPlayer } from './MuxPlayer.astro';
+export type { default as MuxPlayerElement } from '@mux/mux-player';
+export type { MuxVideoTheme } from '../types';

package/src/index.ts

@@ -0,0 +1,3 @@
+export { default as MuxPlayer } from './MuxPlayer.astro';
+export type { default as MuxPlayerElement } from '@mux/mux-player';
+export type { MuxVideoTheme } from './types';

package/src/themes/classic/classic.astro

@@ -0,0 +1,3 @@
+<script>
+  import '@mux/mux-player/themes/classic';
+</script>

package/src/themes/classic/index.ts

@@ -0,0 +1,6 @@
+import type { MuxVideoTheme } from '../../types';
+import component from './classic.astro';
+export default {
+  component,
+  name: 'classic',
+} satisfies MuxVideoTheme;

package/src/themes/gerwig/gerwig.astro

@@ -0,0 +1,3 @@
+<script>
+  import '@mux/mux-player/themes/gerwig';
+</script>

package/src/themes/gerwig/index.ts

@@ -0,0 +1,6 @@
+import type { MuxVideoTheme } from '../../types';
+import component from './gerwig.astro';
+export default {
+  component,
+  name: 'gerwig',
+} satisfies MuxVideoTheme;

package/src/themes/microvideo/index.ts

@@ -0,0 +1,6 @@
+import type { MuxVideoTheme } from '../../types';
+import component from './microvideo.astro';
+export default {
+  component,
+  name: 'microvideo',
+} satisfies MuxVideoTheme;

package/src/themes/microvideo/microvideo.astro

@@ -0,0 +1,3 @@
+<script>
+  import '@mux/mux-player/themes/microvideo';
+</script>

package/src/themes/minimal/index.ts

@@ -0,0 +1,6 @@
+import type { MuxVideoTheme } from '../../types';
+import component from './minimal.astro';
+export default {
+  component,
+  name: 'minimal',
+} satisfies MuxVideoTheme;

package/src/themes/minimal/minimal.astro

@@ -0,0 +1,3 @@
+<script>
+  import '@mux/mux-player/themes/minimal';
+</script>

package/src/themes/news/index.ts

@@ -0,0 +1,6 @@
+import type { MuxVideoTheme } from '../../types';
+import component from './news.astro';
+export default {
+  component,
+  name: 'news',
+} satisfies MuxVideoTheme;

package/src/themes/news/news.astro

@@ -0,0 +1,3 @@
+<script>
+  import '@mux/mux-player/themes/news';
+</script>

package/src/types.ts

@@ -0,0 +1,95 @@
+import type {
+  CmcdTypes,
+  MaxResolutionValue,
+  MinResolutionValue,
+  PlaybackTypes,
+  RenditionOrderValue,
+  StreamTypes,
+} from '@mux/playback-core';
+import type { Tokens } from '@mux/mux-player';
+import type { AstroComponentFactory } from 'astro/runtime/server/index.js';
+
+type ValueOf<T> = T[keyof T];
+
+export type MuxVideoTheme = {
+  component?: AstroComponentFactory;
+  name?: string;
+};
+
+export type BuiltinTheme = 'classic' | 'gerwig' | 'microvideo' | 'minimal' | 'news';
+
+export type MuxPlayerProps = {
+  theme?: MuxVideoTheme | BuiltinTheme | (string & {});
+  hotkeys?: string;
+  nohotkeys?: boolean;
+  castReceiver?: string | undefined;
+  castCustomData?: Record<string, any> | undefined;
+  defaultHiddenCaptions?: boolean;
+  playerSoftwareVersion?: string;
+  playerSoftwareName?: string;
+  playerInitTime?: number;
+  forwardSeekOffset?: number;
+  backwardSeekOffset?: number;
+  maxResolution?: MaxResolutionValue;
+  minResolution?: MinResolutionValue;
+  renditionOrder?: RenditionOrderValue;
+  programStartTime?: number;
+  programEndTime?: number;
+  proudlyDisplayMuxBadge?: boolean;
+  assetStartTime?: number;
+  assetEndTime?: number;
+  metadataVideoId?: string;
+  metadataVideoTitle?: string;
+  metadataViewerUserId?: string;
+  metadata?: {
+    video_id?: string;
+    video_title?: string;
+    viewer_user_id?: string;
+  };
+  primaryColor?: string;
+  secondaryColor?: string;
+  accentColor?: string;
+  placeholder?: string;
+  playbackRates?: number[];
+  defaultShowRemainingTime?: boolean;
+  defaultDuration?: number;
+  noVolumePref?: boolean;
+  thumbnailTime?: number;
+  title?: string;
+  videoTitle?: string;
+  tokens?: Tokens;
+  currentTime?: number;
+  volume?: number;
+  paused?: boolean;
+  src?: string | null;
+  poster?: string;
+  playbackRate?: number;
+  playsInline?: boolean;
+  preload?: string;
+  crossorigin?: string;
+  autoplay?: boolean | string;
+  loop?: boolean;
+  muted?: boolean;
+  audio?: boolean;
+  envKey?: string;
+  debug?: boolean;
+  disableTracking?: boolean;
+  disableCookies?: boolean;
+  disablePictureInPicture?: boolean;
+  extraSourceParams?: Record<string, any>;
+  beaconCollectionDomain?: string;
+  customDomain?: string;
+  playbackId?: string;
+  preferPlayback?: ValueOf<PlaybackTypes> | undefined;
+  streamType?: ValueOf<StreamTypes>;
+  defaultStreamType?: ValueOf<StreamTypes>;
+  targetLiveWindow?: number;
+  startTime?: number;
+  storyboardSrc?: string;
+  preferCmcd?: ValueOf<CmcdTypes> | undefined;
+} & astroHTML.JSX.HTMLAttributes;
+
+export type MuxPlayerAdsProps = MuxPlayerProps & {
+  allowAdBlocker?: boolean;
+  adTagUrl?: string;
+};

package/src/utils.ts

@@ -0,0 +1,68 @@
+/// <reference types="vite/client" />
+import type { MuxVideoTheme } from './types';
+
+const toKebabCase = (string: string) =>
+  string.replace(/[A-Z]/g, (match) => `-${match.toLowerCase()}`).replaceAll('_', '-');
+
+const FLATTEN_PROPS = new Set(['metadata', 'tokens', 'castCustomData']);
+
+export const themes = import.meta.glob<{ default: MuxVideoTheme }>('./themes/*/index.ts');
+
+function stringifyValue(value: any): string {
+  if (Array.isArray(value)) {
+    return value.join(' ');
+  }
+  if (typeof value === 'object' && value !== null) {
+    return JSON.stringify(value);
+  }
+  if (value === true) {
+    return '';
+  }
+  return String(value);
+}
+
+export async function getThemeObject(theme: string | MuxVideoTheme | undefined): Promise<MuxVideoTheme> {
+  if (!theme) {
+    return {};
+  }
+  if (typeof theme !== 'string') {
+    return theme;
+  }
+  const themeModule = themes[`./themes/${theme}/index.ts`];
+  if (!themeModule) {
+    return {
+      name: theme,
+    };
+  }
+  return (await themeModule()).default;
+}
+
+export const toNativeAttributes = (props: { [key: string]: any } = {}): Record<string, string> => {
+  return Object.entries(props).reduce<Record<string, string>>((transformedProps, [propName, propValue]) => {
+    if (typeof propValue === 'undefined' || propValue === null || propValue === false) {
+      return transformedProps;
+    }
+    if (propName === 'style') {
+      transformedProps.style = propValue;
+      return transformedProps;
+    }
+
+    const attrName = toKebabCase(propName);
+
+    if (FLATTEN_PROPS.has(propName)) {
+      if (typeof propValue === 'object' && !Array.isArray(propValue)) {
+        Object.entries(propValue).forEach(([key, value]) => {
+          const kebabKey = toKebabCase(`${attrName}-${key}`);
+          if (typeof propValue !== 'undefined' && propValue !== null && !props.hasOwnProperty(kebabKey)) {
+            transformedProps[kebabKey] = stringifyValue(value);
+          }
+        });
+      }
+    } else {
+      const attrValue = stringifyValue(propValue);
+      transformedProps[attrName] = attrValue;
+    }
+
+    return transformedProps;
+  }, {});
+};