HarmonyOS开发：车载娱乐——音乐与视频的安全边界

📌 核心要点：车载娱乐的核心不是播放能力，而是音频焦点管理、多源切换、驾驶安全限制三大约束下的平衡——娱乐再好，安全第一。

背景与动机

你开车听歌，导航突然要播报"前方500米右转"，这时候音乐怎么办？

方案A：音乐继续放，导航播报被盖住——你错过了路口。
方案B：音乐直接停了，导航播报完音乐也不恢复——你还得手动点播放。
方案C：音乐音量降低，导航播报完成后音乐恢复——这才是正确做法。

C方案就是音频焦点管理。它不是"谁先来谁占着"，而是根据音频类型和优先级动态分配——导航播报比音乐优先，电话比导航优先，紧急告警比一切都优先。

还有更复杂的场景：你连着蓝牙听手机上的歌，突然想听U盘里的歌，怎么切换？切换后播放进度要不要保留？手机上的歌下次连上蓝牙能不能接着听？

以及最敏感的问题：行车中能不能看视频？技术上当然能，但法规不允许。你的应用如果在行车中播放视频，审核直接打回。

这篇文章讲的就是这些"播放之外"的问题。

核心原理

音频焦点管理

音频焦点是车载娱乐的核心机制。车机上同时可能有多个音频源在"说话"——音乐、导航、电话、告警。如果不做焦点管理，所有声音混在一起，驾驶员什么都听不清。

graph TD
    A[音频焦点管理器] --> B{焦点请求}
    
    B -->|紧急告警| C[永久夺取焦点]
    B -->|电话来电| D[暂时夺取焦点]
    B -->|导航播报| E[短暂降低其他音量 DUCK]
    B -->|音乐播放| F[请求焦点，可能被拒]
    
    C --> C1[其他音频全部静音]
    C --> C2[告警结束后不自动恢复]
    
    D --> D1[音乐暂停]
    D --> D2[导航静音]
    D --> D3[电话结束后恢复]
    
    E --> E1[音乐音量降低50%]
    E --> E2[播报完成后音量恢复]
    
    F --> F1{当前焦点被谁占着?}
    F1 -->|空闲| F2[获得焦点，开始播放]
    F1 -->|电话| F3[等待，电话结束后播放]
    F1 -->|导航| F4[获得焦点但可能被DUCK]

    classDef manager fill:#E91E63,stroke:#880E4F,color:#fff
    classDef request fill:#FF9800,stroke:#E65100,color:#fff
    classDef action fill:#2196F3,stroke:#1565C0,color:#fff
    classDef result fill:#4CAF50,stroke:#2E7D32,color:#fff

    class A,B manager
    class C,D,E,F request
    class C1,C2,D1,D2,D3,E1,E2 action
    class F1,F2,F3,F4 result

音频焦点类型

HarmonyOS定义了四种音频焦点类型：

驾驶安全限制

行车中的视频播放是红线。各国法规不同，但基本共识是：车辆移动中，驾驶员可见的屏幕不得播放视频内容。

HarmonyOS的驾驶安全限制：

• 车速>5km/h时，禁止播放视频（音频不受限）
• 车速>5km/h时，禁止显示复杂动画和滚动文字
• 车速>5km/h时，禁止文字输入（只能语音或预设选项）
• 副驾屏幕不受限制（如果车机有双屏）

代码实战

基础用法：音乐播放与音频焦点

先实现最基础的功能——带音频焦点管理的音乐播放器。

// CarMediaPlayer.ets - 带音频焦点的媒体播放器
import { media } from '@kit.MediaKit';
import { audio } from '@kit.AudioKit';

// 播放状态
export enum PlayState {
  IDLE = 'idle',
  PLAYING = 'playing',
  PAUSED = 'paused',
  STOPPED = 'stopped',
}

// 媒体源类型
export enum MediaSourceType {
  BLUETOOTH = 'bluetooth',
  USB = 'usb',
  LOCAL = 'local',
  ONLINE = 'online',
}

// 媒体曲目信息
export interface TrackInfo {
  id: string;
  title: string;
  artist: string;
  album: string;
  duration: number;     // 时长 毫秒
  sourceType: MediaSourceType;
  sourcePath: string;
}

