Merge pull request #1909 from rmcrackan/rmcrackan/cli-scan-auth-and-locale

Surface real CLI/Docker auth failures and fix login-external locales

.cdmurls.json

@@ -0,0 +1,5 @@
+{
+  "CdmUrls": [
+    "https://ollj0gz40d.execute-api.us-west-2.amazonaws.com/default/AudibleCdm"
+  ]
+}

.editorconfig

@@ -0,0 +1,5 @@
+# https://editorconfig.org
+root = true
+
+[*.md]
+charset = utf-8

.gitattributes

@@ -0,0 +1 @@
+*.sh text eol=lf

.github/ISSUE_TEMPLATE/bug_report.md

@@ -6,10 +6,14 @@ labels: bug
 assignees: ''
 ---
 
-**Describe the bug**
+PLEASE FILL OUT THE FOLLOWING. Bug reports with limited information or lacking an attached log file may get limited or delayed help.
+
+___
+
+## Describe the bug  
 A clear and concise description of what the bug is.
 
-**To Reproduce**
+## To Reproduce  
 Steps to reproduce the behavior:
 
 1. Go to '...'
@@ -17,15 +21,25 @@ Steps to reproduce the behavior:
 3. Scroll down to '....'
 4. See error
 
-**Expected behavior**
+## Expected behavior  
 A clear and concise description of what you expected to happen.
 
-**Screenshots**
+## Screenshots  
 If applicable, add screenshots to help explain your problem.
 
-**Platform**
-
+## Platform  
 [e.g. Windows 10, Windows 11, Mac, Linux (State distribution)]
 
-**Log Files**
-Attach your Libation log file here.
+## Log Files
+Attach your Libation log file here. If your user folder contains the file "LibationCrash.log", attach that also.
+
+**Default Log File Locations**
+|Platform|Folder|
+|-|-|
+|Windows|`%userprofile%\Libation`|
+|macOS|`~/Library/Application Support/Libation`|
+|Linux|`~/.local/share/Libation`|
+
+**macOS:** If that folder does not exist because Libation never starts, try launching from Terminal and say whether it works: `/Applications/Libation.app/Contents/MacOS/Libation` (see [Troubleshooting for macOS](https://github.com/rmcrackan/Libation/blob/main/docs/advanced/troubleshoot.md#macos)).
+
+Alternative, you may open the log file folder from within Libation. Open Libation's settings, and on the first tab in Settings you can click the button 'Open log folder'. 

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/feature_request.md

@@ -6,14 +6,26 @@ labels: enhancement
 assignees: ''
 ---
 
-**Is your feature request related to a problem? Please describe.**
+**No-go ideas**  
+There are lots of great ideas and many are beyond what we intend to do for Libation. Some good ideas which we do not intend to pursue:
+
+* comprehensive api/cli
+* aax/audiobook import
+* bulk rename of existing files
+* general metadata/tag editor
+* playback features
+* web gui
+* supporting non-audible vendors
+* official docker support
+
+**Is your feature request related to a problem? Please describe.**  
 A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
 
-**Describe the solution you'd like**
+**Describe the solution you'd like**  
 A clear and concise description of what you want to happen.
 
-**Describe alternatives you've considered**
+**Describe alternatives you've considered**  
 A clear and concise description of any alternative solutions or features you've considered.
 
-**Additional context**
+**Additional context**  
 Add any other context or screenshots about the feature request here.

.github/download-icon.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+  <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/>
+  <polyline points="7 10 12 15 17 10"/>
+  <line x1="12" y1="15" x2="12" y2="3"/>
+</svg>

.github/labels.yml

@@ -0,0 +1,10 @@
+# Labels required by exempt-creators.yml and stale.yml. Sync with sync-labels workflow.
+# (Other repo labels are left unchanged when prune: false.)
+---
+- name: stale
+  color: 'eeeeee'
+  description: 'No activity for an extended period'
+
+- name: exempt
+  color: '0e8a16'
+  description: 'Excluded from automatic stale closure (e.g. maintainer-opened)'

.github/workflows/build-linux.yml

@@ -1,81 +1,83 @@
 # build-linux.yml
-# Reusable workflow that builds the Linux and MacOS versions of Libation.
+# Reusable workflow that builds the Linux and MacOS (x64 and arm64) versions of Libation.
 ---
 name: build
 
 on:
   workflow_call:
     inputs:
-      version_override:
+      libation-version:
         type: string
-        description: 'Version number override'
-        required: false
-      run_unit_tests:
+        required: true
+      dotnet-version:
+        type: string
+        required: true
+      run-unit-tests:
         type: boolean
-        description: 'Skip running unit tests'
-        required: false
-        default: true
-
-env:
-  DOTNET_CONFIGURATION: 'Release'
-  DOTNET_VERSION: '7.0.x'
+      publish-r2r:
+        type: boolean
+      retention-days:
+        type: number
+      architecture:
+        type: string
+        description: "CPU architecture targeted by the build."
+        required: true
+      OS:
+        type: string
+        description: >
+          The operating system targeted by the build.
+          
+          There must be a corresponding Bundle_$OS.sh script file in ./Scripts
+        required: true
 
 jobs:
   build:
+    name: "${{ inputs.OS }}-${{ inputs.architecture }}"
     runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        os: [Linux, MacOS]
-        ui: [Avalonia]
-        release_name: [chardonnay]
+    env:
+      RUNTIME_ID: "linux-${{ inputs.architecture }}"
     steps:
-      - uses: actions/checkout@v3
-      - name: Setup .NET
-        uses: actions/setup-dotnet@v3
+      - uses: actions/checkout@v7
+      
+      - uses: actions/setup-dotnet@v6
         with:
-          dotnet-version: ${{ env.DOTNET_VERSION }}
-        env:
-          NUGET_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Get version
-        id: get_version
-        run: |
-          inputVersion="${{ inputs.version_override }}"
-          if [[ "${#inputVersion}" -gt 0 ]]
-          then
-            version="${inputVersion}"
-          else
-            version="$(grep -oP '(?<=<Version>).*(?=</Version)' ./Source/AppScaffolding/AppScaffolding.csproj)"
-          fi
-          echo "version=${version}" >> "${GITHUB_OUTPUT}"
+          dotnet-version: ${{ inputs.dotnet-version }}
+          dotnet-quality: "ga"
 
       - name: Unit test
-        if: ${{ inputs.run_unit_tests }}
+        if: ${{ inputs.run-unit-tests }}
         working-directory: ./Source
         run: dotnet test
 
       - name: Publish
+        id: publish
         working-directory: ./Source
         run: |
-          dotnet publish -c ${{ env.DOTNET_CONFIGURATION }} -o bin/Publish/${{ matrix.os }}-${{ matrix.release_name }} Libation${{ matrix.ui }}/Libation${{ matrix.ui }}.csproj -p:PublishProfile=Libation${{ matrix.ui }}/Properties/PublishProfiles/${{ matrix.os }}Profile.pubxml
-          dotnet publish -c ${{ env.DOTNET_CONFIGURATION }} -o bin/Publish/${{ matrix.os }}-${{ matrix.release_name }} LoadByOS/${{ matrix.os }}ConfigApp/${{ matrix.os }}ConfigApp.csproj -p:PublishProfile=LoadByOS/Properties/${{ matrix.os }}ConfigApp/PublishProfiles/${{ matrix.os }}Profile.pubxml
-          dotnet publish -c ${{ env.DOTNET_CONFIGURATION }} -o bin/Publish/${{ matrix.os }}-${{ matrix.release_name }} LibationCli/LibationCli.csproj -p:PublishProfile=LibationCli/Properties/PublishProfiles/${{ matrix.os }}Profile.pubxml
-          dotnet publish -c ${{ env.DOTNET_CONFIGURATION }} -o bin/Publish/${{ matrix.os }}-${{ matrix.release_name }} Hangover${{ matrix.ui }}/Hangover${{ matrix.ui }}.csproj -p:PublishProfile=Hangover${{ matrix.ui }}/Properties/PublishProfiles/${{ matrix.os }}Profile.pubxml
+          PUBLISH_ARGS=(
+            '--runtime' '${{ env.RUNTIME_ID }}'
+            '--configuration' 'Release'
+            '--output' '../bin'
+            '-p:PublishProtocol=FileSystem'
+            "-p:PublishReadyToRun=${{ inputs.publish-r2r }}"
+            '-p:SelfContained=true')
+            
+          dotnet publish LibationAvalonia/LibationAvalonia.csproj "${PUBLISH_ARGS[@]}"
+          dotnet publish LoadByOS/LinuxConfigApp/LinuxConfigApp.csproj "${PUBLISH_ARGS[@]}"
+          dotnet publish LibationCli/LibationCli.csproj "${PUBLISH_ARGS[@]}"
+          dotnet publish HangoverAvalonia/HangoverAvalonia.csproj "${PUBLISH_ARGS[@]}"
 
-      - name: Zip artifact
-        id: zip
-        working-directory: ./Source/bin/Publish/${{ matrix.os }}-${{ matrix.release_name }}
+      - name: Build bundle
+        id: bundle
         run: |
-          delfiles=("libmp3lame.x86.dll" "libmp3lame.x64.dll" "ffmpegaac.x86.dll" "ffmpegaac.x64.dll" "ZipExtractor.exe")
-          for n in "${delfiles[@]}"; do rm "$n"; done
-          osbuild="$(echo '${{ matrix.os }}' | tr '[:upper:]' '[:lower:]')"
-          artifact="Libation.${{ steps.get_version.outputs.version }}-${osbuild}-${{ matrix.release_name }}"
+          SCRIPT=./Scripts/Bundle_${{ inputs.OS }}.sh
+          chmod +rx ${SCRIPT}
+          ${SCRIPT} ./bin "${{ inputs.libation-version }}" "${{ inputs.architecture }}"
+          artifact=$(ls ./bundle)
           echo "artifact=${artifact}" >> "${GITHUB_OUTPUT}"
-          tar -zcvf "../${artifact}.tar.gz" .
 
-      - name: Publish artifact
-        uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v7
         with:
-          name: ${{ steps.zip.outputs.artifact }}.tar.gz
-          path: ./Source/bin/Publish/${{ steps.zip.outputs.artifact }}.tar.gz
+          name: ${{ steps.bundle.outputs.artifact }}
+          path: ./bundle/${{ steps.bundle.outputs.artifact }}
           if-no-files-found: error
+          retention-days: ${{ inputs.retention-days }}

.github/workflows/build-mac.yml

@@ -0,0 +1,113 @@
+# build-mac.yml
+# Reusable workflow that builds the MacOS (x64 and arm64) versions of Libation.
+---
+name: build
+
+on:
+  workflow_call:
+    inputs:
+      libation-version:
+        type: string
+        required: true
+      dotnet-version:
+        type: string
+        required: true
+      run-unit-tests:
+        type: boolean
+      publish-r2r:
+        type: boolean
+      retention-days:
+        type: number
+      sign-app:
+        type: boolean
+        description: "Wheather to sign an notorize the app bundle and dmg."
+      architecture:
+        type: string
+        description: "CPU architecture targeted by the build."
+        required: true
+
+jobs:
+  build:
+    name: "macOS-${{ inputs.architecture }}"
+    runs-on: macos-latest
+    env:
+      RUNTIME_ID: "osx-${{ inputs.architecture }}"
+      WAIT_FOR_NOTARIZE: ${{ vars.WAIT_FOR_NOTARIZE == 'true' }}
+    steps:    
+      - uses: apple-actions/import-codesign-certs@v7
+        if: ${{ inputs.sign-app }}
+        with: 
+          p12-file-base64: ${{ secrets.DISTRIBUTION_SIGNING_CERT }}
+          p12-password: ${{ secrets.DISTRIBUTION_SIGNING_CERT_PW }}       
+          
+      - uses: actions/checkout@v7
+      
+      - uses: actions/setup-dotnet@v6
+        with:
+          dotnet-version: ${{ inputs.dotnet-version }}
+          dotnet-quality: "ga"
+
+      - name: Unit test
+        if: ${{ inputs.run-unit-tests }}
+        working-directory: ./Source
+        run: dotnet test
+
+      - name: Publish
+        id: publish
+        working-directory: ./Source
+        run: |
+          PUBLISH_ARGS=(
+            '--runtime' '${{ env.RUNTIME_ID }}'
+            '--configuration' 'Release'
+            '--output' '../bin'
+            '-p:PublishProtocol=FileSystem'
+            "-p:PublishReadyToRun=${{ inputs.publish-r2r }}"
+            '-p:SelfContained=true')
+          
+          dotnet publish LibationAvalonia/LibationAvalonia.csproj "${PUBLISH_ARGS[@]}"
+          dotnet publish LoadByOS/MacOSConfigApp/MacOSConfigApp.csproj "${PUBLISH_ARGS[@]}"
+          dotnet publish LibationCli/LibationCli.csproj "${PUBLISH_ARGS[@]}"
+          dotnet publish HangoverAvalonia/HangoverAvalonia.csproj "${PUBLISH_ARGS[@]}"
+
+      - name: Build bundle
+        id: bundle
+        run: |
+          SCRIPT=./Scripts/Bundle_MacOS.sh
+          chmod +rx ${SCRIPT}
+          ${SCRIPT} ./bin "${{ inputs.libation-version }}" "${{ inputs.architecture }}" "${{ inputs.sign-app }}"
+          artifact=$(ls ./bundle)
+          echo "artifact=${artifact}" >> "${GITHUB_OUTPUT}"
+
+      - name: Notarize bundle
+        if: ${{ inputs.sign-app }}
+        run: |          
+          if [ ${{ vars.WAIT_FOR_NOTARIZE == 'true' }} ]; then
+            WAIT="--wait"
+          fi
+          echo "::debug::Submitting the disk image for notarization"
+          # Capture stdout+stderr (2>&1). Use || true so that when notarytool fails (e.g. Apple TOS
+          # agreement required), the script does not exit before we can print RESPONSE—otherwise the
+          # job would fail with no visible error message in the workflow log.
+          RESPONSE=$(xcrun notarytool submit ./bundle/${{ steps.bundle.outputs.artifact }} $WAIT --no-progress --apple-id ${{ vars.APPLE_DEV_EMAIL }} --password ${{ secrets.APPLE_DEV_PASSWORD }} --team-id ${{ secrets.APPLE_TEAM_ID }} 2>&1) || true
+          echo "$RESPONSE"
+          SUBMISSION_ID=$(echo "$RESPONSE" | awk '/id: / { print $2;exit; }')
+          echo "::notice::Notary Submission Id: $SUBMISSION_ID"
+
+          # Re-fail the step if submit failed (e.g. no submission id). The job still fails, but the
+          # output above is now visible in the log so we can see the real error (e.g. sign agreement).
+          if [ -z "$SUBMISSION_ID" ]; then
+            echo "::error::Notarization submit failed. See output above for details (e.g. Apple TOS agreement)."
+            exit 1
+          fi
+
+          if [ ${{ vars.WAIT_FOR_NOTARIZE == 'true' }} ]; then
+            echo "::debug::Stapling the notarization ticket to the disk image"
+            xcrun stapler staple "./bundle/${{ steps.bundle.outputs.artifact }}"
+          fi
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: ${{ steps.bundle.outputs.artifact }}
+          path: ./bundle/${{ steps.bundle.outputs.artifact }}
+          if-no-files-found: error
+          retention-days: ${{ inputs.retention-days }}

.github/workflows/build-windows.yml

@@ -6,80 +6,125 @@ name: build
 on:
   workflow_call:
     inputs:
-      version_override:
+      libation-version:
         type: string
-        description: 'Version number override'
-        required: false
-      run_unit_tests:
+        required: true
+      dotnet-version:
+        type: string
+        required: true
+      run-unit-tests:
         type: boolean
-        description: 'Skip running unit tests'
-        required: false
-        default: true
-
-env:
-  DOTNET_CONFIGURATION: 'Release'
-  DOTNET_VERSION: '7.0.x'
+      publish-r2r:
+        type: boolean
+      build-installer:
+        type: boolean
+        description: "Build *-setup.exe on all Windows matrix jobs when release (zips always built for .releaseindex.json)"
+        default: false
+      retention-days:
+        type: number
 
 jobs:
   build:
+    name: "Windows-${{ matrix.release_name }}-${{ matrix.architecture }} (${{ matrix.ui }})"
     runs-on: windows-latest
     strategy:
       matrix:
-        os: [Windows]
         ui: [Avalonia]
+        architecture: [x64]
         release_name: [chardonnay]
+        artifact_stem: [Libation]
         include:
-          - os: Windows
+          - architecture: x64
             ui: WinForms
             release_name: classic
-            prefix: Classic-
+            artifact_stem: Libation-Classic
+          - architecture: arm64
+            ui: Avalonia
+            release_name: chardonnay
+            artifact_stem: Libation
     steps:
-      - uses: actions/checkout@v3
-      - name: Setup .NET
-        uses: actions/setup-dotnet@v3
+      - uses: actions/checkout@v7
+      
+      - uses: actions/setup-dotnet@v6
         with:
-          dotnet-version: ${{ env.DOTNET_VERSION }}
-        env:
-          NUGET_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Get version
-        id: get_version
-        run: |
-          if ("${{ inputs.version_override }}".length -gt 0) {
-            $version = "${{ inputs.version_override }}"
-          } else {
-            $version = (Select-Xml -Path "./Source/AppScaffolding/AppScaffolding.csproj" -XPath "/Project/PropertyGroup/Version").Node.InnerXML.Trim()
-          }
-          "version=$version" >> $env:GITHUB_OUTPUT
+          dotnet-version: ${{ inputs.dotnet-version }}
+          dotnet-quality: "ga"
 
       - name: Unit test
-        if: ${{ inputs.run_unit_tests }}
+        if: ${{ inputs.run-unit-tests }}
         working-directory: ./Source
         run: dotnet test
-
+        
       - name: Publish
         working-directory: ./Source
         run: |
-          dotnet publish -c ${{ env.DOTNET_CONFIGURATION }} -o bin/Publish/${{ matrix.os }}-${{ matrix.release_name }} Libation${{ matrix.ui }}/Libation${{ matrix.ui }}.csproj -p:PublishProfile=Libation${{ matrix.ui }}/Properties/PublishProfiles/${{ matrix.os }}Profile.pubxml
-          dotnet publish -c ${{ env.DOTNET_CONFIGURATION }} -o bin/Publish/${{ matrix.os }}-${{ matrix.release_name }} LoadByOS/${{ matrix.os }}ConfigApp/${{ matrix.os }}ConfigApp.csproj -p:PublishProfile=LoadByOS/Properties/${{ matrix.os }}ConfigApp/PublishProfiles/${{ matrix.os }}Profile.pubxml
-          dotnet publish -c ${{ env.DOTNET_CONFIGURATION }} -o bin/Publish/${{ matrix.os }}-${{ matrix.release_name }} LibationCli/LibationCli.csproj -p:PublishProfile=LibationCli/Properties/PublishProfiles/${{ matrix.os }}Profile.pubxml
-          dotnet publish -c ${{ env.DOTNET_CONFIGURATION }} -o bin/Publish/${{ matrix.os }}-${{ matrix.release_name }} Hangover${{ matrix.ui }}/Hangover${{ matrix.ui }}.csproj -p:PublishProfile=Hangover${{ matrix.ui }}/Properties/PublishProfiles/${{ matrix.os }}Profile.pubxml
+          $PUBLISH_ARGS=@(
+            "--runtime", "win-${{ matrix.architecture }}",
+            "--configuration", "Release",
+            "--output", "../bin",
+            "-p:PublishProtocol=FileSystem",
+            "-p:PublishReadyToRun=${{ inputs.publish-r2r }}",
+            "-p:SelfContained=true")            
+          
+          dotnet publish "Libation${{ matrix.ui }}/Libation${{ matrix.ui }}.csproj" $PUBLISH_ARGS
+          dotnet publish "LoadByOS/WindowsConfigApp/WindowsConfigApp.csproj" $PUBLISH_ARGS
+          dotnet publish "LibationCli/LibationCli.csproj" $PUBLISH_ARGS
+          dotnet publish "Hangover${{ matrix.ui }}/Hangover${{ matrix.ui }}.csproj" $PUBLISH_ARGS
 
       - name: Zip artifact
         id: zip
-        working-directory: ./Source/bin/Publish
+        working-directory: ./bin
         run: |
-          $dir = "${{ matrix.os }}-${{ matrix.release_name }}\"
-          $delfiles = @("libmp3lame.so", "ffmpegaac.so", "glass-with-glow_256.svg", "Libation.desktop")
-          foreach ($file in $delfiles){ if (test-path $dir$file){ Remove-Item $dir$file } }
-          $artifact="${{ matrix.prefix }}Libation.${{ steps.get_version.outputs.version }}-" + "${{ matrix.os }}".ToLower() + "-${{ matrix.release_name }}"
-          "artifact=$artifact" >> $env:GITHUB_OUTPUT
-          Compress-Archive -Path "${dir}*" -DestinationPath "$artifact.zip"
-
-      - name: Publish artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: ${{ steps.zip.outputs.artifact }}.zip
-          path: ./Source/bin/Publish/${{ steps.zip.outputs.artifact }}.zip
-          if-no-files-found: error
+          $delfiles = @(
+            "WindowsConfigApp.exe",
+            "WindowsConfigApp.runtimeconfig.json",
+            "WindowsConfigApp.deps.json")
           
+          foreach ($file in $delfiles){ if (test-path $file){ Remove-Item $file } }
+          $artifact="${{ matrix.artifact_stem }}.${{ inputs.libation-version }}-windows-${{ matrix.release_name }}-${{ matrix.architecture }}.zip"
+          "artifact=$artifact" >> $env:GITHUB_OUTPUT
+          Compress-Archive -Path * -DestinationPath "$artifact"
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: ${{ steps.zip.outputs.artifact }}
+          path: ./bin/${{ steps.zip.outputs.artifact }}
+          if-no-files-found: error
+          retention-days: ${{ inputs.retention-days }}
+
+      - name: Install Inno Setup
+        if: ${{ inputs.build-installer }}
+        run: choco install innosetup -y --no-progress
+
+      - name: Build Windows installer
+        id: setup
+        if: ${{ inputs.build-installer }}
+        shell: pwsh
+        run: |
+          if ("${{ matrix.ui }}" -eq "WinForms") {
+            $setupName = "Libation-Classic.${{ inputs.libation-version }}-windows-${{ matrix.release_name }}-${{ matrix.architecture }}-setup.exe"
+            $ui = "WinForms"
+          } else {
+            $setupName = "Libation.${{ inputs.libation-version }}-windows-${{ matrix.release_name }}-${{ matrix.architecture }}-setup.exe"
+            $ui = "Avalonia"
+          }
+          ./Scripts/Windows/Build-WindowsInstaller.ps1 `
+            -Version "${{ inputs.libation-version }}" `
+            -Ui $ui `
+            -Architecture "${{ matrix.architecture }}" `
+            -SkipPublish `
+            -BinDir "${{ github.workspace }}/bin"
+          if (-not (Test-Path "${{ github.workspace }}/bin/$setupName")) {
+            throw "Installer not found: bin/$setupName"
+          }
+          "setup=$setupName" >> $env:GITHUB_OUTPUT
+
+      - name: Upload installer artifact
+        if: ${{ inputs.build-installer }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: ${{ steps.setup.outputs.setup }}
+          path: ./bin/${{ steps.setup.outputs.setup }}
+          if-no-files-found: error
+          retention-days: ${{ inputs.retention-days }}
+

.github/workflows/build.yml

@@ -6,25 +6,67 @@ name: build
 on:
   workflow_call:
     inputs:
-      version_override:
+      libation-version:
         type: string
-        description: 'Version number override'
-        required: false
-      run_unit_tests:
+        description: "Libation version number"
+        required: true
+      dotnet-version:
+        type: string
+        default: "10.x"
+        description: ".NET version to target"
+      run-unit-tests:
         type: boolean
-        description: 'Skip running unit tests'
-        required: false
-        default: true        
+        description: "Whether to run unit tests prior to publishing."
+      publish-r2r:
+        type: boolean
+        description: "Whether to publish assemblies as ReadyToRun."
+      release:
+        type: boolean
+        description: "Whether this workflow is being called as a release"
+      retention-days:
+        type: number
+        description: "Number of days the artifacts are to be retained."
 
-jobs:
+jobs:    
   windows:
     uses: ./.github/workflows/build-windows.yml
     with:
-      version_override: ${{ inputs.version_override }}
-      run_unit_tests: ${{ inputs.run_unit_tests }}
+      libation-version: ${{ inputs.libation-version }}
+      dotnet-version: ${{ inputs.dotnet-version }}
+      run-unit-tests: ${{ inputs.run-unit-tests }}
+      publish-r2r: ${{ inputs.publish-r2r }}
+      build-installer: ${{ inputs.release }}
+      retention-days: ${{ inputs.retention-days }}
+      
+  macOS:
+    strategy:
+      matrix:
+        architecture: [x64, arm64]
+    uses: ./.github/workflows/build-mac.yml
+    with:
+      libation-version: ${{ inputs.libation-version }}
+      dotnet-version: ${{ inputs.dotnet-version }}
+      run-unit-tests: ${{ inputs.run-unit-tests }}
+      publish-r2r: ${{ inputs.publish-r2r }}
+      retention-days: ${{ inputs.retention-days }}
+      architecture: ${{ matrix.architecture }}
+      sign-app: ${{ inputs.release || vars.SIGN_MAC_APP_ON_VALIDATE == 'true' }}
+    secrets: inherit
 
   linux:
+    strategy:
+      matrix:
+        OS: [Redhat, Debian]
+        architecture: [x64, arm64]
     uses: ./.github/workflows/build-linux.yml
     with:
-      version_override: ${{ inputs.version_override }}
-      run_unit_tests: ${{ inputs.run_unit_tests }}     
+      libation-version: ${{ inputs.libation-version }}
+      dotnet-version: ${{ inputs.dotnet-version }}
+      run-unit-tests: ${{ inputs.run-unit-tests }}
+      publish-r2r: ${{ inputs.publish-r2r }}
+      retention-days: ${{ inputs.retention-days }}
+      architecture: ${{ matrix.architecture }}
+      OS: ${{ matrix.OS }}
+
+
+

.github/workflows/deb.yml

@@ -1,38 +0,0 @@
-# deb.yml
-# Reusable workflow that builds the Linux Debian package.
----
-name: deb
-
-on:
-  workflow_call:
-    inputs:
-      version:
-        type: string
-        description: 'Version number'
-        required: true
-
-env:
-  FILE_NAME: "Libation.${{ inputs.version }}-linux-chardonnay"
-  
-jobs:
-  build_deb:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      
-      - name: Download Artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: "${{ env.FILE_NAME }}.tar.gz"
-
-      - name: Build .deb
-        id: deb
-        run: |
-          ./Scripts/targz2deb.sh "${{ env.FILE_NAME }}.tar.gz" ${{ inputs.version }}
-      
-      - name: Publish .deb
-        uses: actions/upload-artifact@v3
-        with:
-          name: ${{ env.FILE_NAME }}.deb
-          path: ${{ env.FILE_NAME }}.deb
-          if-no-files-found: error

.github/workflows/deploy.yml

@@ -0,0 +1,71 @@
+name: Deploy VitePress site to Pages
+
+on:
+  # Runs on pushes targeting the `main` branch. Change this to `master` if you're
+  # using the `master` branch as the default branch.
+  push:
+    branches: [master]
+    paths:
+      - .github/workflows/deploy.yml
+      - docs/**
+      - .vitepress/**
+      - index.md
+      - package.json
+      - package-lock.json
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+        with:
+          fetch-depth: 0 # Not needed if lastUpdated is not enabled
+      # - uses: pnpm/action-setup@v4 # Uncomment this block if you're using pnpm
+      #   with:
+      #     version: 9 # Not needed if you've set "packageManager" in package.json
+      # - uses: oven-sh/setup-bun@v1 # Uncomment this if you're using Bun
+      - name: Setup Node
+        uses: actions/setup-node@v7
+        with:
+          node-version: 24
+          cache: npm # or pnpm / yarn
+      - name: Setup Pages
+        uses: actions/configure-pages@v6
+      - name: Install dependencies
+        run: npm ci # or pnpm install / yarn install / bun install
+      - name: Build with VitePress
+        run: npm run docs:build # or pnpm docs:build / yarn docs:build / bun run docs:build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: .vitepress/dist
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    needs: build
+    runs-on: ubuntu-latest
+    name: Deploy
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5

.github/workflows/docker.yml

@@ -8,7 +8,11 @@ on:
     inputs:
       version:
         type: string
-        description: 'Version number'
+        description: "Version number"
+        required: true
+      release:
+        type: boolean
+        description: "Is this a release build?"
         required: true
     secrets:
       docker_username:
@@ -16,31 +20,48 @@ on:
       docker_token:
         required: true
 
-env:
-  DOCKER_IMAGE: ${{ secrets.docker_username }}/libation
-
 jobs:
-  docker:
+  build_and_push:
     runs-on: ubuntu-latest
+
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v2
+        uses: docker/setup-qemu-action@v4
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v4
 
       - name: Login to Docker Hub
-        uses: docker/login-action@v2
+        if: ${{ inputs.release }}
+        uses: docker/login-action@v4.5.2
         with:
           username: ${{ secrets.docker_username }}
           password: ${{ secrets.docker_token }}
 
-      - name: Build and push
-        uses: docker/build-push-action@v4
+      - name: Generate docker image tags
+        id: metadata
+        uses: docker/metadata-action@v6
         with:
-          push: true
-          build-args: 'FOLDER_NAME=Linux-chardonnay'
-          tags: ${{ env.DOCKER_IMAGE }}:latest,${{ env.DOCKER_IMAGE }}:${{ inputs.version }}
+          flavor: |
+            latest=true
+          images: |
+            name=${{ secrets.docker_username }}/libation
+          tags: |
+            type=raw,value=${{ inputs.version }},enable=${{ inputs.release }}
+
+      - name: Build and push image
+        uses: docker/build-push-action@v7
+        with:
+          # Avoid default git context refs/pull/*/merge (breaks after PR merge or on some re-runs).
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ steps.metadata.outputs.tags != ''}}
+          # Always read cache. Only write on release so PR validate cannot fail
+          # when GHA cache is full or the token cannot write cache.
+          cache-from: type=gha
+          cache-to: ${{ inputs.release && 'type=gha,mode=max,ignore-error=true' || '' }}
+          tags: ${{ steps.metadata.outputs.tags }}
+          labels: ${{ steps.metadata.outputs.labels }}

.github/workflows/exempt-creators-backfill.yml

@@ -0,0 +1,67 @@
+# One-time or occasional backfill: add `exempt` to open issues/PRs opened by
+# rmcrackan or Mbucari that predate exempt-creators.yml. Run from Actions →
+# "Exempt creators backfill" → Run workflow.
+---
+name: Exempt creators backfill
+
+on:
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  backfill:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v9
+        with:
+          script: |
+            const exemptLabel = 'exempt';
+            const creators = new Set(['rmcrackan', 'mbucari']);
+
+            const owner = context.repo.owner;
+            const repo = context.repo.repo;
+
+            const items = await github.paginate(github.rest.issues.listForRepo, {
+              owner,
+              repo,
+              state: 'open',
+              per_page: 100,
+            });
+
+            let labeled = 0;
+            let notCreator = 0;
+            let alreadyExempt = 0;
+
+            for (const item of items) {
+              const login = item.user && item.user.login;
+              if (!login || !creators.has(login.toLowerCase())) {
+                notCreator++;
+                continue;
+              }
+
+              const names = item.labels.map((l) => l.name);
+              if (names.some((n) => n.toLowerCase() === exemptLabel)) {
+                alreadyExempt++;
+                continue;
+              }
+
+              try {
+                await github.rest.issues.addLabels({
+                  owner,
+                  repo,
+                  issue_number: item.number,
+                  labels: [exemptLabel],
+                });
+                labeled++;
+              } catch (e) {
+                core.warning(`#${item.number}: ${e.message}`);
+              }
+            }
+
+            core.info(
+              `Backfill done: added exempt to ${labeled} item(s); ` +
+                `${alreadyExempt} already had exempt; ${notCreator} not from rmcrackan/Mbucari.`
+            );

.github/workflows/exempt-creators.yml

@@ -0,0 +1,39 @@
+# Assigns the `exempt` label to issues and PRs opened by maintainer accounts so
+# stale.yml does not mark them stale. See issue #1532.
+# For issues/PRs opened before this existed, run workflow "Exempt creators backfill".
+# Pattern: https://github.com/Asperguide/asper-header/blob/main/.github/workflows/exempt-creators.yml
+---
+name: Exempt specific creators
+
+on:
+  issues:
+    types: [opened]
+  pull_request:
+    types: [opened]
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  exempt:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Add exempt label
+        if: >-
+          (github.event_name == 'issues' &&
+          contains(fromJSON('["rmcrackan","Mbucari"]'), github.event.issue.user.login)) ||
+          (github.event_name == 'pull_request' &&
+          contains(fromJSON('["rmcrackan","Mbucari"]'), github.event.pull_request.user.login))
+        uses: actions/github-script@v9
+        with:
+          script: |
+            const number = context.issue?.number || context.payload.pull_request?.number;
+            const repo = context.repo;
+            if (number) {
+              await github.rest.issues.addLabels({
+                ...repo,
+                issue_number: number,
+                labels: ['exempt'],
+              });
+            }

.github/workflows/release.yml

@@ -5,17 +5,17 @@ name: release
 on:
   push:
     tags:
-      - 'v*'
+      - "v*"
 jobs:
   prerelease:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-slim
     outputs:
       version: ${{ steps.get_version.outputs.version }}
     steps:
       - name: Get tag version
         id: get_version
         run: |
-          export TAG='${{ github.ref_name }}'
+          export TAG="${{ github.ref_name }}"
           echo "version=${TAG#v}" >> "${GITHUB_OUTPUT}"
 
   docker:
@@ -23,6 +23,7 @@ jobs:
     uses: ./.github/workflows/docker.yml
     with:
       version: ${{ needs.prerelease.outputs.version }}
+      release: true
     secrets:
       docker_username: ${{ secrets.DOCKERHUB_USERNAME }}
       docker_token: ${{ secrets.DOCKERHUB_TOKEN }}
@@ -30,38 +31,38 @@ jobs:
   build:
     needs: [prerelease]
     uses: ./.github/workflows/build.yml
+    secrets: inherit
     with:
-      version_override: ${{ needs.prerelease.outputs.version }}
-      run_unit_tests: false
+      libation-version: ${{ needs.prerelease.outputs.version }}
+      publish-r2r: true
+      release: true
 
-  deb:
-    needs: [prerelease,build]
-    uses: ./.github/workflows/deb.yml
-    with:
-      version: ${{ needs.prerelease.outputs.version }}
-      
   release:
-    needs: [prerelease,build,deb]
+    needs: [prerelease, build]
     runs-on: ubuntu-latest
     steps:
-      - name: Download artifacts
-        uses: actions/download-artifact@v3
+      - name: Download Chardonnay, Linux, and Mac artifacts
+        uses: actions/download-artifact@v8
         with:
           path: artifacts
+          pattern: "Libation.*"
+          merge-multiple: true
+
+      - name: Download Classic Windows artifacts
+        uses: actions/download-artifact@v8
+        with:
+          path: artifacts
+          pattern: "Libation-Classic.*"
+          merge-multiple: true
 
       - name: Release
         id: release
-        uses: softprops/action-gh-release@v1
+        uses: softprops/action-gh-release@v3
         with:
           name: Libation ${{ needs.prerelease.outputs.version }}
-          body: <Put a body here>
+          body: "<Put a body here>"
+          token: ${{ secrets.GITHUB_TOKEN }}
           draft: true
           prerelease: false
-
-      - name: Upload release assets
-        uses: dwenegar/upload-release-assets@v1
-        env:
-          GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
-        with:
-          release_id: '${{ steps.release.outputs.id }}'
-          assets_path: ./artifacts
+          files: |
+            artifacts/*

.github/workflows/stale.yml

@@ -0,0 +1,66 @@
+# Marks inactive issues/PRs stale and closes them after a further quiet period.
+# Exempt labels include `enhancement`, `exempt` (from exempt-creators.yml), and others below.
+# Pattern: https://github.com/Asperguide/asper-header/blob/main/.github/workflows/stale.yml
+---
+name: Close stale issues and PRs
+
+on:
+  schedule:
+    - cron: '0 0 * * *'
+  workflow_dispatch:
+
+permissions:
+  issues: write
+  pull-requests: write
+
+jobs:
+  stale:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/stale@v11
+        with:
+          days-before-stale: 30
+          days-before-close: 14
+          operations-per-run: 100
+
+          stale-issue-message: |
+            This issue has been automatically marked as stale because it has not had any activity for 30 days.
+
+            It will be closed in 14 days if no further activity occurs.
+
+            If this issue is still relevant, please leave a comment to keep it open.
+            Thank you for your contributions to Libation.
+
+          close-issue-message: |
+            This issue has been automatically closed due to inactivity.
+
+            If you believe this issue is still relevant, please reopen it or create a new issue with updated information.
+            Thank you for your understanding.
+
+          stale-issue-label: stale
+
+          stale-pr-message: |
+            This pull request has been automatically marked as stale because it has not had any activity for 30 days.
+
+            It will be closed in 14 days if no further activity occurs.
+
+            If you're still working on this PR, please leave a comment to keep it open.
+            Thank you for your contribution.
+
+          close-pr-message: |
+            This pull request has been automatically closed due to inactivity.
+
+            If you'd like to continue working on this, please reopen the PR or submit a new one.
+            Thank you for your contribution.
+
+          stale-pr-label: stale
+
+          exempt-issue-labels: 'priority: critical,priority: high,security,help wanted,good first issue,needs-discussion,enhancement,exempt'
+          exempt-pr-labels: 'priority: critical,priority: high,security,enhancement,exempt'
+
+          exempt-all-milestones: true
+          exempt-all-assignees: false
+          exempt-draft-pr: true
+          ascending: true
+          remove-stale-when-updated: true
+          debug-only: false

.github/workflows/sync-labels.yml

@@ -0,0 +1,29 @@
+# Ensures labels referenced by exempt-creators / stale workflows exist.
+# Optional per #1532 — run workflow_dispatch if labels are missing.
+# Pattern: https://github.com/Asperguide/asper-header/blob/main/.github/workflows/sync-labels.yml
+---
+name: Sync labels
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - '.github/labels.yml'
+  workflow_dispatch:
+
+permissions:
+  issues: write
+
+jobs:
+  sync-labels:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Sync labels
+        uses: micnncim/action-label-syncer@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          manifest: .github/labels.yml
+          prune: false

.github/workflows/validate-appstream-metainfo.yaml

@@ -0,0 +1,22 @@
+name: Validate MetaInfo
+"on":
+  pull_request:
+    branches: ["master"]
+    paths:
+      - .github/workflows/validate-appstream-metainfo.yml
+      - Source/LoadByOS/LinuxConfigApp/com.getlibation.Libation.metainfo.xml
+  push:
+    branches: ["master"]
+    paths:
+      - .github/workflows/validate-appstream-metainfo.yml
+      - Source/LoadByOS/LinuxConfigApp/com.getlibation.Libation.metainfo.xml
+
+jobs:
+  validate-appstream-metainfo:
+    runs-on: ubuntu-latest
+    container:
+      image: ghcr.io/flathub/flatpak-builder-lint:latest
+    steps:
+      - uses: actions/checkout@v7
+      - name: Check the MetaInfo file
+        run: flatpak-builder-lint appstream Source/LoadByOS/LinuxConfigApp/com.getlibation.Libation.metainfo.xml

.github/workflows/validate-desktop-file.yaml

@@ -0,0 +1,21 @@
+name: Check desktop file
+"on":
+  pull_request:
+    branches: ["master"]
+    paths:
+      - .github/workflows/validate-desktop-file.yml
+      - Source/LoadByOS/LinuxConfigApp/Libation.desktop
+  push:
+    branches: ["master"]
+    paths:
+      - .github/workflows/validate-desktop-file.yml
+      - Source/LoadByOS/LinuxConfigApp/Libation.desktop
+
+jobs:
+  validate-desktop-file:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - run: sudo apt --yes install desktop-file-utils
+      - name: Check the desktop file
+        run: desktop-file-validate Source/LoadByOS/LinuxConfigApp/Libation.desktop

.github/workflows/validate.yml

@@ -1,14 +1,47 @@
 # validate.yml
-# Validates that Libation will build on a pull request or push to master. 
+# Validates that Libation will build on a pull request or push to master.
 ---
 name: validate
 
 on:
   push:
     branches: [master]
+    paths:
+      - Source/**
+      - .github/workflows/**
   pull_request:
     branches: [master]
+    paths:
+      - Source/**
+      - .github/workflows/**
 
 jobs:
+  get_version:
+    runs-on: ubuntu-slim
+    outputs:
+      version: ${{ steps.get_version.outputs.version }}
+    steps:
+      - name: Get version
+        id: get_version
+        run: |
+          wget "https://raw.githubusercontent.com/${{ github.repository }}/${{ github.sha }}/Source/AppScaffolding/AppScaffolding.csproj"
+          version="$(grep -Eio -m 1 '<Version>.*</Version>' ./AppScaffolding.csproj | sed -r 's/<\/?Version>//g')"
+          echo "version=${version}" >> "${GITHUB_OUTPUT}"
   build:
+    needs: [get_version]
     uses: ./.github/workflows/build.yml
+    secrets: inherit
+    with:
+      libation-version: ${{ needs.get_version.outputs.version }}
+      retention-days: 14
+      run-unit-tests: true
+      
+  docker:
+    needs: [get_version]
+    uses: ./.github/workflows/docker.yml
+    with:
+      version: ${{ needs.get_version.outputs.version }}
+      release: false
+    secrets:
+      docker_username: ${{ secrets.DOCKERHUB_USERNAME }}
+      docker_token: ${{ secrets.DOCKERHUB_TOKEN }}

.gitignore

@@ -370,4 +370,15 @@ FodyWeavers.xsd
 
 /__TODO.txt
 /DataLayer/LibationContext.db
-*/bin-Avalonia
+*/bin-Avalonia
+
+# macOS Directory Info
+.DS_Store
+
+# JetBrains Rider Settings
+**/.idea/
+
+# VitePress
+node_modules
+.vitepress/cache
+.vitepress/dist   

.releaseindex.json

@@ -1,6 +1,12 @@
 {
-  "WindowsClassic":  "Libation\\.\\d+\\.\\d+\\.\\d+-win(dows)?-classic\\.zip",
-  "WindowsAvalonia": "Libation\\.\\d+\\.\\d+\\.\\d+-win(dows)?-chardonnay\\.zip",
-  "LinuxAvalonia":   "Libation\\.\\d+\\.\\d+\\.\\d+-linux-chardonnay",
-  "MacOSAvalonia":   "Libation\\.\\d+\\.\\d+\\.\\d+-macos-chardonnay"
+  "WindowsClassic":          "(?:Classic-Libation|Libation-Classic)\\.\\d+\\.\\d+\\.\\d+(?:\\.\\d+)?-win(?:dows)?-classic-x64\\.zip",
+  "WindowsAvalonia":         "Libation\\.\\d+\\.\\d+\\.\\d+(?:\\.\\d+)?-win(?:dows)?-chardonnay-x64\\.zip",
+  "WindowsAvalonia_Arm64":   "Libation\\.\\d+\\.\\d+\\.\\d+(?:\\.\\d+)?-win(?:dows)?-chardonnay-arm64\\.zip",
+  "LinuxAvalonia":           "Libation\\.\\d+\\.\\d+\\.\\d+(?:\\.\\d+)?-linux-chardonnay-amd64\\.deb",
+  "LinuxAvalonia_DEB":       "Libation\\.\\d+\\.\\d+\\.\\d+(?:\\.\\d+)?-linux-chardonnay-amd64\\.deb",
+  "LinuxAvalonia_RPM":       "Libation\\.\\d+\\.\\d+\\.\\d+(?:\\.\\d+)?-linux-chardonnay-amd64\\.rpm",
+  "MacOSAvalonia":           "Libation\\.\\d+\\.\\d+\\.\\d+(?:\\.\\d+)?-macOS-chardonnay-x64\\.dmg",
+  "LinuxAvalonia_Arm64":     "Libation\\.\\d+\\.\\d+\\.\\d+(?:\\.\\d+)?-linux-chardonnay-arm64\\.deb",
+  "LinuxAvalonia_Arm64_RPM": "Libation\\.\\d+\\.\\d+\\.\\d+(?:\\.\\d+)?-linux-chardonnay-arm64\\.rpm",
+  "MacOSAvalonia_Arm64":     "Libation\\.\\d+\\.\\d+\\.\\d+(?:\\.\\d+)?-macOS-chardonnay-arm64\\.dmg"
 }

.vitepress/config.js

@@ -0,0 +1,148 @@
+import { defineConfig } from "vitepress";
+
+// https://vitepress.dev/reference/site-config
+export default defineConfig({
+  vite: {
+    // esbuild 0.28+ will not downlevel destructuring for safari14 / chrome87.
+    // Raise the target so docs:dev and docs:build do not need that transform.
+    build: {
+      target: "es2022",
+    },
+    optimizeDeps: {
+      esbuildOptions: {
+        target: "es2022",
+      },
+    },
+    esbuild: {
+      supported: {
+        destructuring: true,
+      },
+    },
+    // Avoid watching the C# solution / VS locks (EBUSY on .vsidx files).
+    server: {
+      watch: {
+        ignored: ["**/Source/**", "**/.vs/**", "**/bin/**", "**/obj/**"],
+      },
+    },
+  },
+  title: "Libation",
+  description:
+    "Libation: Liberate your Library - A free application for downloading your Audible audiobooks",
+  head: [["link", { rel: "icon", href: "/favicon.ico" }]],
+  cleanUrls: true,
+  themeConfig: {
+    // https://vitepress.dev/reference/default-theme-config
+    logo: {
+      light: "/libation_logo_light.svg",
+      dark: "/libation_logo_dark.svg",
+    },
+
+    footer: {
+      message: "Released under the GPLv3 License",
+    },
+
+    editLink: {
+      pattern: "https://github.com/rmcrackan/Libation/edit/master/:path",
+    },
+
+    lastUpdated: true,
+
+    nav: [
+      { text: "Getting Started", link: "/docs/getting-started" },
+      { text: "Docs", link: "/docs/index" },
+      {
+        text: "Download",
+        link: "https://github.com/rmcrackan/Libation/releases/latest",
+      },
+      {
+        text: "Issues & Requests",
+        link: "https://github.com/rmcrackan/Libation/issues",
+      },
+      { text: "Donate", link: "/donate" },
+    ],
+    sidebar: [
+      {
+        items: [
+          { text: "Overview", link: "/docs/index" },
+          { text: "Getting Started", link: "/docs/getting-started" },
+          { text: "FAQ", link: "/docs/frequently-asked-questions" },
+          {
+            text: "Issues & Requests",
+            link: "https://github.com/rmcrackan/Libation/issues",
+          },
+          { text: "Donate", link: "/donate" },
+        ],
+      },
+      {
+        text: "Installation",
+        collapsed: false,
+        items: [
+          { text: "Linux", link: "/docs/installation/linux" },
+          { text: "Mac", link: "/docs/installation/mac" },
+          { text: "Docker", link: "/docs/installation/docker" },
+        ],
+      },
+      {
+        text: "Features",
+        collapsed: false,
+        items: [
+          {
+            text: "Audio File Formats",
+            link: "/docs/features/audio-file-formats",
+          },
+          {
+            text: "Audiobookshelf Auto-Upload",
+            link: "/docs/features/audiobookshelf",
+          },
+          { text: "Naming Templates", link: "/docs/features/naming-templates" },
+          {
+            text: "Searching & Filtering",
+            link: "/docs/features/searching-and-filtering",
+          },
+          {
+            text: "Easy guide to searching",
+            link: "/docs/features/lucene",
+          },
+        ],
+      },
+      {
+        text: "Advanced",
+        collapsed: false,
+        items: [
+          { text: "Advanced Topics", link: "/docs/advanced/advanced" },
+          { text: "Command Line Interface", link: "/docs/advanced/command-line-interface" },
+          { text: "Troubleshooting", link: "/docs/advanced/troubleshoot" },
+          { text: "Spatial Audio & DRM", link: "/docs/advanced/spatial-audio" },
+        ],
+      },
+      {
+        text: "Development",
+        collapsed: false,
+        items: [
+          {
+            text: "Getting Started",
+            link: "/docs/development/getting-started",
+          },
+          { text: "Contribute", link: "/docs/development/contribute" },
+          { text: "Website & Docs", link: "/docs/development/website" },
+          { text: "Linux Setup (Nix)", link: "/docs/development/nix-linux-setup" },
+        ],
+      },
+    ],
+
+    outline: {
+      level: "deep",
+    },
+
+    socialLinks: [
+      { icon: "github", link: "https://github.com/rmcrackan/Libation" },
+    ],
+
+    search: {
+      provider: "local",
+    },
+
+    // Show the external-link arrow on outbound links in markdown (nav/sidebar already do).
+    externalLinkIcon: true,
+  },
+});

.vitepress/theme/DownloadSuggestionWidget.vue

@@ -0,0 +1,259 @@
+<script setup>
+import { ref, computed, onMounted, watch } from 'vue'
+import { getDetectOS } from './download-detection.js'
+
+const PREVIEW_OPTIONS = [
+  { value: '', label: 'Current system' },
+  { value: 'windows|x64', label: 'Windows (x64)' },
+  { value: 'windows|arm64', label: 'Windows (arm64)' },
+  { value: 'mac|x64', label: 'Mac (x64)' },
+  { value: 'mac|arm64', label: 'Mac (arm64)' },
+  { value: 'linux|x64|', label: 'Linux (x64)' },
+  { value: 'linux|x64|Ubuntu', label: 'Linux Ubuntu (x64)' },
+  { value: 'linux|x64|Fedora', label: 'Linux Fedora (x64)' },
+  { value: 'linux|arm64|', label: 'Linux (arm64)' },
+  { value: 'linux|arm64|Ubuntu', label: 'Linux Ubuntu (arm64)' },
+  { value: 'linux|arm64|Fedora', label: 'Linux Fedora (arm64)' },
+]
+
+const INSTALL_MAC_URL = 'https://getlibation.com/docs/installation/mac'
+const INSTALL_LINUX_URL = 'https://getlibation.com/docs/installation/linux'
+
+const status = ref('loading') // 'loading' | 'ready' | 'error'
+const errorMessage = ref('')
+const cachedAssets = ref([])
+const rec = ref(null)
+const blockHead = ref('')
+const previewValue = ref('')
+const installGuideUrl = ref(null)
+const installGuideLabel = ref('')
+const d = ref(null)
+
+function getPreviewOverrides() {
+  if (!previewValue.value) return null
+  const parts = previewValue.value.split('|')
+  const overrides = { os: parts[0], architecture: parts[1] }
+  if (parts.length > 2 && parts[2]) overrides.linuxFlavor = parts[2]
+  return overrides
+}
+
+function recommendedForLabel(overrides) {
+  if (!d.value) return 'Recommended download for your system'
+  const os = (overrides && overrides.os) || d.value.os
+  const ver = (overrides && overrides.osVersion) || d.value.osVersion
+  const arch = (overrides && overrides.architecture) || d.value.architecture
+  const flavor = (overrides && overrides.linuxFlavor !== undefined) ? overrides.linuxFlavor : d.value.linuxFlavor
+  if (os === 'windows') return 'Recommended download for Windows (' + arch + ')'
+  if (os === 'mac') return 'Recommended download for Mac ' + (ver ? ver + ' ' : '') + '(' + arch + ')'
+  if (os === 'linux') return 'Recommended download for ' + (flavor ? flavor + ' ' : '') + 'Linux (' + arch + ')'
+  return 'Recommended download for your system'
+}
+
+function updateRecommendation() {
+  if (!cachedAssets.value.length || !d.value) return
+  const overrides = getPreviewOverrides()
+  rec.value = d.value.recommendDownload(cachedAssets.value, overrides)
+  blockHead.value = recommendedForLabel(overrides)
+  const os = (overrides && overrides.os) || d.value.os
+  if (os === 'mac') {
+    installGuideUrl.value = INSTALL_MAC_URL
+    installGuideLabel.value = 'Install on macOS'
+  } else if (os === 'linux') {
+    installGuideUrl.value = INSTALL_LINUX_URL
+    installGuideLabel.value = 'Install on Linux'
+  } else {
+    installGuideUrl.value = null
+    installGuideLabel.value = ''
+  }
+}
+
+const showReasonWarn = computed(() => {
+  return rec.value?.reason && rec.value.reason !== 'Recommended for your system.'
+})
+
+const showAssets = computed(() => {
+  if (!rec.value || !d.value || status.value !== 'ready') return []
+  const libationAssets = cachedAssets.value
+  const overrides = getPreviewOverrides()
+  const os = (overrides && overrides.os) || d.value.os
+  const arch = (overrides && overrides.architecture) || d.value.architecture
+  return libationAssets.filter((a) => {
+    const p = d.value.parseAssetFilename(a.name)
+    if (!p) return false
+    if (os === 'windows' || os === 'mac' || os === 'linux') {
+      if (p.platform !== os) return false
+    }
+    if (arch === 'x64' || arch === 'arm64') {
+      if (p.arch !== arch) return false
+    }
+    return true
+  })
+})
+
+watch(previewValue, () => updateRecommendation())
+
+onMounted(() => {
+  d.value = getDetectOS()
+  fetch('https://api.github.com/repos/rmcrackan/Libation/releases/latest')
+    .then((res) => (res.ok ? res.json() : Promise.reject(new Error('Failed to load release'))))
+    .then((release) => {
+      cachedAssets.value = (release.assets || []).map((a) => ({
+        name: a.name,
+        url: a.browser_download_url,
+      }))
+      status.value = 'ready'
+      updateRecommendation()
+    })
+    .catch((err) => {
+      status.value = 'error'
+      errorMessage.value = err.message || 'Could not load latest release.'
+    })
+})
+</script>
+
+<template>
+  <div class="download-widget-wrapper">
+    <div v-if="status === 'loading'" class="download-widget recommended">
+      Loading latest release…
+    </div>
+    <div v-else-if="status === 'error'" class="download-widget recommended">
+      <p class="warn">{{ errorMessage }}</p>
+    </div>
+    <div v-else class="download-widget recommended">
+      <div class="block-head">
+        <svg class="icon-download" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+          <path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" />
+          <polyline points="7 10 12 15 17 10" />
+          <line x1="12" y1="15" x2="12" y2="3" />
+        </svg>
+        <span>{{ blockHead }}{{ rec?.windowsX64Choice ? ':' : rec?.recommended ? ':' : rec ? '.' : '' }}</span>
+        <select v-model="previewValue" aria-label="Find recommended download for" class="preview-select">
+          <option v-for="o in PREVIEW_OPTIONS" :key="o.value || 'current'" :value="o.value">
+            {{ o.label }}
+          </option>
+        </select>
+      </div>
+
+      <!-- Windows x64: Chardonnay + Classic -->
+      <template v-if="rec?.windowsX64Choice">
+        <ul class="widget-list">
+          <li><strong>Chardonnay</strong> (modern UI): <a :href="rec.windowsX64Choice.chardonnay.url" download>{{ rec.windowsX64Choice.chardonnay.name }}</a></li>
+          <li><strong>Classic</strong> (compact, screenreader-friendly): <a :href="rec.windowsX64Choice.classic.url" download>{{ rec.windowsX64Choice.classic.name }}</a></li>
+        </ul>
+        <p class="widget-link"><a :href="rec.classicVsChardonnayFaqUrl" target="_blank" rel="noopener">What's the difference between Classic and Chardonnay?</a></p>
+        <p v-if="showReasonWarn" class="warn">{{ rec.reason }}</p>
+      </template>
+
+      <!-- Single recommended -->
+      <template v-else-if="rec?.recommended">
+        <p class="widget-download"><a :href="rec.recommended.url" download>{{ rec.recommended.name }}</a></p>
+        <p v-if="installGuideUrl" class="widget-link">
+          <a :href="installGuideUrl" target="_blank" rel="noopener">{{ installGuideLabel }}</a>
+        </p>
+        <p v-if="showReasonWarn" class="warn">{{ rec.reason }}</p>
+        <div v-if="rec.alternatives?.length" class="alternatives">
+          {{ rec.alternatives.length === 1 ? 'Another option:' : 'Other options:' }}
+          <ul>
+            <li v-for="a in rec.alternatives" :key="a.name">
+              <a :href="a.url" download>{{ a.name }}</a>
+            </li>
+          </ul>
+        </div>
+      </template>
+
+      <!-- No match -->
+      <template v-else-if="rec">
+        <p class="warn">{{ rec.reason || 'Could not recommend a download.' }}</p>
+        <div class="alternatives">
+          Available:
+          <ul>
+            <li v-for="a in showAssets" :key="a.name">
+              <a :href="a.url" download>{{ a.name }}</a>
+            </li>
+          </ul>
+        </div>
+      </template>
+    </div>
+  </div>
+</template>
+
+<style scoped>
+.download-widget-wrapper {
+  margin: 1.5rem auto;
+  max-width: 42rem;
+}
+.download-widget.recommended {
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  padding: 0.75rem 1rem;
+  border-radius: 8px;
+  font-weight: 600;
+}
+.download-widget.recommended a {
+  color: var(--vp-c-brand-1);
+  text-decoration: underline;
+}
+.download-widget.recommended a:hover {
+  text-decoration: underline;
+  opacity: 0.8;
+}
+.block-head {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  flex-wrap: wrap;
+  margin-bottom: 0.5rem;
+}
+.block-head .icon-download {
+  flex-shrink: 0;
+  width: 1.25rem;
+  height: 1.25rem;
+  color: var(--vp-c-brand-1);
+}
+.preview-select {
+  margin-left: auto;
+  font-size: 0.85rem;
+  padding-right: 1.75rem;
+  padding-left: 0.5rem;
+  appearance: none;
+  background-color: var(--vp-c-bg-soft);
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2'%3E%3Cpath d='M6 9l6 6 6-6'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 0.35rem center;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 4px;
+  cursor: pointer;
+}
+.widget-list {
+  margin: 0 0 0 1rem;
+  padding-left: 0.5rem;
+}
+.widget-list li strong {
+  font-weight: 700;
+}
+.widget-download {
+  margin: 0.25rem 0;
+}
+.widget-link {
+  margin: 0.5rem 0 0;
+}
+.warn {
+  background: var(--vp-custom-block-warning-bg);
+  color: var(--vp-custom-block-warning-text);
+  padding: 0.5rem 0.75rem;
+  border-radius: 6px;
+  margin: 0.5rem 0 0;
+  font-size: 0.9rem;
+  font-weight: normal;
+}
+.alternatives {
+  font-size: 0.9rem;
+  font-weight: normal;
+  color: var(--vp-c-text-2);
+  margin-top: 0.5rem;
+}
+.alternatives ul {
+  margin: 0.25rem 0 0 1rem;
+  padding-left: 0.5rem;
+}
+</style>

.vitepress/theme/Layout.vue

@@ -0,0 +1,23 @@
+<script setup>
+import { ref, onMounted, defineAsyncComponent } from 'vue'
+import DefaultTheme from 'vitepress/theme'
+import { useData } from 'vitepress'
+
+const { frontmatter } = useData()
+const { Layout: DefaultLayout } = DefaultTheme
+const mounted = ref(false)
+onMounted(() => { mounted.value = true })
+
+// Load widget only on client so download-detection.js (navigator) never runs during SSR
+const DownloadSuggestionWidget = defineAsyncComponent(() =>
+  import('./DownloadSuggestionWidget.vue')
+)
+</script>
+
+<template>
+  <DefaultLayout>
+    <template #home-hero-after>
+      <DownloadSuggestionWidget v-if="frontmatter.layout === 'home' && mounted" />
+    </template>
+  </DefaultLayout>
+</template>

.vitepress/theme/custom.css

@@ -0,0 +1,69 @@
+/* Custom styles for Libation documentation */
+
+/* Naming Templates page: monospace in the doc column + outline only.
+   pageClass is applied to .Layout in VitePress; limit scope to #VPContent
+   so the top nav, sidebar, and site footer keep the default font. */
+.Layout.naming-templates-mono #VPContent,
+.Layout.naming-templates-mono #VPContent * {
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas,
+    "Liberation Mono", "Courier New", monospace;
+}
+
+/* Donate page: primary options */
+.donate-options {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+  margin: 1.25rem 0 0.5rem;
+}
+
+.donate-option {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 0.15rem;
+  min-width: 11rem;
+  padding: 1rem 1.25rem;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg-soft);
+  text-decoration: none !important;
+  color: var(--vp-c-text-1) !important;
+  transition: border-color 0.15s ease, background-color 0.15s ease;
+}
+
+.donate-option:hover {
+  border-color: var(--vp-c-brand-1);
+  background: var(--vp-c-bg-elv);
+}
+
+.donate-option__icon {
+  width: 1.75rem;
+  height: 1.75rem;
+  margin-bottom: 0.35rem;
+}
+
+.donate-option__label {
+  font-size: 1.1rem;
+  font-weight: 600;
+  line-height: 1.3;
+}
+
+.donate-option__hint {
+  font-size: 0.85rem;
+  color: var(--vp-c-text-2);
+}
+
+/* Hide certain nav items on tablet devices to prevent horizontal scroll */
+@media (min-width: 640px) and (max-width: 959px) {
+  /* Target specific nav items by their position */
+  /* Hide "Issues & Requests" and "Donate" links on tablet */
+  .VPNav .VPNavBar .nav .VPNavBarMenu .VPMenu:nth-child(3) {
+    display: none;
+  }
+
+  /* Alternative: Use a more specific selector if needed */
+  .VPNavBarMenuLink[href*="issues"] {
+    display: none;
+  }
+}

.vitepress/theme/download-detection.js

@@ -0,0 +1,218 @@
+/**
+ * Client-side OS and system detection for download recommendation.
+ * Uses navigator.userAgent and (when available) navigator.userAgentData.
+ * Call getDetectOS() in the browser only (e.g. in Vue onMounted).
+ */
+export function getDetectOS() {
+  const ua = typeof navigator !== 'undefined' ? navigator.userAgent : ''
+  const uaData = typeof navigator !== 'undefined' && navigator.userAgentData
+
+  function getOS() {
+    if (uaData?.platform) {
+      const p = uaData.platform.toLowerCase()
+      if (p === 'windows') return 'windows'
+      if (p === 'macos') return 'mac'
+      if (p === 'linux') return 'linux'
+      if (p === 'android') return 'android'
+      if (p === 'ios') return 'ios'
+    }
+    if (/\bWindows\b/i.test(ua)) return 'windows'
+    if (/\bMac\b/i.test(ua) || /\bMacintosh\b/i.test(ua)) return 'mac'
+    if (/\bLinux\b/i.test(ua) && !/\bAndroid\b/i.test(ua)) return 'linux'
+    if (/\bAndroid\b/i.test(ua)) return 'android'
+    if (/\b(iPhone|iPad|iPod)\b/i.test(ua)) return 'ios'
+    return 'other'
+  }
+
+  function getOSVersion() {
+    const os = getOS()
+    if (os === 'windows') {
+      const ntMatch = ua.match(/Windows NT (\d+\.\d+)/)
+      if (ntMatch) {
+        const nt = ntMatch[1]
+        if (nt === '10.0') return '10 or 11 (NT 10.0)'
+        if (nt === '6.3') return '8.1'
+        if (nt === '6.2') return '8'
+        if (nt === '6.1') return '7'
+        return `NT ${nt}`
+      }
+      return null
+    }
+    if (os === 'mac') {
+      const macMatch = ua.match(/Mac OS X (\d+[._]\d+(?:[._]\d+)?)/)
+      return macMatch ? macMatch[1].replace(/_/g, '.') : null
+    }
+    if (os === 'linux') {
+      const linuxMatch = ua.match(/Linux ([^\s;)]+)/)
+      return linuxMatch ? linuxMatch[1] : null
+    }
+    if (os === 'android') {
+      const m = ua.match(/Android (\d+(?:\.\d+)*)/)
+      return m ? m[1] : null
+    }
+    if (os === 'ios') {
+      const m = ua.match(/OS (\d+[._]\d+(?:[._]\d+)?)/)
+      return m ? m[1].replace(/_/g, '.') : null
+    }
+    return null
+  }
+
+  function getArchitecture() {
+    if (uaData?.architecture) {
+      const a = uaData.architecture.toLowerCase()
+      if (a === 'x86' || a === 'amd64') return a === 'amd64' ? 'x64' : 'x86'
+      if (a === 'arm' || a === 'arm64' || a === 'aarch64') return a === 'aarch64' ? 'arm64' : a
+      return a
+    }
+    if (/\b(aarch64|arm64|ARM64)\b/i.test(ua)) return 'arm64'
+    if (/\b(arm|aarch32)\b/i.test(ua) && !/arm64/i.test(ua)) return 'arm'
+    if (/\b(Wow64|Win64|x64|x86_64|amd64)\b/i.test(ua)) return 'x64'
+    if (/\b(WOW32|Win32|x86)\b/i.test(ua)) return 'x86'
+    return 'other'
+  }
+
+  function getLinuxFlavor() {
+    if (getOS() !== 'linux') return null
+    if (/\bUbuntu\b/i.test(ua)) return 'Ubuntu'
+    if (/\bFedora\b/i.test(ua)) return 'Fedora'
+    if (/\bDebian\b/i.test(ua)) return 'Debian'
+    if (/\bLinux Mint\b/i.test(ua)) return 'Linux Mint'
+    if (/\bOpenSUSE\b/i.test(ua)) return 'OpenSUSE'
+    if (/\bArch\b/i.test(ua)) return 'Arch'
+    if (/\bCentOS\b/i.test(ua)) return 'CentOS'
+    if (/\bRed Hat\b/i.test(ua)) return 'Red Hat'
+    if (/\bChrome OS\b/i.test(ua) || /\bCrOS\b/i.test(ua)) return 'Chrome OS'
+    return null
+  }
+
+  function parseAssetFilename(name) {
+    if (!name || typeof name !== 'string') return null
+    const lower = name.toLowerCase()
+    let platform = null
+    if (lower.includes('windows')) platform = 'windows'
+    else if (lower.includes('macos') || (lower.includes('mac') && !lower.includes('macos'))) platform = 'mac'
+    else if (lower.includes('linux')) platform = 'linux'
+    if (!platform) return null
+    let arch = null
+    if (lower.includes('arm64') || lower.includes('aarch64')) arch = 'arm64'
+    else if (lower.includes('amd64') || lower.includes('x64')) arch = 'x64'
+    else if (lower.includes('x86') || lower.includes('i386')) arch = 'x86'
+    if (!arch) return null
+    let packageType = null
+    if (lower.endsWith('.deb')) packageType = 'deb'
+    else if (lower.endsWith('.rpm')) packageType = 'rpm'
+    else if (lower.endsWith('.dmg')) packageType = 'dmg'
+    else if (lower.endsWith('-setup.exe')) packageType = 'installer'
+    else if (lower.endsWith('.zip') || lower.endsWith('.msi')) packageType = 'archive'
+    return { platform, arch, packageType: packageType || 'unknown', name }
+  }
+
+  function recommendDownload(assets, overrides) {
+    const os = (overrides && overrides.os != null) ? overrides.os : getOS()
+    const arch = (overrides && overrides.architecture != null) ? overrides.architecture : getArchitecture()
+    const linuxFlavor = (overrides && overrides.linuxFlavor !== undefined) ? overrides.linuxFlavor : getLinuxFlavor()
+    let reason = ''
+    if (!Array.isArray(assets) || assets.length === 0) {
+      return { recommended: null, alternatives: [], reason: reason || 'No assets provided.' }
+    }
+    const wantArch = (arch === 'x64' || arch === 'x86') ? 'x64' : (arch === 'arm64' || arch === 'arm') ? 'arm64' : null
+    const wantOs = os === 'windows' ? 'windows' : os === 'mac' ? 'mac' : os === 'linux' ? 'linux' : null
+    const preferDeb = linuxFlavor === 'Ubuntu' || linuxFlavor === 'Debian' || linuxFlavor === 'Linux Mint' || linuxFlavor === 'Chrome OS'
+    const preferRpm = linuxFlavor === 'Fedora' || linuxFlavor === 'Red Hat' || linuxFlavor === 'CentOS' || linuxFlavor === 'OpenSUSE'
+    const parsed = []
+    for (let i = 0; i < assets.length; i++) {
+      const a = assets[i]
+      const name = a && (a.name != null ? a.name : a)
+      const url = a && a.url
+      const p = parseAssetFilename(name)
+      if (!p) continue
+      parsed.push({ name, url, parsed: p })
+    }
+    if (parsed.length === 0) {
+      return { recommended: null, alternatives: [], reason: reason || 'No recognizable asset filenames.' }
+    }
+    function score(entry) {
+      const p = entry.parsed
+      const nameLower = (entry.name || '').toLowerCase()
+      let s = 0
+      if (wantOs && p.platform === wantOs) s += 100
+      else if (wantOs) s -= 50
+      if (wantArch && p.arch === wantArch) s += 50
+      else if (wantArch) s -= 30
+      if (wantOs === 'linux' && p.packageType === 'deb' && preferDeb) s += 20
+      if (wantOs === 'linux' && p.packageType === 'rpm' && preferRpm) s += 20
+      if (wantOs === 'linux' && !preferDeb && !preferRpm && p.packageType === 'deb') s += 5
+      if (wantOs === 'windows' && p.packageType === 'installer') s += 30
+      if (wantOs === 'windows' && p.packageType === 'archive') s -= 10
+      if (nameLower.includes('chardonnay')) s += 10
+      if (nameLower.includes('classic')) s -= 5
+      return s
+    }
+    parsed.sort((a, b) => score(b) - score(a))
+    const best = parsed[0]
+    const bestScore = score(best)
+    const recommended = bestScore >= 50 ? { name: best.name, url: best.url } : null
+    let altCandidates = parsed.slice(1, 4)
+    if (wantOs) altCandidates = altCandidates.filter(e => e.parsed.platform === wantOs)
+    if (wantArch) altCandidates = altCandidates.filter(e => e.parsed.arch === wantArch)
+    const alternatives = altCandidates.map(e => ({ name: e.name, url: e.url }))
+    const classicVsChardonnayFaqUrl = 'https://getlibation.com/docs/frequently-asked-questions#what-s-the-difference-between-classic-and-chardonnay'
+    function isWindowsSetup(name) {
+      return (name || '').toLowerCase().endsWith('-setup.exe')
+    }
+    function preferWindowsAsset(current, candidate) {
+      if (!candidate) return current
+      if (!current) return candidate
+      const candSetup = isWindowsSetup(candidate.name)
+      const currSetup = isWindowsSetup(current.name)
+      if (candSetup && !currSetup) return candidate
+      return current
+    }
+    function isClassicWindowsAsset(nameLower) {
+      return nameLower.includes('libation-classic') || nameLower.includes('classic-libation')
+    }
+    let windowsX64Choice = null
+    if (wantOs === 'windows' && wantArch === 'x64') {
+      let winChardonnay = null
+      let winClassic = null
+      for (let j = 0; j < parsed.length; j++) {
+        const e = parsed[j]
+        if (e.parsed.platform !== 'windows' || e.parsed.arch !== 'x64') continue
+        const n = (e.name || '').toLowerCase()
+        if (n.includes('chardonnay')) winChardonnay = preferWindowsAsset(winChardonnay, e)
+        else if (isClassicWindowsAsset(n)) winClassic = preferWindowsAsset(winClassic, e)
+      }
+      if (winChardonnay && winClassic) {
+        windowsX64Choice = {
+          chardonnay: { name: winChardonnay.name, url: winChardonnay.url },
+          classic: { name: winClassic.name, url: winClassic.url },
+        }
+      }
+    }
+    if (!recommended && wantOs) {
+      reason = 'No asset matched your system (OS: ' + os + ', arch: ' + arch + '). Try choosing a download manually.'
+    } else if (recommended && wantOs && !wantArch) {
+      reason = 'Matched your OS; architecture could not be detected. If this download is wrong, pick another (e.g. arm64 vs x64).'
+    }
+    return {
+      recommended,
+      alternatives,
+      reason: reason || (recommended ? 'Recommended for your system.' : ''),
+      windowsX64Choice,
+      classicVsChardonnayFaqUrl: windowsX64Choice ? classicVsChardonnayFaqUrl : null,
+    }
+  }
+
+  return {
+    os: getOS(),
+    osVersion: getOSVersion(),
+    architecture: getArchitecture(),
+    linuxFlavor: getLinuxFlavor(),
+    getOS,
+    getOSVersion,
+    getArchitecture,
+    getLinuxFlavor,
+    parseAssetFilename,
+    recommendDownload,
+  }
+}

.vitepress/theme/index.js

@@ -0,0 +1,8 @@
+import DefaultTheme from 'vitepress/theme'
+import Layout from './Layout.vue'
+import './custom.css'
+
+export default {
+  extends: DefaultTheme,
+  Layout,
+}

.vscode/launch.json

@@ -0,0 +1,32 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+
+        {
+            "name": ".NET Core Launch (console) Windows",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build",
+            "program": "${workspaceFolder}/Source/bin/Avalonia/Debug/Libation.dll",
+            "args": [],
+            "cwd": "${workspaceFolder}",
+            "stopAtEntry": false,
+            "console": "internalConsole"
+        },
+        {
+            "name": ".NET Core Launch (console) Linux",
+            "type": "coreclr",
+            "request": "launch",
+            "preLaunchTask": "build_linux",
+            "program": "${workspaceFolder}/Source/bin/Avalonia/Debug/Libation.dll",
+            "args": [],
+            "cwd": "${workspaceFolder}",
+            "stopAtEntry": false,
+            "console": "internalConsole"
+        }
+
+    ]
+}

.vscode/tasks.json

@@ -0,0 +1,59 @@
+{
+    // See https://go.microsoft.com/fwlink/?LinkId=733558
+    // for the documentation about the tasks.json format
+    "version": "2.0.0",
+    "tasks": [
+        {
+            "label": "build",
+            "dependsOn": [
+                "build_libation",
+                "build_linuxconfigapp"
+            ]
+        },
+        {
+            "label": "build_libation",
+            "type": "shell",
+            "command": "dotnet",
+            "args": [
+                "build",
+                "${workspaceFolder}/Source/LibationAvalonia/LibationAvalonia.csproj"
+            ],
+            "group": "build",
+            "presentation": {
+                //"reveal": "silent"
+            },
+            "problemMatcher": "$msCompile"
+        },
+        {
+            "label": "build_linuxconfigapp",
+            "type": "shell",
+            "command": "dotnet",
+            "args": [
+                "build",
+                "${workspaceFolder}/Source/LoadByOS/LinuxConfigApp/LinuxConfigApp.csproj"
+            ],
+            "group": "build",
+            "presentation": {
+                //"reveal": "silent"
+            },
+            "problemMatcher": "$msCompile"
+        },
+        {
+           "label": "build_linux",
+            "type": "shell",
+            "command": "dotnet",
+            "args": [
+                "build",
+                "${workspaceFolder}/Source/LibationAvalonia/LibationAvalonia.csproj",
+                "-p:TargetFramework=net9.0",
+                "-p:TargetFrameworks=net9.0",
+                "-p:RuntimeIdentifier=linux-x64"
+            ],
+            "group": "build",
+            "presentation": {
+                //"reveal": "silent"
+            },
+            "problemMatcher": "$msCompile"
+        }
+    ]
+}

CNAME

@@ -0,0 +1 @@
+getlibation.com

Directory.Build.props

@@ -0,0 +1,5 @@
+<Project>
+  <PropertyGroup>
+    <EnableMSTestRunner>true</EnableMSTestRunner>
+  </PropertyGroup>
+</Project>

Docker/appsettings.json

@@ -0,0 +1,3 @@
+{
+  "LibationFiles": "/config-internal"
+}

Docker/liberate.sh

@@ -1,68 +1,233 @@
 #!/bin/bash
 
-# Rewire echo to print date time
-echo() {
-    if [[ -n $1  ]]; then
-        printf "$(date '+%F %T'): %s\n" "$1"
-    fi
+error() {
+  log "ERROR" "$1"
 }
 
-# ################################
-# Setup
-# ################################
-echo "Starting"
-if [[ -z "${SLEEP_TIME}" ]]; then
-  echo "No sleep time passed in. Will run once and exit."
-else
-  echo "Sleep time is set to ${SLEEP_TIME}"
-fi
+warn() {
+  log "WARNING" "$1"
+}
 
-echo ""
+info() {
+  log "info" "$1"
+}
 
-# Check if the config directory is passed in, and there is no link to it then create the link.
-if [ -d "/config" ] && [ ! -d "/root/Libation" ]; then
-    echo "Linking config directory to the Libation config directory"
-    ln -s /config/ /root/Libation
-fi
+debug() {
+  if [ "${LOG_LEVEL}" = "debug" ]; then
+    log "debug" "$1"
+  fi
+}
 
-# If no config error and exit
-if [ ! -d "/config" ]; then
-    echo "ERROR: No /config directory. You must pass in a volume containing your config mapped to /config"
+log() {
+  LEVEL=$1
+  MESSAGE=$2
+  printf "$(date '+%F %T') %s: %s\n" "${LEVEL}" "${MESSAGE}"
+}
+
+init_config_file() {
+  FILE=$1
+  FULLPATH=${LIBATION_CONFIG_DIR}/${FILE}
+  if [ -f ${FULLPATH} ]; then
+    info "loading ${FILE}"
+    cp ${FULLPATH} ${LIBATION_CONFIG_INTERNAL}/
+    return 0
+  else
+    warn "${FULLPATH} not found, creating empty file"
+    echo "{}" > ${LIBATION_CONFIG_INTERNAL}/${FILE}
+    return 1
+  fi
+}
+
+init_master_key() {
+  FILE=libation-master.key
+  FULLPATH=${LIBATION_CONFIG_DIR}/${FILE}
+  if [ -n "${LIBATION_MASTER_KEY_FILE}" ]; then
+    debug "LIBATION_MASTER_KEY_FILE is already set, not looking for ${FILE}"
+    return 0
+  fi
+  if [ -n "${LIBATION_MASTER_KEY}" ]; then
+    debug "LIBATION_MASTER_KEY is already set, not looking for ${FILE}"
+    return 0
+  fi
+  if [ -f ${FULLPATH} ]; then
+    info "loading ${FILE}"
+    cp ${FULLPATH} ${LIBATION_CONFIG_INTERNAL}/
+  else
+    debug "${FULLPATH} not found, assuming accounts don't use encrypted tokens"
+  fi
+}
+
+update_settings() {
+  FILE=$1
+  KEY=$2
+  VALUE=$3
+  info "setting ${KEY} to ${VALUE}"
+  echo $(jq --arg k "${KEY}" --arg v "${VALUE}" '.[$k] = $v' ${LIBATION_CONFIG_INTERNAL}/${FILE}) > ${LIBATION_CONFIG_INTERNAL}/${FILE}.tmp
+  mv ${LIBATION_CONFIG_INTERNAL}/${FILE}.tmp ${LIBATION_CONFIG_INTERNAL}/${FILE}
+}
+
+is_mounted() {
+  DIR=$1
+  if grep -qs "${DIR} " /proc/mounts;
+  then
+    return 0
+  else
+    return 1
+  fi
+}
+
+create_db() {
+  DBFILE=$1
+  if [ -f "${DBFILE}" ]; then
+    warn "prexisting database found when creating"
+    return 0
+  else
+    if ! touch "${DBFILE}"; then
+      error "unable to create database, check permissions on host"
+      exit 1
+    fi
+    return 1
+  fi
+}
+
+setup_db() {
+  local DBPATH=$1
+  local dbpattern="*.db"
+  local FILE LINK LINK_ORIGIN
+  local -a files
+
+  debug "using database directory ${DBPATH}"
+
+  # Figure out the right databse file
+  if [[ -z $LIBATION_DB_FILE ]]
+  then
+    shopt -s nullglob     # files shall be empty if no match is found
+    files=( "${DBPATH}"/${dbpattern} )
+    shopt -u nullglob
+
+    case ${#files[@]} in
+      0)
+        FILE="${DBPATH}/LibationContext.db"
+        ;;
+      1)
+        FILE="${files[0]}"
+        ;;
+      *)
+        debug "found ${#files[@]} database files matching '${dbpattern}'"
+        error "too many database files found, set LIBATION_DB_FILE to the filename you wish to use"
+        exit 1
+        ;;
+    esac
+  else
+    FILE="${DBPATH}/${LIBATION_DB_FILE}"
+  fi
+
+  debug "planning to use database '${FILE}'"
+
+  if [[ -f $FILE ]]
+  then
+    info "database found at ${FILE}"
+  elif [[ $LIBATION_CREATE_DB == "true" ]]
+  then
+    warn "database not found, creating one at ${FILE}"
+    create_db "${FILE}"
+  else
+    error "database not found and creation is disabled"
     exit 1
-fi
+  fi
 
-# If user passes in db from a /db/ folder and a db does not already exist / is not already linked
-FILE=/db/LibationContext.db
-if [ -f "${FILE}" ] && [ ! -f "/config/LibationContext.db" ]; then
-    echo "Linking passed in Libation database from /db/ to the Libation config directory"
-    ln -s $FILE /config/LibationContext.db
-fi
-
-# Confirm we have a db in the config direcotry.
-if [ ! -f "/config/LibationContext.db" ]; then
-    echo "ERROR: No Libation database detected, exiting."
+  LINK="${LIBATION_CONFIG_INTERNAL}/LibationContext.db"
+  if [[ -L $LINK ]]
+  then
+    # check if the link is correct
+    LINK_ORIGIN=$(readlink -fn "$LINK")
+    if [[ $LINK_ORIGIN == $(readlink -fn "$FILE") ]]
+    then
+      warn "symlink '${LINK_ORIGIN}' to '${LINK}' already established"
+      return 0
+    fi
+    warn "removing existing symlink '${LINK_ORIGIN}' to '${LINK}'"
+    rm -f "$LINK"
+  elif [[ -e $LINK ]]
+  then
+    error "found blocking file at '${LINK}' - can't create symlink"
     exit 1
-fi
+  fi
 
-# ################################
-# Loop and liberate
-# ################################
-while true
-do
-    echo ""
-    echo "Scanning accounts"
-    /libation/LibationCli scan
-    echo "Liberating books"
-    /libation/LibationCli liberate
-    echo ""
+  ln -s "${FILE}" "${LINK}"
+}
+
+run() {
+  info "scanning accounts"
+  /libation/LibationCli scan
+  local scan_exit=$?
+  if [ "${scan_exit}" -ne 0 ]; then
+    error "scan failed (exit ${scan_exit}); skipping liberate. If the log shows Failed to decrypt ExistingAccessToken, see https://getlibation.com/docs/frequently-asked-questions#docker-finds-no-new-books-failed-to-decrypt-existingaccesstoken"
+    exit "${scan_exit}"
+  fi
+  info "liberating books"
+  /libation/LibationCli liberate
+}
+
+main() {
+  info "initializing libation"
+  init_config_file AccountsSettings.json
+  init_config_file Settings.json
+  init_master_key
+
+  info "loading settings"
+  update_settings Settings.json Books "${LIBATION_BOOKS_DIR:-/data}"
+  update_settings Settings.json InProgress /tmp
+
+  info "loading database"
+  # If user provides a separate database mount, use that
+  if is_mounted "${LIBATION_DB_DIR}";
+  then
+    DB_LOCATION=${LIBATION_DB_DIR}
+  # Otherwise, use the config directory
+  else
+    DB_LOCATION=${LIBATION_CONFIG_DIR}
+  fi
+  setup_db ${DB_LOCATION}
+
+  # Try to warn if books dir wasn't mounted in
+  if ! is_mounted "${LIBATION_BOOKS_DIR}";
+  then
+    warn "${LIBATION_BOOKS_DIR} does not appear to be mounted, books will not be saved"
+  fi
+
+  # If a command was passed to the container (e.g. `docker run -it libation bash`),
+  # run that instead of the liberate loop so the environment is still set up
+  if [ "$#" -gt 0 ]; then
+    info "executing '$*' instead of the liberate loop"
+    exec "$@"
+  fi
+
+  # Let the user know what the run type will be
+  if [[ -z "${SLEEP_TIME}" ]]; then
+    SLEEP_TIME=-1
+  fi
+
+  if [ "${SLEEP_TIME}" == -1 ]; then
+    info "running once"
+  else
+    info "running every ${SLEEP_TIME}"
+  fi
+
+  # loop
+  while true
+  do
+    run
     
     # Liberate only once if SLEEP_TIME was set to -1
-    if [ "${SLEEP_TIME}" = -1 ]; then
+    if [ "${SLEEP_TIME}" == -1 ]; then
       break  
     fi
 
-    echo "Sleeping for ${SLEEP_TIME}"
     sleep "${SLEEP_TIME}"
-done
+  done
 
-echo "Exiting"
+  info "exiting"
+}
+
+main "$@"

Dockerfile

@@ -1,22 +1,44 @@
 # Dockerfile
-FROM mcr.microsoft.com/dotnet/sdk:7.0 as build-env
+FROM --platform=${BUILDPLATFORM} mcr.microsoft.com/dotnet/sdk:10.0 AS build
+ARG TARGETARCH
 
 COPY Source /Source
-RUN dotnet publish -c Release -o /Source/bin/Publish/Linux-chardonnay /Source/LibationCli/LibationCli.csproj -p:PublishProfile=/Source/LibationCli/Properties/PublishProfiles/LinuxProfile.pubxml
-COPY Docker/liberate.sh /Source/bin/Publish/Linux-chardonnay
+RUN dotnet publish \
+    /Source/LibationCli/LibationCli.csproj \
+    --os linux \
+    --arch ${TARGETARCH} \
+    --configuration Release \
+    --output /Source/bin/Publish/Linux-chardonnay \
+    -p:PublishProtocol=FileSystem \
+    -p:PublishReadyToRun=true \
+    -p:SelfContained=true
+
+FROM mcr.microsoft.com/dotnet/runtime:10.0
+ARG USER_UID=1001
+ARG USER_GID=1001
+
+# Set the character set that will be used for folder and filenames when liberating
+ENV LANG=C.UTF-8
+ENV LC_ALL=C.UTF-8
+
+ENV SLEEP_TIME=-1
+ENV LIBATION_CONFIG_INTERNAL=/config-internal
+ENV LIBATION_CONFIG_DIR=/config
+ENV LIBATION_DB_DIR=/db
+ENV LIBATION_DB_FILE=
+ENV LIBATION_CREATE_DB=true
+ENV LIBATION_BOOKS_DIR=/data
 
 
-FROM mcr.microsoft.com/dotnet/runtime:7.0
+RUN apt-get update && apt-get -y upgrade && \
+    apt-get install -y jq && \
+    mkdir -m777 ${LIBATION_CONFIG_INTERNAL} ${LIBATION_BOOKS_DIR}
 
-ENV SLEEP_TIME "30m"
+COPY --from=build /Source/bin/Publish/Linux-chardonnay /libation
+COPY Docker/* /libation
 
-# Sets the character set that will be used for folder and filenames when liberating
-ENV LANG C.UTF-8
-ENV LC_ALL C.UTF-8
+RUN ln -s /libation/LibationCli /usr/local/bin/LibationCli
 
-RUN mkdir /db /config /data
+USER ${USER_UID}:${USER_GID}
 
-COPY --from=build-env /Source/bin/Publish/Linux-chardonnay /libation
-
-
-CMD ["./libation/liberate.sh"]
+ENTRYPOINT ["/libation/liberate.sh"]

Documentation/Advanced.md

@@ -1,79 +1,3 @@
-## [Download Libation](https://github.com/rmcrackan/Libation/releases/latest)
+# This page has been moved to https://getlibation.com/docs/advanced/advanced
 
-### If you found this useful, tell a friend. If you found this REALLY useful, you can click here to [PalPal.me](https://paypal.me/mcrackan?locale.x=en_us)
-...or just tell more friends. As long as I'm maintaining this software, it will remain **free** and **open source**.
-
-
-
-# Advanced: Table of Contents
-
-- [Files and folders](#files-and-folders)
-- [Settings](#settings)
-- [Custom File Naming](NamingTemplates.md)
-- [Command Line Interface](#command-line-interface)
-
-
-
-### Files and folders
-
-To make upgrades and reinstalls easier, Libation separates all of its responsibilities to a few different folders. If you don't want to mess with this stuff: ignore it. Read on if you like a little more control over your files.
-
-* In Libation's initial folder are the files that make up the program. Since nothing else is here, just copy new files here to upgrade the program. Delete this folder to delete Libation.
-
-* In a separate folder, Libation keeps track of all of the files it creates like settings and downloaded images. After an upgrade, Libation might think that's its being run for the first time. Just click ADVANCED SETUP and point to this folder. Libation will reload your library and settings.
-
-* The last important folder is the "books location." This is where Libation looks for your downloaded and decrypted books. This is how it knows which books still need to be downloaded. The Audible id must be somewhere in the book's file or folder name for Libation to detect your downloaded book.
-
-### Settings
-
-* 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.
-
-### Command Line Interface
-
-Libationcli.exe allows limited access to Libation's functionalities as a CLI.
-
-Warnings about relying solely on on the CLI:
-* CLI will not perform any upgrades.
-* It will show that there is an upgrade, but that will likely scroll by too fast to notice.
-* It will not perform all post-upgrade migrations. Some migrations are only be possible by launching GUI.
-
-```
-help
-  libationcli --help
-  
-verb-specific help
-  libationcli scan --help
-  
-scan all libraries
-  libationcli scan
-scan only libraries for specific accounts
-  libationcli scan nickname1 nickname2
-  
-convert all m4b files to mp3
-  libationcli convert
-  
-liberate all books and pdfs
-  libationcli liberate
-liberate pdfs only
-  libationcli liberate --pdf
-  libationcli liberate -p
-  
-export library to file
-  libationcli export --path "C:\foo\bar\my.json" --json
-  libationcli export -p "C:\foo\bar\my.json" -j
-  libationcli export -p "C:\foo\bar\my.csv" --csv
-  libationcli export -p "C:\foo\bar\my.csv" -c
-  libationcli export -p "C:\foo\bar\my.xlsx" --xlsx
-  libationcli export -p "C:\foo\bar\my.xlsx" -x
-
-Set download statuses throughout library based on whether each book's audio file can be found.   
-Must include at least one flag: --downloaded , --not-downloaded.  
-Downloaded: If the audio file can be found, set download status to 'Downloaded'.  
-Not Downloaded: If the audio file cannot be found, set download status to 'Not Downloaded'  
-UI: Visible Books \> Set 'Downloaded' status automatically. Visible books. Prompts before saving changes  
-CLI: Full library. No prompt
-
-  libationcli set-status -d
-  libationcli set-status -n
-  libationcli set-status -d -n
-```
+([page in github](https://github.com/rmcrackan/Libation/blob/master/docs/advanced/advanced.md))

Documentation/AudioFileFormats.md

@@ -0,0 +1,3 @@
+# This page has been moved to https://getlibation.com/docs/features/audio-file-formats
+
+([page in github](https://github.com/rmcrackan/Libation/blob/master/docs/features/audio-file-formats.md))

Documentation/Docker.md

@@ -1,36 +1,3 @@
-## [Download Libation](https://github.com/rmcrackan/Libation/releases/latest)
-
-### If you found this useful, tell a friend. If you found this REALLY useful, you can click here to [PalPal.me](https://paypal.me/mcrackan?locale.x=en_us)
-...or just tell more friends. As long as I'm maintaining this software, it will remain **free** and **open source**.
-
-
-### Setup
-In order to use the docker image, you'll need to provide it with a copy of the `AccountsSettings.json`, `Settings.json`, and `LibationContext.db` files. These files can usually be found in the Libation folder in your user's home directory. If you haven't run Libation yet, you'll need to launch it to generate these files and setup your accounts. Once you have them, copy these files to a new location, such as `/opt/libation/config`. Before using them we'll need to make a couple edits so that the filepaths referenced are correct when running from the docker image.
-
-In Settings.json, make the following changes:
-* Change `Books` to `/data`
-* Change `InProgress` to `/tmp`
-
-### Running
-Once the configuration files are copied and edited, the docker image can be run with the following command.
-```
-sudo docker run -d \
-  -v /opt/libation/config:/config \
-  -v /opt/libation/books:/data \
-  --name libation \
-  --restart=always \
-  rmcrackan/libation
-```
-
-By default the container will scan for new books every 30 minutes and download any new ones. This is configurable by passing in a value for the `SLEEP_TIME` environment variable. Additionally, if you pass in `-1` it will scan and download books once and then exit.
-
-```
-sudo docker run -d \
-  -v /opt/libation/config:/config \
-  -v /opt/libation/books:/data \
-  -e SLEEP_TIME='10m' \
-  --name libation \
-  --restart=always \
-  rmcrackan/libation
-```
+# This page has been moved to https://getlibation.com/docs/installation/docker
 
+([page in github](https://github.com/rmcrackan/Libation/blob/master/docs/installation/docker.md))

Documentation/FrequentlyAskedQuestions.md

@@ -0,0 +1,3 @@
+# This page has been moved to https://getlibation.com/docs/frequently-asked-questions
+
+([page in github](https://github.com/rmcrackan/Libation/blob/master/docs/frequently-asked-questions.md))

Documentation/GettingStarted.md

@@ -1,143 +1,3 @@
-## [Download Libation](https://github.com/rmcrackan/Libation/releases/latest)
+# This page has been moved to https://getlibation.com/docs/getting-started
 
-### If you found this useful, tell a friend. If you found this REALLY useful, you can click here to [PalPal.me](https://paypal.me/mcrackan?locale.x=en_us)
-...or just tell more friends. As long as I'm maintaining this software, it will remain **free** and **open source**.
-
-
-
-# Getting started: Table of Contents
-
-- [Download Libation](#download-libation-1)
-- [Installation](#installation)
-- [Create Accounts](#create-accounts)
-- [Import your library](#import-your-library)
-- [Download your books -- DRM-free!](#download-your-books----drm-free)
-- [Download PDF attachments](#download-pdf-attachments)
-- [Details of downloaded files](#details-of-downloaded-files)
-- [Export your library](#export-your-library)
-
-
-
-### [Download Libation](https://github.com/rmcrackan/Libation/releases)
-
-### Installation
-
-* Windows
-
-Extract the zip file to a folder and then run `Libation.exe` from inside of that folder. Do not put it in Program Files. The inability to edit files from there causes problems with configuration and updating.
-
-* [Ubuntu Linux](InstallOnLinux.md)
-* [MacOS](InstallOnMac.md)
-
-### Create Accounts
-
-Create your account(s):
-
-![Create your accounts, menu](images/v40_accounts.png)
-
-New locale options include many more regions including old audible accounts which pre-date the amazon acquisition
-
-![Choose your account locales](images/v40_locales.png)
-
-### Import your library
-
-Be default, Libation will periodically scan the accounts you added above with a checkbox next to them. Nothing for you to do. You can also scan manually.
-
-Select Import > Scan Library:
-
-![Import step 1](images/Import1.png)
-
-Or if you have multiple accounts, you'll get to choose whether to scan all accounts or just the ones you select:
-
-![Import which accounts](images/v40_import.png)
-
-If this is a new installation, or you're scanning an account you haven't scanned before, you'll be prompted to enter your password for the Audible account.
-
-![Login password](images/alt-login1.png)
-
-Enter the password and click Submit. Audible will prompt you with a CAPTCHA image. 
-
-![Login captcha](images/alt-login2.png)
-
-Enter the CAPTCHA answer characters and click Submit. If all has gone well, Libation will start scanning the account. 
-
-In rare instances, the Captcha image/response will fail in an endless loop. If this happens, delete the problem account, and then click Save. Re-add the account and click Save again. Now try to scan the account again. This time, instead of typing your password, click the link that says "Or click here". This will open the Audible External Login dialog shown below.
-
-![Login alternative setup](images/alt-login3.png)
-
-You can either copy the URL shown and paste it into your browser or launch the browser directly by clicking Launch in Browser. Audible will display its standard login page. Login, including answering the CAPTCHA on the next page. In some cases, you might have to approve the login from the email account associated with that login, but once the login is successful, you'll see an error message.
-
-![Login alternative login result](images/alt-login4.png)
-
-This actually means you've successfully logged in. Copy the entire URL shown in your browser and return to Libation. Paste that URL into the text box at the bottom of the Audible External Login window and click Submit.
-
-You'll see this window while it's scanning:
-
-![Import step 2](images/Import2.png)
-
-Success! We see how many new titles are imported:
-
-![Import step 3](images/Import3.png)
-
-### Download your books -- DRM-free!
-
-Automatically download some or all of your audible books. This shows you how much of your library is not yet downloaded and decrypted:
-
-The stoplights will tell you a title's status:
-
-* Green: downloaded and decrypted
-* Yellow: downloaded but still encrypted with DRM
-* Red: not downloaded
-* PDF icon without arrow: downloaded
-* PDF with arrow: not downloaded
-
-Or hover over the button to see the status.
-
-![Liberate book step 1](images/LiberateBook1.png)
-
-Select Liberate > Begin Book Backups
-
-You can also click on the stop light to download only that title and its PDF
-
-![Liberate book step 2](images/LiberateBook2.png)
-
-First the original book with DRM is downloaded
-
-![Liberate book step 3](images/LiberateBook3.png)
-
-Then it's decrypted so you can use it on any device you choose. The very first time you decrypt a book, this step will take a while. Every other book will go much faster. The first time, Libation has to figure out the special decryption key which allows your personal books to be unlocked.
-
-![Liberate book step 4](images/LiberateBook4.png)
-
-And voila! If you have multiple books not yet liberated, Libation will automatically move on to the next.
-
-![Liberate book step 5](images/LiberateBook5.png)
-
-The Audible id must be somewhere in the book's file or folder name for Libation to detect your downloaded book.
-
-### Download PDF attachments
-
-For books which include PDF downloads, Libation can download these for you as well and will attempt to store them with the book. "Book backup" will already download an available PDF. This additional option is useful when Audible adds a PDF to your book after you've already backed it up.
-
-Select Liberate > Begin PDF Backups
-
-![PDF download step 2](images/PdfDownload2.png)
-
-The downloads work just like with books, only with no additional decryption needed.
-
-![PDF download step 3](images/PdfDownload3.png)
-
-### Details of downloaded files
-
-![Post download](images/PostDownload.png)
-
-When you set up Libation, you'll specify a Books directory. Libation looks inside that directory and all subdirectories to look for files or folders with each library book's audible id. This way, organization is completely up to you. When you download + decrypt a book, you get several files
-
-* .m4b: your audiobook in m4b format. This is the most pure version of your audiobook and retains the highest quality. Now that it's decrypted, you can play it on any audio player and put it on any device. If you'd like, you can also use 3rd party tools to turn it into an mp3. The freedom to do what you want with your files was the original inspiration for Libation.
-* .cue: this is a file which logs where chapter breaks occur. Many tools are able to use this if you want to split your book into files along chapter lines.
-
-### Export your library
-
-![Export](images/Export.png)
-
-Export your library to Excel, CSV, or JSON
+([page in github](https://github.com/rmcrackan/Libation/blob/master/docs/getting-started.md))

Documentation/InstallOnLinux.md

@@ -1,22 +1,3 @@
-## [Download Libation](https://github.com/rmcrackan/Libation/releases/latest)
+# This page has been moved to https://getlibation.com/docs/installation/linux
 
-### If you found this useful, tell a friend. If you found this REALLY useful, you can click here to [PalPal.me](https://paypal.me/mcrackan?locale.x=en_us)
-...or just tell more friends. As long as I'm maintaining this software, it will remain **free** and **open source**.
-
-
-### Install and Run Libation on Ubuntu
-
-New Libation releases are automatically packed into a debian package and are available from the Libation repository's releases page.
-
-Run this command in your terminal to dowbnload and install Libation, replacing the url with the Latest Libation .deb package url:
-
-```Console
-wget -O libation.deb https://github.com/rmcrackan/Libation/releases/download/vX.X.X/Libation.X.X.X-linux-chardonnay.deb &&
-sudo apt install ./libation.deb
-```
-
-You should now see Libation among your applications.
-
-Additionally, you may launch Libation, LibationCli, and Hangover (the Libation recovery app) via the command line using 'libation, libationcli', and 'hangover' aliases respectively.
-
-Report bugs to https://github.com/rmcrackan/Libation/issues
+([page in github](https://github.com/rmcrackan/Libation/blob/master/docs/installation/linux.md))

Documentation/InstallOnMac.md

@@ -1,44 +1,3 @@
-## [Download Libation](https://github.com/rmcrackan/Libation/releases/latest)
+# This page has been moved to https://getlibation.com/docs/installation/mac
 
-### If you found this useful, tell a friend. If you found this REALLY useful, you can click here to [PalPal.me](https://paypal.me/mcrackan?locale.x=en_us)
-...or just tell more friends. As long as I'm maintaining this software, it will remain **free** and **open source**.
-
-
-
-# Run Libation on MacOS
-This walkthrough should get you up and running with Libation on your Mac.
-
-## Install Libation
-
-- Download latest MacOS zip to downloads folder
-- Extract and rename folder to Libation
-- in terminal type cd and then drag your folder of libation to terminal so it looks like `cd/users/YourName/Downloads/Libation`
-- Type following commands
-
-```console
-chmod +x ./Libation
-sudo spctl --add --label "Libation" ./Libation
-./Libation
-```
-
-## Trouble with Gatekeeper?
-
-If Gatekeeper is giving you trouble with Libation:
-
-Disable the block
-
-`sudo spctl --master-disable`
-
-Launch Libation and login, etc. and allow the rules to update then re-enable the block.
-
-`sudo spctl --master-enable`
-
-Once Gatekeeper reenabled, you can open Libation again without it being blocked.
-
-Thanks [joseph-holland](https://github.com/rmcrackan/Libation/issues/327#issuecomment-1268993349)!
-
-Report bugs to https://github.com/rmcrackan/Libation/issues
-
-## Get Libation running on Mac
-
-[Run Libation on MacOS](https://user-images.githubusercontent.com/37587114/213933357-983d8ede-2738-4b32-9c6e-40de21ff09c2.mp4)
+([page in github](https://github.com/rmcrackan/Libation/blob/master/docs/installation/mac.md))

Documentation/LinuxDevelopmentSetupUsingNix.md

@@ -0,0 +1,3 @@
+# This page has been moved to https://getlibation.com/docs/development/nix-linux-setup
+
+([page in github](https://github.com/rmcrackan/Libation/blob/master/docs/development/nix-linux-setup.md))

Documentation/NamingTemplates.md

@@ -1,109 +1,3 @@
-# Naming Templates
-File and Folder names can be customized using Libation's built-in tag template naming engine. To edit how folder and file names are created, go to Settings \> Download/Decrypt and edit the naming templates. If you're splitting your audiobook into multiple files by chapter, you can also use a custom template to set each chapter's title metadata tag by editing the template in Settings \> Audio File Options.
-
-These templates apply to both GUI and CLI.
-
-# Table of Contents
-
-- [Template Tags](#template-tags)
-  - [Property Tags](#property-tags)
-  - [Conditional Tags](#conditional-tags)
-- [Tag Formatters](#tag-formatters)
-  - [Text Formatters](#text-formatters)
-  - [Integer Formatters](#integer-formatters)
-  - [Date Formatters](#date-formatters)
-
-
-# Template Tags
-
-These are the naming template tags currently supported by Libation.
-
-## Property Tags
-These tags will be replaced in the template with the audiobook's values.
-
-|Tag|Description|Type|
-|-|-|-|
-|\<id\> **†**|Audible book ID (ASIN)|Text|
-|\<title\>|Full title|Text|
-|\<title short\>|Title. Stop at first colon|Text|
-|\<author\>|Author(s)|Text|
-|\<first author\>|First author|Text|
-|\<narrator\>|Narrator(s)|Text|
-|\<first narrator\>|First narrator|Text|
-|\<series\>|Name of series|Text|
-|\<series#\>|Number order in series|Text|
-|\<bitrate\>|File's original bitrate (Kbps)|Integer|
-|\<samplerate\>|File's original audio sample rate|Integer|
-|\<channels\>|Number of audio channels|Integer|
-|\<account\>|Audible account of this book|Text|
-|\<locale\>|Region/country|Text|
-|\<year\>|Year published|Integer|
-|\<language\>|Book's language|Text|
-|\<language short\> **†**|Book's language abbreviated. Eg: ENG|Text|
-|\<file date\>|File creation date/time.|DateTime|
-|\<pub date\>|Audiobook publication date|DateTime|
-|\<date added\>|Date the book added to your Audible account|DateTime|
-|\<ch count\> **‡**|Number of chapters|Integer|
-|\<ch title\> **‡**|Chapter title|Text|
-|\<ch#\> **‡**|Chapter number|Integer|
-|\<ch# 0\> **‡**|Chapter number with leading zeros|Integer|
-
-**†** Does not support custom formatting
-
-**‡** Only valid for Chapter Filename and Chapter Tile Metadata
-
-To change how these properties are displayed, [read about custom formatters](#tag-formatters)
-
-## Conditional Tags
-Anything between the opening tag (`<tagname->`) and closing tag (`<-tagname>`) will only appear in the name if the condition evaluates to true. 
-
-|Tag|Description|Type|
-|-|-|-|
-|\<if series-\>...\<-if series\>|Only include if part of a book series or podcast|Conditional|
-|\<if podcast-\>...\<-if podcast\>|Only include if part of a podcast|Conditional|
-|\<if bookseries-\>...\<-if bookseries\>|Only include if part of a book series|Conditional|
-
-For example, <if podcast-\>\<series\>\<-if podcast\> will evaluate to the podcast's series name if the file is a podcast. For audiobooks that are not podcasts, that tag will be blank.
-
-You can invert the condition (instead of displaying the text when the condition is true, display the text when it is false) by playing a '!' symbol before the opening tag name.
-
-As an example, this folder template will place all Liberated podcasts into a "Podcasts" folder and all liberated books (not podcasts) into a "Books" folder.
-
-\<if podcast-\>Podcasts<-if podcast\>\<!if podcast-\>Books\<-if podcast\>\\\<title\>
-
-
-# Tag Formatters
-**Text**, **Integer**, and **DateTime** tags can be optionally formatted using format text in square brackets after the tag name. Below is a list of supported formatters for each tag type.
-
-## Text Formatters
-|Formatter|Description|Example Usage|Example Result|
-|-|-|-|-|
-|L|Converts text to lowercase|\<title[L]\>|a study in scarlet꞉ a sherlock holmes novel|
-|U|Converts text to uppercase|\<title short[U]\>|A STUDY IN SCARLET|
-
-## Integer Formatters
-|Formatter|Description|Example Usage|Example Result|
-|-|-|-|-|
-|# (a number)|Zero-pads the number|\<bitrate[4]\><br>\<series#[3]\><br>\<samplerate[6]\>|0128<br>001<br>044100|
-
-**Text**, **Integer**, and **DateTime** tags can be optionally formatted using format text in square brackets after the tag name. Below is a list of supported formatters for each tag type.
-
-## Date Formatters
-Form more standard formatters, [see this guide from Microsoft](https://learn.microsoft.com/en-us/dotnet/standard/base-types/standard-date-and-time-format-strings).
-### Standard DateTime Formatters
-|Formatter|Description|Example Usage|Example Result|
-|-|-|-|-|
-|s|Sortable date/time pattern.|\<file date[s]\>|2023-02-14T13:45:30|
-|Y|Year month pattern.|\<file date[Y]\>|February 2023|
-
-### Custom DateTime Formatters
-You can use custom formatters to construct customized DateTime string. For more custom formatters and examples, [see this guide from Microsoft](https://learn.microsoft.com/en-us/dotnet/standard/base-types/custom-date-and-time-format-strings).
-|Formatter|Description|Example Usage|Example Result|
-|-|-|-|-|
-|yyyy|4-digit year|\<file date[yyyy]\>|2023|
-|yy|2-digit year|\<file date[yy]\>|23|
-|MM|2-digit month|\<file date[MM]\>|02|
-|dd|2-digit day of the month|\<file date[yyyy-MM-dd]\>|2023-02-14|
-|HH<br>mm|The hour, using a 24-hour clock from 00 to 23<br>The minute, from 00 through 59.|\<file date[HH:mm]\>|14:45|
-
+# This page has been moved to https://getlibation.com/docs/features/naming-templates
 
+([page in github](https://github.com/rmcrackan/Libation/blob/master/docs/features/naming-templates.md))

Documentation/SearchingAndFiltering.md

@@ -1,79 +1,3 @@
-## [Download Libation](https://github.com/rmcrackan/Libation/releases/latest)
+# This page has been moved to https://getlibation.com/docs/features/searching-and-filtering
 
-### If you found this useful, tell a friend. If you found this REALLY useful, you can click here to [PalPal.me](https://paypal.me/mcrackan?locale.x=en_us)
-...or just tell more friends. As long as I'm maintaining this software, it will remain **free** and **open source**.
-
-
-
-# Searching and filtering: Table of Contents
-
-- [Tags](#tags)
-- [Searches](#searches)
-- [Search examples](#search-examples)
-- [Filters](#filters)
-
-
-
-### Tags
-
-To add tags to a title, click the tags button
-
-![Tags step 1](images/Tags1.png)
-
-Add as many tags as you'd like. Tags are separated by a space. Each tag can contain letters, numbers, and underscores
-
-![Tags step 2](images/Tags2.png)
-
-Tags are saved non-case specific for easy search. There is one special tag "hidden" which will also grey-out the book
-
-![Tags step 3](images/Tags3.png)
-
-To edit tags, just click the button again.
-
-### Searches
-
-Libation's advanced searching is built on the powerful Lucene search engine. Simple searches are effortless and powerful searches are simple. To search, just type and click Filter or press enter
-
-* Type anything in the search box to search common fields: title, authors, narrators, and the book's audible id
-* Use Lucene's "Query Parser Syntax" for advanced searching.
-    * Easy tutorial: http://www.lucenetutorial.com/lucene-query-syntax.html
-    * Full official guide: https://lucene.apache.org/core/2_9_4/queryparsersyntax.html
-* Tons of search fields, specific to audiobooks
-* Synonyms so you don't have to memorize magic words. Eg: author and author**s** will both work
-* Click [?] button for a full list of search fields and synonyms ![Filter options](images/FilterOptionsButton.png)
-* Search by tag like \[this\]
-* When tags have an underscore you can use part of the tag. This is useful for quick categories. The below examples make this more clear.
-
-### Search examples
-
-Search for anything with the word potter
-
-![Search example: potter](images/SearchExamplePotter.png)
-
-If you only want to see Harry Potter
-
-![Search example: "harry potter"](images/SearchExampleHarryPotter.png)
-
-If you only want to see potter except for Harry Potter. You can also use "-" instead of "NOT"
-
-![Search example: "potter NOT harry"](images/SearchExamplePotterNotHarry.png)
-![Search example: "potter -harry"](images/SearchExamplePotterNotHarry2.png)
-
-To see only books written by Neil Gaiman where he also narrates his own book. (If you don't include AND, you'll see everything written by Neil Gaiman and also all books in your library which are self-narrated.)
-
-![Search example: author:gaiman AND authornarrated](images/SearchExampleGaimanAuthorNarrated.png)
-
-I tagged autobiographies as auto_bio and biographies written by someone else as bio. I can get only autobiographies with \[auto_bio\] or get both by searching \[bio\]
-
-![Search example: \[bio\]](images/SearchExampleBio.png)
-![Search example: \[auto_bio\]](images/SearchExampleAutoBio.png)
-
-### Filters
-
-If you have a search you want to save, click Add To Quick Filters to save it in your Quick Filters list. To use it again, select it from the Quick Filters list.
-
-To edit this list go to Quick Filters > Edit quick filters. Here you can re-order the list, delete filters, double-click a filter to edit it, or double-click the bottom blank box to add a new filter.
-
-Check "Quick Filters > Start Libation with 1st filter Default" to have your top filter automatically applied when Libation starts. In this top example, I want to always start without these: at books I've tagged hidden, books I've tagged as free_audible_originals, and books which I have rated.
-
-![default filters](images/FiltersDefault.png)
+([page in github](https://github.com/rmcrackan/Libation/blob/master/docs/features/searching-and-filtering.md))

Images/libation_cheers.svg

@@ -0,0 +1,32 @@
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 512 512" width="512px" enable-background="new 0 0 512 512">
+<path id="slosh" transform=
+	"translate(-50 23)
+	scale(0.7, 0.7)
+	rotate(12 256,256)"
+d=
+"M139,2
+	A 192,200 0 0 0 103,84
+	A 222,334 41 0 0 241,320
+	V478
+	H160
+	A 16,16 0 0 0 160,510
+	H352
+	A16 16 0 0 0 352,478
+	H271
+	V320
+	A 222,334 -41 0 0 409,84
+	A 192,200 0 0 0 373,2
+M355,32
+	A 192,200 0 0 1 381,127
+	A 187.5,334 -35 0 1 256,286
+	A 187.5,334 35 0 1 131,127
+	A 192,200 0 0 1 157,32
+	H355
+M146,147
+	A 168,300 35 0 0 256,270
+	A 168,300 -35 0 0 366,128
+	S 360,50 280,110
+	S 192,128 147,147
+z" />
+<use href="#slosh" transform="translate(512 0) scale(-1 1)" />
+</svg>

Images/libation_glass.svg

@@ -0,0 +1,41 @@
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 288 288" enable-background="new 0 0 288 288">
+	<defs>
+		<g id="glass">
+			<path transform="translate(16 16)" fill-rule="evenodd" d=
+				"M177,16
+					H79
+					A 32.0781 63.7932 -1.5106 0 0 66 80
+					A 158.789 471.1259 41.9466 0 0 90 131
+					A 81.7197 122.0515 35.3745 0 0 128 143.3484
+					A 81.7197 122.0515 -35.3745 0 0 166 131
+					A 158.789 471.1259 -41.9466 0 0 190 80
+					A 32.0781 63.7932 1.5106 0 0 177 16
+					L 184 0
+					A 44.7901 78.5247 1.1521 0 1 194 122
+					A 97.0039 135.3148 -36.2124 0 1 136 159
+					V 240
+					H 176
+					A 8 8 0 0 1 176 256
+					H 80
+					A 8 8 0 0 1 80 240
+					H 120
+					V 159					
+					A 97.0039 135.3148 36.2124 0 1 62 122
+					A 44.7901 78.5247 -1.1521 0 1 72 0
+					H184
+				z"/>
+		</g>
+		<g transform="translate(16 16)" id="wine-level">
+			<path d=
+				"M182,64
+					H 74
+					A 115.9979 308.8033 38.9474 0 0 128 134.4277
+					A 115.9979 308.8033 -38.9474 0 0 182,64
+				z"/>
+		</g>
+	</defs>	
+	<use href="#glass" stroke="#ffffffa0" stroke-width="16" fill="Transparent" />
+	<use href="#wine-level" stroke="#ffffffa0" stroke-width="16" fill="Transparent" />
+	<use href="#glass" fill="Black" />
+	<use href="#wine-level" fill="Black" />
+</svg>

Images/libation_hangover.svg

@@ -0,0 +1,31 @@
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 288 288" enable-background="new 0 0 288 288">
+	<g>
+		<path transform="rotate(90 128,128) translate(60 -16)" fill-rule="evenodd" d=
+			"M177,16
+				H79
+				A 32.0781 63.7932 -1.5106 0 0 66 80
+				A 158.789 471.1259 41.9466 0 0 90 131
+				A 81.7197 122.0515 35.3745 0 0 128 143.3484
+				A 81.7197 122.0515 -35.3745 0 0 166 131
+				A 158.789 471.1259 -41.9466 0 0 190 80
+				A 32.0781 63.7932 1.5106 0 0 177 16
+				L 184 0
+				A 44.7901 78.5247 1.1521 0 1 194 122
+				A 97.0039 135.3148 -36.2124 0 1 136 159
+				V 240
+				H 176
+				A 8 8 0 0 1 176 256
+				H 80
+				A 8 8 0 0 1 80 240
+				H 120
+				V 159					
+				A 97.0039 135.3148 36.2124 0 1 62 122
+				A 44.7901 78.5247 -1.1521 0 1 72 0
+				H184
+			M170,115
+				V24
+				A 19.5181 45.9183 -3.3549 0 1 182.4322 69.5
+				A 19.5181 45.9183 3.3549 0 1 170 115
+			z"/>
+	</g>
+</svg>

Images/libation_slosh.svg

@@ -0,0 +1,33 @@
+<svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 512 512" enable-background="new 0 0 512 512">
+<path
+transform=
+	"rotate(15 256,256)
+	translate(0 25)
+	scale(0.93, 0.93)"
+d=
+"M139,2
+	A 192,200 0 0 0 103,84
+	A 222,334 41 0 0 241,320
+	V478
+	H160
+	A 16,16 0 0 0 160,510
+	H352
+	A16 16 0 0 0 352,478
+	H271
+	V320
+	A 222,334 -41 0 0 409,84
+	A 192,200 0 0 0 373,2
+M355,32
+	A 192,200 0 0 1 381,127
+	A 187.5,334 -35 0 1 256,286
+	A 187.5,334 35 0 1 131,127
+	A 192,200 0 0 1 157,32
+	H355
+M146,147
+	A 168,300 35 0 0 256,270
+	A 168,300 -35 0 0 366,128
+	S 360,50 280,110
+	S 192,128 147,147
+z" />
+
+</svg>

README.md

@@ -1,69 +1,58 @@
 # Libation: Liberate your Library
 
-## [Download Libation](https://github.com/rmcrackan/Libation/releases/latest)
+**Libation** is a free, open-source application for downloading and managing your Audible audiobooks. It decrypts your library, removes DRM, and lets you own your audiobooks forever.
 
-### If you found this useful, tell a friend. If you found this REALLY useful, you can click here to [PalPal.me](https://paypal.me/mcrackan?locale.x=en_us)
-...or just tell more friends. As long as I'm maintaining this software, it will remain **free** and **open source**.
+> <a href="https://getlibation.com"><img src=".github/download-icon.svg" width="20" height="20" alt="" /></a> **[Which version should I download?](https://getlibation.com)** — get a recommended download for your system on our site.
 
-# Table of Contents
+## Features
 
-- [Audible audiobook manager](#audible-audiobook-manager)
-    - [The good](#the-good)
-    - [The bad](#the-bad)
-    - [The ugly](#the-ugly)
-- [Getting started](Documentation/GettingStarted.md)
-    - [Download Libation](Documentation/GettingStarted.md#download-libation-1)
-    - [Installation](Documentation/GettingStarted.md#installation)
-    - [Create Accounts](Documentation/GettingStarted.md#create-accounts)
-    - [Import your library](Documentation/GettingStarted.md#import-your-library)
-    - [Download your books -- DRM-free!](Documentation/GettingStarted.md#download-your-books----drm-free)
-    - [Download PDF attachments](Documentation/GettingStarted.md#download-pdf-attachments)
-    - [Details of downloaded files](Documentation/GettingStarted.md#details-of-downloaded-files)
-    - [Export your library](Documentation/GettingStarted.md#export-your-library)
-- [Searching and filtering](Documentation/SearchingAndFiltering.md)
-    - [Tags](Documentation/SearchingAndFiltering.md#tags)
-    - [Searches](Documentation/SearchingAndFiltering.md#searches)
-    - [Search examples](Documentation/SearchingAndFiltering.md#search-examples)
-    - [Filters](Documentation/SearchingAndFiltering.md#filters)
-- [Advanced](Documentation/Advanced.md)
-    - [Files and folders](Documentation/Advanced.md#files-and-folders)
-    - [Settings](Documentation/Advanced.md#settings)
-    - [Custom File Naming](Documentation/NamingTemplates.md)
-    - [Command Line Interface](Documentation/Advanced.md#command-line-interface)
-- [Docker](Documentation/Docker.md)
+- **Unlock Your Library**: Download and remove DRM from your audiobooks.
+- **Cross-Platform**: Fully supported on Windows, macOS, and Linux.
+- **Region Support**: Works with Audible regions US, UK, Canada, Germany, France, Australia, Japan, India, and Spain.
+- **Advanced Organization**: Search, filter, and tag your books.
+- **Fast & Efficient**: Powered by AAXClean for fast decryption without heavy dependencies like ffmpeg.
+- **Import**: Easily import your existing library, including cover art.
 
-## Getting started
+## Getting started with Libation
 
+All documentation has been moved to our new site: [getlibation.com](https://getlibation.com). Or jump to the important bits:
+
+* [Getting Started](https://getlibation.com/docs/getting-started)
 * [Download](https://github.com/rmcrackan/Libation/releases/latest)
-* [Step-by-step walk-through](Documentation/GettingStarted.md)
+* [Issues, bugs, and requests](https://github.com/rmcrackan/Libation/issues)
+* [Documentation](https://getlibation.com/docs/index)
 
-## Audible audiobook manager
+## Development
 
-### The good
+Grab the latest release for your platform from the [Releases Page](https://github.com/rmcrackan/Libation/releases/latest).
 
-* Import library from audible, including cover art
-* Download and remove DRM from all books
-* Download accompanying PDFs
-* Add tags to books for better organization
-* Powerful advanced search built on the Lucene search engine
-* Customizable saved filters for common searches
-* Open source
-* Supports most regions: US, UK, Canada, Germany, France, Australia, Japan, India, and Spain
+## Documentation
 
-<a name="theBad"/>
+Comprehensive documentation is available in the `docs` directory and on our [Documentation Site](https://getlibation.com/docs).
 
-### The bad
+- [Getting Started](https://getlibation.com/docs/getting-started)
+- [FAQ](https://getlibation.com/docs/frequently-asked-questions)
+- [Spatial Audio & DRM](https://getlibation.com/docs/advanced/spatial-audio)
 
-* Only fully supported in Windows. (Mac and Linux are in beta)
-* Large file size
-* Made by a programmer, not a designer so the goals are function rather than beauty. And it shows
+## Development & Contributing
 
-### The ugly
+We welcome contributions!
 
-* Documentation? Yer lookin' at it
-* This is a single-developer personal passion project. Support, response, updates, enhancements, bug fixes etc are as my free time allows
-* I have a full-time job, a life, and a finite attention span. Therefore a lot of time can potentially go by with no improvements of any kind
+- **[Development Getting Started](https://getlibation.com/docs/development/getting-started)**: Setup your environment.
+- **[Contribute](https://getlibation.com/docs/development/contribute)**: How to contribute code.
+- **[Website & Docs](https://getlibation.com/docs/development/website)**: How to run and improve the documentation.
+- **[Linux Setup (Nix)](https://getlibation.com/docs/development/nix-linux-setup)**: Nix-based environment setup.
 
-Disclaimer: I've made every good-faith effort to include nothing insecure, malicious, anti-privacy, or destructive. That said: use at your own risk.
+## Community & Support
 
-I made this for myself and I want to share it with the great programming and audible/audiobook communities which have been so generous with their time and help.
+- **[Issues](https://github.com/rmcrackan/Libation/issues)**: Report bugs or request features.
+- **[PayPal](https://paypal.me/mcrackan?locale.x=en_us)**: Support the project if you find it useful.
+
+## License
+
+Libation is released under the GPL-3.0 License
+
+---
+
+If you found this useful, tell a friend. If you found this REALLY useful, you can [donate here](https://getlibation.com/donate)
+...or just tell more friends. As long as I'm maintaining this software, it will remain free and open source.

Scripts/Bundle_Debian.sh

@@ -0,0 +1,130 @@
+#!/bin/bash
+
+BIN_DIR=$1; shift
+VERSION=$1; shift
+ARCH=$1; shift
+
+if [ -z "$BIN_DIR" ]
+then
+  echo "This script must be called with a the Libation Linux bins directory as an argument."
+  exit
+fi
+
+if [ ! -d "$BIN_DIR" ]
+then
+  echo "The directory \"$BIN_DIR\" does not exist."
+  exit
+fi
+
+if [ -z "$VERSION" ]
+then
+  echo "This script must be called with the Libation version number as an argument."
+  exit
+fi
+
+if [ -z "$ARCH" ]
+then
+  echo "This script must be called with the Libation cpu architecture as an argument."
+  exit
+fi
+
+ARCH=$(echo $ARCH | sed 's/x64/amd64/')
+
+DEB_DIR=./deb
+
+FOLDER_EXEC=$DEB_DIR/usr/lib/libation
+echo "Exec dir: $FOLDER_EXEC"
+mkdir -p $FOLDER_EXEC
+
+echo "Moving bins from $BIN_DIR to $FOLDER_EXEC"
+mv "${BIN_DIR}/"* $FOLDER_EXEC
+
+if [ $? -ne 0 ]
+ then echo "Error moving ${BIN_DIR} files"
+ exit
+fi
+
+
+delfiles=('LinuxConfigApp' 'LinuxConfigApp.deps.json' 'LinuxConfigApp.runtimeconfig.json')
+
+for n in "${delfiles[@]}"
+do
+  echo "Deleting $n"
+  rm $FOLDER_EXEC/$n
+done
+
+FOLDER_ICON=$DEB_DIR/usr/share/icons/hicolor/scalable/apps/
+echo "Icon dir: $FOLDER_ICON"
+
+FOLDER_DESKTOP=$DEB_DIR/usr/share/applications
+echo "Desktop dir: $FOLDER_DESKTOP"
+
+FOLDER_DEBIAN=$DEB_DIR/DEBIAN
+echo "Debian dir: $FOLDER_DEBIAN"
+
+mkdir -p $FOLDER_ICON
+mkdir -p $FOLDER_DESKTOP
+mkdir -p $FOLDER_DEBIAN
+
+echo "Copying icon..."
+cp $FOLDER_EXEC/libation_glass.svg $FOLDER_ICON/libation.svg
+
+echo "Copying desktop file..."
+cp $FOLDER_EXEC/Libation.desktop $FOLDER_DESKTOP/Libation.desktop
+
+echo "Creating pre-install file..."
+echo "#!/bin/bash
+# Pre-install script, removes previous installation program files and sym links
+echo \"Removing previously created symlinks...\"
+rm /usr/bin/libation
+rm /usr/bin/hangover
+rm /usr/bin/libationcli
+echo \"Removing previously installed Libation files...\"
+rm -r /usr/lib/libation
+# making sure it won't stop installation
+exit 0
+" >> $FOLDER_DEBIAN/preinst
+
+echo "Creating post-install file..."
+echo "#!/bin/bash
+gtk-update-icon-cache -f /usr/share/icons/hicolor/
+ln -s /usr/lib/libation/Libation /usr/bin/libation
+ln -s /usr/lib/libation/Hangover /usr/bin/hangover
+ln -s /usr/lib/libation/LibationCli /usr/bin/libationcli
+# Increase the maximum number of inotify instances
+if ! grep -q 'fs.inotify.max_user_instances=524288' /etc/sysctl.conf; then
+  echo fs.inotify.max_user_instances=524288 | tee -a /etc/sysctl.conf && sysctl -p
+fi
+" >> $FOLDER_DEBIAN/postinst
+
+echo "Creating control file..."
+echo "Package: Libation
+Version: $VERSION
+Architecture: $ARCH
+Essential: no
+Priority: optional
+Maintainer: github.com/rmcrackan
+Description: liberate your audiobooks
+Recommends: libgtk-3-0, libwebkit2gtk-4.1-0
+" >> $FOLDER_DEBIAN/control
+
+echo "Changing permissions for pre- and post-install files..."
+chmod +x "$FOLDER_DEBIAN/preinst"
+chmod +x "$FOLDER_DEBIAN/postinst"
+
+if [ "$(uname -s)" == "Darwin" ]; then
+  echo "macOS detected, installing dpkg"
+  brew install dpkg
+fi
+
+DEB_FILE=Libation.${VERSION}-linux-chardonnay-${ARCH}.deb
+echo "Creating $DEB_FILE"
+dpkg-deb -Zxz --build $DEB_DIR ./$DEB_FILE
+
+echo "moving to ./bundle/$DEB_FILE"
+mkdir bundle
+mv $DEB_FILE ./bundle/$DEB_FILE
+
+rm -r "$BIN_DIR"
+
+echo "Done!"

Scripts/Bundle_MacOS.sh

@@ -0,0 +1,174 @@
+#!/bin/bash
+set -euo pipefail
+
+BIN_DIR=$1; shift
+VERSION=$1; shift
+ARCH=$1; shift
+SIGN_WITH_KEY=$1; shift
+
+if [ -z "$BIN_DIR" ]
+then
+  echo "This script must be called with a the Libation macos bins directory as an argument."
+  exit 1
+fi
+
+if [ ! -d "$BIN_DIR" ]
+then
+  echo "The directory \"$BIN_DIR\" does not exist."
+  exit 1
+fi
+
+if [ -z "${VERSION:-}" ]
+then
+  echo "This script must be called with the Libation version number as an argument."
+  exit 1
+fi
+
+if [ -z "${ARCH:-}" ]
+then
+  echo "This script must be called with the Libation cpu architecture as an argument."
+  exit 1
+fi
+
+if [ "$SIGN_WITH_KEY" != "true" ]
+then
+  echo "::warning:: App will fail Gatekeeper verification without valid Apple Team information."
+fi
+
+BUNDLE=./Libation.app
+echo "Bundle dir: $BUNDLE"
+
+if [[ -d $BUNDLE ]]
+then
+  echo "$BUNDLE directory already exists, aborting."
+  exit 1
+fi
+
+# hdiutil create intermittently fails on CI with "Resource busy" (macOS background scanning).
+create_dmg_with_retry() {
+  local src_folder="$1"
+  local output_path="$2"
+  local max_attempts=10
+  local attempt=1
+  local delay=3
+
+  while [ "$attempt" -le "$max_attempts" ]; do
+    echo "Creating disk image (attempt ${attempt}/${max_attempts}): ${output_path}"
+    rm -f "${output_path}"
+    sync
+    sleep 1
+
+    if hdiutil create -srcFolder "${src_folder}" -ov -format UDZO -o "${output_path}"; then
+      if [ -f "${output_path}" ]; then
+        return 0
+      fi
+    fi
+
+    echo "hdiutil create failed on attempt ${attempt}"
+    hdiutil detach -force /Volumes/Libation 2>/dev/null || true
+    rm -f "${output_path}" "${output_path}.temp.dmg" 2>/dev/null || true
+    sync
+
+    if [ "$attempt" -lt "$max_attempts" ]; then
+      echo "Waiting ${delay}s before retry..."
+      sleep "${delay}"
+      delay=$((delay + 2))
+    fi
+    attempt=$((attempt + 1))
+  done
+
+  echo "Error: hdiutil create failed after ${max_attempts} attempts"
+  return 1
+}
+
+BUNDLE_CONTENTS=$BUNDLE/Contents
+echo "Bundle Contents dir: $BUNDLE_CONTENTS"
+
+BUNDLE_RESOURCES=$BUNDLE_CONTENTS/Resources
+echo "Resources dir: $BUNDLE_RESOURCES"
+
+BUNDLE_MACOS=$BUNDLE_CONTENTS/MacOS
+echo "MacOS dir: $BUNDLE_MACOS"
+
+mkdir -p $BUNDLE_CONTENTS
+mkdir -p $BUNDLE_RESOURCES
+mkdir -p $BUNDLE_MACOS
+
+mv "${BIN_DIR}/"*  $BUNDLE_MACOS
+
+if [ $? -ne 0 ]; then
+  echo "Error moving ${BIN_DIR} files"
+  exit 1
+fi
+
+echo "Make fileicon executable..."
+chmod +x $BUNDLE_MACOS/fileicon
+
+echo "Moving icon..."
+mv $BUNDLE_MACOS/libation.icns $BUNDLE_RESOURCES/libation.icns
+
+echo "Moving Info.plist file..."
+mv $BUNDLE_MACOS/Info.plist $BUNDLE_CONTENTS/Info.plist
+
+echo "Writing PkgInfo file..."
+printf 'APPL????' > $BUNDLE_CONTENTS/PkgInfo
+
+echo "Moving Libation_DS_Store file..."
+mv $BUNDLE_MACOS/Libation_DS_Store ./Libation_DS_Store
+
+echo "Moving background.png file..."
+mv $BUNDLE_MACOS/background.png ./background.png
+
+echo "Moving background.png file..."
+mv $BUNDLE_MACOS/Libation.entitlements ./Libation.entitlements
+
+PLIST_ARCH=$(echo $ARCH | sed 's/x64/x86_64/')
+echo "Set LSArchitecturePriority to $PLIST_ARCH"
+# Portable sed -i (BSD sed on macOS requires backup arg; use .bak then remove)
+sed -i.bak "s/ARCHITECTURE_STRING/$PLIST_ARCH/" $BUNDLE_CONTENTS/Info.plist && rm -f $BUNDLE_CONTENTS/Info.plist.bak
+
+echo "Set CFBundleVersion to $VERSION"
+sed -i.bak "s/VERSION_STRING/$VERSION/" $BUNDLE_CONTENTS/Info.plist && rm -f $BUNDLE_CONTENTS/Info.plist.bak
+
+delfiles=('MacOSConfigApp' 'MacOSConfigApp.deps.json' 'MacOSConfigApp.runtimeconfig.json')
+for n in "${delfiles[@]}"
+do
+  echo "Deleting $n"
+  rm $BUNDLE_MACOS/$n
+done
+
+DMG_FILE="Libation.${VERSION}-macOS-chardonnay-${ARCH}.dmg"
+
+all_identities=$(security find-identity -v -p codesigning)
+identity=$(echo ${all_identities} | sed -n 's/.*"\(.*\)".*/\1/p')
+
+if [ "$SIGN_WITH_KEY" == "true" ]; then
+  echo "Signing executables in: $BUNDLE"
+  codesign --force --deep --timestamp --options=runtime --entitlements "./Libation.entitlements" --sign "${identity}" "$BUNDLE"
+  codesign --verify --verbose "$BUNDLE"
+else
+  echo "Signing with empty key: $BUNDLE"
+  codesign --force --deep -s - $BUNDLE
+fi
+
+echo "Creating app disk image: $DMG_FILE"
+mkdir Libation
+mv $BUNDLE ./Libation/$BUNDLE
+mv Libation_DS_Store Libation/.DS_Store
+mkdir Libation/.background
+mv background.png Libation/.background/
+ln -s /Applications "./Libation/ "
+mkdir ./bundle
+create_dmg_with_retry ./Libation "./bundle/$DMG_FILE"
+# Create a .DS_Store by:
+#  - mounting an existing image in shadow mode (hdiutil attach Libation.dmg -shadow junk.dmg)
+#  - Open the folder and edit it to your liking.
+#  - Copy the .DS_Store from the directory and save it to Libation_DS_Store
+
+
+if [ "$SIGN_WITH_KEY" == "true" ]; then
+  echo "Signing $DMG_FILE"
+  codesign --deep --sign "${identity}" "./bundle/$DMG_FILE"
+fi
+
+echo "Done!"

Scripts/Bundle_Redhat.sh

@@ -0,0 +1,133 @@
+#!/bin/bash
+
+BIN_DIR=$1; shift
+VERSION=$1; shift
+ARCH=$1; shift
+
+if [ -z "$BIN_DIR" ]
+then
+  echo "This script must be called with a the Libation Linux bins directory as an argument."
+  exit
+fi
+
+if [ ! -d "$BIN_DIR" ]
+then
+  echo "The directory \"$BIN_DIR\" does not exist."
+  exit
+fi
+
+if [ -z "$VERSION" ]
+then
+  echo "This script must be called with the Libation version number as an argument."
+  exit
+fi
+
+if [ -z "$ARCH" ]
+then
+  echo "This script must be called with the Libation cpu architecture as an argument."
+  exit
+fi
+
+BASEDIR=$(pwd)
+
+delfiles=('LinuxConfigApp' 'LinuxConfigApp.deps.json' 'LinuxConfigApp.runtimeconfig.json')
+if [[ "$ARCH" == "x64" ]]
+then
+  ARCH_RPM="x86_64"
+  ARCH="amd64"
+else
+  ARCH_RPM="aarch64"
+fi
+
+notinstalled=('libcoreclrtraceptprovider.so' 'libation_glass.svg' 'Libation.desktop')
+
+mkdir -p ~/rpmbuild/SPECS
+mkdir ~/rpmbuild/BUILD
+mkdir ~/rpmbuild/RPMS
+
+echo "Name:           libation
+Version:        ${VERSION}
+Release:        1
+Summary:        Liberate your Audible Library
+
+License:        GPLv3+
+URL:            https://github.com/rmcrackan/Libation
+Source0:        https://github.com/rmcrackan/Libation   
+
+Requires:       bash gtk3 webkit2gtk4.1
+
+
+%define __os_install_post %{nil}
+
+%description
+Liberate your Audible Library
+
+%install
+mkdir -p %{buildroot}%{_libdir}/%{name}
+mkdir -p %{buildroot}%{_datadir}/icons/hicolor/scalable/apps
+mkdir -p %{buildroot}%{_datadir}/applications
+
+if test -f 'libcoreclrtraceptprovider.so'; then
+    rm 'libcoreclrtraceptprovider.so'
+fi
+
+
+install -m 666 libation_glass.svg %{buildroot}%{_datadir}/icons/hicolor/scalable/apps/libation.svg
+install -m 666 Libation.desktop %{buildroot}%{_datadir}/applications/Libation.desktop
+
+rm libation_glass.svg
+rm Libation.desktop
+
+install * %{buildroot}%{_libdir}/%{name}/
+
+%post
+
+if [ \$1 -eq 1 ] ; then
+  # Initial installation
+  
+  ln -s %{_libdir}/%{name}/Libation %{_bindir}/libation
+  ln -s %{_libdir}/%{name}/Hangover %{_bindir}/hangover
+  ln -s %{_libdir}/%{name}/LibationCli %{_bindir}/libationcli
+
+  gtk-update-icon-cache -f %{_datadir}/icons/hicolor/
+    
+  if ! grep -q 'fs.inotify.max_user_instances=524288' /etc/sysctl.conf; then
+    echo fs.inotify.max_user_instances=524288 | tee -a /etc/sysctl.conf && sysctl -p
+  fi
+fi
+
+%postun
+if [ \$1 -eq 0 ] ; then
+  # Uninstall
+  rm %{_bindir}/libation
+  rm %{_bindir}/hangover
+  rm %{_bindir}/libationcli
+fi
+
+%files
+%{_datadir}/icons/hicolor/scalable/apps/libation.svg
+%{_datadir}/applications/Libation.desktop" >> ~/rpmbuild/SPECS/libation.spec
+
+
+cd "$BIN_DIR"
+
+for f in *; do
+  if [[ " ${delfiles[*]} " =~ " ${f} " ]]; then
+    echo "Deleting $f"
+  elif [[ ! " ${notinstalled[*]} " =~ " ${f} " ]]; then
+    echo "%{_libdir}/%{name}/${f}" >> ~/rpmbuild/SPECS/libation.spec
+    cp $f ~/rpmbuild/BUILD/
+  else
+    cp $f ~/rpmbuild/BUILD/
+  fi
+done
+
+cd ~/rpmbuild/SPECS/
+rpmbuild -bb --target $ARCH_RPM libation.spec
+
+cd $BASEDIR
+RPM_FILE=$(ls ~/rpmbuild/RPMS/${ARCH_RPM})
+
+mkdir bundle
+
+mv ~/rpmbuild/RPMS/${ARCH_RPM}/$RPM_FILE "./bundle/Libation.${VERSION}-linux-chardonnay-${ARCH}.rpm"

Scripts/Windows/Build-WindowsInstaller.ps1

@@ -0,0 +1,164 @@
+#Requires -Version 5.1
+<#
+.SYNOPSIS
+  Builds a Libation Windows setup.exe from a published bin directory using Inno Setup.
+
+.DESCRIPTION
+  Optionally runs dotnet publish (same projects as CI), removes standalone WindowsConfigApp
+  artifacts, then compiles Scripts/Windows/Libation.iss.
+
+.PARAMETER Version
+  Libation version string (e.g. 13.4.1).
+
+.PARAMETER Ui
+  Avalonia (Chardonnay) or WinForms (Classic). Classic is x64 only.
+
+.PARAMETER Architecture
+  x64 or arm64 (Avalonia only).
+
+.PARAMETER BinDir
+  Folder containing published files. Defaults to repo-root bin.
+
+.PARAMETER SkipPublish
+  Skip dotnet publish; BinDir must already contain a complete publish output.
+
+.EXAMPLE
+  .\Build-WindowsInstaller.ps1 -Version 13.4.1 -Ui Avalonia -Architecture x64
+
+.EXAMPLE
+  .\Build-WindowsInstaller.ps1 -Version 13.4.1 -Ui WinForms
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string] $Version,
+
+    [ValidateSet('Avalonia', 'WinForms')]
+    [string] $Ui = 'Avalonia',
+
+    [ValidateSet('x64', 'arm64')]
+    [string] $Architecture = 'x64',
+
+    [string] $BinDir = '',
+
+    [switch] $SkipPublish
+)
+
+$ErrorActionPreference = 'Stop'
+
+if ($Ui -eq 'WinForms' -and $Architecture -ne 'x64') {
+    throw 'Classic (WinForms) is only published for x64.'
+}
+
+$repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..\..')
+$sourceDir = Join-Path $repoRoot 'Source'
+if (-not $BinDir) {
+    $BinDir = Join-Path $repoRoot 'bin'
+}
+if (-not (Test-Path $BinDir)) {
+    New-Item -ItemType Directory -Path $BinDir -Force | Out-Null
+}
+$BinDir = (Resolve-Path $BinDir).Path
+
+$runtime = "win-$Architecture"
+$releaseName = if ($Ui -eq 'WinForms') { 'classic' } else { 'chardonnay' }
+$outputBase = if ($Ui -eq 'WinForms') {
+    "Libation-Classic.$Version-windows-$releaseName-$Architecture-setup"
+} else {
+    "Libation.$Version-windows-$releaseName-$Architecture-setup"
+}
+$architecturesAllowed = if ($Architecture -eq 'arm64') { 'arm64' } else { 'x64compatible' }
+
+function Find-ISCC {
+    $candidates = @(
+        "${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe",
+        "$env:ProgramFiles\Inno Setup 6\ISCC.exe",
+        "${env:LocalAppData}\Programs\Inno Setup 6\ISCC.exe"
+    )
+    foreach ($path in $candidates) {
+        if (Test-Path $path) { return $path }
+    }
+    return $null
+}
+
+if (-not $SkipPublish -and (Test-Path $BinDir)) {
+    Write-Host "Clearing $BinDir before publish ..."
+    Get-ChildItem -LiteralPath $BinDir -Force | Remove-Item -Recurse -Force -ErrorAction SilentlyContinue
+}
+
+if (-not $SkipPublish) {
+    Write-Host "Publishing Libation ($Ui, $runtime) to $BinDir ..."
+    Push-Location $sourceDir
+    try {
+        $publishArgs = @(
+            '--runtime', $runtime,
+            '--configuration', 'Release',
+            '--output', $BinDir,
+            '-p:PublishProtocol=FileSystem',
+            '-p:PublishReadyToRun=false',
+            '-p:SelfContained=true'
+        )
+        dotnet publish "Libation$Ui/Libation$Ui.csproj" @publishArgs
+        dotnet publish 'LoadByOS/WindowsConfigApp/WindowsConfigApp.csproj' @publishArgs
+        dotnet publish 'LibationCli/LibationCli.csproj' @publishArgs
+        dotnet publish "Hangover$Ui/Hangover$Ui.csproj" @publishArgs
+    }
+    finally {
+        Pop-Location
+    }
+}
+
+Write-Host 'Removing standalone WindowsConfigApp launcher artifacts ...'
+$removeFiles = @(
+    'WindowsConfigApp.exe',
+    'WindowsConfigApp.runtimeconfig.json',
+    'WindowsConfigApp.deps.json'
+)
+Push-Location $BinDir
+try {
+    foreach ($file in $removeFiles) {
+        if (Test-Path $file) { Remove-Item $file -Force }
+    }
+    if (-not (Test-Path 'Libation.exe')) {
+        throw "Libation.exe not found in $BinDir. Publish or point -BinDir at a complete output folder."
+    }
+    if (-not (Test-Path 'ZipExtractor.exe')) {
+        throw "ZipExtractor.exe not found in $BinDir. It is required for in-app upgrades."
+    }
+}
+finally {
+    Pop-Location
+}
+
+$iscc = Find-ISCC
+if (-not $iscc) {
+    throw @"
+Inno Setup 6 (ISCC.exe) was not found. Install from https://jrsoftware.org/isdl.php
+and ensure ISCC.exe is under Program Files (x86)\Inno Setup 6\ or similar.
+"@
+}
+
+$setupIcon = Join-Path $PSScriptRoot 'libation.ico'
+if (-not (Test-Path $setupIcon)) {
+    throw "Installer icon not found: $setupIcon"
+}
+$iss = Join-Path $PSScriptRoot 'Libation.iss'
+$defines = @(
+    "/DMyVersion=$Version",
+    "/DMySetupIcon=$setupIcon",
+    "/DMyReleaseName=$releaseName",
+    "/DMyArchitecture=$Architecture",
+    "/DOutputBaseFilename=$outputBase",
+    "/DSourceDir=$BinDir",
+    "/DOutputDir=$BinDir",
+    "/DArchitecturesAllowed=$architecturesAllowed"
+)
+
+Write-Host "Compiling $outputBase.exe ..."
+& $iscc $defines $iss
+if ($LASTEXITCODE -ne 0) {
+    throw "ISCC failed with exit code $LASTEXITCODE."
+}
+
+$setupPath = Join-Path $BinDir "$outputBase.exe"
+Write-Host "Done: $setupPath"

Scripts/Windows/Libation.iss

@@ -0,0 +1,93 @@
+; Libation Windows installer (Inno Setup 6.x)
+;
+; Compile with ISCC and /D defines. See Scripts/Windows/README.md and
+; Build-WindowsInstaller.ps1 for local builds; CI will pass the same defines.
+;
+; Required /D defines from build script:
+;   MyVersion, MyReleaseName, MyArchitecture, MySetupIcon,
+;   OutputBaseFilename, SourceDir, OutputDir, ArchitecturesAllowed
+
+#ifndef MyVersion
+  #define MyVersion "0.0.0-dev"
+#endif
+#ifndef MyReleaseName
+  #define MyReleaseName "chardonnay"
+#endif
+#ifndef MyArchitecture
+  #define MyArchitecture "x64"
+#endif
+#ifndef MySetupIcon
+  #define MySetupIcon "libation.ico"
+#endif
+#ifndef OutputBaseFilename
+  #define OutputBaseFilename "Libation.0.0.0-dev-windows-chardonnay-x64-setup"
+#endif
+#ifndef SourceDir
+  #define SourceDir "."
+#endif
+#ifndef OutputDir
+  #define OutputDir "."
+#endif
+#ifndef ArchitecturesAllowed
+  #define ArchitecturesAllowed "x64compatible"
+#endif
+
+#if MyReleaseName == 'classic'
+  #define InstallFolderName "Libation-Classic"
+  #define AppName "Libation (Classic)"
+#else
+  #define InstallFolderName "Libation"
+  #define AppName "Libation (Chardonnay)"
+#endif
+
+[Setup]
+#if MyReleaseName == 'classic'
+AppId={{B1C2D3E4-F5A6-4B7C-8D9E-0F1A2B3C4D5E}}
+#elif MyArchitecture == 'arm64'
+AppId={{C2D3E4F5-A6B7-4C8D-9E0F-1A2B3C4D5E6F}}
+#else
+AppId={{A7B8C9D0-E1F2-4A3B-8C9D-0E1F2A3B4C5D}}
+#endif
+AppName={#AppName}
+AppVersion={#MyVersion}
+AppVerName={#AppName} {#MyVersion}
+AppPublisher=Libation
+AppPublisherURL=https://getlibation.com/
+AppSupportURL=https://github.com/rmcrackan/Libation/issues
+AppUpdatesURL=https://github.com/rmcrackan/Libation/releases
+DefaultDirName={localappdata}\{#InstallFolderName}
+DefaultGroupName={#AppName}
+PrivilegesRequired=lowest
+OutputDir={#OutputDir}
+OutputBaseFilename={#OutputBaseFilename}
+SourceDir={#SourceDir}
+ArchitecturesAllowed={#ArchitecturesAllowed}
+ArchitecturesInstallIn64BitMode=x64compatible
+DisableProgramGroupPage=no
+Compression=lzma2
+SolidCompression=yes
+WizardStyle=modern
+SetupIconFile={#MySetupIcon}
+UninstallDisplayIcon={app}\Libation.exe
+UninstallDisplayName={#AppName}
+VersionInfoVersion={#MyVersion}
+VersionInfoProductName={#AppName}
+VersionInfoCompany=Libation
+
+[Languages]
+Name: "english"; MessagesFile: "compiler:Default.isl"
+
+[Tasks]
+Name: "desktopicon"; Description: "{cm:CreateDesktopIcon}"; GroupDescription: "{cm:AdditionalIcons}"; Flags: unchecked
+
+[Files]
+Source: "*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs
+
+[Icons]
+Name: "{group}\Libation"; Filename: "{app}\Libation.exe"; Comment: "Libation audiobook manager"
+Name: "{group}\Hangover"; Filename: "{app}\Hangover.exe"; Comment: "Hangover license viewer"
+Name: "{group}\Libation CLI"; Filename: "{app}\LibationCli.exe"; Comment: "Libation command-line tools"
+Name: "{autodesktop}\Libation"; Filename: "{app}\Libation.exe"; Tasks: desktopicon; Comment: "Libation audiobook manager"
+
+[Run]
+Filename: "{app}\Libation.exe"; Description: "{cm:LaunchProgram,{#StringChange(AppName, '&', '&&')}}"; Flags: nowait postinstall skipifsilent

Scripts/Windows/README.md

@@ -0,0 +1,89 @@
+# Windows installer (Inno Setup)
+
+Step 8.1 of the Windows installers plan: a parameterized Inno Setup script that installs the same flat publish layout as the release zip, under a per-user directory, so the in-app upgrader can still overlay files via `ZipExtractor.exe`.
+
+## Prerequisites
+
+1. [.NET SDK](https://dotnet.microsoft.com/download) (same version as the repo; see `build.yml`).
+2. [Inno Setup 6](https://jrsoftware.org/isdl.php) with `ISCC.exe` on PATH or in a default install location.
+
+## Quick build (publish + installer)
+
+From PowerShell, repo root or this folder:
+
+```powershell
+.\Scripts\Windows\Build-WindowsInstaller.ps1 -Version 13.4.1 -Ui Avalonia -Architecture x64
+```
+
+Outputs:
+
+- Publish tree: `bin\` (repo root)
+- Installer: `bin\Libation.13.4.1-windows-chardonnay-x64-setup.exe`
+
+### Variants
+
+| UI | `-Ui` | `-Architecture` | Install folder | Output prefix |
+|----|-------|-----------------|----------------|---------------|
+| Chardonnay x64 | `Avalonia` | `x64` | `%LocalAppData%\Libation` | `Libation.*` |
+| Chardonnay arm64 | `Avalonia` | `arm64` | `%LocalAppData%\Libation` | `Libation.*` |
+| Classic x64 | `WinForms` | `x64` (default) | `%LocalAppData%\Libation-Classic` | `Libation-Classic.*-setup.exe` |
+
+Examples:
+
+```powershell
+.\Scripts\Windows\Build-WindowsInstaller.ps1 -Version 13.4.1 -Ui WinForms
+.\Scripts\Windows\Build-WindowsInstaller.ps1 -Version 13.4.1 -Ui Avalonia -Architecture arm64
+```
+
+### Reuse an existing publish folder
+
+```powershell
+.\Scripts\Windows\Build-WindowsInstaller.ps1 -Version 13.4.1 -Ui Avalonia -BinDir C:\path\to\bin -SkipPublish
+```
+
+`BinDir` must already match CI layout (including `ZipExtractor.exe`, without standalone `WindowsConfigApp.exe`).
+
+## Manual ISCC (without the helper script)
+
+After publish and cleanup (remove `WindowsConfigApp.exe`, `WindowsConfigApp.runtimeconfig.json`, `WindowsConfigApp.deps.json` from `bin`), from `Scripts\Windows`:
+
+```text
+"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" Libation.iss ^
+  /DMyVersion=13.4.1 ^
+  /DMyPrefix= ^
+  /DMyReleaseName=chardonnay ^
+  /DMyArchitecture=x64 ^
+  /DInstallFolderName=Libation ^
+  /DAppName=Libation ^
+  /DOutputBaseFilename=Libation.13.4.1-windows-chardonnay-x64-setup ^
+  /DSourceDir=C:\Dev\_rmcrackan\Libation\bin ^
+  /DOutputDir=C:\Dev\_rmcrackan\Libation\bin ^
+  /DArchitecturesAllowed=x64compatible
+```
+
+Classic x64: use `MyReleaseName=classic` and matching `OutputBaseFilename` (`Libation-Classic.{version}-windows-classic-x64-setup`). Install folder and display name are set in `Libation.iss`. GitHub zip assets use `Libation-Classic.{version}-windows-classic-x64.zip`; `.releaseindex.json` also accepts legacy `Classic-Libation.*` zips on older releases.
+
+arm64: set `MyArchitecture=arm64` and `ArchitecturesAllowed=arm64`.
+
+## Installer behavior
+
+- **Per-user install** (`PrivilegesRequired=lowest`, default dir under `{localappdata}`).
+- **Shortcuts** target `{app}\Libation.exe` (required for upgrade path detection).
+- **Does not** create `appsettings.json` or Libation Files; same as zip install.
+- **Includes** full publish output so `ZipExtractor.exe` remains for in-app updates.
+- **Settings -> Apps:** shows `Libation (Chardonnay)` or `Libation (Classic)` with version in `DisplayVersion` (Inno at install; synced after in-app zip upgrades via `WindowsUninstallRegistrySync`); icon from `SetupIconFile` / `UninstallDisplayIcon` (`Scripts/Windows/libation.ico` and `{app}\Libation.exe`).
+
+## Next plan step (8.2)
+
+Install via `*-setup.exe`, run the app, then verify an older release can upgrade in-app using the existing zip-based upgrader.
+
+CI wiring (`build-windows.yml`) is step 8.3.
+
+## Files in this folder
+
+| File | Purpose |
+|------|---------|
+| `Libation.iss` | Parameterized Inno Setup script |
+| `libation.ico` | Setup/uninstaller icon (copied from Avalonia assets) |
+| `Build-WindowsInstaller.ps1` | Local publish + ISCC helper |
+| `README.md` | This document |

Scripts/targz2deb.sh

@@ -1,136 +0,0 @@
-#!/bin/bash
-
-FILE=$1; shift
-VERSION=$1; shift
-
-if [ -z "$FILE" ]
-then
-  echo "This script must be called with a the Libation Linux bin zip file as an argument."
-  exit
-fi
-
-if [ ! -f "$FILE" ]
-then
-  echo "The file \"$FILE\" does not exist."
-  exit
-fi
-
-if [ -z "$VERSION" ]
-then
-  echo "This script must be called with the Libation version number as an argument."
-  exit
-fi
-
-contains() { case "$1" in *"$2"*) true ;; *) false ;; esac }
-
-if ! contains "$FILE" "$VERSION"
-then
-  echo "This script must be called with a Libation version number that is present in the filename passed."
-  exit
-fi
-
-# remove trailing ".tar.gz"
-FOLDER_MAIN=${FILE::-7}
-echo "Working dir: $FOLDER_MAIN"
-
-if [[ -d "$FOLDER_MAIN" ]]
-then
-  echo "$FOLDER_MAIN directory already exists, aborting."
-  exit
-fi
-
-FOLDER_EXEC="$FOLDER_MAIN/usr/lib/libation"
-echo "Exec dir: $FOLDER_EXEC"
-
-FOLDER_ICON="$FOLDER_MAIN/usr/share/icons/hicolor/scalable/apps/"
-echo "Icon dir: $FOLDER_ICON"
-
-FOLDER_DESKTOP="$FOLDER_MAIN/usr/share/applications"
-echo "Desktop dir: $FOLDER_DESKTOP"
-
-FOLDER_DEBIAN="$FOLDER_MAIN/DEBIAN"
-echo "Debian dir: $FOLDER_DEBIAN"
-
-mkdir -p "$FOLDER_EXEC"
-mkdir -p "$FOLDER_ICON"
-mkdir -p "$FOLDER_DESKTOP"
-mkdir -p "$FOLDER_DEBIAN"
-
-echo "Extracting $FILE to $FOLDER_EXEC..."
-tar -xzf ${FILE} -C ${FOLDER_EXEC}
-
-if [ $? -ne 0 ]
- then echo "Error extracting ${FILE}"
- exit
-fi
-
-echo "Copying icon..."
-cp "$FOLDER_EXEC/glass-with-glow_256.svg" "$FOLDER_ICON/libation.svg"
-
-echo "Copying desktop file..."
-cp "$FOLDER_EXEC/Libation.desktop" "$FOLDER_DESKTOP/Libation.desktop"
-
-echo "Workaround for desktop file..."
-sed -i '/^Exec=Libation/c\Exec=/usr/bin/libation' "$FOLDER_DESKTOP/Libation.desktop"
-
-echo "Creating pre-install file..."
-echo "#!/bin/bash
-
-# Pre-install script, removes previous installation program files and sym links
-
-echo \"Removing previously created symlinks...\"
-
-rm /usr/bin/libation
-rm /usr/bin/Libation
-rm /usr/bin/hangover
-rm /usr/bin/Hangover
-rm /usr/bin/libationcli
-rm /usr/bin/LibationCli
-
-echo \"Removing previously installed Libation files...\"
-
-rm -r /usr/lib/libation
-rm -r /usr/lib/Libation
-
-# making sure it won't stop installation
-exit 0
-" >> "$FOLDER_DEBIAN/preinst"
-
-echo "Creating post-install file..."
-echo "#!/bin/bash
-
-gtk-update-icon-cache -f /usr/share/icons/hicolor/
-
-ln -s /usr/lib/libation/Libation /usr/bin/libation
-ln -s /usr/lib/libation/Hangover /usr/bin/hangover
-ln -s /usr/lib/libation/LibationCli /usr/bin/libationcli
-
-# Increase the maximum number of inotify instances
-echo fs.inotify.max_user_instances=524288 | tee -a /etc/sysctl.conf && sysctl -p
-
-# workaround until this file is moved to the user's home directory
-touch /usr/lib/libation/appsettings.json
-chmod 666 /usr/lib/libation/appsettings.json
-" >> "$FOLDER_DEBIAN/postinst"
-
-echo "Creating control file..."
-echo "Package: Libation
-Version: $VERSION
-Architecture: all
-Essential: no
-Priority: optional
-Maintainer: github.com/rmcrackan
-Description: liberate your audiobooks
-" >> "$FOLDER_DEBIAN/control"
-
-echo "Changing permissions for pre- and post-install files..."
-chmod +x "$FOLDER_DEBIAN/preinst"
-chmod +x "$FOLDER_DEBIAN/postinst"
-
-echo "Creating .deb file..."
-dpkg-deb -Zxz --build $FOLDER_MAIN
-
-rm -r "$FOLDER_MAIN"
-
-echo "Done!"
-

Source/AaxDecrypter/AaxDecrypter.csproj

@@ -1,7 +1,8 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net7.0</TargetFramework>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
   </PropertyGroup>
 
 	<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
@@ -13,7 +14,7 @@
 	</PropertyGroup>
 
 	<ItemGroup>
-	  <PackageReference Include="AAXClean.Codecs" Version="0.5.12" />
+	  <PackageReference Include="AAXClean.Codecs" Version="3.1.0" />
 	</ItemGroup>
 
 	<ItemGroup>

Source/AaxDecrypter/AaxcDownloadConvertBase.cs

@@ -1,105 +1,150 @@
 using AAXClean;
-using Dinah.Core.Net.Http;
+using Mpeg4Lib;
 using System;
+using System.IO;
+using System.Linq;
 using System.Threading.Tasks;
 
-namespace AaxDecrypter
+namespace AaxDecrypter;
+
+public abstract class AaxcDownloadConvertBase : AudiobookDownloadBase
 {
-	public abstract class AaxcDownloadConvertBase : AudiobookDownloadBase
+	public event EventHandler<MetadataItems>? RetrievedMetadata;
+
+	public Mp4File? AaxFile { get; private set; }
+	protected Mp4Operation? AaxConversion { get; set; }
+
+	protected AaxcDownloadConvertBase(string outDirectory, string cacheDirectory, IDownloadOptions dlOptions)
+		: base(outDirectory, cacheDirectory, dlOptions) { }
+
+	/// <summary>Setting cover art by this method will insert the art into the audiobook metadata</summary>
+	public override void SetCoverArt(byte[] coverArt)
 	{
-		public event EventHandler<AppleTags> RetrievedMetadata;
+		base.SetCoverArt(coverArt);
+		if (coverArt is not null && AaxFile?.MetadataItems is not null)
+			AaxFile.MetadataItems.Cover = coverArt;
+	}
 
-		protected AaxFile AaxFile { get; private set; }
-		private Mp4Operation aaxConversion;
-		protected Mp4Operation AaxConversion
+	public override async Task CancelAsync()
+	{
+		await base.CancelAsync();
+		await (AaxConversion?.CancelAsync() ?? Task.CompletedTask);
+	}
+
+	private Mp4File Open()
+	{
+		if (DownloadOptions.DecryptionKeys is not KeyData[] keys || keys.Length == 0)
+			throw new InvalidOperationException($"{nameof(DownloadOptions.DecryptionKeys)} cannot be null or empty for a '{DownloadOptions.InputType}' file.");
+		else if (DownloadOptions.InputType is FileType.Dash)
 		{
-			get => aaxConversion;
-			set
-			{
-				if (aaxConversion is not null)
-					aaxConversion.ConversionProgressUpdate -= AaxFile_ConversionProgressUpdate;
+			//We may have multiple keys , so use the key whose key ID matches
+			//the dash files default Key ID.
+			var keyIds = keys.Select(k => new Guid(k.KeyPart1, bigEndian: true)).ToArray();
 
-				if (value is not null)
-				{
-					aaxConversion = value;
-					aaxConversion.ConversionProgressUpdate += AaxFile_ConversionProgressUpdate;
-				}
-			}
+			var dash = new DashFile(InputFileStream);
+			if (dash.Tenc is null)
+				throw new InvalidOperationException("The DASH file does not contain 'tenc' box, indicating that it is unencrypted.");
+
+			var kidIndex = Array.IndexOf(keyIds, dash.Tenc.DefaultKID);
+			if (kidIndex == -1)
+				throw new InvalidOperationException($"None of the {keyIds.Length} key IDs match the dash file's default KeyID of {dash.Tenc.DefaultKID}");
+
+			keys[0] = keys[kidIndex];
+			var keyId = keys[kidIndex].KeyPart1;
+			var key = keys[kidIndex].KeyPart2 ?? throw new InvalidOperationException($"{nameof(DownloadOptions.DecryptionKeys)} for '{DownloadOptions.InputType}' must have a non-null decryption key (KeyPart2).");
+			dash.SetDecryptionKey(keyId, key);
+			WriteKeyFile($"KeyId={Convert.ToHexString(keyId)}{Environment.NewLine}Key={Convert.ToHexString(key)}");
+
+			//Remove meta box containing DRM info
+			if (DownloadOptions.FixupFile && dash.Moov.GetChild<Mpeg4Lib.Boxes.MetaBox>() is { } meta)
+				dash.Moov.Children.Remove(meta);
+
+			return dash;
 		}
-
-		protected AaxcDownloadConvertBase(string outFileName, string cacheDirectory, IDownloadOptions dlOptions)
-			: base(outFileName, cacheDirectory, dlOptions) { }
-
-		/// <summary>Setting cover art by this method will insert the art into the audiobook metadata</summary>
-		public override void SetCoverArt(byte[] coverArt)
+		else if (DownloadOptions.InputType is FileType.Aax)
 		{
-			base.SetCoverArt(coverArt);
-			if (coverArt is not null && AaxFile?.AppleTags is not null)
-				AaxFile.AppleTags.Cover = coverArt;
+			var aax = new AaxFile(InputFileStream);
+			var key = keys[0].KeyPart1;
+			aax.SetDecryptionKey(keys[0].KeyPart1);
+			WriteKeyFile($"ActivationBytes={Convert.ToHexString(key)}");
+			return aax;
 		}
-
-		public override async Task CancelAsync()
+		else if (DownloadOptions.InputType is FileType.Aaxc)
 		{
-			IsCanceled = true;
-			await (AaxConversion?.CancelAsync() ?? Task.CompletedTask);
-			FinalizeDownload();
+			var aax = new AaxFile(InputFileStream);
+			var key = keys[0].KeyPart1;
+			var iv = keys[0].KeyPart2 ?? throw new InvalidOperationException($"{nameof(DownloadOptions.DecryptionKeys)} for '{DownloadOptions.InputType}' must have a non-null initialization vector (KeyPart2).");
+			aax.SetDecryptionKey(keys[0].KeyPart1, iv);
+			WriteKeyFile($"Key={Convert.ToHexString(key)}{Environment.NewLine}IV={Convert.ToHexString(iv)}");
+			return aax;
 		}
+		else throw new InvalidOperationException($"{nameof(DownloadOptions.InputType)} of '{DownloadOptions.InputType}' is unknown.");
 
-		protected override void FinalizeDownload()
+		void WriteKeyFile(string contents)
 		{
-			AaxConversion = null;
-			base.FinalizeDownload();
-		}
-
-		protected bool Step_GetMetadata()
-		{
-			AaxFile = new AaxFile(InputFileStream);
-			AaxFile.SetDecryptionKey(DownloadOptions.AudibleKey, DownloadOptions.AudibleIV);
-
-			if (DownloadOptions.StripUnabridged)
-			{
-				AaxFile.AppleTags.Title = AaxFile.AppleTags.TitleSansUnabridged;
-				AaxFile.AppleTags.Album = AaxFile.AppleTags.Album?.Replace(" (Unabridged)", "");
-			}
-
-			if (DownloadOptions.FixupFile && !string.IsNullOrWhiteSpace(AaxFile.AppleTags.Narrator))
-				AaxFile.AppleTags.AppleListBox.EditOrAddTag("TCOM", AaxFile.AppleTags.Narrator);
-
-			//Finishing configuring lame encoder.
-			if (DownloadOptions.OutputFormat == OutputFormat.Mp3)
-				MpegUtil.ConfigureLameOptions(
-					AaxFile,
-					DownloadOptions.LameConfig,
-					DownloadOptions.Downsample,
-					DownloadOptions.MatchSourceBitrate);
-
-			OnRetrievedTitle(AaxFile.AppleTags.TitleSansUnabridged);
-			OnRetrievedAuthors(AaxFile.AppleTags.FirstAuthor ?? "[unknown]");
-			OnRetrievedNarrators(AaxFile.AppleTags.Narrator ?? "[unknown]");
-			OnRetrievedCoverArt(AaxFile.AppleTags.Cover);
-
-			RetrievedMetadata?.Invoke(this, AaxFile.AppleTags);
-
-			return !IsCanceled;
-		}
-
-		private void AaxFile_ConversionProgressUpdate(object sender, ConversionProgressEventArgs e)
-		{
-			var remainingSecsToProcess = (e.TotalDuration - e.ProcessPosition).TotalSeconds;
-			var estTimeRemaining = remainingSecsToProcess / e.ProcessSpeed;
-
-			if (double.IsNormal(estTimeRemaining))
-				OnDecryptTimeRemaining(TimeSpan.FromSeconds(estTimeRemaining));
-
-			var progressPercent = e.ProcessPosition / e.TotalDuration;
-
-			OnDecryptProgressUpdate(
-				new DownloadProgress
-				{
-					ProgressPercentage = 100 * progressPercent,
-					BytesReceived = (long)(InputFileStream.Length * progressPercent),
-					TotalBytesToReceive = InputFileStream.Length
-				});
+			var keyFile = Path.Combine(Path.ChangeExtension(InputFileStream.SaveFilePath, ".key"));
+			File.WriteAllText(keyFile, contents + Environment.NewLine);
+			OnTempFileCreated(new(keyFile));
 		}
 	}
+
+	protected bool Step_GetMetadata()
+	{
+		AaxFile = Open();
+
+		RetrievedMetadata?.Invoke(this, AaxFile.MetadataItems);
+
+		if (DownloadOptions.StripUnabridged)
+		{
+			AaxFile.MetadataItems.Title = AaxFile.MetadataItems.TitleSansUnabridged;
+			AaxFile.MetadataItems.Album = AaxFile.MetadataItems.Album?.Replace(" (Unabridged)", "");
+		}
+
+		if (DownloadOptions.FixupFile)
+		{
+			if (!string.IsNullOrWhiteSpace(AaxFile.MetadataItems.Narrator))
+				AaxFile.MetadataItems.AppleListBox.EditOrAddTag("©wrt", AaxFile.MetadataItems.Narrator);
+
+			if (!string.IsNullOrWhiteSpace(AaxFile.MetadataItems.Copyright))
+				AaxFile.MetadataItems.Copyright = AaxFile.MetadataItems.Copyright.Replace("(P)", "℗").Replace("&#169;", "©");
+
+			//Add audiobook shelf tags
+			//https://github.com/advplyr/audiobookshelf/issues/1794#issuecomment-1565050213
+			const string tagDomain = "com.pilabor.tone";
+
+			AaxFile.MetadataItems.Title = DownloadOptions.Title;
+
+			if (DownloadOptions.Subtitle is string subtitle)
+				AaxFile.MetadataItems.AppleListBox.EditOrAddFreeformTag(tagDomain, "SUBTITLE", subtitle);
+
+			if (DownloadOptions.Publisher is string publisher)
+				AaxFile.MetadataItems.AppleListBox.EditOrAddFreeformTag(tagDomain, "PUBLISHER", publisher);
+
+			if (DownloadOptions.Language is string language)
+				AaxFile.MetadataItems.AppleListBox.EditOrAddFreeformTag(tagDomain, "LANGUAGE", language);
+
+			if (DownloadOptions.AudibleProductId is string asin)
+			{
+				AaxFile.MetadataItems.Asin = asin;
+				AaxFile.MetadataItems.AppleListBox.EditOrAddTag("asin", asin);
+				AaxFile.MetadataItems.AppleListBox.EditOrAddFreeformTag(tagDomain, "AUDIBLE_ASIN", asin);
+			}
+
+			if (DownloadOptions.SeriesName is string series)
+				AaxFile.MetadataItems.AppleListBox.EditOrAddFreeformTag(tagDomain, "SERIES", series);
+
+			if (DownloadOptions.SeriesNumber is string part)
+				AaxFile.MetadataItems.AppleListBox.EditOrAddFreeformTag(tagDomain, "PART", part);
+		}
+
+		OnRetrievedTitle(AaxFile.MetadataItems.TitleSansUnabridged);
+		OnRetrievedAuthors(AaxFile.MetadataItems.FirstAuthor);
+		OnRetrievedNarrators(AaxFile.MetadataItems.Narrator);
+		OnRetrievedCoverArt(AaxFile.MetadataItems.Cover);
+		OnInitialized();
+
+		return !IsCanceled;
+	}
+
+	protected virtual void OnInitialized() { }
 }

Source/AaxDecrypter/AaxcDownloadMultiConverter.cs

@@ -1,147 +1,119 @@
 using AAXClean;
 using AAXClean.Codecs;
 using FileManager;
+using Mpeg4Lib;
 using System;
 using System.IO;
 using System.Threading.Tasks;
 
-namespace AaxDecrypter
+namespace AaxDecrypter;
+
+public class AaxcDownloadMultiConverter : AaxcDownloadConvertBase
 {
-	public class AaxcDownloadMultiConverter : AaxcDownloadConvertBase
+	private static readonly TimeSpan minChapterLength = TimeSpan.FromSeconds(3);
+	private FileStream? workingFileStream;
+
+	public AaxcDownloadMultiConverter(string outDirectory, string cacheDirectory, IDownloadOptions dlOptions)
+		: base(outDirectory, cacheDirectory, dlOptions)
 	{
-		private static readonly TimeSpan minChapterLength = TimeSpan.FromSeconds(3);
-		private FileStream workingFileStream;
+		AsyncSteps.Name = $"Download, Convert Aaxc To {DownloadOptions.OutputFormat}, and Split";
+		AsyncSteps["Step 1: Get Aaxc Metadata"] = () => Task.Run(Step_GetMetadata);
+		AsyncSteps["Step 2: Download Decrypted Audiobook"] = Step_DownloadAndDecryptAudiobookAsync;
+	}
 
-		public AaxcDownloadMultiConverter(string outFileName, string cacheDirectory, IDownloadOptions dlOptions)
-			: base(outFileName, cacheDirectory, dlOptions)
+	protected override void OnInitialized()
+	{
+		//Finishing configuring lame encoder.
+		if (DownloadOptions.OutputFormat == OutputFormat.Mp3)
 		{
-			AsyncSteps.Name = $"Download, Convert Aaxc To {DownloadOptions.OutputFormat}, and Split";
-			AsyncSteps["Step 1: Get Aaxc Metadata"] = () => Task.Run(Step_GetMetadata);
-			AsyncSteps["Step 2: Download Decrypted Audiobook"] = Step_DownloadAndDecryptAudiobookAsync;
-			AsyncSteps["Step 3: Download Clips and Bookmarks"] = Step_DownloadClipsBookmarksAsync;
-		}
+			if (AaxFile is null)
+				throw new InvalidOperationException($"AaxFile is null during {nameof(OnInitialized)} in {nameof(AaxcDownloadConvertBase)}.");
+			if (DownloadOptions.LameConfig is null)
+				throw new InvalidOperationException($"LameConfig is null during {nameof(OnInitialized)} in {nameof(DownloadOptions)}.");
 
-		/*
-https://github.com/rmcrackan/Libation/pull/127#issuecomment-939088489
-
-If the chapter truly is empty, that is, 0 audio frames in length, then yes it is ignored.
-If the chapter is shorter than 3 seconds long but still has some audio frames, those frames are combined with the following chapter and not split into a new file.
-
-I also implemented file naming by chapter title. When 2 or more consecutive chapters are combined, the first of the combined chapter's title is used in the file name. For example, given an audiobook with the following chapters:
-
-00:00:00 - 00:00:02 | Part 1
-00:00:02 - 00:35:00 | Chapter 1
-00:35:02 - 01:02:00 | Chapter 2
-01:02:00 - 01:02:02 | Part 2
-01:02:02 - 01:41:00 | Chapter 3
-01:41:00 - 02:05:00 | Chapter 4
-
-The book will be split into the following files:
-
-00:00:00 - 00:35:00 | Book - 01 - Part 1.m4b
-00:35:00 - 01:02:00 | Book - 02 - Chapter 2.m4b
-01:02:00 - 01:41:00 | Book - 03 - Part 2.m4b
-01:41:00 - 02:05:00 | Book - 04 - Chapter 4.m4b
-
-That naming may not be desirable for everyone, but it's an easy change to instead use the last of the combined chapter's title in the file name.
-		 */
-		protected async override Task<bool> Step_DownloadAndDecryptAudiobookAsync()
-		{
-			var chapters = DownloadOptions.ChapterInfo.Chapters;
-
-			// Ensure split files are at least minChapterLength in duration.
-			var splitChapters = new ChapterInfo(DownloadOptions.ChapterInfo.StartOffset);
-
-			var runningTotal = TimeSpan.Zero;
-			string title = "";
-
-			for (int i = 0; i < chapters.Count; i++)
-			{
-				if (runningTotal == TimeSpan.Zero)
-					title = chapters[i].Title;
-
-				runningTotal += chapters[i].Duration;
-
-				if (runningTotal >= minChapterLength)
-				{
-					splitChapters.AddChapter(title, runningTotal);
-					runningTotal = TimeSpan.Zero;
-				}
-			}
-
-			try
-			{
-				await (AaxConversion = decryptMultiAsync(splitChapters));
-
-				if (AaxConversion.IsCompletedSuccessfully)
-					await moveMoovToBeginning(workingFileStream?.Name);
-
-				return AaxConversion.IsCompletedSuccessfully;
-			}
-			finally
-			{
-				workingFileStream?.Dispose();
-				FinalizeDownload();
-			}
-		}
-
-		private Mp4Operation decryptMultiAsync(ChapterInfo splitChapters)
-		{
-			var chapterCount = 0;
-			return
-				DownloadOptions.OutputFormat == OutputFormat.M4b
-				? AaxFile.ConvertToMultiMp4aAsync
-				(
-					splitChapters,
-					newSplitCallback => newSplit(++chapterCount, splitChapters, newSplitCallback),
-					DownloadOptions.TrimOutputToChapterLength
-				)
-				: AaxFile.ConvertToMultiMp3Async
-				(
-					splitChapters,
-					newSplitCallback => newSplit(++chapterCount, splitChapters, newSplitCallback),
-					DownloadOptions.LameConfig,
-					DownloadOptions.TrimOutputToChapterLength
-				);
-
-			void newSplit(int currentChapter, ChapterInfo splitChapters, NewSplitCallback newSplitCallback)
-			{
-				MultiConvertFileProperties props = new()
-				{
-					OutputFileName = OutputFileName,
-					PartsPosition = currentChapter,
-					PartsTotal = splitChapters.Count,
-					Title = newSplitCallback?.Chapter?.Title,
-				};
-
-				moveMoovToBeginning(workingFileStream?.Name).GetAwaiter().GetResult();
-
-				newSplitCallback.OutputFile = workingFileStream = createOutputFileStream(props);
-				newSplitCallback.TrackTitle = DownloadOptions.GetMultipartTitle(props);
-				newSplitCallback.TrackNumber = currentChapter;
-				newSplitCallback.TrackCount = splitChapters.Count;
-
-				OnFileCreated(workingFileStream.Name);
-			}
-
-			FileStream createOutputFileStream(MultiConvertFileProperties multiConvertFileProperties)
-			{
-				var fileName = DownloadOptions.GetMultipartFileName(multiConvertFileProperties);
-				FileUtility.SaferDelete(fileName);
-				return File.Open(fileName, FileMode.OpenOrCreate, FileAccess.ReadWrite);
-			}
-		}
-
-		private Mp4Operation moveMoovToBeginning(string filename)
-		{
-			if (DownloadOptions.OutputFormat is OutputFormat.M4b
-				&& DownloadOptions.MoveMoovToBeginning
-				&& filename is not null
-				&& File.Exists(filename))
-			{
-				return Mp4File.RelocateMoovAsync(filename);
-			}
-			else return Mp4Operation.CompletedOperation;
+			MpegUtil.ConfigureLameOptions(
+				AaxFile,
+				DownloadOptions.LameConfig,
+				DownloadOptions.Downsample,
+				DownloadOptions.MatchSourceBitrate,
+				chapters: null);
 		}
 	}
+
+
+	protected override async Task<bool> Step_DownloadAndDecryptAudiobookAsync()
+	{
+		if (AaxFile is null) return false;
+
+		try
+		{
+			await (AaxConversion = decryptMultiAsync(AaxFile, DownloadOptions.ChapterInfo));
+
+			if (AaxConversion.IsCompletedSuccessfully)
+				await moveMoovToBeginning(AaxFile, workingFileStream?.Name);
+
+			return AaxConversion.IsCompletedSuccessfully;
+		}
+		finally
+		{
+			workingFileStream?.Dispose();
+			FinalizeDownload();
+		}
+	}
+
+	private Mp4Operation decryptMultiAsync(Mp4File aaxFile, ChapterInfo splitChapters)
+	{
+		var chapterCount = 0;
+		return
+			DownloadOptions.OutputFormat == OutputFormat.M4b
+			? aaxFile.ConvertToMultiMp4aAsync
+			(
+				splitChapters,
+				newSplitCallback => newSplit(++chapterCount, splitChapters, newSplitCallback)
+			)
+			: aaxFile.ConvertToMultiMp3Async
+			(
+				splitChapters,
+				newSplitCallback => newSplit(++chapterCount, splitChapters, newSplitCallback),
+				DownloadOptions.LameConfig
+			);
+
+		void newSplit(int currentChapter, ChapterInfo splitChapters, INewSplitCallback newSplitCallback)
+		{
+			moveMoovToBeginning(aaxFile, workingFileStream?.Name).GetAwaiter().GetResult();
+			var newTempFile = GetNewTempFilePath(DownloadOptions.OutputFormat.ToString());
+			MultiConvertFileProperties props = new()
+			{
+				OutputFileName = newTempFile.FilePath,
+				PartsPosition = currentChapter,
+				PartsTotal = splitChapters.Count,
+				Title = newSplitCallback.Chapter?.Title,
+			};
+
+			newSplitCallback.OutputFile = workingFileStream = createOutputFileStream(props);
+			newSplitCallback.TrackTitle = DownloadOptions.GetMultipartTitle(props);
+			newSplitCallback.TrackNumber = currentChapter;
+			newSplitCallback.TrackCount = splitChapters.Count;
+
+			OnTempFileCreated(newTempFile with { PartProperties = props });
+		}
+
+		FileStream createOutputFileStream(MultiConvertFileProperties multiConvertFileProperties)
+		{
+			FileUtility.SaferDelete(multiConvertFileProperties.OutputFileName);
+			return File.Open(multiConvertFileProperties.OutputFileName, FileMode.OpenOrCreate, FileAccess.ReadWrite);
+		}
+	}
+
+	private Mp4Operation moveMoovToBeginning(Mp4File aaxFile, string? filename)
+	{
+		if (DownloadOptions.OutputFormat is OutputFormat.M4b
+			&& DownloadOptions.MoveMoovToBeginning
+			&& filename is not null
+			&& File.Exists(filename))
+		{
+			return Mp4File.RelocateMoovAsync(filename);
+		}
+		else return Mp4Operation.FromCompleted(aaxFile);
+	}
 }

Source/AaxDecrypter/AaxcDownloadSingleConverter.cs

@@ -1,67 +1,113 @@
 using AAXClean;
 using AAXClean.Codecs;
+using Dinah.Core.Net.Http;
 using FileManager;
+using System;
 using System.IO;
 using System.Threading.Tasks;
 
-namespace AaxDecrypter
+namespace AaxDecrypter;
+
+public class AaxcDownloadSingleConverter : AaxcDownloadConvertBase
 {
-	public class AaxcDownloadSingleConverter : AaxcDownloadConvertBase
+	private readonly AverageSpeed averageSpeed = new();
+	private TempFile? outputTempFile;
+
+	public AaxcDownloadSingleConverter(string outDirectory, string cacheDirectory, IDownloadOptions dlOptions)
+		: base(outDirectory, cacheDirectory, dlOptions)
 	{
-		public AaxcDownloadSingleConverter(string outFileName, string cacheDirectory, IDownloadOptions dlOptions)
-			: base(outFileName, cacheDirectory, dlOptions)
-		{
+		var step = 1;
 
-			AsyncSteps.Name = $"Download and Convert Aaxc To {DownloadOptions.OutputFormat}";
-			AsyncSteps["Step 1: Get Aaxc Metadata"] = () => Task.Run(Step_GetMetadata);
-			AsyncSteps["Step 2: Download Decrypted Audiobook"] = Step_DownloadAndDecryptAudiobookAsync;
-			AsyncSteps["Step 3: Download Clips and Bookmarks"] = Step_DownloadClipsBookmarksAsync;
-			AsyncSteps["Step 4: Create Cue"] = Step_CreateCueAsync;
-		}
-
-		protected async override Task<bool> Step_DownloadAndDecryptAudiobookAsync()
-		{
-			FileUtility.SaferDelete(OutputFileName);
-
-			using var outputFile = File.Open(OutputFileName, FileMode.OpenOrCreate, FileAccess.ReadWrite);
-			OnFileCreated(OutputFileName);
-
-			try
-			{
-				await (AaxConversion = decryptAsync(outputFile));
-
-				if (AaxConversion.IsCompletedSuccessfully
-					&& DownloadOptions.MoveMoovToBeginning
-					&& DownloadOptions.OutputFormat is OutputFormat.M4b)
-				{
-					outputFile.Close();
-					await (AaxConversion = Mp4File.RelocateMoovAsync(OutputFileName));
-				}
-
-				return AaxConversion.IsCompletedSuccessfully;
-			}
-			finally
-			{
-				FinalizeDownload();
-			}
-		}
-
-		private Mp4Operation decryptAsync(Stream outputFile)
-			=> DownloadOptions.OutputFormat == OutputFormat.Mp3
-			? AaxFile.ConvertToMp3Async
-			(
-				outputFile,
-				DownloadOptions.LameConfig,
-				DownloadOptions.ChapterInfo,
-				DownloadOptions.TrimOutputToChapterLength
-			)
-			: DownloadOptions.FixupFile
-			? AaxFile.ConvertToMp4aAsync
-			(
-				outputFile,
-				DownloadOptions.ChapterInfo,
-				DownloadOptions.TrimOutputToChapterLength
-			)
-			: AaxFile.ConvertToMp4aAsync(outputFile);
+		AsyncSteps.Name = $"Download and Convert Aaxc To {DownloadOptions.OutputFormat}";
+		AsyncSteps[$"Step {step++}: Get Aaxc Metadata"] = () => Task.Run(Step_GetMetadata);
+		AsyncSteps[$"Step {step++}: Download Decrypted Audiobook"] = Step_DownloadAndDecryptAudiobookAsync;
+		if (DownloadOptions.MoveMoovToBeginning && DownloadOptions.OutputFormat is OutputFormat.M4b)
+			AsyncSteps[$"Step {step++}: Move moov atom to beginning"] = Step_MoveMoov;
+		AsyncSteps[$"Step {step++}: Create Cue"] = Step_CreateCueAsync;
 	}
+
+	protected override void OnInitialized()
+	{
+		//Finishing configuring lame encoder.
+		if (DownloadOptions.OutputFormat == OutputFormat.Mp3)
+		{
+			if (AaxFile is null)
+				throw new InvalidOperationException($"AaxFile is null during {nameof(OnInitialized)} in {nameof(AaxcDownloadConvertBase)}.");
+			if (DownloadOptions.LameConfig is null)
+				throw new InvalidOperationException($"LameConfig is null during {nameof(OnInitialized)} in {nameof(DownloadOptions)}.");
+
+			MpegUtil.ConfigureLameOptions(
+				AaxFile,
+				DownloadOptions.LameConfig,
+				DownloadOptions.Downsample,
+				DownloadOptions.MatchSourceBitrate,
+				DownloadOptions.ChapterInfo);
+		}
+	}
+
+	protected override async Task<bool> Step_DownloadAndDecryptAudiobookAsync()
+	{
+		if (AaxFile is null) return false;
+		outputTempFile = GetNewTempFilePath(DownloadOptions.OutputFormat.ToString());
+		FileUtility.SaferDelete(outputTempFile.FilePath);
+
+		using var outputFile = File.Open(outputTempFile.FilePath, FileMode.OpenOrCreate, FileAccess.ReadWrite);
+		OnTempFileCreated(outputTempFile);
+
+		try
+		{
+			await (AaxConversion = decryptAsync(AaxFile, outputFile));
+
+			return AaxConversion.IsCompletedSuccessfully;
+		}
+		finally
+		{
+			FinalizeDownload();
+		}
+	}
+
+	private async Task<bool> Step_MoveMoov()
+	{
+		if (outputTempFile is null) return false;
+		AaxConversion = Mp4File.RelocateMoovAsync(outputTempFile.FilePath);
+		AaxConversion.ConversionProgressUpdate += AaxConversion_MoovProgressUpdate;
+		await AaxConversion;
+		AaxConversion.ConversionProgressUpdate -= AaxConversion_MoovProgressUpdate;
+		return AaxConversion.IsCompletedSuccessfully;
+	}
+
+	private void AaxConversion_MoovProgressUpdate(object? sender, ConversionProgressEventArgs e)
+	{
+		averageSpeed.AddPosition(e.ProcessPosition.TotalSeconds);
+
+		var remainingTimeToProcess = (e.EndTime - e.ProcessPosition).TotalSeconds;
+		var estTimeRemaining = remainingTimeToProcess / averageSpeed.Average;
+
+		if (double.IsNormal(estTimeRemaining))
+			OnDecryptTimeRemaining(TimeSpan.FromSeconds(estTimeRemaining));
+
+		OnDecryptProgressUpdate(
+			new DownloadProgress
+			{
+				ProgressPercentage = 100 * e.FractionCompleted,
+				BytesReceived = (long)(InputFileStream.Length * e.FractionCompleted),
+				TotalBytesToReceive = InputFileStream.Length
+			});
+	}
+
+	private Mp4Operation decryptAsync(Mp4File aaxFile, Stream outputFile)
+		=> DownloadOptions.OutputFormat == OutputFormat.Mp3
+		? aaxFile.ConvertToMp3Async
+		(
+			outputFile,
+			DownloadOptions.LameConfig,
+			DownloadOptions.ChapterInfo
+		)
+		: DownloadOptions.FixupFile
+		? aaxFile.ConvertToMp4aAsync
+		(
+			outputFile,
+			DownloadOptions.ChapterInfo
+		)
+		: aaxFile.ConvertToMp4aAsync(outputFile);
 }

Source/AaxDecrypter/AudiobookDownloadBase.cs

@@ -6,191 +6,221 @@ using System;
 using System.IO;
 using System.Threading.Tasks;
 
-namespace AaxDecrypter
+namespace AaxDecrypter;
+
+public enum OutputFormat { M4b, Mp3 }
+
+public abstract class AudiobookDownloadBase
 {
-	public enum OutputFormat { M4b, Mp3 }
+	public event EventHandler<string?>? RetrievedTitle;
+	public event EventHandler<string?>? RetrievedAuthors;
+	public event EventHandler<string?>? RetrievedNarrators;
+	public event EventHandler<byte[]?>? RetrievedCoverArt;
+	public event EventHandler<DownloadProgress>? DecryptProgressUpdate;
+	public event EventHandler<TimeSpan>? DecryptTimeRemaining;
+	public event EventHandler<TempFile>? TempFileCreated;
 
-	public abstract class AudiobookDownloadBase
+	public bool IsCanceled { get; protected set; }
+	protected AsyncStepSequence AsyncSteps { get; } = new();
+	protected string OutputDirectory { get; }
+	public IDownloadOptions DownloadOptions { get; }
+	protected NetworkFileStream InputFileStream => NfsPersister.NetworkFileStream;
+	protected virtual long InputFilePosition
 	{
-		public event EventHandler<string> RetrievedTitle;
-		public event EventHandler<string> RetrievedAuthors;
-		public event EventHandler<string> RetrievedNarrators;
-		public event EventHandler<byte[]> RetrievedCoverArt;
-		public event EventHandler<DownloadProgress> DecryptProgressUpdate;
-		public event EventHandler<TimeSpan> DecryptTimeRemaining;
-		public event EventHandler<string> FileCreated;
-
-		public bool IsCanceled { get; protected set; }
-		protected AsyncStepSequence AsyncSteps { get; } = new();
-		protected string OutputFileName { get; }
-		protected IDownloadOptions DownloadOptions { get; }
-		protected NetworkFileStream InputFileStream => nfsPersister.NetworkFileStream;
-
-		private readonly NetworkFileStreamPersister nfsPersister;
-		private readonly DownloadProgress zeroProgress;
-		private readonly string jsonDownloadState;
-		private readonly string tempFilePath;
-
-		protected AudiobookDownloadBase(string outFileName, string cacheDirectory, IDownloadOptions dlOptions)
+		get
 		{
-			OutputFileName = ArgumentValidator.EnsureNotNullOrWhiteSpace(outFileName, nameof(outFileName));
+			//Use try/catch instread of checking CanRead to avoid
+			//a race with the background download completing
+			//between the check and the Position call.
+			try { return InputFileStream.Position; }
+			catch { return InputFileStream.Length; }
+		}
+	}
+	private bool downloadFinished;
 
-			var outDir = Path.GetDirectoryName(OutputFileName);
-			if (!Directory.Exists(outDir))
-				Directory.CreateDirectory(outDir);
+	private NetworkFileStreamPersister? m_nfsPersister;
+	private NetworkFileStreamPersister NfsPersister => m_nfsPersister ??= OpenNetworkFileStream();
+	private readonly DownloadProgress zeroProgress;
+	private readonly string jsonDownloadState;
+	private readonly string tempFilePath;
 
-			if (!Directory.Exists(cacheDirectory))
-				Directory.CreateDirectory(cacheDirectory);
+	protected AudiobookDownloadBase(string outDirectory, string cacheDirectory, IDownloadOptions dlOptions)
+	{
+		OutputDirectory = ArgumentValidator.EnsureNotNullOrWhiteSpace(outDirectory, nameof(outDirectory));
+		DownloadOptions = ArgumentValidator.EnsureNotNull(dlOptions, nameof(dlOptions));
+		DownloadOptions.DownloadSpeedChanged += (_, speed) => InputFileStream.SpeedLimit = speed;
 
-			jsonDownloadState = Path.Combine(cacheDirectory, Path.GetFileName(Path.ChangeExtension(OutputFileName, ".json")));
-			tempFilePath = Path.ChangeExtension(jsonDownloadState, ".aaxc");
+		if (!Directory.Exists(OutputDirectory))
+			Directory.CreateDirectory(OutputDirectory);
 
-			DownloadOptions = ArgumentValidator.EnsureNotNull(dlOptions, nameof(dlOptions));
-			DownloadOptions.DownloadSpeedChanged += (_, speed) => InputFileStream.SpeedLimit = speed;
+		if (!Directory.Exists(cacheDirectory))
+			Directory.CreateDirectory(cacheDirectory);
 
-			// delete file after validation is complete
-			FileUtility.SaferDelete(OutputFileName);
+		jsonDownloadState = Path.Combine(cacheDirectory, $"{DownloadOptions.AudibleProductId}.json");
+		tempFilePath = Path.ChangeExtension(jsonDownloadState, ".aaxc");
 
-			nfsPersister = OpenNetworkFileStream();
+		zeroProgress = new DownloadProgress
+		{
+			BytesReceived = 0,
+			ProgressPercentage = 0,
+			TotalBytesToReceive = 0
+		};
 
-			zeroProgress = new DownloadProgress
+		OnDecryptProgressUpdate(zeroProgress);
+	}
+
+	protected TempFile GetNewTempFilePath(string extension)
+	{
+		extension = FileUtility.GetStandardizedExtension(extension);
+		var path = Path.Combine(OutputDirectory, Guid.NewGuid().ToString("N") + extension);
+		return new(path, extension);
+	}
+
+	public async Task<bool> RunAsync()
+	{
+		await InputFileStream.BeginDownloadingAsync();
+		var progressTask = Task.Run(reportProgress);
+
+		(bool success, var elapsed) = await AsyncSteps.RunAsync();
+
+		//Stop the downloader so it doesn't keep running in the background.
+		if (!success)
+			NfsPersister.Dispose();
+
+		await progressTask;
+
+		var speedup = DownloadOptions.RuntimeLength / elapsed;
+		Serilog.Log.Information($"Speedup is {speedup:F0}x realtime.");
+
+		NfsPersister.Dispose();
+		return success;
+
+		async Task reportProgress()
+		{
+			AverageSpeed averageSpeed = new();
+
+			while (
+				InputFileStream.CanRead
+				&& InputFileStream.Length > InputFilePosition
+				&& !InputFileStream.IsCancelled
+				&& !downloadFinished)
 			{
-				BytesReceived = 0,
-				ProgressPercentage = 0,
-				TotalBytesToReceive = InputFileStream.Length
-			};
+				averageSpeed.AddPosition(InputFilePosition);
 
+				var estSecsRemaining = (InputFileStream.Length - InputFilePosition) / averageSpeed.Average;
+
+				if (double.IsNormal(estSecsRemaining))
+					OnDecryptTimeRemaining(TimeSpan.FromSeconds(estSecsRemaining));
+
+				var progressPercent = 100d * InputFilePosition / InputFileStream.Length;
+
+				OnDecryptProgressUpdate(
+					new DownloadProgress
+					{
+						ProgressPercentage = progressPercent,
+						BytesReceived = InputFilePosition,
+						TotalBytesToReceive = InputFileStream.Length
+					});
+
+				await Task.Delay(200);
+			}
+
+			OnDecryptTimeRemaining(TimeSpan.Zero);
 			OnDecryptProgressUpdate(zeroProgress);
 		}
+	}
 
-		public async Task<bool> RunAsync()
+	public virtual Task CancelAsync()
+	{
+		IsCanceled = true;
+		FinalizeDownload();
+		return Task.CompletedTask;
+	}
+	protected abstract Task<bool> Step_DownloadAndDecryptAudiobookAsync();
+
+	public virtual void SetCoverArt(byte[] coverArt) { }
+	protected void OnRetrievedTitle(string? title)
+		=> RetrievedTitle?.Invoke(this, title);
+	protected void OnRetrievedAuthors(string? authors)
+		=> RetrievedAuthors?.Invoke(this, authors);
+	protected void OnRetrievedNarrators(string? narrators)
+		=> RetrievedNarrators?.Invoke(this, narrators);
+	protected void OnRetrievedCoverArt(byte[]? coverArt)
+		=> RetrievedCoverArt?.Invoke(this, coverArt);
+	protected void OnDecryptProgressUpdate(DownloadProgress downloadProgress)
+		=> DecryptProgressUpdate?.Invoke(this, downloadProgress);
+	protected void OnDecryptTimeRemaining(TimeSpan timeRemaining)
+		=> DecryptTimeRemaining?.Invoke(this, timeRemaining);
+	public void OnTempFileCreated(TempFile path)
+		=> TempFileCreated?.Invoke(this, path);
+
+	protected virtual void FinalizeDownload()
+	{
+		NfsPersister.Dispose();
+		downloadFinished = true;
+	}
+
+	protected async Task<bool> Step_CreateCueAsync()
+	{
+		if (!DownloadOptions.CreateCueSheet) return !IsCanceled;
+
+		if (DownloadOptions.ChapterInfo.Count <= 1)
 		{
-			AsyncSteps[$"Cleanup"] = CleanupAsync;
-			(bool success, var elapsed) = await AsyncSteps.RunAsync();
-
-			var speedup = DownloadOptions.RuntimeLength / elapsed;
-			Serilog.Log.Information($"Speedup is {speedup:F0}x realtime.");
-
-			return success;
-		}
-
-		public abstract Task CancelAsync();
-		protected abstract Task<bool> Step_DownloadAndDecryptAudiobookAsync();
-
-		public virtual void SetCoverArt(byte[] coverArt)
-		{
-			if (coverArt is not null)
-				OnRetrievedCoverArt(coverArt);
-		}
-
-		protected void OnRetrievedTitle(string title)
-			=> RetrievedTitle?.Invoke(this, title);
-		protected void OnRetrievedAuthors(string authors)
-			=> RetrievedAuthors?.Invoke(this, authors);
-		protected void OnRetrievedNarrators(string narrators)
-			=> RetrievedNarrators?.Invoke(this, narrators);
-		protected void OnRetrievedCoverArt(byte[] coverArt)
-			=> RetrievedCoverArt?.Invoke(this, coverArt);
-		protected void OnDecryptProgressUpdate(DownloadProgress downloadProgress)
-			=> DecryptProgressUpdate?.Invoke(this, downloadProgress);
-		protected void OnDecryptTimeRemaining(TimeSpan timeRemaining)
-			=> DecryptTimeRemaining?.Invoke(this, timeRemaining);
-		protected void OnFileCreated(string path)
-			=> FileCreated?.Invoke(this, path);
-
-		protected virtual void FinalizeDownload()
-		{
-			nfsPersister?.Dispose();
-			OnDecryptProgressUpdate(zeroProgress);
-		}
-
-		protected async Task<bool> Step_DownloadClipsBookmarksAsync()
-		{
-			if (!IsCanceled && DownloadOptions.DownloadClipsBookmarks)
-			{
-				var recordsFile = await DownloadOptions.SaveClipsAndBookmarksAsync(OutputFileName);
-
-				if (File.Exists(recordsFile))
-					OnFileCreated(recordsFile);
-			}
+			Serilog.Log.Logger.Information($"Skipped creating .cue because book has no chapters.");
 			return !IsCanceled;
 		}
 
-		protected async Task<bool> Step_CreateCueAsync()
+		// not a critical step. its failure should not prevent future steps from running
+		try
 		{
-			if (!DownloadOptions.CreateCueSheet) return !IsCanceled;
-
-			// not a critical step. its failure should not prevent future steps from running
-			try
-			{
-				var path = Path.ChangeExtension(OutputFileName, ".cue");
-				await File.WriteAllTextAsync(path, Cue.CreateContents(Path.GetFileName(OutputFileName), DownloadOptions.ChapterInfo));
-				OnFileCreated(path);
-			}
-			catch (Exception ex)
-			{
-				Serilog.Log.Logger.Error(ex, $"{nameof(Step_CreateCueAsync)} Failed");
-			}
-			return !IsCanceled;
+			var tempFile = GetNewTempFilePath(".cue");
+			await File.WriteAllTextAsync(tempFile.FilePath, Cue.CreateContents(Path.GetFileName(tempFile.FilePath), DownloadOptions.ChapterInfo));
+			OnTempFileCreated(tempFile);
 		}
-
-		private async Task<bool> CleanupAsync()
+		catch (Exception ex)
 		{
-			if (IsCanceled) return false;
-
-			FileUtility.SaferDelete(jsonDownloadState);
-
-			if (!string.IsNullOrEmpty(DownloadOptions.AudibleKey) &&
-				!string.IsNullOrEmpty(DownloadOptions.AudibleIV) &&
-				DownloadOptions.RetainEncryptedFile)
-			{
-				string aaxPath = Path.ChangeExtension(tempFilePath, ".aax");
-				FileUtility.SaferMove(tempFilePath, aaxPath);
-
-				//Write aax decryption key
-				string keyPath = Path.ChangeExtension(aaxPath, ".key");
-				FileUtility.SaferDelete(keyPath);
-				await File.WriteAllTextAsync(keyPath, $"Key={DownloadOptions.AudibleKey}{Environment.NewLine}IV={DownloadOptions.AudibleIV}");
-
-				OnFileCreated(aaxPath);
-				OnFileCreated(keyPath);
-			}
-			else
-				FileUtility.SaferDelete(tempFilePath);
-
-			return !IsCanceled;
+			Serilog.Log.Logger.Error(ex, $"{nameof(Step_CreateCueAsync)} Failed");
 		}
+		return !IsCanceled;
+	}
 
-		private NetworkFileStreamPersister OpenNetworkFileStream()
+	private NetworkFileStreamPersister OpenNetworkFileStream()
+	{
+		NetworkFileStreamPersister? nfsp = default;
+		try
 		{
-			NetworkFileStreamPersister nfsp = default;
-			try
-			{
-				if (!File.Exists(jsonDownloadState))
-					return nfsp = newNetworkFilePersister();
-
-				nfsp = new NetworkFileStreamPersister(jsonDownloadState);
-				// The download url expires after 1 hour.
-				// The new url points to the same file.
-				nfsp.NetworkFileStream.SetUriForSameFile(new Uri(DownloadOptions.DownloadUrl));
-				return nfsp;
-			}
-			catch
-			{
-				FileUtility.SaferDelete(jsonDownloadState);
-				FileUtility.SaferDelete(tempFilePath);
+			if (!File.Exists(jsonDownloadState))
 				return nfsp = newNetworkFilePersister();
-			}
-			finally
-			{
-				nfsp.NetworkFileStream.SpeedLimit = DownloadOptions.DownloadSpeedBps;
-			}
 
-			NetworkFileStreamPersister newNetworkFilePersister()
+			nfsp = new NetworkFileStreamPersister(jsonDownloadState);
+			// The download url expires after 1 hour.
+			// The new url points to the same file.
+			nfsp.NetworkFileStream.SetUriForSameFile(new Uri(DownloadOptions.DownloadUrl));
+			return nfsp;
+		}
+		catch
+		{
+			nfsp?.Target?.Dispose();
+			FileUtility.SaferDelete(jsonDownloadState);
+			FileUtility.SaferDelete(tempFilePath);
+			return nfsp = newNetworkFilePersister();
+		}
+		finally
+		{
+			//nfsp will only be null when an unhandled exception occurs. Let the caller handle it.
+			if (nfsp is not null)
 			{
-				var networkFileStream = new NetworkFileStream(tempFilePath, new Uri(DownloadOptions.DownloadUrl), 0, new() { { "User-Agent", DownloadOptions.UserAgent } });
-				return new NetworkFileStreamPersister(networkFileStream, jsonDownloadState);
+				nfsp.NetworkFileStream.RequestHeaders["User-Agent"] = DownloadOptions.UserAgent;
+				nfsp.NetworkFileStream.SpeedLimit = DownloadOptions.DownloadSpeedBps;
+				OnTempFileCreated(new(tempFilePath, DownloadOptions.InputType.ToString()));
+				OnTempFileCreated(new(jsonDownloadState));
 			}
 		}
+
+		NetworkFileStreamPersister newNetworkFilePersister()
+		{
+			var networkFileStream = new NetworkFileStream(tempFilePath, new Uri(DownloadOptions.DownloadUrl), 0, new() { { "User-Agent", DownloadOptions.UserAgent } });
+			return new NetworkFileStreamPersister(networkFileStream, jsonDownloadState);
+		}
 	}
 }

Source/AaxDecrypter/AverageSpeed.cs

@@ -0,0 +1,171 @@
+using Dinah.Core;
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+namespace AaxDecrypter;
+
+public static class LinqStats
+{
+	public static (double mean, double stdDev) BasicStatisticsBy<T>(this IEnumerable<T> values, Func<T, double> selector)
+	{
+		var count = values.Count();
+		var mean = values.Average(selector);
+
+		return (mean, Math.Sqrt(values.Sum(s => Math.Pow(selector(s) - mean, 2)) / (count - 1)));
+	}
+
+	public static bool T_Test_2By<T>(this IEnumerable<T> values, Func<T, double> selector, IEnumerable<T> secondGroup, Significance confidence)
+	{
+		var n1 = values.Count();
+		var n2 = secondGroup.Count();
+		var n = n1 + n2;
+
+		if (n1 < 3 || n2 < 3) return false;
+
+		(var mean1, var stdDev1) = values.BasicStatisticsBy(selector);
+		(var mean2, var stdDev2) = secondGroup.BasicStatisticsBy(selector);
+
+		var pooledStdDev = Math.Sqrt((((n1 - 1) * (stdDev1 * stdDev1)) + ((n2 - 1) * (stdDev2 * stdDev2))) / (n1 + n2 - 2));
+
+		var testStat = Math.Abs(mean1 - mean2) / (pooledStdDev * Math.Sqrt(1d / n1 + 1d / n2));
+		var crit = T_Stat(Math.Min(n - 2, MAX_DEGREES_FREEDOM), confidence);
+
+		return testStat > crit;
+	}
+
+	public static bool T_Test_1By<T>(this IEnumerable<T> values, Func<T, double> selector, double testMean, Significance confidence)
+	{
+		var n = values.Count();
+
+		if (n < 2) return false;
+
+		(var sampleMean, var sampleStdDev) = values.BasicStatisticsBy(selector);
+
+		var testStat = Math.Abs(sampleMean - testMean) / (sampleStdDev / Math.Sqrt(n));
+		var crit = T_Stat(Math.Min(n - 1, MAX_DEGREES_FREEDOM), confidence);
+
+		return testStat > crit;
+	}
+
+	private static double T_Stat(int degreesFreedom, Significance confidence)
+	{
+		ArgumentValidator.EnsureBetweenInclusive(degreesFreedom, nameof(degreesFreedom), MIN_DEGREES_FREEDOM, MAX_DEGREES_FREEDOM);
+
+		return T_TABLE[(int)confidence][degreesFreedom - MIN_DEGREES_FREEDOM];
+	}
+
+	static LinqStats()
+	{
+		T_TABLE = new double[][] { T_Table_01, T_Table_05, T_Table_10, T_Table_15, T_Table_20, T_Table_25 };
+	}
+
+	private const int MIN_DEGREES_FREEDOM = 1;
+	private const int MAX_DEGREES_FREEDOM = 201;
+	/// <summary>
+	/// 2-tailed  t-Distribution critical values at 75%, 80%, 85%,
+	/// 90%, 95%, and 99% confidence for 1 - 201 degrees of freedom.
+	/// </summary>
+	private static readonly double[][] T_TABLE;
+	private static readonly double[] T_Table_25 = { 2.414213562, 1.603567451, 1.422625281, 1.344397556, 1.300949037, 1.273349309, 1.254278682, 1.240318261, 1.229659173, 1.221255395, 1.214460246, 1.208852542, 1.204146242, 1.200140298, 1.196689284, 1.193685414, 1.191047107, 1.188711483, 1.186629298, 1.184761434, 1.183076432, 1.181548697, 1.180157199, 1.178884497, 1.177716003, 1.176639425, 1.175644329, 1.174721803, 1.173864189, 1.173064871, 1.1723181, 1.17161886, 1.170962753, 1.17034591, 1.169764906, 1.169216709, 1.168698615, 1.168208212, 1.167743338, 1.167302049, 1.166882595, 1.166483396, 1.166103019, 1.165740162, 1.165393644, 1.165062385, 1.164745398, 1.164441782, 1.164150707, 1.163871412, 1.163603196, 1.163345413, 1.163097467, 1.162858803, 1.162628911, 1.162407316, 1.162193577, 1.161987283, 1.161788052, 1.161595527, 1.161409375, 1.161229286, 1.161054967, 1.160886145, 1.160722566, 1.160563987, 1.160410184, 1.160260944, 1.160116066, 1.159975363, 1.159838656, 1.159705777, 1.159576569, 1.15945088, 1.15932857, 1.159209503, 1.159093552, 1.158980598, 1.158870524, 1.158763222, 1.158658589, 1.158556526, 1.15845694, 1.158359742, 1.158264847, 1.158172173, 1.158081645, 1.157993188, 1.157906731, 1.157822209, 1.157739556, 1.157658712, 1.157579617, 1.157502216, 1.157426454, 1.157352281, 1.157279646, 1.157208502, 1.157138804, 1.157070509, 1.157003573, 1.156937958, 1.156873624, 1.156810534, 1.156748653, 1.156687945, 1.156628379, 1.156569922, 1.156512543, 1.156456213, 1.156400904, 1.156346587, 1.156293237, 1.156240827, 1.156189334, 1.156138733, 1.156089001, 1.156040117, 1.155992058, 1.155944804, 1.155898335, 1.155852631, 1.155807674, 1.155763446, 1.155719928, 1.155677105, 1.155634959, 1.155593475, 1.155552637, 1.15551243, 1.155472839, 1.155433851, 1.155395452, 1.155357629, 1.155320368, 1.155283658, 1.155247486, 1.155211841, 1.15517671, 1.155142084, 1.15510795, 1.1550743, 1.155041122, 1.155008406, 1.154976144, 1.154944326, 1.154912942, 1.154881984, 1.154851443, 1.154821311, 1.15479158, 1.154762241, 1.154733287, 1.154704711, 1.154676505, 1.154648662, 1.154621175, 1.154594037, 1.154567242, 1.154540783, 1.154514654, 1.154488849, 1.154463361, 1.154438185, 1.154413316, 1.154388747, 1.154364474, 1.15434049, 1.154316792, 1.154293373, 1.154270229, 1.154247355, 1.154224746, 1.154202398, 1.154180307, 1.154158467, 1.154136875, 1.154115526, 1.154094417, 1.154073543, 1.1540529, 1.154032485, 1.154012294, 1.153992323, 1.153972568, 1.153953027, 1.153933695, 1.15391457, 1.153895647, 1.153876925, 1.153858399, 1.153840066, 1.153821925, 1.15380397, 1.153786201, 1.153768613, 1.153751204, 1.153733972, 1.153716914, 1.153700026 };
+	private static readonly double[] T_Table_20 = { 3.077683537, 1.885618083, 1.637744354, 1.533206274, 1.475884049, 1.439755747, 1.414923928, 1.39681531, 1.383028738, 1.372183641, 1.363430318, 1.356217334, 1.350171289, 1.345030374, 1.340605608, 1.336757167, 1.33337939, 1.330390944, 1.327728209, 1.325340707, 1.323187874, 1.321236742, 1.31946024, 1.317835934, 1.316345073, 1.314971864, 1.313702913, 1.312526782, 1.311433647, 1.310415025, 1.309463549, 1.308572793, 1.307737124, 1.306951587, 1.306211802, 1.305513886, 1.304854381, 1.304230204, 1.303638589, 1.303077053, 1.302543359, 1.302035487, 1.301551608, 1.30109006, 1.300649332, 1.300228048, 1.299824947, 1.299438879, 1.299068785, 1.298713694, 1.298372713, 1.298045016, 1.297729843, 1.297426488, 1.2971343, 1.296852673, 1.296581044, 1.29631889, 1.296065725, 1.295821094, 1.295584571, 1.295355762, 1.295134294, 1.29491982, 1.294712013, 1.294510568, 1.294315197, 1.294125629, 1.293941609, 1.293762898, 1.293589269, 1.293420507, 1.293256413, 1.293096793, 1.292941469, 1.292790268, 1.292643029, 1.292499597, 1.292359828, 1.292223583, 1.29209073, 1.291961144, 1.291834705, 1.291711301, 1.291590824, 1.291473171, 1.291358243, 1.291245948, 1.291136195, 1.291028899, 1.290923979, 1.290821356, 1.290720956, 1.290622708, 1.290526543, 1.290432395, 1.290340202, 1.290249904, 1.290161442, 1.290074761, 1.289989809, 1.289906533, 1.289824884, 1.289744816, 1.289666283, 1.289589241, 1.289513648, 1.289439464, 1.289366649, 1.289295166, 1.289224979, 1.289156054, 1.289088355, 1.289021851, 1.28895651, 1.288892302, 1.288829199, 1.288767171, 1.288706191, 1.288646234, 1.288587273, 1.288529284, 1.288472243, 1.288416127, 1.288360913, 1.288306581, 1.288253109, 1.288200477, 1.288148665, 1.288097654, 1.288047427, 1.287997964, 1.287949248, 1.287901264, 1.287853994, 1.287807422, 1.287761534, 1.287716314, 1.287671748, 1.287627821, 1.287584521, 1.287541833, 1.287499745, 1.287458245, 1.287417319, 1.287376957, 1.287337146, 1.287297876, 1.287259135, 1.287220914, 1.2871832, 1.287145985, 1.287109259, 1.287073012, 1.287037235, 1.287001918, 1.286967053, 1.286932631, 1.286898644, 1.286865084, 1.286831942, 1.286799212, 1.286766884, 1.286734952, 1.286703409, 1.286672248, 1.286641461, 1.286611042, 1.286580985, 1.286551283, 1.286521929, 1.286492918, 1.286464244, 1.286435901, 1.286407882, 1.286380184, 1.286352799, 1.286325724, 1.286298952, 1.286272479, 1.286246299, 1.286220408, 1.286194801, 1.286169474, 1.286144421, 1.286119638, 1.286095122, 1.286070867, 1.28604687, 1.286023127, 1.285999633, 1.285976384, 1.285953377, 1.285930609, 1.285908074, 1.285885771, 1.285863694, 1.285841842, 1.285820209, 1.285798794 };
+	private static readonly double[] T_Table_15 = { 4.16529977, 2.281930588, 1.924319657, 1.778192164, 1.699362566, 1.650173154, 1.616591737, 1.59222144, 1.573735785, 1.559235933, 1.547559766, 1.537956495, 1.529919606, 1.523095061, 1.517227969, 1.51213017, 1.507659754, 1.503707672, 1.500188756, 1.497035518, 1.494193795, 1.491619612, 1.489276897, 1.487135783, 1.485171326, 1.483362535, 1.481691617, 1.48014339, 1.478704821, 1.477364662, 1.47611315, 1.474941772, 1.473843072, 1.47281049, 1.471838233, 1.470921166, 1.470054719, 1.469234815, 1.468457801, 1.467720399, 1.467019655, 1.466352901, 1.465717725, 1.465111933, 1.464533534, 1.463980712, 1.463451805, 1.462945295, 1.46245979, 1.461994009, 1.461546775, 1.461117, 1.460703683, 1.460305896, 1.45992278, 1.459553538, 1.45919743, 1.458853767, 1.458521908, 1.458201256, 1.457891251, 1.457591373, 1.457301133, 1.457020074, 1.456747768, 1.45648381, 1.456227824, 1.455979454, 1.455738365, 1.455504241, 1.455276784, 1.455055715, 1.454840767, 1.45463169, 1.454428246, 1.454230212, 1.454037373, 1.453849529, 1.453666487, 1.453488066, 1.453314093, 1.453144404, 1.452978842, 1.452817259, 1.452659513, 1.452505469, 1.452354998, 1.452207977, 1.452064289, 1.451923821, 1.451786468, 1.451652126, 1.451520697, 1.451392088, 1.451266209, 1.451142973, 1.451022299, 1.450904108, 1.450788323, 1.450674871, 1.450563684, 1.450454694, 1.450347836, 1.450243048, 1.450140271, 1.450039448, 1.449940523, 1.449843444, 1.449748158, 1.449654617, 1.449562773, 1.449472581, 1.449383997, 1.449296977, 1.449211481, 1.449127468, 1.449044902, 1.448963744, 1.448883959, 1.448805513, 1.448728372, 1.448652503, 1.448577876, 1.44850446, 1.448432226, 1.448361146, 1.448291192, 1.448222337, 1.448154557, 1.448087826, 1.44802212, 1.447957415, 1.447893688, 1.447830919, 1.447769085, 1.447708165, 1.44764814, 1.44758899, 1.447530695, 1.447473238, 1.447416601, 1.447360765, 1.447305715, 1.447251433, 1.447197905, 1.447145113, 1.447093044, 1.447041682, 1.446991013, 1.446941023, 1.446891698, 1.446843026, 1.446794994, 1.446747588, 1.446700797, 1.446654609, 1.446609012, 1.446563996, 1.446519548, 1.446475659, 1.446432318, 1.446389514, 1.446347238, 1.44630548, 1.44626423, 1.44622348, 1.44618322, 1.446143442, 1.446104137, 1.446065296, 1.446026911, 1.445988975, 1.44595148, 1.445914417, 1.44587778, 1.445841561, 1.445805753, 1.445770349, 1.445735343, 1.445700727, 1.445666495, 1.445632641, 1.445599159, 1.445566042, 1.445533284, 1.445500881, 1.445468825, 1.445437112, 1.445405736, 1.445374691, 1.445343973, 1.445313576, 1.445283495, 1.445253726, 1.445224264, 1.445195103, 1.445166239, 1.445137668, 1.445109385, 1.445081387 };
+	private static readonly double[] T_Table_10 = { 6.313751515, 2.91998558, 2.353363435, 2.131846786, 2.015048373, 1.943180281, 1.894578605, 1.859548038, 1.833112933, 1.812461123, 1.795884819, 1.782287556, 1.770933396, 1.761310136, 1.753050356, 1.745883676, 1.739606726, 1.734063607, 1.729132812, 1.724718243, 1.720742903, 1.717144374, 1.713871528, 1.71088208, 1.708140761, 1.70561792, 1.703288446, 1.701130934, 1.699127027, 1.697260887, 1.695518783, 1.693888748, 1.692360309, 1.690924255, 1.689572458, 1.688297714, 1.68709362, 1.68595446, 1.684875122, 1.683851013, 1.682878002, 1.681952357, 1.681070703, 1.680229977, 1.679427393, 1.678660414, 1.677926722, 1.677224196, 1.676550893, 1.675905025, 1.67528495, 1.674689154, 1.674116237, 1.673564906, 1.673033965, 1.672522303, 1.672028888, 1.671552762, 1.671093032, 1.670648865, 1.670219484, 1.669804163, 1.669402222, 1.669013025, 1.668635976, 1.668270514, 1.667916114, 1.667572281, 1.667238549, 1.666914479, 1.666599658, 1.666293696, 1.665996224, 1.665706893, 1.665425373, 1.665151353, 1.664884537, 1.664624645, 1.664371409, 1.664124579, 1.663883913, 1.663649184, 1.663420175, 1.663196679, 1.6629785, 1.662765449, 1.662557349, 1.662354029, 1.662155326, 1.661961084, 1.661771155, 1.661585397, 1.661403674, 1.661225855, 1.661051817, 1.66088144, 1.66071461, 1.660551217, 1.660391156, 1.660234326, 1.66008063, 1.659929976, 1.659782273, 1.659637437, 1.659495383, 1.659356034, 1.659219312, 1.659085144, 1.658953458, 1.658824187, 1.658697265, 1.658572629, 1.658450216, 1.658329969, 1.65821183, 1.658095744, 1.657981659, 1.657869522, 1.657759285, 1.657650899, 1.657544319, 1.657439499, 1.657336397, 1.65723497, 1.657135178, 1.657036982, 1.656940344, 1.656845226, 1.656751594, 1.656659413, 1.656568649, 1.65647927, 1.656391244, 1.656304542, 1.656219133, 1.656134988, 1.65605208, 1.655970382, 1.655889868, 1.655810511, 1.655732287, 1.655655173, 1.655579143, 1.655504177, 1.655430251, 1.655357345, 1.655285437, 1.655214506, 1.655144534, 1.6550755, 1.655007387, 1.654940175, 1.654873847, 1.654808385, 1.654743774, 1.654679996, 1.654617035, 1.654554875, 1.654493503, 1.654432901, 1.654373057, 1.654313957, 1.654255585, 1.654197929, 1.654140976, 1.654084713, 1.654029128, 1.653974208, 1.653919942, 1.653866317, 1.653813324, 1.653760949, 1.653709184, 1.653658017, 1.653607437, 1.653557435, 1.653508002, 1.653459126, 1.6534108, 1.653363013, 1.653315758, 1.653269024, 1.653222803, 1.653177088, 1.653131869, 1.653087138, 1.653042889, 1.652999113, 1.652955802, 1.652912949, 1.652870547, 1.652828589, 1.652787068, 1.652745977, 1.65270531, 1.652665059, 1.652625219, 1.652585784, 1.652546746, 1.652508101 };
+	private static readonly double[] T_Table_05 = { 12.70620474, 4.30265273, 3.182446305, 2.776445105, 2.570581836, 2.446911851, 2.364624252, 2.306004135, 2.262157163, 2.228138852, 2.20098516, 2.17881283, 2.160368656, 2.144786688, 2.131449546, 2.119905299, 2.109815578, 2.10092204, 2.093024054, 2.085963447, 2.079613845, 2.073873068, 2.06865761, 2.063898562, 2.059538553, 2.055529439, 2.051830516, 2.048407142, 2.045229642, 2.042272456, 2.039513446, 2.036933343, 2.034515297, 2.032244509, 2.030107928, 2.028094001, 2.026192463, 2.024394164, 2.02269092, 2.02107539, 2.01954097, 2.018081703, 2.016692199, 2.015367574, 2.014103389, 2.012895599, 2.011740514, 2.010634758, 2.009575237, 2.008559112, 2.00758377, 2.006646805, 2.005745995, 2.004879288, 2.004044783, 2.003240719, 2.002465459, 2.001717484, 2.000995378, 2.000297822, 1.999623585, 1.998971517, 1.998340543, 1.997729654, 1.997137908, 1.996564419, 1.996008354, 1.995468931, 1.994945415, 1.994437112, 1.993943368, 1.993463567, 1.992997126, 1.992543495, 1.992102154, 1.99167261, 1.991254395, 1.990847069, 1.99045021, 1.990063421, 1.989686323, 1.989318557, 1.98895978, 1.988609667, 1.988267907, 1.987934206, 1.987608282, 1.987289865, 1.9869787, 1.986674541, 1.986377154, 1.986086317, 1.985801814, 1.985523442, 1.985251004, 1.984984312, 1.984723186, 1.984467455, 1.984216952, 1.983971519, 1.983731003, 1.983495259, 1.983264145, 1.983037526, 1.982815274, 1.982597262, 1.98238337, 1.982173483, 1.98196749, 1.981765282, 1.981566757, 1.981371815, 1.981180359, 1.980992298, 1.980807541, 1.980626002, 1.980447599, 1.980272249, 1.980099876, 1.979930405, 1.979763763, 1.979599878, 1.979438685, 1.979280117, 1.979124109, 1.978970602, 1.978819535, 1.97867085, 1.978524491, 1.978380405, 1.978238539, 1.978098842, 1.977961264, 1.977825758, 1.977692277, 1.977560777, 1.977431212, 1.977303542, 1.977177724, 1.97705372, 1.976931489, 1.976810994, 1.976692198, 1.976575066, 1.976459563, 1.976345655, 1.976233309, 1.976122494, 1.976013178, 1.975905331, 1.975798924, 1.975693928, 1.975590315, 1.975488058, 1.975387131, 1.975287508, 1.975189163, 1.975092073, 1.974996213, 1.97490156, 1.974808092, 1.974715786, 1.974624621, 1.974534576, 1.97444563, 1.974357764, 1.974270957, 1.974185191, 1.974100447, 1.974016708, 1.973933954, 1.973852169, 1.973771337, 1.97369144, 1.973612462, 1.973534388, 1.973457202, 1.973380889, 1.973305434, 1.973230823, 1.973157042, 1.973084077, 1.973011915, 1.972940542, 1.972869946, 1.972800114, 1.972731033, 1.972662692, 1.972595079, 1.972528182, 1.97246199, 1.972396491, 1.972331676, 1.972267533, 1.972204051, 1.972141222, 1.972079034, 1.972017478, 1.971956544, 1.971896224 };
+	private static readonly double[] T_Table_01 = { 63.65674116, 9.924843201, 5.84090931, 4.604094871, 4.032142984, 3.707428021, 3.499483297, 3.355387331, 3.249835542, 3.169272673, 3.105806516, 3.054539589, 3.012275839, 2.976842734, 2.946712883, 2.920781622, 2.89823052, 2.878440473, 2.860934606, 2.84533971, 2.831359558, 2.818756061, 2.807335684, 2.796939505, 2.787435814, 2.778714533, 2.770682957, 2.763262455, 2.756385904, 2.749995654, 2.744041919, 2.738481482, 2.733276642, 2.728394367, 2.723805589, 2.71948463, 2.715408722, 2.711557602, 2.707913184, 2.704459267, 2.701181304, 2.698066186, 2.695102079, 2.692278266, 2.689585019, 2.687013492, 2.684555618, 2.682204027, 2.679951974, 2.677793271, 2.675722234, 2.673733631, 2.671822636, 2.669984796, 2.668215988, 2.666512398, 2.664870482, 2.663286954, 2.661758752, 2.660283029, 2.658857127, 2.657478565, 2.656145025, 2.654854337, 2.653604469, 2.652393515, 2.651219685, 2.650081299, 2.648976774, 2.647904624, 2.646863444, 2.645851913, 2.644868782, 2.643912872, 2.642983067, 2.642078313, 2.641197611, 2.640340015, 2.639504627, 2.638690596, 2.637897113, 2.63712341, 2.636368757, 2.635632458, 2.634913852, 2.634212309, 2.633527229, 2.632858038, 2.632204191, 2.631565166, 2.630940463, 2.630329608, 2.629732145, 2.629147638, 2.628575671, 2.628015844, 2.627467774, 2.626931096, 2.626405457, 2.625890521, 2.625385965, 2.624891476, 2.624406758, 2.623931523, 2.623465496, 2.623008411, 2.622560015, 2.622120061, 2.621688313, 2.621264543, 2.620848534, 2.620440073, 2.620038957, 2.619644989, 2.619257981, 2.618877749, 2.618504116, 2.618136914, 2.617775976, 2.617421145, 2.617072266, 2.616729191, 2.616391776, 2.616059883, 2.615733377, 2.615412127, 2.615096008, 2.614784899, 2.61447868, 2.614177238, 2.613880461, 2.613588242, 2.613300477, 2.613017065, 2.612737908, 2.61246291, 2.61219198, 2.611925028, 2.611661966, 2.611402711, 2.611147181, 2.610895295, 2.610646976, 2.61040215, 2.610160742, 2.609922682, 2.609687901, 2.609456331, 2.609227907, 2.609002566, 2.608780245, 2.608560883, 2.608344423, 2.608130807, 2.60791998, 2.607711886, 2.607506474, 2.607303692, 2.607103489, 2.606905817, 2.606710628, 2.606517876, 2.606327515, 2.606139501, 2.605953791, 2.605770342, 2.605589114, 2.605410067, 2.605233162, 2.605058359, 2.604885623, 2.604714916, 2.604546204, 2.60437945, 2.604214622, 2.604051686, 2.60389061, 2.603731363, 2.603573912, 2.603418229, 2.603264282, 2.603112045, 2.602961487, 2.602812582, 2.602665303, 2.602519622, 2.602375515, 2.602232955, 2.602091918, 2.60195238, 2.601814317, 2.601677705, 2.601542523, 2.601408747, 2.601276355, 2.601145327, 2.601015642, 2.600887278, 2.600760216, 2.600634436 };
+}
+
+public enum Significance
+{
+	P01,
+	P05,
+	P10,
+	P15,
+	P20,
+	P25
+}
+
+public class AverageSpeed
+{
+	/// <summary>Average speed in units per second</summary>
+	public double Average { get; private set; }
+	public TimeSpan SlowWindow { get; }
+	public TimeSpan FastWindow { get; }
+	public Significance SlowSignificance { get; }
+	public Significance FastSignificance { get; }
+
+	private DateTime start;
+	private TimeSpan lastTime;
+	private double lastPosition = double.NaN;
+
+	private readonly record struct Point(TimeSpan Time, double Velocity);
+	private readonly LinkedList<Point> speeds = new();
+	private const int MAX_SPEEDS = 200;
+
+	public AverageSpeed() : this(TimeSpan.FromSeconds(15), Significance.P10, TimeSpan.FromSeconds(3), Significance.P01) { }
+
+	/// <param name="slowWindow">Total moving average time window</param>
+	/// <param name="slowSignificance">T-test significance level at which the newest speed will be considered different from the slow window's mean speed.</param>
+	/// <param name="fastWindow">A shorter moving window of the most resent speeds. The average speed in <paramref name="fastWindow"/> is compared to the average speed in the rest of <paramref name="slowWindow"/> to quickly detect large changes in speed.</param>
+	/// <param name="fastSignificance">T-test significance level at which the mean speed in <paramref name="fastWindow"/> will be considered different from the mean speed of the remainder of <paramref name="slowWindow"/>.</param>
+	public AverageSpeed(TimeSpan slowWindow, Significance slowSignificance, TimeSpan fastWindow, Significance fastSignificance)
+	{
+		SlowWindow = ArgumentValidator.EnsureGreaterThan(slowWindow, nameof(slowWindow), fastWindow);
+		FastWindow = ArgumentValidator.EnsureGreaterThan(fastWindow, nameof(fastWindow), TimeSpan.Zero);
+		SlowSignificance = slowSignificance;
+		FastSignificance = fastSignificance;
+	}
+
+	/// <summary>Add a new position to the moving average</summary>
+	public void AddPosition(double position)
+	{
+		var now = DateTime.UtcNow;
+		if (start == default)
+			start = now;
+
+		var time = now - start;
+
+		while (speeds.Count > MAX_SPEEDS || (speeds.Count > 2 && time - speeds.First!.Value.Time > SlowWindow))
+			speeds.RemoveFirst();
+
+		if (!double.IsNaN(lastPosition))
+		{
+			var newSpeed = (position - lastPosition) / (time - lastTime).TotalSeconds;
+			speeds.AddLast(new Point(time, newSpeed));
+		}
+
+		lastTime = time;
+		lastPosition = position;
+
+		Average = ComputeNextAverage();
+	}
+
+	private double ComputeNextAverage()
+	{
+		if (speeds.Count == 0)
+			return 0;
+		else if (speeds.Count == 1)
+			return speeds.Last!.Value.Velocity;
+		else
+		{
+			var n_newest = speeds.Count(s => s.Time > lastTime.Subtract(FastWindow));
+
+			var n_oldest = speeds.Count - n_newest;
+
+			if (speeds.Take(n_oldest).T_Test_2By(s => s.Velocity, speeds.TakeLast(n_newest), FastSignificance))
+			{
+				//Speeds in FastWindow are significantly different from reset of speeds in SlowWindow.
+				//Discard older speeds and keep only speeds in FastWindow
+				for (; n_oldest > 0; n_oldest--)
+					speeds.RemoveFirst();
+
+				return speeds.Average(s => s.Velocity);
+			}
+			else
+				return
+					speeds.T_Test_1By(s => s.Velocity, Average, SlowSignificance)
+					? speeds.Average(s => s.Velocity)
+					: Average;
+		}
+	}
+}

Source/AaxDecrypter/Cue.cs

@@ -1,60 +1,59 @@
-using AAXClean;
-using Dinah.Core;
+using Dinah.Core;
+using Mpeg4Lib;
 using System.IO;
 using System.Text;
 
-namespace AaxDecrypter
+namespace AaxDecrypter;
+
+public static class Cue
 {
-    public static class Cue
-    {
-        public static string CreateContents(string filePath, ChapterInfo chapters)
-        {
-            var stringBuilder = new StringBuilder();
+	public static string CreateContents(string filePath, ChapterInfo chapters)
+	{
+		var stringBuilder = new StringBuilder();
 
-            stringBuilder.AppendLine(GetFileLine(filePath, "MP3"));
+		stringBuilder.AppendLine(GetFileLine(filePath, "MP3"));
 
-            var startOffset = chapters.StartOffset;
+		var startOffset = chapters.StartOffset;
 
-            var trackCount = 1;
-            foreach (var c in chapters.Chapters)
-            {
-                var startTime = c.StartOffset - startOffset;
+		var trackCount = 1;
+		foreach (var c in chapters.Chapters)
+		{
+			var startTime = c.StartOffset - startOffset;
 
-                stringBuilder.AppendLine($"TRACK {trackCount++} AUDIO");
-                stringBuilder.AppendLine($"  TITLE \"{c.Title}\"");
-                stringBuilder.AppendLine($"  INDEX 01 {(int)startTime.TotalMinutes}:{startTime:ss}:{(int)(startTime.Milliseconds * 75d / 1000):D2}");
-            }
+			stringBuilder.AppendLine($"TRACK {trackCount++} AUDIO");
+			stringBuilder.AppendLine($"  TITLE \"{c.Title}\"");
+			stringBuilder.AppendLine($"  INDEX 01 {(int)startTime.TotalMinutes}:{startTime:ss}:{(int)(startTime.Milliseconds * 75d / 1000):D2}");
+		}
 
-            return stringBuilder.ToString();
-        }
+		return stringBuilder.ToString();
+	}
 
-        public static void UpdateFileName(FileInfo cueFileInfo, string audioFilePath)
-            => UpdateFileName(cueFileInfo.FullName, audioFilePath);
+	public static void UpdateFileName(FileInfo cueFileInfo, string audioFilePath)
+		=> UpdateFileName(cueFileInfo.FullName, audioFilePath);
 
-        public static void UpdateFileName(string cueFilePath, FileInfo audioFileInfo)
-            => UpdateFileName(cueFilePath, audioFileInfo.FullName);
+	public static void UpdateFileName(string cueFilePath, FileInfo audioFileInfo)
+		=> UpdateFileName(cueFilePath, audioFileInfo.FullName);
 
-        public static void UpdateFileName(FileInfo cueFileInfo, FileInfo audioFileInfo)
-            => UpdateFileName(cueFileInfo.FullName, audioFileInfo.FullName);
+	public static void UpdateFileName(FileInfo cueFileInfo, FileInfo audioFileInfo)
+		=> UpdateFileName(cueFileInfo.FullName, audioFileInfo.FullName);
 
-        public static void UpdateFileName(string cueFilePath, string audioFilePath)
-        {
-            var cueContents = File.ReadAllLines(cueFilePath);
+	public static void UpdateFileName(string cueFilePath, string audioFilePath)
+	{
+		var cueContents = File.ReadAllLines(cueFilePath);
 
-            for (var i = 0; i < cueContents.Length; i++)
-            {
-                var line = cueContents[i];
-                if (!line.Trim().StartsWith("FILE") || !line.Contains(' '))
-                    continue;
+		for (var i = 0; i < cueContents.Length; i++)
+		{
+			var line = cueContents[i];
+			if (!line.Trim().StartsWith("FILE") || !line.Contains(' '))
+				continue;
 
-                var fileTypeBegins = line.LastIndexOf(" ") + 1;
-                cueContents[i] = GetFileLine(audioFilePath, line[fileTypeBegins..]);
-                break;
-            }
+			var fileTypeBegins = line.LastIndexOf(" ") + 1;
+			cueContents[i] = GetFileLine(audioFilePath, line[fileTypeBegins..]);
+			break;
+		}
 
-            File.WriteAllLines(cueFilePath, cueContents);
-        }
+		File.WriteAllLines(cueFilePath, cueContents);
+	}
 
-        private static string GetFileLine(string filePath, string audioType) => $"FILE {Path.GetFileName(filePath).SurroundWithQuotes()} {audioType}";
-    }
+	private static string GetFileLine(string filePath, string audioType) => $"FILE {Path.GetFileName(filePath).SurroundWithQuotes()} {audioType}";
 }

Source/AaxDecrypter/IDownloadOptions.cs

@@ -1,32 +1,54 @@
 using AAXClean;
+using Mpeg4Lib;
 using System;
-using System.Threading.Tasks;
 
-namespace AaxDecrypter
+namespace AaxDecrypter;
+
+public class KeyData
 {
-    public interface IDownloadOptions
-    {
-        event EventHandler<long> DownloadSpeedChanged;
-        string DownloadUrl { get; }
-        string UserAgent { get; }
-        string AudibleKey { get; }
-        string AudibleIV { get; }
-        TimeSpan RuntimeLength { get; }
-        OutputFormat OutputFormat { get; }
-        bool TrimOutputToChapterLength { get; }
-        bool RetainEncryptedFile { get; }
-        bool StripUnabridged { get; }
-        bool CreateCueSheet { get; }
-        bool DownloadClipsBookmarks { get; }
-        long DownloadSpeedBps { get; }
-        ChapterInfo ChapterInfo { get; }
-        bool FixupFile { get; }
-        NAudio.Lame.LameConfig LameConfig { get; }
-        bool Downsample { get; }
-        bool MatchSourceBitrate { get; }
-        bool MoveMoovToBeginning { get; }
-        string GetMultipartFileName(MultiConvertFileProperties props);
-        string GetMultipartTitle(MultiConvertFileProperties props);
-        Task<string> SaveClipsAndBookmarksAsync(string fileName);
-    }
+	public byte[] KeyPart1 { get; }
+	public byte[]? KeyPart2 { get; }
+
+	public KeyData(byte[] keyPart1, byte[]? keyPart2 = null)
+	{
+		KeyPart1 = keyPart1;
+		KeyPart2 = keyPart2;
+	}
+
+	[Newtonsoft.Json.JsonConstructor]
+	public KeyData(string keyPart1, string? keyPart2 = null)
+	{
+		ArgumentNullException.ThrowIfNull(keyPart1, nameof(keyPart1));
+		KeyPart1 = Convert.FromHexString(keyPart1);
+		if (keyPart2 != null)
+			KeyPart2 = Convert.FromHexString(keyPart2);
+	}
+}
+
+public interface IDownloadOptions
+{
+	event EventHandler<long> DownloadSpeedChanged;
+	string DownloadUrl { get; }
+	string UserAgent { get; }
+	KeyData[]? DecryptionKeys { get; }
+	TimeSpan RuntimeLength { get; }
+	OutputFormat OutputFormat { get; }
+	bool StripUnabridged { get; }
+	bool CreateCueSheet { get; }
+	long DownloadSpeedBps { get; }
+	ChapterInfo ChapterInfo { get; }
+	bool FixupFile { get; }
+	string? AudibleProductId { get; }
+	string? Title { get; }
+	string? Subtitle { get; }
+	string? Publisher { get; }
+	string? Language { get; }
+	string? SeriesName { get; }
+	string? SeriesNumber { get; }
+	NAudio.Lame.LameConfig? LameConfig { get; }
+	bool Downsample { get; }
+	bool MatchSourceBitrate { get; }
+	bool MoveMoovToBeginning { get; }
+	string GetMultipartTitle(MultiConvertFileProperties props);
+	public FileType? InputType { get; }
 }

Source/AaxDecrypter/MpegUtil.cs

@@ -1,31 +1,71 @@
-using AAXClean;
+using AAXClean.Codecs;
+using Mpeg4Lib;
 using NAudio.Lame;
+using System;
+using System.Linq;
 
-namespace AaxDecrypter
+namespace AaxDecrypter;
+
+public static class MpegUtil
 {
-	public static class MpegUtil
+	private const string TagDomain = "com.pilabor.tone";
+	public static void ConfigureLameOptions(
+		Mpeg4File mp4File,
+		LameConfig lameConfig,
+		bool downsample,
+		bool matchSourceBitrate,
+		ChapterInfo? chapters)
 	{
-		public static void ConfigureLameOptions(Mp4File mp4File, LameConfig lameConfig, bool downsample, bool matchSourceBitrate)
+		double bitrateMultiple = 1;
+
+		if (mp4File.TimeScale < lameConfig.OutputSampleRate)
 		{
-			double bitrateMultiple = 1;
+			lameConfig.OutputSampleRate = mp4File.TimeScale;
+		}
+		else if (mp4File.TimeScale > lameConfig.OutputSampleRate)
+		{
+			bitrateMultiple *= (double)lameConfig.OutputSampleRate / mp4File.TimeScale;
+		}
 
-			if (mp4File.AudioChannels == 2)
-			{
-				if (downsample)
-					bitrateMultiple = 0.5;
-				else
-					lameConfig.Mode = MPEGMode.Stereo;
-			}
+		if (mp4File.AudioChannels == 2)
+		{
+			if (downsample)
+				bitrateMultiple /= 2;
+			else
+				lameConfig.Mode = MPEGMode.Stereo;
+		}
 
-			if (matchSourceBitrate)
-			{
-				int kbps = (int)(mp4File.AverageBitrate * bitrateMultiple / 1024);
+		if (matchSourceBitrate)
+		{
+			int kbps = (int)Math.Round(mp4File.AverageBitrate * bitrateMultiple / 1024);
 
-				if (lameConfig.VBR is null)
-					lameConfig.BitRate = kbps;
-				else if (lameConfig.VBR == VBRMode.ABR)
-					lameConfig.ABRRateKbps = kbps;
-			}
+			if (lameConfig.VBR is null)
+				lameConfig.BitRate = kbps;
+			else if (lameConfig.VBR == VBRMode.ABR)
+				lameConfig.ABRRateKbps = kbps;
+		}
+
+		//Setup metadata tags
+		lameConfig.ID3 = mp4File.MetadataItems.ToIDTags();
+
+		if (mp4File.MetadataItems.AppleListBox.GetFreeformTagString(TagDomain, "SUBTITLE") is string subtitle)
+			lameConfig.ID3.Subtitle = subtitle;
+
+		if (chapters?.Count > 0)
+		{
+			var cue = Cue.CreateContents(lameConfig.ID3.Title + ".mp3", chapters);
+			lameConfig.ID3.UserDefinedText.Add("CUESHEET", cue);
+		}
+
+		//Copy over all other freeform tags
+		foreach (var t in mp4File.MetadataItems.AppleListBox.Tags.OfType<Mpeg4Lib.Boxes.FreeformTagBox>())
+		{
+			if (t.Name?.Name is string name &&
+				t.Mean?.ReverseDnsDomain is string domain &&
+				!lameConfig.ID3.UserDefinedText.ContainsKey(name) &&
+				mp4File.MetadataItems.AppleListBox.GetFreeformTagString(domain, name) is string tagStr &&
+				!string.IsNullOrWhiteSpace(tagStr))
+				lameConfig.ID3.UserDefinedText.Add(name, tagStr);
 		}
 	}
 }

Source/AaxDecrypter/MultiConvertFileProperties.cs

@@ -1,13 +1,12 @@
 using System;
 
-namespace AaxDecrypter
+namespace AaxDecrypter;
+
+public class MultiConvertFileProperties
 {
-    public class MultiConvertFileProperties
-    {
-        public string OutputFileName { get; set; }
-        public int PartsPosition { get; set; }
-        public int PartsTotal { get; set; }
-        public string Title { get; set; }
-        public DateTime FileDate { get; } = DateTime.Now;
-    }
+	public required string OutputFileName { get; set; }
+	public int PartsPosition { get; set; }
+	public int PartsTotal { get; set; }
+	public string? Title { get; set; }
+	public DateTime FileDate { get; } = DateTime.Now;
 }

Source/AaxDecrypter/NetworkFileStream.cs

@@ -8,329 +8,419 @@ using System.Net.Http;
 using System.Threading;
 using System.Threading.Tasks;
 
-namespace AaxDecrypter
+namespace AaxDecrypter;
+
+/// <summary>A resumable, simultaneous file downloader and reader. </summary>
+public class NetworkFileStream : Stream, IUpdatable
 {
-	/// <summary>A resumable, simultaneous file downloader and reader. </summary>
-	public class NetworkFileStream : Stream, IUpdatable
+	public event EventHandler? Updated;
+
+	#region Public Properties
+
+	/// <summary> Location to save the downloaded data. </summary>
+	[JsonProperty(Required = Required.Always)]
+	public string SaveFilePath { get; }
+
+	/// <summary> Http(s) address of the file to download. </summary>
+	[JsonProperty(Required = Required.Always)]
+	public Uri Uri { get; private set; }
+
+	/// <summary> Http headers to be sent to the server with the request. </summary>
+	[JsonProperty(Required = Required.Always)]
+	public Dictionary<string, string> RequestHeaders { get; private set; }
+
+	/// <summary> The position in <see cref="SaveFilePath"/> that has been written and flushed to disk. </summary>
+	[JsonProperty(Required = Required.Always)]
+	public long WritePosition { get; private set; }
+
+	/// <summary> The total length of the <see cref="Uri"/> file to download. </summary>
+	[JsonProperty(Required = Required.Always)]
+	public long ContentLength { get; private set; }
+
+	[JsonIgnore]
+	public bool IsCancelled => _cancellationSource.IsCancellationRequested;
+
+	[JsonIgnore]
+	public Task? DownloadTask { get; private set; }
+
+	private long _speedLimit = 0;
+	/// <summary>bytes per second</summary>
+	public long SpeedLimit { get => _speedLimit; set => _speedLimit = value <= 0 ? 0 : Math.Max(value, MIN_BYTES_PER_SECOND); }
+
+	#endregion
+
+	#region Private Properties
+	private FileStream _writeFile { get; }
+	private FileStream _readFile { get; }
+	private CancellationTokenSource _cancellationSource { get; } = new();
+	private EventWaitHandle? _downloadedPiece { get; set; }
+
+	private DateTime NextUpdateTime { get; set; }
+
+	#endregion
+
+	#region Constants
+
+	//Download memory buffer size
+	private const int DOWNLOAD_BUFF_SZ = 8 * 1024;
+
+	//NetworkFileStream will flush all data in _writeFile to disk after every
+	//DATA_FLUSH_SZ bytes are written to the file stream.
+	private const int DATA_FLUSH_SZ = 1024 * 1024;
+
+	//Number of times per second the download rate is checked and throttled
+	private const int THROTTLE_FREQUENCY = 8;
+
+	//Minimum throttle rate. The minimum amount of data that can be throttled
+	//on each iteration of the download loop is DOWNLOAD_BUFF_SZ.
+	public const int MIN_BYTES_PER_SECOND = DOWNLOAD_BUFF_SZ * THROTTLE_FREQUENCY;
+
+	#endregion
+
+	#region Constructor
+
+	/// <summary> A resumable, simultaneous file downloader and reader. </summary>
+	/// <param name="saveFilePath">Path to a location on disk to save the downloaded data from <paramref name="uri"/></param>
+	/// <param name="uri">Http(s) address of the file to download.</param>
+	/// <param name="writePosition">The position in <paramref name="uri"/> to begin downloading.</param>
+	/// <param name="requestHeaders">Http headers to be sent to the server with the <see cref="HttpWebRequest"/>.</param>
+	public NetworkFileStream(string saveFilePath, Uri uri, long writePosition = 0, Dictionary<string, string>? requestHeaders = null)
 	{
-		public event EventHandler Updated;
+		SaveFilePath = ArgumentValidator.EnsureNotNullOrWhiteSpace(saveFilePath, nameof(saveFilePath));
+		Uri = ArgumentValidator.EnsureNotNull(uri, nameof(uri));
+		WritePosition = ArgumentValidator.EnsureGreaterThan(writePosition, nameof(writePosition), -1);
 
-		#region Public Properties
+		if (!Directory.Exists(Path.GetDirectoryName(saveFilePath)))
+			throw new ArgumentException($"Specified {nameof(saveFilePath)} directory \"{Path.GetDirectoryName(saveFilePath)}\" does not exist.");
 
-		/// <summary> Location to save the downloaded data. </summary>
-		[JsonProperty(Required = Required.Always)]
-		public string SaveFilePath { get; }
+		RequestHeaders = requestHeaders ?? new();
 
-		/// <summary> Http(s) address of the file to download. </summary>
-		[JsonProperty(Required = Required.Always)]
-		public Uri Uri { get; private set; }
-
-		/// <summary> Http headers to be sent to the server with the request. </summary>
-		[JsonProperty(Required = Required.Always)]
-		public Dictionary<string, string> RequestHeaders { get; private set; }
-
-		/// <summary> The position in <see cref="SaveFilePath"/> that has been written and flushed to disk. </summary>
-		[JsonProperty(Required = Required.Always)]
-		public long WritePosition { get; private set; }
-
-		/// <summary> The total length of the <see cref="Uri"/> file to download. </summary>
-		[JsonProperty(Required = Required.Always)]
-		public long ContentLength { get; private set; }
-
-		[JsonIgnore]
-		public bool IsCancelled => _cancellationSource.IsCancellationRequested;
-
-		private long _speedLimit = 0;
-		/// <summary>bytes per second</summary>
-		public long SpeedLimit { get => _speedLimit; set => _speedLimit = value <= 0 ? 0 : Math.Max(value, MIN_BYTES_PER_SECOND); }
-
-		#endregion
-
-		#region Private Properties
-		private FileStream _writeFile { get; }
-		private FileStream _readFile { get; }
-		private CancellationTokenSource _cancellationSource { get; } = new();
-		private EventWaitHandle _downloadedPiece { get; set; }
-		private Task _backgroundDownloadTask { get; set; }
-
-		#endregion
-
-		#region Constants
-
-		//Download buffer size
-		private const int DOWNLOAD_BUFF_SZ = 32 * 1024;
-
-		//NetworkFileStream will flush all data in _writeFile to disk after every
-		//DATA_FLUSH_SZ bytes are written to the file stream.
-		private const int DATA_FLUSH_SZ = 1024 * 1024;
-
-		//Number of times per second the download rate is checkd and throttled
-		private const int THROTTLE_FREQUENCY = 8;
-
-		//Minimum throttle rate. The minimum amount of data that can be throttled
-		//on each iteration of the download loop is DOWNLOAD_BUFF_SZ.
-		public const int MIN_BYTES_PER_SECOND = DOWNLOAD_BUFF_SZ * THROTTLE_FREQUENCY;
-
-		#endregion
-
-		#region Constructor
-
-		/// <summary> A resumable, simultaneous file downloader and reader. </summary>
-		/// <param name="saveFilePath">Path to a location on disk to save the downloaded data from <paramref name="uri"/></param>
-		/// <param name="uri">Http(s) address of the file to download.</param>
-		/// <param name="writePosition">The position in <paramref name="uri"/> to begin downloading.</param>
-		/// <param name="requestHeaders">Http headers to be sent to the server with the <see cref="HttpWebRequest"/>.</param>
-		public NetworkFileStream(string saveFilePath, Uri uri, long writePosition = 0, Dictionary<string, string> requestHeaders = null)
+		_writeFile = new FileStream(SaveFilePath, FileMode.OpenOrCreate, FileAccess.Write, FileShare.ReadWrite)
 		{
-			SaveFilePath = ArgumentValidator.EnsureNotNullOrWhiteSpace(saveFilePath, nameof(saveFilePath));
-			Uri = ArgumentValidator.EnsureNotNull(uri, nameof(uri));
-			WritePosition = ArgumentValidator.EnsureGreaterThan(writePosition, nameof(writePosition), -1);
+			Position = WritePosition
+		};
 
-			if (!Directory.Exists(Path.GetDirectoryName(saveFilePath)))
-				throw new ArgumentException($"Specified {nameof(saveFilePath)} directory \"{Path.GetDirectoryName(saveFilePath)}\" does not exist.");
-
-			RequestHeaders = requestHeaders ?? new();
-
-			_writeFile = new FileStream(SaveFilePath, FileMode.OpenOrCreate, FileAccess.Write, FileShare.ReadWrite)
-			{
-				Position = WritePosition
-			};
-
-			_readFile = new FileStream(SaveFilePath, FileMode.Open, FileAccess.Read, FileShare.ReadWrite);
-
-			SetUriForSameFile(uri);
+		if (_writeFile.Length < WritePosition)
+		{
+			_writeFile.Dispose();
+			throw new InvalidDataException($"{SaveFilePath} file length is shorter than {WritePosition}");
 		}
 
-		#endregion
+		_readFile = new FileStream(SaveFilePath, FileMode.Open, FileAccess.Read, FileShare.ReadWrite);
 
-		#region Downloader
+		SetUriForSameFile(uri);
+	}
 
-		/// <summary> Update the <see cref="Dinah.Core.IO.JsonFilePersister{T}"/>. </summary>
-		private void OnUpdate()
+	#endregion
+
+	#region Downloader
+
+	/// <summary> Update the <see cref="Dinah.Core.IO.JsonFilePersister{T}"/>. </summary>
+	private void OnUpdate(bool waitForWrite = false)
+	{
+		try
 		{
-			RequestHeaders["Range"] = $"bytes={WritePosition}-";
-			try
+			if (waitForWrite || DateTime.UtcNow > NextUpdateTime)
 			{
 				Updated?.Invoke(this, EventArgs.Empty);
-			}
-			catch (Exception ex)
-			{
-				Serilog.Log.Error(ex, "An error was encountered while saving the download progress to JSON");
+				//JsonFilePersister Will not allow update intervals shorter than 100 milliseconds
+				//If an update is called less than 100 ms since the last update, persister will
+				//sleep the thread until 100 ms has elapsed.
+				NextUpdateTime = DateTime.UtcNow.AddMilliseconds(110);
 			}
 		}
-
-		/// <summary> Set a different <see cref="System.Uri"/> to the same file targeted by this instance of <see cref="NetworkFileStream"/> </summary>
-		/// <param name="uriToSameFile">New <see cref="System.Uri"/> host must match existing host.</param>
-		public void SetUriForSameFile(Uri uriToSameFile)
+		catch (Exception ex)
 		{
-			ArgumentValidator.EnsureNotNullOrWhiteSpace(uriToSameFile?.AbsoluteUri, nameof(uriToSameFile));
-
-			if (uriToSameFile.Host != Uri.Host)
-				throw new ArgumentException($"New uri to the same file must have the same host.\r\n Old Host :{Uri.Host}\r\nNew Host: {uriToSameFile.Host}");
-			if (_backgroundDownloadTask is not null)
-				throw new InvalidOperationException("Cannot change Uri after download has started.");
-
-			Uri = uriToSameFile;
-			RequestHeaders["Range"] = $"bytes={WritePosition}-";
+			Serilog.Log.Error(ex, "An error was encountered while saving the download progress to JSON");
 		}
-
-		/// <summary> Begins downloading <see cref="Uri"/> to <see cref="SaveFilePath"/> in a background thread. </summary>
-		/// <returns>The downloader <see cref="Task"/></returns>
-		private Task BeginDownloading()
-		{
-			if (ContentLength != 0 && WritePosition == ContentLength)
-				return Task.CompletedTask;
-
-			if (ContentLength != 0 && WritePosition > ContentLength)
-				throw new WebException($"Specified write position (0x{WritePosition:X10}) is larger than  {nameof(ContentLength)} (0x{ContentLength:X10}).");
-
-			var request = new HttpRequestMessage(HttpMethod.Get, Uri);
-
-			foreach (var header in RequestHeaders)
-				request.Headers.Add(header.Key, header.Value);
-
-			var response = new HttpClient().Send(request, HttpCompletionOption.ResponseHeadersRead, _cancellationSource.Token);
-
-			if (response.StatusCode != HttpStatusCode.PartialContent)
-				throw new WebException($"Server at {Uri.Host} responded with unexpected status code: {response.StatusCode}.");
-
-			//Content length is the length of the range request, and it is only equal
-			//to the complete file length if requesting Range: bytes=0-
-			if (WritePosition == 0)
-				ContentLength = response.Content.Headers.ContentLength.GetValueOrDefault();
-
-			var networkStream = response.Content.ReadAsStream(_cancellationSource.Token);
-			_downloadedPiece = new EventWaitHandle(false, EventResetMode.AutoReset);
-
-			//Download the file in the background.
-			return Task.Run(() => DownloadFile(networkStream), _cancellationSource.Token);
-		}
-
-		/// <summary> Download <see cref="Uri"/> to <see cref="SaveFilePath"/>.</summary>
-		private async Task DownloadFile(Stream networkStream)
-		{
-			var downloadPosition = WritePosition;
-			var nextFlush = downloadPosition + DATA_FLUSH_SZ;
-			var buff = new byte[DOWNLOAD_BUFF_SZ];
-
-			try
-			{
-				DateTime startTime = DateTime.Now;
-				long bytesReadSinceThrottle = 0;
-				int bytesRead;
-				do
-				{
-					bytesRead = await networkStream.ReadAsync(buff, _cancellationSource.Token);
-					await _writeFile.WriteAsync(buff, 0, bytesRead, _cancellationSource.Token);
-
-					downloadPosition += bytesRead;
-
-					if (downloadPosition > nextFlush)
-					{
-						await _writeFile.FlushAsync(_cancellationSource.Token);
-						WritePosition = downloadPosition;
-						OnUpdate();
-						nextFlush = downloadPosition + DATA_FLUSH_SZ;
-						_downloadedPiece.Set();
-					}
-
-					#region throttle
-
-					bytesReadSinceThrottle += bytesRead;
-
-					if (SpeedLimit >= MIN_BYTES_PER_SECOND && bytesReadSinceThrottle > SpeedLimit / THROTTLE_FREQUENCY)
-					{
-						var delayMS = (int)(startTime.AddSeconds(1d / THROTTLE_FREQUENCY) - DateTime.Now).TotalMilliseconds;
-						if (delayMS > 0)
-							await Task.Delay(delayMS, _cancellationSource.Token);
-
-						startTime = DateTime.Now;
-						bytesReadSinceThrottle = 0;
-					}
-
-					#endregion
-
-				} while (downloadPosition < ContentLength && !IsCancelled && bytesRead > 0);
-
-				WritePosition = downloadPosition;
-
-				if (!IsCancelled && WritePosition < ContentLength)
-					throw new WebException($"Downloaded size (0x{WritePosition:X10}) is less than {nameof(ContentLength)} (0x{ContentLength:X10}).");
-
-				if (WritePosition > ContentLength)
-					throw new WebException($"Downloaded size (0x{WritePosition:X10}) is greater than {nameof(ContentLength)} (0x{ContentLength:X10}).");
-			}
-			catch (TaskCanceledException)
-			{
-				Serilog.Log.Information("Download was cancelled");
-			}
-			finally
-			{
-				networkStream.Close();
-				_writeFile.Close();
-				_downloadedPiece.Set();
-				OnUpdate();
-			}
-		}
-
-		#endregion
-
-		#region Download Stream Reader
-
-		[JsonIgnore]
-		public override bool CanRead => true;
-
-		[JsonIgnore]
-		public override bool CanSeek => true;
-
-		[JsonIgnore]
-		public override bool CanWrite => false;
-
-		[JsonIgnore]
-		public override long Length
-		{
-			get
-			{
-				_backgroundDownloadTask ??= BeginDownloading();
-				return ContentLength;
-			}
-		}
-
-		[JsonIgnore]
-		public override long Position { get => _readFile.Position; set => Seek(value, SeekOrigin.Begin); }
-
-		[JsonIgnore]
-		public override bool CanTimeout => false;
-
-		[JsonIgnore]
-		public override int ReadTimeout { get => base.ReadTimeout; set => base.ReadTimeout = value; }
-
-		[JsonIgnore]
-		public override int WriteTimeout { get => base.WriteTimeout; set => base.WriteTimeout = value; }
-
-		public override void Flush() => throw new InvalidOperationException();
-		public override void SetLength(long value) => throw new InvalidOperationException();
-		public override void Write(byte[] buffer, int offset, int count) => throw new InvalidOperationException();
-
-		public override int Read(byte[] buffer, int offset, int count)
-		{
-			_backgroundDownloadTask ??= BeginDownloading();
-
-			var toRead = Math.Min(count, Length - Position);
-			WaitToPosition(Position + toRead);
-			return IsCancelled ? 0 : _readFile.Read(buffer, offset, count);
-		}
-
-		public override long Seek(long offset, SeekOrigin origin)
-		{
-			var newPosition = origin switch
-			{
-				SeekOrigin.Current => Position + offset,
-				SeekOrigin.End => ContentLength + offset,
-				_ => offset,
-			};
-
-			WaitToPosition(newPosition);
-			return _readFile.Position = newPosition;
-		}
-
-		/// <summary>Blocks until the file has downloaded to at least <paramref name="requiredPosition"/>, then returns. </summary>
-		/// <param name="requiredPosition">The minimum required flushed data length in <see cref="SaveFilePath"/>.</param>
-		private void WaitToPosition(long requiredPosition)
-		{
-			while (WritePosition < requiredPosition
-				&& _backgroundDownloadTask?.IsCompleted is false
-				&& !IsCancelled)
-			{
-				_downloadedPiece.WaitOne(50);
-			}
-		}
-
-		private bool disposed = false;
-
-		/*
-		 * https://learn.microsoft.com/en-us/dotnet/api/system.io.stream.dispose?view=net-7.0
-		 * 
-		 * In derived classes, do not override the Close() method, instead, put all of the
-		 * Stream cleanup logic in the Dispose(Boolean) method.
-		 */
-		protected override void Dispose(bool disposing)
-		{
-			if (disposing && !disposed)
-			{
-				_cancellationSource.Cancel();
-				_backgroundDownloadTask?.GetAwaiter().GetResult();
-				_downloadedPiece?.Dispose();
-				_cancellationSource?.Dispose();
-				_readFile.Dispose();
-				_writeFile.Dispose();
-				OnUpdate();
-			}
-
-			disposed = true;
-			base.Dispose(disposing);
-		}
-
-		#endregion
 	}
+
+	/// <summary> Set a different <see cref="System.Uri"/> to the same file targeted by this instance of <see cref="NetworkFileStream"/> </summary>
+	/// <param name="uriToSameFile">New <see cref="System.Uri"/> host must match existing host.</param>
+	public void SetUriForSameFile(Uri uriToSameFile)
+	{
+		ArgumentValidator.EnsureNotNullOrWhiteSpace(uriToSameFile?.AbsoluteUri, nameof(uriToSameFile));
+
+		if (Path.GetFileName(uriToSameFile.LocalPath) != Path.GetFileName(Uri.LocalPath))
+			throw new ArgumentException($"New uri to the same file must have the same file name.");
+		if (uriToSameFile.Host != Uri.Host)
+			throw new ArgumentException($"New uri to the same file must have the same host.\r\n Old Host :{Uri.Host}\r\nNew Host: {uriToSameFile.Host}");
+		if (DownloadTask is not null)
+			throw new InvalidOperationException("Cannot change Uri after download has started.");
+
+		Uri = uriToSameFile;
+	}
+
+	/// <summary> Begins downloading <see cref="Uri"/> to <see cref="SaveFilePath"/> in a background thread. </summary>
+	/// <returns>The downloader <see cref="Task"/></returns>
+	public async Task BeginDownloadingAsync()
+	{
+		if (ContentLength != 0 && WritePosition == ContentLength)
+		{
+			DownloadTask = Task.CompletedTask;
+			return;
+		}
+
+		if (ContentLength != 0 && WritePosition > ContentLength)
+			throw new WebException($"Specified write position (0x{WritePosition:X10}) is larger than  {nameof(ContentLength)} (0x{ContentLength:X10}).");
+
+		//Initiate connection with the first request block and
+		//get the total content length before returning.
+		var client = new HttpClient();
+		var response = await RequestNextByteRangeAsync(client);
+
+		if (ContentLength != 0 && ContentLength != response.FileSize)
+			throw new WebException($"Content length of 0x{response.FileSize:X10} differs from partially downloaded content length of 0x{ContentLength:X10}");
+
+		ContentLength = response.FileSize;
+
+		_downloadedPiece = new EventWaitHandle(false, EventResetMode.AutoReset);
+		//Hand off the client and the open request to the downloader to download and write data to file.
+		DownloadTask = Task.Run(() => DownloadLoopInternal(client, response), _cancellationSource.Token);
+	}
+
+	private async Task DownloadLoopInternal(HttpClient client, BlockResponse blockResponse)
+	{
+		try
+		{
+			long startPosition = WritePosition;
+
+			while (WritePosition < ContentLength && !IsCancelled)
+			{
+				try
+				{
+					await DownloadToFile(blockResponse);
+				}
+				catch (HttpIOException e)
+					when (e.HttpRequestError is HttpRequestError.ResponseEnded
+							&& WritePosition != startPosition
+							&& WritePosition < ContentLength && !IsCancelled)
+				{
+					Serilog.Log.Logger.Debug($"The download connection ended before the file completed downloading all 0x{ContentLength:X10} bytes");
+
+					//the download made *some* progress since the last attempt.
+					//Try again to complete the download from where it left off.
+					//Make sure to rewind file to last flush position.
+					_writeFile.Position = startPosition = WritePosition;
+					blockResponse.Dispose();
+					blockResponse = await RequestNextByteRangeAsync(client);
+
+					Serilog.Log.Logger.Debug($"Resuming the file download starting at position 0x{WritePosition:X10}.");
+				}
+			}
+		}
+		catch (Exception ex)
+		{
+			//Don't throw from DownloadTask.
+			//This task gets awaited in Dispose() and we don't want to have an unhandled exception there.
+			Serilog.Log.Error(ex, "An error was encountered during the download process.");
+		}
+		finally
+		{
+			_writeFile.Dispose();
+			blockResponse.Dispose();
+			client.Dispose();
+		}
+	}
+
+	private async Task<BlockResponse> RequestNextByteRangeAsync(HttpClient client)
+	{
+		using var request = new HttpRequestMessage(HttpMethod.Get, Uri);
+
+		//Just in case it snuck in the saved json (Issue #1232)
+		RequestHeaders.Remove("Range");
+
+		foreach (var header in RequestHeaders)
+			request.Headers.Add(header.Key, header.Value);
+
+		request.Headers.Add("Range", $"bytes={WritePosition}-");
+
+		var response = await client.SendAsync(request, HttpCompletionOption.ResponseHeadersRead, _cancellationSource.Token);
+
+		if (response.StatusCode != HttpStatusCode.PartialContent)
+			throw new WebException($"Server at {Uri.Host} responded with unexpected status code: {response.StatusCode}.");
+
+		var totalSize = response.Content.Headers.ContentRange?.Length ??
+			throw new WebException("The response did not contain a total content length.");
+
+		var rangeSize = response.Content.Headers.ContentLength ??
+			throw new WebException($"The response did not contain a {nameof(response.Content.Headers.ContentLength)};");
+
+		return new BlockResponse(response, rangeSize, totalSize);
+	}
+
+	private readonly record struct BlockResponse(HttpResponseMessage Response, long BlockSize, long FileSize) : IDisposable
+	{
+		public void Dispose() => Response?.Dispose();
+	}
+
+	/// <summary> Download <see cref="Uri"/> to <see cref="SaveFilePath"/>.</summary>
+	private async Task DownloadToFile(BlockResponse block)
+	{
+		var endPosition = WritePosition + block.BlockSize;
+		using var networkStream = await block.Response.Content.ReadAsStreamAsync(_cancellationSource.Token);
+
+		var downloadPosition = WritePosition;
+		var nextFlush = downloadPosition + DATA_FLUSH_SZ;
+		var buff = new byte[DOWNLOAD_BUFF_SZ];
+
+		try
+		{
+			DateTime startTime = DateTime.UtcNow;
+			long bytesReadSinceThrottle = 0;
+			int bytesRead;
+			do
+			{
+				bytesRead = await networkStream.ReadAsync(buff, _cancellationSource.Token);
+				await _writeFile.WriteAsync(buff, 0, bytesRead, _cancellationSource.Token);
+
+				downloadPosition += bytesRead;
+
+				if (downloadPosition > nextFlush)
+				{
+					await _writeFile.FlushAsync(_cancellationSource.Token);
+					WritePosition = downloadPosition;
+					OnUpdate();
+					nextFlush = downloadPosition + DATA_FLUSH_SZ;
+					_downloadedPiece?.Set();
+				}
+
+				#region throttle
+
+				bytesReadSinceThrottle += bytesRead;
+
+				if (SpeedLimit >= MIN_BYTES_PER_SECOND && bytesReadSinceThrottle > SpeedLimit / THROTTLE_FREQUENCY)
+				{
+					var delayMS = (int)(startTime.AddSeconds(1d / THROTTLE_FREQUENCY) - DateTime.UtcNow).TotalMilliseconds;
+					if (delayMS > 0)
+						await Task.Delay(delayMS, _cancellationSource.Token);
+
+					startTime = DateTime.UtcNow;
+					bytesReadSinceThrottle = 0;
+				}
+
+				#endregion
+
+			} while (downloadPosition < endPosition && !IsCancelled && bytesRead > 0);
+
+			await _writeFile.FlushAsync(_cancellationSource.Token);
+			WritePosition = downloadPosition;
+
+			if (!IsCancelled && WritePosition < endPosition)
+				throw new WebException($"Downloaded size (0x{WritePosition:X10}) is less than {nameof(ContentLength)} (0x{ContentLength:X10}).");
+
+			if (WritePosition > endPosition)
+				throw new WebException($"Downloaded size (0x{WritePosition:X10}) is greater than {nameof(ContentLength)} (0x{ContentLength:X10}).");
+		}
+		catch (OperationCanceledException)
+		{
+			Serilog.Log.Information("Download was cancelled");
+		}
+		finally
+		{
+			_downloadedPiece?.Set();
+			OnUpdate(waitForWrite: true);
+		}
+	}
+
+	#endregion
+
+	#region Download Stream Reader
+
+	[JsonIgnore]
+	public override bool CanRead => _readFile.CanRead;
+
+	[JsonIgnore]
+	public override bool CanSeek => _readFile.CanSeek;
+
+	[JsonIgnore]
+	public override bool CanWrite => false;
+
+	[JsonIgnore]
+	public override long Length
+	{
+		get
+		{
+			if (DownloadTask is null)
+				throw new InvalidOperationException($"Background downloader must first be started by calling {nameof(BeginDownloadingAsync)}");
+			return ContentLength;
+		}
+	}
+
+	[JsonIgnore]
+	public override long Position { get => _readFile.Position; set => Seek(value, SeekOrigin.Begin); }
+
+	[JsonIgnore]
+	public override bool CanTimeout => false;
+
+	[JsonIgnore]
+	public override int ReadTimeout { get => base.ReadTimeout; set => base.ReadTimeout = value; }
+
+	[JsonIgnore]
+	public override int WriteTimeout { get => base.WriteTimeout; set => base.WriteTimeout = value; }
+
+	public override void Flush() => throw new InvalidOperationException();
+	public override void SetLength(long value) => throw new InvalidOperationException();
+	public override void Write(byte[] buffer, int offset, int count) => throw new InvalidOperationException();
+
+	public override int Read(byte[] buffer, int offset, int count)
+	{
+		if (DownloadTask is null)
+			throw new InvalidOperationException($"Background downloader must first be started by calling {nameof(BeginDownloadingAsync)}");
+
+		var toRead = Math.Min(count, Length - Position);
+		WaitToPosition(Position + toRead);
+		return IsCancelled ? 0 : _readFile.Read(buffer, offset, count);
+	}
+
+	public override long Seek(long offset, SeekOrigin origin)
+	{
+		var newPosition = origin switch
+		{
+			SeekOrigin.Current => Position + offset,
+			SeekOrigin.End => ContentLength + offset,
+			_ => offset,
+		};
+
+		WaitToPosition(newPosition);
+		return _readFile.Position = newPosition;
+	}
+
+	/// <summary>Blocks until the file has downloaded to at least <paramref name="requiredPosition"/>, then returns. </summary>
+	/// <param name="requiredPosition">The minimum required flushed data length in <see cref="SaveFilePath"/>.</param>
+	private void WaitToPosition(long requiredPosition)
+	{
+		while (WritePosition < requiredPosition
+			&& DownloadTask?.IsCompleted is false
+			&& !IsCancelled)
+		{
+			_downloadedPiece?.WaitOne(50);
+		}
+	}
+
+	private bool disposed = false;
+
+	/*
+	 * https://learn.microsoft.com/en-us/dotnet/api/system.io.stream.dispose?view=net-7.0
+	 * 
+	 * In derived classes, do not override the Close() method, instead, put all of the
+	 * Stream cleanup logic in the Dispose(Boolean) method.
+	 */
+	protected override void Dispose(bool disposing)
+	{
+		if (disposing && !Interlocked.CompareExchange(ref disposed, true, false))
+		{
+			_cancellationSource.Cancel();
+			DownloadTask?.GetAwaiter().GetResult();
+			_downloadedPiece?.Dispose();
+			_cancellationSource?.Dispose();
+			_readFile.Dispose();
+			_writeFile.Dispose();
+			OnUpdate(waitForWrite: true);
+		}
+
+		base.Dispose(disposing);
+	}
+
+	#endregion
 }

Source/AaxDecrypter/NetworkFileStreamPersister.cs

@@ -1,25 +1,24 @@
 using Dinah.Core.IO;
 
-namespace AaxDecrypter
+namespace AaxDecrypter;
+
+internal class NetworkFileStreamPersister : JsonFilePersister<NetworkFileStream>
 {
-	internal class NetworkFileStreamPersister : JsonFilePersister<NetworkFileStream>
+	/// <summary>Alias for Target </summary>
+	public NetworkFileStream NetworkFileStream => Target;
+
+	/// <summary>uses path. create file if doesn't yet exist</summary>
+	public NetworkFileStreamPersister(NetworkFileStream networkFileStream, string path, string? jsonPath = null)
+		: base(networkFileStream, path, jsonPath) { }
+
+	/// <summary>load from existing file</summary>
+	public NetworkFileStreamPersister(string path, string? jsonPath = null)
+		: base(path, jsonPath) { }
+
+	protected override void Dispose(bool disposing)
 	{
-		/// <summary>Alias for Target </summary>
-		public NetworkFileStream NetworkFileStream => Target;
-
-		/// <summary>uses path. create file if doesn't yet exist</summary>
-		public NetworkFileStreamPersister(NetworkFileStream networkFileStream, string path, string jsonPath = null)
-			: base(networkFileStream, path, jsonPath) { }
-
-		/// <summary>load from existing file</summary>
-		public NetworkFileStreamPersister(string path, string jsonPath = null)
-			: base(path, jsonPath) { }
-
-		protected override void Dispose(bool disposing)
-		{
-			if (disposing)
-				NetworkFileStream?.Dispose();
-			base.Dispose(disposing);
-		}
+		if (disposing)
+			NetworkFileStream?.Dispose();
+		base.Dispose(disposing);
 	}
 }

Source/AaxDecrypter/TempFile.cs

@@ -0,0 +1,16 @@
+using FileManager;
+
+namespace AaxDecrypter;
+
+public record TempFile
+{
+	public LongPath FilePath { get; init; }
+	public string Extension { get; }
+	public MultiConvertFileProperties? PartProperties { get; init; }
+	public TempFile(LongPath filePath, string? extension = null)
+	{
+		FilePath = filePath;
+		extension ??= System.IO.Path.GetExtension(filePath);
+		Extension = FileUtility.GetStandardizedExtension(extension).ToLowerInvariant();
+	}
+}

Source/AaxDecrypter/UnencryptedAudiobookDownloader.cs

@@ -1,65 +1,33 @@
-using Dinah.Core.Net.Http;
-using FileManager;
-using System;
+using FileManager;
 using System.Threading.Tasks;
 
-namespace AaxDecrypter
+namespace AaxDecrypter;
+
+public class UnencryptedAudiobookDownloader : AudiobookDownloadBase
 {
-	public class UnencryptedAudiobookDownloader : AudiobookDownloadBase
+	protected override long InputFilePosition => InputFileStream.WritePosition;
+
+	public UnencryptedAudiobookDownloader(string outDirectory, string cacheDirectory, IDownloadOptions dlLic)
+		: base(outDirectory, cacheDirectory, dlLic)
 	{
-		public UnencryptedAudiobookDownloader(string outFileName, string cacheDirectory, IDownloadOptions dlLic)
-			: base(outFileName, cacheDirectory, dlLic)
-		{
-			AsyncSteps.Name = "Download Unencrypted Audiobook";
-			AsyncSteps["Step 1: Download Audiobook"] = Step_DownloadAndDecryptAudiobookAsync;
-			AsyncSteps["Step 2: Download Clips and Bookmarks"] = Step_DownloadClipsBookmarksAsync;
-			AsyncSteps["Step 3: Create Cue"] = Step_CreateCueAsync;
-		}
+		AsyncSteps.Name = "Download Unencrypted Audiobook";
+		AsyncSteps["Step 1: Download Audiobook"] = Step_DownloadAndDecryptAudiobookAsync;
+		AsyncSteps["Step 2: Create Cue"] = Step_CreateCueAsync;
+	}
 
-		public override Task CancelAsync()
+	protected override async Task<bool> Step_DownloadAndDecryptAudiobookAsync()
+	{
+		await (InputFileStream.DownloadTask ?? Task.CompletedTask);
+
+		if (IsCanceled)
+			return false;
+		else
 		{
-			IsCanceled = true;
 			FinalizeDownload();
-			return Task.CompletedTask;
-		}
-
-		protected override async Task<bool> Step_DownloadAndDecryptAudiobookAsync()
-		{
-			DateTime startTime = DateTime.Now;
-
-			// MUST put InputFileStream.Length first, because it starts background downloader.
-
-			while (InputFileStream.Length > InputFileStream.WritePosition && !InputFileStream.IsCancelled)
-			{
-				var rate = InputFileStream.WritePosition / (DateTime.Now - startTime).TotalSeconds;
-
-				var estTimeRemaining = (InputFileStream.Length - InputFileStream.WritePosition) / rate;
-
-				if (double.IsNormal(estTimeRemaining))
-					OnDecryptTimeRemaining(TimeSpan.FromSeconds(estTimeRemaining));
-
-				var progressPercent = 100d * InputFileStream.WritePosition / InputFileStream.Length;
-
-				OnDecryptProgressUpdate(
-					new DownloadProgress
-					{
-						ProgressPercentage = progressPercent,
-						BytesReceived = InputFileStream.WritePosition,
-						TotalBytesToReceive = InputFileStream.Length
-					});
-
-				await Task.Delay(200);
-			}
-
-			if (IsCanceled)
-				return false;
-			else
-			{
-				FinalizeDownload();
-				FileUtility.SaferMove(InputFileStream.SaveFilePath, OutputFileName);
-				OnFileCreated(OutputFileName);
-				return true;
-			}
+			var tempFile = GetNewTempFilePath(DownloadOptions.OutputFormat.ToString());
+			FileUtility.SaferMove(InputFileStream.SaveFilePath, tempFile.FilePath);
+			OnTempFileCreated(tempFile);
+			return true;
 		}
 	}
 }

Source/AppScaffolding/AppScaffolding.csproj

@@ -1,11 +1,16 @@
 <?xml version="1.0" encoding="utf-8"?>
 <Project Sdk="Microsoft.NET.Sdk">
   <PropertyGroup>
-    <TargetFramework>net7.0</TargetFramework>
-    <Version>9.2.2.1</Version>
+    <TargetFramework>net10.0</TargetFramework>
+    <Version>13.7.4</Version>
+    <Nullable>enable</Nullable>
   </PropertyGroup>
   <ItemGroup>
-    <PackageReference Include="Octokit" Version="5.0.0" />
+    <PackageReference Include="Octokit" Version="14.0.0" />
+    <!-- Do not remove unused Serilog.Sinks -->
+    <!-- Only File sink is currently used. By user request (June 2024) others packages are included for experimental use. -->
+    <PackageReference Include="Serilog.Sinks.Console" Version="6.1.1" />
+    <PackageReference Include="Serilog.Sinks.File" Version="7.0.0" />
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\ApplicationServices\ApplicationServices.csproj" />
@@ -18,4 +23,4 @@
   <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Release|AnyCPU'">
     <DebugType>embedded</DebugType>
   </PropertyGroup>
-</Project>
+</Project>

Source/AppScaffolding/LibationScaffolding.cs

@@ -1,367 +1,646 @@
-using System;
-using System.Collections.Generic;
-using System.IO;
-using System.Linq;
-using System.Reflection;
 using ApplicationServices;
 using AudibleUtilities;
-using Dinah.Core;
 using Dinah.Core.IO;
 using Dinah.Core.Logging;
 using LibationFileManager;
-using Microsoft.EntityFrameworkCore;
+using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
 using Serilog;
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.IO;
+using System.Linq;
+using System.Reflection;
+using System.Runtime.InteropServices;
 
-namespace AppScaffolding
+namespace AppScaffolding;
+
+public enum ReleaseIdentifier
 {
-	public enum ReleaseIdentifier
+	None,
+	WindowsClassic = OS.Windows | Variety.Classic | Architecture.X64,
+	WindowsAvalonia = OS.Windows | Variety.Chardonnay | Architecture.X64,
+	LinuxAvalonia = OS.Linux | Variety.Chardonnay | Architecture.X64,
+	MacOSAvalonia = OS.MacOS | Variety.Chardonnay | Architecture.X64,
+	LinuxAvalonia_Arm64 = OS.Linux | Variety.Chardonnay | Architecture.Arm64,
+	MacOSAvalonia_Arm64 = OS.MacOS | Variety.Chardonnay | Architecture.Arm64,
+	WindowsAvalonia_Arm64 = OS.Windows | Variety.Chardonnay | Architecture.Arm64,
+}
+
+// I know I'm taking the wine metaphor a bit far by naming this "Variety", but I don't know what else to call it
+[Flags]
+public enum Variety
+{
+	None,
+	Classic = 0x10000,
+	Chardonnay = 0x20000,
+}
+
+public static class LibationScaffolding
+{
+	public const string RepositoryUrl = "ht" + "tps://github.com/rmcrackan/Libation";
+	public const string WebsiteUrl = "ht" + "tps://getlibation.com";
+	public const string DonateUrl = WebsiteUrl + "/donate";
+	public const string RepositoryLatestUrl = "ht" + "tps://github.com/rmcrackan/Libation/releases/latest";
+	/// <summary>Documentation for naming template syntax</summary>
+	public const string NamingTemplatesDocUrl = WebsiteUrl + "/docs/features/naming-templates";
+	public static ReleaseIdentifier ReleaseIdentifier { get; private set; }
+	public static Variety Variety { get; private set; }
+
+	// AppScaffolding
+	private static Assembly? _executingAssembly;
+	private static Assembly ExecutingAssembly
+		=> _executingAssembly ??= Assembly.GetExecutingAssembly();
+
+	// LibationWinForms or LibationCli
+	private static Assembly? _entryAssembly;
+	private static Assembly? EntryAssembly
+		=> _entryAssembly ??= Assembly.GetEntryAssembly();
+
+	// previously: System.Reflection.Assembly.GetExecutingAssembly().GetName().Version;
+	private static Version? _buildVersion;
+	public static Version? BuildVersion
+		=> _buildVersion ??= new[] { ExecutingAssembly.GetName(), EntryAssembly?.GetName() }.Max(a => a?.Version);
+
+	/// <summary>Run migrations before loading Configuration for the first time. Then load and return Configuration</summary>
+	public static Configuration RunPreConfigMigrations()
 	{
-		None,
-		WindowsClassic,
-		WindowsAvalonia,
-		LinuxAvalonia,
-		MacOSAvalonia
+		// must occur before access to Configuration instance
+		// // outdated. kept here as an example of what belongs in this area
+		// // Migrations.migrate_to_v5_2_0__pre_config();
+
+		InstallFolderUnblock.TryUnblockProcessDirectoryIfWindows();
+
+		Configuration.SetLibationVersion(BuildVersion);
+
+		//***********************************************//
+		//                                               //
+		//   do not use Configuration before this line   //
+		//                                               //
+		//***********************************************//
+		return Configuration.Instance;
 	}
 
-	// I know I'm taking the wine metaphor a bit far by naming this "Variety", but I don't know what else to call it
-	public enum VarietyType { None, Classic, Chardonnay }
-
-	public static class LibationScaffolding
+	/// <summary>most migrations go in here</summary>
+	public static void RunPostConfigMigrations(Configuration config, bool ephemeralSettings = false)
 	{
-		public const string RepositoryUrl = "ht" + "tps://github.com/rmcrackan/Libation";
-		public const string WebsiteUrl = "ht" + "tps://getlibation.com";
-		public const string RepositoryLatestUrl = "ht" + "tps://github.com/rmcrackan/Libation/releases/latest";
-		public static ReleaseIdentifier ReleaseIdentifier { get; private set; }
-		public static VarietyType Variety
-			=> ReleaseIdentifier == ReleaseIdentifier.WindowsClassic ? VarietyType.Classic
-			: ReleaseIdentifier.In(ReleaseIdentifier.WindowsAvalonia, ReleaseIdentifier.LinuxAvalonia, ReleaseIdentifier.MacOSAvalonia) ? VarietyType.Chardonnay
-			: VarietyType.None;
-
-		public static void SetReleaseIdentifier(ReleaseIdentifier releaseID)
-			=> ReleaseIdentifier = releaseID;
-
-		// AppScaffolding
-		private static Assembly _executingAssembly;
-		private static Assembly ExecutingAssembly
-			=> _executingAssembly ??= Assembly.GetExecutingAssembly();
-
-		// LibationWinForms or LibationCli
-		private static Assembly _entryAssembly;
-		private static Assembly EntryAssembly
-			=> _entryAssembly ??= Assembly.GetEntryAssembly();
-
-		// previously: System.Reflection.Assembly.GetExecutingAssembly().GetName().Version;
-		private static Version _buildVersion;
-		public static Version BuildVersion
-			=> _buildVersion
-			??= new[] { ExecutingAssembly.GetName(), EntryAssembly.GetName() }
-			.Max(a => a.Version);
-
-        /// <summary>Run migrations before loading Configuration for the first time. Then load and return Configuration</summary>
-        public static Configuration RunPreConfigMigrations()
+		if (ephemeralSettings)
 		{
-			// must occur before access to Configuration instance
-			// // outdated. kept here as an example of what belongs in this area
-			// // Migrations.migrate_to_v5_2_0__pre_config();
-
-			//***********************************************//
-			//                                               //
-			//   do not use Configuration before this line   //
-			//                                               //
-			//***********************************************//
-			return Configuration.Instance;
+			var settings = JObject.Parse(File.ReadAllText(config.LibationFiles.SettingsFilePath));
+			config.LoadEphemeralSettings(settings);
 		}
-
-		/// <summary>most migrations go in here</summary>
-		public static void RunPostConfigMigrations(Configuration config)
+		else
 		{
-			AudibleApiStorage.EnsureAccountsSettingsFileExists();
-
-			//
-			// migrations go below here
-			//
-
-			Migrations.migrate_to_v6_6_9(config);
+			config.LoadPersistentSettings(config.LibationFiles.SettingsFilePath);
 		}
+		DeleteOpenSqliteFiles(config);
+		AudibleApiStorage.EnsureAccountsSettingsFileExists();
+		IdentityTokenStorageWiring.Apply(config);
 
-		/// <summary>Initialize logging. Wire-up events. Run after migration</summary>
-		public static void RunPostMigrationScaffolding(Configuration config)
-		{
-			ensureSerilogConfig(config);
-			configureLogging(config);
-			logStartupState(config);
+		//
+		// migrations go below here
+		//
 
-			// all else should occur after logging
+		Migrations.migrate_to_v6_6_9(config);
+		Migrations.migrate_to_v11_5_0(config);
+		Migrations.migrate_to_v11_6_5(config);
+		Migrations.migrate_to_v12_0_1(config);
+	}
 
-			wireUpSystemEvents(config);
-		}
-
-		private static void ensureSerilogConfig(Configuration config)
-		{
-			if (config.GetObject("Serilog") is not null)
-				return;
-
-			var serilogObj = new JObject
-			{
-				{ "MinimumLevel", "Information" },
-				{ "WriteTo", new JArray
-					{
-						// new JObject { {"Name", "Console" } }, // this has caused more problems than it's solved
-						new JObject
-						{
-							{ "Name", "File" },
-							{ "Args",
-								new JObject
-								{
-									// for this sink to work, a path must be provided. we override this below
-									{ "path", Path.Combine(config.LibationFiles, "_Log.log") },
-									{ "rollingInterval", "Month" },
-									// Serilog template formatting examples
-									// - default:                    "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}"
-									//   output example:             2019-11-26 08:48:40.224 -05:00 [DBG] Begin Libation
-									// - with class and method info: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] (at {Caller}) {Message:lj}{NewLine}{Exception}";
-									//   output example:             2019-11-26 08:48:40.224 -05:00 [DBG] (at LibationWinForms.Program.init()) Begin Libation
-									// {Properties:j} needed for expanded exception logging
-									{ "outputTemplate", "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] (at {Caller}) {Message:lj}{NewLine}{Exception} {Properties:j}" }
-								}
-							}
-						}
-					}
-				},
-				// better exception logging with: Serilog.Exceptions library -- WithExceptionDetails
-				{ "Using", new JArray{ "Dinah.Core", "Serilog.Exceptions" } }, // dll's name, NOT namespace
-				{ "Enrich", new JArray{ "WithCaller", "WithExceptionDetails" } },
-			};
-			config.SetNonString(serilogObj, "Serilog");
-		}
-
-		// to restore original: Console.SetOut(origOut);
-		private static TextWriter origOut { get; } = Console.Out;
-
-		private static void configureLogging(Configuration config)
-		{
-			config.ConfigureLogging();
-
-			// capture most Console.WriteLine() and write to serilog. See below tests for details.
-			// Some dependencies print helpful info via Console.WriteLine. We'd like to log it.
-			//
-			// If Serilog also writes to Console, this might be asking for trouble. ie: infinite loops.
-			// To use that way, SerilogTextWriter needs to be more robust and tested. Esp the Write() methods.
-			// However, empirical testing so far has shown no issues.
-			Console.SetOut(new MultiTextWriter(origOut, new SerilogTextWriter()));
-
-            #region Console => Serilog tests
-            /*
-			// all below apply to "Console." and "Console.Out."
-
-			// captured
-			Console.WriteLine("str");
-			Console.WriteLine(new { a = "anon" });
-			Console.WriteLine("{0}", "format");
-			Console.WriteLine("{0}{1}", "zero|", "one");
-			Console.WriteLine("{0}{1}{2}", "zero|", "one|", "two");
-			Console.WriteLine("{0}", new object[] { "arr" });
-
-			// not captured
-			Console.WriteLine();
-			Console.WriteLine(true);
-			Console.WriteLine('0');
-			Console.WriteLine(1);
-			Console.WriteLine(2m);
-			Console.WriteLine(3f);
-			Console.WriteLine(4d);
-			Console.WriteLine(5L);
-			Console.WriteLine((uint)6);
-			Console.WriteLine((ulong)7);
-
-			Console.Write("str");
-			Console.Write(true);
-			Console.Write('0');
-			Console.Write(1);
-			Console.Write(2m);
-			Console.Write(3f);
-			Console.Write(4d);
-			Console.Write(5L);
-			Console.Write((uint)6);
-			Console.Write((ulong)7);
-			Console.Write(new { a = "anon" });
-			Console.Write("{0}", "format");
-			Console.Write("{0}{1}", "zero|", "one");
-			Console.Write("{0}{1}{2}", "zero|", "one|", "two");
-			Console.Write("{0}", new object[] { "arr" });
-			*/
-            #endregion
-
-            // .Here() captures debug info via System.Runtime.CompilerServices attributes. Warning: expensive
-            //var withLineNumbers_outputTemplate = "[{Timestamp:HH:mm:ss} {Level}] {SourceContext}{NewLine}{Message}{NewLine}in method {MemberName} at {FilePath}:{LineNumber}{NewLine}{Exception}{NewLine}";
-            //Log.Logger.Here().Debug("Begin Libation. Debug with line numbers");
-        }
-
-		private static void logStartupState(Configuration config)
-		{
-#if DEBUG
-			var mode = "Debug";
-#else
-			var mode = "Release";
-#endif
-			if (System.Diagnostics.Debugger.IsAttached)
-				mode += " (Debugger attached)";
-
-			// begin logging session with a form feed
-			Log.Logger.Information("\r\n\f");
-			Log.Logger.Information("Begin. {@DebugInfo}", new
-			{
-				AppName = EntryAssembly.GetName().Name,
-				Version = BuildVersion.ToString(),
-				ReleaseIdentifier,
-				Configuration.OS,
-                InteropFactory.InteropFunctionsType,
-                Mode = mode,
-				LogLevel_Verbose_Enabled = Log.Logger.IsVerboseEnabled(),
-				LogLevel_Debug_Enabled = Log.Logger.IsDebugEnabled(),
-				LogLevel_Information_Enabled = Log.Logger.IsInformationEnabled(),
-				LogLevel_Warning_Enabled = Log.Logger.IsWarningEnabled(),
-				LogLevel_Error_Enabled = Log.Logger.IsErrorEnabled(),
-				LogLevel_Fatal_Enabled = Log.Logger.IsFatalEnabled(),
-
-                config.BetaOptIn,
-                config.UseCoverAsFolderIcon,
-                config.LibationFiles,
-				AudibleFileStorage.BooksDirectory,
-
-				config.InProgress,
-
-				AudibleFileStorage.DownloadsInProgressDirectory,
-				DownloadsInProgressFiles = FileManager.FileUtility.SaferEnumerateFiles(AudibleFileStorage.DownloadsInProgressDirectory).Count(),
-
-				AudibleFileStorage.DecryptInProgressDirectory,
-				DecryptInProgressFiles = FileManager.FileUtility.SaferEnumerateFiles(AudibleFileStorage.DecryptInProgressDirectory).Count(),
-			});
-
-            if (InteropFactory.InteropFunctionsType is null)
-                Serilog.Log.Logger.Warning("WARNING: OSInteropProxy.InteropFunctionsType is null");
-        }
-
-        private static void wireUpSystemEvents(Configuration configuration)
-		{
-			LibraryCommands.LibrarySizeChanged += (_, __) => SearchEngineCommands.FullReIndex();
-			LibraryCommands.BookUserDefinedItemCommitted += (_, books) => SearchEngineCommands.UpdateBooks(books);
-		}
-
-		public static UpgradeProperties GetLatestRelease()
-		{
-			// timed out
-			(var latest, var zip) = getLatestRelease(TimeSpan.FromSeconds(10));
-
-			if (latest is null || zip is null)
-				return null;
-
-			var latestVersionString = latest.TagName.Trim('v');
-			if (!Version.TryParse(latestVersionString, out var latestRelease))
-				return null;
-
-			// we're up to date
-			if (latestRelease <= BuildVersion)
-				return null;
-
-			// we have an update
-
-			var zipUrl = zip?.BrowserDownloadUrl;
-
-			Log.Logger.Information("Update available: {@DebugInfo}", new
-			{
-				latestRelease = latestRelease.ToString(),
-				latest.HtmlUrl,
-				zipUrl
-			});
-
-			return new(zipUrl, latest.HtmlUrl, zip.Name, latestRelease, latest.Body);
-		}
-		private static (Octokit.Release, Octokit.ReleaseAsset) getLatestRelease(TimeSpan timeout)
+	/// <summary>
+	/// Delete shared memory and write-ahead log SQLite database files which may prevent access to the database.
+	/// These file may or may not cause libation to hang on CreateContext,
+	/// so try our luck by swallowing any exceptions and continuing.
+	/// </summary>
+	private static void DeleteOpenSqliteFiles(Configuration config)
+	{
+		var walFile = SqliteStorage.DatabasePath + "-wal";
+		var shmFile = SqliteStorage.DatabasePath + "-shm";
+		if (File.Exists(walFile))
 		{
 			try
 			{
-				var task = getLatestRelease();
-				if (task.Wait(timeout))
-					return task.Result;
-
-				Log.Logger.Information("Timed out");
+				FileManager.FileUtility.SaferDelete(walFile);
 			}
-			catch (AggregateException aggEx)
+			catch (Exception ex)
 			{
-				Log.Logger.Error(aggEx, "Checking for new version too often");
+				Log.Logger.Warning(ex, "Could not delete SQLite WAL file: {WalFile}", walFile);
 			}
-			return (null, null);
 		}
-		private static async System.Threading.Tasks.Task<(Octokit.Release, Octokit.ReleaseAsset)> getLatestRelease()
+		if (File.Exists(shmFile))
 		{
-			var ownerAccount = "rmcrackan";
-			var repoName = "Libation";
-
-			var gitHubClient = new Octokit.GitHubClient(new Octokit.ProductHeaderValue(repoName));
-
-			//Download the release index
-			var bts = await gitHubClient.Repository.Content.GetRawContent(ownerAccount, repoName, ".releaseindex.json");
-			var releaseIndex = JObject.Parse(System.Text.Encoding.ASCII.GetString(bts));
-			var regexPattern = releaseIndex.Value<string>(ReleaseIdentifier.ToString());
-
-			// https://octokitnet.readthedocs.io/en/latest/releases/
-			var releases = await gitHubClient.Repository.Release.GetAll(ownerAccount, repoName);
-
-			var regex = new System.Text.RegularExpressions.Regex(regexPattern, System.Text.RegularExpressions.RegexOptions.IgnoreCase);
-			var latestRelease = releases.FirstOrDefault(r => !r.Draft && !r.Prerelease && r.Assets.Any(a => regex.IsMatch(a.Name)));
-			return (latestRelease, latestRelease?.Assets?.FirstOrDefault(a => regex.IsMatch(a.Name)));
+			try
+			{
+				FileManager.FileUtility.SaferDelete(shmFile);
+			}
+			catch (Exception ex)
+			{
+				Log.Logger.Warning(ex, "Could not delete SQLite SHM file: {ShmFile}", shmFile);
+			}
 		}
 	}
+	static bool migrationsRun = false;
 
-	internal static class Migrations
+	/// <summary>Initialize logging. Wire-up events. Run after migration</summary>
+	public static void RunPostMigrationScaffolding(Variety variety, Configuration config)
 	{
-		public static void migrate_to_v6_6_9(Configuration config)
+		if (System.Threading.Interlocked.CompareExchange(ref migrationsRun, true, false))
+			return;
+		Variety = Enum.IsDefined(variety) ? variety : Variety.None;
+
+		var releaseID = (ReleaseIdentifier)((int)variety | (int)Configuration.OS | (int)RuntimeInformation.ProcessArchitecture);
+
+		ReleaseIdentifier = Enum.IsDefined(releaseID) ? releaseID : ReleaseIdentifier.None;
+
+		ensureSerilogConfig(config);
+		configureLogging(config);
+		logStartupState(config);
+
+		// all else should occur after logging
+
+		wireUpSystemEvents(config);
+	}
+
+	private static void ensureSerilogConfig(Configuration config)
+	{
+		if (config.GetObject("Serilog") is JObject serilog)
 		{
-			var writeToPath = $"Serilog.WriteTo";
-
-			// remove WriteTo[].Name == Console
+			bool fileChanged = false;
+			if (serilog.SelectToken("$.WriteTo[?(@.Name == 'ZipFile')]", false) is JObject zipFileSink)
 			{
-				if (UNSAFE_MigrationHelper.Settings_TryGetArrayLength(writeToPath, out var length1))
-				{
-					for (var i = length1 - 1; i >= 0; i--)
-					{
-						var exists = UNSAFE_MigrationHelper.Settings_TryGetFromJsonPath($"{writeToPath}[{i}].Name", out var value);
-
-						if (exists && value == "Console")
-							UNSAFE_MigrationHelper.Settings_RemoveFromArray(writeToPath, i);
-					}
-				}
+				zipFileSink["Name"] = "File";
+				fileChanged = true;
+			}
+			var hooks = typeof(FileSinkHook).AssemblyQualifiedName;
+			if (serilog.SelectToken("$.WriteTo[?(@.Name == 'File')].Args", false) is JObject fileSinkArgs
+				&& fileSinkArgs["hooks"]?.Value<string>() != hooks)
+			{
+				fileSinkArgs["hooks"] = hooks;
+				fileChanged = true;
 			}
 
-			// add Serilog.Exceptions -- WithExceptionDetails
-			{
-				// outputTemplate should contain "{Properties:j}"
+			if (fileChanged)
+				config.SetNonString(serilog.DeepClone(), "Serilog");
+			return;
+		}
+
+		var serilogObj = new JObject
+		{
+			{ "MinimumLevel", "Information" },
+			{ "WriteTo", new JArray
 				{
-					// re-calculate. previous loop may have changed the length
-					if (UNSAFE_MigrationHelper.Settings_TryGetArrayLength(writeToPath, out var length2))
+					// ABOUT SINKS
+					// Only File sink is currently used. By user request (June 2024) others packages are included for experimental use.
+
+					// new JObject { {"Name", "Console" } }, // this has caused more problems than it's solved
+					new JObject
 					{
-						var propertyName = "outputTemplate";
-						for (var i = 0; i < length2; i++)
-						{
-							var jsonPath = $"{writeToPath}[{i}].Args";
-							var exists = UNSAFE_MigrationHelper.Settings_TryGetFromJsonPath($"{jsonPath}.{propertyName}", out var value);
-
-							var newValue = "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] (at {Caller}) {Message:lj}{NewLine}{Exception} {Properties:j}";
-
-							if (exists && value != newValue)
-								UNSAFE_MigrationHelper.Settings_SetWithJsonPath(jsonPath, propertyName, newValue);
+						{ "Name", "File" },
+						{ "Args",
+							new JObject
+							{
+								// for this sink to work, a path must be provided. we override this below
+								{ "path", Path.Combine(config.LibationFiles.Location, "Log.log") },
+								{ "rollingInterval", "Month" },
+								// Serilog template formatting examples
+								// - default:                    "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}"
+								//   output example:             2019-11-26 08:48:40.224 -05:00 [DBG] Begin Libation
+								// - with class and method info: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] (at {Caller}) {Message:lj}{NewLine}{Exception}";
+								//   output example:             2019-11-26 08:48:40.224 -05:00 [DBG] (at LibationWinForms.Program.init()) Begin Libation
+								// {Properties:j} needed for expanded exception logging
+								{ "outputTemplate", "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] (at {Caller}) {Message:lj}{NewLine}{Exception} {Properties:j}" },
+								{ "hooks", typeof(FileSinkHook).AssemblyQualifiedName }, // for FileSinkHook
+							}
 						}
 					}
 				}
+			},
+			// better exception logging with: Serilog.Exceptions library -- WithExceptionDetails
+			{ "Using", new JArray{ "Dinah.Core", "Serilog.Exceptions" } }, // dll's name, NOT namespace
+			{ "Enrich", new JArray{ "WithCaller", "WithExceptionDetails" } },
+		};
+		config.SetNonString(serilogObj, "Serilog");
+	}
 
-				// Serilog.Using must include "Serilog.Exceptions"
-				UNSAFE_MigrationHelper.Settings_AddUniqueToArray("Serilog.Using", "Serilog.Exceptions");
+	// to restore original: Console.SetOut(origOut);
+	private static TextWriter origOut { get; } = Console.Out;
 
-				// Serilog.Enrich must include "WithExceptionDetails"
-				UNSAFE_MigrationHelper.Settings_AddUniqueToArray("Serilog.Enrich", "WithExceptionDetails");
+	private static void configureLogging(Configuration config)
+	{
+		config.ConfigureLogging();
+		Log.Information(
+			"Paths: LibationFiles={LibationFiles} AppsettingsJson={AppsettingsJson} SQLiteDb={SqliteDb}",
+			config.LibationFiles.Location,
+			config.LibationFiles.AppsettingsJsonFile ?? "(null, LIBATION_FILES_DIR may be set)",
+			Path.Combine(config.LibationFiles.Location, "LibationContext.db"));
+		DbContexts.TryEmitPendingInitialDatabaseStatistics();
+
+		// capture most Console.WriteLine() and write to serilog. See below tests for details.
+		// Some dependencies print helpful info via Console.WriteLine. We'd like to log it.
+		//
+		// If Serilog also writes to Console, this might be asking for trouble. ie: infinite loops.
+		// To use that way, SerilogTextWriter needs to be more robust and tested. Esp the Write() methods.
+		// However, empirical testing so far has shown no issues.
+		Console.SetOut(new MultiTextWriter(origOut, new SerilogTextWriter()));
+
+		#region Console => Serilog tests
+		/*
+	// all below apply to "Console." and "Console.Out."
+
+	// captured
+	Console.WriteLine("str");
+	Console.WriteLine(new { a = "anon" });
+	Console.WriteLine("{0}", "format");
+	Console.WriteLine("{0}{1}", "zero|", "one");
+	Console.WriteLine("{0}{1}{2}", "zero|", "one|", "two");
+	Console.WriteLine("{0}", new object[] { "arr" });
+
+	// not captured
+	Console.WriteLine();
+	Console.WriteLine(true);
+	Console.WriteLine('0');
+	Console.WriteLine(1);
+	Console.WriteLine(2m);
+	Console.WriteLine(3f);
+	Console.WriteLine(4d);
+	Console.WriteLine(5L);
+	Console.WriteLine((uint)6);
+	Console.WriteLine((ulong)7);
+
+	Console.Write("str");
+	Console.Write(true);
+	Console.Write('0');
+	Console.Write(1);
+	Console.Write(2m);
+	Console.Write(3f);
+	Console.Write(4d);
+	Console.Write(5L);
+	Console.Write((uint)6);
+	Console.Write((ulong)7);
+	Console.Write(new { a = "anon" });
+	Console.Write("{0}", "format");
+	Console.Write("{0}{1}", "zero|", "one");
+	Console.Write("{0}{1}{2}", "zero|", "one|", "two");
+	Console.Write("{0}", new object[] { "arr" });
+	*/
+		#endregion
+
+		// .Here() captures debug info via System.Runtime.CompilerServices attributes. Warning: expensive
+		//var withLineNumbers_outputTemplate = "[{Timestamp:HH:mm:ss} {Level}] {SourceContext}{NewLine}{Message}{NewLine}in method {MemberName} at {FilePath}:{LineNumber}{NewLine}{Exception}{NewLine}";
+		//Log.Logger.Here().Debug("Begin Libation. Debug with line numbers");
+	}
+
+	private static void logStartupState(Configuration config)
+	{
+#if DEBUG
+		var mode = "Debug";
+#else
+		var mode = "Release";
+#endif
+		if (Debugger.IsAttached)
+			mode += " (Debugger attached)";
+
+		// begin logging session with a form feed
+		Log.Logger.Information("\r\n\f");
+
+		static int fileCount(FileManager.LongPath? longPath)
+		{
+			if (longPath is null)
+				return -1;
+			try { return FileManager.FileUtility.SaferEnumerateFiles(longPath).Count(); }
+			catch { return -1; }
+		}
+
+		Log.Logger.Information("Begin. {@DebugInfo}", new
+		{
+			AppName = EntryAssembly?.GetName().Name,
+			Version = BuildVersion?.ToString(),
+			ReleaseIdentifier,
+			Configuration.OS,
+			Environment.OSVersion,
+			InteropFactory.InteropFunctionsType,
+			Mode = mode,
+			LogLevel_Verbose_Enabled = Log.Logger.IsVerboseEnabled(),
+			LogLevel_Debug_Enabled = Log.Logger.IsDebugEnabled(),
+			LogLevel_Information_Enabled = Log.Logger.IsInformationEnabled(),
+			LogLevel_Warning_Enabled = Log.Logger.IsWarningEnabled(),
+			LogLevel_Error_Enabled = Log.Logger.IsErrorEnabled(),
+			LogLevel_Fatal_Enabled = Log.Logger.IsFatalEnabled(),
+
+			config.AutoScan,
+			config.BetaOptIn,
+			config.UseCoverAsFolderIcon,
+			config.LibationFiles,
+			AudibleFileStorage.BooksDirectory,
+
+			config.InProgress,
+
+			AudibleFileStorage.DownloadsInProgressDirectory,
+			DownloadsInProgressFiles = fileCount(AudibleFileStorage.DownloadsInProgressDirectory),
+
+			AudibleFileStorage.DecryptInProgressDirectory,
+			DecryptInProgressFiles = fileCount(AudibleFileStorage.DecryptInProgressDirectory),
+
+			disableIPv6 = AppContext.TryGetSwitch("System.Net.DisableIPv6", out bool disableIPv6Value),
+		});
+
+		if (InteropFactory.InteropFunctionsType is null)
+			Serilog.Log.Logger.Warning("WARNING: OSInteropProxy.InteropFunctionsType is null");
+	}
+
+	private static void wireUpSystemEvents(Configuration configuration)
+	{
+		LibraryCommands.LibrarySizeChanged += (_, libraryBooks)
+			=> SearchEngineCommands.FullReIndex(libraryBooks);
+
+		LibraryCommands.BookUserDefinedItemCommitted += (_, books)
+			=> SearchEngineCommands.UpdateBooks(books);
+	}
+
+	public static VersionCheckResult GetLatestRelease()
+	{
+		var (version, latest, zip, checkSucceeded, definitive) = getLatestRelease(TimeSpan.FromSeconds(10));
+
+		if (!checkSucceeded || !definitive)
+			return new VersionCheckResult(VersionCheckOutcome.UnableToDetermine);
+
+		if (version is null || latest is null || zip is null)
+			return new VersionCheckResult(VersionCheckOutcome.UpToDate);
+
+		// we have an update
+		var zipUrl = zip.BrowserDownloadUrl;
+
+		Log.Logger.Information("Update available: {@DebugInfo}", new
+		{
+			latestRelease = version.ToString(),
+			latest.HtmlUrl,
+			zipUrl
+		});
+
+		return new VersionCheckResult(VersionCheckOutcome.UpdateAvailable, new UpgradeProperties(zipUrl, latest.HtmlUrl, zip.Name, version, latest.Body));
+	}
+	private static (Version? releaseVersion, Octokit.Release?, Octokit.ReleaseAsset? zip, bool checkSucceeded, bool definitive) getLatestRelease(TimeSpan timeout)
+	{
+		try
+		{
+			var task = getLatestReleaseAsync();
+			if (task.Wait(timeout))
+				return (task.Result.releaseVersion, task.Result.latest, task.Result.zip, true, task.Result.definitive);
+
+			Log.Logger.Information("Version check timed out");
+		}
+		catch (AggregateException aggEx)
+		{
+			var inner = aggEx.InnerException;
+			if (inner?.Message?.Contains("API rate limit", StringComparison.OrdinalIgnoreCase) == true)
+				Log.Logger.Error(aggEx, "Checking for new version too often");
+			else
+				Log.Logger.Error(aggEx, "Version check failed. Agg exception");
+		}
+		catch (Exception ex)
+		{
+			// different text to make it easier to identify in logs, vs the AggregateException case above
+			Log.Logger.Error(ex, "Version check failed. General exception");
+		}
+		return (null, null, null, false, false);
+	}
+	private static async System.Threading.Tasks.Task<(Version? releaseVersion, Octokit.Release? latest, Octokit.ReleaseAsset? zip, bool definitive)> getLatestReleaseAsync()
+	{
+		const string ownerAccount = "rmcrackan";
+		const string repoName = "Libation";
+
+		var gitHubClient = new Octokit.GitHubClient(new Octokit.ProductHeaderValue(repoName));
+
+		//https://docs.github.com/en/rest/releases/releases?apiVersion=2022-11-28#get-the-latest-release
+		var latestRelease = await gitHubClient.Repository.Release.GetLatest(ownerAccount, repoName);
+
+		//Ensure that latest release is greater than the current version
+		var latestVersionString = latestRelease.TagName.Trim('v');
+		if (!Version.TryParse(latestVersionString, out var releaseVersion) || releaseVersion <= BuildVersion)
+			return (null, null, null, true);
+
+		//Download the release index
+		var bts = await gitHubClient.Repository.Content.GetRawContent(ownerAccount, repoName, ".releaseindex.json");
+		var releaseIndex = JObject.Parse(System.Text.Encoding.ASCII.GetString(bts));
+
+		string? regexPattern;
+		string? releaseIdString = null;
+
+		try
+		{
+			releaseIdString = InteropFactory.Create().ReleaseIdString;
+			regexPattern = releaseIndex.Value<string>(releaseIdString);
+		}
+		catch
+		{
+			regexPattern = null;
+		}
+		if (string.IsNullOrEmpty(regexPattern) && Configuration.IsLinux)
+		{
+			var baseId = ReleaseIdentifier.ToString();
+			regexPattern = releaseIndex.Value<string>($"{baseId}_RPM")
+				?? releaseIndex.Value<string>($"{baseId}_DEB");
+			releaseIdString ??= $"{baseId}_RPM";
+		}
+		if (string.IsNullOrEmpty(regexPattern))
+			regexPattern = releaseIndex.Value<string>(ReleaseIdentifier.ToString());
+		if (string.IsNullOrEmpty(regexPattern))
+		{
+			Log.Logger.Warning("Release index has no entry for this platform (ReleaseIdentifier: {ReleaseId}, ReleaseIdString: {ReleaseIdString}). Version check inconclusive.", ReleaseIdentifier, releaseIdString);
+			return (null, null, null, false);
+		}
+
+		var regex = new System.Text.RegularExpressions.Regex(regexPattern, System.Text.RegularExpressions.RegexOptions.IgnoreCase);
+		var zip = latestRelease?.Assets?.FirstOrDefault(a => regex.IsMatch(a.Name));
+
+		if (zip is not null && !string.IsNullOrEmpty(releaseIdString))
+			Log.Logger.Information("Update asset matched using {ReleaseIdString}: {AssetName}", releaseIdString, zip.Name);
+
+		return (releaseVersion, latestRelease, zip, true);
+	}
+}
+
+internal static class Migrations
+{
+	public static void migrate_to_v6_6_9(Configuration config)
+	{
+		var writeToPath = $"Serilog.WriteTo";
+
+		// remove WriteTo[].Name == Console
+		{
+			if (UNSAFE_MigrationHelper.Settings_TryGetArrayLength(writeToPath, out var length1))
+			{
+				for (var i = length1 - 1; i >= 0; i--)
+				{
+					var exists = UNSAFE_MigrationHelper.Settings_TryGetFromJsonPath($"{writeToPath}[{i}].Name", out var value);
+
+					if (exists && value == "Console")
+						UNSAFE_MigrationHelper.Settings_RemoveFromArray(writeToPath, i);
+				}
 			}
 		}
+
+		// add Serilog.Exceptions -- WithExceptionDetails
+		{
+			// outputTemplate should contain "{Properties:j}"
+			{
+				// re-calculate. previous loop may have changed the length
+				if (UNSAFE_MigrationHelper.Settings_TryGetArrayLength(writeToPath, out var length2))
+				{
+					var propertyName = "outputTemplate";
+					for (var i = 0; i < length2; i++)
+					{
+						var jsonPath = $"{writeToPath}[{i}].Args";
+						var exists = UNSAFE_MigrationHelper.Settings_TryGetFromJsonPath($"{jsonPath}.{propertyName}", out var value);
+
+						var newValue = "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] (at {Caller}) {Message:lj}{NewLine}{Exception} {Properties:j}";
+
+						if (exists && value != newValue)
+							UNSAFE_MigrationHelper.Settings_SetWithJsonPath(jsonPath, propertyName, newValue);
+					}
+				}
+			}
+
+			// Serilog.Using must include "Serilog.Exceptions"
+			UNSAFE_MigrationHelper.Settings_AddUniqueToArray("Serilog.Using", "Serilog.Exceptions");
+
+			// Serilog.Enrich must include "WithExceptionDetails"
+			UNSAFE_MigrationHelper.Settings_AddUniqueToArray("Serilog.Enrich", "WithExceptionDetails");
+		}
+	}
+
+	class FilterState_6_6_9
+	{
+		public bool UseDefault { get; set; }
+		public List<string> Filters { get; set; } = [];
+	}
+
+	public static void migrate_to_v12_0_1(Configuration config)
+	{
+		//Migrate from version 1 file cache to the dictionary-based version 2 cache
+		const string FILENAME_V1 = "FileLocations.json";
+		const string FILENAME_V2 = "FileLocationsV2.json";
+
+		var jsonFileV1 = Path.Combine(Configuration.Instance.LibationFiles.Location, FILENAME_V1);
+		var jsonFileV2 = Path.Combine(Configuration.Instance.LibationFiles.Location, FILENAME_V2);
+
+		if (!File.Exists(jsonFileV2) && File.Exists(jsonFileV1))
+		{
+			try
+			{
+				//FilePathCache loads the cache in its static constructor,
+				//so perform migration without using FilePathCache.CacheEntry
+				if (JArray.Parse(File.ReadAllText(jsonFileV1)) is not JArray v1Cache || v1Cache.Count == 0)
+					return;
+
+				Dictionary<string, JArray> cache = [];
+
+				//Convert to c# objects to speed up searching by ID inside the iterator 
+				var allItems
+					= v1Cache
+					.Select(i => new
+					{
+						Id = i["Id"]?.Value<string>(),
+						Path = i["Path"]?["Path"]?.Value<string>()
+					}).Where(i => i.Id != null)
+					.ToArray();
+
+				foreach (var id in allItems.Select(i => i.Id).OfType<string>().Distinct())
+				{
+					//Use this opportunity to purge non-existent files and re-classify file types
+					//(due to *.aax files previously not being classified as FileType.AAXC)
+					var items = allItems
+						.Where(i => i.Id == id && File.Exists(i.Path))
+						.Select(i => new JObject
+						{
+							{ "Id", i.Id },
+							{ "FileType", (int)FileTypes.GetFileTypeFromPath(i.Path!) },
+							{ "Path", new JObject{ { "Path", i.Path } } }
+						})
+						.ToArray();
+
+					if (items.Length == 0)
+						continue;
+
+					cache[id] = new JArray(items);
+				}
+
+				var cacheJson = new JObject { { "Dictionary", JObject.FromObject(cache) } };
+				var cacheFileText = cacheJson.ToString(Formatting.Indented);
+
+				void migrate()
+				{
+					File.WriteAllText(jsonFileV2, cacheFileText);
+					File.Delete(jsonFileV1);
+				}
+
+				try { migrate(); }
+				catch (IOException)
+				{
+					try { migrate(); }
+					catch (IOException)
+					{
+						migrate();
+					}
+				}
+			}
+			catch { /* eat */ }
+		}
+	}
+
+	public static void migrate_to_v11_6_5(Configuration config)
+	{
+		//Settings migration for unsupported sample rates (#1116)
+		if (config.MaxSampleRate < AAXClean.SampleRate.Hz_8000)
+			config.MaxSampleRate = AAXClean.SampleRate.Hz_8000;
+		else if (config.MaxSampleRate > AAXClean.SampleRate.Hz_48000)
+			config.MaxSampleRate = AAXClean.SampleRate.Hz_48000;
+	}
+
+	public static void migrate_to_v11_5_0(Configuration config)
+	{
+		// Read file, but convert old format to new (with Name field) as necessary.
+		if (!File.Exists(QuickFilters.JsonFile))
+		{
+			QuickFilters.InMemoryState = new();
+			return;
+		}
+
+		try
+		{
+			if (JsonConvert.DeserializeObject<QuickFilters.FilterState>(File.ReadAllText(QuickFilters.JsonFile))
+				is QuickFilters.FilterState inMemState)
+			{
+				QuickFilters.InMemoryState = inMemState;
+				return;
+			}
+		}
+		catch
+		{
+			// Eat
+		}
+
+		try
+		{
+			if (JsonConvert.DeserializeObject<FilterState_6_6_9>(File.ReadAllText(QuickFilters.JsonFile))
+				is FilterState_6_6_9 inMemState)
+			{
+                // Copy old structure to new.
+                QuickFilters.InMemoryState = new()
+                {
+                    UseDefault = inMemState.UseDefault
+                };
+                foreach (var oldFilter in inMemState.Filters)
+					QuickFilters.InMemoryState.Filters.Add(new QuickFilters.NamedFilter(oldFilter, null));
+
+				return;
+			}
+			Debug.Assert(false, "Should not get here, QuickFilters.json deserialization issue");
+		}
+		catch
+		{
+			// Eat
+		}
 	}
 }

Source/AppScaffolding/OSConfigBase.cs

@@ -1,29 +0,0 @@
-using System;
-
-namespace AppScaffolding
-{
-    public abstract class OSConfigBase
-    {
-        public abstract Type InteropFunctionsType { get; }
-        public virtual Type[] ReferencedTypes { get; } = new Type[0];
-
-        public void Run()
-        {
-            //Each of these types belongs to a different windows-only assembly that's needed by
-            //the WinInterop methods. By referencing these types in main we force the runtime to
-            //load their assemblies before execution reaches inside main. This allows the calling
-            //process to find these assemblies in its module list.
-            _ = ReferencedTypes;
-            _ = InteropFunctionsType;
-
-            //Wait for the calling process to be ready to read the WriteLine()
-            Console.ReadLine();
-
-            // Signal the calling process that execution has reached inside main, and that all referenced assemblies have been loaded.
-            Console.WriteLine();
-
-            // Wait for the calling process to finish reading the process module list, then exit.
-            Console.ReadLine();
-        }
-    }
-}

Source/AppScaffolding/UNSAFE_MigrationHelper.cs

@@ -1,273 +1,267 @@
-using System;
-using System.Collections.Generic;
-using System.IO;
-using System.Linq;
-using Dinah.Core;
+using Dinah.Core;
+using LibationFileManager;
 using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
+using System;
+using System.Collections.Generic;
+using System.IO;
 
-namespace AppScaffolding
+namespace AppScaffolding;
+
+/// <summary>
+/// 
+/// 
+///      directly manipulates settings files without going through domain logic.
+///      
+///      for migrations only. use with caution.
+/// 
+/// 
+/// </summary>
+public static class UNSAFE_MigrationHelper
 {
-	/// <summary>
-	/// 
-	/// 
-	///      directly manipulates settings files without going through domain logic.
-	///      
-	///      for migrations only. use with caution.
-	/// 
-	/// 
-	/// </summary>
-	public static class UNSAFE_MigrationHelper
+	public static string? SettingsDirectory
+		=> !APPSETTINGS_TryGet(LibationFiles.LIBATION_FILES_KEY, out var value) || value is null
+		? null
+		: value;
+
+	#region appsettings.json
+
+	public static bool APPSETTINGS_TryGet(string key, out string? value)
 	{
-		public static string SettingsDirectory
-			=> !APPSETTINGS_TryGet(LIBATION_FILES_KEY, out var value) || value is null
-			? null
-			: value;
+		bool success = false;
+		JToken? val = null;
 
-		#region appsettings.json
-		private static string APPSETTINGS_JSON { get; } = Path.Combine(Path.GetDirectoryName(Environment.ProcessPath), "appsettings.json");
+		process_APPSETTINGS_Json(jObj => success = jObj.TryGetValue(key, out val), false);
 
-		public static bool APPSETTINGS_Json_Exists => File.Exists(APPSETTINGS_JSON);
+		value = success ? val?.Value<string>() : null;
+		return success;
+	}
 
-		public static bool APPSETTINGS_TryGet(string key, out string value)
+	/// <summary>only insert if not exists</summary>
+	public static void APPSETTINGS_Insert(string key, string value)
+		=> process_APPSETTINGS_Json(jObj => jObj.TryAdd(key, value));
+
+	/// <summary>only update if exists</summary>
+	public static void APPSETTINGS_Update(string key, string value)
+		=> process_APPSETTINGS_Json(jObj =>
 		{
-			bool success = false;
-			JToken val = null;
+			if (jObj.ContainsKey(key))
+				jObj[key] = value;
+		});
 
-			process_APPSETTINGS_Json(jObj => success = jObj.TryGetValue(key, out val), false);
+	/// <summary>only delete if exists</summary>
+	public static void APPSETTINGS_Delete(string key)
+		=> process_APPSETTINGS_Json(jObj =>
+		{
+			if (jObj.ContainsKey(key))
+				jObj.Remove(key);
+		});
 
-			value = success ? val.Value<string>() : null;
-			return success;
+	/// <param name="save">True: save if contents changed. False: no not attempt save</param>
+	private static void process_APPSETTINGS_Json(Action<JObject> action, bool save = true)
+	{
+		if (Configuration.Instance.LibationFiles.AppsettingsJsonFile is not string appSettingsFile)
+			return;
+
+		var startingContents = File.ReadAllText(appSettingsFile);
+
+		JObject jObj;
+		try
+		{
+			jObj = JObject.Parse(startingContents);
+		}
+		catch
+		{
+			return;
 		}
 
-		/// <summary>only insert if not exists</summary>
-		public static void APPSETTINGS_Insert(string key, string value)
-			=> process_APPSETTINGS_Json(jObj => jObj.TryAdd(key, value));
+		action(jObj);
 
-		/// <summary>only update if exists</summary>
-		public static void APPSETTINGS_Update(string key, string value)
-			=> process_APPSETTINGS_Json(jObj => {
-				if (jObj.ContainsKey(key))
-					jObj[key] = value;
-			});
+		if (!save)
+			return;
 
-		/// <summary>only delete if exists</summary>
-		public static void APPSETTINGS_Delete(string key)
-			=> process_APPSETTINGS_Json(jObj => {
-				if (jObj.ContainsKey(key))
-					jObj.Remove(key);
-			});
+		// only save if different
+		var endingContents_indented = jObj.ToString(Formatting.Indented);
+		var endingContents_compact = jObj.ToString(Formatting.None);
+		if (startingContents.EqualsInsensitive(endingContents_indented) || startingContents.EqualsInsensitive(endingContents_compact))
+			return;
 
-		/// <param name="save">True: save if contents changed. False: no not attempt save</param>
-		private static void process_APPSETTINGS_Json(Action<JObject> action, bool save = true)
+		File.WriteAllText(Configuration.Instance.LibationFiles.AppsettingsJsonFile, endingContents_indented);
+		System.Threading.Thread.Sleep(100);
+	}
+	#endregion
+	#region Settings.json
+
+	public static string? SettingsJsonPath => SettingsDirectory is null ? null : Path.Combine(SettingsDirectory, LibationFiles.SETTINGS_JSON);
+
+	public static bool Settings_TryGet(string key, out string? value)
+	{
+		bool success = false;
+		JToken? val = null;
+
+		process_SettingsJson(jObj => success = jObj.TryGetValue(key, out val), false);
+
+		value = success ? val?.Value<string>() : null;
+		return success;
+	}
+
+	public static bool Settings_JsonPathIsType(string jsonPath, JTokenType jTokenType)
+	{
+		JToken? val = null;
+
+		process_SettingsJson(jObj => val = jObj.SelectToken(jsonPath), false);
+
+		return val?.Type == jTokenType;
+	}
+
+	public static bool Settings_TryGetFromJsonPath(string jsonPath, out string? value)
+	{
+		JToken? val = null;
+
+		process_SettingsJson(jObj => val = jObj.SelectToken(jsonPath), false);
+
+		if (val?.Type == JTokenType.String)
 		{
-			// only insert if not exists
-			if (!APPSETTINGS_Json_Exists)
-				return;
-
-			var startingContents = File.ReadAllText(APPSETTINGS_JSON);
-
-			JObject jObj;
-			try
-			{
-				jObj = JObject.Parse(startingContents);
-			}
-			catch
-			{
-				return;
-			}
-
-			action(jObj);
-
-			if (!save)
-				return;
-
-			// only save if different
-			var endingContents_indented = jObj.ToString(Formatting.Indented);
-			var endingContents_compact = jObj.ToString(Formatting.None);
-			if (startingContents.EqualsInsensitive(endingContents_indented) || startingContents.EqualsInsensitive(endingContents_compact))
-				return;
-
-			File.WriteAllText(APPSETTINGS_JSON, endingContents_indented);
-			System.Threading.Thread.Sleep(100);
-		}
-		#endregion
-		#region Settings.json
-		public const string LIBATION_FILES_KEY = "LibationFiles";
-		private const string SETTINGS_JSON = "Settings.json";
-
-		public static string SettingsJsonPath => SettingsDirectory is null ? null : Path.Combine(SettingsDirectory, SETTINGS_JSON);
-		public static bool SettingsJson_Exists => SettingsJsonPath is not null && File.Exists(SettingsJsonPath);
-
-		public static bool Settings_TryGet(string key, out string value)
-		{
-			bool success = false;
-			JToken val = null;
-
-			process_SettingsJson(jObj => success = jObj.TryGetValue(key, out val), false);
-
-			value = success ? val.Value<string>() : null;
-			return success;
-		}
-
-		public static bool Settings_JsonPathIsType(string jsonPath, JTokenType jTokenType)
-		{
-			JToken val = null;
-
-			process_SettingsJson(jObj => val = jObj.SelectToken(jsonPath), false);
-
-			return val?.Type == jTokenType;
-		}
-
-		public static bool Settings_TryGetFromJsonPath(string jsonPath, out string value)
-		{
-			JToken val = null;
-
-			process_SettingsJson(jObj => val = jObj.SelectToken(jsonPath), false);
-
-			if (val?.Type == JTokenType.String)
-			{
-				value = val.Value<string>();
-				return true;
-			}
-			else
-			{
-				value = null;
-				return false;
-			}
-		}
-
-		public static void Settings_SetWithJsonPath(string jsonPath, string propertyName, string newValue)
-		{
-			if (!Settings_TryGetFromJsonPath($"{jsonPath}.{propertyName}", out _))
-				return;
-
-			process_SettingsJson(jObj =>
-			{
-				var token = jObj.SelectToken(jsonPath);
-				if (token is null
-				|| token is not JObject o
-				|| o[propertyName] is null)
-					return;
-
-				var oldValue = token.Value<string>(propertyName);
-				if (oldValue != newValue)
-					token[propertyName] = newValue;
-			});
-		}
-
-		public static bool Settings_TryGetArrayLength(string jsonPath, out int length)
-		{
-			length = 0;
-
-			if (!Settings_JsonPathIsType(jsonPath, JTokenType.Array))
-				return false;
-
-			JArray array = null;
-			process_SettingsJson(jObj => array = (JArray)jObj.SelectToken(jsonPath));
-
-			length = array.Count;
+			value = val.Value<string>();
 			return true;
 		}
-
-		public static void Settings_AddToArray(string jsonPath, string newValue)
+		else
 		{
-			if (!Settings_JsonPathIsType(jsonPath, JTokenType.Array))
-				return;
-
-			process_SettingsJson(jObj =>
-			{
-				var array = (JArray)jObj.SelectToken(jsonPath);
-				array.Add(newValue);
-			});
+			value = null;
+			return false;
 		}
-
-		/// <summary>Do not add if already exists</summary>
-		public static void Settings_AddUniqueToArray(string arrayPath, string newValue)
-		{
-			if (!Settings_TryGetArrayLength(arrayPath, out var qty))
-				return;
-
-			for (var i = 0; i < qty; i++)
-			{
-				var exists = Settings_TryGetFromJsonPath($"{arrayPath}[{i}]", out var value);
-				if (exists && value == newValue)
-					return;
-			}
-
-			Settings_AddToArray(arrayPath, newValue);
-		}
-
-		/// <summary>only remove if not exists</summary>
-		public static void Settings_RemoveFromArray(string jsonPath, int position)
-		{
-			if (!Settings_JsonPathIsType(jsonPath, JTokenType.Array))
-				return;
-
-			process_SettingsJson(jObj =>
-			{
-				var array = (JArray)jObj.SelectToken(jsonPath);
-				if (position < array.Count)
-					array.RemoveAt(position);
-			});
-		}
-
-		/// <summary>only insert if not exists</summary>
-		public static void Settings_Insert(string key, string value)
-			=> process_SettingsJson(jObj => jObj.TryAdd(key, value));
-
-		/// <summary>only update if exists</summary>
-		public static void Settings_Update(string key, string value)
-			=> process_SettingsJson(jObj => {
-				if (jObj.ContainsKey(key))
-					jObj[key] = value;
-			});
-
-		/// <summary>only delete if exists</summary>
-		public static void Settings_Delete(string key)
-			=> process_SettingsJson(jObj => {
-				if (jObj.ContainsKey(key))
-					jObj.Remove(key);
-			});
-
-		/// <param name="save">True: save if contents changed. False: no not attempt save</param>
-		private static void process_SettingsJson(Action<JObject> action, bool save = true)
-		{
-			// only insert if not exists
-			if (!SettingsJson_Exists)
-				return;
-
-			var startingContents = File.ReadAllText(SettingsJsonPath);
-
-			JObject jObj;
-			try
-			{
-				jObj = JObject.Parse(startingContents);
-			}
-			catch
-			{
-				return;
-			}
-
-			action(jObj);
-
-			if (!save)
-				return;
-
-			// only save if different
-			var endingContents_indented = jObj.ToString(Formatting.Indented);
-			var endingContents_compact = jObj.ToString(Formatting.None);
-			if (startingContents.EqualsInsensitive(endingContents_indented) || startingContents.EqualsInsensitive(endingContents_compact))
-				return;
-
-			File.WriteAllText(SettingsJsonPath, endingContents_indented);
-			System.Threading.Thread.Sleep(100);
-		}
-		#endregion
-		#region LibationContext.db
-		public const string LIBATION_CONTEXT = "LibationContext.db";
-		public static string DatabaseFile => SettingsDirectory is null ? null : Path.Combine(SettingsDirectory, LIBATION_CONTEXT);
-		public static bool DatabaseFile_Exists => DatabaseFile is not null && File.Exists(DatabaseFile);
-		#endregion
 	}
+
+	public static void Settings_SetWithJsonPath(string jsonPath, string propertyName, string newValue)
+	{
+		if (!Settings_TryGetFromJsonPath($"{jsonPath}.{propertyName}", out _))
+			return;
+
+		process_SettingsJson(jObj =>
+		{
+			var token = jObj.SelectToken(jsonPath);
+			if (token is null
+			|| token is not JObject o
+			|| o[propertyName] is null)
+				return;
+
+			var oldValue = token.Value<string>(propertyName);
+			if (oldValue != newValue)
+				token[propertyName] = newValue;
+		});
+	}
+
+	public static bool Settings_TryGetArrayLength(string jsonPath, out int length)
+	{
+		length = 0;
+
+		if (!Settings_JsonPathIsType(jsonPath, JTokenType.Array))
+			return false;
+
+		JArray? array = null;
+		process_SettingsJson(jObj => array = jObj.SelectToken(jsonPath) as JArray);
+
+		length = array?.Count ?? 0;
+		return true;
+	}
+
+	public static void Settings_AddToArray(string jsonPath, string newValue)
+	{
+		if (!Settings_JsonPathIsType(jsonPath, JTokenType.Array))
+			return;
+
+		process_SettingsJson(jObj =>
+		{
+			(jObj.SelectToken(jsonPath) as JArray)?.Add(newValue);
+		});
+	}
+
+	/// <summary>Do not add if already exists</summary>
+	public static void Settings_AddUniqueToArray(string arrayPath, string newValue)
+	{
+		if (!Settings_TryGetArrayLength(arrayPath, out var qty))
+			return;
+
+		for (var i = 0; i < qty; i++)
+		{
+			var exists = Settings_TryGetFromJsonPath($"{arrayPath}[{i}]", out var value);
+			if (exists && value == newValue)
+				return;
+		}
+
+		Settings_AddToArray(arrayPath, newValue);
+	}
+
+	/// <summary>only remove if not exists</summary>
+	public static void Settings_RemoveFromArray(string jsonPath, int position)
+	{
+		if (!Settings_JsonPathIsType(jsonPath, JTokenType.Array))
+			return;
+
+		process_SettingsJson(jObj =>
+		{
+			if (jObj.SelectToken(jsonPath) is JArray array && position < array.Count)
+				array.RemoveAt(position);
+		});
+	}
+
+	/// <summary>only insert if not exists</summary>
+	public static void Settings_Insert(string key, string value)
+		=> process_SettingsJson(jObj => jObj.TryAdd(key, value));
+
+	/// <summary>only update if exists</summary>
+	public static void Settings_Update(string key, string value)
+		=> process_SettingsJson(jObj =>
+		{
+			if (jObj.ContainsKey(key))
+				jObj[key] = value;
+		});
+
+	/// <summary>only delete if exists</summary>
+	public static void Settings_Delete(string key)
+		=> process_SettingsJson(jObj =>
+		{
+			if (jObj.ContainsKey(key))
+				jObj.Remove(key);
+		});
+
+	/// <param name="save">True: save if contents changed. False: no not attempt save</param>
+	private static void process_SettingsJson(Action<JObject> action, bool save = true)
+	{
+		// only insert if not exists
+		if (!File.Exists(SettingsJsonPath))
+			return;
+
+		var startingContents = File.ReadAllText(SettingsJsonPath);
+
+		JObject jObj;
+		try
+		{
+			jObj = JObject.Parse(startingContents);
+		}
+		catch
+		{
+			return;
+		}
+
+		action(jObj);
+
+		if (!save)
+			return;
+
+		// only save if different
+		var endingContents_indented = jObj.ToString(Formatting.Indented);
+		var endingContents_compact = jObj.ToString(Formatting.None);
+		if (startingContents.EqualsInsensitive(endingContents_indented) || startingContents.EqualsInsensitive(endingContents_compact))
+			return;
+
+		File.WriteAllText(SettingsJsonPath, endingContents_indented);
+		System.Threading.Thread.Sleep(100);
+	}
+	#endregion
+	#region LibationContext.db
+	public const string LIBATION_CONTEXT = "LibationContext.db";
+	public static string? DatabaseFile => SettingsDirectory is null ? null : Path.Combine(SettingsDirectory, LIBATION_CONTEXT);
+	public static bool DatabaseFile_Exists => DatabaseFile is not null && File.Exists(DatabaseFile);
+	#endregion
 }

Source/AppScaffolding/UpgradeProperties.cs

@@ -1,34 +1,42 @@
-using System;
+using System;
 using System.Text.RegularExpressions;
 
-namespace AppScaffolding
+namespace AppScaffolding;
+
+/// <summary>Result of a version check: definitive up-to-date, update available, or unable to determine.</summary>
+public enum VersionCheckOutcome
 {
-	public record UpgradeProperties
-	{
-		private static readonly Regex linkstripper = new Regex(@"\[(.*)\]\(.*\)");
-		public string ZipUrl { get; }
-		public string HtmlUrl { get; }
-		public string ZipName { get; }
-		public Version LatestRelease { get; }
-		public string Notes { get; }
-
-		public UpgradeProperties(string zipUrl, string htmlUrl, string zipName, Version latestRelease, string notes)
-		{
-			ZipName = zipName;
-			HtmlUrl = htmlUrl;
-			ZipUrl = zipUrl;
-			LatestRelease = latestRelease;
-			Notes = stripMarkdownLinks(notes);
-		}
-		private string stripMarkdownLinks(string body)
-		{
-			body = body.Replace(@"\", "");
-			var matches = linkstripper.Matches(body);
-
-			foreach (Match match in matches)
-				body = body.Replace(match.Groups[0].Value, match.Groups[1].Value);
-
-			return body;
-		}
-	}
+	UpToDate,
+	UpdateAvailable,
+	UnableToDetermine,
+}
+
+/// <summary>Result of checking for a new version. Use <see cref="Outcome"/> to show the right message; <see cref="UpgradeProperties"/> is set only when <see cref="Outcome"/> is <see cref="VersionCheckOutcome.UpdateAvailable"/>.</summary>
+public record VersionCheckResult(VersionCheckOutcome Outcome, UpgradeProperties? UpgradeProperties = null);
+
+public partial record UpgradeProperties
+{
+	public string ZipUrl { get; }
+	public string HtmlUrl { get; }
+	public string ZipName { get; }
+	public Version LatestRelease { get; }
+	public string Notes { get; }
+
+	public UpgradeProperties(string zipUrl, string htmlUrl, string zipName, Version latestRelease, string notes)
+	{
+		ZipName = zipName;
+		HtmlUrl = htmlUrl;
+		ZipUrl = zipUrl;
+		LatestRelease = latestRelease;
+
+		var text = NoAppBlockRegex().Replace(notes, "");
+		text = LinkStripRegex().Replace(text, "$1");
+		Notes = text.Trim();
+	}
+
+	[GeneratedRegex(@"\[(.*)\]\(.*\)")]
+	private static partial Regex LinkStripRegex();
+
+	[GeneratedRegex(@"<!-- BEGIN NO-APP -->.*?<!-- END NO-APP -->", RegexOptions.Singleline)]
+	private static partial Regex NoAppBlockRegex();
 }

Source/ApplicationServices/ApplicationServices.csproj

@@ -1,17 +1,24 @@
 <Project Sdk="Microsoft.NET.Sdk">
 
   <PropertyGroup>
-    <TargetFramework>net7.0</TargetFramework>
+    <TargetFramework>net10.0</TargetFramework>
+    <Nullable>enable</Nullable>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="CsvHelper" Version="30.0.1" />
-    <PackageReference Include="NPOI" Version="2.6.0" />
+	<PackageReference Include="CsvHelper" Version="33.1.0">
+      <PrivateAssets>compile;contentFiles;build;buildMultitargeting;buildTransitive;analyzers;native</PrivateAssets>
+	</PackageReference>
+	<PackageReference Include="ClosedXML" Version="0.105.0">
+      <PrivateAssets>compile;contentFiles;build;buildMultitargeting;buildTransitive;analyzers;native</PrivateAssets>
+	</PackageReference>
   </ItemGroup>
 
   <ItemGroup>
     <ProjectReference Include="..\DtoImporterService\DtoImporterService.csproj" />
     <ProjectReference Include="..\LibationSearchEngine\LibationSearchEngine.csproj" />
+    <ProjectReference Include="..\DataLayer.Postgres\DataLayer.Postgres.csproj" />
+    <ProjectReference Include="..\DataLayer.Sqlite\DataLayer.Sqlite.csproj" />
   </ItemGroup>
 
 	<PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">

Source/ApplicationServices/AudiobookshelfApiService.cs

@@ -0,0 +1,566 @@
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Net;
+using System.Net.Http;
+using System.Net.Http.Headers;
+using System.Threading.Tasks;
+
+namespace ApplicationServices;
+
+public static class AudiobookshelfApiService
+{
+	public record Library(string Id, string Name, string MediaType, List<Folder> Folders);
+	public record Folder(string Id, string FullPath);
+	public enum UploadResult { Success, AlreadyExists, Failed }
+
+	/// <summary>
+	/// Audiobookshelf client (browser) route segments. If present in a pasted URL,
+	/// everything from that segment onward is UI path, not part of the API base.
+	/// </summary>
+	private static readonly HashSet<string> ClientRouteSegments = new(StringComparer.OrdinalIgnoreCase)
+	{
+		"library",
+		"item",
+		"collection",
+		"playlist",
+		"author",
+		"series",
+		"audiobook",
+		"config",
+		"login",
+		"account",
+	};
+
+	/// <summary>
+	/// Normalize a user-supplied Audiobookshelf server URL to an API base address.
+	/// Compensates for common mistakes such as pasting a browser library/item page URL,
+	/// including a trailing <c>/api</c> path, query strings, or omitting the scheme.
+	/// </summary>
+	/// <returns>Absolute http(s) base URL with no trailing slash.</returns>
+	public static string NormalizeServerUrl(string? serverUrl)
+	{
+		if (string.IsNullOrWhiteSpace(serverUrl))
+			throw new ArgumentException("Server URL is required.", nameof(serverUrl));
+
+		var trimmed = serverUrl.Trim();
+
+		// Allow host:port without a scheme (common when copying from docs or local setups).
+		if (!trimmed.Contains("://", StringComparison.Ordinal))
+			trimmed = "http://" + trimmed;
+
+		if (!Uri.TryCreate(trimmed, UriKind.Absolute, out var uri)
+			|| (uri.Scheme != Uri.UriSchemeHttp && uri.Scheme != Uri.UriSchemeHttps)
+			|| string.IsNullOrWhiteSpace(uri.Host))
+		{
+			throw new ArgumentException(
+				"Server URL must be an absolute http(s) address, for example http://localhost:13378 or https://abs.example.com",
+				nameof(serverUrl));
+		}
+
+		var path = StripClientRoutesAndApi(uri.AbsolutePath);
+		var authority = uri.GetLeftPart(UriPartial.Authority);
+		if (string.IsNullOrEmpty(path) || path == "/")
+			return authority;
+
+		return authority + path.TrimEnd('/');
+	}
+
+	private static string StripClientRoutesAndApi(string absolutePath)
+	{
+		if (string.IsNullOrEmpty(absolutePath) || absolutePath == "/")
+			return "";
+
+		var parts = absolutePath.Split('/', StringSplitOptions.RemoveEmptyEntries);
+		var prefixLength = 0;
+
+		for (var i = 0; i < parts.Length; i++)
+		{
+			var part = parts[i];
+
+			// Trailing or mid-path /api/... means the user included the API root.
+			if (string.Equals(part, "api", StringComparison.OrdinalIgnoreCase))
+				break;
+
+			if (ClientRouteSegments.Contains(part))
+				break;
+
+			prefixLength += 1 + part.Length;
+		}
+
+		if (prefixLength <= 0)
+			return "";
+
+		return absolutePath[..prefixLength];
+	}
+
+	private static HttpClient CreateClient(string serverUrl)
+	{
+		var normalized = NormalizeServerUrl(serverUrl);
+		var client = new HttpClient();
+		client.BaseAddress = new Uri(normalized + "/");
+		client.Timeout = TimeSpan.FromSeconds(30);
+		return client;
+	}
+
+	public static async Task<List<Library>> GetLibrariesAsync(string serverUrl, string apiToken)
+	{
+		var normalizedUrl = NormalizeServerUrl(serverUrl);
+		apiToken = AudiobookshelfTokenStorage.DecryptToken(apiToken) ?? "";
+
+		using var client = CreateClient(normalizedUrl);
+		client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiToken);
+
+		HttpResponseMessage response;
+		try
+		{
+			response = await client.GetAsync("api/libraries");
+		}
+		catch (TaskCanceledException ex)
+		{
+			throw new HttpRequestException(
+				$"Timed out connecting to Audiobookshelf at {normalizedUrl}. Check the Server URL and that the server is running.",
+				ex);
+		}
+		catch (HttpRequestException ex)
+		{
+			throw new HttpRequestException(
+				$"Could not reach Audiobookshelf at {normalizedUrl}. Check the Server URL, network, and that the server is running. Details: {ex.Message}",
+				ex);
+		}
+
+		if (!response.IsSuccessStatusCode)
+		{
+			var errorBody = await response.Content.ReadAsStringAsync();
+			throw CreateLibrariesFetchException(normalizedUrl, response.StatusCode, errorBody);
+		}
+
+		var json = await response.Content.ReadAsStringAsync();
+		var obj = JObject.Parse(json);
+		var libraries = obj["libraries"] as JArray ?? new JArray();
+
+		var allLibraries = libraries.Select(l => new Library(
+			l["id"]?.Value<string>() ?? "",
+			l["name"]?.Value<string>() ?? "",
+			l["mediaType"]?.Value<string>() ?? "book",
+			(l["folders"] as JArray ?? new JArray())
+				.Select(f => new Folder(
+					f["id"]?.Value<string>() ?? "",
+					f["fullPath"]?.Value<string>() ?? ""))
+				.ToList()))
+			.ToList();
+
+		// Only return libraries with book media type
+		return allLibraries.Where(l => string.Equals(l.MediaType, "book", StringComparison.OrdinalIgnoreCase)).ToList();
+	}
+
+	private static HttpRequestException CreateLibrariesFetchException(string normalizedUrl, HttpStatusCode statusCode, string errorBody)
+	{
+		var code = (int)statusCode;
+		var bodyPreview = SummarizeErrorBody(errorBody);
+
+		if (statusCode is HttpStatusCode.Unauthorized or HttpStatusCode.Forbidden)
+		{
+			return new HttpRequestException(
+				$"Audiobookshelf rejected the API token ({code} {statusCode}). " +
+				$"Check that the token is correct and not expired. Server: {normalizedUrl}");
+		}
+
+		if (statusCode == HttpStatusCode.NotFound)
+		{
+			return new HttpRequestException(
+				$"Audiobookshelf returned 404 when calling {normalizedUrl}/api/libraries. " +
+				"Server URL should be the Audiobookshelf base address only " +
+				"(for example http://localhost:13378 or https://abs.example.com), " +
+				"not a library or book page from the browser. " +
+				"If Audiobookshelf is served under a subpath, include that subpath " +
+				$"(for example http://host/audiobookshelf). Response: {bodyPreview}");
+		}
+
+		return new HttpRequestException(
+			$"Audiobookshelf API returned {code} ({statusCode}) when fetching libraries from {normalizedUrl}. Response: {bodyPreview}");
+	}
+
+	private static string SummarizeErrorBody(string errorBody)
+	{
+		if (string.IsNullOrWhiteSpace(errorBody))
+			return "(empty)";
+
+		var trimmed = errorBody.Trim();
+		const int maxLen = 280;
+		if (trimmed.Length <= maxLen)
+			return trimmed;
+
+		return trimmed[..maxLen] + "...";
+	}
+
+	public sealed record ConnectResult(
+		bool Success,
+		string StatusMessage,
+		string? NormalizedServerUrl,
+		bool ServerUrlAdjusted,
+		IReadOnlyList<Library> Libraries);
+
+	/// <summary>
+	/// Normalize URL, fetch book libraries, and produce UI status text.
+	/// Callers apply busy-state and bind <see cref="ConnectResult.Libraries"/> to controls.
+	/// </summary>
+	public static async Task<ConnectResult> ConnectAsync(string? serverUrl, string? apiToken)
+	{
+		if (string.IsNullOrWhiteSpace(serverUrl) || string.IsNullOrWhiteSpace(apiToken))
+		{
+			return new ConnectResult(
+				Success: false,
+				StatusMessage: "Please enter both server URL and API token.",
+				NormalizedServerUrl: null,
+				ServerUrlAdjusted: false,
+				Libraries: []);
+		}
+
+		string normalizedUrl;
+		bool urlAdjusted;
+		try
+		{
+			var trimmedUrl = serverUrl.Trim();
+			normalizedUrl = NormalizeServerUrl(trimmedUrl);
+			urlAdjusted = !string.Equals(trimmedUrl.TrimEnd('/'), normalizedUrl, StringComparison.OrdinalIgnoreCase);
+		}
+		catch (Exception ex)
+		{
+			return new ConnectResult(
+				Success: false,
+				StatusMessage: $"Connection failed: {ex.Message}",
+				NormalizedServerUrl: null,
+				ServerUrlAdjusted: false,
+				Libraries: []);
+		}
+
+		try
+		{
+			var libraries = await GetLibrariesAsync(normalizedUrl, apiToken.Trim());
+			if (libraries.Count == 0)
+			{
+				return new ConnectResult(
+					Success: false,
+					StatusMessage: "No book libraries found. Check your settings.",
+					NormalizedServerUrl: normalizedUrl,
+					ServerUrlAdjusted: urlAdjusted,
+					Libraries: []);
+			}
+
+			return new ConnectResult(
+				Success: true,
+				StatusMessage: FormatConnectedStatus(libraries.Count, urlAdjusted),
+				NormalizedServerUrl: normalizedUrl,
+				ServerUrlAdjusted: urlAdjusted,
+				Libraries: libraries);
+		}
+		catch (Exception ex)
+		{
+			return new ConnectResult(
+				Success: false,
+				StatusMessage: $"Connection failed: {ex.Message}",
+				NormalizedServerUrl: normalizedUrl,
+				ServerUrlAdjusted: urlAdjusted,
+				Libraries: []);
+		}
+	}
+
+	public static string FormatConnectedStatus(int libraryCount, bool urlAdjusted)
+	{
+		var libraryWord = libraryCount == 1 ? "library" : "libraries";
+		var message = $"Connected. Found {libraryCount} {libraryWord}.";
+		if (urlAdjusted)
+			message += " Server URL adjusted to the API base address.";
+		return message;
+	}
+
+	/// <summary>
+	/// Normalize for persistence when possible; otherwise keep the trimmed raw value
+	/// so the user can fix it on the next connect attempt.
+	/// </summary>
+	public static string TryNormalizeServerUrlForSave(string? url)
+	{
+		if (string.IsNullOrWhiteSpace(url))
+			return url?.Trim() ?? "";
+
+		try
+		{
+			return NormalizeServerUrl(url);
+		}
+		catch (ArgumentException)
+		{
+			return url.Trim();
+		}
+	}
+
+	public static async Task<bool> BookExistsAsync(string serverUrl, string apiToken, string libraryId, string title, string? author = null)
+	{
+		apiToken = AudiobookshelfTokenStorage.DecryptToken(apiToken) ?? "";
+		using var client = CreateClient(serverUrl);
+		client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiToken);
+		client.Timeout = TimeSpan.FromSeconds(30);
+
+		var normalizedTitle = NormalizeTitle(title);
+		var baseTitle = GetBaseTitle(normalizedTitle);
+
+		Serilog.Log.Logger.Debug("Audiobookshelf duplicate check: looking for '{Title}' (base: '{BaseTitle}') in library {LibraryId}", normalizedTitle, baseTitle, libraryId);
+
+		try
+		{
+			// Search with base title first (shorter = broader fuzzy matches, better recall)
+			var candidates = await SearchLibraryAsync(client, libraryId, baseTitle, 20);
+
+			// Also search with full title to catch cases where ABS stores the longer/subtitled version
+			if (!string.Equals(normalizedTitle, baseTitle, StringComparison.Ordinal))
+			{
+				var fullCandidates = await SearchLibraryAsync(client, libraryId, normalizedTitle, 10);
+				foreach (var c in fullCandidates)
+				{
+					if (!candidates.Any(existing => string.Equals(existing.Id, c.Id, StringComparison.Ordinal)))
+						candidates.Add(c);
+				}
+			}
+
+			if (candidates.Count == 0)
+			{
+				Serilog.Log.Logger.Debug("Audiobookshelf duplicate check: no candidates found for '{Title}' in library {LibraryId}", normalizedTitle, libraryId);
+				return false;
+			}
+
+			Serilog.Log.Logger.Debug("Audiobookshelf duplicate check: found {Count} candidate(s) for '{Title}' in library {LibraryId}", candidates.Count, normalizedTitle, libraryId);
+
+			foreach (var candidate in candidates)
+			{
+				if (string.IsNullOrWhiteSpace(candidate.Title))
+					continue;
+
+				bool titleMatch = false;
+
+				// 1) Exact match against normalized title
+				if (string.Equals(candidate.Title, normalizedTitle, StringComparison.OrdinalIgnoreCase))
+					titleMatch = true;
+
+				// 2) Exact match against base title (without subtitle)
+				if (!titleMatch && string.Equals(candidate.Title, baseTitle, StringComparison.OrdinalIgnoreCase))
+					titleMatch = true;
+
+				// 3) Exact match against combined title:subtitle
+				if (!titleMatch && !string.IsNullOrWhiteSpace(candidate.FullTitle)
+					&& string.Equals(candidate.FullTitle, normalizedTitle, StringComparison.OrdinalIgnoreCase))
+					titleMatch = true;
+
+				if (titleMatch && AuthorsCompatible(author, candidate.Authors))
+				{
+					Serilog.Log.Logger.Information("Audiobookshelf duplicate check: found match for '{Title}' (id={ItemId})", title, candidate.Id);
+					return true;
+				}
+			}
+
+			Serilog.Log.Logger.Debug("Audiobookshelf duplicate check: '{Title}' not found in library {LibraryId}", normalizedTitle, libraryId);
+			return false;
+		}
+		catch (Exception ex)
+		{
+			Serilog.Log.Logger.Debug(ex, "Audiobookshelf duplicate check failed for '{Title}' in library {LibraryId}", title, libraryId);
+			throw; // Let caller decide whether to proceed with upload
+		}
+	}
+
+	private record SearchCandidate(string Id, string Title, string FullTitle, List<string> Authors);
+
+	private static async Task<List<SearchCandidate>> SearchLibraryAsync(HttpClient client, string libraryId, string query, int limit)
+	{
+		var url = $"api/libraries/{Uri.EscapeDataString(libraryId)}/search?q={Uri.EscapeDataString(query)}&limit={limit}";
+		var response = await client.GetAsync(url);
+		if (!response.IsSuccessStatusCode)
+		{
+			var errorBody = await response.Content.ReadAsStringAsync();
+			throw new HttpRequestException($"Audiobookshelf search returned {(int)response.StatusCode} for query '{query}'. Body: {errorBody}");
+		}
+
+		var json = await response.Content.ReadAsStringAsync();
+		var obj = JObject.Parse(json);
+		var books = obj["book"] as JArray ?? new JArray();
+
+		var results = new List<SearchCandidate>();
+		foreach (var entry in books)
+		{
+			var item = entry["libraryItem"] ?? entry;
+			var id = item["id"]?.Value<string>() ?? entry["id"]?.Value<string>() ?? "";
+			var itemTitle = item["media"]?["metadata"]?["title"]?.Value<string>()?.Replace("\u00A0", " ").Trim();
+			var itemSubtitle = item["media"]?["metadata"]?["subtitle"]?.Value<string>()?.Replace("\u00A0", " ").Trim();
+
+			var itemFullTitle = string.IsNullOrWhiteSpace(itemSubtitle)
+				? itemTitle
+				: $"{itemTitle}: {itemSubtitle}";
+
+			var authors = item["media"]?["metadata"]?["authors"] as JArray;
+			var authorList = authors?.Select(a => a["name"]?.Value<string>()?.Trim() ?? "")
+				.Where(n => !string.IsNullOrWhiteSpace(n))
+				.ToList() ?? [];
+
+			results.Add(new SearchCandidate(
+				id,
+				NormalizeTitle(itemTitle),
+				NormalizeTitle(itemFullTitle),
+				authorList));
+		}
+
+		return results;
+	}
+
+	private static bool AuthorsCompatible(string? libationAuthor, List<string> absAuthors)
+	{
+		// If either side has no author info, we can't use authors to disambiguate
+		if (string.IsNullOrWhiteSpace(libationAuthor))
+			return true;
+		if (absAuthors == null || absAuthors.Count == 0)
+			return true;
+
+		var libationAuthors = libationAuthor.Split(',', StringSplitOptions.RemoveEmptyEntries)
+			.Select(a => NormalizeAuthor(a))
+			.Where(a => !string.IsNullOrWhiteSpace(a))
+			.ToList();
+
+		if (libationAuthors.Count == 0)
+			return true;
+
+		foreach (var absAuthor in absAuthors.Select(NormalizeAuthor))
+		{
+			foreach (var la in libationAuthors)
+			{
+				if (string.Equals(absAuthor, la, StringComparison.OrdinalIgnoreCase))
+					return true;
+			}
+		}
+
+		return false;
+	}
+
+	private static string NormalizeAuthor(string? author)
+	{
+		if (string.IsNullOrWhiteSpace(author))
+			return author ?? "";
+		return author.Replace("\u00A0", " ").Trim();
+	}
+
+	private static string NormalizeTitle(string? title)
+	{
+		if (string.IsNullOrWhiteSpace(title))
+			return title ?? "";
+
+		var normalized = title
+			.Replace("\u00A0", " ")
+			.Replace("(Unabridged)", "", StringComparison.OrdinalIgnoreCase)
+			.Replace("(Abridged)", "", StringComparison.OrdinalIgnoreCase)
+			.Trim();
+
+		// Collapse multiple spaces to single space
+		while (normalized.Contains("  ", StringComparison.Ordinal))
+			normalized = normalized.Replace("  ", " ", StringComparison.Ordinal);
+
+		return normalized;
+	}
+
+	private static string GetBaseTitle(string fullTitle)
+	{
+		if (string.IsNullOrWhiteSpace(fullTitle))
+			return fullTitle;
+
+		var colonIndex = fullTitle.IndexOf(": ", StringComparison.Ordinal);
+		return colonIndex > 0 ? fullTitle[..colonIndex].Trim() : fullTitle;
+	}
+
+	public static async Task<UploadResult> UploadBookAsync(
+		string serverUrl,
+		string apiToken,
+		string libraryId,
+		string folderId,
+		string title,
+		string? author,
+		string? series,
+		IEnumerable<string> filePaths)
+	{
+		apiToken = AudiobookshelfTokenStorage.DecryptToken(apiToken) ?? "";
+
+		// Pre-check for existing item
+		try
+		{
+			if (await BookExistsAsync(serverUrl, apiToken, libraryId, title, author))
+			{
+				Serilog.Log.Logger.Information("Skipping Audiobookshelf upload: book '{Title}' already exists in library {LibraryId}", title, libraryId);
+				return UploadResult.AlreadyExists;
+			}
+		}
+		catch (Exception ex)
+		{
+			Serilog.Log.Logger.Warning(ex, "Pre-check for existing book on Audiobookshelf failed; will still attempt upload");
+			// Continue to upload attempt below
+		}
+
+		using var client = CreateClient(serverUrl);
+		client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", apiToken);
+		client.Timeout = TimeSpan.FromMinutes(30);
+
+		using var form = new MultipartFormDataContent();
+		form.Add(new StringContent(title), "title");
+
+		if (!string.IsNullOrWhiteSpace(author))
+			form.Add(new StringContent(author), "author");
+		if (!string.IsNullOrWhiteSpace(series))
+			form.Add(new StringContent(series), "series");
+
+		form.Add(new StringContent(libraryId), "library");
+		form.Add(new StringContent(folderId), "folder");
+
+		int fileIndex = 0;
+		var streams = new List<Stream>();
+		try
+		{
+			foreach (var path in filePaths.Where(File.Exists))
+			{
+				var stream = File.OpenRead(path);
+				streams.Add(stream);
+				var fileContent = new StreamContent(stream);
+				fileContent.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
+				form.Add(fileContent, fileIndex.ToString(), Path.GetFileName(path));
+				fileIndex++;
+			}
+
+			if (fileIndex == 0)
+			{
+				Serilog.Log.Logger.Warning("No audio files found to upload to Audiobookshelf for '{Title}'", title);
+				return UploadResult.Failed;
+			}
+
+			var response = await client.PostAsync("api/upload", form);
+
+			if (response.IsSuccessStatusCode)
+				return UploadResult.Success;
+
+			var responseBody = await response.Content.ReadAsStringAsync();
+			Serilog.Log.Logger.Error("Audiobookshelf upload failed for '{Title}' with status {(int)response.StatusCode} ({StatusCode}). Response body: {ResponseBody}",
+				title, (int)response.StatusCode, response.StatusCode, responseBody);
+
+			// Treat "already exists" 500 errors as skip/success
+			if (response.StatusCode == System.Net.HttpStatusCode.InternalServerError
+				&& responseBody.Contains("already exists", StringComparison.OrdinalIgnoreCase))
+			{
+				return UploadResult.AlreadyExists;
+			}
+
+			return UploadResult.Failed;
+		}
+		finally
+		{
+			foreach (var stream in streams)
+			{
+				try { stream.Dispose(); } catch { /* ignored */ }
+			}
+		}
+	}
+}

Source/ApplicationServices/AudiobookshelfTokenStorage.cs

@@ -0,0 +1,68 @@
+using AudibleApi.Authorization;
+using LibationFileManager;
+
+namespace ApplicationServices;
+
+public static class AudiobookshelfTokenStorage
+{
+	private const string EncryptedPrefix = "enc:";
+	private const string AssociatedData = "audiobookshelf-api-token";
+
+	public static string? EncryptToken(string? plaintextToken)
+	{
+		if (string.IsNullOrEmpty(plaintextToken))
+			return plaintextToken;
+
+		// Guard against double-encrypting an already-encrypted value
+		if (plaintextToken.StartsWith(EncryptedPrefix))
+			return plaintextToken;
+
+		if (Configuration.Instance.TokenStorageMethod != TokenStorageMethod.Encrypted)
+			return plaintextToken;
+
+		var protector = IdentityTokenStorage.Protector;
+		if (protector is null)
+		{
+			Serilog.Log.Logger.Warning("Audiobookshelf API token encryption requested but no protector is available; storing plaintext");
+			return plaintextToken;
+		}
+
+		try
+		{
+			var encrypted = protector.Protect(plaintextToken, AssociatedData);
+			return EncryptedPrefix + encrypted;
+		}
+		catch (System.Exception ex)
+		{
+			Serilog.Log.Logger.Error(ex, "Failed to encrypt Audiobookshelf API token; storing plaintext");
+			return plaintextToken;
+		}
+	}
+
+	public static string? DecryptToken(string? storedToken)
+	{
+		if (string.IsNullOrEmpty(storedToken))
+			return storedToken;
+
+		if (!storedToken.StartsWith(EncryptedPrefix))
+			return storedToken;
+
+		var payload = storedToken[EncryptedPrefix.Length..];
+		var protector = IdentityTokenStorage.Protector;
+		if (protector is null)
+		{
+			Serilog.Log.Logger.Warning("Audiobookshelf API token decryption requested but no protector is available; returning stored value");
+			return storedToken;
+		}
+
+		try
+		{
+			return protector.Unprotect(payload, AssociatedData);
+		}
+		catch (System.Exception ex)
+		{
+			Serilog.Log.Logger.Error(ex, "Failed to decrypt Audiobookshelf API token; returning stored value");
+			return storedToken;
+		}
+	}
+}

Source/ApplicationServices/BulkSetDownloadStatus.cs

@@ -1,78 +1,76 @@
-using System;
+using DataLayer;
+using Dinah.Core;
+using LibationFileManager;
 using System.Collections.Generic;
 using System.Linq;
 using System.Threading.Tasks;
-using DataLayer;
-using Dinah.Core;
-using LibationFileManager;
 
-namespace ApplicationServices
+namespace ApplicationServices;
+
+public class BulkSetDownloadStatus
 {
-    public class BulkSetDownloadStatus
-    {
-        private List<(string message, LiberatedStatus newStatus, IEnumerable<Book> Books)> actionSets { get; } = new();
+	private List<(string message, LiberatedStatus newStatus, IEnumerable<LibraryBook> LibraryBooks)> actionSets { get; } = new();
 
-        public int Count => actionSets.Count;
+	public int Count => actionSets.Count;
 
-        public IEnumerable<string> Messages => actionSets.Select(a => a.message);
-        public string AggregateMessage => $"Are you sure you want to set {Messages.Aggregate((a, b) => $"{a} and {b}")}?";
+	public IEnumerable<string> Messages => actionSets.Select(a => a.message);
+	public string AggregateMessage => $"Are you sure you want to set {Messages.Aggregate((a, b) => $"{a} and {b}")}?";
 
-        private List<LibraryBook> _libraryBooks;
-        private bool _setDownloaded;
-        private bool _setNotDownloaded;
+	private readonly List<LibraryBook> _libraryBooks;
+	private readonly bool _setDownloaded;
+	private readonly bool _setNotDownloaded;
 
-        public BulkSetDownloadStatus(List<LibraryBook> libraryBooks, bool setDownloaded, bool setNotDownloaded)
-        {
-            _libraryBooks = libraryBooks;
-            _setDownloaded = setDownloaded;
-            _setNotDownloaded = setNotDownloaded;
-        }
+	public BulkSetDownloadStatus(List<LibraryBook> libraryBooks, bool setDownloaded, bool setNotDownloaded)
+	{
+		_libraryBooks = libraryBooks;
+		_setDownloaded = setDownloaded;
+		_setNotDownloaded = setNotDownloaded;
+	}
 
-        public int Discover()
-        {
-            var bookExistsList = _libraryBooks
-                .Select(libraryBook => new
-                {
-                    libraryBook.Book,
-                    FileExists = AudibleFileStorage.Audio.GetPath(libraryBook.Book.AudibleProductId) is not null
-                })
-                .ToList();
+	public int Discover()
+	{
+		var bookExistsList = _libraryBooks
+			.Select(libraryBook => new
+			{
+				LibraryBook = libraryBook,
+				FileExists = AudibleFileStorage.Audio.GetPath(libraryBook.Book.AudibleProductId) is not null
+			})
+			.ToList();
 
-            if (_setDownloaded)
-            {
-                var books2change = bookExistsList
-                    .Where(a => a.FileExists && a.Book.UserDefinedItem.BookStatus != LiberatedStatus.Liberated)
-                    .Select(a => a.Book)
-                    .ToList();
+		if (_setDownloaded)
+		{
+			var books2change = bookExistsList
+				.Where(a => a.FileExists && a.LibraryBook.Book.UserDefinedItem.BookStatus != LiberatedStatus.Liberated)
+				.Select(a => a.LibraryBook)
+				.ToList();
 
-                if (books2change.Any())
-                    actionSets.Add((
-                        $"{"book".PluralizeWithCount(books2change.Count)} to 'Downloaded'",
-                        LiberatedStatus.Liberated,
-                        books2change));
-            }
+			if (books2change.Any())
+				actionSets.Add((
+					$"{"book".PluralizeWithCount(books2change.Count)} to 'Downloaded'",
+					LiberatedStatus.Liberated,
+					books2change));
+		}
 
-            if (_setNotDownloaded)
-            {
-                var books2change = bookExistsList
-                    .Where(a => !a.FileExists && a.Book.UserDefinedItem.BookStatus != LiberatedStatus.NotLiberated)
-                    .Select(a => a.Book)
-                    .ToList();
+		if (_setNotDownloaded)
+		{
+			var books2change = bookExistsList
+				.Where(a => !a.FileExists && a.LibraryBook.Book.UserDefinedItem.BookStatus != LiberatedStatus.NotLiberated)
+				.Select(a => a.LibraryBook)
+				.ToList();
 
-                if (books2change.Any())
-                    actionSets.Add((
-                        $"{"book".PluralizeWithCount(books2change.Count)} to 'Not Downloaded'",
-                        LiberatedStatus.NotLiberated,
-                        books2change));
-            }
+			if (books2change.Any())
+				actionSets.Add((
+					$"{"book".PluralizeWithCount(books2change.Count)} to 'Not Downloaded'",
+					LiberatedStatus.NotLiberated,
+					books2change));
+		}
 
-            return Count;
-        }
+		return Count;
+	}
 
-        public void Execute()
-        {
-            foreach (var a in actionSets)
-                a.Books.UpdateBookStatus(a.newStatus);
-        }
-    }
+	public async Task ExecuteAsync()
+	{
+		foreach (var a in actionSets)
+			await a.LibraryBooks.UpdateBookStatusAsync(a.newStatus);
+	}
 }

Source/ApplicationServices/DbContexts.cs

@@ -1,21 +1,140 @@
-using System;
-using System.Collections.Generic;
-using DataLayer;
+using DataLayer;
 using LibationFileManager;
+using Serilog;
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Threading;
 
-namespace ApplicationServices
+namespace ApplicationServices;
+
+public static class DbContexts
 {
-	public static class DbContexts
-	{
-		/// <summary>Use for fully functional context, incl. SaveChanges(). For query-only, use the other method</summary>
-		public static LibationContext GetContext()
-			=> LibationContext.Create(SqliteStorage.ConnectionString);
+	private static bool _sqliteDbValidated;
 
-		/// <summary>Use for full library querying. No lazy loading</summary>
-		public static List<LibraryBook> GetLibrary_Flat_NoTracking(bool includeParents = false)
+	private static readonly object _initialDatabaseStatisticsCaptureLock = new();
+
+	/// <summary>
+	/// True after initial DB statistics were read and either written to Serilog or stored for <see cref="TryEmitPendingInitialDatabaseStatistics"/>.
+	/// False if capture has not run yet or the last attempt threw (a later <see cref="GetContext"/> may retry).
+	/// </summary>
+	private static bool _initialDatabaseStatisticsCaptured;
+
+	/// <summary>Shape of the initial DB statistics log event; edit here only when changing what is logged.</summary>
+	private sealed class InitialDatabaseStatistics
+	{
+		public required int LibraryBooksNotInTrash { get; init; }
+		public required int LibraryBooksInTrash { get; init; }
+		public required int BookRecords { get; init; }
+	}
+
+	private static InitialDatabaseStatistics? _pendingInitialDbStats;
+
+	/// <summary>Use for fully functional context, incl. SaveChanges(). For query-only, use the other method</summary>
+	public static LibationContext GetContext()
+	{
+		var context = !string.IsNullOrEmpty(Configuration.Instance.PostgresqlConnectionString)
+			? LibationContextFactory.CreatePostgres(Configuration.Instance.PostgresqlConnectionString)
+			: LibationContextFactory.CreateSqlite(SqliteStorage.ConnectionString);
+		try
 		{
-			using var context = GetContext();
-			return context.GetLibrary_Flat_NoTracking(includeParents);
+			LibationContextFactory.ApplyMigrations(
+				context,
+				string.IsNullOrEmpty(Configuration.Instance.PostgresqlConnectionString) ? SqliteStorage.DatabasePath : null);
+		}
+		catch (InvalidOperationException ex) when (ex.Message.Contains("Libation cannot write its SQLite database", StringComparison.Ordinal))
+		{
+			Log.Error(
+				ex,
+				"SQLite migrations failed (read-only or blocked). LibationFiles={LibationFiles} DatabasePath={DatabasePath} AppsettingsJson={AppsettingsJson}",
+				Configuration.Instance.LibationFiles.Location,
+				SqliteStorage.DatabasePath,
+				Configuration.Instance.LibationFiles.AppsettingsJsonFile ?? "(null, LIBATION_FILES_DIR may be set)");
+			throw;
+		}
+
+		// Validate SQLite DB file was created and is accessible (once per process; OS may delay availability)
+		if (!_sqliteDbValidated && string.IsNullOrEmpty(Configuration.Instance.PostgresqlConnectionString))
+		{
+			EssentialFileValidator.ValidateCreatedAndReport(SqliteStorage.DatabasePath);
+			_sqliteDbValidated = true;
+		}
+
+		TryCaptureInitialDatabaseStatistics(context);
+
+		return context;
+	}
+
+	private static void TryCaptureInitialDatabaseStatistics(LibationContext context)
+	{
+		lock (_initialDatabaseStatisticsCaptureLock)
+		{
+			if (_initialDatabaseStatisticsCaptured)
+				return;
+
+			try
+			{
+				var (notInTrash, inTrash) = context.GetLibraryBookCountsByTrashFlag();
+				var bookRecords = context.GetBookCount();
+
+				var stats = new InitialDatabaseStatistics
+				{
+					LibraryBooksNotInTrash = notInTrash,
+					LibraryBooksInTrash = inTrash,
+					BookRecords = bookRecords,
+				};
+
+				if (Configuration.Instance.SerilogInitialized)
+					LogInitialDatabaseStatistics(stats);
+				else
+					_pendingInitialDbStats = stats;
+
+				_initialDatabaseStatisticsCaptured = true;
+			}
+			catch (Exception ex)
+			{
+				if (Configuration.Instance.SerilogInitialized)
+					Log.Warning(ex, "Could not capture initial database statistics");
+			}
 		}
 	}
+
+	/// <summary>
+	/// Writes initial DB statistics that were captured before Serilog was configured (e.g. WinForms early library load).
+	/// Call once after <see cref="Configuration.ConfigureLogging"/>.
+	/// </summary>
+	public static void TryEmitPendingInitialDatabaseStatistics()
+	{
+		var pending = Interlocked.Exchange(ref _pendingInitialDbStats, null);
+		if (pending is not null)
+			LogInitialDatabaseStatistics(pending);
+	}
+
+	private static void LogInitialDatabaseStatistics(InitialDatabaseStatistics stats) =>
+		Log.Logger.Information("Initial database statistics. {@DbStats}", stats);
+
+	/// <summary>Use for full library querying. No lazy loading</summary>
+	public static List<LibraryBook> GetLibrary_Flat_NoTracking(bool includeParents = false)
+	{
+		using var context = GetContext();
+		return context.GetLibrary_Flat_NoTracking(includeParents);
+	}
+
+	public static List<LibraryBook> GetUnliberated_Flat_NoTracking()
+	{
+		using var context = GetContext();
+		return context.GetUnLiberated_Flat_NoTracking();
+	}
+
+	public static List<LibraryBook> GetDeletedLibraryBooks()
+	{
+		using var context = GetContext();
+		return context.GetDeletedLibraryBooks();
+	}
+
+	public static LibraryBook? GetLibraryBook_Flat_NoTracking(string productId, bool caseSensative = true, string? account = null)
+	{
+		using var context = GetContext();
+		return context.GetLibraryBook_Flat_NoTracking(productId, caseSensative, account);
+	}
 }

Source/ApplicationServices/ExportDto.cs

@@ -0,0 +1,141 @@
+using CsvHelper.Configuration.Attributes;
+using DataLayer;
+using Newtonsoft.Json;
+using System;
+using System.Linq;
+
+namespace ApplicationServices;
+
+internal class ExportDto(LibraryBook libBook)
+{
+	[Name("Account")]
+	public string Account { get; } = libBook.Account;
+
+	[Name("Date Added to library")]
+	public DateTime DateAdded { get; } = libBook.DateAdded;
+
+	[Name("Is Audible Plus?")]
+	public bool IsAudiblePlus { get; } = libBook.IsAudiblePlus;
+
+	[Name("Absent from last scan?")]
+	public bool AbsentFromLastScan { get; } = libBook.AbsentFromLastScan;
+
+	[Name("Audible Product Id")]
+	public string AudibleProductId { get; } = libBook.Book.AudibleProductId;
+
+	[Name("Locale")]
+	public string Locale { get; } = libBook.Book.Locale;
+
+	[Name("Title")]
+	public string Title { get; } = libBook.Book.Title;
+
+	[Name("Subtitle")]
+	public string Subtitle { get; } = libBook.Book.Subtitle;
+
+	[Name("Authors")]
+	public string AuthorNames { get; } = libBook.Book.AuthorNames;
+
+	[Name("Narrators")]
+	public string NarratorNames { get; } = libBook.Book.NarratorNames;
+
+	[Name("Length In Minutes")]
+	public int LengthInMinutes { get; } = libBook.Book.LengthInMinutes;
+
+	[Name("Description")]
+	public string Description { get; } = libBook.Book.Description;
+
+	[Name("Publisher")]
+	public string? Publisher { get; } = libBook.Book.Publisher;
+
+	[Name("Has PDF")]
+	public bool HasPdf { get; } = libBook.Book.HasPdf;
+
+	[Name("Series Names")]
+	public string SeriesNames { get; } = libBook.Book.SeriesNames();
+
+	[Name("Series Order")]
+	public string SeriesOrder { get; } = libBook.Book.SeriesLink?.Any() is true ? string.Join(", ", libBook.Book.SeriesLink.Select(sl => $"{sl.Order} : {sl.Series.Name}")) : "";
+
+	[Name("Community Rating: Overall")]
+	public float? CommunityRatingOverall { get; } = ZeroIsNull(libBook.Book.Rating?.OverallRating);
+
+	[Name("Community Rating: Performance")]
+	public float? CommunityRatingPerformance { get; } = ZeroIsNull(libBook.Book.Rating?.PerformanceRating);
+
+	[Name("Community Rating: Story")]
+	public float? CommunityRatingStory { get; } = ZeroIsNull(libBook.Book.Rating?.StoryRating);
+
+	[Name("Cover Id")]
+	public string? PictureId { get; } = libBook.Book.PictureId;
+
+	[Name("Cover Id Large")]
+	public string? PictureLarge { get; } = libBook.Book.PictureLarge;
+
+	[Name("Is Abridged?")]
+	public bool IsAbridged { get; } = libBook.Book.IsAbridged;
+
+	[Name("Date Published")]
+	public DateTime? DatePublished { get; } = libBook.Book.DatePublished;
+
+	[Name("Categories")]
+	public string CategoriesNames { get; } = string.Join("; ", libBook.Book.LowestCategoryNames());
+
+	[Name("My Rating: Overall")]
+	public float? MyRatingOverall { get; } = ZeroIsNull(libBook.Book.UserDefinedItem.Rating.OverallRating);
+
+	[Name("My Rating: Performance")]
+	public float? MyRatingPerformance { get; } = ZeroIsNull(libBook.Book.UserDefinedItem.Rating.PerformanceRating);
+
+	[Name("My Rating: Story")]
+	public float? MyRatingStory { get; } = ZeroIsNull(libBook.Book.UserDefinedItem.Rating.StoryRating);
+
+	[Name("My Libation Tags")]
+	public string MyLibationTags { get; } = libBook.Book.UserDefinedItem.Tags;
+
+	[Name("Book Liberated Status")]
+	public string BookStatus { get; } = libBook.Book.UserDefinedItem.BookStatus.ToString();
+
+	[Name("PDF Liberated Status")]
+	public string? PdfStatus { get; } = libBook.Book.UserDefinedItem.PdfStatus.ToString();
+
+	[Name("Content Type")]
+	public string ContentType { get; } = libBook.Book.ContentType.ToString();
+
+	[Name("Language")]
+	public string? Language { get; } = libBook.Book.Language;
+
+	[Name("Last Downloaded")]
+	public DateTime? LastDownloaded { get; } = libBook.Book.UserDefinedItem.LastDownloaded;
+
+	[Name("Last Downloaded Version")]
+	public string? LastDownloadedVersion { get; } = libBook.Book.UserDefinedItem.LastDownloadedVersion?.ToString();
+
+	[Name("Is Finished?")]
+	public bool IsFinished { get; } = libBook.Book.UserDefinedItem.IsFinished;
+
+	[Name("Is Spatial?")]
+	public bool IsSpatial { get; } = libBook.Book.IsSpatial;
+
+	[Name("Included Until")]
+	public DateTime? IncludedUntil { get; } = libBook.IncludedUntil;
+
+	[Name("Last Downloaded File Version")]
+	public string? LastDownloadedFileVersion { get; } = libBook.Book.UserDefinedItem.LastDownloadedFileVersion;
+
+	[Ignore /* csv ignore */]
+	public AudioFormat? LastDownloadedFormat { get; } = libBook.Book.UserDefinedItem.LastDownloadedFormat;
+
+	[Name("Last Downloaded Codec"), JsonIgnore]
+	public string CodecString => LastDownloadedFormat?.CodecString ?? "";
+
+	[Name("Last Downloaded Sample rate"), JsonIgnore]
+	public int? SampleRate => LastDownloadedFormat?.SampleRate;
+
+	[Name("Last Downloaded Audio Channels"), JsonIgnore]
+	public int? ChannelCount => LastDownloadedFormat?.ChannelCount;
+
+	[Name("Last Downloaded Bitrate"), JsonIgnore]
+	public int? BitRate => LastDownloadedFormat?.BitRate;
+
+	private static float? ZeroIsNull(float? value) => value is 0 ? null : value;
+}

Source/ApplicationServices/ISearchEngine.cs

@@ -0,0 +1,8 @@
+using LibationSearchEngine;
+
+namespace ApplicationServices;
+
+public interface ISearchEngine
+{
+	SearchResultSet? GetSearchResultSet(string? searchString);
+}

Source/ApplicationServices/LibraryExporter.cs

@@ -1,299 +1,81 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
+using ClosedXML.Excel;
 using CsvHelper;
 using CsvHelper.Configuration.Attributes;
 using DataLayer;
-using NPOI.XSSF.UserModel;
-using Serilog;
+using Newtonsoft.Json;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using System.Reflection;
 
-namespace ApplicationServices
+namespace ApplicationServices;
+
+public static class LibraryExporter
 {
-	public class ExportDto
+	public static void ToCsv(string saveFilePath, IEnumerable<LibraryBook>? libraryBooks = null)
 	{
-		public static string GetName(string fieldName)
-		{
-			var property = typeof(ExportDto).GetProperty(fieldName);
-			var attribute = property.GetCustomAttributes(typeof(NameAttribute), true)[0];
-			var description = (NameAttribute)attribute;
-			var text = description.Names;
-			return text[0];
-		}
+		libraryBooks ??= DbContexts.GetLibrary_Flat_NoTracking();
+		var dtos = libraryBooks.ToDtos();
+		if (dtos.Count == 0)
+			return;
 
-		[Name("Account")]
-		public string Account { get; set; }
-
-		[Name("Date Added to library")]
-		public DateTime DateAdded { get; set; }
-
-		[Name("Audible Product Id")]
-		public string AudibleProductId { get; set; }
-
-		[Name("Locale")]
-		public string Locale { get; set; }
-
-		[Name("Title")]
-		public string Title { get; set; }
-
-		[Name("Authors")]
-		public string AuthorNames { get; set; }
-
-		[Name("Narrators")]
-		public string NarratorNames { get; set; }
-
-		[Name("Length In Minutes")]
-		public int LengthInMinutes { get; set; }
-
-		[Name("Description")]
-		public string Description { get; set; }
-
-		[Name("Publisher")]
-		public string Publisher { get; set; }
-
-		[Name("Has PDF")]
-		public bool HasPdf { get; set; }
-
-		[Name("Series Names")]
-		public string SeriesNames { get; set; }
-
-		[Name("Series Order")]
-		public string SeriesOrder { get; set; }
-
-		[Name("Community Rating: Overall")]
-		public float? CommunityRatingOverall { get; set; }
-
-		[Name("Community Rating: Performance")]
-		public float? CommunityRatingPerformance { get; set; }
-
-		[Name("Community Rating: Story")]
-		public float? CommunityRatingStory { get; set; }
-
-		[Name("Cover Id")]
-		public string PictureId { get; set; }
-
-		[Name("Is Abridged?")]
-		public bool IsAbridged { get; set; }
-
-		[Name("Date Published")]
-		public DateTime? DatePublished { get; set; }
-
-		[Name("Categories")]
-		public string CategoriesNames { get; set; }
-
-		[Name("My Rating: Overall")]
-		public float? MyRatingOverall { get; set; }
-
-		[Name("My Rating: Performance")]
-		public float? MyRatingPerformance { get; set; }
-
-		[Name("My Rating: Story")]
-		public float? MyRatingStory { get; set; }
-
-		[Name("My Libation Tags")]
-		public string MyLibationTags { get; set; }
-
-		[Name("Book Liberated Status")]
-		public string BookStatus { get; set; }
-
-		[Name("PDF Liberated Status")]
-		public string PdfStatus { get; set; }
-
-		[Name("Content Type")]
-		public string ContentType { get; set; }
-
-        [Name("Audio Format")]
-		public string AudioFormat { get; set; }
-
-		[Name("Language")]
-        public string Language { get; set; }
-    }
-	public static class LibToDtos
-	{
-		public static List<ExportDto> ToDtos(this IEnumerable<LibraryBook> library)
-			=> library.Select(a => new ExportDto
-			{
-				Account = a.Account,
-				DateAdded = a.DateAdded,
-				AudibleProductId = a.Book.AudibleProductId,
-				Locale = a.Book.Locale,
-				Title = a.Book.Title,
-				AuthorNames = a.Book.AuthorNames(),
-				NarratorNames = a.Book.NarratorNames(),
-				LengthInMinutes = a.Book.LengthInMinutes,
-				Description = a.Book.Description,
-				Publisher = a.Book.Publisher,
-				HasPdf = a.Book.HasPdf(),
-				SeriesNames = a.Book.SeriesNames(),
-				SeriesOrder = a.Book.SeriesLink.Any() ? a.Book.SeriesLink?.Select(sl => $"{sl.Order} : {sl.Series.Name}").Aggregate((a, b) => $"{a}, {b}") : "",
-				CommunityRatingOverall = a.Book.Rating?.OverallRating,
-				CommunityRatingPerformance = a.Book.Rating?.PerformanceRating,
-				CommunityRatingStory = a.Book.Rating?.StoryRating,
-				PictureId = a.Book.PictureId,
-				IsAbridged = a.Book.IsAbridged,
-				DatePublished = a.Book.DatePublished,
-				CategoriesNames = a.Book.CategoriesNames().Any() ? a.Book.CategoriesNames().Aggregate((a, b) => $"{a}, {b}") : "",
-				MyRatingOverall = a.Book.UserDefinedItem.Rating.OverallRating,
-				MyRatingPerformance = a.Book.UserDefinedItem.Rating.PerformanceRating,
-				MyRatingStory = a.Book.UserDefinedItem.Rating.StoryRating,
-				MyLibationTags = a.Book.UserDefinedItem.Tags,
-				BookStatus = a.Book.UserDefinedItem.BookStatus.ToString(),
-				PdfStatus = a.Book.UserDefinedItem.PdfStatus.ToString(),
-				ContentType = a.Book.ContentType.ToString(),
-				AudioFormat = a.Book.AudioFormat.ToString(),
-				Language = a.Book.Language
-			}).ToList();
+		using var csv = new CsvWriter(new System.IO.StreamWriter(saveFilePath), CultureInfo.CurrentCulture);
+		csv.WriteHeader(typeof(ExportDto));
+		csv.NextRecord();
+		csv.WriteRecords(dtos);
 	}
-	public static class LibraryExporter
+
+	public static void ToJson(string saveFilePath, IEnumerable<LibraryBook>? libraryBooks = null)
 	{
-		public static void ToCsv(string saveFilePath)
-		{
-			var dtos = DbContexts.GetLibrary_Flat_NoTracking().ToDtos();
-			if (!dtos.Any())
-				return;
-
-			using var writer = new System.IO.StreamWriter(saveFilePath);
-			using var csv = new CsvWriter(writer, System.Globalization.CultureInfo.CurrentCulture);
-
-			csv.WriteHeader(typeof(ExportDto));
-			csv.NextRecord();
-			csv.WriteRecords(dtos);
-		}
-
-		public static void ToJson(string saveFilePath)
-		{
-			var dtos = DbContexts.GetLibrary_Flat_NoTracking().ToDtos();
-			var json = Newtonsoft.Json.JsonConvert.SerializeObject(dtos, Newtonsoft.Json.Formatting.Indented);
-			System.IO.File.WriteAllText(saveFilePath, json);
-		}
-
-		public static void ToXlsx(string saveFilePath)
-		{
-			var dtos = DbContexts.GetLibrary_Flat_NoTracking().ToDtos();
-
-			var workbook = new XSSFWorkbook();
-			var sheet = workbook.CreateSheet("Library");
-
-			var detailSubtotalFont = workbook.CreateFont();
-			detailSubtotalFont.IsBold = true;
-
-			var detailSubtotalCellStyle = workbook.CreateCellStyle();
-			detailSubtotalCellStyle.SetFont(detailSubtotalFont);
-
-			// headers
-			var rowIndex = 0;
-			var row = sheet.CreateRow(rowIndex);
-
-			var columns = new[] {
-				nameof(ExportDto.Account),
-				nameof(ExportDto.DateAdded),
-				nameof(ExportDto.AudibleProductId),
-				nameof(ExportDto.Locale),
-				nameof(ExportDto.Title),
-				nameof(ExportDto.AuthorNames),
-				nameof(ExportDto.NarratorNames),
-				nameof(ExportDto.LengthInMinutes),
-				nameof(ExportDto.Description),
-				nameof(ExportDto.Publisher),
-				nameof(ExportDto.HasPdf),
-				nameof(ExportDto.SeriesNames),
-				nameof(ExportDto.SeriesOrder),
-				nameof(ExportDto.CommunityRatingOverall),
-				nameof(ExportDto.CommunityRatingPerformance),
-				nameof(ExportDto.CommunityRatingStory),
-				nameof(ExportDto.PictureId),
-				nameof(ExportDto.IsAbridged),
-				nameof(ExportDto.DatePublished),
-				nameof(ExportDto.CategoriesNames),
-				nameof(ExportDto.MyRatingOverall),
-				nameof(ExportDto.MyRatingPerformance),
-				nameof(ExportDto.MyRatingStory),
-				nameof(ExportDto.MyLibationTags),
-				nameof(ExportDto.BookStatus),
-				nameof(ExportDto.PdfStatus),
-				nameof(ExportDto.ContentType),
-				nameof(ExportDto.AudioFormat),
-                nameof(ExportDto.Language)
-            };
-			var col = 0;
-			foreach (var c in columns)
-			{
-				var cell = row.CreateCell(col++);
-				var name = ExportDto.GetName(c);
-				cell.SetCellValue(name);
-				cell.CellStyle = detailSubtotalCellStyle;
-			}
-
-			var dateFormat = workbook.CreateDataFormat();
-			var dateStyle = workbook.CreateCellStyle();
-			dateStyle.DataFormat = dateFormat.GetFormat("MM/dd/yyyy HH:mm:ss");
-
-			rowIndex++;
-
-			// Add data rows
-			foreach (var dto in dtos)
-			{
-				col = 0;
-
-				row = sheet.CreateRow(rowIndex);
-
-				row.CreateCell(col++).SetCellValue(dto.Account);
-
-				var dateAddedCell = row.CreateCell(col++);
-				dateAddedCell.CellStyle = dateStyle;
-				dateAddedCell.SetCellValue(dto.DateAdded);
-
-				row.CreateCell(col++).SetCellValue(dto.AudibleProductId);
-				row.CreateCell(col++).SetCellValue(dto.Locale);
-				row.CreateCell(col++).SetCellValue(dto.Title);
-				row.CreateCell(col++).SetCellValue(dto.AuthorNames);
-				row.CreateCell(col++).SetCellValue(dto.NarratorNames);
-				row.CreateCell(col++).SetCellValue(dto.LengthInMinutes);
-				row.CreateCell(col++).SetCellValue(dto.Description);
-				row.CreateCell(col++).SetCellValue(dto.Publisher);
-				row.CreateCell(col++).SetCellValue(dto.HasPdf);
-				row.CreateCell(col++).SetCellValue(dto.SeriesNames);
-				row.CreateCell(col++).SetCellValue(dto.SeriesOrder);
-
-				col = createCell(row, col, dto.CommunityRatingOverall);
-				col = createCell(row, col, dto.CommunityRatingPerformance);
-				col = createCell(row, col, dto.CommunityRatingStory);
-
-				row.CreateCell(col++).SetCellValue(dto.PictureId);
-				row.CreateCell(col++).SetCellValue(dto.IsAbridged);
-
-				var datePubCell = row.CreateCell(col++);
-				datePubCell.CellStyle = dateStyle;
-				if (dto.DatePublished.HasValue)
-					datePubCell.SetCellValue(dto.DatePublished.Value);
-				else
-					datePubCell.SetCellValue("");
-
-				row.CreateCell(col++).SetCellValue(dto.CategoriesNames);
-
-				col = createCell(row, col, dto.MyRatingOverall);
-				col = createCell(row, col, dto.MyRatingPerformance);
-				col = createCell(row, col, dto.MyRatingStory);
-
-				row.CreateCell(col++).SetCellValue(dto.MyLibationTags);
-				row.CreateCell(col++).SetCellValue(dto.BookStatus);
-				row.CreateCell(col++).SetCellValue(dto.PdfStatus);
-				row.CreateCell(col++).SetCellValue(dto.ContentType);
-                row.CreateCell(col++).SetCellValue(dto.AudioFormat);
-                row.CreateCell(col++).SetCellValue(dto.Language);
-
-                rowIndex++;
-			}
-
-			using var fileData = new System.IO.FileStream(saveFilePath, System.IO.FileMode.Create);
-			workbook.Write(fileData);
-		}
-		private static int createCell(NPOI.SS.UserModel.IRow row, int col, float? nullableFloat)
-		{
-			if (nullableFloat.HasValue)
-				row.CreateCell(col++).SetCellValue(nullableFloat.Value);
-			else
-				row.CreateCell(col++).SetCellValue("");
-			return col;
-		}
+		libraryBooks ??= DbContexts.GetLibrary_Flat_NoTracking();
+		var dtos = libraryBooks.ToDtos();
+		var serializer = new JsonSerializer();
+		using var writer = new JsonTextWriter(new System.IO.StreamWriter(saveFilePath)) { Formatting = Formatting.Indented };
+		serializer.Serialize(writer, dtos);
 	}
+
+	public static void ToXlsx(string saveFilePath, IEnumerable<LibraryBook>? libraryBooks = null)
+	{
+		libraryBooks ??= DbContexts.GetLibrary_Flat_NoTracking();
+		var dtos = libraryBooks.ToDtos();
+
+		using var workbook = new XLWorkbook();
+		var sheet = workbook.AddWorksheet("Library");
+		var columns = typeof(ExportDto).GetProperties().Where(p => p.GetCustomAttribute<NameAttribute>() is not null).ToArray();
+
+		// headers
+		var currentRow = sheet.FirstRow();
+		var currentCell = currentRow.FirstCell();
+		foreach (var column in columns)
+		{
+			currentCell.Value = GetColumnName(column);
+			currentCell.Style.Font.Bold = true;
+			currentCell = currentCell.CellRight();
+		}
+
+		var dateFormat = CultureInfo.CurrentCulture.DateTimeFormat.ShortDatePattern + " HH:mm:ss";
+
+		// Add data rows
+		foreach (var dto in dtos)
+		{
+			currentRow = currentRow.RowBelow();
+			currentCell = currentRow.FirstCell();
+
+			foreach (var column in columns)
+			{
+				var value = column.GetValue(dto);
+				currentCell.Value = XLCellValue.FromObject(value);
+				currentCell.Style.DateFormat.Format = currentCell.DataType is XLDataType.DateTime ? dateFormat : string.Empty;
+				currentCell = currentCell.CellRight();
+			}
+		}
+
+		workbook.SaveAs(saveFilePath);
+	}
+
+	private static List<ExportDto> ToDtos(this IEnumerable<LibraryBook> library)
+		=> library.Select(a => new ExportDto(a)).ToList();
+
+	private static string GetColumnName(PropertyInfo property)
+		=> property.GetCustomAttribute<NameAttribute>()?.Names?.FirstOrDefault() ?? property.Name;
 }

Source/ApplicationServices/MainSearchEngine.cs

@@ -0,0 +1,15 @@
+using LibationSearchEngine;
+
+namespace ApplicationServices;
+
+/// <summary>
+/// The main search engine used Libation.
+/// Acts as an adapter to SearchEngineCommands.Search()
+/// </summary>
+public class MainSearchEngine : ISearchEngine
+{
+	public static MainSearchEngine Instance { get; } = new MainSearchEngine();
+	private MainSearchEngine() { }
+	public SearchResultSet? GetSearchResultSet(string? searchString)
+		=> string.IsNullOrEmpty(searchString) ? null : SearchEngineCommands.Search(searchString);
+}

Source/ApplicationServices/RecordExporter.cs

@@ -1,198 +1,185 @@
 using AudibleApi.Common;
+using ClosedXML.Excel;
 using CsvHelper;
 using DataLayer;
 using Newtonsoft.Json.Linq;
-using NPOI.XSSF.UserModel;
 using System;
 using System.Collections.Generic;
+using System.Globalization;
 using System.Linq;
 
-namespace ApplicationServices
+namespace ApplicationServices;
+
+public static class RecordExporter
 {
-	public static class RecordExporter
+	public static void ToXlsx(string saveFilePath, IEnumerable<IRecord> records)
 	{
-		public static void ToXlsx(string saveFilePath, IEnumerable<IRecord> records)
+		if (!records.Any())
+			return;
+
+		using var workbook = new XLWorkbook();
+		var worksheet = workbook.AddWorksheet("Records");
+
+		// headers
+		var columns = new List<string>
 		{
-			if (!records.Any())
-				return;
+			nameof(Type.Name),
+			nameof(IRecord.Created),
+			nameof(IRecord.Start) + "_ms",
+		};
 
-			using var workbook = new XSSFWorkbook();
-			var sheet = workbook.CreateSheet("Records");
+		if (records.OfType<IAnnotation>().Any())
+		{
+			columns.Add(nameof(IAnnotation.AnnotationId));
+			columns.Add(nameof(IAnnotation.LastModified));
+		}
+		if (records.OfType<IRangeAnnotation>().Any())
+		{
+			columns.Add(nameof(IRangeAnnotation.End) + "_ms");
+			columns.Add(nameof(IRangeAnnotation.Text));
+		}
+		if (records.OfType<Clip>().Any())
+			columns.Add(nameof(Clip.Title));
 
-			var detailSubtotalFont = workbook.CreateFont();
-			detailSubtotalFont.IsBold = true;
+		int rowIndex = 1, col = 1;
+		var headerRow = worksheet.Row(rowIndex++);
+		foreach (var c in columns)
+		{
+			var headerCell = headerRow.Cell(col++);
+			headerCell.Value = c;
+			headerCell.Style.Font.Bold = true;
+		}
 
-			var detailSubtotalCellStyle = workbook.CreateCellStyle();
-			detailSubtotalCellStyle.SetFont(detailSubtotalFont);
+		var dateFormat = CultureInfo.CurrentCulture.DateTimeFormat.ShortDatePattern + " HH:mm:ss";
 
-			// headers
-			var rowIndex = 0;
-			var row = sheet.CreateRow(rowIndex);
+		// Add data rows
+		foreach (var record in records)
+		{
+			col = 1;
+			var row = worksheet.Row(rowIndex++);
 
-			var columns = new List<string>
+			row.Cell(col++).Value = record.GetType().Name;
+			row.Cell(col++).SetDate(record.Created.DateTime, dateFormat);
+			row.Cell(col++).Value = record.Start.TotalMilliseconds;
+
+			if (record is IAnnotation annotation)
 			{
-				nameof(Type.Name),
-				nameof(IRecord.Created),
-				nameof(IRecord.Start) + "_ms",
-			};
 
-			if (records.OfType<IAnnotation>().Any())
-			{
-				columns.Add(nameof(IAnnotation.AnnotationId));
-				columns.Add(nameof(IAnnotation.LastModified));
-			}
-			if (records.OfType<IRangeAnnotation>().Any())
-			{
-				columns.Add(nameof(IRangeAnnotation.End) + "_ms");
-				columns.Add(nameof(IRangeAnnotation.Text));
-			}
-			if (records.OfType<Clip>().Any())
-				columns.Add(nameof(Clip.Title));
+				row.Cell(col++).Value = annotation.AnnotationId;
+				row.Cell(col++).SetDate(annotation.LastModified.DateTime, dateFormat);
 
-			var col = 0;
-			foreach (var c in columns)
-			{
-				var cell = row.CreateCell(col++);
-				cell.SetCellValue(c);
-				cell.CellStyle = detailSubtotalCellStyle;
-			}
-
-			var dateFormat = workbook.CreateDataFormat();
-			var dateStyle = workbook.CreateCellStyle();
-			dateStyle.DataFormat = dateFormat.GetFormat("MM/dd/yyyy HH:mm:ss");
-
-			// Add data rows
-			foreach (var record in records)
-			{
-				col = 0;
-
-				row = sheet.CreateRow(++rowIndex);
-
-				row.CreateCell(col++).SetCellValue(record.GetType().Name);
-
-				var dateCreatedCell = row.CreateCell(col++);
-				dateCreatedCell.CellStyle = dateStyle;
-				dateCreatedCell.SetCellValue(record.Created.DateTime);
-
-				row.CreateCell(col++).SetCellValue(record.Start.TotalMilliseconds);
-
-				if (record is IAnnotation annotation)
+				if (annotation is IRangeAnnotation rangeAnnotation)
 				{
-					row.CreateCell(col++).SetCellValue(annotation.AnnotationId);
+					row.Cell(col++).Value = rangeAnnotation.End.TotalMilliseconds;
+					row.Cell(col++).Value = rangeAnnotation.Text;
 
-					var lastModifiedCell = row.CreateCell(col++);
-					lastModifiedCell.CellStyle = dateStyle;
-					lastModifiedCell.SetCellValue(annotation.LastModified.DateTime);
-
-					if (annotation is IRangeAnnotation rangeAnnotation)
-					{
-						row.CreateCell(col++).SetCellValue(rangeAnnotation.End.TotalMilliseconds);
-						row.CreateCell(col++).SetCellValue(rangeAnnotation.Text);
-
-						if (rangeAnnotation is Clip clip)
-							row.CreateCell(col++).SetCellValue(clip.Title);
-					}
+					if (rangeAnnotation is Clip clip)
+						row.Cell(col++).Value = clip.Title;
 				}
 			}
-
-			using var fileData = new System.IO.FileStream(saveFilePath, System.IO.FileMode.Create);
-			workbook.Write(fileData);
 		}
 
-		public static void ToJson(string saveFilePath, LibraryBook libraryBook, IEnumerable<IRecord> records)
+		workbook.SaveAs(saveFilePath);
+	}
+
+	private static void SetDate(this IXLCell cell, DateTime? value, string dateFormat)
+	{
+		cell.Value = value;
+		cell.Style.DateFormat.Format = dateFormat;
+	}
+	public static void ToJson(string saveFilePath, LibraryBook libraryBook, IEnumerable<IRecord> records)
+	{
+		if (!records.Any())
+			return;
+
+		var recordsEx = extendRecords(records);
+
+		var recordsObj = new JObject
 		{
-			if (!records.Any())
-				return;
+			{ "title", libraryBook.Book.TitleWithSubtitle},
+			{ "asin", libraryBook.Book.AudibleProductId},
+			{ "exportTime", DateTime.Now},
+			{ "records", JArray.FromObject(recordsEx) }
+		};
 
-			var recordsEx = extendRecords(records);
+		System.IO.File.WriteAllText(saveFilePath, recordsObj.ToString(Newtonsoft.Json.Formatting.Indented));
+	}
 
-			var recordsObj = new JObject
+	public static void ToCsv(string saveFilePath, IEnumerable<IRecord> records)
+	{
+		if (!records.Any())
+			return;
+
+		using var writer = new System.IO.StreamWriter(saveFilePath);
+		using var csv = new CsvWriter(writer, System.Globalization.CultureInfo.CurrentCulture);
+
+		//Write headers for the present record type that has the most properties
+		if (records.OfType<Clip>().Any())
+			csv.WriteHeader(typeof(ClipEx));
+		else if (records.OfType<Note>().Any())
+			csv.WriteHeader(typeof(NoteEx));
+		else if (records.OfType<Bookmark>().Any())
+			csv.WriteHeader(typeof(BookmarkEx));
+		else
+			csv.WriteHeader(typeof(LastHeardEx));
+
+		var recordsEx = extendRecords(records);
+
+		csv.NextRecord();
+		csv.WriteRecords(recordsEx.OfType<ClipEx>());
+		csv.WriteRecords(recordsEx.OfType<NoteEx>());
+		csv.WriteRecords(recordsEx.OfType<BookmarkEx>());
+		csv.WriteRecords(recordsEx.OfType<LastHeardEx>());
+	}
+
+	private static IEnumerable<IRecordEx> extendRecords(IEnumerable<IRecord> records)
+		=> records
+		.Select<IRecord, IRecordEx>(
+			r => r switch
 			{
-				{ "title", libraryBook.Book.Title},
-				{ "asin", libraryBook.Book.AudibleProductId},
-				{ "exportTime", DateTime.Now},
-				{ "records", JArray.FromObject(recordsEx) }
-			};
+				Clip c => new ClipEx(nameof(Clip), c),
+				Note n => new NoteEx(nameof(Note), n),
+				Bookmark b => new BookmarkEx(nameof(Bookmark), b),
+				LastHeard l => new LastHeardEx(nameof(LastHeard), l),
+				_ => throw new InvalidOperationException(),
+			});
 
-			System.IO.File.WriteAllText(saveFilePath, recordsObj.ToString(Newtonsoft.Json.Formatting.Indented));
-		}		
 
-		public static void ToCsv(string saveFilePath, IEnumerable<IRecord> records)
+	private interface IRecordEx { string Type { get; } }
+
+	private record LastHeardEx : LastHeard, IRecordEx
+	{
+		public string Type { get; }
+		public LastHeardEx(string type, LastHeard original) : base(original)
 		{
-			if (!records.Any())
-				return;
-
-			using var writer = new System.IO.StreamWriter(saveFilePath);
-			using var csv = new CsvWriter(writer, System.Globalization.CultureInfo.CurrentCulture);
-
-			//Write headers for the present record type that has the most properties
-			if (records.OfType<Clip>().Any())
-				csv.WriteHeader(typeof(ClipEx));
-			else if (records.OfType<Note>().Any())
-				csv.WriteHeader(typeof(NoteEx));
-			else if (records.OfType<Bookmark>().Any())
-				csv.WriteHeader(typeof(BookmarkEx));
-			else
-				csv.WriteHeader(typeof(LastHeardEx));
-
-			var recordsEx = extendRecords(records);
-
-			csv.NextRecord();
-			csv.WriteRecords(recordsEx.OfType<ClipEx>()); 
-			csv.WriteRecords(recordsEx.OfType<NoteEx>()); 
-			csv.WriteRecords(recordsEx.OfType<BookmarkEx>()); 
-			csv.WriteRecords(recordsEx.OfType<LastHeardEx>()); 
+			Type = type;
 		}
+	}
 
-		private static IEnumerable<IRecordEx> extendRecords(IEnumerable<IRecord> records)
-			=> records
-			.Select<IRecord, IRecordEx>(
-				r => r switch
-				{
-					Clip c => new ClipEx(nameof(Clip), c),
-					Note n => new NoteEx(nameof(Note), n),
-					Bookmark b => new BookmarkEx(nameof(Bookmark), b),
-					LastHeard l => new LastHeardEx(nameof(LastHeard), l),
-					_ => throw new InvalidOperationException(),
-				});
-
-
-		private interface IRecordEx { string Type { get; } }
-
-		private record LastHeardEx : LastHeard, IRecordEx
+	private record BookmarkEx : Bookmark, IRecordEx
+	{
+		public string Type { get; }
+		public BookmarkEx(string type, Bookmark original) : base(original)
 		{
-			public string Type { get; }
-			public LastHeardEx(string type, LastHeard original) : base(original)
-			{
-				Type = type;
-			}
+			Type = type;
 		}
+	}
 
-		private record BookmarkEx : Bookmark, IRecordEx
+	private record NoteEx : Note, IRecordEx
+	{
+		public string Type { get; }
+		public NoteEx(string type, Note original) : base(original)
 		{
-			public string Type { get; }
-			public BookmarkEx(string type, Bookmark original) : base(original)
-			{
-				Type = type;
-			}
+			Type = type;
 		}
+	}
 
-		private record NoteEx : Note, IRecordEx
+	private record ClipEx : Clip, IRecordEx
+	{
+		public string Type { get; }
+		public ClipEx(string type, Clip original) : base(original)
 		{
-			public string Type { get; }
-			public NoteEx(string type, Note original) : base(original)
-			{
-				Type = type;
-			}
-		}
-
-		private record ClipEx : Clip, IRecordEx
-		{
-			public string Type { get; }
-			public ClipEx(string type, Clip original) : base(original)
-			{
-				Type = type;
-			}
+			Type = type;
 		}
 	}
 }

Source/ApplicationServices/SearchEngineCommands.cs

@@ -1,20 +1,26 @@
-using System;
+using DataLayer;
+using LibationSearchEngine;
+using Serilog;
+using System;
 using System.Collections.Generic;
 using System.IO;
 using System.Linq;
-using DataLayer;
-using LibationSearchEngine;
 
-namespace ApplicationServices
+namespace ApplicationServices;
+
+public static class SearchEngineCommands
 {
-	public static class SearchEngineCommands
-	{
-		#region Search
-		public static SearchResultSet Search(string searchString) => performSafeQuery(e =>
-			e.Search(searchString)
-		);
+	/// <summary>Serializes all search index access so only one reader/writer is active at a time, avoiding write.lock contention.</summary>
+	private static readonly object IndexLock = new();
 
-		private static T performSafeQuery<T>(Func<SearchEngine, T> func)
+	#region Search
+	public static SearchResultSet Search(string searchString) => performSafeQuery(e =>
+		e.Search(searchString)
+	);
+
+	private static T performSafeQuery<T>(Func<SearchEngine, T> func)
+	{
+		lock (IndexLock)
 		{
 			var engine = new SearchEngine();
 			try
@@ -26,55 +32,72 @@ namespace ApplicationServices
 				fullReIndex(engine);
 				return func(engine);
 			}
-		}
-		#endregion
-
-		public static event EventHandler SearchEngineUpdated;
-
-		#region Update
-		private static bool isUpdating;
-
-		public static void UpdateBooks(IEnumerable<Book> books)
-		{
-			// Semi-arbitrary. At some point it's more worth it to do a full re-index than to do one offs.
-			// I did not benchmark before choosing the number here
-			if (books.Count() > 15)
-				FullReIndex();
-			else
+			catch (Exception ex) when (SearchEngine.IsRecoverableCorruptIndexException(ex))
 			{
-				foreach (var book in books)
-					UpdateUserDefinedItems(book);
+				Log.Warning(ex, "Search index unreadable or corrupt; rebuilding and retrying query.");
+				fullReIndex(engine);
+				return func(engine);
 			}
 		}
+	}
+	#endregion
 
-		public static void FullReIndex() => performSafeCommand(fullReIndex);
+	public static event EventHandler? SearchEngineUpdated;
 
-		internal static void UpdateUserDefinedItems(Book book) => performSafeCommand(e =>
-			{
-				e.UpdateLiberatedStatus(book);
-				e.UpdateTags(book.AudibleProductId, book.UserDefinedItem.Tags);
-				e.UpdateUserRatings(book);
-			}
-		);
+	#region Update
+	private static bool isUpdating;
 
-		private static void performSafeCommand(Action<SearchEngine> action)
+	public static void UpdateBooks(IEnumerable<LibraryBook> books)
+	{
+		// Semi-arbitrary. At some point it's more worth it to do a full re-index than to do one offs.
+		// I did not benchmark before choosing the number here
+		if (books.Count() > 15)
+			FullReIndex();
+		else
 		{
-			try
-			{
-				update(action);
-			}
-			catch (FileNotFoundException)
-			{
-				fullReIndex(new SearchEngine());
-				update(action);
-			}
+			foreach (var book in books)
+				UpdateUserDefinedItems(book);
 		}
+	}
 
-		private static void update(Action<SearchEngine> action)
+	public static void FullReIndex() => performSafeCommand(fullReIndex);
+	public static void FullReIndex(List<LibraryBook> libraryBooks)
+		=> performSafeCommand(se => fullReIndex(se, libraryBooks.WithoutParents()));
+
+	internal static void UpdateUserDefinedItems(LibraryBook book) => performSafeCommand(e =>
 		{
-			if (action is null)
-				return;
+			e.UpdateLiberatedStatus(book);
+			e.UpdateTags(book.Book.AudibleProductId, book.Book.UserDefinedItem.Tags);
+			e.UpdateUserRatings(book);
+		}
+	);
 
+	private static void performSafeCommand(Action<SearchEngine> action)
+	{
+		try
+		{
+			update(action);
+		}
+		catch (FileNotFoundException)
+		{
+			fullReIndex(new SearchEngine());
+			update(action);
+		}
+		catch (Exception ex) when (SearchEngine.IsRecoverableCorruptIndexException(ex))
+		{
+			Log.Warning(ex, "Search index unreadable or corrupt; rebuilding and retrying.");
+			fullReIndex(new SearchEngine());
+			update(action);
+		}
+	}
+
+	private static void update(Action<SearchEngine> action)
+	{
+		if (action is null)
+			return;
+
+		lock (IndexLock)
+		{
 			// support nesting incl recursion
 			var prevIsUpdating = isUpdating;
 			try
@@ -83,19 +106,22 @@ namespace ApplicationServices
 
 				action(new SearchEngine());
 				if (!prevIsUpdating)
-					SearchEngineUpdated?.Invoke(null, null);
+					SearchEngineUpdated?.Invoke(null, EventArgs.Empty);
 			}
 			finally
 			{
 				isUpdating = prevIsUpdating;
 			}
 		}
-
-		private static void fullReIndex(SearchEngine engine)
-		{
-			var library = DbContexts.GetLibrary_Flat_NoTracking();
-			engine.CreateNewIndex(library);
-		}
-		#endregion
 	}
+
+	private static void fullReIndex(SearchEngine engine)
+	{
+		var library = DbContexts.GetLibrary_Flat_NoTracking();
+		fullReIndex(engine, library);
+	}
+
+	private static void fullReIndex(SearchEngine engine, IEnumerable<LibraryBook> libraryBooks)
+	=> engine.CreateNewIndex(libraryBooks);
+	#endregion
 }

Source/ApplicationServices/TempSearchEngine.cs

@@ -0,0 +1,44 @@
+using DataLayer;
+using LibationFileManager;
+using LibationSearchEngine;
+using System.Collections.Generic;
+
+namespace ApplicationServices;
+
+/// <summary>
+/// A temporary search engine created in InProgress/TempSearchEngine
+/// Used for Trash Bin searches to avoid interfering with the main search engine
+/// </summary>
+public class TempSearchEngine : ISearchEngine
+{
+	public static string SearchEnginePath { get; }
+		= System.IO.Path.Combine(Configuration.Instance.InProgress, nameof(TempSearchEngine));
+	private SearchEngine SearchEngine { get; } = new SearchEngine(SearchEnginePath);
+
+	public bool ReindexSearchEngine(IEnumerable<LibraryBook> books)
+	{
+		try
+		{
+			SearchEngine.CreateNewIndex(books, overwrite: true);
+			return true;
+		}
+		catch
+		{
+			return false;
+		}
+	}
+	public SearchResultSet? GetSearchResultSet(string? searchString)
+	{
+		if (string.IsNullOrEmpty(searchString))
+			return null;
+
+		try
+		{
+			return SearchEngine.Search(searchString);
+		}
+		catch
+		{
+			return null;
+		}
+	}
+}

Source/AudibleUtilities/Account.cs

@@ -1,103 +1,98 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using AudibleApi;
+using AudibleApi;
 using AudibleApi.Authorization;
 using Dinah.Core;
 using Newtonsoft.Json;
+using System;
+using System.Diagnostics.CodeAnalysis;
 
-namespace AudibleUtilities
+namespace AudibleUtilities;
+
+public class Account : IUpdatable
 {
-	public class Account : IUpdatable
+	public event EventHandler? Updated;
+	private void update(object? sender = null, EventArgs? e = null)
+		=> Updated?.Invoke(this, EventArgs.Empty);
+
+	// canonical. immutable. email or phone number
+	public string AccountId { get; }
+
+	// user-friendly, non-canonical name. mutable
+	public string? AccountName
 	{
-		public event EventHandler Updated;
-		private void update(object sender = null, EventArgs e = null)
-			=> Updated?.Invoke(this, new EventArgs());
-
-		// canonical. immutable. email or phone number
-		public string AccountId { get; }
-
-		// user-friendly, non-canonical name. mutable
-		private string _accountName;
-		public string AccountName
+		get => field;
+		set
 		{
-			get => _accountName;
-			set
-			{
-				if (string.IsNullOrWhiteSpace(value))
-					return;
-				var v = value.Trim();
-				if (v == _accountName)
-					return;
-				_accountName = v;
-				update();
-			}
+			if (string.IsNullOrWhiteSpace(value))
+				return;
+			var v = value.Trim();
+			if (v == field)
+				return;
+			field = v;
+			update();
 		}
-
-		// whether to include this account when scanning libraries.
-		// technically this is an app setting; not an attribute of account. but since it's managed with accounts, it makes sense to put this exception-to-the-rule here
-		private bool _libraryScan = true;
-		public bool LibraryScan
-		{
-			get => _libraryScan;
-			set
-			{
-				if (value == _libraryScan)
-					return;
-				_libraryScan = value;
-				update();
-			}
-		}
-
-		private string _decryptKey = "";
-		/// <summary>aka: activation bytes</summary>
-		public string DecryptKey
-		{
-			get => _decryptKey;
-			set
-			{
-				var v = (value ?? "").Trim();
-				if (v == _decryptKey)
-					return;
-				_decryptKey = v;
-				update();
-			}
-		}
-
-		private Identity _identity;
-		public Identity IdentityTokens
-		{
-			get => _identity;
-			set
-			{
-				if (_identity is null && value is null)
-					return;
-
-				if (_identity is not null)
-					_identity.Updated -= update;
-
-				if (value is not null)
-					value.Updated += update;
-
-				_identity = value;
-				update();
-			}
-		}
-
-		[JsonIgnore]
-		public Locale Locale => IdentityTokens?.Locale;
-
-		public Account(string accountId)
-		{
-			AccountId = ArgumentValidator.EnsureNotNullOrWhiteSpace(accountId, nameof(accountId)).Trim();
-		}
-
-		public override string ToString() => $"{AccountId} - {Locale?.Name ?? "[empty]"}";
-
-		public string MaskedLogEntry => @$"AccountId={mask(AccountId)}|AccountName={mask(AccountName)}|Locale={Locale?.Name ?? "[empty]"}";
-		private static string mask(string str)
-			=> str is null ? "[null]"
-			: str == string.Empty ? "[empty]"
-			: str.ToMask();
 	}
+
+	// whether to include this account when scanning libraries.
+	// technically this is an app setting; not an attribute of account. but since it's managed with accounts, it makes sense to put this exception-to-the-rule here
+	public bool LibraryScan
+	{
+		get => field;
+		set
+		{
+			if (value == field)
+				return;
+			field = value;
+			update();
+		}
+	}
+
+	/// <summary>aka: activation bytes</summary>
+	[AllowNull]
+	public string? DecryptKey
+	{
+		get => field;
+		set
+		{
+			var v = (value ?? "").Trim();
+			if (v == field)
+				return;
+			field = v;
+			update();
+		}
+	}
+
+	public Identity? IdentityTokens
+	{
+		get => field;
+		set
+		{
+			if (field is null && value is null)
+				return;
+
+			if (field is not null)
+				field.Updated -= update;
+
+			if (value is not null)
+				value.Updated += update;
+
+			field = value;
+			update();
+		}
+	}
+
+	[JsonIgnore]
+	public Locale? Locale => IdentityTokens?.Locale;
+
+	public Account(string accountId)
+	{
+		AccountId = ArgumentValidator.EnsureNotNullOrWhiteSpace(accountId, nameof(accountId)).Trim();
+	}
+
+	public override string ToString() => $"{AccountId} - {Locale?.Name ?? "[empty]"}";
+
+	public string MaskedLogEntry => @$"AccountId={mask(AccountId)}|AccountName={mask(AccountName)}|Locale={Locale?.Name ?? "[empty]"}";
+	private static string mask(string? str)
+		=> str is null ? "[null]"
+		: str == string.Empty ? "[empty]"
+		: str.ToMask();
 }

Source/AudibleUtilities/AccountSettingsDecryptFailure.cs

@@ -0,0 +1,89 @@
+using AudibleApi.Authorization;
+
+namespace AudibleUtilities;
+
+/// <summary>
+/// Libation-facing helpers when AccountsSettings.json contains encrypted tokens
+/// that cannot be unlocked on this OS/machine (common when copying Windows config into Docker).
+/// </summary>
+public static class AccountSettingsDecryptFailure
+{
+	public const string LoadErrorCaption = "Error Loading Account Settings";
+
+	public const string FaqUrl
+		= "https://getlibation.com/docs/frequently-asked-questions#docker-finds-no-new-books-failed-to-decrypt-existingaccesstoken";
+
+	private static readonly string[] ThingsToTryBullets =
+	[
+		"Keep tokens encrypted: on the machine that created the file, export the master key (Settings -> Important -> Export encryption key..., or LibationCli export-master-key libation-master.key), then copy that file into the Docker/config folder next to AccountsSettings.json (or set LIBATION_MASTER_KEY_FILE / LIBATION_MASTER_KEY).",
+		"Or convert to plaintext: Settings -> Important, uncheck \"Store authentication tokens encrypted\", convert existing tokens when prompted, then copy the updated AccountsSettings.json again.",
+		"Or re-authenticate on this machine/container with LibationCli login-external or import-account.",
+		$"Details: {FaqUrl}",
+	];
+
+	/// <summary>
+	/// True when <paramref name="ex"/> (or an inner exception) is a decrypt failure from identity token JSON.
+	/// </summary>
+	public static bool TryFindInTree(Exception ex, out IdentityTokenDecryptException? match)
+	{
+		ArgumentNullException.ThrowIfNull(ex);
+		IdentityTokenDecryptException? found = null;
+		walk(ex);
+		match = found;
+		return found is not null;
+
+		void walk(Exception? e)
+		{
+			if (e is null || found is not null)
+				return;
+
+			if (e is IdentityTokenDecryptException decryptEx)
+			{
+				found = decryptEx;
+				return;
+			}
+
+			if (e is AggregateException agg)
+			{
+				foreach (var inner in agg.InnerExceptions)
+					walk(inner);
+			}
+
+			walk(e.InnerException);
+		}
+	}
+
+	public static IEnumerable<string> GetExplainerLines(Exception ex)
+	{
+		ArgumentNullException.ThrowIfNull(ex);
+
+		yield return "Encrypted authentication tokens in AccountsSettings.json could not be decrypted on this machine.";
+		yield return "The encryption key is stored in the OS secret store where the tokens were encrypted (for example Windows DPAPI) and does not travel when you copy the file to Docker or another computer.";
+		if (TryFindInTree(ex, out var decryptEx) && decryptEx is not null)
+			yield return $"Underlying error: {decryptEx.Message.TrimEnd('.')}.";
+		yield return string.Empty;
+		yield return "Things to try:";
+		foreach (var bullet in ThingsToTryBullets)
+			yield return "• " + bullet;
+	}
+
+	public static string GetExplainerBody(Exception ex)
+		=> string.Join("\r\n", GetExplainerLines(ex));
+
+	/// <summary>
+	/// Dialog body after backup-and-empty recovery when load failed due to token decrypt.
+	/// </summary>
+	public static string GetRecoveredDialogBody(Exception ex, string backupPath)
+	{
+		ArgumentNullException.ThrowIfNull(ex);
+		ArgumentException.ThrowIfNullOrWhiteSpace(backupPath);
+
+		return $"""
+			{GetExplainerBody(ex)}
+
+			Libation created a new, empty account settings file so the app can start. You will need to re-add your Audible account(s) (or copy a plaintext AccountsSettings.json) before scanning or downloading.
+
+			The previous account settings file was archived at '{backupPath}'
+			""";
+	}
+}

Source/AudibleUtilities/AccountTokenStorage.cs

@@ -0,0 +1,59 @@
+using AudibleApi.Authorization;
+
+namespace AudibleUtilities;
+
+/// <summary>
+/// Alignment and conversion helpers for identity tokens in <c>AccountsSettings.json</c>.
+/// Preference changes alone do not convert; conversion is explicit via <see cref="ConvertAllAccounts"/>.
+/// </summary>
+public static class AccountTokenStorage
+{
+	/// <summary>
+	/// Compare persisted encryption metadata for all account identities to <paramref name="method"/>.
+	/// </summary>
+	public static TokenStorageAlignment GetAccountsAlignment(TokenStorageMethod method, string? accountsSettingsFile = null)
+	{
+		var path = accountsSettingsFile ?? AudibleApiStorage.AccountsSettingsFile;
+		if (!File.Exists(path))
+			return TokenStorageAlignment.NoApplicableTokens;
+
+		using var persister = new AccountsSettingsPersister(path);
+		var alignments = new List<TokenStorageAlignment>();
+
+		foreach (var account in persister.AccountsSettings.Accounts)
+		{
+			if (account.IdentityTokens is null)
+				continue;
+
+			alignments.Add(IdentityTokenConversion.GetAlignment(account.IdentityTokens, method));
+		}
+
+		return CombineAlignments(alignments);
+	}
+
+	/// <summary>
+	/// Convert every identity in the accounts settings file to <paramref name="method"/>.
+	/// All-or-nothing: failure leaves the original file unchanged.
+	/// </summary>
+	public static IdentityTokenConversionResult ConvertAllAccounts(TokenStorageMethod method, string? accountsSettingsFile = null)
+	{
+		var path = accountsSettingsFile ?? AudibleApiStorage.AccountsSettingsFile;
+		return IdentityTokenConversion.ConvertAllIdentitiesInFile(path, method);
+	}
+
+	private static TokenStorageAlignment CombineAlignments(IReadOnlyList<TokenStorageAlignment> alignments)
+	{
+		if (alignments.Count == 0)
+			return TokenStorageAlignment.NoApplicableTokens;
+		if (alignments.Any(a => a == TokenStorageAlignment.Indeterminate))
+			return TokenStorageAlignment.Indeterminate;
+		if (alignments.All(a => a is TokenStorageAlignment.AllMatch or TokenStorageAlignment.NoApplicableTokens))
+		{
+			return alignments.Any(a => a == TokenStorageAlignment.AllMatch)
+				? TokenStorageAlignment.AllMatch
+				: TokenStorageAlignment.NoApplicableTokens;
+		}
+
+		return TokenStorageAlignment.SomeMismatch;
+	}
+}

Source/AudibleUtilities/AccountsSettings.cs

@@ -1,142 +1,158 @@
-using System;
-using System.Collections.Generic;
-using System.Linq;
-using AudibleApi;
+using AudibleApi;
 using AudibleApi.Authorization;
 using Dinah.Core;
 using Newtonsoft.Json;
+using System;
+using System.Collections.Generic;
+using System.Linq;
 
-namespace AudibleUtilities
+namespace AudibleUtilities;
+
+// 'AccountsSettings' is intentionally NOT IEnumerable<> so that properties can be added/extended
+// from newtonsoft (https://www.newtonsoft.com/json/help/html/SerializationGuide.htm):
+//   .NET :  IList, IEnumerable, IList<T>, Array
+//   JSON :  Array (properties on the collection will not be serialized)
+public class AccountsSettings : IUpdatable
 {
-	// 'AccountsSettings' is intentionally NOT IEnumerable<> so that properties can be added/extended
-	// from newtonsoft (https://www.newtonsoft.com/json/help/html/SerializationGuide.htm):
-	//   .NET :  IList, IEnumerable, IList<T>, Array
-	//   JSON :  Array (properties on the collection will not be serialized)
-	public class AccountsSettings : IUpdatable
+	public event EventHandler? Updated;
+	private void update(object? sender = null, EventArgs? e = null)
 	{
-		public event EventHandler Updated;
-		private void update(object sender = null, EventArgs e = null)
-		{
-			foreach (var account in Accounts)
-				validate(account);
-			update_no_validate();
-		}
-		private void update_no_validate() => Updated?.Invoke(this, new EventArgs());
-
-		public AccountsSettings() { }
-
-		// for some reason this will make the json instantiator use _accounts_json.set()
-		[JsonConstructor]
-		protected AccountsSettings(List<Account> accountsSettings) { }
-
-		#region Accounts
-		private List<Account> _accounts_backing = new List<Account>();
-		[JsonProperty(PropertyName = nameof(Accounts))]
-		private List<Account> _accounts_json
-		{
-			get => _accounts_backing;
-			// 'set' is only used by json deser
-			set
-			{
-				if (value is null)
-					return;
-
-				foreach (var account in value)
-					_add(account);
-
-				update_no_validate();
-			}
-		}
-		[JsonIgnore]
-		public IReadOnlyList<Account> Accounts => _accounts_json.AsReadOnly();
-		#endregion
-
-		#region de/serialize
-		public static AccountsSettings FromJson(string json)
-			=> JsonConvert.DeserializeObject<AccountsSettings>(json, Identity.GetJsonSerializerSettings());
-
-		public string ToJson(Formatting formatting = Formatting.Indented)
-			=> JsonConvert.SerializeObject(this, formatting, Identity.GetJsonSerializerSettings());
-		#endregion
-
-		// more common naming convention alias for internal collection
-		public IReadOnlyList<Account> GetAll() => Accounts;
-
-		public Account Upsert(string accountId, string locale)
-		{
-			var acct = GetAccount(accountId, locale);
-
-			if (acct is not null)
-				return acct;
-
-			var l = Localization.Get(locale);
-			var id = new Identity(l);
-
-			var account = new Account(accountId) { IdentityTokens = id };
-			Add(account);
-			return account;
-		}
-
-		public void Add(Account account)
-		{
-			_add(account);
-			update_no_validate();
-		}
-
-		public void _add(Account account)
-		{
+		foreach (var account in Accounts)
 			validate(account);
+		update_no_validate();
+	}
+	private void update_no_validate() => Updated?.Invoke(this, new EventArgs());
 
-			_accounts_backing.Add(account);
-			account.Updated += update;
-		}
+	public AccountsSettings() { }
 
-		public Account GetAccount(string accountId, string locale)
+	// for some reason this will make the json instantiator use _accounts_json.set()
+	[JsonConstructor]
+	protected AccountsSettings(List<Account> accountsSettings) { }
+
+	#region Accounts
+	private readonly List<Account> _accounts_backing = new List<Account>();
+	[JsonProperty(PropertyName = nameof(Accounts))]
+	private List<Account> _accounts_json
+	{
+		get => _accounts_backing;
+		// 'set' is only used by json deser
+		set
 		{
-			if (locale is null)
-				return null;
+			if (value is null)
+				return;
 
-			return Accounts.SingleOrDefault(a => a.AccountId == accountId && a.IdentityTokens.Locale.Name == locale);
-		}
+			foreach (var account in value)
+				_add(account);
 
-		public bool Delete(string accountId, string locale)
-		{
-			var acct = GetAccount(accountId, locale);
-			if (acct is null)
-				return false;
-			return Delete(acct);
-		}
-
-		public bool Delete(Account account)
-		{
-			if (!_accounts_backing.Contains(account))
-				return false;
-
-			account.Updated -= update;
-			var result = _accounts_backing.Remove(account);
 			update_no_validate();
-			return result;
-		}
-
-		private void validate(Account account)
-		{
-			ArgumentValidator.EnsureNotNull(account, nameof(account));
-
-			var accountId = account.AccountId;
-			var locale = account?.IdentityTokens?.Locale?.Name;
-
-			var acct = GetAccount(accountId, locale);
-
-			// new: ok
-			if (acct is null)
-				return;
-
-			// same account instance: ok
-			if (acct == account)
-				return;
-			
-			// same account id + locale, different instance: bad
-			throw new InvalidOperationException("Cannot add an account with the same account Id and Locale");
 		}
 	}
+
+	private string? _cdm;
+	[JsonProperty]
+	public string? Cdm
+	{
+		get => _cdm;
+		set
+		{
+			if (value is null)
+				return;
+
+			_cdm = value;
+			update_no_validate();
+		}
+	}
+
+	[JsonIgnore]
+	public IReadOnlyList<Account> Accounts => _accounts_json.AsReadOnly();
+	#endregion
+
+	#region de/serialize
+	public static AccountsSettings? FromJson(string json)
+		=> JsonConvert.DeserializeObject<AccountsSettings>(json, Identity.GetJsonSerializerSettings());
+
+	public string ToJson(Formatting formatting = Formatting.Indented)
+		=> JsonConvert.SerializeObject(this, formatting, Identity.GetJsonSerializerSettings());
+	#endregion
+
+	// more common naming convention alias for internal collection
+	public IReadOnlyList<Account> GetAll() => Accounts;
+
+	public Account Upsert(string accountId, string? locale)
+	{
+		var acct = GetAccount(accountId, locale);
+
+		if (acct is not null)
+			return acct;
+
+		var l = Localization.Get(locale);
+		var id = new Identity(l);
+
+		// Match GUI default for new rows (WinForms/Avalonia): include account in library scans.
+		var account = new Account(accountId) { IdentityTokens = id, LibraryScan = true };
+		Add(account);
+		return account;
+	}
+
+	public void Add(Account account)
+	{
+		_add(account);
+		update_no_validate();
+	}
+
+	public void _add(Account account)
+	{
+		validate(account);
+
+		_accounts_backing.Add(account);
+		account.Updated += update;
+	}
+
+	public Account? GetAccount(string accountId, string? locale)
+	{
+		if (locale is null)
+			return null;
+
+		return Accounts.SingleOrDefault(a => a.AccountId == accountId && a.Locale?.Name == locale);
+	}
+
+	public bool Delete(string accountId, string locale)
+	{
+		var acct = GetAccount(accountId, locale);
+		if (acct is null)
+			return false;
+		return Delete(acct);
+	}
+
+	public bool Delete(Account account)
+	{
+		if (!_accounts_backing.Contains(account))
+			return false;
+
+		account.Updated -= update;
+		var result = _accounts_backing.Remove(account);
+		update_no_validate();
+		return result;
+	}
+
+	private void validate(Account account)
+	{
+		ArgumentValidator.EnsureNotNull(account, nameof(account));
+
+		var accountId = account.AccountId;
+		var locale = account?.IdentityTokens?.Locale?.Name;
+
+		var acct = GetAccount(accountId, locale);
+
+		// new: ok
+		if (acct is null)
+			return;
+
+		// same account instance: ok
+		if (acct == account)
+			return;
+
+		// same account id + locale, different instance: bad
+		throw new InvalidOperationException("Cannot add an account with the same account Id and Locale");
+	}
 }