VitePress

Mux Plugin Settings Documentation ​

Plugin Settings ​

Basic Configuration ​

Plugin Name ​

  • Setting: pluginName
  • Type: String
  • Default: 'MUX'
  • Description: The public-facing name of the plugin that appears in the Craft CMS control panel
  • Environment Variable: MUX_PLUGIN_NAME

MUX Token ID ​

  • Setting: muxTokenId
  • Type: String
  • Default: '' (empty)
  • Description: Mux Token ID generated in your Mux account. This is required for API authentication with Mux services.
  • Environment Variable: MUX_TOKEN_ID
  • Required: Yes

MUX Token Secret ​

  • Setting: muxTokenSecret
  • Type: String
  • Default: '' (empty)
  • Description: MUX Token Secret generated in your Mux account. This is required for API authentication with Mux services.
  • Environment Variable: MUX_TOKEN_SECRET
  • Required: Yes

Video Processing Settings ​

Max Resolution Tier ​

  • Setting: maxResolutionTier
  • Type: String (Select)
  • Default: '1080p'
  • Options:
    • '2160p' - 4K resolution
    • '1440p' - 2K resolution
    • '1080p' - Full HD (default)
    • '720p' - HD resolution
  • Description: Controls the maximum resolution tier your video assets are encoded, stored, and streamed at. Higher resolutions provide better quality but require more bandwidth and storage.
  • Environment Variable: MUX_MAX_RESOLUTION_TIER

MP4 Support Depreciated ​

  • Setting: mp4Support
  • Type: String (Select)
  • Default: 'none'
  • Options:
    • 'none' - No MP4 renditions
    • 'capped-1080p' - Capped at 1080p resolution
    • 'audio-only' - Audio-only renditions
    • 'capped-1080p,audio-only' - Both capped 1080p and audio-only
  • Description: Enable static MP4 renditions on your video assets for offline viewing and other use cases. Note: This feature is deprecated. Use Static Renditions instead. This must be set to none to use static renditions.
  • Environment Variable: MUX_MP4_SUPPORT
  • Documentation: Mux MP4 Renditions Guide

Static Renditions ​

  • Setting: staticRenditions
  • Type: String (Select)
  • Default: 'none'
  • Options:
    • 'none' - No static renditions
    • 'highest' - Highest quality static rendition
    • 'audio-only' - Audio-only static rendition
  • Description: Enable static renditions on your video assets for offline viewing and other use cases. Set MP4 Support to "None" to use Static Renditions.
  • Environment Variable: MUX_STATIC_RENDITIONS
  • Documentation: Mux Static Renditions Guide

Security Settings ​

Secure Playback ​

  • Setting: muxSecurePlayback
  • Type: Boolean
  • Default: false
  • Description: Enable secure video playback using JWT tokens. When enabled, videos require signed keys in the playback URL for access. This provides additional security for your video content.
  • Environment Variable: MUX_SECURE_PLAYBACK
  • Documentation: Mux Secure Video Playback Guide

Watermark/Overlay Settings ​

Watermark URL ​

  • Setting: watermark_url
  • Type: String
  • Default: '' (empty)
  • Description: URL of the watermark/overlay image to be applied to videos. Valid file types are .png and .jpg. Other formats like .gif, .webp, and .svg are not supported.
  • Environment Variable: MUX_WATERMARK_URL

Vertical Alignment ​

  • Setting: vertical_align
  • Type: String (Select)
  • Default: 'top'
  • Options:
    • 'top' - Align to top of video
    • 'center' - Center vertically
    • 'bottom' - Align to bottom of video
  • Description: Where the vertical positioning of the overlay/watermark should begin from.
  • Environment Variable: MUX_VERTICAL_ALIGN

Vertical Margin ​

  • Setting: vertical_margin
  • Type: String
  • Default: '0'
  • Description: The distance from the vertical alignment starting point and the image's closest edge. Can be expressed as a percentage (e.g., 10%) or as a pixel value (e.g., 100px). Negative values will move the overlay offscreen. For 'center' alignment, positive values shift toward bottom, negative toward top.
  • Environment Variable: MUX_VERTICAL_MARGIN

Horizontal Alignment ​

  • Setting: horizontal_align
  • Type: String (Select)
  • Default: 'left'
  • Options:
    • 'left' - Align to left side of video
    • 'middle' - Center horizontally
    • 'right' - Align to right side of video
  • Description: Where the horizontal positioning of the overlay/watermark should begin from.
  • Environment Variable: MUX_HORIZONTAL_ALIGN

Horizontal Margin ​

  • Setting: horizontal_margin
  • Type: String
  • Default: '0'
  • Description: The distance from the horizontal alignment starting point and the image's closest edge. Can be expressed as a percentage (e.g., 10%) or as a pixel value (e.g., 100px). Negative values will move the overlay offscreen. For 'center' alignment, positive values shift toward right, negative toward left.
  • Environment Variable: MUX_HORIZONTAL_MARGIN

