Skip to content

Latest commit

 

History

History
173 lines (121 loc) · 7.89 KB

README.md

File metadata and controls

173 lines (121 loc) · 7.89 KB
Raw

Mux Video Uploader

A Strapi plugin for managing uploads to Mux.

This plugin provides the ability to upload content via a url or a direct file upload to Mux.

🤩 Features

  • Upload videos using a url or a file to Mux from inside of Strapi
  • Manage assets with the plugin's asset grid and pagination capabilities
  • Search for assets using title or Mux Asset ID values
  • Preview content using a player (powered by the mux-player-react project)
  • Delete assets which result in the Mux Asset also being deleted
  • Support uploading audio files
  • Attachment of either sidecar subtitle files (supports .vtt or .srt files) or Mux's auto-generated captions
  • Enable Signed playback for protected video delivery
  • Support of Mux's video quality and maximum stream resolution
  • Enable MP4 downloads on assets during upload
  • Mux updates Strapi automatically when the asset is ready using Webhooks

🧑‍💻 Install

For installing with Strapi v5, install the latest—

npm i strapi-plugin-mux-video-uploader@latest

yarn add strapi-plugin-mux-video-uploader@latest

For installing with Strapi v4, install v2.0.0—

npm i [email protected]

yarn add [email protected]

🖐 Requirements

  • A Mux account
  • You will need both the Access Token and Secret Key scoped with "Full Access" permissions which can be created in the Mux Dashboard
  • (Optional) If you plan to support Signed video playback, you will need to obtain a Signing key set
  • The Webhook Signing Secret which can be created in the Mux Dashboard (See the Webhooks section for more info)
  • Tested with Strapi v5.0.6 Community Edition

⚙️ Configuration

In order for this plugin to communicate with Mux, some configuration values need to be set for the plugin before it can be used.

Starting in v3.0.0 of this plugin, we have switch to Strapi's File Based Config. To increase the portability of clustered deployments, we have switched to this paradigm to manage app configs. This means that setting the configurations using the Settings view in the Strapi Admin UI will no longer be available.

In migrating to v3.0.0, you will need to transition to the Strapi File Based Config and copy the values that you had used to initially set up your plugin—

Typescript - Plugin Config

// Path: ./config/plugins.ts
export default ({env}) => ({
  // ...
  "mux-video-uploader": {
    enabled: true,
    config: {
      accessTokenId: env('ACCESS_TOKEN_ID'),
      secretKey: env('ACCESS_TOKEN_SECRET'),
      webhookSigningSecret: env('WEBHOOK_SIGNING_SECRET'),
      playbackSigningId: env('SIGNING_KEY_ID'),
      playbackSigningSecret: env('SIGNING_KEY_PRIVATE_KEY'),
    }
  }
  // ...
});

Javascript - Plugin Config

// Path: ./config/plugins.js
module.exports = ({env}) => ({
  // ...
  "mux-video-uploader": {
    enabled: true,
    config: {
      accessTokenId: env('ACCESS_TOKEN_ID'),
      secretKey: env('ACCESS_TOKEN_SECRET'),
      webhookSigningSecret: env('WEBHOOK_SIGNING_SECRET'),
      playbackSigningId: env('SIGNING_KEY_ID'),
      playbackSigningSecret: env('SIGNING_KEY_PRIVATE_KEY'),
    }
  }
  // ...
});

🪝 Webhooks

Please note: We've currently disabled webhook signature verification as there is not a way to access the raw request body from the Koa.js middleware (which Strapi is using for parsing requests). This is needed to ensure that we are verifying the signature and that the request JSON payload has properties in the same order that was used for generating the signature.

When setting up your Webhook configuration in the Mux Dashboard, the "URL to notify" field should be in the format of—

{STRAPI_BASE_URL}/mux-video-uploader/webhook-handler

Where {STRAPI_BASE_URL} is the publicly accessible hostname of your Strapi instance.

🧑‍⚖️ Permissions

Currently, anyone with "Super Admin" access to your Strapi instance will be able to utilize the plugin for uploading and managing content within the Strapi CE version. More sophisticated permissions can be defined for Strapi Enterprise users using RBAC.

Please note: End Users can only have read operation permissions (find, findOne and count). Write operations are not supported due to potential security reasons.

🤝 Contributing

Contributions, issues and feature requests are welcome!

Developers for this plugin should take a look at the README_INTERNAL.md document for details on setting up dev environments.

If you encounter an error or have questions, please feel free to file inquiries on the Issues page for strapi-plugin-mux-video-uploader.

🗣 FAQ

My Strapi instance is not publicly available, can I still use Webhooks?

Yes! However, in order to make it work, you'll need a "Webhook Relay" that runs from within your network. You can use a Webhook Relay service like Smee (https://smee.io/) or ngrok (https://ngrok.com/) to forward Webhook events to an instance of Strapi behind a firewall.

I've installed the plugin, but the Strapi Admin UI doesn't show it

This happens when you need to rebuild your Strapi instance. To do this, you need delete the .cache, .strapi, and build folders (while Strapi is off) and restart to rebuild the instance.

Here is an example of how to do this on a unix-based operating system from within the Strapi application root—

rm -rf ./.cache ./build ./.strapi

Custom subtitles and captions aren't working

When uploading a video with custom text tracks, Mux asks for an URL pointing to these files. This feature currently works only on deployed Strapi installations.

When developing locally with Strapi, we don't have a globally reachable URL. Unlike webhooks with which we can use a local webhook proxy (e.g. Smee.io or ngrok), the plugin currently offers no way to configure a base URL to receive Mux's caption download requests. You'll still be able to upload videos, but the tracks won't be properly parsed by Mux.

Another approach would be to use tunnel service such as Cloudflare ZeroTrust or Tailscale to route requests against a publicly accessible hostname to your local instance. If you go this route, you will need to ensure that you configure Strapi to use the hostname when generating the Mux's caption download requests. Here is an example of how to do that—

Typescript - Server Config

// Path: ./config/server.ts
export default ({ env }) => ({
  // ... Existing properties set by Strapi
  url: env('PUBLIC_URL', 'https://your_host.domain.tld'),
});

Javascript - Server Config

// Path: ./config/server.js
module.exports = ({ env }) => ({
  // ... Existing properties set by Strapi
  url: env('PUBLIC_URL', 'https://your_host.domain.tld'),
});

❤️ Thanks

Strapi.io

📚 References