Source code for audiodev.android_audio

# SPDX-FileCopyrightText: 2026 Brad Barnett
#
# SPDX-License-Identifier: MIT
"""Android media session for `audiodev.PCMOutput`.

Hooks into ``PCMOutput(session=…)`` so the first ``open()`` / ``write()``
acquires audio focus and starts a ``mediaPlayback`` foreground service, and
the last ``close()`` releases both. Non-Android imports are a no-op.

Requires pyjnius and a p4a service named ``mediaplayback`` with
``:foreground:foregroundServiceType=mediaPlayback`` (see android-template).
"""

from __future__ import annotations

import sys
import threading

__all__ = ["AndroidMediaSession", "get_session"]

_LOCK = threading.RLock()
_SESSION = None


[docs] class AndroidMediaSession: """Duck-typed `audiodev.AudioSession` for Android media hardening. Multiple ``PCMOutput`` instances may share one session; FGS + focus stay up while any owner is open. """ def __init__(self): self._owners = [] self.codec = None self.duplex = True self._focus_listener = None self._started = False def get_codec(self): return self.codec def acquire(self, owner, direction): with _LOCK: if owner in self._owners: return self.codec if not self._owners: self._start_media() self._owners.append(owner) return self.codec def release(self, owner): with _LOCK: if owner in self._owners: self._owners.remove(owner) if not self._owners and self._started: self._stop_media() def _start_media(self): if sys.platform != "android": self._started = True return try: from jnius import PythonJavaClass, autoclass, java_method except ImportError as exc: raise RuntimeError( "Android audio_out needs pyjnius (add pyjnius to the APK)" ) from exc class _FocusListener(PythonJavaClass): __javainterfaces__ = [ "android/media/AudioManager$OnAudioFocusChangeListener" ] @java_method("(I)V") def onAudioFocusChange(self, focus_change): pass PythonActivity = autoclass("org.kivy.android.PythonActivity") AudioManager = autoclass("android.media.AudioManager") activity = PythonActivity.mActivity if activity is None: raise RuntimeError("PythonActivity.mActivity is not ready") am = activity.getSystemService("audio") listener = _FocusListener() # Keep a hard ref so the JVM callback is not GC'd. self._focus_listener = listener result = am.requestAudioFocus( listener, AudioManager.STREAM_MUSIC, AudioManager.AUDIOFOCUS_GAIN, ) if result == AudioManager.AUDIOFOCUS_REQUEST_FAILED: raise OSError("requestAudioFocus failed") pkg = activity.getPackageName() Service = autoclass(pkg + ".ServiceMediaplayback") # Notification keeps the mediaPlayback FGS visible (Android 14+). Service.start( activity, "", "PyDevices", "Playing audio", "", ) self._started = True self._audio_manager = am def _stop_media(self): if sys.platform != "android": self._started = False return try: from jnius import autoclass PythonActivity = autoclass("org.kivy.android.PythonActivity") activity = PythonActivity.mActivity am = getattr(self, "_audio_manager", None) listener = self._focus_listener if am is not None and listener is not None: try: am.abandonAudioFocus(listener) except Exception: pass if activity is not None: Service = autoclass(activity.getPackageName() + ".ServiceMediaplayback") Service.stop(activity) finally: self._focus_listener = None self._audio_manager = None self._started = False
[docs] def get_session(): """Return the process-wide Android media session (created once).""" global _SESSION with _LOCK: if _SESSION is None: _SESSION = AndroidMediaSession() return _SESSION