fix: Renamed Encoding Tiers to Video Quality Levels (#437)

spuppo-mux · web-flow · commit 57d6c799fb5c · 2025-11-03T14:02:33.000+01:00
diff --git a/README.md b/README.md
@@ -122,7 +122,7 @@ For reference, here's an example `mux.videoAsset` document:
   thumbTime: 65.82,
   // Full Mux asset data:
   data: {
-    encoding_tier: 'smart',
+    video_quality: 'plus',
     max_resolution_tier: '1080p',
     aspect_ratio: '16:9',
     created_at: '1706645034',
@@ -228,25 +228,25 @@ export default defineConfig({
 
 When uploading new assets, editors can still choose a lower resolution for each video than configured globally. This option controls the maximum resolution encoded or processed for the uploaded video. The option is particularly important to manage costs when uploaded videos are higher than `1080p` resolution. More information on the feature is available on Mux's [docs](https://docs.mux.com/guides/stream-videos-in-4k). Also, read more on this feature announcement on Mux's [blog](https://www.mux.com/blog/more-pixels-fewer-problems-introducing-4k-support-for-mux-video).
 
-### Encoding tier (smart or baseline)
+### Video Quality Level (plus or basic)
 
-The [encoding tier](https://docs.mux.com/guides/use-encoding-tiers) informs the cost, quality, and available platform features for the asset. You can choose between `smart` and `baseline` at the plugin configuration. Defaults to `smart`.
+The [video quality level](https://docs.mux.com/guides/use-video-quality-levels) informs the cost, quality, and available platform features for the asset. You can choose between `plus` and `basic` at the plugin configuration. Defaults to `plus`.
 
 ```js
 import {muxInput} from 'sanity-plugin-mux-input'
 
 export default defineConfig({
-  plugins: [muxInput({encoding_tier: 'baseline'})],
+  plugins: [muxInput({video_quality: 'basic'})],
 })
 ```
 
-If `encoding_tier: 'smart'`, editors can still choose to use the `baseline` encoding tier on a per-video basis when uploading new assets.
+If `video_quality: 'plus'`, editors can still choose to use the `basic` video quality level on a per-video basis when uploading new assets.
 
-More information on the feature is available on Mux's [documentation](https://docs.mux.com/guides/use-encoding-tiers). Also, read more on the feature announcement on Mux's [blog](https://www.mux.com/blog/our-next-pricing-lever-baseline-on-demand-assets-with-free-video-encoding)
+More information on the feature is available on Mux's [documentation](https://www.mux.com/docs/guides/use-video-quality-levels). Also, read more on the feature announcement on Mux's [blog](https://www.mux.com/blog/our-next-pricing-lever-baseline-on-demand-assets-with-free-video-encoding)
 
 ### Auto-generated subtitles and captions
 
-If you've enabled smart encoding, you can use Mux's [auto-generated subtitles](https://docs.mux.com/guides/video/auto-generated-subtitles) feature. Unless you pass `disableTextTrackConfig: true` to the configuration, users will be able to choose a language to auto-generate subtitles for uploaded videos. Refer to Mux's documentation for the list of supported languages.
+If you are using 'plus' video quality level, you can use Mux's [auto-generated subtitles](https://docs.mux.com/guides/video/auto-generated-subtitles) feature. Unless you pass `disableTextTrackConfig: true` to the configuration, users will be able to choose a language to auto-generate subtitles for uploaded videos. Refer to Mux's documentation for the list of supported languages.
 
 You can also define a default language for the upload configuration form:
 
@@ -256,7 +256,7 @@ import {muxInput} from 'sanity-plugin-mux-input'
 export default defineConfig({
   plugins: [
     muxInput({
-      encoding_tier: 'smart',
+      video_quality: 'plus',
       defaultAutogeneratedSubtitleLang: 'en', // choose from one of the supported languages
     }),
   ],
diff --git a/example/sanity.config.ts b/example/sanity.config.ts
@@ -23,7 +23,7 @@ export default defineConfig({
     // https://www.sanity.io/docs/the-vision-plugin
     visionTool({defaultApiVersion: apiVersion}),
     muxInput({
-      encoding_tier: 'smart',
+      video_quality: 'plus',
       max_resolution_tier: '2160p',
       mp4_support: 'standard',
       defaultAutogeneratedSubtitleLang: 'en',
diff --git a/example/sanity.types.ts b/example/sanity.types.ts
@@ -207,7 +207,7 @@ export type MuxAssetData = {
   status?: string
   max_stored_resolution?: string
   passthrough?: string
-  encoding_tier?: string
+  video_quality?: string
   master_access?: string
   aspect_ratio?: string
   duration?: number
diff --git a/example/schema.json b/example/schema.json
@@ -1181,7 +1181,7 @@
           },
           "optional": true
         },
-        "encoding_tier": {
+        "video_quality": {
           "type": "objectAttribute",
           "value": {
             "type": "string"
diff --git a/sanity.config.ts b/sanity.config.ts
@@ -28,7 +28,7 @@ export default defineConfig({
   plugins: [
     structureTool(),
     muxInput({
-      encoding_tier: 'smart',
+      video_quality: 'plus',
       max_resolution_tier: '2160p',
       mp4_support: 'standard',
       defaultAutogeneratedSubtitleLang: 'en',
diff --git a/src/_exports/index.ts b/src/_exports/index.ts
@@ -8,7 +8,7 @@ export type {VideoAssetDocument} from '../util/types'
 
 export const defaultConfig: PluginConfig = {
   mp4_support: 'none',
-  encoding_tier: 'smart',
+  video_quality: 'plus',
   max_resolution_tier: '1080p',
   normalize_audio: false,
   defaultSigned: false,
@@ -17,6 +17,18 @@ export const defaultConfig: PluginConfig = {
 }
 
 export const muxInput = definePlugin<Partial<PluginConfig> | void>((userConfig) => {
+  // TODO: Remove this on next major version when we end support for encoding_tier
+  if (typeof userConfig === 'object' && 'encoding_tier' in userConfig) {
+    const deprecated_encoding_tier = userConfig.encoding_tier
+    if (!userConfig.video_quality) {
+      if (deprecated_encoding_tier === 'baseline') {
+        userConfig.video_quality = 'basic'
+      }
+      if (deprecated_encoding_tier === 'smart') {
+        userConfig.video_quality = 'plus'
+      }
+    }
+  }
   const config: PluginConfig = {...defaultConfig, ...(userConfig || {})}
   return {
     name: 'mux-input',
diff --git a/src/components/UploadConfiguration.tsx b/src/components/UploadConfiguration.tsx
@@ -23,18 +23,19 @@ import PlaybackPolicy from './uploadConfiguration/PlaybackPolicy'
 import type {StagedUpload} from './Uploader'
 
 export type UploadConfigurationStateAction =
-  | {action: 'encoding_tier'; value: UploadConfig['encoding_tier']}
+  | {action: 'video_quality'; value: UploadConfig['video_quality']}
   | {action: 'max_resolution_tier'; value: UploadConfig['max_resolution_tier']}
   | {action: 'mp4_support'; value: UploadConfig['mp4_support']}
   | {action: 'normalize_audio'; value: UploadConfig['normalize_audio']}
   | {action: 'signed_policy'; value: UploadConfig['signed_policy']}
   | {action: 'public_policy'; value: UploadConfig['public_policy']}
   | TrackAction
 
-const ENCODING_OPTIONS = [
-  {value: 'smart', label: 'Smart'},
-  {value: 'baseline', label: 'Baseline'},
-] as const satisfies {value: UploadConfig['encoding_tier']; label: string}[]
+const VIDEO_QUALITY_LEVELS = [
+  {value: 'basic', label: 'Basic'},
+  {value: 'plus', label: 'Plus'},
+  {value: 'premium', label: 'Premium'},
+] as const satisfies {value: UploadConfig['video_quality']; label: string}[]
 
 const RESOLUTION_TIERS = [
   {value: '1080p', label: '1080p'},
@@ -63,7 +64,7 @@ export default function UploadConfiguration({
 }) {
   const id = useId()
   const autoTextTracks = useRef<NonNullable<UploadConfig['text_tracks']>>(
-    pluginConfig.encoding_tier === 'smart' && pluginConfig.defaultAutogeneratedSubtitleLang
+    pluginConfig.video_quality === 'plus' && pluginConfig.defaultAutogeneratedSubtitleLang
       ? [
           {
             _id: uuid(),
@@ -78,21 +79,21 @@ export default function UploadConfiguration({
   const [config, dispatch] = useReducer(
     (prev: UploadConfig, action: UploadConfigurationStateAction) => {
       switch (action.action) {
-        case 'encoding_tier':
-          // If encoding tier switches to baseline, remove smart-only features
-          if (action.value === 'baseline') {
+        case 'video_quality':
+          // If video quality level switches to basic, remove plus-only features
+          if (action.value === 'basic') {
             return Object.assign({}, prev, {
-              encoding_tier: action.value,
+              video_quality: action.value,
               mp4_support: 'none',
               max_resolution_tier: '1080p',
               text_tracks: prev.text_tracks?.filter(({type}) => type !== 'autogenerated'),
               public_policy: true,
               signed_policy: false,
             })
-            // If encoding tier switches to smart, add back in default smart features
+            // If video quality level switches to plus, add back in default plus features
           }
           return Object.assign({}, prev, {
-            encoding_tier: action.value,
+            video_quality: action.value,
             mp4_support: pluginConfig.mp4_support,
             max_resolution_tier: pluginConfig.max_resolution_tier,
             text_tracks: [...autoTextTracks, ...(prev.text_tracks || [])],
@@ -138,7 +139,7 @@ export default function UploadConfiguration({
       }
     },
     {
-      encoding_tier: pluginConfig.encoding_tier,
+      video_quality: pluginConfig.video_quality,
       max_resolution_tier: pluginConfig.max_resolution_tier,
       mp4_support: pluginConfig.mp4_support,
       signed_policy: secrets.enableSignedUrls && pluginConfig.defaultSigned,
@@ -159,6 +160,7 @@ export default function UploadConfiguration({
   }, [])
   if (skipConfig) return null
 
+  const basicConfig = config.video_quality !== 'plus' && config.video_quality !== 'premium'
   const maxSupportedResolution = RESOLUTION_TIERS.findIndex(
     (rt) => rt.value === pluginConfig.max_resolution_tier
   )
@@ -198,11 +200,11 @@ export default function UploadConfiguration({
         {!disableUploadConfig && (
           <Stack space={3} paddingBottom={2}>
             <FormField
-              title="Encoding Tier"
+              title="Video Quality Level"
               description={
                 <>
-                  The encoding tier informs the cost, quality, and available platform features for
-                  the asset.{' '}
+                  The video quality level informs the cost, quality, and available platform features
+                  for the asset.{' '}
                   <a
                     href="https://docs.mux.com/guides/use-encoding-tiers"
                     target="_blank"
@@ -214,17 +216,17 @@ export default function UploadConfiguration({
               }
             >
               <Flex gap={3}>
-                {ENCODING_OPTIONS.map(({value, label}) => {
+                {VIDEO_QUALITY_LEVELS.map(({value, label}) => {
                   const inputId = `${id}--encodingtier-${value}`
                   return (
                     <Flex key={value} align="center" gap={2}>
                       <Radio
-                        checked={config.encoding_tier === value}
+                        checked={config.video_quality === value}
                         name="asset-encodingtier"
                         onChange={(e) =>
                           dispatch({
-                            action: 'encoding_tier' as const,
-                            value: e.currentTarget.value as UploadConfig['encoding_tier'],
+                            action: 'video_quality' as const,
+                            value: e.currentTarget.value as UploadConfig['video_quality'],
                           })
                         }
                         value={value}
@@ -239,7 +241,7 @@ export default function UploadConfiguration({
               </Flex>
             </FormField>
 
-            {config.encoding_tier === 'smart' && maxSupportedResolution > 0 && (
+            {!basicConfig && maxSupportedResolution > 0 && (
               <FormField
                 title="Resolution Tier"
                 description={
@@ -286,12 +288,12 @@ export default function UploadConfiguration({
               </FormField>
             )}
 
-            {config.encoding_tier === 'smart' && (
+            {!basicConfig && (
               <FormField title="Additional Configuration">
                 <Stack space={2}>
                   <PlaybackPolicy id={id} config={config} secrets={secrets} dispatch={dispatch} />
 
-                  {config.encoding_tier === 'smart' && (
+                  {!basicConfig && (
                     <Flex align="center" gap={2} padding={[0, 2]}>
                       <Checkbox
                         id={`${id}--mp4_support`}
@@ -319,7 +321,7 @@ export default function UploadConfiguration({
           </Stack>
         )}
 
-        {!disableTextTrackConfig && config.encoding_tier === 'smart' && (
+        {!disableTextTrackConfig && !basicConfig && (
           <TextTracksEditor
             tracks={config.text_tracks}
             dispatch={dispatch}
@@ -329,9 +331,7 @@ export default function UploadConfiguration({
 
         <Box marginTop={4}>
           <Button
-            disabled={
-              config.encoding_tier === 'smart' && !config.public_policy && !config.signed_policy
-            }
+            disabled={!basicConfig && !config.public_policy && !config.signed_policy}
             icon={UploadIcon}
             text="Upload"
             tone="positive"
@@ -388,7 +388,7 @@ function formatUploadConfig(config: UploadConfig): MuxNewAssetSettings {
     mp4_support: config.mp4_support,
     playback_policy: setPlaybackPolicy(config),
     max_resolution_tier: config.max_resolution_tier,
-    encoding_tier: config.encoding_tier,
+    video_quality: config.video_quality,
     normalize_audio: config.normalize_audio,
   }
 }
diff --git a/src/schema.ts b/src/schema.ts
@@ -98,6 +98,10 @@ const muxAssetData = {
       type: 'string',
       name: 'encoding_tier',
     },
+    {
+      type: 'string',
+      name: 'video_quality',
+    },
     {
       type: 'string',
       name: 'master_access',
diff --git a/src/util/types.ts b/src/util/types.ts
@@ -4,26 +4,35 @@ import type {PartialDeep} from 'type-fest'
 export interface MuxInputConfig {
   /**
    * Enable static renditions by setting this to 'standard'. Can be overwritten on a per-asset basis.
-   * Requires `"encoding_tier": "smart"`
+   * Requires `"video_quality": "plus"`
    * @see {@link https://docs.mux.com/guides/video/enable-static-mp4-renditions#why-enable-mp4-support}
    * @defaultValue 'none'
    */
   mp4_support: 'none' | 'standard'
 
   /**
    * Max resolution tier can be used to control the maximum resolution_tier your asset is encoded, stored, and streamed at.
-   * Requires `"encoding_tier": "smart"`
+   * Requires `"video_quality": "plus"`
    * @see {@link https://docs.mux.com/guides/stream-videos-in-4k}
    * @defaultValue '1080p'
    */
   max_resolution_tier: '2160p' | '1440p' | '1080p'
 
   /**
+   * @deprecated Use {@link video_quality}
+   * <br>
    * The encoding tier informs the cost, quality, and available platform features for the asset.
    * @see {@link https://docs.mux.com/guides/use-encoding-tiers}
    * @defaultValue 'smart'
    */
-  encoding_tier: 'baseline' | 'smart'
+  encoding_tier?: 'baseline' | 'smart'
+
+  /**
+   * The video quality level informs the cost, quality, and available platform features for the asset.
+   * @see {@link https://www.mux.com/docs/guides/use-video-quality-levels}
+   * @defaultValue 'plus'
+   */
+  video_quality: 'basic' | 'plus' | 'premium'
 
   /**
    * Normalize the audio track loudness level.
@@ -41,7 +50,7 @@ export interface MuxInputConfig {
 
   /**
    * Auto-generate captions for these languages by default.
-   * Requires `"encoding_tier": "smart"`
+   * Requires `"video_quality": "plus"`
    *
    * @see {@link https://docs.mux.com/guides/add-autogenerated-captions-and-use-transcripts}
    * @deprecated use `defaultAutogeneratedSubtitleLang` instead. Only a single autogenerated
@@ -50,7 +59,7 @@ export interface MuxInputConfig {
 
   /**
    * Auto-generate captions for this language by default. Users can still
-   * Requires `"encoding_tier": "smart"`
+   * Requires `"video_quality": "plus"`
    *
    * @see {@link https://docs.mux.com/guides/add-autogenerated-captions-and-use-transcripts}
    */
@@ -123,9 +132,10 @@ export const SUPPORTED_MUX_LANGUAGES = [
   {label: 'Bulgarian', code: 'bg', state: 'Beta'},
 ] as const
 
-export const ENCODING_TIERS = [
-  {label: 'Baseline', value: 'baseline'},
-  {label: 'Smart', value: 'smart'},
+export const VIDEO_QUALITY_LEVELS = [
+  {label: 'Basic', value: 'basic'},
+  {label: 'Plus', value: 'plus'},
+  {label: 'Premium', value: 'premium'},
 ] as const
 
 export const SUPPORTED_MUX_LANGUAGES_VALUES = SUPPORTED_MUX_LANGUAGES.map((l) => l.code)
@@ -168,7 +178,7 @@ export type UploadTextTrack = AutogeneratedTextTrack | CustomTextTrack
 export interface UploadConfig
   extends Pick<
     MuxInputConfig,
-    'encoding_tier' | 'max_resolution_tier' | 'mp4_support' | 'normalize_audio'
+    'max_resolution_tier' | 'mp4_support' | 'normalize_audio' | 'video_quality'
   > {
   text_tracks: UploadTextTrack[]
   signed_policy: boolean
@@ -182,7 +192,7 @@ export interface UploadConfig
 export interface MuxNewAssetSettings
   extends Pick<
     MuxInputConfig,
-    'encoding_tier' | 'max_resolution_tier' | 'mp4_support' | 'normalize_audio'
+    'max_resolution_tier' | 'mp4_support' | 'normalize_audio' | 'video_quality'
   > {
   /** An array of objects that each describe an input file to be used to create the asset.*/
   input?: {
