axiom-now-playing-carplay

CarPlay 集成

耗时：15-20 分钟（如果 MPNowPlayingInfoCenter 已正常工作）

关键要点

CarPlay 使用与锁定屏幕和控制中心相同的 MPNowPlayingInfoCenter 和 MPRemoteCommandCenter。 如果你的“正在播放”集成在 iOS 上正常工作，那么它在 CarPlay 中也会自动生效，无需添加任何代码。

CarPlay 会读取什么

iOS 组件	CarPlay 显示内容
MPNowPlayingInfoCenter.nowPlayingInfo	CPNowPlayingTemplate 元数据（标题、艺术家、封面图）
MPRemoteCommandCenter 处理程序	CPNowPlayingTemplate 按钮响应
nowPlayingInfo 中的封面图	CarPlay UI 中的专辑封面

无需 CarPlay 专用元数据。现有代码即可正常工作。

CPNowPlayingTemplate 自定义（iOS 14+）

如需使用标准播放/暂停/跳过之外的自定义播放控制：

import CarPlay

@MainActor
class SceneDelegate: UIResponder, UIWindowSceneDelegate, CPTemplateApplicationSceneDelegate {

    func templateApplicationScene(
        _ templateApplicationScene: CPTemplateApplicationScene,
        didConnect interfaceController: CPInterfaceController
    ) {
        // ✅ Configure CPNowPlayingTemplate at connection time (not when pushed)
        let nowPlayingTemplate = CPNowPlayingTemplate.shared

        // Enable Album/Artist browsing (shows button that navigates to album/artist view in your app)
        nowPlayingTemplate.isAlbumArtistButtonEnabled = true

        // Enable Up Next queue (shows button that displays upcoming tracks)
        nowPlayingTemplate.isUpNextButtonEnabled = true

        // Add custom buttons (iOS 14+)
        setupCustomButtons(for: nowPlayingTemplate)
    }

    private func setupCustomButtons(for template: CPNowPlayingTemplate) {
        var buttons: [CPNowPlayingButton] = []

        // Playback rate button
        let rateButton = CPNowPlayingPlaybackRateButton { [weak self] button in
            self?.cyclePlaybackRate()
        }
        buttons.append(rateButton)

        // Shuffle button
        let shuffleButton = CPNowPlayingShuffleButton { [weak self] button in
            self?.toggleShuffle()
        }
        buttons.append(shuffleButton)

        // Repeat button
        let repeatButton = CPNowPlayingRepeatButton { [weak self] button in
            self?.cycleRepeatMode()
        }
        buttons.append(repeatButton)

        // Update template with custom buttons
        template.updateNowPlayingButtons(buttons)
    }
}

权限要求

CarPlay 要求在 Xcode 项目中添加权限：

Info.plist：

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Entitlements 文件：

<key>com.apple.developer.carplay-audio</key>
<true/>

如果没有此权限，CarPlay 将完全不显示你的应用。

CarPlay 特有注意事项

问题	原因	解决方法	耗时
CarPlay 不显示应用	缺少权限	添加 com.apple.developer.carplay-audio	5 分钟
CarPlay 中“正在播放”为空白	未设置 MPNowPlayingInfoCenter	与锁定屏幕使用相同的修复方法（模式 1）	10 分钟
自定义按钮未显示	在推送后才配置	在 templateApplicationScene(_:didConnect:) 中配置	5 分钟
按钮在设备上可用，但在 CarPlay 模拟器中不可用	调试器干扰	不连接调试器进行测试	1 分钟
缺少专辑封面	与 iOS 问题相同	修复 MPMediaItemArtwork（模式 3）	15 分钟

测试 CarPlay

模拟器（Xcode 12+）：

1. I/O → 外接显示器 → CarPlay
2. 轻点 CarPlay 显示屏
3. 在“音频”部分找到你的应用
4. 重要：为确保测试可靠，请在不连接调试器的情况下运行（调试器可能干扰 CarPlay 音频会话的激活）

真实车辆： 需要获得 Apple 的权限批准（对于启用了 UIBackgroundModes 音频模式的应用会自动批准；无需手动申请）。

验证

• 应用显示在 CarPlay 的“音频”部分
• “正在播放”显示正确的元数据
• 显示专辑封面
• 播放/暂停/跳过按钮响应正常
• 自定义按钮（如有）显示且可正常工作
• 已分别在连接和未连接调试器的情况下测试

资源

技能：axiom-now-playing、axiom-now-playing-musickit