export class CarMediaPlayer {
  private avPlayer: media.AVPlayer | null = null;
  private audioManager: audio.AudioManager | null = null;
  private audioSessionId: number = -1;
  private playState: PlayState = PlayState.IDLE;
  private currentTrack: TrackInfo | null = null;
  private playlist: TrackInfo[] = [];
  private currentIndex: number = 0;
  private wasPausedByFocusLoss: boolean = false;

  // 回调
  private onPlayStateChange?: (state: PlayState) => void;
  private onTrackChange?: (track: TrackInfo) => void;

  // 初始化
  async init(): Promise<void> {
    // 创建音频管理器
    this.audioManager = audio.getAudioManager();

    // 创建播放器
    this.avPlayer = await media.createAVPlayer();

    // 设置播放器状态回调
    this.avPlayer.on('stateChange', (state: string) => {
      switch (state) {
        case 'prepared':
          console.info('[Media] 播放器准备就绪');
          break;
        case 'playing':
          this.playState = PlayState.PLAYING;
          this.onPlayStateChange?.(PlayState.PLAYING);
          break;
        case 'paused':
          this.playState = PlayState.PAUSED;
          this.onPlayStateChange?.(PlayState.PAUSED);
          break;
        case 'stopped':
          this.playState = PlayState.STOPPED;
          this.onPlayStateChange?.(PlayState.STOPPED);
          break;
      }
    });

    // 播放完成回调
    this.avPlayer.on('endOfStream', () => {
      this.playNext();
    });

    // 请求音频焦点
    await this.requestAudioFocus();

    console.info('[Media] 播放器初始化完成');
  }

  // 请求音频焦点
  async requestAudioFocus(): Promise<boolean> {
    if (!this.audioManager) return false;

    try {
      const result = await this.audioManager.requestAudioFocus({
        streamUsage: audio.StreamUsage.STREAM_USAGE_MUSIC,
        contentType: audio.ContentType.CONTENT_TYPE_MUSIC,
        pauseWhenDucked: false, // 被DUCK时不暂停，只降低音量
      });

      this.audioSessionId = result;

      // 监听焦点变化
      this.audioManager.on('audioFocusChange', this.audioSessionId, (focusChange: audio.AudioFocusChangeInfo) => {
        this.handleFocusChange(focusChange);
      });

      return true;
    } catch (err) {
      console.error(`[Media] 请求音频焦点失败: ${(err as Error).message}`);
      return false;
    }
  }

  // 处理音频焦点变化
  private handleFocusChange(focusChange: audio.AudioFocusChangeInfo): void {
    switch (focusChange.focusType) {
      case audio.InterruptFocusType.INTERRUPT_FOCUS_TRANSIENT:
        // 临时失去焦点（导航播报）→ 暂停
        if (this.playState === PlayState.PLAYING) {
          this.wasPausedByFocusLoss = true;
          this.pause();
          console.info('[Media] 临时失去焦点，暂停播放');
        }
        break;

      case audio.InterruptFocusType.INTERRUPT_FOCUS_TRANSIENT_DUCK:
        // 被DUCK（导航提示音）→ 降低音量，不暂停
        if (this.avPlayer) {
          this.avPlayer.setVolume(0.3); // 降低到30%
          console.info('[Media] 被DUCK，降低音量');
          // 导航播报完成后恢复
          setTimeout(() => {
            this.avPlayer?.setVolume(1.0);
            console.info('[Media] DUCK结束，恢复音量');
          }, 5000);
        }
        break;

      case audio.InterruptFocusType.INTERRUPT_FOCUS_RELEASE:
        // 焦点恢复
        if (this.wasPausedByFocusLoss) {
          this.play();
          this.wasPausedByFocusLoss = false;
          console.info('[Media] 焦点恢复，继续播放');
        }
        break;

      case audio.InterruptFocusType.INTERRUPT_FOCUS_PERMANENT:
        // 永久失去焦点（电话）→ 暂停
        if (this.playState === PlayState.PLAYING) {
          this.wasPausedByFocusLoss = true;
          this.pause();
          console.info('[Media] 永久失去焦点，暂停播放');
        }
        break;
    }
  }