Width ​

  • Setting: width
  • Type: String
  • Default: '' (empty)
  • Description: How wide the overlay should appear. Can be expressed as a percentage (e.g., 10%) or as a pixel value (e.g., 100px). If both width and height are left blank, the width will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If height is supplied with no width, the width will scale proportionally to the height.
  • Environment Variable: MUX_WIDTH

Height ​

  • Setting: height
  • Type: String
  • Default: '' (empty)
  • Description: How tall the overlay should appear. Can be expressed as a percentage (e.g., 10%) or as a pixel value (e.g., 100px). If both width and height are left blank, the height will be the true pixels of the image, applied as if the video has been scaled to fit a 1920x1080 frame. If width is supplied with no height, the height will scale proportionally to the width.
  • Environment Variable: MUX_HEIGHT

Opacity ​

  • Setting: opacity
  • Type: String
  • Default: '100'
  • Description: How opaque the overlay should appear, expressed as a percentage. 100% is fully opaque, 0% is fully transparent.
  • Environment Variable: MUX_OPACITY

Webhook Configuration ​

Webhook URL ​

  • Setting: muxWebhookUrl
  • Type: String (Read-only)
  • Value: {siteUrl}actions/mux/webhooks/mux-webhooks
  • Description: The webhook URL that Mux will use to send real-time updates to your Craft CMS installation. This URL is automatically generated and should be configured in your Mux account settings.
  • Documentation: Mux Webhooks Guide

Field Settings ​

Mux Asset Field Configuration ​

Allow Uploads ​

  • Setting: allowUploads
  • Type: Boolean
  • Default: true
  • Description: Whether authors should be able to upload videos directly to the field, rather than requiring them to select/upload assets via the selection modal.

Default Upload Location ​

  • Setting: defaultUploadLocationSource and defaultUploadLocationSubpath
  • Type: String
  • Description: Where assets should be stored when they are uploaded directly to the field. You can specify both the source (volume) and subpath.

Restrict Location ​

  • Setting: restrictLocation
  • Type: Boolean
  • Default: false
  • Description: Whether assets should be restricted to a single location.

Restricted Location Source ​

  • Setting: restrictedLocationSource
  • Type: String
  • Description: The source key where assets can be selected from, if assets are restricted.

Restricted Location Subpath ​

  • Setting: restrictedLocationSubpath
  • Type: String
  • Description: The subpath where assets can be selected from, if assets are restricted.

Allow Subfolders ​

  • Setting: allowSubfolders
  • Type: Boolean
  • Default: false
  • Description: Whether assets can be selected from subfolders, if assets are restricted.

Restricted Default Upload Subpath ​

  • Setting: restrictedDefaultUploadSubpath
  • Type: String
  • Description: The subpath where assets should be uploaded to by default, if assets are restricted and subfolders are allowed.

Environment Variables ​

All settings can be configured using environment variables. The plugin uses Craft's EnvAttributeParserBehavior to automatically parse environment variables. Use the following format in your .env file:

shell
# Basic Configuration
MUX_PLUGIN_NAME="MUX"
MUX_TOKEN_ID="your_token_id_here"
MUX_TOKEN_SECRET="your_token_secret_here"

# Video Processing
MUX_MAX_RESOLUTION_TIER="1080p"
MUX_MP4_SUPPORT="none"
MUX_STATIC_RENDITIONS="none"

# Security
MUX_SECURE_PLAYBACK=false

# Watermark Settings
MUX_WATERMARK_URL=""
MUX_VERTICAL_ALIGN="top"
MUX_VERTICAL_MARGIN="0"
MUX_HORIZONTAL_ALIGN="left"
MUX_HORIZONTAL_MARGIN="0"
MUX_WIDTH=""
MUX_HEIGHT=""
MUX_OPACITY="100"

# Upload Settings
MUX_MAX_UPLOAD_FILESIZE="734003200"
# Must be multiples of 256kb
MUX_UPLOAD_CHUNK_SIZE="8388608"

Config File ​

Add config file mux.php to Craft config folder to override values.

TIP

Always reference the Environment Variable for muxTokenId and muxTokenSecretso it is not stored in repository compromising those values.

php
<?php

use craft\helpers\App;

return [
    'pluginName' => 'MUX',
    'muxTokenId' => App::env('MUX_TOKEN_ID'),
    'muxTokenSecret' => App::env('MUX_TOKEN_SECRET'),
    'maxResolutionTier' => '1080p',
    'staticRenditions' => 'highest',
    'muxSecurePlayback' => true,
    'watermark_url' => 'https://example.com/watermark.png',
    'vertical_align' => 'bottom',
    'vertical_margin' => '10px',
    'horizontal_align' => 'right',
    'horizontal_margin' => '10px',
    'width' => '200px',
    'height' => '100px',
    'opacity' => '80',
    'maxUploadFileSize' => '1048576', // 1GB in kB
    'uploadChunkSize' => '8192', // 8MB
    'defaultGeneratedSubtitleLanguage' => 'en',
];