VoiceServer: afplay (macOS-only) breaks audio on Linux — silent failure

[pkumaschow]

Summary

VoiceServer/server.ts hardcodes /usr/bin/afplay for audio playback. afplay is macOS-only and does not exist on Linux, causing all TTS notifications to fail silently with ENOENT. Because the startup catchphrase is fired as a detached fire-and-forget curl, the error is never surfaced to the user — the voice server appears to work but produces no audio.

Affected Files

• VoiceServer/server.ts — playAudio() function (~line 379)
• VoiceServer/start.sh, stop.sh, restart.sh — use launchctl (macOS-only), fail silently on Linux

Error

{"status":"error","message":"TTS failed: ENOENT: no such file or directory, posix_spawn '/usr/bin/afplay'"}

Platform

• Linux (tested on Fedora 43, kernel 6.18)
• macOS unaffected

What Breaks

• Startup catchphrase never plays
• Algorithm phase voice announcements never play
• All /notify POST calls return status: error
• No visible error to the user (fire-and-forget curl swallows it)

Regression Vector

Every PAI migration/reinstall that overwrites VoiceServer/server.ts from the upstream repo reverts any local Linux fix, breaking voice again silently.

Proposed Fix

In playAudio(), detect the platform and use ffplay (part of ffmpeg, widely available on Linux) instead of afplay:

// Play audio — afplay on macOS, ffplay on Linux
async function playAudio(audioBuffer: ArrayBuffer, volume: number = FALLBACK_VOLUME): Promise<void> {
  const tempFile = `/tmp/voice-${Date.now()}.mp3`;
  await Bun.write(tempFile, audioBuffer);

  const isMac = process.platform === 'darwin';
  const player = isMac ? '/usr/bin/afplay' : '/usr/bin/ffplay';
  const args = isMac
    ? ['-v', volume.toString(), tempFile]
    : ['-nodisp', '-autoexit', '-volume', Math.round(volume * 100).toString(), tempFile];

  return new Promise((resolve, reject) => {
    const proc = spawn(player, args);
    proc.on('error', (error) => { reject(error); });
    proc.on('exit', (code) => {
      spawn('/bin/rm', [tempFile]);
      if (code === 0) resolve();
      else reject(new Error(`${isMac ? 'afplay' : 'ffplay'} exited with code ${code}`));
    });
  });
}

ffplay is available at /usr/bin/ffplay on most Linux distros via the ffmpeg package. For distros without ffmpeg, mpg123 is a lighter alternative for MP3 playback.

The start.sh/stop.sh/restart.sh scripts similarly need Linux-compatible process management (e.g. PID file approach) instead of launchctl.

[bgturner]

Tested on: Ubuntu 24.04.4 LTS, PAI v5.0.0, bun v1.3.9

Confirmed. On Linux, afplay doesn't exist — posix_spawn '/usr/bin/afplay' throws ENOENT and TTS silently fails after generating audio. The audio file is created and then nothing plays.

Fix

Prerequisite:

sudo apt install ffmpeg

VoiceServer/server.ts (or PULSE/VoiceServer/voice.ts in unified Pulse):

Add an OS detection constant near the top of the file:

const IS_MACOS = process.platform === "darwin"

Update playAudio to branch on it:

async function playAudio(audioBuffer: ArrayBuffer, volume: number = 1.0): Promise<void> {
  const tempFile = `/tmp/voice-${Date.now()}.mp3`
  await Bun.write(tempFile, audioBuffer)

  return new Promise((resolve, reject) => {
    // afplay volume is a float multiplier (1.0 = normal); ffplay -volume is 0–100
    const proc = IS_MACOS
      ? spawn("/usr/bin/afplay", ["-v", volume.toString(), tempFile])
      : spawn("/usr/bin/ffplay", [
          "-nodisp",        // suppress the display window (required on headless/non-X sessions)
          "-autoexit",      // exit when audio completes instead of waiting for keypress
          "-loglevel", "quiet",
          "-volume", String(Math.min(200, Math.round(volume * 100))),  // ffplay scale: 0–100
          tempFile,
        ])

    proc.on("error", (err) => reject(err))
    proc.on("exit", (code) => {
      spawn("/bin/rm", [tempFile])
      if (code === 0) resolve()
      else reject(new Error(`audio player exited with code ${code}`))
    })
  })
}

Three Linux-specific details that bite if missed:

1. -nodisp is required — without it, ffplay opens an SDL window, which crashes on headless/Wayland sessions
2. -autoexit is required — without it, ffplay waits indefinitely for a keypress after audio finishes
3. Volume scale: afplay takes 1.0 for normal; ffplay takes 100 for normal — scale with Math.round(volume * 100)

Management scripts

If the VoiceServer has its own install.sh / start.sh using launchctl, those need Linux branches too (systemctl --user, same pattern as the Pulse manage.sh fix in #1185). In the unified Pulse v5.0 architecture the voice module runs inside Pulse itself, so this is handled by manage.sh.

Verification

$ curl -s http://localhost:31337/notify -X POST \
    -H "Content-Type: application/json" \
    -d '{"message":"hello","voice_enabled":true}'
{"status":"success","message":"Notification sent"}
# → audio plays via ffplay on Linux

Happy to open a PR if this direction is confirmed.

[danielmiessler]

Hey @pkumaschow, thanks for raising this, and sorry it sat for a while.

We're changing how LifeOS ships. Instead of cloning a full ~/.claude directory and running it as a complete system, LifeOS is becoming a skill you install through an agentic installer. The installer hands integration to your own AI, which reads your actual machine (your OS, your paths, your harness) and wires the hooks and system prompt in where they belong.

That's aimed right at what you hit here. The old "one directory, one layout, hope it matches your setup" approach is exactly what broke for so many people, and the new model should handle it far better because your AI does the integration per machine instead of us guessing.

So we're closing this in prep for that release. If it still bites you once the skill-based version is out, reopen or file a fresh one and we'll jump on it. Appreciate you taking the time.