sanity-plugin-media-video v1.3.0

Sanity Plugin Media Video

A Sanity plugin for adding a media object (Image/Video) to your sanity studio schemas and displaying the media with built-in functionalities such as auto-play, custom PiP on scroll, etc.

This is a Sanity Studio v3 plugin.

• Sanity Plugin Media Video
  • 🔌 Installation
  • 🧑‍💻 Usage
    • Basic configuration
  • ⚙️ Plugin Configuration
  • 🌐 Localization
    • Available locales to be overriden
  • 🎬 How to render the media video on your website
    • NOTE
    • Props
    • videoHookCallbacks object
    • Custom class names and its corresponding CSS selectors
    • CSS Selectors for Media Video Components
    • Use your own implementation
      • Using the provided Hooks
  • 🗃️ Data model
  • 🛢 GROQ Query
  • ❓ FAQs
  • 📝 License
  • 🧪 Develop \& test
    • Release new version

🔌 Installation

Install peer dependencies such as zod and sanity-plugin-mux-input as well since this uses Mux as part of the video encoding service.

npm install sanity-plugin-media-video sanity-plugin-mux-input zod

🧑‍💻 Usage

Add it as a plugin in sanity.config.ts (or .js):

Basic configuration

// sanity.config.ts

import { defineConfig } from 'sanity';
import { mediaVideoPlugin } from 'sanity-plugin-media-video';

export default defineConfig({
  //...
  plugins: [
    // Add the muxInput from `sanity-plugin-mux-input` to make the mux 3rd party integration work
    muxInput({
      // your optional mux config here. Refer to this link for more info: https://github.com/sanity-io/sanity-plugin-mux-input?tab=readme-ov-file#configuring-mux-video-uploads
    }),

    // Add the mediaVideo plugin
    mediaVideoPlugin({
      // your optional configuration here
    }),
  ],
});

The plugin adds a new object type called media. Simply add it as a type to one of your defined fields like so

export default defineType({
  name: 'my-section',
  title: 'My Example Section',
  type: 'object',
  fields: [
    // ...your-other-fields
    defineField({
      name: 'my-custom-media-field',
      title: 'My Custom Media Field',
      type: 'media',
    }),
    // ...your-other-fields
  ],
});

Structure would look something like this:

⚙️ Plugin Configuration

This is the main configuration of the plugin. The available options are:

{
  // Optional boolean to enable/disable required validation on the image field
  isImageRequired?: boolean
}

🌐 Localization

This plugin uses the Studio UI Localization resource bundle, it is now possible to localize the fields to fit your needs.

Here is the default English bundle:

{
  'image.title': 'Image',
  'image.description': 'Serves as the image preview of the video',
  'image.required.title': 'Image is required',
  'image.altText.title': 'Alt Text',
  'image.altText.description':
    'Set an alternative text for accessibility purposes',
  'enableVideo.title': 'Enable Video',
  'enableVideo.description': 'Toggle to enable video',
  'videoType.title': 'Video Type',
  'videoType.link.title': 'Link',
  'videoType.mux.title': 'Mux',
  'videoType.required.title': 'Video Type is required',
  'isAutoPlay.title': 'Auto Play',
  'isAutoPlay.description': 'Automatically play the video when loaded',
  'isPipAutomatic.title': 'Enable Automatic PiP for Autoplay',
  'isPipAutomatic.description':
    'This automatically creates a small floating video player when you scroll past the main video',
  'videoUrl.title': 'Video Link',
  'videoUrl.required.title': 'Video Link is required',
  'muxVideo.required.title': 'Mux Video is required',
}

Available locales to be overriden

• en-US
• de-DE

If you want to override or add a new language, you will need to create a custom bundle with your desired translations. In order to override/add you must use mediaVideo as the namespace and add it to the i18n object in your sanity plugin configuration. Here is an example:

const myEnglishOverride = defineLocaleResourceBundle({
  // make sure the `locale` language code corresponds to the one you want to override
  locale: 'en-US',
  namespace: 'mediaVideo',
  resources: {
    'image.title': 'This is my override title',
  },
});

// sanity.config.ts
export default defineConfig({
  // ...
  i18n: {
    bundles: [myEnglishOverride],
  },
});

🎬 How to render the media video on your website

This plugin gives out a ready out of the box made component for rendering the media video on your website with built-in functionalities such as auto-play, custom PiP on scroll, etc. One way to render it is to use the provided renderer component or you can implement your own renderer component with the data that you get from the media object.

NOTE

• This plugin uses the react-player library for rendering the media video.
• The renderer also needs to be wrapped within the provided custom Provider component in order to function properly.

1. Import the Provider component and wrap the renderer component with it. Suggested to be placed in the root of your application.

import { MediaVideoProvider } from 'sanity-plugin-media-video/contexts';

// other code

<body>
  <MediaVideoProvider>
    {/* Your renderer component here or other components */}
  </MediaVideoProvider>
</body>;

2. Use the renderer component like so. Example usage below

You will need to require the CSS file from this package (or provide your own). The example below shows how to include the CSS from this package if your build system supports requiring CSS files

import { MediaVideo } from 'sanity-plugin-media-video/renderer';

// IMPORTANT: require the CSS file from this package
// Recommended to us the provided CSS as well, but you can override it if you want.
// Refer to the table above for the CSS selectors.
import 'sanity-plugin-media-video/dist/sanity-plugin-media-video.css';

