From 7f0e0c6b3763ef8577b7967bd188d3cc8d45830f Mon Sep 17 00:00:00 2001 From: Roger Tuan Date: Mon, 29 Sep 2025 12:05:30 -0700 Subject: [PATCH 1/3] Make the Mux Playback ID more explicit. --- src/VideoPlayer/index.tsx | 157 ++++++++++++++++++++++---------------- 1 file changed, 92 insertions(+), 65 deletions(-) diff --git a/src/VideoPlayer/index.tsx b/src/VideoPlayer/index.tsx index 8e41bc2..1fccf1d 100644 --- a/src/VideoPlayer/index.tsx +++ b/src/VideoPlayer/index.tsx @@ -8,48 +8,75 @@ // // [1]: https://www.mux.com/player -import React, { forwardRef } from 'react'; +import React, {forwardRef} from 'react'; // We use and extend Typescript types defined in the MUX player. - import type MuxPlayerElement from '@mux/mux-player'; -import type { MuxPlayerProps } from '@mux/mux-player-react'; +import type {MuxPlayerProps} from '@mux/mux-player-react'; // React MUX player is made available in two flavours: eager and lazy loaded. We // choose to use the lazy version to avoid loading the web component uselessly. // MUX player lazy version loads internally the eager version using // `React.lazy()`. - import MuxPlayer from '@mux/mux-player-react/lazy'; // The core of this component is the `useVideoPlayer` hook: it takes // data from DatoCMS GraphQL API and returns props as expected by the // `` component. - -import { useVideoPlayer } from '../useVideoPlayer/index.js'; +import {useVideoPlayer} from '../useVideoPlayer/index.js'; type Maybe = T | null; type Possibly = Maybe | undefined; +/** + * The playback ID is how the player knows which video to play. + * At least one of these is required. + * If both are provided, `muxPlaybackId` takes precedence. + * This is for backward compatibility. + */ +type PlaybackIdSources = + | { muxPlaybackId: Possibly; } + | { playbackId: Possibly; } + // `Video` represents a fragment of data regarding a video as returned from // DatoCMS GraphQL API. - -export type Video = { - /** Title attribute (`title`) for the video */ - title?: Possibly; - /** The height of the video */ - height?: Possibly; - /** The width of the video */ - width?: Possibly; - /** The MUX playbaack ID */ - muxPlaybackId?: Possibly; - /** The MUX playbaack ID */ - playbackId?: Possibly; - /** A data: URI containing a blurhash for the video */ - blurUpThumb?: Possibly; - /** Other data can be passed, but they have no effect on rendering the player */ - // biome-ignore lint/suspicious/noExplicitAny: we intentionally want to allow to add any other value to this video object - [k: string]: any; +/** + * Video data as returned by the DatoCMS GraphQL Content Delivery API. + * + * You MUST provide `muxPlaybackId`. The `streamingUrl` property is not used. + * + * @property muxPlaybackId - Mux playback ID + * @property playbackId - (Optional, fallback only) A playback ID alias for backward compatibility. + * @property title - Title attribute (`title`) for the video. + * @property height - The height of the video in pixels. + * @property width - The width of the video in pixels. + * @property blurUpThumb - A `data:` URI containing a blurhash placeholder image. + * @property [k: string] - Any additional properties are accepted but not used + * by the renderer. + * + * @example + * ```ts + * const video: Video = { + * muxPlaybackId: "abcdef123456", + * title: "Example video", + * width: 1920, + * height: 1080, + * blurUpThumb: "data:image/png;base64,..." + * }; + * ``` + */ +export type Video = PlaybackIdSources & { + /** Title attribute (`title`) for the video */ + title?: Possibly; + /** The height of the video */ + height?: Possibly; + /** The width of the video */ + width?: Possibly; + /** A data: URI containing a blurhash for the video */ + blurUpThumb?: Possibly; + /** Other data can be passed, but they have no effect on rendering the player */ + // biome-ignore lint/suspicious/noExplicitAny: we intentionally want to allow to add any other value to this video object + [k: string]: any; }; // The component supports [all the props][1] allowed by the `` @@ -59,51 +86,51 @@ export type Video = { // [1]: https://github.com/muxinc/elements/blob/main/packages/mux-player-react/REFERENCE.md export type VideoPlayerProps = MuxPlayerProps & { - /** The actual response you get from a DatoCMS `video` GraphQL query */ - data?: Video; + /** The actual response you get from a DatoCMS `video` GraphQL query */ + data?: Video; }; export const VideoPlayer: ( - props: VideoPlayerProps, + props: VideoPlayerProps, ) => ReturnType = forwardRef< - MuxPlayerElement, - VideoPlayerProps + MuxPlayerElement, + VideoPlayerProps >((props, ref) => { - const { - data = {}, - disableCookies = true, - disableTracking = true, - preload = 'metadata', - style: styleFromProps, - ...rest - } = props; - - const { - title, - playbackId, - style: styleFromHook, - placeholder, - } = useVideoPlayer({ - data, - }); - - const style = { - ...styleFromHook, - ...styleFromProps, - }; - - return ( - - ); + const { + data = {muxPlaybackId: undefined}, + disableCookies = true, + disableTracking = true, + preload = 'metadata', + style: styleFromProps, + ...rest + } = props; + + const { + title, + playbackId, + style: styleFromHook, + placeholder, + } = useVideoPlayer({ + data, + }); + + const style = { + ...styleFromHook, + ...styleFromProps, + }; + + return ( + + ); }); From 2658fcd2258e095677ebdbdbbce6c1bb12e77265 Mon Sep 17 00:00:00 2001 From: Roger Tuan Date: Mon, 29 Sep 2025 12:10:05 -0700 Subject: [PATCH 2/3] Reformat --- src/VideoPlayer/index.tsx | 110 +++++++++++++++++++------------------- 1 file changed, 55 insertions(+), 55 deletions(-) diff --git a/src/VideoPlayer/index.tsx b/src/VideoPlayer/index.tsx index 1fccf1d..12af769 100644 --- a/src/VideoPlayer/index.tsx +++ b/src/VideoPlayer/index.tsx @@ -8,11 +8,11 @@ // // [1]: https://www.mux.com/player -import React, {forwardRef} from 'react'; +import React, { forwardRef } from 'react'; // We use and extend Typescript types defined in the MUX player. import type MuxPlayerElement from '@mux/mux-player'; -import type {MuxPlayerProps} from '@mux/mux-player-react'; +import type { MuxPlayerProps } from '@mux/mux-player-react'; // React MUX player is made available in two flavours: eager and lazy loaded. We // choose to use the lazy version to avoid loading the web component uselessly. @@ -23,7 +23,7 @@ import MuxPlayer from '@mux/mux-player-react/lazy'; // The core of this component is the `useVideoPlayer` hook: it takes // data from DatoCMS GraphQL API and returns props as expected by the // `` component. -import {useVideoPlayer} from '../useVideoPlayer/index.js'; +import { useVideoPlayer } from '../useVideoPlayer/index.js'; type Maybe = T | null; type Possibly = Maybe | undefined; @@ -35,8 +35,8 @@ type Possibly = Maybe | undefined; * This is for backward compatibility. */ type PlaybackIdSources = - | { muxPlaybackId: Possibly; } - | { playbackId: Possibly; } + | { muxPlaybackId: Possibly } + | { playbackId: Possibly }; // `Video` represents a fragment of data regarding a video as returned from // DatoCMS GraphQL API. @@ -66,17 +66,17 @@ type PlaybackIdSources = * ``` */ export type Video = PlaybackIdSources & { - /** Title attribute (`title`) for the video */ - title?: Possibly; - /** The height of the video */ - height?: Possibly; - /** The width of the video */ - width?: Possibly; - /** A data: URI containing a blurhash for the video */ - blurUpThumb?: Possibly; - /** Other data can be passed, but they have no effect on rendering the player */ - // biome-ignore lint/suspicious/noExplicitAny: we intentionally want to allow to add any other value to this video object - [k: string]: any; + /** Title attribute (`title`) for the video */ + title?: Possibly; + /** The height of the video */ + height?: Possibly; + /** The width of the video */ + width?: Possibly; + /** A data: URI containing a blurhash for the video */ + blurUpThumb?: Possibly; + /** Other data can be passed, but they have no effect on rendering the player */ + // biome-ignore lint/suspicious/noExplicitAny: we intentionally want to allow to add any other value to this video object + [k: string]: any; }; // The component supports [all the props][1] allowed by the `` @@ -86,51 +86,51 @@ export type Video = PlaybackIdSources & { // [1]: https://github.com/muxinc/elements/blob/main/packages/mux-player-react/REFERENCE.md export type VideoPlayerProps = MuxPlayerProps & { - /** The actual response you get from a DatoCMS `video` GraphQL query */ - data?: Video; + /** The actual response you get from a DatoCMS `video` GraphQL query */ + data?: Video; }; export const VideoPlayer: ( - props: VideoPlayerProps, + props: VideoPlayerProps, ) => ReturnType = forwardRef< - MuxPlayerElement, - VideoPlayerProps + MuxPlayerElement, + VideoPlayerProps >((props, ref) => { - const { - data = {muxPlaybackId: undefined}, - disableCookies = true, - disableTracking = true, - preload = 'metadata', - style: styleFromProps, - ...rest - } = props; + const { + data = { muxPlaybackId: undefined }, + disableCookies = true, + disableTracking = true, + preload = 'metadata', + style: styleFromProps, + ...rest + } = props; - const { - title, - playbackId, - style: styleFromHook, - placeholder, - } = useVideoPlayer({ - data, - }); + const { + title, + playbackId, + style: styleFromHook, + placeholder, + } = useVideoPlayer({ + data, + }); - const style = { - ...styleFromHook, - ...styleFromProps, - }; + const style = { + ...styleFromHook, + ...styleFromProps, + }; - return ( - - ); + return ( + + ); }); From 67e7173a5d7a2cbc2be3bf167531e0f024ab631d Mon Sep 17 00:00:00 2001 From: Roger Tuan Date: Mon, 29 Sep 2025 12:13:56 -0700 Subject: [PATCH 3/3] Clarify the two params --- src/VideoPlayer/index.tsx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/VideoPlayer/index.tsx b/src/VideoPlayer/index.tsx index 12af769..2001867 100644 --- a/src/VideoPlayer/index.tsx +++ b/src/VideoPlayer/index.tsx @@ -43,10 +43,12 @@ type PlaybackIdSources = /** * Video data as returned by the DatoCMS GraphQL Content Delivery API. * - * You MUST provide `muxPlaybackId`. The `streamingUrl` property is not used. + * You MUST provide `muxPlaybackId` (which is a field in your GraphQL query). The `streamingUrl` property is not used here. + * + * As long as you provide `muxPlaybackId`, you can safely ignore the `playbackId` param. If you accidentally provide both, `muxPlaybackId` takes precedence. * * @property muxPlaybackId - Mux playback ID - * @property playbackId - (Optional, fallback only) A playback ID alias for backward compatibility. + * @property playbackId - (Optional, fallback only) Alias for the `muxPlaybackId` param, for backward compatibility * @property title - Title attribute (`title`) for the video. * @property height - The height of the video in pixels. * @property width - The width of the video in pixels.