Managed Settings

Quick start with Group Policy#

1. Download TypeWhisper-win-PolicyTemplates.zip from the release you deploy and copy the ADMX and ADML files to the Central Store.
2. In the Group Policy Management Editor, open Computer Configuration > Administrative Templates > TypeWhisper and configure the settings you need, such as “Allow cloud transcription” or “Application update mode”.
3. Run gpupdate /target:computer on a test device and check Settings > Advanced > Managed settings in TypeWhisper.

Details are under Group Policy. For Intune or other tools, see Intune and Registry and scripts.

How managed settings work#

TypeWhisper reads machine policies from two registry keys. Group Policy, Intune, and other management tools write the same values.

When several sources set a value, this order applies:

1. Enforced policy
2. The user's own choice
3. Recommended policy
4. The app default

The app reads the 64-bit registry view and never writes the keys. It reads the policy before plugins and background work start, so values present at the first launch apply right away. Later changes reach the running app through a registry notification, with a check every 30 seconds as a fallback, and apply without a restart. Standard users cannot write HKLM, so they cannot change enforced values.

Value types and lists#

• Switches are REG_DWORD values of 0 or 1, options are REG_DWORD numbers, and text is REG_SZ.
• A list is a subkey with numbered REG_SZ values (1, 2, …) next to a REG_DWORD named <Name>Configured. Without that marker, or with 0, the list restricts nothing. With 1, only the listed entries are allowed; an empty list allows nothing.
• An entry that matches nothing, such as none, allows nothing as well. Group Policy needs this form, because its editor does not save an enabled list without entries.

Invalid and unknown values#

• An invalid enforced value blocks its setting until it is corrected. It never relaxes a restriction.
• If the policy key cannot be read, the app keeps the last known values and blocks managed operations.
• Restrictions placed under Recommended and unknown values are reported as policy problems and ignored.
• Removing a value restores the user's own setting. Removing the whole key restores all of them.

Key reference#

All values live under HKLM\SOFTWARE\Policies\TypeWhisper. Values that can also be recommended go under Recommended as well. Pairs and lists are described in more detail below.

License#

Models#

Updates and startup#

Data and plugins#

Provider and model pairs#

A pair names a provider by its selection ID and a model by the ID the provider lists. Both values belong under the same key. A pair with only one value is invalid, and the affected function waits until the pair is complete.

• Local Parakeet engine: com.typewhisper.sherpa-onnx. Its model IDs appear on the Dictation page and as id in GET /v1/models, for example parakeet-tdt-0.6b. The API itself lists the engine as sherpa-onnx with the provider_id local; policies take the package ID.
• Cloud plugins: their package ID, such as com.typewhisper.groq or com.typewhisper.openai, and the model IDs their settings page lists, for example whisper-large-v3.
• Endpoint profiles of the OpenAI Compatible plugin: openai-compatible-<id>.
• Text models: the same package IDs, with the model IDs the workflow editor offers for that provider.

.\Set-TypeWhisperPolicy.ps1 -String @{ TranscriptionProviderId = 'com.typewhisper.sherpa-onnx'; TranscriptionModelId = 'parakeet-tdt-0.6b' }

Enforced pairs#

An enforced transcription pair wins over the user's selection, dictation workflows with their own model, queued and recovered jobs, and HTTP API requests. A request for another engine or model gets 403 forbidden. The pickers in Dictation and setup show the pair and are locked; the Provider settings button stays available for API keys and downloads. The user's own selection is kept and applies again when the pair is removed. A plugin's own model selection is switched to the enforced model and restored once the policy is removed.

An enforced text model pair replaces the provider and model of every workflow, the default workflow LLM, and API translation. The workflow editor keeps saved selections but locks the pickers and names the enforced pair; the Default LLM dialog is read-only. Text sent to another provider or model is refused.

Missing providers and models#

An unknown or unavailable ID never causes a silent switch:

• A required provider that is not installed, not enabled, or refused by an allowlist or a cloud key stays visibly selected. Dictation or processing is blocked with the reason.
• A required model that the provider does not offer, or that is not downloaded, blocks the same way. With AllowModelDownloads set to 0, your deployment has to provide the model files; otherwise the user can download the model from the provider page.
• Settings > Advanced > Managed settings lists these conflicts under Policy problems, next to the pair itself.

Recommended pairs#

A recommended pair is the starting selection of a profile that has not chosen a transcription provider or saved a default workflow LLM. Users can change it, and an existing choice is never replaced. A recommended model that is not downloaded yet has to be downloaded by the user or provided by your deployment; until then, setup asks for a ready model as usual.

Cloud processing and plugin locality#

Every plugin declares in its locality field where it processes content; the plugin catalog publishes the same value:

• local: nothing leaves the device.
• cloud: the vendor's fixed service.
• configurable: an endpoint, script, or command the user defines, which the app cannot verify.

