一文走进HarmonyOS开发中的分布式音频

小知识

你有没有遇到过这种场景：在手机上听音乐，突然想用客厅的音箱播放；或者在平板上看电影，想用电视的音响系统获得更好的音效；又或者在车上用手机导航，想让语音播报通过车载音响输出。

这就是分布式音频要解决的问题——让音频流可以跨设备流动，在最适合的设备上播放。

传统方案下，音频输出是绑死在设备上的。手机播放的声音只能从手机扬声器出来，想切换到其他设备，只能通过蓝牙配对、DLNA投屏等方式，操作繁琐且体验割裂。

HarmonyOS的分布式音频能力，让音频输出变得像"水流"一样自然——你可以让音频在多个设备间无缝切换，或者同时在多个设备上播放。更重要的是，这一切对应用开发者是透明的，你只需要调用标准的音频API，系统会自动处理跨设备的路由和同步。

核心原理

分布式音频架构

分布式音频基于以下几个核心概念：

1. AudioProvider：音频提供者，声明本设备的音频输出能力
2. AudioRouter：音频路由器，决定音频流应该输出到哪个设备
3. AudioStream：音频流，承载实际的音频数据
4. AudioSync：音频同步器，确保多设备播放同步
   

音频路由策略

分布式音频支持多种路由策略：

1. 自动路由：系统根据设备能力和场景自动选择最佳输出设备
2. 手动路由：用户明确指定输出设备
3. 多设备路由：同时在多个设备上输出
4. 群组路由：输出到设备群组（如"全屋音响"）

音频同步机制

多设备播放时，同步是关键挑战：

// 音频同步参数
interface AudioSyncParams {
    // 同步模式
    mode: 'ntp' | 'ptp' | 'audio_clock';
    
    // 同步精度要求（毫秒）
    precision: number;
    
    // 缓冲策略
    bufferStrategy: 'fixed' | 'adaptive';
    
    // 延迟补偿
    latencyCompensation: boolean;
}

代码实战

示例一：基础分布式音频播放

这是最基础的分布式音频播放示例，支持将音频路由到指定设备。

// DistributedAudio.ets
import audio from '@ohos.multimedia.audio';
import deviceManager from '@ohos.distributedDeviceManager';
import distributedAudio from '@ohos.distributedAudio';

export class DistributedAudio {
    private context: common.UIAbilityContext;
    private deviceManager: deviceManager.DeviceManager | null = null;
    
    // 音频播放器
    private audioPlayer: audio.AVPlayer | null = null;
    
    // 分布式音频路由器
    private audioRouter: distributedAudio.AudioRouter | null = null;
    
    // 当前音频流
    private audioStream: distributedAudio.AudioStream | null = null;
    
    // 播放状态
    private playState: PlayState = {
        isPlaying: false,
        currentTime: 0,
        duration: 0,
        volume: 0.5,
        currentDevice: 'local'
    };

    constructor(context: common.UIAbilityContext) {
        this.context = context;
    }

    // 初始化
    async initialize(): Promise<void> {
        console.info('[DistributedAudio] Initializing...');
        
        try {
            // 初始化设备管理器
            this.deviceManager = deviceManager.createDeviceManager(
                this.context.applicationInfo.name
            );
            
            // 初始化音频路由器
            this.audioRouter = distributedAudio.createAudioRouter();
            
            // 监听设备变化
            this.setupDeviceListener();
            
            console.info('[DistributedAudio] Initialized');
        } catch (error) {
            console.error('[DistributedAudio] Init failed:', error);
            throw error;
        }
    }

    // 设置设备监听
    private setupDeviceListener(): void {
        if (!this.deviceManager) return;
        
        this.deviceManager.on('deviceStateChange', (data: deviceManager.DeviceInfo) => {
            console.info('[DistributedAudio] Device state changed:', data.deviceName);
            
            // 刷新可用音频设备列表
            this.refreshAudioDevices();
        });
    }

