axiom-now-playing-carplay

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CarPlay Integration

CarPlay集成

Time cost: 15-20 minutes (if MPNowPlayingInfoCenter already working)

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

Key Insight

核心要点

CarPlay uses the SAME MPNowPlayingInfoCenter and MPRemoteCommandCenter as Lock Screen and Control Center. If your Now Playing integration works on iOS, it automatically works in CarPlay with zero additional code.

**CarPlay与锁屏和控制中心使用相同的MPNowPlayingInfoCenter和MPRemoteCommandCenter。**如果你的Now Playing集成在iOS上正常运行，它将自动在CarPlay中生效，无需额外编写任何代码。

What CarPlay Reads

CarPlay读取的内容

iOS Component	CarPlay Display
`MPNowPlayingInfoCenter.nowPlayingInfo`	CPNowPlayingTemplate metadata (title, artist, artwork)
`MPRemoteCommandCenter` handlers	CPNowPlayingTemplate button responses
Artwork from `nowPlayingInfo`	Album art in CarPlay UI

No CarPlay-specific metadata needed. Your existing code works.

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

无需CarPlay专属元数据，现有代码即可直接使用。

CPNowPlayingTemplate Customization (iOS 14+)

CPNowPlayingTemplate定制（iOS 14+）

For custom playback controls beyond standard play/pause/skip:

swift

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)
    }
}

如需实现播放/暂停/切歌之外的自定义播放控制：

swift

import CarPlay

@MainActor
class SceneDelegate: UIResponder, UIWindowSceneDelegate, CPTemplateApplicationSceneDelegate {

    func templateApplicationScene(
        _ templateApplicationScene: CPTemplateApplicationScene,
        didConnect interfaceController: CPInterfaceController
    ) {
        // ✅ 在连接时配置CPNowPlayingTemplate（而非推送时）
        let nowPlayingTemplate = CPNowPlayingTemplate.shared

        // 启用专辑/艺术家浏览（显示可跳转到应用内专辑/艺术家页面的按钮）
        nowPlayingTemplate.isAlbumArtistButtonEnabled = true

        // 启用“下一曲列表”（显示可查看即将播放曲目列表的按钮）
        nowPlayingTemplate.isUpNextButtonEnabled = true

        // 添加自定义按钮（iOS 14+）
        setupCustomButtons(for: nowPlayingTemplate)
    }

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

        // 播放速率按钮
        let rateButton = CPNowPlayingPlaybackRateButton { [weak self] button in
            self?.cyclePlaybackRate()
        }
        buttons.append(rateButton)

        // 随机播放按钮
        let shuffleButton = CPNowPlayingShuffleButton { [weak self] button in
            self?.toggleShuffle()
        }
        buttons.append(shuffleButton)

        // 重复播放按钮
        let repeatButton = CPNowPlayingRepeatButton { [weak self] button in
            self?.cycleRepeatMode()
        }
        buttons.append(repeatButton)

        // 更新模板的自定义按钮
        template.updateNowPlayingButtons(buttons)
    }
}

Entitlement Requirement

权限要求

CarPlay requires an entitlement in your Xcode project:

Info.plist:

xml

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

Entitlements file:

xml

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

Without the entitlement, CarPlay won't show your app at all.

CarPlay需要在Xcode项目中配置相应权限：

Info.plist：

xml

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

权限文件：

xml

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

如果没有配置该权限，CarPlay将不会显示你的应用。

CarPlay-Specific Gotchas

CarPlay专属常见问题

Issue	Cause	Fix	Time
CarPlay doesn't show app	Missing entitlement	Add `com.apple.developer.carplay-audio`	5 min
Now Playing blank in CarPlay	MPNowPlayingInfoCenter not set	Same fix as Lock Screen (Pattern 1)	10 min
Custom buttons don't appear	Configured after push	Configure at `templateApplicationScene(_:didConnect:)`	5 min
Buttons work on device, not CarPlay simulator	Debugger interference	Test without debugger attached	1 min
Album art missing	Same as iOS issue	Fix MPMediaItemArtwork (Pattern 3)	15 min

问题	原因	解决方法	耗时
CarPlay中不显示应用	缺少权限	添加 `com.apple.developer.carplay-audio` 权限	5分钟
CarPlay中的Now Playing页面空白	MPNowPlayingInfoCenter未配置	与锁屏问题的解决方法相同（模式1）	10分钟
自定义按钮不显示	在推送后才配置	在 `templateApplicationScene(_:didConnect:)` 方法中配置	5分钟
设备上按钮正常，但CarPlay模拟器中无响应	调试器干扰	断开调试器后测试	1分钟
专辑封面缺失	与iOS端问题相同	修复MPMediaItemArtwork（模式3）	15分钟

Testing CarPlay

测试CarPlay

Simulator (Xcode 12+):

I/O → External Displays → CarPlay
Tap CarPlay display
Find your app in Audio section
Important: Run without debugger for reliable testing (debugger can interfere with CarPlay audio session activation)

Real Vehicle: Requires entitlement approval from Apple (automatic for apps with

UIBackgroundModes

audio; no manual request needed).

模拟器（Xcode 12+）：

点击I/O → 外部显示器 → CarPlay
点击CarPlay显示器
在音频分类中找到你的应用
重要提示：为保证测试可靠性，请断开调试器运行（调试器可能会干扰CarPlay音频会话激活）

真实车辆： 需要获得Apple的权限批准（对于配置了

UIBackgroundModes

音频权限的应用，该批准会自动通过；无需手动申请）。

Verification

验证清单

Resources

资源

Skills: axiom-now-playing, axiom-now-playing-musickit

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