f8-features-audio-workflow

# Audio Feature Workflow > **⚠️ IMPORTANT**: Before using this feature, you **MUST** formally initialize F8Framework in the launch sequence. Ensure `ModuleCenter.Initialize(this);` has run first, then create the required module, for example `FF8.Audio = ModuleCenter.CreateModule<AudioManager>();`. ## Use this skill when - The task is about sound playback, volume, or audio management. - The user asks about BGM, voice, SFX, or 3D audio effects. - The user needs global pause/resume or audio switch persistence. ## Path resolution 1. Prefer project source at Assets/F8Framework. 2. If F8Framework is installed as a package, use Packages/F8Framework. 3. For usage docs, read: Assets/F8Framework/Tests/Audio/README.md ## Sources of truth - Runtime module: Assets/F8Framework/Runtime/Audio - Test docs: Assets/F8Framework/Tests/Audio ## Key classes and interfaces | Class | Role | |-------|------| | `AudioManager` | Core module. Access via `FF8.Audio`. | | `AudioMusic` | Background music player. | | `AudioVoice` | Voice/dialogue player. | | `AudioEffect` | SFX and UI sound player. | ## API quick reference ### Background music ```csharp FF8.Audio.PlayMusic("assetName", callback, loop: true, priority: 1, fadeDuration: 3f); float progress = FF8.Audio.ProgressMusic; FF8.Audio.SetProgressMusic = 0.5f; FF8.Audio.VolumeMusic = 0.5f; // Auto-saves to PlayerPrefs FF8.Audio.SwitchMusic = false; // Auto-saves to PlayerPrefs FF8.Audio.SetMusicComplete(callback); ``` ### Voice ```csharp FF8.Audio.PlayVoice("assetName", callback, loop: true, priority: 1, fadeDuration: 3f); float progressVoice = FF8.Audio.ProgressVoice; FF8.Audio.SetProgressVoice = 0.5f; FF8.Audio.VolumeVoice = 0.5f; FF8.Audio.SwitchVoice = false; FF8.Audio.SetVoiceComplete(callback); ``` ### Sound effects ```csharp FF8.Audio.PlayUISound("assetName", callback, loop: true, priority: 1, fadeDuration: 3f); FF8.Audio.PlayBtnClick("assetName", callback); FF8.Audio.PlayAudioEffect("assetName", callback); FF8.Audio.VolumeAudioEffect = 0.5f; FF8.Audio.SwitchAudioEffect = false; FF8.Audio.SetUISoundComplete(callback); FF8.Audio.SetBtnClickComplete(callback); FF8.Audio.SetAudioEffectComplete(callback); ``` ### One-shot 2D audio effects ```csharp FF8.Audio.PlayAudioEffect2D("assetName", volume: 1f, maxNum: 5, callback); ``` ### 3D audio effects ```csharp FF8.Audio.PlayAudioEffect3D("assetName", isRandom: true, transform.position, volume: 1f, spatialBlend: 1f, maxNum: 5, callback); ``` ### Global control ```csharp FF8.Audio.PauseAll(); // Pause all, including one-shot AudioEffect instances FF8.Audio.ResumeAll(); // Resume all, including one-shot AudioEffect instances FF8.Audio.StopAll(); // Stop all, including one-shot AudioEffect instances FF8.Audio.UnloadAll(true); // Unload all audio (true = force including in-use) ``` ### Optional AudioMixer ```csharp FF8.Audio.SetAudioMixer(FF8.Asset.Load<AudioMixer>("F8AudioMixer")); ``` ### Individual channel control ```csharp FF8.Audio.AudioMusic.Pause(); FF8.Audio.AudioMusicVoice.Resume(); FF8.Audio.AudioMusicBtnClick.Stop(); FF8.Audio.AudioMusicUISound.UnloadAll(); ``` ## Workflow 1. Load audio clips via AssetManager (place in AssetBundles or Resources). 2. Choose category: Music (BGM), Voice, AudioEffect (SFX/UI), or one-shot 2D/3D AudioEffect. 3. Use priority parameter for Music/Voice to handle overlapping tracks. 4. Volume and switch settings auto-persist to PlayerPrefs. 5. Use fadeDuration for smooth transitions between tracks. 6. For 3D effects, set `spatialBlend: 1f` and provide world position. 7. Optionally set up F8AudioMixer for advanced mixing control. ## Common error handling | Error | Cause | Solution | |-------|-------|----------| | Audio clip not found | Asset not in loadable directory | Ensure clip is under AssetBundles or Resources, press F8 | | No sound on mobile | Volume or switch set to off | Check `SwitchMusic`/`SwitchAudioEffect` values | | Memory leak from audio | Not unloading unused clips | Call `UnloadAll()` when transitioning scenes | | One-shot SFX stops too early | Timer using scaled time or clip load failed | Use current `AudioEffect` implementation; it tracks one-shot instances with unscaled clip duration | ## Cross-module dependencies - **AssetManager**: All audio clips loaded via `FF8.Asset`. - **Storage**: Volume/switch settings internally stored via PlayerPrefs. ## Output checklist - Audio category selected (Music/Voice/AudioEffect/one-shot AudioEffect). - Volume persistence configured. - Files changed and why. - Validation status and remaining risks.