    // 获取可用的音频输出设备
    async getAvailableAudioDevices(): Promise<AudioDeviceInfo[]> {
        console.info('[DistributedAudio] Getting available audio devices');
        
        const devices: AudioDeviceInfo[] = [];
        
        // 添加本地设备
        devices.push({
            deviceId: 'local',
            deviceName: '本机扬声器',
            deviceType: 'speaker',
            isOnline: true,
            capabilities: {
                supportsPlayback: true,
                supportsVolumeControl: true,
                maxVolume: 100,
                supportsLowLatency: true
            }
        });
        
        // 获取远程设备
        if (this.deviceManager) {
            const remoteDevices = this.deviceManager.getTrustedDeviceListSync();
            
            for (const device of remoteDevices) {
                if (device.deviceState !== deviceManager.DeviceState.ONLINE) {
                    continue;
                }
                
                // 查询设备的音频能力
                try {
                    const audioCap = await this.queryDeviceAudioCapability(device.deviceId);
                    
                    if (audioCap.supportsPlayback) {
                        devices.push({
                            deviceId: device.deviceId,
                            deviceName: device.deviceName,
                            deviceType: this.mapDeviceType(device.deviceType),
                            isOnline: true,
                            capabilities: audioCap
                        });
                    }
                } catch (error) {
                    console.error('[DistributedAudio] Query capability failed:', error);
                }
            }
        }
        
        console.info('[DistributedAudio] Found', devices.length, 'audio devices');
        return devices;
    }

    // 创建音频播放器并准备播放
    async prepareAudioSource(source: AudioSource): Promise<void> {
        console.info('[DistributedAudio] Preparing audio source:', source.url);
        
        try {
            // 创建音频播放器
            this.audioPlayer = await audio.createAVPlayer();
            
            // 设置播放源
            if (source.type === 'file') {
                const fd = await this.openFile(source.url);
                this.audioPlayer.fdSrc = fd;
            } else if (source.type === 'network') {
                this.audioPlayer.url = source.url;
            }
            
            // 设置状态监听
            this.setupPlayerListeners();
            
            // 准备播放
            await this.audioPlayer.prepare();
            
            // 获取时长
            this.playState.duration = this.audioPlayer.duration;
            
            console.info('[DistributedAudio] Audio prepared, duration:', this.playState.duration);
        } catch (error) {
            console.error('[DistributedAudio] Prepare failed:', error);
            throw error;
        }
    }

    // 设置播放器监听
    private setupPlayerListeners(): void {
        if (!this.audioPlayer) return;
        
        // 状态变化
        this.audioPlayer.on('stateChange', (state: string) => {
            console.info('[DistributedAudio] Player state:', state);
            
            switch (state) {
                case 'playing':
                    this.playState.isPlaying = true;
                    break;
                case 'paused':
                case 'stopped':
                    this.playState.isPlaying = false;
                    break;
            }
        });
        
        // 播放进度
        this.audioPlayer.on('timeUpdate', (time: number) => {
            this.playState.currentTime = time;
        });
        
        // 播放完成
        this.audioPlayer.on('finish', () => {
            console.info('[DistributedAudio] Playback finished');
            this.playState.isPlaying = false;
            this.playState.currentTime = 0;
        });
        
        // 错误
        this.audioPlayer.on('error', (error: BusinessError) => {
            console.error('[DistributedAudio] Player error:', error);
        });
    }

    // 切换音频输出设备
    async switchOutputDevice(deviceId: string): Promise<boolean> {
        console.info('[DistributedAudio] Switching to device:', deviceId);
        
        try {
            if (deviceId === 'local') {
                // 切换到本地播放
                await this.audioRouter?.routeToLocal();
                this.playState.currentDevice = 'local';
            } else {
                // 切换到远程设备
                await this.audioRouter?.routeToDevice(deviceId);
                this.playState.currentDevice = deviceId;
            }
            
            console.info('[DistributedAudio] Device switched successfully');
            return true;
        } catch (error) {
            console.error('[DistributedAudio] Switch failed:', error);
            return false;
        }
    }

