Audio Debugging Skill

This skill activates when you encounter audio-related issues in VSSK-shadecn.

When to Use

This skill automatically activates for:

• Audio playback not working
• Pitch preservation issues
• Speed control problems
• Audio caching failures
• Waveform rendering issues
• Audio buffer errors
• Service worker audio problems

Debugging Process

1. Identify the Issue

• What's the expected behavior?
• What's actually happening?
• When does it occur? (specific conditions)
• Which browsers/devices affected?

2. Check Common Problems

Audio Won't Play

• Audio file loaded correctly?
• Audio context resumed (user gesture required)?
• Network errors or CORS issues?
• Browser autoplay policy blocking?

Pitch Preservation Issues

• Using correct Web Audio API methods?
• playbackRate vs detune?
• Browser support for pitch shifting?
• Alternative library needed?

Caching Problems

• Service worker registered?
• Cache strategy correct for audio?
• Storage quota exceeded?
• Cache versioning working?

3. Diagnostic Commands

// Check audio context state
console.log('AudioContext state:', audioContext.state)

// Test audio loading
fetch('/audio/song.mp3')
  .then(res => console.log('Audio fetch:', res.status))
  .catch(err => console.error('Audio fetch error:', err))

// Check cache
caches.open('audio-v1').then(cache =>
  cache.keys().then(keys => console.log('Cached audio:', keys.length))
)

// Monitor playback
audio.addEventListener('error', (e) => {
  console.error('Audio error:', e)
  console.log('Error code:', audio.error?.code)
  console.log('Error message:', audio.error?.message)
})

4. Browser-Specific Issues

iOS Safari

• Requires user gesture to start audio
• Limited concurrent audio contexts
• No background audio without special handling
• Service worker limitations

Chrome Android

• Autoplay policy restrictions
• Battery optimization may pause audio
• Storage quota more restrictive

5. Common Fixes

Audio Context Suspended

// Resume audio context on user interaction
const resumeAudioContext = async () => {
  if (audioContext.state === 'suspended') {
    await audioContext.resume()
  }
}

// Call on user gesture (click, tap)
button.addEventListener('click', resumeAudioContext)

Pitch Preservation

// Use Web Audio API for pitch preservation
const source = audioContext.createBufferSource()
source.playbackRate.value = 0.5 // Half speed
source.detune.value = 0 // Keep original pitch

Cache Issues

// Check storage quota
if ('storage' in navigator && 'estimate' in navigator.storage) {
  const estimate = await navigator.storage.estimate()
  console.log(`Using ${estimate.usage} of ${estimate.quota} bytes`)
}

Output Format

Provide:

1. Problem Diagnosis: What's wrong and why
2. Root Cause: Technical explanation
3. Solution: Step-by-step fix with code
4. Prevention: How to avoid this in future
5. Testing: How to verify it's fixed