  // 播放指定曲目
  async playTrack(track: TrackInfo): Promise<void> {
    if (!this.avPlayer) return;

    this.currentTrack = track;

    // 根据源类型设置播放地址
    if (track.sourceType === MediaSourceType.LOCAL || track.sourceType === MediaSourceType.USB) {
      this.avPlayer.url = track.sourcePath;
    } else {
      this.avPlayer.url = track.sourcePath;
    }

    await this.avPlayer.prepare();
    await this.avPlayer.play();
    this.onTrackChange?.(track);
    console.info(`[Media] 正在播放: ${track.title} - ${track.artist}`);
  }

  // 播放
  async play(): Promise<void> {
    if (!this.avPlayer) return;
    await this.avPlayer.play();
  }

  // 暂停
  async pause(): Promise<void> {
    if (!this.avPlayer) return;
    await this.avPlayer.pause();
  }

  // 下一首
  async playNext(): Promise<void> {
    if (this.playlist.length === 0) return;
    this.currentIndex = (this.currentIndex + 1) % this.playlist.length;
    await this.playTrack(this.playlist[this.currentIndex]);
  }

  // 上一首
  async playPrev(): Promise<void> {
    if (this.playlist.length === 0) return;
    this.currentIndex = (this.currentIndex - 1 + this.playlist.length) % this.playlist.length;
    await this.playTrack(this.playlist[this.currentIndex]);
  }

  // 切换媒体源
  async switchSource(sourceType: MediaSourceType): Promise<void> {
    // 保存当前播放状态
    const wasPlaying = this.playState === PlayState.PLAYING;
    const prevTrack = this.currentTrack;

    // 停止当前播放
    if (this.avPlayer) {
      await this.avPlayer.stop();
    }

    // 根据源类型加载新播放列表
    switch (sourceType) {
      case MediaSourceType.BLUETOOTH:
        this.playlist = await this.loadBluetoothPlaylist();
        break;
      case MediaSourceType.USB:
        this.playlist = await this.loadUSBPlaylist();
        break;
      case MediaSourceType.LOCAL:
        this.playlist = await this.loadLocalPlaylist();
        break;
    }

    console.info(`[Media] 切换到${sourceType}源，${this.playlist.length}首曲目`);

    // 如果之前在播放，自动开始播放新源的第一首
    if (wasPlaying && this.playlist.length > 0) {
      this.currentIndex = 0;
      await this.playTrack(this.playlist[0]);
    }

    // 保存上一首歌的信息，方便切回时恢复
    if (prevTrack) {
      this.saveLastPlayedTrack(prevTrack);
    }
  }

  // 简化的播放列表加载
  private async loadBluetoothPlaylist(): Promise<TrackInfo[]> {
    // 实际应通过蓝牙协议获取手机端的播放列表
    return [];
  }

  private async loadUSBPlaylist(): Promise<TrackInfo[]> {
    // 实际应扫描USB存储中的音频文件
    return [];
  }

  private async loadLocalPlaylist(): Promise<TrackInfo[]> {
    // 加载本地存储的音频文件
    return [];
  }

  // 保存上次播放的曲目
  private saveLastPlayedTrack(track: TrackInfo): void {
    AppStorage.setOrCreate('lastPlayedTrack', JSON.stringify(track));
  }

  // 销毁
  async destroy(): Promise<void> {
    if (this.avPlayer) {
      await this.avPlayer.release();
    }
    if (this.audioManager && this.audioSessionId !== -1) {
      this.audioManager.abandonAudioFocus(this.audioSessionId);
    }
  }
}

进阶用法：驾驶安全限制与视频播放控制

视频播放必须遵守驾驶安全限制。车速超过阈值时，视频必须自动暂停，只保留音频。

// SafeVideoPlayer.ets - 驾驶安全视频播放器
import { media } from '@kit.MediaKit';
import { car } from '@kit.CarKit';

export class SafeVideoPlayer {
  private avPlayer: media.AVPlayer | null = null;
  private vehicleManager: car.VehicleManager | null = null;
  private isVideoAllowed: boolean = true; // 当前是否允许播放视频
  private speedThreshold: number = 5; // 5km/h以上禁止视频
  private videoPausePosition: number = 0; // 视频暂停位置

