All notable changes to FlowSound will be documented in this file.
The format is based on Keep a Changelog, and this project follows Semantic Versioning.
- Fixed release app bundle metadata so
CFBundleShortVersionString,CFBundleVersion, and the About window version are generated fromVERSION. - Fixed release packaging to fail when the built app bundle version does not match
VERSION. - Fixed release packaging to fail when
CHANGELOG.mddoes not contain a matching release section instead of publishing placeholder release notes. - Fixed Netease Cloud Music playback-state detection for Chinese and English Controls menu titles.
- Added a
MusicControlAdaptercapability model for official, experimental, and community music app integrations. - Added adapter metadata for support level, bundle identifiers, playback-state capability, and volume-control capability.
- Added Netease Cloud Music as an experimental adapter using menu-state playback detection, relative volume steps, and Core Audio output feedback.
- Added adapter profile import/export for transparent community adapter metadata.
- Added tests that verify Apple Music and Spotify remain official absolute-volume adapters.
- Added tests for the Netease experimental adapter descriptor and adapter profile import/export.
- Migrated the existing AppleScript music control path to
AppleScriptMusicControlAdapterwhile preserving current Apple Music and Spotify behavior. - Changed the Preferences music app picker to show experimental support levels instead of presenting all adapters as official support.
- Changed Netease Cloud Music restore to use a more conservative relative-step count to avoid increasing volume after each duck/restore cycle.
- Changed Netease adapter profile export to write a local JSON file under Application Support and reveal it in Finder instead of using a save panel.
- Changed adapter profile import to read local JSON files from FlowSound's Application Support profile folder instead of opening a panel.
- Changed Netease menu automation to run inside FlowSound instead of
/usr/bin/osascript, so Accessibility permission belongs to FlowSound. - Tightened Preferences tab layout so fixed-height scroll areas no longer stretch section spacing.
- Tightened Preferences content heights again and removed the duplicated launch-at-login status text.
- Updated architecture and contributor documentation to keep future community adapters separate from official native support.
- Updated app and documentation copy to explain Netease Accessibility permission, approximate volume restore, and local-only adapter profiles.
- Updated public documentation and website copy for the current support matrix: macOS 15+, Apple Music, Spotify, and English / Simplified Chinese.
- Clarified that additional music apps can be adapted when they expose reliable local playback and volume control.
- Fixed Preferences language switching leaving stale translated content layered in the window.
- Fixed repeated Preferences rebuilds accumulating reused AppKit subviews and duplicate fixed-width constraints.
- Fixed Preferences opening with severe layout lag, missing content, and unresponsive tab/save controls.
- Replaced recursive Preferences height fitting with stable per-tab height targets.
- Fixed recent audio source rendering by using explicit scroll document sizing instead of fragile nested scroll constraints.
- Fixed Preferences tab spacing and removed the oversized empty top gap inside tab content.
- Fixed Preferences window height so it adapts to the selected tab instead of using the tallest tab's height.
- Fixed the recently detected audio sources list so app names, bundle identifiers, pids, and watched/excluded status are visible.
- Added Preferences language selection with System, English, and Simplified Chinese options.
- Added a tabbed Preferences layout with General, Monitoring, and Tools tabs.
- Added a Tools panel for recently detected audio sources from the last 3 minutes, including bundle identifier, pid, and current watched/excluded status.
- Added unit tests for language preference persistence and recent audio source retention.
- Changed the menu bar item to icon-only and removed the user-facing menu bar text option.
- Moved diagnostics actions from the menu bar menu into Preferences > Tools.
- Kept watched and excluded app configuration as raw bundle identifier text editors, with Tools as the assisted discovery path.
- Fixed Preferences Advanced expansion overflowing the screen and hiding the Save / Reset buttons.
- Fixed Preferences not returning to a compact height after Advanced is collapsed.
- Clarified that new feature work should happen on the
devbranch whilemainstays on the last stable public release.
- Added Spotify as a selectable music app controlled through local AppleScript.
- Added English and Simplified Chinese app UI selected from the system language, defaulting to English.
- Added a clearer Preferences layout with music app selection and advanced bundle identifier filters collapsed by default.
- Lowered the supported runtime target from macOS 26+ to macOS 15+.
- Changed Core Audio tap setup to use bundle identifiers on macOS 26+ and process object IDs on macOS 15-25.
- Updated the website, install notes, privacy notes, security notes, architecture, and roadmap for macOS 15+ and Apple Music / Spotify support.
- Redesigned the website hero to use a more visual before-and-after audio focus diagram.
- Moved the Product Hunt badge out of the hero visualization and into the main call-to-action area.
- Reduced the website header height and logo footprint.
- Changed the website hero side panel to explain the Apple Music audio-focus workflow and user pain point more directly.
- Added Product Hunt featured badge support with light and dark theme variants.
- Added a static one-page FlowSound landing page for Cloudflare Pages.
- Added English and Simplified Chinese website copy with browser-language detection and manual language switching.
- Added YouTube demo embed, download link, GitHub link, privacy notes, permission explanations, and FAQ sections.
- Added Cloudflare Pages headers and deployment notes for the static website.
- Fixed release archives containing an invalid app bundle signature by ad-hoc signing
FlowSound.appafter packaging. - Fixed generated GitHub Release notes keeping the literal
VERSIONplaceholder.
- Fixed the interrupted-restore service test using fixed sleeps that could fail on slower CI runners.
- Added public install, privacy, and security documentation for open-source distribution.
- Added release notes template for GitHub Releases.
- Added release packaging script that builds a zip archive and SHA-256 checksum file, with optional Developer ID signing and notarization.
- Added GitHub Actions release workflow for tagged builds and release artifact uploads.
- Fixed interrupted restore flows overwriting the saved Apple Music restore volume with an in-progress fade volume such as
0.
- Fixed launch-at-login registration being blocked when local app builds report
SMAppServicestatus asnotFound. - Fixed Preferences Save touching the login item when the launch-at-login checkbox state did not change.
- Fixed active detection being reset by brief low-RMS buffers before active duration could complete.
- Fixed repeated Preferences saves registering duplicate launch-at-login entries while approval was pending.
- Added excluded app bundle identifiers for all-apps monitoring mode.
- Added default exclusions for Apple Music, FlowSound, and common macOS notification services.
- Added Preferences editor for excluded bundle identifiers.
- Changed all-apps mode to use RMS tap activity as the active/quiet source while keeping process-output polling as diagnostics.
- Changed settings initialization to migrate old default timing values to the current defaults.
- Added audio monitoring mode setting with
All apps except Apple MusicandOnly watched appsoptions. - Added default all-apps monitoring that excludes Apple Music and FlowSound.
- Added Preferences control for switching monitoring modes.
- Added tests for monitoring mode defaults, persistence, and Apple Music exclusions.
- Changed default timings to active duration 1 second, quiet duration 3 seconds, fade-out 2 seconds, and fade-in 2 seconds.
- Changed the Core Audio process tap to use an exclusive tap in all-apps monitoring mode.
- Changed the process-output quiet release window to reduce active/quiet thrashing from the fallback detector.
- Added automatic Safari watched-app expansion to include WebKit audio helper bundle identifiers.
- Added Core Audio process-output polling as a fallback activity signal for watched apps.
- Added diagnostic logs for active candidates, audible samples, matched output processes, audio activity changes, service events, and state transitions.
- Added Apple Music playback-state check before ducking.
- Added tests for Safari helper bundle expansion.
- Changed Core Audio startup logs to include the expanded watched bundle identifiers.
- Changed ducking behavior so FlowSound skips pause/restore when Apple Music is not already playing.
- Added editable watched app bundle identifiers in Preferences.
- Added bundle identifier parsing, validation, deduplication, and persistence.
- Added settings tests for watched app whitelist parsing and storage.
- Changed Core Audio process tap setup to use the persisted watched app whitelist.
- Added launch-at-login control using
SMAppService.mainApp. - Added Preferences checkbox and status text for launch-at-login.
- Added shortcut from Preferences to System Settings Login Items.
- Reworked Preferences form layout to use fixed-height rows and avoid large spacing between fade settings.
- Added
CoreAudioProcessTapMonitorusing Core Audio process taps. - Added bundle ID-based audio capture for the fixed Safari and Telegram whitelist.
- Added RMS-based activity detection with active duration and quiet release timing.
- Added private aggregate device and IO proc setup for reading tap buffers.
- Changed default audio monitoring from manual simulation to Core Audio process tap monitoring.
- Moved Core Audio tap setup off the main AppKit thread.
- Added deactivated icon asset generation from
FlowSound-Deactivate-iCon.png. - Added active and inactive menu bar template icons.
- Added default service activation on app launch.
- Changed menu bar toggle wording to Activate / Deactivate.
- Changed menu bar icon rendering to follow the current activation state.
- Changed state labels from listening / disabled to activated / deactivated for user-facing status.
- Added Preferences window for threshold, timing, fade, and menu bar text settings.
- Added persistent settings storage through
UserDefaults. - Added generated
.icnsapp icon and bundle icon declaration. - Added appearance-aware About logo selection for light and dark mode.
- Changed startup diagnostics window to a manual menu action instead of showing on every launch.
- Changed menu bar presentation to respect the user's text visibility preference.
- Changed app packaging to generate iconset and
.icnsassets.
- Added explicit AppKit main entry point for the menu bar app.
- Added local diagnostics logging at
~/Library/Logs/FlowSound/FlowSound.log. - Added startup diagnostics window for development builds.
- Added diagnostics path menu item.
- Changed the status item to a fixed-width visible text-and-icon menu item.
- Improved diagnosis for cases where macOS launches FlowSound but the menu bar item is not visible.
- Added generated logo assets split from the supplied source artwork.
- Added visible menu bar icon fallback using a generated template image and text fallback.
- Changed the About window to use the split light-background logo asset.
- Changed app bundle builds to regenerate logo assets automatically.
- Fixed invisible menu bar status item when the previous SF Symbol name was unavailable.
- Added native Swift Package executable for the FlowSound menu bar app.
- Added AppKit status menu with enable, disable, quit, and manual audio simulation controls.
- Added ducking state machine for listening, ducking, paused, restoring, disabled, and error states.
- Added Apple Music controller using AppleScript through
osascript. - Added fade-out, pause, resume, and fade-in service orchestration.
- Added About window that displays the supplied FlowSound logo artwork.
- Added app bundle packaging script and Info.plist permission descriptions.
- Added state machine tests.
- Added project ignore rules for SwiftPM and Xcode build output.
- Initialized product documentation for FlowSound.
- Added technical feasibility assessment for macOS 26+ background music ducking.
- Documented required development, runtime, permission, and testing environment.
- Added initial architecture, roadmap, contribution process, and agent workflow notes.
- Added repository-level
AGENTS.mdinstructions for future agent work.