    // 开始播放
    async play(): Promise<void> {
        console.info('[DistributedAudio] Starting playback');
        
        if (!this.audioPlayer) {
            console.error('[DistributedAudio] No audio player');
            return;
        }
        
        try {
            await this.audioPlayer.play();
            console.info('[DistributedAudio] Playback started');
        } catch (error) {
            console.error('[DistributedAudio] Play failed:', error);
        }
    }

    // 暂停播放
    async pause(): Promise<void> {
        if (!this.audioPlayer) return;
        
        try {
            await this.audioPlayer.pause();
            console.info('[DistributedAudio] Playback paused');
        } catch (error) {
            console.error('[DistributedAudio] Pause failed:', error);
        }
    }

    // 停止播放
    async stop(): Promise<void> {
        if (!this.audioPlayer) return;
        
        try {
            await this.audioPlayer.stop();
            this.playState.currentTime = 0;
            console.info('[DistributedAudio] Playback stopped');
        } catch (error) {
            console.error('[DistributedAudio] Stop failed:', error);
        }
    }

    // 跳转到指定位置
    async seekTo(time: number): Promise<void> {
        if (!this.audioPlayer) return;
        
        try {
            await this.audioPlayer.seek(time);
            console.info('[DistributedAudio] Seeked to:', time);
        } catch (error) {
            console.error('[DistributedAudio] Seek failed:', error);
        }
    }

    // 设置音量
    async setVolume(volume: number): Promise<void> {
        if (!this.audioPlayer) return;
        
        try {
            // 音量范围 0-1
            const normalizedVolume = Math.max(0, Math.min(1, volume));
            await this.audioPlayer.setVolume(normalizedVolume);
            
            this.playState.volume = normalizedVolume;
            console.info('[DistributedAudio] Volume set to:', normalizedVolume);
        } catch (error) {
            console.error('[DistributedAudio] Set volume failed:', error);
        }
    }

    // 获取播放状态
    getPlayState(): PlayState {
        return { ...this.playState };
    }

    // 查询设备音频能力
    private async queryDeviceAudioCapability(deviceId: string): Promise<AudioCapability> {
        // 实际实现需要查询远程设备
        return {
            supportsPlayback: true,
            supportsVolumeControl: true,
            maxVolume: 100,
            supportsLowLatency: false
        };
    }

    // 设备类型映射
    private mapDeviceType(type: number): string {
        const types = ['unknown', 'phone', 'tablet', 'tv', 'watch', 'car'];
        return types[type] || 'unknown';
    }

    // 打开文件
    private async openFile(path: string): Promise<number> {
        // 实际实现
        return 0;
    }

    // 刷新音频设备
    private refreshAudioDevices(): void {
        // 通知UI刷新
        this.getAvailableAudioDevices().then(devices => {
            AppStorage.setOrCreate('audioDevices', devices);
        });
    }

    // 释放资源
    async release(): Promise<void> {
        console.info('[DistributedAudio] Releasing');
        
        // 停止播放
        if (this.playState.isPlaying) {
            await this.stop();
        }
        
        // 释放播放器
        if (this.audioPlayer) {
            await this.audioPlayer.release();
            this.audioPlayer = null;
        }
        
        // 释放路由器
        if (this.audioRouter) {
            distributedAudio.releaseAudioRouter(this.audioRouter);
            this.audioRouter = null;
        }
        
        // 释放设备管理器
        if (this.deviceManager) {
            deviceManager.releaseDeviceManager(this.deviceManager);
            this.deviceManager = null;
        }
        
        console.info('[DistributedAudio] Released');
    }
}

// 接口定义
interface PlayState {
    isPlaying: boolean;
    currentTime: number;
    duration: number;
    volume: number;
    currentDevice: string;
}

interface AudioDeviceInfo {
    deviceId: string;
    deviceName: string;
    deviceType: string;
    isOnline: boolean;
    capabilities: AudioCapability;
}

interface AudioCapability {
    supportsPlayback: boolean;
    supportsVolumeControl: boolean;
    maxVolume: number;
    supportsLowLatency: boolean;
}

interface AudioSource {
    type: 'file' | 'network';
    url: string;
}

interface BusinessError {
    code: number;
    message: string;
}

示例二：多设备音频同步播放

