Android 10+ 如何用AudioPlaybackCapture API录制系统声音？完整代码示例

Android 10+ 系统音频录制实战：深入AudioPlaybackCapture API与完整实现

在移动应用开发中，音频处理一直是一个充满挑战的领域。对于许多开发者而言，录制来自设备内部的音频——比如游戏激战时的音效、流媒体音乐播放的片段，或是视频会议中对方的声音——曾经是一个难以逾越的技术壁垒。传统的AudioRecord API只能捕获麦克风输入，对于系统内部播放的音频流，安卓系统出于安全和隐私的考虑，长期将其隔离在应用沙盒之外。这种限制催生了许多复杂且不稳定的“曲线救国”方案，例如依赖辅助功能（Accessibility Service）模拟屏幕录制并提取音频，或是尝试通过底层音频路由进行拦截，这些方法不仅实现繁琐，而且兼容性极差，在不同厂商的设备上表现各异。

随着Android 10（API级别29）的发布，谷歌官方终于为这一需求打开了一扇门：AudioPlaybackCapture API。这个API的引入，标志着安卓系统首次在非Root环境下，为应用提供了合法、可控地捕获其他应用音频输出的能力。它并非一个简单的“录音”功能升级，而是安卓音频架构的一次重要演进，旨在支持屏幕录制、游戏直播、无障碍字幕生成等丰富的用户体验场景。然而，与任何强大的能力相伴的是复杂的权限模型和精细的使用约束。许多开发者在初次接触AudioPlaybackCapture时，往往会陷入权限配置错误、捕获不到声音、或者音频质量不佳的困境。

本文将从一个实践者的角度，深入剖析AudioPlaybackCapture API的设计哲学、核心机制与实战要点。我们将不再重复官方文档中那些基础的代码片段，而是聚焦于如何在实际项目中稳健、高效地集成这一功能。你会了解到权限声明的“潜规则”，掌握配置捕获策略以平衡功能与用户体验的技巧，并通过一个完整的、包含错误处理与性能优化的示例项目，彻底弄懂如何让系统音频录制功能在你的应用中可靠运行。无论你是想为应用添加游戏精彩时刻录制，还是构建一个专业的音频分析工具，这篇文章都将为你提供从原理到落地的完整路径。

1. 理解AudioPlaybackCapture：权限、策略与系统架构

在编写第一行代码之前，深刻理解AudioPlaybackCapture的工作机制和限制条件至关重要。这能帮助你在后续开发中避开许多“坑”。

1.1 核心权限模型与隐私保护

AudioPlaybackCapture功能的核心是CAPTURE_AUDIO_OUTPUT权限。这是一个签名（signature）|特权（privileged） 级别的权限。这意味着：

• 对于普通应用（非系统应用）：你无法在AndroidManifest.xml中简单地声明并使用它。尝试声明<uses-permission android:name="android.permission.CAPTURE_AUDIO_OUTPUT" />对于上架到公开应用商店（如Google Play）的应用是无效的，该权限不会被授予。
• 正确的使用途径：普通应用必须通过媒体投影（MediaProjection） API来间接获得音频捕获的能力。具体来说，你需要先请求用户授权进行屏幕捕获（包括音频），系统在用户同意后会返回一个MediaProjection对象，然后你可以利用这个对象来配置AudioPlaybackCapture。这是谷歌设计的隐私保护关键一环，确保了用户对“被录音”拥有完全的知情权和控制权。

注意：网络上一些早期资料或针对特定设备（如已Root设备）的教程可能会直接讨论CAPTURE_AUDIO_OUTPUT权限，这对于开发面向大众的通用应用是具有误导性的。我们的实现将严格遵循通过MediaProjection获取授权的标准路径。

1.2 捕获配置策略：精细控制录制范围

AudioPlaybackCaptureConfiguration是API的指挥中心，它决定了你能捕获哪些音频流。构建配置时，你需要考虑三个维度的策略：

1. 排除策略（Exclusion Rules）：你可以指定哪些应用或音频用途的音频不被捕获。这是保护用户隐私和遵守平台政策的关键。

   • addMatchingUid(int uid): 排除指定UID（用户ID）的应用。
   • addMatchingUsage(@AudioAttributes.AttributeUsage int usage): 排除特定用途的音频，例如USAGE_VOICE_COMMUNICATION（语音通话）和USAGE_ASSISTANCE_ACCESSIBILITY（无障碍服务）默认就是被排除的，你通常也不应该去捕获它们。

2. 捕获策略（Capture Policy）：定义当有音频被排除规则过滤时，系统的行为。

   • CAPTURE_POLICY_ALWAYS: 始终捕获，即使部分音频被排除。这是最常用的策略。
   • CAPTURE_POLICY_AUTO: 如果目标音频流中任何部分被排除，则整个捕获请求会被拒绝。更严格，但能确保捕获内容的“纯净性”。

3. 音频属性匹配：你还可以通过AudioAttributes来精细匹配希望捕获的音频类型，比如只捕获媒体播放（USAGE_MEDIA）或游戏音频（USAGE_GAME）。

下面是一个配置示例的对比表格，展示了不同策略组合的意图：

1.3 系统音频路由与混音原理

了解音频数据如何从应用流向你的录制缓冲区，有助于调试问题。当多个应用同时播放声音时（例如，后台播放音乐的同时玩一款游戏），安卓音频系统会将所有这些音频流混音（Mix） 成一个最终的输出流，发送给扬声器或耳机。AudioPlaybackCapture API捕获的正是这个混音后的最终输出流的一个副本。

这意味着：

• 你捕获到的是所有可捕获音频的混合体，无法在录制后分离出单个应用的声音（除非你在配置中排除了其他所有应用）。
• 捕获的音频质量（采样率、声道数）由你在创建A