Playlist AI v0.15.0 — Safer, faster, more reliable

Playlist AI v0.15.0 🎧

v0.15.0 is a reliability and correctness release. It makes local asset installation transactional, keeps recommendation and feedback state consistent, improves first-run setup and exports, and removes several sources of misleading success or stale UI state.

Important

Upgrading an affected Windows v0.14.x installation: save your work, close every Playlist AI window, and run the matching v0.15.0 Windows installer from this release in the existing installation directory. If Playlist AI remains in Task Manager, restart Windows first. Your settings, downloaded models, and playlist history do not need to be reset.

✨ Highlights

• Safer Windows updates. The installer now fails clearly when Windows prevents the executable from being replaced, and the updater verifies the installed version instead of trusting a successful installer exit code alone.
• Faster startup. CLAP and MERT integrity checks and native worker startup now run in the background with cancellation and stale-result protection.
• More reliable setup. Fresh setup requires every supported step, enables MERT and DSP by default, checks for installed analysis assets before offering a download, and keeps failed completion attempts open for retry.
• Stronger playlist correctness. Required journey waypoints keep the separation they need, explicit references can participate in MERT retrieval even without Deej-AI vectors, and exposure penalties now apply consistently to dynamic recordings.
• Exports survive navigation. Export progress, results, errors, and the exact selected playlist remain attached to the originating review draft.
• Cleaner playlist and settings screens. Internal selection commentary has been removed, current recommendation choices are focused on Enhanced hybrid and Deej-AI only, and historical modes remain available when replaying older results.

🛡️ Installation and recovery

Catalog and runtime installation paths received a substantial safety overhaul:

• Catalog archives are validated before publication, including portable filenames, Windows reserved names, case-insensitive collisions, file counts, declared sizes, and SHA-256 digests.
• Catalogs are extracted into an operation-owned staging area and activated only after the complete generation verifies successfully.
• A recovery journal can restore interrupted catalog replacements, while shared OS-backed leases prevent an active catalog from being replaced underneath open SQLite or mapped-vector readers.
• MusicBrainz index locks now follow process lifetime, so a crashed process does not leave a permanent time-based lock. Corrupt indexes are repaired into a verified sibling before activation.
• The pinned local text runtime installs into a private child profile, validates complete primary and CPU generations, and switches the active generation without deleting an independent or previously working runtime.
• CSV exports are staged and synchronized before publication. Existing or concurrently created destinations are preserved unless overwrite consent applies to the same captured file.

🎼 Recommendation and feedback correctness

• Journey generation reserves the candidates needed to separate same-artist required waypoints before filling optional positions.
• A bounded artist-group search handles feasible journeys that greedy sequencing misses. Exhaustion returns an honest partial result instead of claiming the constraints were satisfied.
• Explicit positive and negative track references retain their identity without a dense Deej-AI vector and can participate in MERT evidence acquisition, retrieval, ranking, discovery, and history replay.
• Recording-level exposure penalties now cover dynamic tracks as well as dense catalog tracks.
• Dense and content-based taste projections use the same effective feedback reducer. The latest direct choice wins within its scope, request feedback overrides durable state, and stable sequence numbers resolve equal timestamps across reopen and database maintenance.
• Feedback choices, pending state, and errors remain with the playlist workspace when navigating between screens.

🧭 Setup and interface improvements

• MERT music analysis and DSP preview are enabled automatically for fresh installations and no longer present optional enable/disable controls during setup.
• Already-installed model and analysis assets are detected before download actions are shown.
• Setup completion revalidates readiness and presents a retry path if preferences cannot be saved.
• Existing completed installations retain explicit rules-only or preview-off choices during repair.
• Removed current recommendation modes migrate once to Enhanced hybrid; AcousticBrainz-first and CLAP-first policies remain readable for historical results.
• Playlist screens omit internal matching and missing-context commentary while preserving actionable partial-result notices.
• Soundiiz share URLs and URL-bearing opener failures are excluded from normal logs.
• Privacy copy now describes automatic metadata lookup and explicit export handoff more precisely.

⚡ Performance

The remediation also removes avoidable work from common paths. On the recorded Windows development host:

Operation	Before	After
History listing: 50 records with 256 KiB evidence each	45.7–54.4 ms; ~27.8 MB/op	98–189 μs; ~26.7 KB/op
Dynamic reference lookup: 10,000 rows	3.38 ms; ~1.52 MB/op	85.5 μs; ~20.2 KB/op
Host construction with installed CLAP and MERT	5.94–6.06 s	4.52–5.94 ms

These are short synthetic or local measurements on an Intel Core Ultra 9 285H with warm filesystem caches. They establish the measured code-path improvement, not performance on every computer or musical-quality gains.

🔧 Model export and maintainer tooling

• Exporter preflight now reads the same exact requirement files used by pip.
• The offline CLAP and MERT export environments use updated, pinned dependencies, including Transformers 5.10.1 and ONNX Runtime 1.26.0.
• A manual-only model export parity workflow validates hash-pinned sources in an isolated CPU environment and retains bounded JSON reports without publishing or activating model graphs.
• Fresh local exports passed tokenizer, preprocessing, tensor, and cosine-parity fixtures for both CLAP and MERT. These checks validate numerical compatibility; they do not measure recommendation quality.

📦 Compatibility

• New recommendations use multichannel/v30; new taste projections use taste-profile/v3.
• Existing saved results, history, and taste snapshots remain readable. Recreating an old playlist under the new algorithm version may produce a different result.
• Feedback storage remains schema version 1 with an additive sequence field. Existing events are migrated transactionally and retain their order.
• Historical AcousticBrainz-first and CLAP-first results remain replayable.
• MERT, CLAP, and Deej-AI embedding identities, graph hashes, preprocessing contracts, and caches remain separate.
• No model pack, recommendation catalog, or user data is bundled into the application release.

✅ Validation

The merged release tree passed the repository's Windows gate, including frontend typechecking and production build, 216 frontend tests, Go vet, the native CGO race suite, golangci-lint with zero issues, Windows installer replacement fixtures, and release-asset policy checks. Linux, macOS, Linux arm64, Windows amd64, and Windows arm64 hosted build checks also passed before the release tag was created.

The separate 95% coverage target remains open: backend statement coverage was 82.39%, frontend statements 94.83%, branches 89.21%, functions 93.39%, and lines 97.26%. No packages or assertions were excluded to inflate those figures.

Native installed-app updating from v0.14.2 to v0.15.0, native save-picker interaction on every platform, and inference under low-memory or GPU contention were not exercised as part of the recorded local validation.

📥 Downloads

Choose the package for your operating system and architecture from the assets below:

• Windows: amd64 or arm64 installer; portable ZIPs are also available.
• macOS: Apple silicon DMG or ZIP.
• Linux: x86-64 and arm64 AppImage, DEB, RPM, Arch package, or portable tarball.

Code signing and notarization depend on the release credentials configured in GitHub Actions. An unsigned package may display the normal operating-system trust warning on first launch.

📚 More information

• Application update behavior and Windows recovery
• Implementation and validation record
• Startup and setup readiness
• Full changes since v0.14.2

Thanks for using Playlist AI. 💜

Playlist AI v0.14.2 — Ready by default, quieter playlists

A smoother first run, sensible audio defaults, and a quieter Playlist screen.

Playlist AI v0.14.2 tightens setup so a completed wizard means the app is ready to generate playlists. Music analysis, MERT similarity, and DSP preview measurements are active by default, recommendation choices are clearer, and internal selection commentary no longer competes with the music.

✨ What’s new

✅ Setup now finishes with everything ready

Every step shown by the setup wizard is required before continuing. The wizard no longer offers Skip for now paths that could leave a partially configured installation.