支持在多个设备上同步播放音频，实现"全屋音响"效果。

// MultiDeviceAudioSync.ets
import distributedAudio from '@ohos.distributedAudio';

export class MultiDeviceAudioSync {
    // 音频流管理器
    private streamManager: distributedAudio.StreamManager | null = null;
    
    // 多设备播放会话
    private multiPlaySession: distributedAudio.MultiPlaySession | null = null;
    
    // 同步控制器
    private syncController: AudioSyncController | null = null;
    
    // 活跃的输出设备
    private activeDevices: Set<string> = new Set();

    // 初始化多设备同步播放
    async initializeMultiPlay(): Promise<void> {
        console.info('[MultiAudio] Initializing multi-device playback');
        
        try {
            // 创建流管理器
            this.streamManager = distributedAudio.createStreamManager();
            
            // 创建同步控制器
            this.syncController = new AudioSyncController();
            
            console.info('[MultiAudio] Initialized');
        } catch (error) {
            console.error('[MultiAudio] Init failed:', error);
        }
    }

    // 添加输出设备
    async addOutputDevice(deviceId: string): Promise<boolean> {
        console.info('[MultiAudio] Adding device:', deviceId);
        
        if (this.activeDevices.has(deviceId)) {
            console.warn('[MultiAudio] Device already active');
            return false;
        }
        
        try {
            // 创建设备音频流
            const audioStream = await this.streamManager?.createStream({
                deviceId: deviceId,
                format: 'pcm',
                sampleRate: 48000,
                channels: 2,
                encoding: 'pcm_16bit'
            });
            
            // 注册到同步控制器
            this.syncController?.registerStream(deviceId, audioStream!);
            
            this.activeDevices.add(deviceId);
            
            console.info('[MultiAudio] Device added');
            return true;
        } catch (error) {
            console.error('[MultiAudio] Add device failed:', error);
            return false;
        }
    }

    // 移除输出设备
    async removeOutputDevice(deviceId: string): Promise<void> {
        console.info('[MultiAudio] Removing device:', deviceId);
        
        if (!this.activeDevices.has(deviceId)) {
            return;
        }
        
        // 从同步控制器注销
        this.syncController?.unregisterStream(deviceId);
        
        // 释放音频流
        await this.streamManager?.releaseStream(deviceId);
        
        this.activeDevices.delete(deviceId);
    }

    // 开始同步播放
    async startSyncPlay(audioSource: AudioSource): Promise<void> {
        console.info('[MultiAudio] Starting sync playback');
        
        if (this.activeDevices.size === 0) {
            console.error('[MultiAudio] No active devices');
            return;
        }
        
        try {
            // 创建多设备播放会话
            this.multiPlaySession = await distributedAudio.createMultiPlaySession({
                devices: Array.from(this.activeDevices),
                source: audioSource,
                
                // 同步配置
                syncConfig: {
                    mode: 'ptp',  // 精确时间协议
                    precision: 5,  // 5ms同步精度
                    bufferStrategy: 'adaptive',
                    latencyCompensation: true
                }
            });
            
            // 设置同步监听
            this.setupSyncListeners();
            
            // 开始播放
            await this.multiPlaySession.play();
            
            console.info('[MultiAudio] Sync playback started');
        } catch (error) {
            console.error('[MultiAudio] Start sync play failed:', error);
        }
    }

    // 设置同步监听
    private setupSyncListeners(): void {
        if (!this.multiPlaySession) return;
        
        // 监听同步状态
        this.multiPlaySession.on('syncState', (state: SyncState) => {
            console.info('[MultiAudio] Sync state:', state.status);
            
            if (state.status === 'drift_detected') {
                // 检测到漂移，触发重新同步
                this.handleSyncDrift(state);
            }
        });
        
        // 监听设备延迟
        this.multiPlaySession.on('deviceLatency', (info: DeviceLatencyInfo) => {
            console.info('[MultiAudio] Device latency:', info.deviceId, info.latency, 'ms');
            
            // 动态调整缓冲
            this.syncController?.adjustBuffer(info.deviceId, info.latency);
        });
        
        // 监听设备掉线
        this.multiPlaySession.on('deviceDisconnected', (deviceId: string) => {
            console.warn('[MultiAudio] Device disconnected:', deviceId);
            this.activeDevices.delete(deviceId);
        });
    }

