skills/audio-code-review/SKILL.md
Technical Director review of audio system code quality
npx skillsauth add sipherxyz/universal-ue-skills audio-code-reviewInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
Role: Technical Director - Audio Systems Specialist
Scope: Plugins/SipherAudio/, Plugins/S2ContextEffects/, Content/S2/Audio/
Platform Focus: PC, PS5, Xbox Series X, Next-gen consoles
Performance Target: 60 FPS with dynamic audio
Conduct a strict, high-performance code review of audio system implementations, focusing on:
1. Synchronous Asset Loading
// ❌ BLOCKING - Console cert FAIL
CBM_Designer = AudioSettings->DesignerControlBusMix.LoadSynchronous();
UClass* ControllerClass = ControllerClassSoft.LoadSynchronous();
LoadedObj = ObjPath.TryLoad();
// ✅ CORRECT - Async with FStreamableManager
FStreamableManager& Streamable = UAssetManager::GetStreamableManager();
Streamable.RequestAsyncLoad(AssetPath,
FStreamableDelegate::CreateUObject(this, &ThisClass::OnAssetsLoaded),
FStreamableManager::AsyncLoadHighPriority);
Check for:
LoadSynchronous() calls in any audio codeTryLoad() calls during gameplayTSoftObjectPtr loads are asyncTSoftClassPtr loads are async2. Audio Component Lifecycle
// ❌ WRONG - Memory leak risk
FGameplayEffectSpec* GESpec = new FGameplayEffectSpec(...);
// ❌ WRONG - No pooling, GC pressure
UAudioComponent* Comp = UGameplayStatics::CreateSound2D(this, Sound);
// ✅ CORRECT - Use FGameplayEffectSpecHandle
FGameplayEffectSpecHandle SpecHandle = ASC->MakeOutgoingSpec(...);
// ✅ CORRECT - Implement audio component pool
UAudioComponent* AcquireComponentFromPool();
void ReleaseComponentToPool(UAudioComponent* Component);
Check for:
new for UObjects or FGameplayEffectSpecUPROPERTY() on all UObject references3. Audio Thread Safety
// ❌ WRONG - All audio on game thread
AudioComponent->SetSound(NewSound);
AudioComponent->FadeIn(FadeTime, TargetVolume);
// ✅ CORRECT - Delegate to audio thread
FAudioThread::RunCommandOnAudioThread([AudioComponent, NewSound]()
{
if (AudioComponent && NewSound)
{
AudioComponent->SetSound(NewSound);
}
});
Check for:
FAudioThread::RunCommandOnAudioThread()4. Component Caching
// ❌ WRONG - O(n) lookup every call
auto AudioManager = GetWorld()->GetSubsystem<USipherAudioManagerSubsystem>();
// ⚠️ QUESTIONABLE - TWeakObjectPtr overhead
TWeakObjectPtr<USipherAudioManagerWorldSubsystem> WorldManagerWeak;
// ✅ CORRECT - Cache in PostInitializeComponents
UPROPERTY(Transient)
TObjectPtr<USipherAudioManagerSubsystem> CachedAudioManager;
void PostInitializeComponents()
{
Super::PostInitializeComponents();
CachedAudioManager = GetGameInstance()->GetSubsystem<USipherAudioManagerSubsystem>();
}
Check for:
GetSubsystem() calls in hot paths (Tick, frequent calls)5. Logging & Error Handling
// ❌ WRONG - LogTemp usage
UE_LOG(LogTemp, Warning, TEXT("Audio failed"));
// ❌ WRONG - No validation
SetSound(NewSound);
// ✅ CORRECT - Custom log category
DEFINE_LOG_CATEGORY_STATIC(LogSipherAudio, Log, All);
UE_LOG(LogSipherAudio, Warning, TEXT("Audio environment %s failed to load"), *Tag.ToString());
// ✅ CORRECT - Validate before use
if (!IsValid(NewSound))
{
UE_LOG(LogSipherAudio, Error, TEXT("Invalid sound asset"));
return;
}
Check for:
IsValid())6. UE5 Audio Features
// ⚠️ MISSING - No MetaSounds usage
UPROPERTY(EditAnywhere)
TObjectPtr<USoundBase> BGMSound;
// ✅ GOOD - Use MetaSoundSource for dynamic parameters
UPROPERTY(EditAnywhere)
TObjectPtr<UMetaSoundSource> BGMMetaSound;
void UpdateCombatIntensity(float Intensity)
{
if (AudioComponent)
{
AudioComponent->SetFloatParameter(FName("CombatIntensity"), Intensity);
}
}
Check for:
7. Code Organization
// ❌ WRONG - Monolithic function (300+ lines)
void CrossFadeNewBGM(FName BGMIdToTransit)
{
if (CurrentWorldPlaylist.IsEmpty()) { }
else {
if(CurrentWorldPlaylist.Find(BGMIdToTransit)) {
if (!CurrentBGMPlayer) { }
else {
if (CurrentBGMPlayer->GetSound() == NewBGM.BGM) { }
else {
// ... 200 more lines ...
}
}
}
}
}
// ✅ CORRECT - Decomposed into focused functions
void CrossFadeNewBGM(FName BGMIdToTransit)
{
if (!ValidatePlaylist(BGMIdToTransit)) return;
USoundBase* NewSound = GetBGMFromPlaylist(BGMIdToTransit);
if (ShouldCrossfade(NewSound))
{
StartCrossfade(NewSound);
}
}
Check for:
8. Blueprint Exposure
// ❌ WRONG - Public state flags (race conditions)
UPROPERTY(BlueprintReadWrite)
bool isLoadingFlag = false;
UPROPERTY(BlueprintReadWrite)
bool OnAudioTransitionFlag = false;
// ✅ CORRECT - Encapsulated with accessors
UPROPERTY(BlueprintReadOnly, Category = "Audio State", meta = (AllowPrivateAccess = "true"))
bool bIsTransitioning = false;
UFUNCTION(BlueprintPure, Category = "Audio State")
bool IsTransitioning() const { return bIsTransitioning; }
Check for:
BlueprintReadWrite on state machine flagsbIsActive, not isActiveFlag)const// ✅ GOOD USAGE
void InitControlBusMixes()
{
if (UModulationStatics* Modulation = GEngine->GetAudioDeviceManager())
{
Modulation->ActivateBusMix(*CBM_Designer);
// Load user settings
TArray<FSoundControlBusMixStage> MixStages =
Modulation->LoadMixFromProfile(UserProfileIndex, *CBM_User);
}
}
Check for:
// ✅ GOOD USAGE
void PlayBGMQuantized(UQuartzClockHandle* MusicClock)
{
if (AudioComponent && MusicClock)
{
FQuartzQuantizationBoundary Boundary;
Boundary.Quantization = EQuartzCommandQuantization::Bar;
Boundary.CountingReferencePoint = EQuarztQuantizationReference::BarRelative;
AudioComponent->PlayQuantized(GetWorld(), MusicClock,
Boundary, FOnQuartzCommandEventBP());
}
}
Check for:
Frame Budget Analysis:
Unreal Insights Checks:
# Profile audio systems
UnrealEditor.exe S2.uproject -game -trace=cpu,loadtime,audio -tracefile=audio_profile
# Analysis targets:
# 1. Zero LoadSynchronous calls during gameplay
# 2. Audio thread shows activity (not all on game thread)
# 3. No frame spikes during environment transitions
# 4. Asset streaming working correctly
Check Insights for:
LoadSynchronous / TryLoad calls (should be 0)// PS5 Tempest Audio
#if PLATFORM_PS5
AudioComponent->SetSpatializationMethod(ESpatializationMethod::HRTF);
#endif
// Xbox Spatial Sound
#if PLATFORM_XBOXONE || PLATFORM_XSX
AudioComponent->EnableSpatialSound(true);
#endif
Check for:
Objective: Ensure consistent, descriptive naming for all audio assets following UE5 and project conventions.
Sound Assets:
SW_ - Sound Wave (imported audio files)
SC_ - Sound Cue (sound composition/logic)
MS_ - MetaSound Source
MSP_ - MetaSound Patch
Audio Configuration:
SoundClass_ - Sound Class hierarchy nodes
Mix_ - Sound Mix (legacy volume control)
CBM_ - Control Bus Mix (Audio Modulation)
Bus_ - Audio Bus (submix routing)
ControlBus_ - Control Bus (modulation parameter)
Att_ - Attenuation Settings (spatial audio)
Quartz Assets:
QC_ - Quartz Clock Handle
QCH_ - Quartz Clock Handle (alternative)
Quartz_ - General Quartz configuration
Context Effects:
CE_ - Context Effect configuration
CEL_ - Context Effect Library
Content/S2/Audio/
├── BGM/ # Background Music
│ ├── Combat/ # Combat music layers
│ ├── Exploration/ # Ambient exploration
│ └── Boss/ # Boss encounter themes
├── SFX/ # Sound Effects
│ ├── Character/ # Character sounds
│ │ ├── Footsteps/
│ │ ├── Vocals/
│ │ └── Abilities/
│ ├── Weapons/ # Weapon sounds
│ ├── UI/ # UI feedback
│ └── Ambience/ # Environmental ambience
├── Dialogue/ # Voice acting
│ ├── Player/
│ ├── NPCs/
│ └── Bosses/
├── AudioConfig/ # Configuration assets
│ ├── Attenuation/ # Att_* files
│ ├── Modulation/ # CBM_*, ControlBus_* files
│ ├── SoundClasses/ # SoundClass_* hierarchy
│ └── Quartz/ # QC_* timing assets
└── MetaSounds/ # MetaSound sources
├── Music/ # Dynamic music systems
└── Procedural/ # Procedural audio
✓ SW_BGM_Boss_Intro_Loop
✓ SC_Player_Footstep_Stone
✓ MS_Combat_Dynamic_Layer
✓ CBM_MasterVolume
✓ Att_Weapon_Close
✓ SoundClass_SFX_Weapons
✓ QC_MusicClock
✓ CE_Footstep_Surface_Stone
✗ NewSound1 # No prefix, vague name
✗ sound_cue_final_v2 # Lowercase, version suffix, no context
✗ BGM-BossMusic # Wrong separator (use underscore)
✗ SFX.Footstep.Stone # Wrong separator (use underscore)
✗ SW_ALLCAPS # Don't use all caps after prefix
✗ SW_Boss Music Loop # No spaces (use underscore)
✗ SC_Test # Temporary/test assets shouldn't be committed
1. Structure:
[Prefix]_[Category]_[Subcategory]_[Descriptor]_[Variant]
Examples:
SW_Character_Player_Jump_01
SW_Weapon_Sword_Swing_Heavy
SC_UI_Button_Hover
MS_BGM_Combat_Intensity_System
CBM_Gameplay_DynamicMix
2. Descriptive Clarity:
3. Consistency:
4. Special Cases:
Variations:
SW_Character_Grunt_01
SW_Character_Grunt_02
SW_Character_Grunt_03
Layered Music:
SW_BGM_Combat_Base_Loop
SW_BGM_Combat_Drums_Loop
SW_BGM_Combat_Melody_Loop
State-Driven:
SC_BGM_Exploration_Calm
SC_BGM_Exploration_Alert
SC_BGM_Exploration_Combat
Check for:
Console Audio Assets:
# ❌ WRONG - Don't duplicate assets per platform
SW_Explosion_PS5
SW_Explosion_Xbox
SW_Explosion_PC
# ✅ CORRECT - Use single asset with platform scalability
SW_Explosion
# Configure platform-specific compression in asset settings
Check for:
1. Scan Asset Folders:
# List all audio assets
ls -R Content/S2/Audio/
# Find assets without proper prefixes
grep -r "^[^A-Z]" Content/S2/Audio/
2. Check for Common Issues:
3. Validate Against Standards:
When reviewing asset naming, include:
## 🎵 Audio Asset Naming Review
**Assets Scanned:** X total
**Compliant:** Y (Z%)
**Issues Found:** W
### 📊 Compliance Breakdown
| Category | Total | Compliant | Issues |
|----------|-------|-----------|--------|
| Sound Waves (SW_) | 150 | 142 | 8 |
| Sound Cues (SC_) | 80 | 75 | 5 |
| MetaSounds (MS_) | 30 | 30 | 0 |
| Config Assets | 40 | 38 | 2 |
### 🔴 Critical Naming Issues
#### Issue #1: Missing Prefixes
**Location:** `Content/S2/Audio/SFX/`
**Files:**
- `ExplosionSound.uasset` → Should be `SW_Explosion` or `SC_Explosion`
- `FootstepGrass.uasset` → Should be `SW_Character_Footstep_Grass`
**Impact:** Breaks asset search/filtering, unclear asset type
**Fix Time:** 30 minutes (batch rename)
#### Issue #2: Inconsistent Patterns
**Location:** `Content/S2/Audio/BGM/`
**Files:**
- `SW_Boss1Music.uasset`
- `SW_BossMusic02.uasset`
- `SW_BGM_Boss_03.uasset`
**Expected Pattern:** `SW_BGM_Boss_[Name]_[Variant]`
**Fix Time:** 1 hour (standardize naming)
### 🟡 Organization Issues
#### Misplaced Assets
- `Content/S2/Audio/CBM_Volume.uasset` → Move to `AudioConfig/Modulation/`
- `Content/S2/Audio/SFX/Att_Global.uasset` → Move to `AudioConfig/Attenuation/`
### ✅ Well-Organized Sections
- ✓ `Content/S2/Audio/BGM/Combat/` - All assets follow `SW_BGM_Combat_*` pattern
- ✓ `Content/S2/Audio/MetaSounds/` - Proper MS_ prefixes, well categorized
- ✓ `Content/S2/Audio/AudioConfig/Quartz/` - Clean QC_ naming
### 🎯 Recommendations
**Immediate Actions:**
1. Rename 8 assets missing prefixes (30 min)
2. Standardize boss music naming pattern (1 hour)
3. Move misplaced config assets to AudioConfig/ (15 min)
**Batch Rename Script:**
\`\`\`python
# Example rename script for UE5 Python API
import unreal
# Rename assets without SW_ prefix in SFX folder
asset_registry = unreal.AssetRegistryHelpers.get_asset_registry()
assets = asset_registry.get_assets_by_path("/Game/S2/Audio/SFX/", recursive=True)
for asset_data in assets:
asset_name = asset_data.asset_name
if not asset_name.startswith(("SW_", "SC_", "MS_")):
# Suggest proper name based on asset type
new_name = f"SW_{asset_name}"
print(f"Rename: {asset_name} → {new_name}")
\`\`\`
**Next Steps:**
- Review with audio team
- Update asset naming guide documentation
- Train team on naming standards
- Set up pre-commit hooks to enforce naming
Generate a report in: claude-agents/reports/technical-director/audio/code_review_[date].md
Report Structure:
# Audio Code Quality Review - [Component Name]
**Date:** YYYY-MM-DD
**Reviewer:** Technical Director AI Agent
**Files Reviewed:** [List of files]
**Assets Reviewed:** [Asset paths if applicable]
**Scope:** [Specific functionality reviewed]
## 📊 Executive Summary
🔴 **Critical Issues**: X | 🟡 **High Priority**: Y | 🟢 **Medium**: Z | ⚪ **Low**: W
**Overall Grade:** [A-F]
**Console Cert Status:** [PASS/FAIL]
**Performance Grade:** 🟩🟩🟩⬜⬜ 60%
**Asset Naming Compliance:** 🟩🟩🟩🟩⬜ 85% (if asset review performed)
## 🔴 Critical Issues
### Issue #1: [Title]
**File:** `Path/To/File.cpp:123`
**Severity:** 🔴 Critical
**Impact:** [Console cert blocker / Memory leak / Performance regression]
**Current Code:**
\`\`\`cpp
// Show problematic code
\`\`\`
**Fix:**
\`\`\`cpp
// Show correct implementation
\`\`\`
**Effort:** [Hours/Days]
**Priority:** P0
## 🟡 High Priority Issues
[Continue with high priority items...]
## 🟢 Medium Priority Issues
[Continue with medium priority items...]
## 🎵 Audio Asset Naming Review (if applicable)
**Assets Scanned:** X total
**Compliant:** Y (Z%)
**Issues Found:** W
### 📊 Compliance Breakdown
| Category | Total | Compliant | Issues |
|----------|-------|-----------|--------|
| Sound Waves (SW_) | 150 | 142 | 8 |
| Sound Cues (SC_) | 80 | 75 | 5 |
| MetaSounds (MS_) | 30 | 30 | 0 |
| Config Assets | 40 | 38 | 2 |
### Naming Issues Found
[List specific naming convention violations]
### Organization Issues
[List folder structure or asset organization problems]
## ✅ Strengths
- List positive findings
- Good patterns observed
- Best practices followed
## 📈 Performance Analysis
**Frame Budget Breakdown:**
- Audio updates: Xms (Y% of 16.67ms)
- Asset loading: Handled async ✅
- Memory usage: XMB (within budget)
## 🎯 Recommendations
**Immediate (This Sprint):**
1. Fix critical issue #1 (estimated: X hours)
2. Fix critical issue #2 (estimated: Y hours)
3. Rename non-compliant assets (estimated: X hours)
**Next Sprint:**
1. Address high priority issues
2. Implement performance optimizations
3. Reorganize misplaced assets
**Future:**
1. MetaSounds integration
2. Spatial audio support
3. Asset naming automation/validation
## 📋 Testing Checklist
- [ ] All fixes implemented
- [ ] Unreal Insights profiling clean
- [ ] Console cert tools pass
- [ ] Regression tests pass
- [ ] Audio still plays correctly
- [ ] Asset renames propagated to all references
- [ ] No broken asset references after reorganization
---
**Report Generated:** [Timestamp]
**Next Review:** [Date]
\`\`\`
## Example Invocation
To use this skill, invoke it when reviewing audio code or assets:
**Code Review:**
\`\`\`
/skill audio-code-review
Please review the following audio implementation:
- Plugins/SipherAudio/Source/SipherAudio/Private/SipherAudioManagerSubsystem.cpp
- Focus on the SetAudioEnvironmentTag and CreateEnvironmentController functions
\`\`\`
**Asset Naming Convention Review:**
\`\`\`
/skill audio-code-review
Please review the audio asset naming conventions in Content/S2/Audio/
- Check all Sound Waves, Sound Cues, and MetaSounds for proper prefixes
- Verify folder organization matches standards
- Identify any misnamed or misplaced assets
\`\`\`
**Combined Review:**
\`\`\`
/skill audio-code-review
Conduct a comprehensive audio review:
1. Code quality in Plugins/SipherAudio/
2. Asset naming conventions in Content/S2/Audio/
3. Generate unified report with priorities
\`\`\`
## Knowledge Base References
- `claude-agents/reports/technical-director/audio/audio-systems-review.md` - Initial audit
- `claude-agents/reports/technical-director/audio/audio-systems-fast-implementation-plan.md` - Fix timeline
- `/CLAUDE.md` - Project standards and common pitfalls
- `.github/copilot-instructions.md` - UE5 coding standards
## Success Criteria
**Code Review Complete When:**
- ✅ All critical issues documented with line numbers
- ✅ Performance analysis includes frame budget impact
- ✅ Console cert compliance assessed
- ✅ Actionable recommendations with effort estimates
- ✅ Test plan provided for validation
- ✅ Report follows visual standards (emojis, progress bars)
## Legacy Metadata
```yaml
skill: audio-code-review
invoke: /audio-systems:audio-code-review
type: code-review
category: technical-director
scope: Plugins/SipherAudio, Plugins/S2ContextEffects, Content/S2/Audio
development
This skill should be used when implementing features in isolation using git worktrees. Triggers on "create worktree", "isolated workspace", "parallel development", or when starting implementation that should not affect main workspace.
testing
Manage VFX team issues on GitHub Projects - timeline scheduling, status updates, member commit checks, bulk assign. Use when managing VFX team project board, adding issues to timeline, checking member progress, or bulk-updating issue fields.
tools
Generate C++ validation rules from JSON definitions. Use when team updates ValidationRules.json or asks to add/modify validation rules.
development
Check codebase for Microsoft Xbox XR (Xbox Requirements) compliance issues. Scans for account picker, cloud saves, achievements, Quick Resume, and Xbox certification requirements. Use before console submission or when preparing for Microsoft certification. Triggers on "XR", "Xbox certification", "Microsoft compliance", "Xbox cert", "Xbox requirements", "GDK compliance".