  // 回调
  private onVideoBlocked?: (reason: string) => void;
  private onVideoResumed?: () => void;

  async init(vehicleManager: car.VehicleManager): Promise<void> {
    this.vehicleManager = vehicleManager;

    // 订阅车速变化
    this.vehicleManager.subscribeProperty(
      car.VehiclePropertyId.PERF_VEHICLE_SPEED,
      car.SubscribeOption.CONTINUOUS,
      1000,
      (_: number, speed: number) => {
        this.onSpeedChange(speed);
      }
    );
  }

  // 车速变化处理
  private onSpeedChange(speed: number): void {
    const shouldBlockVideo = speed > this.speedThreshold;

    if (shouldBlockVideo && this.isVideoAllowed) {
      // 车速超过阈值，禁止视频
      this.isVideoAllowed = false;
      this.blockVideo();
    } else if (!shouldBlockVideo && !this.isVideoAllowed) {
      // 车速低于阈值，恢复视频
      this.isVideoAllowed = true;
      this.resumeVideo();
    }
  }

  // 禁止视频播放
  private async blockVideo(): Promise<void> {
    if (!this.avPlayer) return;

    // 保存当前播放位置
    this.videoPausePosition = await this.avPlayer.currentTime;

    // 切换到纯音频模式
    // 方案1：隐藏视频画面，只保留音频
    this.onVideoBlocked?.('行车中禁止观看视频，已切换为音频模式');

    // 方案2：完全暂停
    await this.avPlayer.pause();

    console.info('[SafeVideo] 车速超过阈值，视频已暂停');
  }

  // 恢复视频播放
  private async resumeVideo(): Promise<void> {
    if (!this.avPlayer) return;

    // 恢复到暂停位置
    await this.avPlayer.seek(this.videoPausePosition);
    await this.avPlayer.play();

    this.onVideoResumed?.();
    console.info('[SafeVideo] 车速低于阈值，视频已恢复');
  }

  // 播放视频（带安全检查）
  async playVideo(url: string): Promise<boolean> {
    if (!this.isVideoAllowed) {
      this.onVideoBlocked?.('行车中禁止播放视频');
      return false;
    }

    this.avPlayer = await media.createAVPlayer();
    this.avPlayer.url = url;
    await this.avPlayer.prepare();
    await this.avPlayer.play();
    return true;
  }

  // 设置回调
  setCallbacks(
    onVideoBlocked: (reason: string) => void,
    onVideoResumed: () => void
  ): void {
    this.onVideoBlocked = onVideoBlocked;
    this.onVideoResumed = onVideoResumed;
  }
}

完整示例：车载媒体播放器页面

把音乐播放、音频焦点、媒体源切换、视频安全限制整合到一个完整的页面里。

// CarEntertainmentPage.ets - 车载媒体播放器完整页面
@Entry
@Component
struct CarEntertainmentPage {
  @State playState: string = 'stopped';
  @State trackTitle: string = '未播放';
  @State trackArtist: string = '--';
  @State currentSource: string = '本地';
  @State progress: number = 0;
  @State duration: number = 0;
  @State isVideoBlocked: boolean = false;
  @State videoBlockReason: string = '';
  @State playlist: TrackInfo[] = [];