    // 处理同步漂移
    private handleSyncDrift(state: SyncState): void {
        console.info('[MultiAudio] Handling sync drift');
        
        // 找出漂移最大的设备
        let maxDriftDevice = '';
        let maxDrift = 0;
        
        for (const [deviceId, drift] of Object.entries(state.drifts)) {
            if (Math.abs(drift) > maxDrift) {
                maxDrift = Math.abs(drift);
                maxDriftDevice = deviceId;
            }
        }
        
        // 调整该设备的播放位置
        this.syncController?.adjustPosition(maxDriftDevice, state.drifts[maxDriftDevice]);
    }

    // 暂停所有设备
    async pauseAll(): Promise<void> {
        if (!this.multiPlaySession) return;
        
        try {
            await this.multiPlaySession.pause();
            console.info('[MultiAudio] All devices paused');
        } catch (error) {
            console.error('[MultiAudio] Pause failed:', error);
        }
    }

    // 恢复所有设备
    async resumeAll(): Promise<void> {
        if (!this.multiPlaySession) return;
        
        try {
            await this.multiPlaySession.resume();
            console.info('[MultiAudio] All devices resumed');
        } catch (error) {
            console.error('[MultiAudio] Resume failed:', error);
        }
    }

    // 停止所有设备
    async stopAll(): Promise<void> {
        if (!this.multiPlaySession) return;
        
        try {
            await this.multiPlaySession.stop();
            console.info('[MultiAudio] All devices stopped');
        } catch (error) {
            console.error('[MultiAudio] Stop failed:', error);
        }
    }

    // 设置单个设备音量
    async setDeviceVolume(deviceId: string, volume: number): Promise<void> {
        if (!this.multiPlaySession) return;
        
        try {
            await this.multiPlaySession.setVolume(deviceId, volume);
            console.info('[MultiAudio] Volume set for', deviceId, ':', volume);
        } catch (error) {
            console.error('[MultiAudio] Set volume failed:', error);
        }
    }

    // 获取同步状态
    getSyncStatus(): SyncStatus {
        return {
            deviceCount: this.activeDevices.size,
            devices: Array.from(this.activeDevices),
            isPlaying: this.multiPlaySession?.isPlaying() || false,
            syncAccuracy: this.syncController?.getAccuracy() || 0
        };
    }
}

// 音频同步控制器
class AudioSyncController {
    private streams: Map<string, distributedAudio.AudioStream> = new Map();
    private bufferSizes: Map<string, number> = new Map();
    private referenceTime: number = 0;
    
    // 同步精度（毫秒）
    private targetAccuracy: number = 5;
    private currentAccuracy: number = 0;

    registerStream(deviceId: string, stream: distributedAudio.AudioStream): void {
        this.streams.set(deviceId, stream);
        this.bufferSizes.set(deviceId, 1024);  // 默认缓冲大小
    }

    unregisterStream(deviceId: string): void {
        this.streams.delete(deviceId);
        this.bufferSizes.delete(deviceId);
    }

    // 调整缓冲大小
    adjustBuffer(deviceId: string, latency: number): void {
        // 根据延迟调整缓冲
        const baseBuffer = 1024;
        const latencyFactor = latency / 50;  // 50ms为基准延迟
        
        const newBufferSize = Math.round(baseBuffer * (1 + latencyFactor));
        this.bufferSizes.set(deviceId, newBufferSize);
        
        // 应用到音频流
        const stream = this.streams.get(deviceId);
        if (stream) {
            stream.setBufferSize(newBufferSize);
        }
    }

    // 调整播放位置
    adjustPosition(deviceId: string, drift: number): void {
        const stream = this.streams.get(deviceId);
        if (stream) {
            // 根据漂移调整播放位置
            const adjustmentMs = -drift;
            stream.adjustPosition(adjustmentMs);
        }
    }

