fix: route audio-only playback through afplay on macOS to avoid mpv/CoreAudio issue

[Annincikee]

Linked issue

Fixes #5157 for me locally (see verification below), but this is a
workaround, not a diagnosed root-cause fix in mpv/CoreAudio — see "Risk /
compatibility" for what that means, and I'd welcome maintainer input on
whether this is the right approach vs. something more surgical in mpv
itself (e.g. a newer bundled mpv, or an mpv.conf-level fix for the
channel-mapping issue below).

Summary / motivation

On macOS, mpv/MpvManager is used for both audio and video playback. On
my own Mac (macOS 27 beta, Anki 26.05), audio-only card playback was
cutting off partway through — the same symptom reported in #5157. The
unified log showed entries like this around each cutoff:

(AudioToolboxCore) [com.apple.coreaudio:AudioConverter] channel mapping input channel '6619138' for output channel '0' is out of range [-1..'2')
(CoreAudio) [com.apple.coreaudio:AUHAL]  AUHAL.cpp:683  SelectDevice: (0x78e73cc040) disconnecting device 102
(AudioSession) [com.apple.coreaudio:as_client] SessionCore_macOS_Legacy.mm:163  --> setPlayState Stopped  Output {BuiltInSpeakerDevice, 0xf}

Caveat: I have not root-caused this inside mpv/CoreAudio itself — I
don't know why the channel mapping is failing, only that avoiding mpv's
CoreAudio output path for audio-only playback makes the cutoff go away on
my machine (see "How to test").

Since the overwhelming majority of [sound:...] tags are audio-only, this
PR routes audio-only SoundOrVideoTags through the system's built-in
afplay binary on macOS instead of mpv/MpvManager, avoiding mpv's
CoreAudio output path entirely for that case. Video playback is
unaffected and still goes through mpv, since afplay only handles audio.

Implementation notes

• SimpleAfplayPlayer is a new SimpleProcessPlayer/SoundPlayer that
  shells out to /usr/bin/afplay, ranked above MpvManager so it's
  chosen for audio tags; video tags still fall through to mpv since
  SimpleAfplayPlayer.rank_for_tag returns None for them.
• afplay doesn't accept -- as an options/filename separator (unlike
  mpv/mplayer), so SimpleProcessPlayer gained a supports_arg_separator
  flag that SimpleAfplayPlayer opts out of; mpv/mplayer/Windows/Linux
  behavior is unchanged (flag defaults to True).

How to test

Checklist (minimum)

• Ran the relevant local checks (see below).
• No new automated test was added for the afplay path itself (see
  "Risk" below for why, and happy to add one if maintainers want a
  particular shape) — existing qt/tests/test_sound.py coverage
  (mpv packaging/playback) still passes unmodified.

What I actually verified

• Hit the [macOS 27] Audio playback stops before completion in Anki 26.05 #5157 cutoff myself on macOS 27 beta / Anki 26.05, built this
  patch locally, packaged it into a DMG via the normal Briefcase
  installer path, installed it on my own Mac, and confirmed audio-only
  cards now play to completion — the cutoff is gone for me.
• just build and RELEASE=1 ./ninja pylib qt succeed.
• ruff check / mypy clean on qt/aqt/sound.py.
• check:pytest (pylib + qt): 83/84 pass; the one failure
  (test_compile_fails_loudly) is a pre-existing test that hits a live
  network download and is unrelated to this change.
• Confirmed via strings on the packaged aqt/sound.pyc that the
  bundled build contains the new SimpleAfplayPlayer/afplay code path.

What I did NOT verify

• Single data point (my machine only) — haven't heard back yet from
  other [macOS 27] Audio playback stops before completion in Anki 26.05 #5157 reporters on whether this resolves it for them too.
• No playback-quality/timing testing across different sample rates or
  channel layouts.
• afplay's format coverage (CoreAudio-backed) vs. mpv's for every
  extension in AUDIO_EXTENSIONS (e.g. ogg/opus/spx) — not
  verified across all of them.

Risk / compatibility / migration

• Change is scoped to macOS only; Windows/Linux continue to use
  mpv/mplayer through SimpleProcessPlayer unchanged.
• afplay has a narrower feature set than mpv (no seek/pause API is
  wired up for it, since Player.seek_relative/toggle_pause are
  optional no-ops by default) — audio-only cards lose in-player
  seek/pause that mpv provided. This is a real functional regression,
  not just a routing change, and the main thing I'd want maintainer
  opinion on before this is mergeable as-is.
• afplay's format support may not exactly match mpv's for every
  extension in AUDIO_EXTENSIONS; unverified.

UI evidence

N/A — backend audio-playback routing change, no UI change.

Scope

• This PR is focused on one change (no unrelated edits).

[read-the-docs-community]

Documentation build overview

📚 Anki | 🛠️ Build #33752898 | 📁 Comparing c1a561d against latest (3e4a0a6)

  🔍 Preview build  

2 files changed

± genindex.html
± autoapi/aqt/sound/index.html

[abdnh]

Bypassing mpv is not the right approach - pretty sure it doesn't support all formats (e.g. opus).

We'll look into the issue once 26.08 is out.