• Catalog, metadata, language understanding, CLAP music analysis, MERT similarity, and preview setup must be ready when their step is shown.
• An existing compatible music-analysis installation is detected before offering a download and immediately enables Continue.
• Status failures now offer a clear retry path instead of silently allowing incomplete setup.
• Completed installations remain recognized, so healthy assets are not downloaded again.

🎧 MERT and DSP are ready by default

Enhanced hybrid now consistently uses its local audio tools whenever they are available.

• MERT audio similarity is enabled automatically after its verified model is installed.
• DSP preview measurements are enabled automatically and no longer have a separate checkbox.
• Preferences saved by older releases with either feature disabled no longer turn off these Enhanced hybrid inputs.
• Download, analysis, cancellation, and cache-management controls remain available in Settings.

🎛️ Clearer recommendation choices

Settings now presents the two recommendation modes intended for regular use:

Mode	Best for
Enhanced hybrid	Combining compatible catalog, metadata, CLAP, MERT, DSP, and listening-history evidence
Deej-AI only	Using the original deterministic embedding walk without the enhanced evidence stack

The separate AcousticBrainz-first and CLAP-first choices have been removed from the selector. Saved playlists retain their original generation data and mode metadata.

🧹 A quieter Playlist screen

Playlist results now focus on tracks and actionable limitations.

• Removed Close match labels and their incomplete/conflicting-evidence explanation.
• Removed the “Strong matches were preferred…” selection summary.
• Removed the optional artist/album context outage message when existing references and musical evidence were already sufficient.
• Actionable lookup failures, true shortfalls, and partial-result notices remain visible.
• Suppressed technical context remains available in session diagnostics for troubleshooting.

ℹ️ Clear application identity

The bottom of Settings now shows the running Playlist AI version, author Paul Pietkiewicz, and the GPL-3.0 license in a subdued, legible footer.

📦 Downloads

Choose the installer for the simplest setup, or a portable archive when you need one.

Platform	Packages
Windows x64	NSIS installer and portable ZIP
Windows ARM64	NSIS installer and portable ZIP
Linux x64	AppImage, DEB, RPM, Arch package, and portable TAR.GZ
Linux ARM64	AppImage, DEB, RPM, Arch package, and portable TAR.GZ
macOS Apple Silicon	DMG and portable application ZIP
Windows package metadata	winget manifest ZIP

The catalog and model packs download separately through the app’s verified setup flow. They are not bundled into the application installers.

🔄 Upgrading from v0.14.0 or v0.14.1

Install the package for your platform over the existing application. Your settings, catalog, model files, saved playlists, history, and taste data remain in place. On launch, setup checks the assets already installed and shows only required work that is still missing.

Because MERT and DSP are now part of the default Enhanced hybrid configuration, older saved preferences that disabled them are intentionally superseded. Existing cached analysis is reused when compatible.

🧪 Validation

• The release-preparation PR passed the complete CI gate and CodeQL analysis.
• Native application and package builds passed for Windows x64/ARM64, Linux x64/ARM64, and macOS Apple Silicon.
• Windows builds passed the compiled audio-worker capability check.
• The production binary reports version 0.14.2.
• Release publication validated all 17 expected application and winget assets, each with an uploaded SHA-256 digest.
• Focused frontend and bridge regressions cover required setup readiness, installed-model detection, automatic audio defaults, simplified settings, and Playlist notice filtering.

📚 Included work

• Require complete setup, enable audio defaults, simplify Settings, and clean up Playlist presentation
• Compare v0.14.1...v0.14.2

---

Playlist AI is local-first free software by Paul Pietkiewicz, licensed under GPL-3.0.

Playlist AI v0.14.1 — More resilient Windows builds

Reliable native builds on Windows

Playlist AI v0.14.1 is a maintenance release focused on making Windows CI and release packaging resilient to temporary upstream download failures. It keeps the platform-specific CLAP and MERT setup introduced in v0.14.0 and ships freshly validated installers for every supported target.

Highlights

🛠️ Windows setup now survives transient download failures

The Windows build pipeline downloads two build-time tools: the pinned LLVM-MinGW compiler used for native CLAP support and the official pnpm installer. A temporary HTTP 504 previously stopped the entire CI or release job on its first attempt.

Both downloads now:

• retry up to three times with bounded 2-second and 4-second delays;
• remove partial files before each retry;
• preserve the pinned source, version, and SHA-256 verification for LLVM-MinGW; and
• retain the existing pnpm version and executable health checks.

Permanent failures still stop the build clearly, and an unverified compiler archive can never be activated.

📦 LAION CLAP preparation dependency refresh

The optional offline environment used to prepare the original LAION CLAP checkpoint now pins Torch 2.13.0 instead of 2.9.1. Python remains limited to the offline model-preparation workflow; the Playlist AI desktop application still uses compiled Go and native ONNX Runtime components.

🔒 No application or data migration

This patch does not change recommendation behavior, saved playlists, taste data, model-pack URLs, cached embeddings, or local privacy behavior. Existing v0.14.0 installations can update normally.

Downloads

Fresh packages are attached for every supported release target:

Platform	Packages
Windows amd64	NSIS installer and portable ZIP
Windows ARM64	NSIS installer and portable ZIP
Linux amd64	AppImage, DEB, RPM, Arch package, and portable TAR.GZ
Linux ARM64	AppImage, DEB, RPM, Arch package, and portable TAR.GZ
macOS Apple Silicon	DMG and portable application ZIP
Windows package metadata	winget manifest ZIP

The application downloads the selected catalog and optional model packs separately through the existing verified setup flow; large model files are not bundled into these installers.

Validation

• All five native release packaging jobs completed successfully.
• Windows amd64 and ARM64 installers completed with the hardened download path.
• Linux amd64, Linux ARM64, and macOS builds passed.
• GitHub Release asset validation and winget manifest generation passed.
• The release contains all 17 expected assets.
• The release preparation PR passed the complete CI matrix and CodeQL analysis.
• The offline retry regressions verify attempt limits, backoff timing, partial-file cleanup, terminal failures, checksum rejection, and installed-toolchain reuse.

Included changes

• Update the LAION CLAP preparation Torch dependency
• Retry transient Windows build-tool downloads
• Prepare v0.14.1 package metadata

See the complete comparison with v0.14.0.

Playlist AI v0.14.0 — Platform-ready models, cleaner setup

Platform-ready models. A cleaner setup flow.

This release makes model distribution predictable across supported desktop targets, simplifies optional MERT setup, and removes retired model and metadata paths from the application.

Highlights

🎯 The right model pack for the right machine

CLAP and MERT now resolve immutable, platform-specific manifests using the current operating system and architecture. The app selects the matching native ONNX Runtime library and verifies the downloaded manifest before extracting any archive parts.

Published CLAP packs are available for:

Platform	Architectures
Windows	amd64, arm64
Linux	amd64, arm64
macOS	arm64 (Apple Silicon)

macOS Intel is reported as unsupported because the pinned ONNX Runtime release does not provide the required macOS Intel runtime.

✨ A simpler optional MERT experience

MERT remains available for audio-to-audio similarity in Enhanced hybrid, but Settings no longer shows the large model-detail panel, revision and size readout, manual manifest field, or individual removal button. The normal setup path downloads the verified pack from Playlist AI’s Cloudflare R2 archive.

Use Reset models and datasets when you want to remove app-managed models, MERT files, cached representations, and model download caches together.

🧰 Reproducible CLAP packaging

The repository now includes the preparation workflow for the original LAION CLAP checkpoint: download, convert, verify, compress, split into upload-safe parts, and reassemble from a manifest. Each archive part stays below 200 MB, and the published manifests are pinned by SHA-256 and byte count.

🧹 Smaller, focused application surface

The retired DistilBERT intent-model path and Discogs metadata path have been removed. MusicBrainz remains the local metadata source, while the built-in rules and llama.cpp paths continue to handle prompt interpretation.

Downloads

The release workflow builds and validates native packages for every shipped target:

• Windows amd64: NSIS installer and portable ZIP
• Windows arm64: NSIS installer and portable ZIP
• Linux amd64: AppImage, DEB, RPM, Arch package, and portable TAR.GZ
• Linux arm64: AppImage, DEB, RPM, Arch package, and portable TAR.GZ
• macOS arm64: DMG and portable application ZIP
• Windows package metadata: winget manifest ZIP

The catalog and optional model packs are downloaded by the application when selected; they are not bundled into these installers.

Trust, privacy, and licensing

Model manifests and archive parts are verified before installation. Audio previews are processed locally for supported analysis, and derived representations remain on the device.

MERT is optional and remains subject to its CC-BY-NC-4.0 noncommercial license. CLAP and native runtime components retain their upstream license terms, which are included with the prepared packs.

Validation

• All five native package jobs completed successfully in CI.
• GitHub Release asset validation completed successfully.
• winget manifest generation completed successfully.
• 204 frontend tests passed.
• TypeScript typechecking and production frontend build passed.
• go vet passed.
• Race-enabled Go tests passed across the repository.
• golangci-lint reported 0 issues.
• Dark and light browser captures passed at 390px and 1000px widths.
• All five published CLAP R2 manifests matched their local SHA-256 hashes and byte counts, with every archive part present at the expected size.

Upgrade notes

Existing playlists and taste data are preserved. Existing installed MERT data remains usable after upgrading; the Settings screen simply presents the smaller control surface. Resetting models and datasets clears the app-managed model state and returns setup to its initial state.

For the complete change history, see the comparison with v0.13.0.

What's Changed

• feat(models): align platform packs and simplify model setup by @platten in #38
• chore(release): prepare v0.14.0 by @platten in #41

Full Changelog: v0.13.0...v0.14.0

Playlist AI v0.13.0 — Find more music with MERT and offline MusicBrainz

Playlist AI 0.13.0 turns MERT into a working recommendation source, adds a
downloadable offline MusicBrainz index, and gives the prompt parser a much richer
musical vocabulary. Together, these changes help Enhanced Hybrid find fitting
recordings beyond the original Deej-AI catalog while keeping prompts, listening
history, embeddings, and derived audio analysis on your device.

These notes cover all changes since v0.12.1.

🎧 MERT now finds similar tracks

MERT moves from being an analysis-only feature into the Enhanced Hybrid
recommendation path.

• Audio-to-audio retrieval: a reference track with a cached MERT embedding can
  retrieve compatible tracks from the local embedding cache. Search is bounded,
  recording-deduplicated, deterministic, and version-aware.
• Works with 30-second previews: the embedding describes only the analyzed
  preview interval. Playlist AI shows that coverage instead of presenting the
  result as full-track proof.
• Stable replay: each generated playlist freezes the MERT search view and
  policy identity. Replaying history does not silently rescan a changed cache.
• Independent controls: MERT similarity and deterministic DSP measurements
  have separate switches, caches, status, cleanup, and repair behavior.
• Graceful sparse coverage: when too few compatible MERT embeddings are
  available, candidate discovery continues and the Deej-AI model can fill
  remaining slots. Every refill still passes exclusions, identity checks,
  deduplication, ranking, and sequencing.

MERT compares audio with audio. It does not understand the text prompt, and a
cosine score is not a probability, beat match, genre label, or promise about an
entire recording.

🌍 Discover newer recordings with local MusicBrainz data

Settings and the first-run wizard can now install a compact, searchable
MusicBrainz index from Playlist AI's Cloudflare R2 archive. Candidate and identity
searches use the local index before the public MusicBrainz API, avoiding its
one-request-per-second limit for covered data.

The published v0.13.0 bundle contains MusicBrainz snapshot
20260912-001001:

Download	Size
Two Zstandard parts	283.80 MB
Expanded SQLite index	679.64 MB

The installer resumes verified parts, enforces HTTPS and size limits, validates
every SHA-256, decompresses with bounded memory, checks the embedded index
manifest and snapshot, and activates the new file only after verification. A
failed update leaves the previous active index in place.

The local index can propose artists and recordings outside the roughly 957,000
tracks in Deej-AI. Playlist AI resolves those candidates to Deezer previews when
available, gathers compatible CLAP, MERT, DSP, and AcousticBrainz evidence, and
then applies the normal ranking rules. Metadata proposes a candidate; it does not
by itself prove that the music sounds right.

🗣️ A musical thesaurus that speaks each provider's language

The prompt layer now uses a reviewed, provider-aware thesaurus for genres, moods,
instrumentation, vocals, texture, and listening activities.

• User phrases map separately to descriptive CLAP captions, exact archived
  AcousticBrainz classes, MusicBrainz search spellings, and deterministic DSP
  proxies.
• Ambiguous and numerical language keeps its context. Negation and exclusions
  remain explicit rather than becoming positive similarity hints.
• Unsupported AcousticBrainz or DSP mappings remain unknown instead of being
  invented from a nearby word.
• MusicBrainz discovery aliases broaden search without claiming that every
  returned recording has a verified genre or acoustic property.

MiniLM has been removed from prompt interpretation and model setup. The
deterministic parser, local llama.cpp parser, and optional DistilBERT extractor
remain available. Existing MiniLM-only preferences do not reopen setup or block
startup after upgrading.

🧭 Better controls and steadier generation

• MERT setup now lives under Recommendation models in Settings and has a
  focused optional step in the wizard.
• Compatible inference workers expose compute-device selection while retaining
  CPU fallback and native health checks.
• Candidate preview analysis runs in parallel within its existing time and item
  budgets, reducing waits when several tracks require evidence.
• Navigating away from Generate no longer discards in-progress playlist state.
  Playlist lengths are clearer, and model/dataset reset controls are grouped at
  the bottom of Settings with confirmation.
• Analysis screens explain long-running work more clearly and retain cancellation
  and retry behavior.
• Surprise prompts no longer inherit an accidental track count from visible UI
  defaults.

🎯 Recommendation correctness fixes

• Explicit artist requests stay attached to their intended role during candidate
  discovery and refill.
• Artist exclusions cannot be bypassed by similarity, genre, instrumental, or
  related-artist paths.
• MusicBrainz and Deezer discovery remains request-budgeted, rate-limited, and
  bounded even when candidates fail resolution.
• Required track counts are propagated independently of recommendation search
  internals, preventing lifecycle tests and stale state from changing the target.
• Instrumental searches reuse valid cached evidence and avoid treating incomplete
  metadata as proof of “no vocals.”

🛠️ Faster and safer MusicBrainz packaging

Maintainers can build the downloadable index in one command with
musicbrainzpack.

• Artist and recording dumps import concurrently through typed, bounded pipelines
  and staged SQLite databases.
• Large JSONL rows stream safely instead of failing at a 16 MiB scanner limit.
• Configurable SQLite caches, long transactions, prepared statements, and artist
  deduplication reduce avoidable disk work.
• Zstandard compression uses a smaller encoder window, computes the index hash in
  the same pass, and splits artifacts below Cloudflare R2's 200 MB target.
• pterm progress bars show download/import throughput, estimated completion, and
  imported row counts. Completed indexes are reused on rerun unless
  -replace-index is requested.

The included performance report uses deterministic synthetic fixtures on Windows
amd64. It supports the selected transaction and compression settings, but it is
not a measurement of full-snapshot peak memory or recommendation quality.

✨ Updates and maintenance

• The in-app updater now renders Markdown release notes, making headings, lists,
  links, and emphasis readable before an upgrade.
• Windows updates accept an already initialized compatible COM apartment instead
  of failing startup.
• Cross-platform reset paths handle harmless path aliases while still rejecting a
  data directory that is itself a link.
• The Windows race-test script selects the verified LLVM-MinGW compiler and
  restores the caller's environment afterward.
• Linux and macOS CI packaging waits for lint and tests, reducing wasted package
  jobs after an early failure.