    // 获取当前同步精度
    getAccuracy(): number {
        return this.currentAccuracy;
    }

    // 设置参考时间
    setReferenceTime(time: number): void {
        this.referenceTime = time;
    }
}

// 接口定义
interface SyncState {
    status: 'synced' | 'drift_detected' | 'resyncing';
    drifts: Record<string, number>;
}

interface DeviceLatencyInfo {
    deviceId: string;
    latency: number;
}

interface SyncStatus {
    deviceCount: number;
    devices: string[];
    isPlaying: boolean;
    syncAccuracy: number;
}

示例三：音频无缝切换

实现音频在不同设备间的无缝切换，播放不中断。

// SeamlessAudioSwitch.ets
import distributedAudio from '@ohos.distributedAudio';

export class SeamlessAudioSwitch {
    private audioRouter: distributedAudio.AudioRouter | null = null;
    
    // 当前播放器
    private currentPlayer: audio.AVPlayer | null = null;
    
    // 目标设备预加载播放器
    private preloadedPlayers: Map<string, audio.AVPlayer> = new Map();
    
    // 切换状态
    private switchState: SwitchState = {
        isSwitching: false,
        fromDevice: '',
        toDevice: ''
    };

    // 初始化无缝切换
    async initialize(): Promise<void> {
        this.audioRouter = distributedAudio.createAudioRouter();
        
        // 监听设备变化，提前预加载
        this.audioRouter.on('deviceAvailabilityChange', async (devices: AudioDeviceInfo[]) => {
            await this.preloadForDevices(devices);
        });
    }

    // 为设备预加载播放器
    private async preloadForDevices(devices: AudioDeviceInfo[]): Promise<void> {
        for (const device of devices) {
            if (!this.preloadedPlayers.has(device.deviceId)) {
                try {
                    // 创建预加载播放器
                    const player = await this.createPreloadedPlayer(device.deviceId);
                    this.preloadedPlayers.set(device.deviceId, player);
                    
                    console.info('[SeamlessSwitch] Preloaded for:', device.deviceId);
                } catch (error) {
                    console.error('[SeamlessSwitch] Preload failed:', error);
                }
            }
        }
    }

    // 创建预加载播放器
    private async createPreloadedPlayer(deviceId: string): Promise<audio.AVPlayer> {
        // 实际实现需要创建并准备播放器
        return null as any;
    }

    // 无缝切换到目标设备
    async seamlessSwitch(targetDeviceId: string): Promise<boolean> {
        console.info('[SeamlessSwitch] Switching to:', targetDeviceId);
        
        if (this.switchState.isSwitching) {
            console.warn('[SeamlessSwitch] Already switching');
            return false;
        }
        
        this.switchState.isSwitching = true;
        this.switchState.toDevice = targetDeviceId;
        
        try {
            // 1. 获取当前播放位置
            const currentPosition = this.currentPlayer?.currentTime || 0;
            const isPlaying = this.currentPlayer?.state === 'playing';
            
            // 2. 准备目标设备播放器
            let targetPlayer = this.preloadedPlayers.get(targetDeviceId);
            if (!targetPlayer) {
                targetPlayer = await this.createPreloadedPlayer(targetDeviceId);
            }
            
            // 3. 同步播放位置
            await targetPlayer.seek(currentPosition);
            
            // 4. 同步音量
            const currentVolume = await this.currentPlayer?.getVolume() || 0.5;
            await targetPlayer.setVolume(currentVolume);
            
            // 5. 交叉淡入淡出切换
            await this.crossFade(this.currentPlayer!, targetPlayer, 500);  // 500ms淡入淡出
            
            // 6. 更新当前播放器
            this.currentPlayer = targetPlayer;
            this.switchState.fromDevice = this.switchState.toDevice;
            
            // 7. 如果之前在播放，确保继续播放
            if (isPlaying) {
                await targetPlayer.play();
            }
            
            console.info('[SeamlessSwitch] Switch completed');
            return true;
        } catch (error) {
            console.error('[SeamlessSwitch] Switch failed:', error);
            return false;
        } finally {
            this.switchState.isSwitching = false;
        }
    }

