Windows Setup

🪟 Windows Setup & Identity

This guide explains how to properly configure your Flutter application on Windows so that it is correctly identified by the system media center (SMTC) and doesn't appear as "Unknown Application".

---

🧐 The Challenge

Windows identifies applications primarily through their App User Model ID (AUMID). If an application doesn't have an AUMID, the Windows Media Session Manager cannot associate the media controls with your app, leading it to display "Unknown Application".

---

🛠️ Solutions

1. MSIX Packaging (Recommended)

The most robust way to ensure your application is correctly identified is to package it as an MSIX package. When an app is installed via MSIX, Windows automatically assigns it an AUMID based on the package information.

We recommend using the msix package for Flutter:

1. Add msix to your dev_dependencies:

   dev_dependencies:
     msix: ^3.16.1

2. Configure your app info in pubspec.yaml:

   msix_config:
     display_name: My Awesome App
     publisher_display_name: My Company
     # ... other config

3. Build and package:

   flutter build windows
   dart run msix:create

2. Dynamic Start Menu Shortcut (For Unpackaged Apps)

If you are distributing your application as a portable ZIP (unpackaged) or testing via flutter run, you must explicitly set the AppUserModelID at runtime. The plugin provides a convenient method to set the AUMID and optionally register a display name (which creates a temporary Start Menu shortcut):

if (Platform.isWindows) {
  // Call this as early as possible in your main()
  await FlutterMediaSession().setWindowsAppUserModelId(
    'YourCompany.YourApp.Id',
    // ⚠️ ONLY provide displayName if your app is portable/unpackaged.
    displayName: 'My Awesome App', 
  );
}

Warning

Best Practice for Installers: You should always omit displayName if you are using a custom installer (like Inno Setup), as those tools already handle shortcut creation.

3. Custom Installers (Inno Setup, WiX, etc.)

If you are using a custom installer to distribute your application, you must configure your installer to embed the AppUserModelID directly into the Start Menu shortcut it creates.

Example: Inno Setup In your .iss script, add the AppUserModelID parameter to your shortcut in the [Icons] section:

[Icons]
Name: "{autoprograms}\{#MyAppName}"; Filename: "{app}\{#MyAppExeName}"; AppUserModelID: "YourCompany.YourApp.Id"

---

✅ Verifying the Setup

1. Start your application.
2. Play some media and activate the media session.
3. Open the system media controls (volume flyout or Win+G).
4. Verify that your application's name and icon are correctly displayed.