• Offline maintainer tooling updates ONNX from 1.18.0 to 1.22.0 and PyTorch from
  2.7.1 to 2.13.0. These Python dependencies are not application prerequisites
  and do not change the distributed ONNX weights by themselves.

🔐 Privacy, verification, and licenses

Prompts, listening history, taste data, cached embeddings, and derived audio
features remain local. Explicit online discovery can send extracted artist,
album, recording, or genre searches to MusicBrainz and Deezer; preview audio is
discarded immediately after analysis.

MusicBrainz core data is CC0. Community tags and genres are
CC-BY-NC-SA-3.0. MERT-v1-95M remains optional and licensed
CC-BY-NC-4.0 for noncommercial use. The application remains GPL-3.0-only, and
native/model packs retain their upstream notices.

The release preparation passed the repository's complete Windows gate: 217
frontend tests, production frontend build, go vet, race-enabled Go tests, and
lint with zero issues. The merged feature PR also passed CodeQL and native package
builds on Windows, macOS Apple Silicon, Linux amd64, and Linux arm64. These are
software and packaging checks, not a listening study.

📦 Installing or upgrading

Platform	Architectures	Packages
Windows	x86-64, ARM64	NSIS installer or portable ZIP
Linux	x86-64, ARM64	AppImage, DEB, RPM, Arch package or portable tar.gz
macOS	Apple Silicon	DMG or portable application ZIP

Existing settings, history, catalog data, analysis caches, and installed models
are retained. MERT remains an optional separate download. The MusicBrainz index
is also optional and downloads only when selected in the wizard or Settings.

Allow temporary disk space for compressed parts and the expanded index during a
MusicBrainz installation. Windows ARM64 is cross-compiled; package build success
does not constitute native ARM64 execution evidence. Signing and notarization
depend on the repository's optional release credentials, so your operating system
may still show its normal warning for an unsigned package.

Further reading