With AllowCloudTranscription or AllowCloudTextProcessing set to 0, only local plugins keep running for that content. Plugins marked cloud or configurable and packages without a recognized value are refused. A plugin without the field falls back to its older isLocal flag. A package that is not local and whose capabilities are all turned off is refused as a whole: it is not installed, loaded, or enabled, and the Marketplace and its plugin page name the reason. Pickers show refused entries grayed out with the reason and never switch a selection on their own.

Known limits#

• AllowModelDownloads covers the downloads the app starts. A plugin that fetches runtime files while it loads a model, such as GPU runtimes in the transcription worker or the vocabulary files of the local Parakeet plugin, is not stopped. Provide these files with your deployment; the hosts are listed on the Deployment page.
• Configuration actions such as validating an API key still run under AllowCloudTextProcessing; they carry credentials, not transcripts.
• A refused provider that is still selected is refused with the same message when it is used.
• Audio that a streaming provider received before a stricter policy arrived cannot be recalled. The policy is checked again at the next provider call.

Managed license key#

ManagedLicenseKey activates a commercial license in the session of every Windows user who starts TypeWhisper. You don't need to call Polar yourself or hand the key to users. Surrounding whitespace is ignored, an empty value counts as not set, and supporter keys are not accepted. The app never writes, changes, or removes the value.

New-Item -Path 'HKLM:\SOFTWARE\Policies\TypeWhisper' -Force | Out-Null
Set-ItemProperty -Path 'HKLM:\SOFTWARE\Policies\TypeWhisper' -Name 'ManagedLicenseKey' -Value 'YOUR_LICENSE_KEY' -Type String

Deploy the value with the Group Policy setting “Managed license key”, a registry item in Group Policy Preferences, an Intune PowerShell script that runs in the system context, or any other tool that writes HKLM. Keep real keys out of shell history and script logs.

Activation and seats#

• The app reads the value at startup, when the policy changes while it runs, and through Retry activation in Settings > Premium > License.
• It stores the key and its activation in the user's license file, encrypted with Windows Data Protection (DPAPI), and does not activate again on every launch.
• Each Windows user account on a device holds its own activation, so a device with several users uses one seat per user. The direct download and the Microsoft Store version keep separate profiles: a user who runs both takes one seat per version. Polar names each activation after the computer and the Windows user, for example TYPEWHISPER (tw-user2).
• The first activation needs internet access. If it fails, retry it on the License page or at the next launch; there is no automatic retry in the background. Existing licenses keep their normal offline validation.
• While the key is managed, the License page hides key entry, device deactivation, and purchase links, suppresses Premium purchase prompts, and shows the license status without the key. Supporter keys cannot be entered while a managed key is configured.

Changing or removing the key#

• A new key is activated and stored before the previous activation is deactivated. If the new key fails, the previous license stays intact. If deactivating the old activation fails, it stays listed in Polar and can be removed there.
• Removing the value brings back the manual license controls at the next launch or retry. It does not deactivate the existing activation: deactivate the device manually or revoke the license in Polar. The app notices central changes at its next validation, at launch, when the key changes, or on Retry activation, once seven days have passed since the last successful check of an active license.
• A key that Polar rejects is not retried automatically. An activation deleted in Polar is created again at the next check while the configured key stays valid.

Group Policy#

Every release includes the templates as TypeWhisper-win-PolicyTemplates.zip, laid out like PolicyDefinitions: TypeWhisper.admx, the en-US and de-DE language files, and Set-TypeWhisperPolicy.ps1. Use the templates from the release you deploy. They contain machine policies only and write exactly the values in the reference above.

• TypeWhisper-win-PolicyTemplates.zip
• Templates and script in the repository

1. Copy TypeWhisper.admx to the Central Store \\<domain>\SYSVOL\<domain>\Policies\PolicyDefinitions and the ADML files into its en-US and de-DE subfolders. Without a Central Store, use %SystemRoot%\PolicyDefinitions on the computer that edits the policy.
2. Open the policy in the Group Policy Management Editor, or gpedit.msc for the local policy, under Computer Configuration > Administrative Templates > TypeWhisper. Recommended settings are in the subfolder “Recommended settings (users can change)”.
3. Configure the settings. Switches write 1 when Enabled and 0 when Disabled. Text, option, and list settings write their values when Enabled and remove them when Disabled. Not Configured always removes the value. For a list that allows nothing, enter the single entry none. Replacing a list removes the old numbered entries.
4. The policy applies at the next Group Policy refresh, and the running app picks it up within seconds. To refresh right away:

gpupdate /target:computer

Settings in the editor#

Each pair is one setting, so 18 registry values appear as 16 settings:

The subfolder for recommended settings holds five more, which write the same values under Recommended: Transcription provider and model (recommended), Text model provider and model (recommended), Update channel (recommended), Start TypeWhisper at sign-in (recommended), and Hide optional prompts (recommended).

Intune#

Import the ADMX template#

