Document experimental device registration and the License Denied workaround.

Co-authored-by: Cursor <cursoragent@cursor.com>

.vitepress/config.js

@@ -124,6 +124,7 @@ export default defineConfig({
         items: [
           { text: "Advanced Topics", link: "/docs/advanced/advanced" },
           { text: "Command Line Interface", link: "/docs/advanced/command-line-interface" },
+          { text: "Device registration", link: "/docs/advanced/device-registration" },
           { text: "Troubleshooting", link: "/docs/advanced/troubleshoot" },
           { text: "Spatial Audio & DRM", link: "/docs/advanced/spatial-audio" },
         ],

docs/advanced/advanced.md

@@ -14,6 +14,8 @@ To make upgrades and reinstalls easier, Libation separates all of its responsibi
 
 - Check for new Libation versions at startup. Enabled by default: each time Libation starts it asks GitHub whether a newer release exists, and offers it to you if there is one. Turn it off if something else keeps Libation up to date, such as a package manager or an AppImage updater. Turning it off only stops the automatic check - Settings > About still has a "Check for Upgrade" button that works either way.
 
+- Device registration (experimental). Which virtual device Libation registers with Amazon when you sign in. Leave the Android emulator default unless downloads fail for titles that still play in the official Audible app. Changing it does not convert existing accounts; you must remove and re-add the account. See [Device registration](./device-registration.md).
+
 - Allow Libation to fix up audiobook metadata. After decrypting a title, Libation attempts to fix details like chapters and cover art. Some power users and/or control freaks prefer to manage this themselves. By unchecking this setting, Libation will only decrypt the book and will leave metadata as-is, warts and all.
 
 In addition to the options that are enabled if you allow Libation to "fix up" the audiobook, it does the following:

docs/advanced/command-line-interface.md

@@ -115,6 +115,12 @@ libationcli login-external -a you@example.com -l us --response-url "https://www.
 
 If the account row already has valid saved tokens, the CLI reports that no browser login is needed and exits without opening the flow.
 
+Optional `--device-registration` picks which virtual device to register as on a **new** sign-in: `CurrentAndroid` (default from Settings), `RetailAndroid`, or `Mkb79IPhone`. It does nothing to an account that is already authenticated; remove the account first. See [Device registration](/docs/advanced/device-registration).
+
+```console
+libationcli login-external --account you@example.com --locale us --device-registration Mkb79IPhone
+```
+
 Use `libationcli login-external --help` for the exact options on your build.
 
 ## List configured accounts (`list-accounts`)

docs/advanced/device-registration.md

@@ -0,0 +1,50 @@
+# Device registration (experimental)
+
+When you sign in, Libation registers a virtual device with Amazon. Audible then ties download licenses to that device. The default is an Android emulator, which is required for [Widevine](/docs/features/audio-file-formats#use-widevine-drm).
+
+Audible has been refusing licenses (`License Denied` / `CustomerThrottled`) for some emulator registrations even when the same title still plays in the official Audible app. If that happens, you can try an experimental registration, or import credentials from [mkb79's audible-cli](https://github.com/mkb79/audible-cli).
+
+Changing this setting does **not** convert accounts you already signed in. Remove and re-add the account (or run `login-external`) after you pick a different profile.
+
+## Where to find it
+
+- **Chardonnay:** Settings -> Important -> **Device registration (experimental)**
+- **Classic:** Settings -> Import library -> **Device registration (experimental)**
+- **CLI / Docker:** `DeviceRegistrationKind` in `Settings.json`, or `--device-registration` on `login-external`. See [Command Line Interface](/docs/advanced/command-line-interface#log-in-with-an-external-browser-login-external).
+
+## The three profiles
+
+| Setting value | Label in Settings | Widevine | What it registers |
+|---------------|-------------------|----------|-------------------|
+| `CurrentAndroid` | Android emulator (default) | Yes | The emulator Libation has used for years |
+| `RetailAndroid` | Android Pixel (experimental) | Yes | Same Android Audible app as the default, with a retail Pixel fingerprint |
+| `Mkb79IPhone` | iPhone / audible-cli (experimental; no Widevine) | No | The virtual iPhone used by audible-cli |
+
+Leave the default unless downloads fail for titles that still work in the official app.
+
+## How to apply a new profile
+
+1. Pick the profile in Settings (or set `DeviceRegistrationKind` / `--device-registration`).
+2. Remove the account from Libation. Existing Amazon device records keep the old registration until you sign in again.
+3. Add the account and sign in, or run `login-external`.
+4. Scan and try the download again.
+
+Importing an audible-cli JSON file with `import-account` is the other workaround: those credentials already come from audible-cli's iPhone registration, so you do not need to change this setting first.
+
+## Widevine
+
+**Use Widevine DRM** only works when the account was registered as an Android Audible app (`CurrentAndroid` or `RetailAndroid`). The iPhone profile cannot use Widevine. If you need Widevine later, remove the account and sign in again with an Android profile.
+
+## Settings.json (Docker and CLI)
+
+```json
+{
+  "DeviceRegistrationKind": "RetailAndroid"
+}
+```
+
+Accepted values: `CurrentAndroid`, `RetailAndroid`, `Mkb79IPhone`. Then remove the account and sign in again. `login-external --device-registration Mkb79IPhone` overrides Settings for that one sign-in.
+
+## If it still fails
+
+Wait 24 to 48 hours: Audible also rate-limits heavy Plus use. See [Daily download limit](/docs/features/daily-download-limit) and [Retrying titles Audible refuses](/docs/features/retrying-refused-downloads). If the official app can play the title and a new registration still cannot download it, open a GitHub issue and attach your log.

docs/advanced/spatial-audio.md

@@ -62,7 +62,7 @@ Download and decrypt titles while Libation still supports the format Audible del
 
 1. Open **Settings** and enable **Use Widevine DRM**.
 2. Enable **Request xHE-AAC Codec**.
-3. Re-add your account if Libation prompts you (Widevine requires an Android-style device registration).
+3. Re-add your account if Libation prompts you (Widevine requires an Android device registration; the experimental iPhone profile cannot use it). See [Device registration](./device-registration.md).
 4. Re-download the title.
 
 See [Audio File Formats](../features/audio-file-formats.md) for codec details and [Supported Media Players](../features/audio-file-formats.md#supported-media-players) if you have trouble playing xHE-AAC.

docs/advanced/troubleshoot.md

@@ -264,9 +264,10 @@ Symptoms include a crash on startup that mentions `LibationContext.db` under a p
 These errors come from Audible refusing to grant a download license. Common causes:
 
 1. **Temporary Audible outage or Plus throttling** -- wait 24 to 48 hours and try again. See the [FAQ](/docs/frequently-asked-questions).
-2. **Title requires Widevine** -- some Plus titles no longer download as AAXC; enable **Use Widevine DRM** in Settings and re-add your account if prompted. See [issue #1580](https://github.com/rmcrackan/Libation/issues/1580).
-3. **Spatial / Dolby Atmos requested (older Libation versions)** -- Audible now requires Widevine L1 for many spatial titles. Libation 13.1.3+ no longer offers spatial download. See [Spatial Audio & DRM](/docs/advanced/spatial-audio).
-4. **You no longer have rights to the title** -- it was returned, it left the Plus catalog, or the account that owned it is no longer active. Check the title in the Audible app or website.
+2. **Virtual-device registration** -- the official Audible app can play the title, but Libation cannot. Try an [experimental device registration](/docs/advanced/device-registration) (then remove and re-add the account), or import credentials from [audible-cli](https://github.com/mkb79/audible-cli).
+3. **Title requires Widevine** -- some Plus titles no longer download as AAXC; enable **Use Widevine DRM** in Settings and re-add your account if prompted. The iPhone registration cannot use Widevine. See [issue #1580](https://github.com/rmcrackan/Libation/issues/1580) and [Device registration](/docs/advanced/device-registration#widevine).
+4. **Spatial / Dolby Atmos requested (older Libation versions)** -- Audible now requires Widevine L1 for many spatial titles. Libation 13.1.3+ no longer offers spatial download. See [Spatial Audio & DRM](/docs/advanced/spatial-audio).
+5. **You no longer have rights to the title** -- it was returned, it left the Plus catalog, or the account that owned it is no longer active. Check the title in the Audible app or website.
 
 After a refusal Libation waits before asking about that title again, so you see the explanation once rather than on every run. It attempts the title again by itself; to try it sooner, name it (`libationcli liberate <ASIN>`) or mark it **Download Pending** (previously "Not Downloaded"). See [Retrying titles Audible refuses](/docs/features/retrying-refused-downloads).
 

docs/features/audio-file-formats.md

@@ -18,7 +18,7 @@ Audiobooks can be requested from Audible as "Normal" quality or "High" quality,
 ### Use Widevine DRM
 
 When this setting is disabled, all audiobooks will be downloaded using Audible's in-house DRM (AAX(C)) in the [AAC-LC](#aac-lc) format.
-When this setting is enabled, Libation will request audio files protected by Google's Widevine DRM scheme. This unlocks [Request xHE-AAC Codec](#request-xhe-aac-codec) for higher-quality stereo downloads on titles where Audible delivers them via Widevine L3.
+When this setting is enabled, Libation will request audio files protected by Google's Widevine DRM scheme. This unlocks [Request xHE-AAC Codec](#request-xhe-aac-codec) for higher-quality stereo downloads on titles where Audible delivers them via Widevine L3. Widevine requires an Android device registration; the experimental iPhone profile cannot use it. See [Device registration](/docs/advanced/device-registration#widevine).
 
 If you don't enable **Request xHE-AAC Codec**, then enabling **Use Widevine DRM** will have no practical effect in nearly all circumstances. Audiobooks will be downloaded in the same [AAC-LC](#aac-lc) format with the same bitrate and the same number of audio channels. On rare occasions, enabling **Use Widevine DRM** without xHE-AAC will result in audio files with a different bitrate.
 

docs/features/daily-download-limit.md

@@ -74,4 +74,4 @@ A container that liberates on a schedule combines well with a limit: each run do
 
 ## When a license is denied anyway
 
-If Audible refuses a license despite the limit, Libation waits before asking about that title again instead of re-requesting it on every run. See [Retrying titles Audible refuses](/docs/features/retrying-refused-downloads).
+If Audible refuses a license despite the limit, Libation waits before asking about that title again instead of re-requesting it on every run. See [Retrying titles Audible refuses](/docs/features/retrying-refused-downloads). If the official Audible app can still play the title, try an [experimental device registration](/docs/advanced/device-registration) or import credentials from audible-cli.

docs/features/parallel-downloads.md

@@ -16,7 +16,7 @@ Audible throttles license requests. Downloading too many titles at once leads it
 
 **Above 3 concurrent downloads, license denials start appearing.** The exact threshold is Audible's and is not published, so 3 is the conservative choice rather than a measured maximum. The ceiling of 10 exists to stop the setting from being turned into a reliable way to get your downloads refused.
 
-If you are seeing license denials, lowering this number is the first thing to try. See [Retrying titles Audible refuses](/docs/features/retrying-refused-downloads) for what Libation does with a title once it has been refused.
+If you are seeing license denials, lowering this number is the first thing to try. See [Retrying titles Audible refuses](/docs/features/retrying-refused-downloads) for what Libation does with a title once it has been refused. If the official app can still play the title, also see [Device registration](/docs/advanced/device-registration).
 
 ## Your machine may run fewer than you asked for
 

docs/features/retrying-refused-downloads.md

@@ -15,6 +15,10 @@ Without this, a title Audible had just refused was requested again on the very n
 refused licenses every run, forever: pointless traffic to Audible, which itself risks throttling, and a
 console and log full of the same warning for the same titles.
 
+If the official Audible app can play a title that Libation cannot download, that can be the virtual device
+Libation registered at sign-in rather than the wait described here. See [Device
+registration](/docs/advanced/device-registration).
+
 ## How long Libation waits
 
 The wait starts short and doubles with each refusal in a row. Nothing is ever permanent: every kind of

docs/frequently-asked-questions.md

@@ -67,6 +67,14 @@ You likely copied an `AccountsSettings.json` that has **encrypted** tokens (`"Is
 
 Full steps: [Troubleshooting - Failed to decrypt ExistingAccessToken](/docs/advanced/troubleshoot#failed-to-decrypt-existingaccesstoken-docker-finds-no-new-books) and [Docker Troubleshooting](/docs/installation/docker#troubleshooting).
 
+## Downloads fail with "Content license denied" but the Audible app still plays the title
+
+That is Audible refusing a download license, not a Libation decrypt bug. Wait 24 to 48 hours if you just downloaded many Plus titles.
+
+If the official app can play the title and waiting does not help, try an [experimental device registration](/docs/advanced/device-registration): pick a profile in Settings, then **remove and re-add the account** (or `login-external`). You can also import credentials from [audible-cli](https://github.com/mkb79/audible-cli). Changing the setting does not convert accounts you already signed in.
+
+See [Troubleshooting](/docs/advanced/troubleshoot#download-fails-with-drm-license-response-not-ok-or-content-license-denied).
+
 ## Docker log says Failed to encrypt identity field / Saving as plaintext
 
 That means encryption was preferred but could not run (usually no master key in the container). Libation re-saves those fields as plaintext and **continues** - this is expected and not a crash. Supply a master key if you want encryption at rest, or switch token storage to plaintext to quiet the Errors.

docs/index.md

@@ -32,6 +32,7 @@ Learn about Libation's powerful features:
 
 - **[Advanced Topics](/docs/advanced/advanced)** - Deep dives and configuration details
 - **[Command Line Interface](/docs/advanced/command-line-interface)** - CLI usage and commands
+- **[Device registration](/docs/advanced/device-registration)** - Experimental login profiles when Audible denies download licenses
 - **[Troubleshooting](/docs/advanced/troubleshoot)** - Common errors and solutions
 - **[Spatial Audio & DRM](/docs/advanced/spatial-audio)** - Why Dolby Atmos download is not available and what still works
 

docs/installation/docker.md

@@ -52,6 +52,7 @@ If you run Libation on a server or in Docker and do not want to copy `AccountsSe
 - `login-external` — Browser-based sign-in: the CLI prints an Audible login URL; you open it in a normal browser, sign in, then paste the final URL from the address bar back into the terminal. Example:
   `LibationCli login-external --account you@example.com --locale us`
   If standard input is not a TTY (for example in some automation), pass the final URL with `--response-url "https://..."` instead of pasting interactively.
+  Optional `--device-registration CurrentAndroid|RetailAndroid|Mkb79IPhone` applies only to a new sign-in; remove the account first. See [Device registration](/docs/advanced/device-registration).
 - `list-accounts` — List configured accounts and whether each has valid stored credentials (and scan-on/off). Example:
   `LibationCli list-accounts` or `LibationCli list-accounts --bare` for tab-separated output.
 

index.md

@@ -82,6 +82,7 @@ Learn about Libation's powerful features:
 
 - **[Advanced Topics](/docs/advanced/advanced)** - Deep dives and configuration details
 - **[Command Line Interface](/docs/advanced/command-line-interface)** - CLI usage and commands
+- **[Device registration](/docs/advanced/device-registration)** - Experimental login profiles when Audible denies download licenses
 - **[Troubleshooting](/docs/advanced/troubleshoot)** - Common errors and solutions
 - **[Spatial Audio & DRM](/docs/advanced/spatial-audio)** - Why Dolby Atmos download is not available and what still works