Control macOS Background Sounds

Author: txchen

src/background-sounds.jxa

@@ -43,6 +43,7 @@ function discoverSounds(settings, bundle) {
   }
   const seen = {};
   const sounds = [];
+  const objects = {};
   for (const sound of values) {
     const path = stringValue(sound.path);
     const usable = Boolean(path) && Boolean(fileManager.fileExistsAtPath(path));
@@ -51,14 +52,16 @@ function discoverSounds(settings, bundle) {
     if (!seen[option.id]) {
       seen[option.id] = true;
       sounds.push(option);
+      objects[option.id] = sound;
     }
   }
-  return sounds;
+  return { sounds: sounds, objects: objects };
 }
 
 function readSnapshot(settings, bundle) {
   const selected = soundOption(settings.selectedComfortSound);
-  const sounds = discoverSounds(settings, bundle);
+  const discovered = discoverSounds(settings, bundle);
+  const sounds = discovered.sounds;
   if (!sounds.some(function (sound) { return sound.id === selected.id; })) {
     throw new Error("The selected sound is not immediately usable");
   }
@@ -74,7 +77,7 @@ function readSnapshot(settings, bundle) {
 
 function run(argv) {
   const command = argv[0];
-  if (command !== "probe" && command !== "read") return failure("contract-mismatch", "Unsupported fixed command");
+  if (["probe", "read", "set-enabled", "set-sound", "set-volume"].indexOf(command) < 0) return failure("contract-mismatch", "Unsupported fixed command");
   try {
     const bundle = $.NSBundle.bundleWithPath(FRAMEWORK);
     if (!bundle || !bundle.load) return failure("framework-load", "HearingUtilities.framework could not be loaded");
@@ -89,6 +92,21 @@ function run(argv) {
       if (!responds(settings, selector)) return failure("contract-mismatch", "Required Background Sounds contract is unavailable");
     }
     if (!Boolean(settings.comfortSoundsAvailable)) return failure("unavailable", "Enable Background Sounds availability in macOS System Settings");
+    if (command === "set-enabled") {
+      if (argv[1] !== "true" && argv[1] !== "false") return failure("contract-mismatch", "Invalid enabled value");
+      settings.setComfortSoundsEnabled(argv[1] === "true");
+    } else if (command === "set-volume") {
+      const percent = Number(argv[1]);
+      if (!Number.isInteger(percent) || percent < 0 || percent > 100) return failure("contract-mismatch", "Invalid volume value");
+      settings.setRelativeVolume(percent / 100);
+    } else if (command === "set-sound") {
+      let id;
+      try { id = JSON.parse(argv[1]); } catch (_) { return failure("contract-mismatch", "Invalid sound id"); }
+      if (typeof id !== "string" || !id) return failure("contract-mismatch", "Invalid sound id");
+      const discovered = discoverSounds(settings, bundle);
+      if (!discovered.objects[id]) return failure("unavailable", "Open System Settings to download this Background Sound, then refresh.");
+      settings.setSelectedComfortSound(discovered.objects[id]);
+    }
     return envelope(true, { snapshot: readSnapshot(settings, bundle) });
   } catch (error) {
     return failure("contract-mismatch", error && error.message ? error.message : error);

src/background-sounds.ts

@@ -19,6 +19,9 @@ export type BackgroundSoundsFailureCode = typeof backgroundSoundsFailureCodes[nu
 export interface BackgroundSoundsControl {
   probe(signal?: AbortSignal): Promise<BackgroundSoundsSnapshot>;
   read(signal?: AbortSignal): Promise<BackgroundSoundsSnapshot>;
+  setEnabled(value: boolean, signal?: AbortSignal): Promise<BackgroundSoundsSnapshot>;
+  setSound(id: string, signal?: AbortSignal): Promise<BackgroundSoundsSnapshot>;
+  setVolume(percent: number, signal?: AbortSignal): Promise<BackgroundSoundsSnapshot>;
 }
 
 export class BackgroundSoundsError extends Error {
@@ -66,15 +69,36 @@ export class JxaBackgroundSoundsControl implements BackgroundSoundsControl {
 
   probe(signal?: AbortSignal): Promise<BackgroundSoundsSnapshot> { return this.invoke("probe", signal); }
   read(signal?: AbortSignal): Promise<BackgroundSoundsSnapshot> { return this.invoke("read", signal); }
+  async setEnabled(value: boolean, signal?: AbortSignal): Promise<BackgroundSoundsSnapshot> {
+    const snapshot = await this.invoke("set-enabled", signal, value ? "true" : "false");
+    return this.confirm(snapshot.enabled === value, snapshot);
+  }
+  async setSound(id: string, signal?: AbortSignal): Promise<BackgroundSoundsSnapshot> {
+    if (!id || id.length > 200) throw new BackgroundSoundsError("invalid-snapshot", "The selected Background Sound is invalid.");
+    const snapshot = await this.invoke("set-sound", signal, JSON.stringify(id));
+    return this.confirm(snapshot.sound.id === id, snapshot);
+  }
+  async setVolume(percent: number, signal?: AbortSignal): Promise<BackgroundSoundsSnapshot> {
+    if (!Number.isInteger(percent) || percent < 0 || percent > 100) {
+      throw new BackgroundSoundsError("invalid-snapshot", "Background Sound volume must be an integer from 0 to 100.");
+    }
+    const snapshot = await this.invoke("set-volume", signal, String(percent));
+    return this.confirm(snapshot.volumePercent === percent, snapshot);
+  }
+
+  private confirm(matches: boolean, snapshot: BackgroundSoundsSnapshot): BackgroundSoundsSnapshot {
+    if (!matches) throw new BackgroundSoundsError("apply-mismatch", "macOS did not confirm the requested Background Sounds change.");
+    return snapshot;
+  }
 
-  private async invoke(command: "probe" | "read", signal?: AbortSignal): Promise<BackgroundSoundsSnapshot> {
+  private async invoke(command: "probe" | "read" | "set-enabled" | "set-sound" | "set-volume", signal?: AbortSignal, value?: string): Promise<BackgroundSoundsSnapshot> {
     if (!existsSync(this.helperPath) && this.run === nodeExecFile) {
       throw new BackgroundSoundsError("helper-missing", "The bundled Background Sounds helper is missing. Reinstall TMU and retry.");
     }
     try {
       const result = await this.run(
         "/usr/bin/osascript",
-        ["-l", "JavaScript", this.helperPath, command],
+        ["-l", "JavaScript", this.helperPath, command, ...(value === undefined ? [] : [value])],
         { timeout: this.timeoutMs, maxBuffer: this.maxBufferBytes, shell: false, ...(signal ? { signal } : {}) },
       );
       return parseEnvelope(result.stdout);
@@ -137,4 +161,7 @@ export class UnavailableBackgroundSoundsControl implements BackgroundSoundsContr
   private fail(): never { throw new BackgroundSoundsError("unsupported-platform", "Background Sounds requires macOS 26.5 or newer."); }
   async probe(): Promise<BackgroundSoundsSnapshot> { return this.fail(); }
   async read(): Promise<BackgroundSoundsSnapshot> { return this.fail(); }
+  async setEnabled(): Promise<BackgroundSoundsSnapshot> { return this.fail(); }
+  async setSound(): Promise<BackgroundSoundsSnapshot> { return this.fail(); }
+  async setVolume(): Promise<BackgroundSoundsSnapshot> { return this.fail(); }
 }

src/coordinator.ts

@@ -54,6 +54,13 @@ import {
 import { UiStateStore, type UiStateAction } from "./ui-state";
 import { BackgroundSoundsError, type BackgroundSoundsControl } from "./background-sounds";
 
+type BackgroundSoundsOperation =
+  | { type: "probe" }
+  | { type: "read" }
+  | { type: "setEnabled"; value: boolean }
+  | { type: "setSound"; value: string }
+  | { type: "setVolume"; value: number };
+
 export type DependencyHealthRefresh = (
   helper: HelperName,
   currentHealth: DependencyHealthState,
@@ -113,6 +120,7 @@ export class AppCoordinator {
   private readonly backgroundSoundsControl?: BackgroundSoundsControl;
   private backgroundSoundsTail: Promise<void> = Promise.resolve();
   private backgroundSoundsAbort: AbortController | null = null;
+  private backgroundVolumeTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(options: AppCoordinatorOptions) {
     this.appState = options.appState;
@@ -165,18 +173,47 @@ export class AppCoordinator {
   async enterBackgroundSounds(): Promise<void> {
     const shouldProbe = this.appState.backgroundSounds.status === "candidate"
       || this.appState.backgroundSounds.status === "unavailable";
-    await this.runBackgroundSounds(shouldProbe ? "probe" : "read");
+    await this.runBackgroundSounds({ type: shouldProbe ? "probe" : "read" });
   }
 
   async refreshBackgroundSounds(): Promise<void> {
-    await this.runBackgroundSounds(this.appState.backgroundSounds.status === "candidate" ? "probe" : "read");
+    await this.runBackgroundSounds({ type: this.appState.backgroundSounds.status === "candidate" ? "probe" : "read" });
   }
 
   async retryBackgroundSounds(): Promise<void> {
-    await this.runBackgroundSounds(this.appState.backgroundSounds.status === "unavailable" ? "probe" : "read");
+    await this.runBackgroundSounds({ type: this.appState.backgroundSounds.status === "unavailable" ? "probe" : "read" });
+  }
+
+  async setBackgroundSoundsEnabled(value: boolean): Promise<void> {
+    if (this.appState.backgroundSounds.status !== "ready") return;
+    await this.runBackgroundSounds({ type: "setEnabled", value });
+  }
+
+  async cycleBackgroundSound(delta: 1 | -1): Promise<void> {
+    const state = this.appState.backgroundSounds;
+    if (state.status !== "ready") return;
+    const current = state.snapshot.sounds.findIndex((sound) => sound.id === state.snapshot.sound.id);
+    const index = (current + delta + state.snapshot.sounds.length) % state.snapshot.sounds.length;
+    const target = state.snapshot.sounds[index];
+    if (target) await this.runBackgroundSounds({ type: "setSound", value: target.id });
+  }
+
+  adjustBackgroundSoundsVolume(delta: 1 | -1): void {
+    const state = this.appState.backgroundSounds;
+    if (state.status !== "ready") return;
+    const current = this.uiState.background.pendingVolumePercent ?? state.snapshot.volumePercent;
+    const target = Math.max(0, Math.min(100, current + delta * 5));
+    this.dispatchUi({ type: "setBackgroundPendingVolume", percent: target });
+    if (this.backgroundVolumeTimer) clearTimeout(this.backgroundVolumeTimer);
+    this.backgroundVolumeTimer = setTimeout(() => {
+      this.backgroundVolumeTimer = null;
+      void this.runBackgroundSounds({ type: "setVolume", value: target }).finally(() => {
+        this.dispatchUi({ type: "setBackgroundPendingVolume", percent: null });
+      });
+    }, 150);
   }
 
-  private async runBackgroundSounds(operation: "probe" | "read"): Promise<void> {
+  private async runBackgroundSounds(operation: BackgroundSoundsOperation): Promise<void> {
     if (!this.backgroundSoundsControl || this.appState.backgroundSounds.status === "hidden" || this.tornDown) return;
     const task = async () => {
       const previous = this.appState.backgroundSounds;
@@ -187,7 +224,14 @@ export class AppCoordinator {
       const controller = new AbortController();
       this.backgroundSoundsAbort = controller;
       try {
-        const snapshot = await this.backgroundSoundsControl![operation](controller.signal);
+        const control = this.backgroundSoundsControl!;
+        const snapshot = operation.type === "setEnabled" ? await control.setEnabled(operation.value, controller.signal)
+          : operation.type === "setSound" ? await control.setSound(operation.value, controller.signal)
+            : operation.type === "setVolume" ? await control.setVolume(operation.value, controller.signal)
+              : await control[operation.type](controller.signal);
+        if ("snapshot" in previous && mutationChangedIndependentBackgroundValues(operation, previous.snapshot, snapshot)) {
+          throw new BackgroundSoundsError("apply-mismatch", "macOS changed an independent Background Sounds setting; refresh and retry.");
+        }
         this.appState.backgroundSounds = { status: "ready", snapshot };
       } catch (error) {
         if (this.tornDown && error instanceof BackgroundSoundsError && error.code === "cancelled") return;
@@ -286,6 +330,9 @@ export class AppCoordinator {
   async teardown(): Promise<void> {
     if (this.tornDown) return;
     this.tornDown = true;
+    if (this.backgroundVolumeTimer) clearTimeout(this.backgroundVolumeTimer);
+    this.backgroundVolumeTimer = null;
+    this.dispatchUi({ type: "setBackgroundPendingVolume", percent: null });
     this.backgroundSoundsAbort?.abort();
     await this.saveLastPlaylistSnapshot({ meaningful: false });
     this.pendingDownloadBatches.length = 0;
@@ -1427,3 +1474,15 @@ export class AppCoordinator {
     for (const listener of this.stateListeners) listener(reason);
   }
 }
+
+function mutationChangedIndependentBackgroundValues(
+  operation: BackgroundSoundsOperation,
+  before: import("./background-sounds").BackgroundSoundsSnapshot,
+  after: import("./background-sounds").BackgroundSoundsSnapshot,
+): boolean {
+  const sameSound = before.sound.id === after.sound.id;
+  if (operation.type === "setEnabled") return !sameSound || before.volumePercent !== after.volumePercent;
+  if (operation.type === "setSound") return before.enabled !== after.enabled || before.volumePercent !== after.volumePercent;
+  if (operation.type === "setVolume") return before.enabled !== after.enabled || !sameSound;
+  return false;
+}

src/domain.ts

@@ -252,7 +252,7 @@ export type UiState = {
     selectedBatchIndex: number;
     scroll: number;
   };
-  background: { selectedRow: number };
+  background: { selectedRow: number; pendingVolumePercent: number | null };
   terminal: {
     columns: number;
     rows: number;

src/ui-state.ts

@@ -23,6 +23,7 @@ export type UiStateAction =
   | { type: "setDownloaderInputFocus"; focused: boolean }
   | { type: "setDownloaderBatchSelection"; index: number; resultCount: number }
   | { type: "setBackgroundSelection"; index: number }
+  | { type: "setBackgroundPendingVolume"; percent: number | null }
   | { type: "setPendingVimChord"; pending: boolean }
   | { type: "selectPlaylistTrack"; index: number; identities: readonly TrackIdentity[] }
   | { type: "resetPlaylistSelection"; index: number; identities: readonly TrackIdentity[] }
@@ -59,7 +60,7 @@ export function createInitialUiState(options: InitialUiStateOptions = {}): UiSta
     selectedPlaylistIdentity: null,
     library: { query: "", inputFocused: false, selectedIndex: 0, healthSelectedIndex: 0, scroll: 0 },
     downloader: { urlInput: "", inputFocused: true, selectedBatchIndex: 0, scroll: 0 },
-    background: { selectedRow: 0 },
+    background: { selectedRow: 0, pendingVolumePercent: null },
     terminal: { columns, rows, tier: responsiveTier(columns, rows) },
     pendingConfirmation: null,
     renameDialog: null,
@@ -122,7 +123,9 @@ export function reduceUiState(state: UiState, action: UiStateAction): UiState {
         downloader: { ...state.downloader, selectedBatchIndex, scroll: visibleScroll(state.downloader.scroll, selectedBatchIndex) },
       }; }
     case "setBackgroundSelection":
-      return { ...state, background: { selectedRow: clampIndex(action.index, 3) } };
+      return { ...state, background: { ...state.background, selectedRow: clampIndex(action.index, 3) } };
+    case "setBackgroundPendingVolume":
+      return { ...state, background: { ...state.background, pendingVolumePercent: action.percent } };
     case "setPendingVimChord":
       return { ...state, pendingVimChord: action.pending ? { key: "g", expiresAtMs: Date.now() + 1_000 } : null };
     case "selectPlaylistTrack": {

src/vue-tui/component.ts

@@ -665,6 +665,7 @@ function backgroundView(snapshot: PublicationSnapshot, noColor: boolean) {
   }
   if (!("snapshot" in state)) return null;
   const snapshotValue = state.snapshot;
+  const pendingVolume = snapshot.uiState.background.pendingVolumePercent;
   const stale = state.status === "degraded";
   const busy = state.status === "busy";
   const filled = Math.round(snapshotValue.volumePercent / 10);
@@ -673,7 +674,7 @@ function backgroundView(snapshot: PublicationSnapshot, noColor: boolean) {
     h(Text, () => ""),
     row(0, "Background Sounds", snapshotValue.enabled ? "● On" : "○ Off"),
     row(1, "Sound", `‹ ${snapshotValue.sound.label} ›`),
-    row(2, "Volume", `[${"■".repeat(filled)}${"·".repeat(10 - filled)}] ${snapshotValue.volumePercent}%`),
+    row(2, "Volume", `[${"■".repeat(filled)}${"·".repeat(10 - filled)}] ${snapshotValue.volumePercent}%${pendingVolume === null ? "" : ` → ${pendingVolume}% pending`}`),
     h(Text, { dimColor: true }, () => `  ${"State".padEnd(20)}${busy ? "Refreshing from macOS…" : stale ? "Stale · press u to retry" : "Confirmed from macOS"}`),
     stale ? h(Text, { color: noColor ? undefined : "red" }, () => state.error) : null,
   ]);
@@ -689,8 +690,18 @@ async function routeBackground(input: string, key: InputKey, coordinator: AppCoo
     coordinator.dispatchUi({ type: "setBackgroundSelection", index: coordinator.uiState.background.selectedRow + delta });
     return true;
   }
-  // Read-only slice: consume arrows on Settings rows so they never seek the Player.
-  return Boolean(key.leftArrow || key.rightArrow || key.return);
+  if (!key.leftArrow && !key.rightArrow && !key.return) return false;
+  const state = coordinator.appState.backgroundSounds;
+  if (state.status !== "ready") return true;
+  const row = coordinator.uiState.background.selectedRow;
+  if (row === 0) {
+    if (key.leftArrow) await coordinator.setBackgroundSoundsEnabled(false);
+    else if (key.rightArrow) await coordinator.setBackgroundSoundsEnabled(true);
+    else await coordinator.setBackgroundSoundsEnabled(!state.snapshot.enabled);
+  }
+  else if (row === 1) await coordinator.cycleBackgroundSound(key.leftArrow ? -1 : 1);
+  else if (row === 2 && (key.leftArrow || key.rightArrow)) coordinator.adjustBackgroundSoundsVolume(key.leftArrow ? -1 : 1);
+  return true;
 }
 
 function activePlaylistName(appState: PublicationSnapshot["appState"]): string {
@@ -1057,7 +1068,7 @@ function activeShortcutGroups(tab: UiState["activeTab"], incompleteSelected: boo
     title: "BACKGROUND SOUNDS",
     rows: [
       ["j/k, ↑/↓", "Move selection"], ["u", "Refresh or retry macOS state"],
-      ["←/→, Enter", "Controls are read-only in this release"],
+      ["←/→", "Adjust focused sound or volume"], ["Enter", "Activate focused control"],
     ],
   }];
   return [
@@ -1198,7 +1209,7 @@ function footer(ui: UiState, incompleteSelected = false, noColor = false) {
             ? [["j/k", "Move"], ["/", "Search"], ["Enter", "Play"], ["a", "Add"], ["?", "Help"]]
             : [["j/k", "Move"], ["/", "Search"], ["Enter", "Play"], ["a", "Add to Playlist"], ["e", "Rename"], ["?", "Help"]]
           : ui.activeTab === "background"
-            ? [["j/k", "Move"], ["u", "Refresh"], ["?", "Help"]]
+            ? [["j/k", "Move"], ["←/→", "Adjust"], ["Enter", "Activate"], ["u", "Refresh"], ["?", "Help"]]
           : ui.downloader.inputFocused
             ? [["Type", "URL"], ["Enter", "Submit"], ["Esc/Tab → ?", "Help"]]
             : [["j/k", "Move"], ["x", "Cancel/Remove"], ["gg/G", "Ends"], ["Tab", "Focus"], ["?", "Help"]];