    // 交叉淡入淡出
    private async crossFade(
        fromPlayer: audio.AVPlayer,
        toPlayer: audio.AVPlayer,
        duration: number
    ): Promise<void> {
        const steps = 20;
        const stepDuration = duration / steps;
        const fromVolume = await fromPlayer.getVolume();
        
        // 开始目标播放器（静音）
        await toPlayer.setVolume(0);
        await toPlayer.play();
        
        // 渐变
        for (let i = 0; i <= steps; i++) {
            const progress = i / steps;
            
            // 淡出源设备
            const fromVol = fromVolume * (1 - progress);
            await fromPlayer.setVolume(fromVol);
            
            // 淡入目标设备
            const toVol = fromVolume * progress;
            await toPlayer.setVolume(toVol);
            
            // 等待
            await this.sleep(stepDuration);
        }
        
        // 停止源播放器
        await fromPlayer.pause();
        await fromPlayer.setVolume(fromVolume);  // 恢复音量
    }

    // 辅助方法
    private sleep(ms: number): Promise<void> {
        return new Promise(resolve => setTimeout(resolve, ms));
    }

    // 获取切换状态
    getSwitchState(): SwitchState {
        return { ...this.switchState };
    }
}

// 接口定义
interface SwitchState {
    isSwitching: boolean;
    fromDevice: string;
    toDevice: string;
}

踰坑与注意事项

坑一：多设备音量不一致

问题描述：切换设备后音量差异很大，需要重新调节。

解决方案：实现音量归一化

// 音量归一化管理
class VolumeNormalizer {
    private deviceVolumeProfiles: Map<string, VolumeProfile> = new Map();
    
    // 学习设备音量特性
    async learnDeviceProfile(deviceId: string): Promise<void> {
        // 播放测试音频，记录设备响应
        const testVolumes = [0.2, 0.5, 0.8];
        const actualLevels: number[] = [];
        
        for (const vol of testVolumes) {
            await this.setDeviceVolume(deviceId, vol);
            const level = await this.measureActualLevel(deviceId);
            actualLevels.push(level);
        }
        
        // 建立音量映射曲线
        this.deviceVolumeProfiles.set(deviceId, {
            deviceId: deviceId,
            curve: this.buildVolumeCurve(testVolumes, actualLevels)
        });
    }
    
    // 获取归一化音量
    getNormalizedVolume(deviceId: string, targetLevel: number): number {
        const profile = this.deviceVolumeProfiles.get(deviceId);
        if (!profile) return targetLevel;
        
        return profile.curve.inverse(targetLevel);
    }
}

坑二：同步播放出现回声

问题描述：多设备同步播放时，由于延迟差异，产生回声效果。

解决方案：延迟补偿和对齐

// 配置延迟补偿
const syncConfig: distributedAudio.SyncConfig = {
    mode: 'ptp',
    precision: 5,
    
    // 延迟补偿
    latencyCompensation: {
        enabled: true,
        
        // 测量方法
        measurementMethod: 'ping_pong',  // 往返测量
        
        // 补偿策略
        strategy: 'delay_to_max',  // 所有设备延迟对齐到最大延迟
        
        // 最大容忍延迟差
        maxLatencyDiff: 50  // 50ms
    }
};

坑三：网络抖动导致卡顿

问题描述：网络不稳定时，音频流传输抖动，导致播放卡顿。

解决方案：自适应缓冲

// 自适应缓冲管理
class AdaptiveBufferManager {
    private minBuffer = 100;   // 最小缓冲 100ms
    private maxBuffer = 1000;  // 最大缓冲 1000ms
    private currentBuffer = 300;  // 当前缓冲 300ms
    
    // 根据网络状况调整
    adjustBuffer(networkQuality: NetworkQuality): void {
        switch (networkQuality) {
            case 'excellent':
                this.currentBuffer = this.minBuffer;
                break;
            case 'good':
                this.currentBuffer = 200;
                break;
            case 'fair':
                this.currentBuffer = 500;
                break;
            case 'poor':
                this.currentBuffer = this.maxBuffer;
                break;
        }
        
        // 应用新缓冲配置
        this.applyBufferConfig(this.currentBuffer);
    }
}

