Audio Playback Fundamentals in Cocos Creator

Cocos Creator provides two distinct approaches for audio playback: the AudioSource component and the AudioEngine API. Understanding the differences between these two options helps developers choose the right approach for their specific requirements.

The AudioSource component functions as a scene entity that can be configured through the editor. In contrast, AudioEngine is a pure API accessible only through scripting. Both approaches handle AudioClip resources, which must be loaded and configured within the Cocos Creator editor environment.

Implementing AudioSource Component

Add an AudioSource componetn to an empty node within your scene hierarchy. Create a component script that exposes the audio source and provides basic playback controls:

cc.Class({
    properties: {
        audioSource: {
            type: cc.AudioSource,
            default: null
        }
    },
    
    playAudio() {
        this.audioSource.play();
    },
    
    pauseAudio() {
        this.audioSource.pause();
    },
    
    stopAudio() {
        this.audioSource.stop();
    }
});

Using AudioEngine API

Define an AudioClip property in your component and invoke the engine API directly:

cc.Class({
    properties: {
        clip: {
            default: null,
            type: cc.AudioClip
        }
    },
    
    onLoad() {
        this.audioID = cc.audioEngine.playEffect(this.clip, false, 1);
    },
    
    onDestroy() {
        cc.audioEngine.stopEffect(this.audioID);
    }
});

The AudioEngine API requires passing a complete AudioClip object rather than a URL string. Define audio assets in the properties section and drag audio files from the project assets into the inspector fields.

Essential AudioEngine Methods

AudioSource Component Methods:

• play() - Start playback
• stop() - Halt playback
• pause() - Pause current playback
• resume() - Continue paused playback
• rewind() - Restart from beginning

AudioEngine System:

// Background music with loop
cc.audioEngine.playMusic(source);
cc.audioEngine.stopMusic();

// Short sound effects
cc.audioEngine.playEffect(source);
cc.audioEngine.stopEffect(source);

AudioEngine provides a more reliable experience across native platforms compared to AudioSource component playback in certain scenarios.

Sound Manager Implementation

Create a singleton-based manager to centralize audio operations throughout your game:

const { ccclass, property } = cc._decorator;

@ccclass
export default class AudioManager {
    audioBasePath: string = 'res/sounds/';
    audioCache: { [key: string]: cc.AudioClip } = {};
    audioEnabled: boolean = true;
    currentMusicKey: string = '';
    
    private static _instance: AudioManager;
    
    public static getInstance(): AudioManager {
        if (!this._instance) {
            this._instance = new AudioManager();
        }
        return this._instance;
    }
    
    registerAudio(key: string, clip: cc.AudioClip) {
        this.audioCache[key] = clip;
    }
    
    playSfx(sfxName: string) {
        if (!this.audioEnabled) return;
        cc.audioEngine.playEffect(this.audioCache[sfxName], false);
    }
    
    playBackgroundMusic(musicName: string) {
        this.currentMusicKey = musicName;
        if (!this.audioEnabled) return;
        cc.audioEngine.playMusic(this.audioCache[musicName], true);
    }
    
    haltBackgroundMusic() {
        cc.audioEngine.stopMusic();
    }
    
    toggleAudio(enabled: boolean) {
        this.audioEnabled = enabled;
        if (this.audioEnabled && this.currentMusicKey) {
            this.playBackgroundMusic(this.currentMusicKey);
        } else {
            cc.audioEngine.stopAll();
        }
    }
    
    isAudioEnabled(): boolean {
        return this.audioEnabled;
    }
}

The singleton pattern ensures a single point of control for all audio operations. The audioCache object stores key-value pairs mapping audio identifiers to their corresponding AudioClip assets.

Loading Audio Resources at Startup

Place all audio files in a folder named sounds within the resources directory, as dynamic loading via code requires resources to be located there. Attach a game controller component to the Canvas node:

const { ccclass, property } = cc._decorator;
import AudioManager from "AudioManager";

@ccclass
export default class GameController extends cc.Component {
    initializeAudioAssets() {
        cc.loader.loadResDir('sounds', cc.AudioClip, (err, clips) => {
            if (err) {
                console.error("Audio loading failed:", err);
                return;
            }
            clips.forEach(clip => {
                AudioManager.getInstance().registerAudio(clip.name, clip);
            });
        });
    }
    
    onLoad() {
        this.initializeAudioAssets();
    }
    
    handlePlayButton() {
        AudioManager.getInstance().playBackgroundMusic('spring_music');
    }
    
    handleStopButton() {
        AudioManager.getInstance().haltBackgroundMusic();
    }
}

The controller loads all audio assets during the onLoad lifecycle phase and exposes button click handlers for UI integration.

Browser Compatibility Considerations

Some browsers enforce restrictions on automatic audio playback. Chrome disables WebAudio autoplay by default, which may cause silent playback in certain configurations. When this occurs, select the audio asset in the project hierarchy and modify the loading mode to DOM Audio in the property inspector to ensure proper playback across different browser environments.