const MyComponent = (props) => {
  return (
    <MediaVideo
      className='my-custom-class-name'
      classNames={{
        rootCn: 'my-custom-root-container-class-name',
        containerCn: 'my-custom-container-class-name',
        imageContainerCn: 'my-custom-image-container-class-name',
        imageCn: 'my-custom-image-class-name',
        videoBackgroundCn: 'my-custom-video-background-class-name',
        inlineVideoBackgroundCn: 'my-custom-inline-video-background-class-name',
        videoCn: 'my-custom-video-class-name',
        dialogTriggerCn: 'my-custom-dialog-trigger-class-name',
        dialogContentCn: 'my-custom-dialog-content-class-name',
        dialogOverlayCn: 'my-custom-dialog-overlay-class-name',
        dialogCloseCn: 'my-custom-dialog-close-class-name',
        playBtnContainerCn: 'my-custom-play-button-container-class-name',
        playBtnCn: 'my-custom-play-button-class-name',
      }}
      videoUrl={videoUrl}
      imagePreview={imagePreview}
      isAutoPlay={isAutoPlay}
      isPipAutomatic={isPipAutomatic}
      videoType={videoType ?? 'link'}
      muxData={muxData}
    />
  );
};

Props

videoHookCallbacks object

Custom class names and its corresponding CSS selectors

CSS Selectors for Media Video Components

Use your own implementation

You can use your own implementation if you want since the the Media Video renderer is only an optional added feature in this plugin. Suggested way to do this is by leveraging react-player library to make it easier to render the video.

Optionally the plugin also provides some block components to help you build your own implementation if you want to. You can access them through the MediaVideoComponents object like so:

import { MediaVideoComponents } from 'sanity-plugin-media-video/renderer';

// Recommended to us the provided CSS as well, but you can override it if you want.
// Refer to the table above for the CSS selectors.
import 'sanity-plugin-media-video/dist/sanity-plugin-media-video.css';

const MyCustomComponent = (props) => {
  return (
    <MediaVideoComponents.MediaVideoRoot
      ref={ref}
      className={className}
      {...props}
    >
      <MediaVideoComponents.MediaVideoContainer>
        {/* Your own implementation */}
      </MediaVideoComponents.MediaVideoContainer>
    </MediaVideoComponents.MediaVideoRoot>
  );
};

Using the provided Hooks

You can also use the hooks provided by the plugin to help you build your own implementation:

import { MediaVideoComponents } from 'sanity-plugin-media-video/renderer';

import 'sanity-plugin-media-video/dist/sanity-plugin-media-video.css';

const MyCustomComponent = (props) => {
  const isDesktop = useMediaQuery('(min-width: 1024px)'); // Used to know if the screen is desktop or not
  const pipUniqueId = uuidv4();

  // Setup Intersection Observer to determine when the component is in view
  const intersectionObserver = useInView({
    rootMargin: '0px',
    threshold: [0, 0.5, 1],
  });
  const { ref: topLevelRef } = intersectionObserver;

  // Custom hook to manage video playback state and related events
  const {
    desktopPopoutPlay,
    inlinePlay,
    inlinePause,
    showImage,
    playedByAutoPlay,
    isPopoutOpen,
    isFloatingPip,
    setInlinePause,
    handleOnVideoProgress,
    handleClickPlay,
    handleVideoOnReady,
    handleInlineOnPlay,
    handleOnPipForceClose,
    setActivePip,
  } = useMediaVideoPlayback({
    /**
     * The following props are required for the hook to work
     * can refer to the implementation in the MediaVideo component
     * for more details
     */
    isAutoPlay,
    isPipAutomatic,
    intersectionObserver,
    pipUniqueId,
    isDesktop,
    playInPopout,
  });

  return {
    /* Your own implementation */
  };
};

🗃️ Data model

{
  _type: 'media';
  enableVideo: boolean;
  isAutoPlay: boolean;
  videoType: 'link' | 'mux';
  isPipAutomatic: boolean;
  videoUrl: string;
  muxVideo: {
    _type: 'mux.video';
    asset: {
      _ref: string;
      _type: 'reference';
      _weak: boolean;
    }
  }
  image: {
    _type: 'image';
    asset: {
      _type: 'reference';
      _ref: string;
    }
    altText: string;
    crop: {
      _type: 'sanity.imageCrop';
      bottom: number;
      left: number;
      right: number;
      top: number;
    }
    hotspot: {
      _type: 'sanity.imageHotspot';
      height: number;
      width: number;
      x: number;
      y: number;
    }
  }
}

🛢 GROQ Query

You can query the data model with this sample groq query

// Example for fetching data above
*[ _type == "exampleSchemaWithMedia" ] {
  myMediaField {
    image {
      asset->{
        _id,
        url,
        metadata {
          lqip
        }
      },
      crop,
      hotspot,
      altText
    },
    enableVideo,
    videoType,
    isAutoPlay,
    isPipAutomatic,
    videoUrl,
    muxVideo {
      _type,
      asset->{
        playbackId,
        assetId,
        filename,
        ...
      },
    },
  }
}

❓ FAQs

• How to add a new language?

  • You can refer to the 🌐 Localization section on how to override or add a new language

• Why the need to add an image field to the media object?

  • The image field is used to display a custom preview image of the video. This is useful for SSR performance and SEO purposes as it does not load the video itself directly when the page is rendered.
  • This also makes it possible to just be a Media Picture instead if you do not want to use the video feature. With that you can then render it however you want with the image data

📝 License

MIT © Evelan

🧪 Develop & test

This plugin uses @sanity/plugin-kit with default configuration for build & watch scripts.

See Testing a plugin in Sanity Studio on how to run this plugin with hotreload in the studio.

Release new version

Run "CI & Release" workflow. Make sure to select the main branch and check "Release new version".

Semantic release will only release on configured branches, so it is safe to run release on any branch.