• Enhanced audio and MERT behavior
• Prompt thesaurus and provider contracts
• Offline MusicBrainz index
• MusicBrainz packer performance
• Model distribution and licenses
• [Full changelog: v0.12.1 → v0.13.0](https://github.com/platten/playlistai/comp...

Playlist AI v0.12.1 — Hosted models, simpler setup

Playlist AI 0.12.1 makes the model packs introduced alongside 0.12.0 directly
installable from Settings and the setup wizard. It also makes Enhanced
Hybrid the default recommendation mode for new installations and unset
preferences. These notes cover changes since v0.12.0.

📥 Download models directly in the app

You no longer need to download, join, or extract model archives manually.

• Intent language models: Settings downloads the hosted DistilBERT and
  MiniLM encoder pack. The wizard starts this download when those assets are
  missing. Verified encoders are reused when only the native runtime needs repair.
• MERT: choose Download MERT for this device. The app selects Windows
  x86-64 or ARM64, Linux x86-64 or ARM64, or macOS Apple Silicon automatically.
  Unsupported targets display an explanation before any download starts.
• Resumable segments: each pack contains two compressed parts, with a maximum
  of 190 MB per part. Completed verified segments survive cancellation and are
  reused on retry.
• Native assembly and extraction: the app joins the segments as a stream,
  decompresses them, and verifies every extracted file. No Python installation
  is required to download or run the models.
• Existing imports remain available: advanced users can still provide a
  custom HTTPS manifest, a local manifest, or an unpacked MERT directory.

Download sizes

Pack	Compressed total	Segments
DistilBERT + MiniLM	324.06 MB	2
MERT · Windows x86-64	213.88 MB	2
MERT · Windows ARM64	214.01 MB	2
MERT · Linux x86-64	216.26 MB	2
MERT · Linux ARM64	215.50 MB	2
MERT · macOS Apple Silicon	217.33 MB	2

Sizes use decimal MB. Compression is lossless: no quantization, pruning or
precision reduction was applied. Intent encoders are shared across platforms;
their matching native runtime is downloaded separately if missing. MERT packs
include their platform runtime and, on Windows, the required app-local DLLs.

🧭 Enhanced Hybrid by default

New installations and unset or invalid mode preferences now use Enhanced
Hybrid. The playlist screen's fallback agrees with that default.

Explicit saved mode choices remain respected, as does an explicit legacy
Deej-AI configuration. The default-mode change does not automatically download
models, enable preview analysis, or turn on experimental intent suggestions.
MERT remains optional; missing evidence is still treated as unknown.

✨ A wizard that knows what is already installed

Setup offers an optional MERT step after music analysis. It selects the same
platform pack as Settings, shows download progress, and supports cancellation
and retry. The Enable bounded preview analysis checkbox lets you explicitly
choose whether to use enhanced audio evidence.

Healthy installed assets are skipped. A completed installation is not sent
through setup just because MERT is newly available; previously selected models
with missing files can still trigger focused repair steps. Downloading a model
does not silently change your analysis preferences.

🔒 Verified downloads and confined extraction

Built-in R2 manifest URLs and SHA-256 hashes are pinned in the application.
Every compressed segment and extracted file also has an expected size and hash.
Unexpected manifest changes are rejected before downloading segments.

The transport enforces size limits, refuses HTTPS downgrades, and rejects
absolute paths, traversal, links, duplicates and unlisted archive entries.
Extraction now also uses Go's filesystem-root API to confine filesystem access
to the staging directory. Model-specific compatibility and native health checks
remain in place before activation.

📊 Validation and model limitations

All six real hosted packs were downloaded through the native Go transport,
reassembled, decompressed and checked against their original file hashes.
R2 byte-range support was verified for resumable downloads. The downloaded
Windows MERT pack passed native parity, cancellation and restart checks.
MiniLM passed 17 embedding/tokenizer reference cases, and DistilBERT passed
17 tokenizer cases. The feature validation included 199 frontend tests, the Go
race suite, lint and browser checks in both themes and narrow/wide windows.

These are installation and regression checks, not a new listening study.
MiniLM suggestions remain experimental. The trained DistilBERT pilot remains
inactive because its expanded calibration did not establish useful additional
intent extraction. Shipping the base encoder does not change that conclusion.

MERT retains its CC-BY-NC-4.0 noncommercial license. DistilBERT and MiniLM
retain their Apache-2.0 licenses; native runtimes include their own notices.

📦 Installing or upgrading

Platform	Architectures	Packages
Windows	x86-64, ARM64	NSIS installer or portable ZIP
Linux	x86-64, ARM64	AppImage, DEB, RPM, Arch package or portable tar.gz
macOS	Apple Silicon	DMG or portable application ZIP

Upgrade the application to v0.12.1 to get the hosted model controls;
v0.12.0 cannot directly consume the segmented manifests. Existing settings,
history, catalogs and installed models are retained. Model weights remain
separate downloads rather than being added to every application installer.
Allow temporary disk space for compressed segments, extracted files and the
installed copy. Windows ARM64 is cross-compiled; build success is not native
execution evidence. Installed-updater flows have not been tested on every OS.

Further reading

• Model downloads, hosting and preparation
• Recommendation modes
• Setup readiness and repairs
• DistilBERT calibration findings
• Full changelog: v0.12.0 → v0.12.1

Release verification

All five platform packaging jobs and the release-preparation PR checks passed, including CodeQL. All 17 assets were verified against GitHub's SHA-256 digests. Package versions and processor architectures were checked; Linux DEB/Arch executables matched their portable counterparts, and winget hashes matched the Windows installers. The downloaded Windows x86-64 executable reports 0.12.1 and passes both native worker-capability probes.

The tagged source also includes the merged offline-maintainer Transformers dependency update to 5.10.1. This does not change the deployed ONNX weights or add Python as an application prerequisite; the recorded model export/parity evidence remains tied to its documented toolchain.

Playlist AI v0.12.0 — Better intent, richer hybrid recommendations

Playlist AI 0.12.0 adds Enhanced Hybrid recommendations, strengthens the
translation from your words into musical criteria, and makes updates and setup
more convenient. This release brings together the changes since v0.11.1.

🎧 Enhanced Hybrid: more ways to understand the sound

The new optional recommendation mode combines existing catalog, metadata,
AcousticBrainz and CLAP evidence with local audio measurements and optional
MERT audio representations.

• Describe more than a genre. Measured preview characteristics can support
  soft sound preferences, while MERT contributes audio similarity and transition
  continuity when compatible analysis is available.
• Keep musical evidence separate. CLAP text/audio similarity, MERT audio
  similarity, deterministic measurements and archived classifier predictions
  retain their own identities and coverage. Unknown evidence is shown honestly.
• Strong matches come first. Close suggestions carry evidence gaps instead
  of silently claiming every requested trait was verified. Explicit exclusions,
  essential criteria and recording deduplication remain enforced.
• Reuse analysis. Derived preview evidence is cached with model and
  preprocessing identities. Temporary preview audio is cleaned up after analysis.

The existing Deej-AI-only, AcousticBrainz-first and CLAP-first modes remain
available. Enhanced Hybrid does not require MERT installation, and an audio
similarity score alone does not prove a genre, mood or full-track characteristic.

🧭 Your wording survives the language model

A source-aware English pre-parser now extracts explicit facts before the local
LLM interprets the request. A versioned music dictionary translates recognized
concepts into provider-specific genres, classifiers and CLAP descriptions.

• Better handling of exclusions, indirect negation, compound artist names,
  year alternatives, decades and combined hour/minute durations.
• “Mostly instrumental” retains its preference strength instead of becoming
  an invented universal ban on vocals. Mood and texture are not automatically
  promoted into mandatory genres.
• Explicit source facts constrain the LLM's output. Model-only mandatory
  categories and output roles cannot silently replace the original request.
• Artist journeys preserve actual endpoints: a request moving from Nine Inch
  Nails to Marilyn Manson can keep those artists at the ends, with similar
  eligible tracks between them.
• Ambiguous spelling is confirmed. For a likely “Christian Löffler” typo, choose
  the suggested artist, keep your original wording, or cancel. Keeping the
  original prevents silent fuzzy correction and can leave the name unresolved.

Enhanced Hybrid can also use attributed MusicBrainz, Wikidata and Wikipedia
artist/album context to seed discovery. Lookups are cached, bounded and scoped
to music references; the full prompt and private listening history are not sent
to those services. Artist context guides retrieval and does not certify every
recording's sound.

⏱️ Ask for a duration, not just a track count

Duration requests now carry a target, tolerance and known playlist total through
generation, controls and saved history. For example, a 75-minute request with
a one-minute tolerance targets 4,440–4,560 seconds, with a variable number
of tracks unless you also specify a count.

Selection preserves required tracks, endpoints and musical constraints while
searching eligible alternatives. Only grounded full-recording duration metadata
can verify the total; a 30-second preview is not treated as a track's length.
Missing durations or an unsuccessful bounded search produce an explanation.

🖥️ Native language and audio tooling

The desktop keeps inference in compiled native workers: Python is not a
desktop prerequisite. Verified setup paths acquire missing compatible model
and runtime assets. Catalogs and large model weights remain separate downloads,
so application upgrades do not need to redistribute your existing data.

• Native MiniLM support provides an experimental semantic proposal path. It
  remains off by default with conservative acceptance thresholds.
• DistilBERT tooling supports reviewed annotations, training, export and
  calibration. The current small trained pilot remains inactive: expanding
  the diagnostic to 128 prompts did not establish useful additional extraction.
• Optional MERT packs have separate model identities and upstream license
  notices. Windows packs include the required app-local runtime dependencies.
• Offline Python preparation and evaluation scripts are documented for people
  building datasets or model packs; they are not needed to run Playlist AI.

✨ Clearer updates and less repeated setup

• The startup updater displays GitHub release notes immediately, with a
  scrollable “What’s new” section and access to the full release page.
• Existing data and models are checked locally. A healthy completed setup opens
  normally after an upgrade; missing selected capabilities reopen only the
  necessary repair steps.
• Setup skips available assets and rechecks between steps. Newly introduced
  optional features alone do not force everyone through the wizard again.
• Deliberate rules-only parsing and disabled previews are preserved, including
  across restarts. Update progress, cancellation and retry remain accessible in
  narrow windows and both themes.

🛠️ Reliability and development improvements

This release preserves full-width random seeds, strengthens update archive
extraction boundaries, and improves cancellation and deterministic cache replay.
CI uses GitHub-hosted runners, parallel validation and reduced fixture/retry
overhead, with timing reports to make further optimization measurable.

📊 What the measurements show—and what remains open

On the recorded development comparison with the same 3B language model, the
stricter consumed-intent audit improved from 11/30 to 29/30. In a bounded
cached 40-playlist replay, returned tracks increased from 270 to 296 out of
495 requested, and full count requests increased from 16/38 to 18/38.
Recorded excluded-artist, artist-only and endpoint violations fell to zero.
These gains came from the source compiler and schema changes; MiniLM was disabled
in that comparison.

These are development regressions, not a representative listening study or
proof that every request now succeeds. Many replay requests remain partial or
unsupported, and the composer-versus-performer example remains unresolved.
The larger-model comparison and expanded DistilBERT diagnostic are published
with their limitations rather than treated as guaranteed quality improvements.

The final feature tree passed hosted checks for every release build target and
the local Windows gate, including 191 frontend tests, Go race tests, vet,
lint, bindings, typechecking and production build. Browser fixtures exercised
update and setup states at narrow/wide sizes in both themes. Native installed
updater flows have not been exercised on every platform.

📦 Downloads and upgrading

Platform	Architectures	Packages
Windows	x86-64, ARM64	NSIS installer or portable ZIP
Linux	x86-64, ARM64	AppImage, DEB, RPM, Arch package or portable tar.gz
macOS	Apple Silicon	DMG or portable application ZIP

Choose the package matching your OS and processor. Existing settings, history,
catalogs and installed models are retained; no data reset is required. Newly
generated playlists can differ because interpretation and ranking have changed.
Signing depends on the configured release credentials. Windows ARM64 packages
are cross-compiled; a successful build is not native ARM64 execution evidence.

Further reading

• Enhanced Hybrid settings
• Intent and playlist measurements
• Approved duration and spelling behavior
• Expanded DistilBERT diagnostic
• Setup and update behavior
• Full changelog: v0.11.1 → v0.12.0

Release verification

All five platform package jobs and the release-source CI completed successfully. All 17 published assets were checked against GitHub's SHA-256 digests. Linux package versions and architectures, macOS bundle version and architecture, Windows portable architectures, and winget installer hashes were verified. The downloaded Windows x86-64 executable reports 0.12.0 and passes the audio and intent worker capability probes. A transient HTTP 403 fetching a pinned Microsoft license document was resolved by rerunning the failed Windows ARM64 job; no source or tag changes were required.

Playlist AI v0.11.1 — Verified genres and a more reliable generation lifecycle

Playlist AI v0.11.1 — Verified genres and a more reliable generation lifecycle

Playlist AI 0.11.1 tightens single-genre recommendations, stops unnecessary track
analysis, and fixes state, storage, and lifecycle errors. It also publishes a
new, deliberately limited benchmark replay—including failures rather than only
successful playlists. These notes cover changes since v0.11.0.

Every track must fit a single requested genre

When you specify one playlist-wide genre, every recommended track must have
affirmative evidence for that genre. The check runs before selection and again
on the assembled playlist, including required tracks.

• Best-available mode, discovery, diversity, and listening history cannot bypass
  genre eligibility. Unknown evidence is no longer permission to fill the list.
• Established aliases and directional subgenre relationships remain supported:
  techno can satisfy electronic, but electronic alone does not prove techno.
  Influence and fusion are not automatically treated as equivalent genres.
• Evidence can come from provenanced musical metadata, resolved track tags, a
  compatible grounded-description index with complete query coverage, or a
  supported calibrated audio assessment. Catalog identity, artist/title words,
  and uncalibrated preview similarity do not establish genre.
• Sparse sidecars no longer hide valid metadata fallback. Compatible semantic
  evidence can also verify candidates outside an index's retrieval shortlist.
• If too few tracks qualify, the app returns fewer tracks with an explanation.
  Required tracks that conflict with genre eligibility request clarification.
  A request can return no tracks when there is no defensible evidence.

Deej-AI-only does not verify genres. A single-genre request in that mode now
returns an unsupported outcome suggesting AcousticBrainz-first or CLAP-first,
instead of an unchecked playlist. Artist-based engine-only recommendations remain
available. Deliberate multi-genre requests and category journeys retain their
existing semantics; soft mood and texture preferences are not all promoted to
hard genre filters.

See single-genre verification
for evidence rules and compatibility details.

Stop work when a valid playlist is ready

Recommendation generation still prepares a bounded shortlist targeting twice
the requested count, but no longer analyzes surplus candidates once selection
and sequencing can produce the requested playlist. Required tracks count toward
the total. Rejected candidates and incomplete journeys still permit bounded
refill; the stop condition is a valid playlist, not merely enough candidates.

Related corrections include:

• Refill excludes already-attempted semantic candidates before top-K selection,
  avoiding repeated pages that cannot improve the result.
• A failed later retrieval preserves an already usable candidate pool and reports
  the interruption. An exhausted audio-session budget preserves accepted tracks;
  cancellation of the parent request remains cancellation.
• Required waypoints respect hard artist spacing, including scarce separators
  between same-artist waypoints, or report a conflict.
• Iterative completion and final output share one assembly operation, reducing
  duplicated ranking, selection, and sequencing logic.

Saved playlists, navigation, and feedback

• Loading a saved playlist cannot submit the previously selected record while a
  slower load is pending. Late responses cannot replace the newer selection.
• Editing a saved description creates a fresh request. An unchanged saved result
  can be displayed without rebuilding or inventing a new generation identity.
• Navigating between screens retains the active result, accepted controls,
  generation seed, and export draft.
• Exposure is recorded only when the UI acknowledges displaying a result.
  Discarded builds and repeated acknowledgments do not add exposure, and exposure
  is never treated as a like.
• Clearing taste data invalidates pending profile writes and display tokens, so
  in-flight work cannot restore the cleared information.
• Historical playlist messages use the domain outcome. Reaching the requested
  count does not retroactively verify an old playlist's musical requirements.
• Generate no longer shows redundant Edit description buttons; its description
  remains directly editable.

Safer settings, storage, and runtime management

Settings now use atomic replacement and acknowledge successful persistence.
Corrupt preferences are preserved with an actionable mutation error rather than
silently overwritten. A custom data_dir rebases implicit catalog/cache paths
while retaining explicitly configured paths; existing files are not relocated.

SQLite stores share escaped URI construction, preventing reserved path characters
from redirecting access. If startup detects a recognizable database at a legacy
misinterpreted path, it warns rather than silently creating an empty replacement.
Recovery is intentionally not automatic: close the app and back up the database
and any -wal/-shm files before reviewing a recovery destination.

Other fixes validate catalog embedding headers, honor cancellation while hashing
downloads, prevent slow model activation from undoing a newer selection or clear,
and publish complete catalog service snapshots with explicit shutdown ownership.
Intent normalization no longer mutates caller-owned vocal preferences, and
validation rejects nonfinite resolution weights. Refactoring separates intent
normalization, migration, validation, capability checks, and lifecycle ownership
without replacing the recommendation engine.

Measured performance—not a universal speedup claim

On the Linux/WSL2 development host, a production-catalog benchmark using 956,917
tracks, a ten-track Boards of Canada request, seed 42, and five samples measured:

Recommendation-only variant	Median	Range
Uncached exact retrieval	60.350 ms	59.344–62.052 ms
Request-scoped cache	62.773 ms	61.998–64.975 ms

Both variants produced identical playlists and scoring evidence. The cache was
about 4% slower for this short request and allocated more memory; the website no
longer presents the historical 5.8× result as a current universal improvement.
These timings exclude parsing, providers, audio analysis, and startup.

Separate synthetic measurements found the 100-track category-journey fixture
improved from 72.697–73.754 ms to 23.039–23.748 ms, with allocation volume reduced
from 58.784 MB to 1.274 MB per operation. This is a sequencing microbenchmark,
not whole-app latency or evidence of better music. Hosts were not dedicated
benchmark machines, and results should not be generalized to every request.

Commands, raw timing samples, hardware, and limitations are recorded in the
performance report
and codebase review.

Forty-prompt replay: incomplete coverage remains visible

The September 11 replay requested ten tracks per prompt and tested a minimum of
five distinct recordings, diversity, and other contract assertions. It reused
saved interpretations and cached derived features; it was not fresh LLM/CLAP
evaluation or a held-out listening study.

Mode	Completed / 40	Interrupted	Unattempted	Passed all assertions / completed
AcousticBrainz-first	38	2	0	11 / 38
CLAP-first	27	2	11	7 / 27
Deej-AI-only	40	0	0	9 / 40

In total, 105 of 120 mode/cases completed; four remained interrupted and eleven
were unattempted. For this replay the all-assertions, at-least-five, and
exactly-ten success counts were the same. The five-track target for every
prompt was not achieved.

Both enhanced modes returned zero tracks for “Classical, 10 tracks.” and
“Electronic music. Make a 10-song playlist.” with insufficient-genre-evidence
explanations, rather than unrelated filler. Preview evidence was sparse: only
2 of 112 selected AcousticBrainz-first tracks and 2 of 72 CLAP-first tracks had
analyzed preview evidence. Neither mode selected a pick with an available
acousticbrainz_intent scoring component. No new preview bytes were downloaded.
Native CLAP worker health passed, but this does not establish fresh inference
quality; the worker used CPU execution, not GPU inference.

No completed result violated the recording-duplicate, adjacent-artist, or
excluded-artist assertions. Some short results failed diversity. This is not an
independent genre-quality assessment and does not establish a winning source
priority; cache warmth, completed case sets, and concurrent work differed.

Known unresolved findings include a CPU-active catalog-resolution scan during
the punk request that did not promptly honor cancellation, ambiguous reference
resolution, and MusicBrainz HTTP 503 responses. Some bounded stages needed forced
termination. These are documented limitations, not fixed-performance claims.
See the complete replay protocol and results.

Validation and coverage

The local Linux repository gate passed for the included application changes:
shell checks, generated Wails bindings, 150 frontend tests, TypeScript
checking, production frontend build, Go vet, pure-Go core compilation,
race-enabled Go tests, and lint with zero issues. Seven rendered Chromium
workflows covered generation, recommendations, wizard, logs, export, updates,
and saved-session navigation. The website also passed checks at five viewport
sizes. These local checks do not establish hosted release-build success or
native Windows/macOS execution.

The refactor's recorded inclusive coverage was **83...

Playlist AI v0.11.0 — Better filtering, clearer playlists, and useful logs

Playlist AI v0.11.0 — Better filtering, clearer playlists, and useful logs

Playlist AI 0.11.0 improves how recommendation candidates are checked, makes
playlist outcomes easier to understand, and adds practical debug controls and
frontend regression testing. These notes cover changes since v0.10.0.

Recommendation shortlists before musical analysis

Evidence-aware recommendation generation now prepares a bounded shortlist aimed
at twice the requested playlist size before checking candidates with
AcousticBrainz and CLAP. For example, a 10-track recommendation request starts
with a target of 20 candidates, then selects eligible tracks toward the requested
10. Required tracks count toward the total rather than being added on top.

• Candidates are ranked and diversity-aware shortlist selection happens before
  expensive audio analysis. Request-local retrieval budgets expand when needed,
  within the configured candidate cap.
• Analysis stops once final selection and sequencing can satisfy the request.
  Rejected or insufficient candidates trigger bounded refill rather than one
  unbounded scan or a repeated request for each track.
• Required tracks, recording deduplication, hard exclusions, artist diversity,
  and ordered journeys remain enforced. Enough accepted tracks alone is not a
  reason to stop if a later journey stage is still missing.
• Refill retains the original request anchor. Provisional alternatives are not
  treated as accepted listening history; accepted selections can inform later
  continuation requests.
• AcousticBrainz-first and CLAP-first preserve their separate evidence policies.
  Deej-AI-only still skips this musical-analysis stage. Direct metadata discovery
  retains its existing oversampling policy; the two-times shortlist applies to
  recommendation candidates, including recommendation fallback.

The strategy identity is now multichannel/v19. Regeneration can produce
different playlists; saved playlists keep their existing results and version
information. This release does not promise a full playlist when eligible tracks
or musical evidence are insufficient, and does not claim a measured latency or
musical-quality improvement from the shortlist change.

Accurate playlist messages

A full-length playlist no longer always displays “A verified partial playlist
was generated.” Track count and musical fulfillment are separate:

Result	User-facing message
10 tracks returned, with some unverified request details	“Playlist created with 10 tracks,” with relevant explanations retained
6 tracks returned for a 10-track request	“Created 6 of 10 requested tracks”
Request fulfilled	No partial-result banner
Unsupported or ambiguous request	An inability-to-verify or clarification message

Unknown musical evidence is not relabeled as verified merely because the count
was reached. Older saved-result notices are corrected for display without
rewriting history or promoting their stored outcome. Warnings remain dismissible.

Log levels and diagnostic privacy

Open Settings → Application logs → Open logs and choose the minimum level:
DEBUG, INFO, WARN, or ERROR.

• DEBUG enables detailed recommendation diagnostics, including available prompt,
  interpretation, provider, AcousticBrainz, CLAP, and selection evidence.
• Selecting a higher level stops debug collection and clears retained DEBUG
  entries. Filtering the viewer does not discard ordinary retained logs.
• Local dropdown changes invalidate older log polls; changes made in Settings
  appear on the next successful refresh. Consent is checked again before appending a
  diagnostic, including when it changes during payload serialization.
• Verbose in-memory diagnostics do not require lowering the ordinary console log
  level. Retained logs remain bounded and are not written to a persistent log file
  by this feature.

Detailed diagnostics can contain private prompts and listening information.
Review them before sharing. The preference can persist, but log contents are
memory-only. Clearing diagnostic logs does not clear separately stored history or
derived musical analysis. Preview audio cleanup and existing opt-in behavior remain.

A clearer, more accessible desktop interface

• The theme control uses a computer for System, sun for Light, and
  moon for Dark. It retains an accessible name, keyboard operation, and local
  preference persistence.
• The Generate screen places the description and primary action first, with
  clearer mode guidance and example cards below. Selecting an example fills the
  description and focuses it; generation remains an explicit action.
• Shared theme tokens improve surfaces, hover states, and secondary-text contrast
  in light and dark appearances.
• Track details use a keyboard-accessible button with an expanded state; preview
  controls remain separate. Long names and explanations are better accommodated
  in narrow desktop windows.

Linux package architecture correction

Linux packaging tasks now explicitly propagate the target architecture to nfpm
for DEB, RPM, and Arch packages. This prevents ARM64 packages from inheriting an
amd64 header despite containing an ARM64 executable. Nine regression cases cover
native, amd64, and arm64 targets across the three formats. Unlike the packaging
repair documented for v0.10.0, the correction is included in this release's source.

Tests and coverage: progress, not a 95% claim

The contributor gate now includes 35 Vitest/Testing Library frontend tests,
alongside TypeScript checking and the production build. New backend regressions
cover recommendation pools and refill, required journeys, resolver caching and
ambiguity, intent normalization, semantic evidence, lossless seeds, and logging
privacy. Rendered-browser checks cover log interactions, theme cycling, playlist
outcome messages, and related generation navigation.

Measured on Linux for the application changes included in this release:

Coverage metric	Result
Backend statements across internal/...	78.52%, up from 76.89%
Core domain statements	98.3%
Logging statements	97.9%
Resolution statements	100%
Frontend lines	6.81%
Frontend statements / branches / functions	6.43% / 4.96% / 5.03%

The requested repository-wide 95% target is not achieved. The new separate
coverage command correctly fails below that target; ordinary passing CI is not
a coverage guarantee. Backend coverage excludes root bootstrap and command-line
and packaging tools; frontend measurement includes all application TS/TSX modules,
including unimported screens, and excludes only declarations and tests. Native
build variants require their own host measurements. Browser checks are separate
evidence and are not counted in the Vitest percentages.

Reproduce the standard gate and separate coverage check:

bash scripts/test.sh
bash scripts/coverage.sh

.\scripts\test.ps1
.\scripts\coverage.ps1

The application tree passed the full local Linux gate: shell regressions, bindings
generation, 35 frontend tests, typecheck, production build, Go vet, pure-Go core
compilation, race-enabled Go tests, and lint with zero issues. Earlier rendered UI
checks passed; existing Settings fixture console warnings remain documented and
are not interpreted as coverage. Windows coverage-script execution was not
verified locally. No new held-out listening study, forty-prompt comparison, or
end-to-end performance benchmark was performed for this release.

Upgrade, packages, and limitations

No user-data reset or intent/history migration is required. Existing settings,
catalogs, metadata, profiles, and installed models remain compatible. Neither the
default language model nor the analysis-model recommendation changes in 0.11.0.
Model weights and large datasets remain separate wizard downloads; the desktop
application does not acquire a Python dependency.

Packages are built for Windows x64/ARM64 (NSIS and portable ZIP), Linux x64/ARM64
(AppImage, DEB, RPM, Arch package, and portable TAR.GZ), and Apple Silicon macOS
(DMG and application ZIP). The workflow also generates a winget manifest ZIP.
There is no Intel Mac package. Signing and notarization depend on configured
credentials, so operating-system trust prompts may appear.

Musical analysis still depends on available metadata and preview coverage.
CLAP similarities are not probabilities, and this release does not establish
general-fit calibration or properties of unheard portions of tracks. Unsupported
criteria and insufficient evidence remain visible instead of being concealed
by arbitrary full-length results.

Release artifact verification

The release packaging workflow
and hosted CI
passed every job, including the Windows contributor gate and both Windows
installer architectures. All 16 application packages plus the winget ZIP matched the
approved filenames, nonzero sizes, and GitHub SHA-256 digests. Both installer
hashes in the winget manifest match their corresponding Windows assets.

The downloaded Linux x64 binary and Windows x64 binary (executed on Windows
through WSL interoperability) report 0.11.0 and pass --check-audio-worker.
This probe confirms compiled worker availability, not model inference. Linux
x64/ARM64 executable architectures and DEB metadata were inspected; the ARM64
Arch package declares aarch64. The macOS ZIP passed its integrity check and
contains 0.11.0 bundle metadata. Native macOS and Windows ARM64 execution, RPM
header inspection, signing/notarization, and complete installed-updater flows
were not independently exercised in these local artifact checks.

Further reading

• [All changes since v0.10.0](https://github.com/platten/playlistai/compare/v0.1...

Playlist AI v0.10.0 — Music analysis and recommendation diagnostics

Playlist AI v0.10.0 — Music analysis and recommendation diagnostics

Playlist AI 0.10.0 makes recommendation decisions easier to inspect, introduces
the full-precision music-only CLAP model as the recommended analysis download,
and gives Deej-AI-only users examples that match their selected engine.

These notes describe changes since the published v0.9.0 release. The existing
AcousticBrainz-first, CLAP-first, and Deej-AI-only recommendation modes remain
available. The local language-model default is unchanged.

See how a playlist was built

Open Settings → Application logs, enable Show detailed recommendation
diagnostics, then open the log window and generate a playlist. The new option
records the following information when that stage runs and evidence is available:

Stage	Diagnostic information
Request	Submitted prompt and available session context
Interpretation	Parsed musical intent, parser backend, fallback status, and model completion content/termination reason
Provider access	Request URLs with credential-like query parameters redacted, attempts, HTTP status, response size when known, elapsed time, and errors
Metadata discovery	Resolved artist pools, track metadata, sources, and discovery notices
CLAP analysis	Model identity, preview identity and coverage, per-segment audio embedding vectors, clause scores, eligibility, and analysis totals
AcousticBrainz	Available tempo, danceability, loudness, dynamic complexity, key/scale, prediction classes and scores, provenance, and model versions
Selection	Each selected track's explanation, retrieval sources, scoring components, generation outcome, and reproducibility information

CLAP audio vectors are logged when analysis is computed or loaded from cache.
This reuses the record already being assessed; it does not fetch audio again or
add a database lookup solely for logging. AcousticBrainz records contain the
feature projection used by Playlist AI, rather than every field in the upstream
archive. API response summaries and parsed metadata are logged; raw provider
response bodies and request headers are not dumped.

Useful event names include analysis.clap_audio_embedding, analysis.clap,
analysis.acousticbrainz_features, analysis.acousticbrainz_comparison, and
recommendation.pick.

Retention and privacy

Detailed collection is off by default. Its preference persists across app
restarts, while log records stay in memory. Disabling it removes retained DEBUG
entries and clears them from the viewer when it next refreshes. Ordinary session
logs remain available.

Individual diagnostic records are capped at 64 KiB, with oversized records
explicitly marked as truncated. The backend retains at most 2,000 records or
16 MiB of log text. Disabled diagnostics skip payload serialization. This
allows normal CLAP vectors to be inspected while bounding retained log data.

Full prompts, listening context, model output, and track evidence can reveal
private interests. Review excerpts before sharing them. Debug collection does
not write log files or retain preview audio. Derived analysis and saved playlist
evidence continue to use their existing local stores and separate clearing
controls; disabling logs does not erase those stores.

CLAP Music, full precision

New recommended analysis installations use LAION larger CLAP Music, replacing
Music + Speech as the wizard's default checkpoint. The audio and text encoders
are paired FP32 ONNX exports with 512-dimensional embeddings.

• Encoder downloads total 778,209,534 bytes, approximately 778 MB, plus
  tokenizer files and the platform's ONNX Runtime download.
• The bundle declares a 2 GiB memory budget. This is a configuration value,
  not a newly measured peak-memory guarantee.
• The setup download verifies pinned file sizes, SHA-256 hashes, embedding
  compatibility, and local inference before activating the bundle.
• Users with an older or custom model see a Recommended update option under
  Settings → Music analysis. Installing the application alone does not
  replace an existing analysis model.
• The existing bundle remains active unless the replacement installs and passes
  its health check. Older analyses remain stored under their original model
  identity; incompatible embedding spaces are never mixed.

Model weights remain separate from the application installers and download only
through analysis setup. The new graphs use the already published, checksummed
model assets hosted under v0.9.0; v0.10.0 does not duplicate those large files.
Desktop execution continues to use compiled Go and the native inference runtime,
without requiring Python, pip, or PyTorch on the listener's machine.

Executed numerical checks and their limits

The recorded Linux x64 export validation used source revision
a0b4534a14f58e20944452dff00a22a06ce629d1:

Check	Recorded result
Synthetic audio/text numerical fixtures	10/10 passed
Maximum absolute embedding error	1.0430813 × 10⁻⁷
Minimum reference/export cosine	1.0
Tokenizer fixtures	7/7 exact
Preprocessing fixtures	3/3 within tolerance
Maximum preprocessing error	7.6293945 × 10⁻⁶
Three synthetic audio cases	143.27–154.32 ms per recorded case
Seven text cases	54.33–66.37 ms per recorded case

These are recorded export checks, not desktop end-to-end latency or musical
quality benchmarks. A separate four-prompt smoke check found unusually similar
text vectors for unrelated descriptions: cosine 0.998960–0.999329. The model
therefore retains the existing uncalibrated general-fit policy. Numerical parity
does not establish that it improves recommendations over Music + Speech.

CLAP scores remain preview-scoped similarities, not probabilities. Existing
vocal-screening behavior remains available, but unheard parts of a recording
are unassessed. AcousticBrainz coverage and classifier uncertainty also remain
visible. This release does not add a new held-out listening evaluation or rerun
the previous forty-prompt, three-mode quality study with the replacement model.

Examples that fit Deej-AI-only mode

The Generate screen now reads the recommendation mode separately from the
parser. Selecting Deej-AI only shows exactly these four examples, including
when an LLM is installed:

1. Bonobo, 10 tracks
2. Daft Punk, 20 tracks
3. A journey from Justice to Boards of Canada, 15 tracks
4. A journey from Radiohead to Sigur Rós, 12 tracks

The placeholder, guidance, mode badge, and Surprise me action follow the same
catalog-reference requirement. Choosing an example fills the description;
generation begins when Generate playlist is pressed. Genre and mood examples
remain available in the evidence-aware modes.

These examples guide an artist/reference request or an ordered journey; catalog
resolution and normal eligibility still apply. Their presence does not guarantee
that every requested count can be filled in every catalog or configuration.

Settings and contributor guidance

The Off choice has been removed from Settings → Track previews. Deezer
and Spotify remain selectable. Existing saved off preferences are not migrated
automatically; select a provider to enable previews if an older installation
still has playback disabled.

For contributors, AGENTS.md now defines planning, research, coding, and code
review responsibilities, with file ownership and handoff expectations. The new
SKILLS.md covers Conventional Commits, creating and maintaining PRs, a thorough
PR description template, validation, compatibility, and documentation standards.

Upgrade and packages

Install the package matching your operating system and architecture. Existing
settings, history, catalog data, metadata, and taste profiles remain compatible;
there is no required data reset. Updating the CLAP bundle is a separate action
in Settings. Existing saved playlists retain their evidence; regeneration can
use the newly installed model and its distinct identity.

Platform	Architectures	Package formats
Windows	x64, ARM64	NSIS installer and portable ZIP
Linux	x64, ARM64	AppImage, DEB, RPM, Arch package, and portable TAR.GZ
macOS	Apple Silicon	DMG and portable application ZIP
winget metadata	Windows x64/ARM64	platten.PlaylistAI-0.10.0-winget.zip

The release workflow assembles 16 application packages and one winget manifest
ZIP, validates the application-asset allowlist, and attaches them to the
release. Models, recommendation catalogs, and metadata dumps are downloaded
separately. There is no Intel Mac package. Linux packages use GTK4 and WebKitGTK
6.0; native inference still requires the downloaded platform runtime. Signing
and notarization depend on configured credentials, so OS trust prompts may occur.

Linux ARM64 packaging correction

Pre-publication inspection caught ARM64 DEB/RPM/Arch packages carrying x64
architecture headers. Those three containers were rebuilt with explicit
GOARCH=arm64, using the unchanged CI-built ARM64 executable and configuration
from the v0.10.0 tag. Their architecture metadata is corrected; the extracted
DEB executable matches the original portable binary's SHA-256.

The tag and application code are unchanged. A follow-up packaging-task fix and
nine native/amd64/arm64 regression cases prevent the same defaulting problem in
future builds. Reproduction instructions are in
the release guide.

Validation and remaining limitations

The release tree passed the full local scripts/test.sh gate: shell checks,
release-asset guard tests, Wails binding generation, frontend typecheck and
production build, Go vet, pure-Go core compilation, race-enabled Go tests, and
golangci-lint with zero issues. Focused tests co...