  build() {
    Column({ space: 16 }) {
      // 标题与媒体源
      Row() {
        Text('车载媒体')
          .fontSize(24)
          .fontWeight(FontWeight.Bold)
          .fontColor(Color.White)
        Row({ space: 8 }) {
          ForEach(['本地', '蓝牙', 'USB'], (source: string) => {
            Text(source)
              .fontSize(13)
              .fontColor(this.currentSource === source ? '#4FC3F7' : '#888888')
              .padding({ left: 12, right: 12, top: 6, bottom: 6 })
              .backgroundColor(this.currentSource === source ? '#1A3A5C' : '#1A1A2E')
              .borderRadius(16)
              .onClick(() => { this.currentSource = source; })
          })
        }
        .margin({ left: 20 })
      }
      .width('100%')
      .padding({ left: 30, top: 20 })

      // 视频禁止提示
      if (this.isVideoBlocked) {
        Row({ space: 8 }) {
          Text('⚠️')
            .fontSize(18)
          Text(this.videoBlockReason)
            .fontSize(14)
            .fontColor('#FF9800')
            .layoutWeight(1)
        }
        .width('100%')
        .padding({ left: 20, right: 20, top: 12, bottom: 12 })
        .margin({ left: 30, right: 30 })
        .backgroundColor('#3E2723')
        .borderRadius(8)
      }

      // 专辑封面区域
      Column({ space: 12 }) {
        // 模拟专辑封面
        Column() {
          Text('🎵')
            .fontSize(64)
        }
        .width(200)
        .height(200)
        .backgroundColor('#1A1A2E')
        .borderRadius(20)
        .justifyContent(FlexAlign.Center)

        // 曲目信息
        Text(this.trackTitle)
          .fontSize(22)
          .fontWeight(FontWeight.Medium)
          .fontColor(Color.White)
        Text(this.trackArtist)
          .fontSize(16)
          .fontColor('#888888')
      }
      .padding({ top: 20 })

      // 进度条
      Column({ space: 8 }) {
        Progress({ value: this.progress, total: this.duration > 0 ? this.duration : 1 })
          .width('80%')
          .color('#4FC3F7')
          .backgroundColor('#333333')
          .style(ProgressStyle.Linear)
        Row() {
          Text(this.formatTime(this.progress))
            .fontSize(12)
            .fontColor('#888888')
          Text(this.formatTime(this.duration))
            .fontSize(12)
            .fontColor('#888888')
        }
        .width('80%')
        .justifyContent(FlexAlign.SpaceBetween)
      }

      // 播放控制
      Row({ space: 24 }) {
        Button('⏮')
          .width(56)
          .height(56)
          .fontSize(24)
          .backgroundColor('#2A2A3E')
          .fontColor(Color.White)
          .borderRadius(28)
          .onClick(() => {})

        Button(this.playState === 'playing' ? '⏸' : '▶️')
          .width(72)
          .height(72)
          .fontSize(32)
          .backgroundColor(this.playState === 'playing' ? '#FF9800' : '#4CAF50')
          .fontColor(Color.White)
          .borderRadius(36)
          .onClick(() => {
            this.playState = this.playState === 'playing' ? 'paused' : 'playing';
          })

        Button('⏭')
          .width(56)
          .height(56)
          .fontSize(24)
          .backgroundColor('#2A2A3E')
          .fontColor(Color.White)
          .borderRadius(28)
          .onClick(() => {})
      }
      .padding({ top: 16 })

      // 播放列表
      Column({ space: 8 }) {
        Text('播放列表')
          .fontSize(16)
          .fontWeight(FontWeight.Medium)
          .fontColor(Color.White)
          .padding({ left: 30 })
          .alignSelf(ItemAlign.Start)

        List({ space: 8 }) {
          ForEach([
            { title: '晴天', artist: '周杰伦' },
            { title: '稻香', artist: '周杰伦' },
            { title: '平凡之路', artist: '朴树' },
            { title: '光辉岁月', artist: 'Beyond' },
          ], (item: { title: string, artist: string }, index: number) => {
            ListItem() {
              Row({ space: 12 }) {
                Text(`${index + 1}`)
                  .fontSize(14)
                  .fontColor('#888888')
                  .width(30)
                Column({ space: 2 }) {
                  Text(item.title)
                    .fontSize(15)
                    .fontColor(Color.White)
                  Text(item.artist)
                    .fontSize(12)
                    .fontColor('#888888')
                }
                .layoutWeight(1)
                .alignItems(HorizontalAlign.Start)
                Text('▶️')
                  .fontSize(16)
              }
              .width('100%')
              .padding(12)
              .backgroundColor('#161B22')
              .borderRadius(8)
              .onClick(() => {
                this.trackTitle = item.title;
                this.trackArtist = item.artist;
                this.playState = 'playing';
              })
            }
          })
        }
        .padding({ left: 30, right: 30 })
        .height(200)
      }
      .layoutWeight(1)
    }
    .width('100%')
    .height('100%')
    .backgroundColor('#0D1117')
  }

  // 格式化时间
  private formatTime(ms: number): string {
    const seconds = Math.floor(ms / 1000);
    const mins = Math.floor(seconds / 60);
    const secs = seconds % 60;
    return `${mins}:${secs.toString().padStart(2, '0')}`;
  }
}

