fix(amf): default AMD encoding to FFmpeg

Native AMF has limited device and driver coverage, while the FFmpeg path remains the broadly supported implementation. Make FFmpeg the automatic AMD choice and expose native AMF only as an explicit experimental option.

Use unambiguous encoder names across both UIs and preserve the old names as hidden aliases that retain their previous implementation semantics.

Generated with [Codex](https://openai.com/codex/)

Model: GPT 5.6-Sol High

Author: Nonary

docs/configuration.md

@@ -912,7 +912,7 @@ editing the `conf` file in a text editor. Use the examples as reference.
             <br>
             **FreeBSD/Linux + VA-API:**
             <br>
-            Unlike with *amdvce* and *nvenc*, it doesn't matter if video encoding is done on a different GPU.
+            Unlike with AMD AMF encoders and *nvenc*, it doesn't matter if video encoding is done on a different GPU.
             @code{}
             ls /dev/dri/renderD*  # to find all devices capable of VAAPI
             # replace ``renderD129`` with the device from above to list the name and capabilities of the device
@@ -2662,13 +2662,19 @@ editing the `conf` file in a text editor. Use the examples as reference.
         <td>For Intel graphics cards</td>
     </tr>
     <tr>
-        <td>amdvce</td>
-        <td>For AMD graphics cards (native AMF encoder)</td>
+        <td>amdvce_ffmpeg</td>
+        <td>For AMD graphics cards. This is the supported FFmpeg-based AMF encoder and the
+            implementation used by automatic selection on Windows.
+            @note{Existing configurations using @code{}amdvce_legacy@endcode are accepted as
+            a compatibility alias for @code{}amdvce_ffmpeg@endcode. The former native
+            @code{}amdvce@endcode value is accepted as an alias for
+            @code{}amdvce_experimental@endcode.}</td>
     </tr>
     <tr>
-        <td>amdvce_legacy</td>
-        <td>Explicit rollback to the FFmpeg-based AMD AMF encoder. Never selected automatically —
-            automatic probing and `amdvce` fail closed instead of silently falling back.
+        <td>amdvce_experimental</td>
+        <td>Experimental native AMD AMF encoder. It is not selected automatically, has limited
+            hardware test coverage, and may not work with older GPUs or driver versions. Explicit
+            selection fails closed instead of silently changing encoder implementations.
             @note{Applies to Windows only.}</td>
     </tr>
     <tr>
@@ -3356,9 +3362,9 @@ They appear in the Frame Limiter section of the settings UI.
 or newer, which reports AMF 1.4.32. FFmpeg refuses 10-bit P010 surfaces on any older runtime, so HDR
 is not offered to clients even though Sunshine's own AMF check only needs 1.4.23. Update your
 graphics drivers if HDR is unavailable on an AMD GPU. This limitation applies to the
-@code{amdvce_legacy} rollback encoder only; the native @code{amdvce} encoder talks to AMF directly
-and is not subject to FFmpeg's 10-bit refusal. Sunshine carries one narrow exception for the legacy
-encoder: on a Radeon Pro 5500 XT (PCI @code{1002:7340}) running AMF 1.4.31.x, it presents 1.4.32 to
+@code{amdvce_ffmpeg} encoder only; the experimental native @code{amdvce_experimental} encoder talks to AMF
+directly and is not subject to FFmpeg's 10-bit refusal. Sunshine carries one narrow exception for the
+FFmpeg-based encoder: on a Radeon Pro 5500 XT (PCI @code{1002:7340}) running AMF 1.4.31.x, it presents 1.4.32 to
 FFmpeg for the duration of codec validation so HEVC Main10 is not refused. The exception is applied
 automatically, has no configuration option, and does not apply to any other adapter. The detected AMF
 runtime version is written to the log on every AMD HDR HEVC attempt (search for
@@ -3371,7 +3377,7 @@ runtime version is written to the log on every AMD HDR HEVC attempt (search for
         <td>Description</td>
         <td colspan="2">
             The encoder usage profile is used to set the base set of encoding parameters.
-            @note{This option only applies when using amdvce [encoder](#encoder).}
+            @note{This option applies to the AMD [encoders](#encoder).}
             @note{The other AMF options that follow will override a subset of the settings applied by your usage
             profile, but there are hidden parameters set in usage profiles that cannot be overridden elsewhere.}
         </td>
@@ -3418,7 +3424,7 @@ runtime version is written to the log on every AMD HDR HEVC attempt (search for
         <td>Description</td>
         <td colspan="2">
             The encoder rate control.
-            @note{This option only applies when using amdvce [encoder](#encoder).}
+            @note{This option applies to the AMD [encoders](#encoder).}
             @warning{The `vbr_latency` option generally works best, but some bitrate overshoots may still occur.
             Enabling HRD allows all bitrate based rate controls to better constrain peak bitrate, but may result in
             encoding artifacts depending on your card.}
@@ -3475,7 +3481,7 @@ runtime version is written to the log on every AMD HDR HEVC attempt (search for
         <td colspan="2">
             The target quality level used by the `qvbr` rate control method, where 1 is the lowest quality and 51
             is the highest. Higher values spend more bits to preserve quality.
-            @note{This option only applies to AMD [encoders](#encoder) with `amd_rc` set to `qvbr`. Native `amdvce` automatically enables PreAnalysis with a one-frame low-latency lookahead for `qvbr`, `hqvbr`, and `hqcbr`.}
+            @note{This option only applies to AMD [encoders](#encoder) with `amd_rc` set to `qvbr`. Native `amdvce_experimental` automatically enables PreAnalysis with a one-frame low-latency lookahead for `qvbr`, `hqvbr`, and `hqcbr`.}
             @note{Leave this at `0` to keep the encoder default.}
         </td>
     </tr>
@@ -3504,7 +3510,7 @@ runtime version is written to the log on every AMD HDR HEVC attempt (search for
         <td>Description</td>
         <td colspan="2">
             Enable Hypothetical Reference Decoder (HRD) enforcement to help constrain the target bitrate.
-            @note{This option only applies when using amdvce [encoder](#encoder).}
+            @note{This option applies to the AMD [encoders](#encoder).}
             @warning{HRD is known to cause encoding artifacts or negatively affect encoding quality on certain cards.}
         </td>
     </tr>
@@ -3530,7 +3536,7 @@ runtime version is written to the log on every AMD HDR HEVC attempt (search for
         <td colspan="2">
             The quality profile controls the tradeoff between speed and quality of encoding.
             `auto` leaves the quality property unset so the selected AMF usage preset can choose it.
-            @note{This option only applies when using amdvce [encoder](#encoder).}
+            @note{This option applies to the AMD [encoders](#encoder).}
         </td>
     </tr>
     <tr>
@@ -3570,9 +3576,9 @@ runtime version is written to the log on every AMD HDR HEVC attempt (search for
     <tr>
         <td>Description</td>
         <td colspan="2">
-            Preanalysis can increase encoding quality at the cost of latency. Native `amdvce` uses a one-frame
+            Preanalysis can increase encoding quality at the cost of latency. Native `amdvce_experimental` uses a one-frame
             low-latency lookahead; it is enabled automatically by `qvbr`, `hqvbr`, and `hqcbr`. The setting is
-            also forwarded to `amdvce_legacy`.
+            also forwarded to `amdvce_ffmpeg`.
         </td>
     </tr>
     <tr>
@@ -3599,7 +3605,7 @@ runtime version is written to the log on every AMD HDR HEVC attempt (search for
             allocation of more bits to smooth areas compared to more textured areas.
             `auto` leaves the property unset so the selected AMF usage preset can choose it. VBAQ is enabled
             by default.
-            @note{This option only applies when using amdvce [encoder](#encoder).}
+            @note{This option applies to the AMD [encoders](#encoder).}
         </td>
     </tr>
     <tr>
@@ -3636,8 +3642,7 @@ runtime version is written to the log on every AMD HDR HEVC attempt (search for
         <td>Description</td>
         <td colspan="2">
             The entropy encoding to use.
-            @note{This option only applies when using H.264 with the amdvce
-            [encoder](#encoder).}
+            @note{This option only applies when using H.264 with an AMD [encoder](#encoder).}
         </td>
     </tr>
     <tr>
@@ -3675,7 +3680,7 @@ runtime version is written to the log on every AMD HDR HEVC attempt (search for
         <td colspan="2">
             Enable AV1 screen-content coding tools, which can improve efficiency and text/UI clarity for desktop and
             screen-heavy content.
-            @note{AV1 only. This option only applies to the native amdvce [encoder](#encoder) (not amdvce_legacy).}
+            @note{AV1 only. This option only applies to the native amdvce_experimental [encoder](#encoder) (not amdvce_ffmpeg).}
             @note{Leave at `auto` to use the driver default.}
         </td>
     </tr>
@@ -3713,7 +3718,7 @@ runtime version is written to the log on every AMD HDR HEVC attempt (search for
         <td>Description</td>
         <td colspan="2">
             AV1 encoding-latency tier. Lower tiers finish each frame faster at the cost of higher power draw.
-            @note{AV1 only. This option only applies to the native amdvce [encoder](#encoder) (not amdvce_legacy).}
+            @note{AV1 only. This option only applies to the native amdvce_experimental [encoder](#encoder) (not amdvce_ffmpeg).}
             @note{Leave at `auto` to use the driver default.}
         </td>
     </tr>
@@ -4202,23 +4207,23 @@ playnite_exclude_categories = ["Steam", {"id": "deck", "name": "Steam Deck"}]
 
 ### amd_ltr_frames
 
-Sets the number of long-term reference frames used by the native AMD encoder. Leave this at the automatic default unless a client or driver-specific recovery workflow requires a fixed value.
+Sets the number of long-term reference frames used by the experimental native AMD encoder. Leave this at the automatic default unless a client or driver-specific recovery workflow requires a fixed value.
 
 ### amd_input_queue_size
 
-Sets the native AMD encoder input queue depth. A positive explicit value overrides automatic low-latency queue selection.
+Sets the experimental native AMD encoder input queue depth. A positive explicit value overrides automatic low-latency queue selection.
 
 ### amd_smart_access_video
 
-Controls AMD SmartAccess Video when the installed AMF runtime exposes that capability. Use `auto` to leave the driver default unchanged.
+Controls SmartAccess Video for the experimental native AMD encoder when the installed AMF runtime exposes that capability. Use `auto` to leave the driver default unchanged.
 
 ### amd_lowlatency_mode
 
-Controls AMD's native encoder low-latency mode. Use `auto` to leave the driver default unchanged.
+Controls the experimental native AMD encoder's low-latency mode. Use `auto` to leave the driver default unchanged.
 
 ### amd_high_motion_quality_boost
 
-Controls AMD's high-motion quality boost. Use `auto` to leave the driver default unchanged.
+Controls high-motion quality boost for the experimental native AMD encoder. Use `auto` to leave the driver default unchanged.
 
 ### dd_paused_virtual_display_timeout_secs
 

src/amf/amf_lifecycle.h

@@ -227,18 +227,30 @@ namespace amf::lifecycle {
   };
 
   struct encoder_selection_policy_t {
-    bool include_legacy = false;
+    bool include_experimental = false;
     bool fail_closed = false;
   };
 
+  inline constexpr std::string_view canonical_encoder_name(
+    std::string_view requested_encoder) noexcept {
+    if (requested_encoder == "amdvce_legacy") {
+      return "amdvce_ffmpeg";
+    }
+    if (requested_encoder == "amdvce") {
+      return "amdvce_experimental";
+    }
+    return requested_encoder;
+  }
+
   inline constexpr encoder_selection_policy_t encoder_selection_policy(
     std::string_view requested_encoder) noexcept {
-    // Native AMF and the FFmpeg AMF implementation are separate, explicit
-    // contracts. Automatic probing must never make a native feature/property
-    // failure look successful by selecting the legacy encoder behind the user.
+    // The FFmpeg AMF implementation is the supported default. The native AMF
+    // implementation has limited hardware coverage and is only considered when
+    // the user explicitly opts into the experimental encoder.
+    const auto canonical_encoder = canonical_encoder_name(requested_encoder);
     return {
-      requested_encoder == "amdvce_legacy",
-      requested_encoder == "amdvce",
+      canonical_encoder == "amdvce_experimental",
+      canonical_encoder == "amdvce_experimental",
     };
   }
 

src/config.cpp

@@ -33,6 +33,7 @@
 #include <nlohmann/json.hpp>
 
 // local includes
+#include "amf/amf_lifecycle.h"
 #include "config.h"
 #include "config_key.h"
 #include "config_playnite.h"
@@ -1714,7 +1715,7 @@ namespace config {
     int_f(vars, "amd_vbaq", video.amd.amd_vbaq, amd::tristate_from_view);
     bool_f(vars, "amd_enforce_hrd", (bool &) video.amd.amd_enforce_hrd);
 
-    // Native AMF encoder (amdvce) tuning knobs.
+    // Native AMF encoder (amdvce_experimental) tuning knobs.
     int_f(vars, "amd_ltr_frames", video.amd.amd_ltr_frames);
     if (video.amd.amd_ltr_frames < 0 || video.amd.amd_ltr_frames > 2) {
       BOOST_LOG(warning) << "config: amd_ltr_frames must be between 0 and 2, clamping: "sv << video.amd.amd_ltr_frames;
@@ -1755,6 +1756,12 @@ namespace config {
     string_f(vars, "capture", video.capture);
     bool_f(vars, "wgc_pacing_smoothing", video.wgc_pacing_smoothing);
     string_f(vars, "encoder", video.encoder);
+    const auto configured_encoder = video.encoder;
+    video.encoder = std::string(amf::lifecycle::canonical_encoder_name(video.encoder));
+    if (video.encoder != configured_encoder) {
+      BOOST_LOG(info) << "config: encoder = " << configured_encoder
+                      << " is deprecated; using " << video.encoder << '.';
+    }
     string_f(vars, "adapter_name", video.adapter_name);
     string_f(vars, "adapter_pnp_id", video.adapter_pnp_id);
     if (!video.adapter_pnp_id.empty() && video.adapter_name.empty()) {
@@ -2832,7 +2839,10 @@ namespace config {
       if (name == adapter_pnp_id_key) {
         continue;
       }
-      base.insert_or_assign(name, value);
+      base.insert_or_assign(
+        name,
+        name == "encoder" ? std::string(amf::lifecycle::canonical_encoder_name(value)) : value
+      );
     }
 
     const auto adapter_name = overrides.find(std::string(adapter_name_key));
@@ -3077,6 +3087,9 @@ namespace config {
       if (!is_valid_override_key(normalized_key) || !is_allowed_override_key(normalized_key)) {
         continue;
       }
+      if (normalized_key == "encoder") {
+        v = std::string(amf::lifecycle::canonical_encoder_name(v));
+      }
       filtered.emplace(std::move(normalized_key), std::move(v));
     }
 

src/config.h

@@ -96,7 +96,7 @@ namespace config {
       std::optional<int> amd_preanalysis;
       std::optional<int> amd_vbaq;  // nullopt = follow usage-preset default
       int amd_coder;
-      // Native AMF encoder (amdvce) tuning knobs.
+      // Native AMF encoder (amdvce_experimental) tuning knobs.
       int amd_ltr_frames;  // Long-term reference frames for RFI (0 = off)
       int amd_input_queue_size;  // AMF input queue depth (0 = driver default)
       // Curated tri-state native-AMF feature knobs. nullopt (auto) leaves the

src/platform/windows/display_vram.cpp

@@ -2221,7 +2221,7 @@ namespace platf::dxgi {
                       << " bitrate=" << client_config.bitrate << "kbps (active=" << active_encoder_count << ')';
 
       // AMF SDK integer values are passed straight through from the existing
-      // amd_* config (shared with the FFmpeg amdvce_legacy path).
+      // amd_* config (shared with the FFmpeg amdvce_ffmpeg path).
       if (client_config.videoFormat == 0) {
         amf_cfg.usage = config::video.amd.amd_usage_h264;
         amf_cfg.quality_preset = config::video.amd.amd_quality_h264;