1. In the Intune admin center, open Devices > Manage devices > Configuration, select the Import ADMX tab, then Import. Upload TypeWhisper.admx with the en-US ADML file. The import accepts en-US only.
2. Under Configuration > Create > New policy, create a profile for Windows 10 and later of the type Templates > Imported Administrative templates (Preview), configure the settings, and assign the profile to device groups.

Removing a setting from the profile, or unassigning the profile, returns the value to Not Configured. The app treats that as removal: enforced values disappear and the users' own settings apply again. Microsoft lists the import of custom ADMX templates as a public preview; test it in a pilot tenant first. To move to a newer template, for example one with settings from a later release, first delete the profiles that use the old template, then the imported file, and import the new files afterward; Intune rejects a second file with the same namespace.

Alternative: OMA-URI#

In tenants without the import, ingest the ADMX through a custom OMA-URI profile. Install the template with its file content as a string value:

./Device/Vendor/MSFT/Policy/ConfigOperations/ADMXInstall/TypeWhisper/Policy/TypeWhisperAdmx

Then address each setting by its name in TypeWhisper.admx, such as AllowCloudTranscription or TranscriptionSelection, with <enabled/> or <disabled/> and the <data id="…" value="…"/> elements of the policy. Recommended settings use the second category:

./Device/Vendor/MSFT/Policy/Config/TypeWhisper~Policy~TypeWhisper/<PolicyName>
./Device/Vendor/MSFT/Policy/Config/TypeWhisper~Policy~TypeWhisper~TypeWhisper_Recommended/<PolicyName>

Two examples:

OMA-URI  ./Device/Vendor/MSFT/Policy/Config/TypeWhisper~Policy~TypeWhisper/AllowCloudTranscription
Value    <disabled/>

OMA-URI  ./Device/Vendor/MSFT/Policy/Config/TypeWhisper~Policy~TypeWhisper/TranscriptionSelection
Value    <enabled/><data id="TranscriptionProviderId" value="com.typewhisper.sherpa-onnx"/><data id="TranscriptionModelId" value="parakeet-tdt-0.6b"/>

Check the exact URIs on a pilot device before you roll them out.

Registry and scripts#

Set-TypeWhisperPolicy.ps1 writes the same values from an elevated PowerShell session: for Group Policy Preferences, Intune scripts, other management tools, and tests. It runs in Windows PowerShell 5.1 and PowerShell 7 and writes lists the way the app and the template expect them.

# Enforced values
.\Set-TypeWhisperPolicy.ps1 -Dword @{ UpdateMode = 1; LaunchAtLogin = 1; AllowCloudTranscription = 0 }
.\Set-TypeWhisperPolicy.ps1 -String @{ TranscriptionProviderId = 'com.typewhisper.sherpa-onnx'; TranscriptionModelId = 'parakeet-tdt-0.6b' }
.\Set-TypeWhisperPolicy.ps1 -List @{ AllowedUpdateChannels = @('stable'); AllowedPlugins = @('com.typewhisper.sherpa-onnx') }

# Recommended values
.\Set-TypeWhisperPolicy.ps1 -Recommended -Dword @{ UpdateChannel = 0 }

# Show the policy, remove values, or clear it
.\Set-TypeWhisperPolicy.ps1 -Show
.\Set-TypeWhisperPolicy.ps1 -Remove AllowedPlugins, ManagedLicenseKey
.\Set-TypeWhisperPolicy.ps1 -Clear

Without the script, plain registry commands do the same:

$policy = 'HKLM:\SOFTWARE\Policies\TypeWhisper'
New-Item -Path $policy -Force | Out-Null
Set-ItemProperty -Path $policy -Name UpdateMode -Value 1 -Type DWord          # check only
Set-ItemProperty -Path $policy -Name LaunchAtLogin -Value 1 -Type DWord       # start with Windows
Set-ItemProperty -Path $policy -Name AllowedUpdateChannelsConfigured -Value 1 -Type DWord
New-Item -Path "$policy\AllowedUpdateChannels" -Force | Out-Null
Set-ItemProperty -Path "$policy\AllowedUpdateChannels" -Name 1 -Value stable -Type String
New-Item -Path "$policy\Recommended" -Force | Out-Null
Set-ItemProperty -Path "$policy\Recommended" -Name UpdateChannel -Value 0 -Type DWord

Check the effective values#

• Settings > Advanced > Managed settings shows the values in effect on the device and, under Policy problems, everything that does not fit: invalid values, incomplete pairs, missing providers or models, and restrictions placed under Recommended.
• Locked settings say in the app that your organization manages them. If the policy cannot be read, the section says so and the app keeps the last known values.
• The support report (Settings > Advanced > Support diagnostics > Support report > Export diagnostics…) contains the same section. Users can send it to you or to TypeWhisper support.
• Set-TypeWhisperPolicy.ps1 -Show prints what is in the registry.