踩坑与注意事项

坑1：音频焦点丢失后不恢复

这是最常见的bug：导航播报完，音乐不恢复了。原因是你只处理了"失去焦点"，没处理"焦点恢复"。

解决方案：

• 在handleFocusChange中，INTERRUPT_FOCUS_RELEASE事件必须恢复播放
• 用wasPausedByFocusLoss标记区分"用户主动暂停"和"焦点丢失暂停"
• 只有焦点丢失导致的暂停才自动恢复，用户主动暂停的不要自动恢复

坑2：蓝牙切换延迟

从蓝牙源切换到USB源，蓝牙连接不断开，但音频流已经切走了。如果用户切回蓝牙，手机端的播放器可能已经自动暂停了。

解决方案：

• 切换源时，通过AVRCP协议通知手机端暂停
• 切回蓝牙时，通过AVRCP协议通知手机端恢复
• 保存每个源的播放状态，切换时恢复

坑3：USB热插拔

用户正在听U盘里的歌，突然拔掉U盘——播放器直接崩溃，因为文件路径无效了。

解决方案：

• 监听USB设备的插拔事件
• U盘拔出时，立即停止播放，清空播放列表
• 提示用户"USB设备已移除"

坑4：视频安全限制的边界情况

车速刚好在5km/h上下波动（比如堵车走走停停），视频会频繁暂停/恢复，体验极差。

解决方案：

• 加一个滞后窗口：从禁止到允许需要持续低速5秒以上
• 从允许到禁止立即生效（安全优先）
• 提供用户手动选择：暂停视频后不自动恢复，等用户确认

坑5：多应用音频冲突

你的音乐应用和第三方的音乐应用同时运行，两个都在抢音频焦点。结果就是：你播你的，它播它的，混在一起。

解决方案：

• 同一时刻只允许一个音乐应用持有焦点
• 新应用请求焦点时，旧应用自动失去焦点
• 系统级的音频焦点管理器负责仲裁，应用只需要遵守规则

HarmonyOS 6适配说明

HarmonyOS 6在车载娱乐方面做了几项更新：

1. 空间音频：新增车载空间音频支持，利用车内多个扬声器实现3D音效。导航播报从左前方传来（模拟路口方向），音乐环绕整个车厢。

2. 多区音频：支持车内不同区域播放不同内容——驾驶员听导航，后排听音乐。每个区域独立音量控制。

3. 视频安全增强：新增驾驶员视线检测——即使车停着，如果驾驶员视线不在屏幕上，视频也不播放。通过车内摄像头实现。

4. 媒体源自动切换：新增智能源切换——上车自动连接手机蓝牙，插U盘自动识别，拔U盘自动切回蓝牙。不需要用户手动选择。

适配代码：

// HarmonyOS 6 多区音频
import { audio } from '@kit.AudioKit';

async function setupMultiZoneAudio(): Promise<void> {
  const audioManager = audio.getAudioManager();
  
  // 驾驶区音频
  const driverZone = await audioManager.createAudioRenderer({
    streamUsage: audio.StreamUsage.STREAM_USAGE_MUSIC,
    contentType: audio.ContentType.CONTENT_TYPE_MUSIC,
    zoneId: audio.AudioZone.DRIVER, // 驾驶区
  });

  // 后排音频
  const rearZone = await audioManager.createAudioRenderer({
    streamUsage: audio.StreamUsage.STREAM_USAGE_MUSIC,
    contentType: audio.ContentType.CONTENT_TYPE_MUSIC,
    zoneId: audio.AudioZone.REAR, // 后排区
  });

  // 驾驶区播放导航音频
  // 后排播放音乐
  console.info('[Media] 多区音频已配置');
}

总结

车载娱乐的难点不在播放——AVPlayer几行代码就能播放音乐视频。真正的难点在音频焦点管理、多源切换、驾驶安全限制这些"播放之外"的问题。处理不好，要么导航播报被音乐盖住错过路口，要么行车中视频还在播放违反法规。娱乐再好，安全第一。

一句话：车载娱乐做得好不好，不是看音质多棒画面多清晰，而是看导航播报时音乐能不能优雅地让路，行车中视频能不能可靠地暂停。