HarmonyOS 6适配

新增空间音频支持

HarmonyOS 6支持分布式空间音频：

// 配置空间音频
const spatialConfig: distributedAudio.SpatialConfig = {
    enabled: true,
    
    // 空间音频格式
    format: 'dolby_atmos',  // Dolby Atmos
    
    // 扬声器配置
    speakerLayout: {
        type: '5.1.2',  // 5.1.2声道
        positions: [
            { speaker: 'front_left', position: { x: -1, y: 1, z: 0 } },
            { speaker: 'front_right', position: { x: 1, y: 1, z: 0 } },
            { speaker: 'center', position: { x: 0, y: 1, z: 0 } },
            { speaker: 'surround_left', position: { x: -1, y: -1, z: 0 } },
            { speaker: 'surround_right', position: { x: 1, y: -1, z: 0 } },
            { speaker: 'subwoofer', position: { x: 0, y: 0, z: 0 } },
            { speaker: 'height_left', position: { x: -1, y: 0, z: 1 } },
            { speaker: 'height_right', position: { x: 1, y: 0, z: 1 } }
        ]
    },
    
    // 听者位置
    listenerPosition: { x: 0, y: 0, z: 0 },
    listenerOrientation: { yaw: 0, pitch: 0, roll: 0 }
};

await distributedAudio.enableSpatialAudio(spatialConfig);

增强的音频质量自适应

// 自适应质量配置
const adaptiveConfig: distributedAudio.AdaptiveQualityConfig = {
    enabled: true,
    
    // 质量级别
    qualityLevels: [
        { 
            quality: 'lossless',
            minBandwidth: 2000000,  // 2Mbps
            format: 'pcm_24bit',
            sampleRate: 96000
        },
        { 
            quality: 'high',
            minBandwidth: 500000,  // 500kbps
            format: 'aac',
            sampleRate: 48000,
            bitrate: 320000
        },
        { 
            quality: 'standard',
            minBandwidth: 100000,  // 100kbps
            format: 'aac',
            sampleRate: 44100,
            bitrate: 128000
        }
    ],
    
    // 切换策略
    switchStrategy: {
        hysteresis: 10,  // 滞后10秒，避免频繁切换
        smoothTransition: true
    }
};

音频设备群组

// 创建设备群组
const speakerGroup = await distributedAudio.createDeviceGroup({
    groupId: 'living_room',
    groupName: '客厅音响',
    devices: ['tv_speaker', 'soundbar', 'smart_speaker'],
    
    // 群组模式
    mode: 'synchronized',  // 同步播放
    
    // 主设备
    primaryDevice: 'soundbar',  // 音量控制等以主设备为准
    
    // 音量联动
    volumeLink: {
        enabled: true,
        mode: 'proportional',  // 按比例联动
        ratios: {
            'tv_speaker': 0.8,
            'soundbar': 1.0,
            'smart_speaker': 0.6
        }
    }
});

// 播放到群组
await audioPlayer.setOutputDevice(speakerGroup.groupId);

总结

分布式音频让声音突破了设备的物理限制，可以在最适合的设备上播放，甚至同时在多个设备上同步播放。无论是简单的设备切换，还是复杂的多设备同步，都为用户提供了更灵活、更沉浸的音频体验。

核心要点：

1. 音频路由：灵活决定音频输出到哪个设备
2. 多设备同步：精确时间协议确保多设备播放同步
3. 无缝切换：交叉淡入淡出实现设备间平滑切换
4. 自适应质量：根据网络状况动态调整音频质量

最佳实践：

• 实现音量归一化，避免切换设备时音量跳变
• 使用延迟补偿消除多设备回声
• 自适应缓冲应对网络抖动
• 预加载目标设备播放器实现快速切换
• 善用设备群组简化多设备管理

分布式音频是HarmonyOS分布式能力的重要组成部分，下一篇我们将探讨分布式输入，看看如何实现跨设备的输入事件处理。