Documentation

Troubleshooting

Solutions to common issues and problems

🔊 Audio Issues

❌ No Sound During Playback

  • Check Volume: Master fader and track faders up?
  • Check Mute: Ensure tracks not muted (M button off)
  • Check Solo: Solo mode isolates specific tracks
  • Check Output: System Settings → Sound → Output device
  • Check Levels: Look at meters - signal present?
  • Restart Audio: Quit and relaunch Stori

❌ Crackling or Glitches

  • Check CPU: Look at CPU meter in toolbar
  • Increase Buffer: Higher buffer = less glitches
  • Close Apps: Quit other audio applications
  • Bounce Tracks: Render MIDI to audio to save CPU
  • Freeze Effects: Disable effects temporarily
  • Restart Mac: Clear system audio state

❌ Latency/Delay

  • Lower Buffer Size: 128 or 64 samples
  • Use Interface: External audio interface better than built-in
  • Close Background: Quit CPU-heavy apps
  • Check Bluetooth: Bluetooth adds latency - use wired
  • Disable Effects: Effects add processing time
  • Sample Rate: Match interface to project (44.1kHz)

❌ Distortion/Clipping

  • Check Meters: Are they hitting red?
  • Lower Faders: Reduce track and master volume
  • Check Gain: Lower region gain in Inspector
  • Remove Effects: Distortion/compression adding gain?
  • Headroom: Keep peaks at -6dB to -3dB
  • Master Limiter: Add limiter to prevent clipping

🤖 AI Generation Issues

❌ Generation Fails

  • Check Services: ⌘⇧M - all indicators green?
  • Restart Services: Stop All → Start All
  • Check RAM: Need 16GB for AI models
  • Close Apps: Free up memory
  • Check Disk: 10GB free space required
  • Check Internet: First run downloads models

❌ Services Won't Start

  • Port Conflicts: Other apps using ports 10000-10002?
  • Check Terminal: Look for error messages
  • Python Version: Need Python 3.11+
  • Dependencies: Run setup script again
  • Permissions: Grant file access in System Settings
  • Logs: Check service logs for errors

❌ Slow Generation

  • First Run: Initial model download takes time
  • Model Loading: First generation loads model (~10-15s)
  • Expected Time: 30-60s for 30-second clips normal
  • CPU Throttling: Check Activity Monitor
  • Background Tasks: Close heavy applications
  • Use Smaller Model: Faster but lower quality

❌ Poor Quality Results

  • Improve Prompt: Be more specific and detailed
  • Use Enhancement: Click "Enhance Prompt" button
  • Generate Multiple: Try 3-5 variations
  • Adjust Temperature: Lower for consistency
  • Try Different Model: Medium vs small/large
  • 30 Seconds: Sweet spot for quality

⛓️ Blockchain & Wallet Issues

❌ Wallet Won't Connect

  • Core Installed? Download from core.app
  • Wallet Unlocked? Unlock Core wallet
  • Network Added? Add TellUrStori L1 (Chain ID 507)
  • Grant Permission: Approve connection in Core
  • Restart Both: Quit Stori and Core, relaunch
  • Check Browser: Some wallets need browser open

❌ Transaction Failed

  • Insufficient Funds: Need TUS for gas + payment
  • Gas Too Low: Increase gas limit
  • Network Congestion: Wait and try again
  • Rejected in Wallet: Approve in Core popup
  • Check Balance: Verify wallet has enough TUS
  • Block Explorer: Check transaction status

❌ IPFS Upload Fails

  • File Size: Check if files too large (500MB limit)
  • Internet: Stable connection required
  • IPFS Daemon: Local daemon running? (optional)
  • Timeout: Large files take longer
  • Retry Upload: Click retry button
  • Check Logs: Review upload progress details

❌ NFT Not Appearing

  • Wait for Confirmation: Takes 1-5 seconds
  • Refresh View: Close and reopen marketplace
  • Check Wallet: Verify transaction in Core
  • Block Explorer: Confirm on blockchain
  • Indexer Delay: GraphQL indexer may lag slightly
  • Restart Stori: Force refresh data

⚡ Performance Issues

❌ App Slow or Laggy

  • Too Many Tracks: Limit to 8-16 for smooth performance
  • Too Many Effects: Each effect uses CPU
  • Bounce MIDI: Convert to audio to save CPU
  • Close Other Apps: Free system resources
  • Check Activity Monitor: Look for memory/CPU hogs
  • Restart Mac: Clear system caches

❌ High CPU Usage

  • Check CPU Meter: Toolbar shows current load
  • Bypass Effects: Disable effects temporarily
  • Increase Buffer: 256 or 512 samples
  • Reduce Track Count: Fewer simultaneous tracks
  • Close Background: Quit Safari, Chrome, etc.
  • Sample Rate: Use 44.1kHz not 96kHz

❌ App Crashes

  • Update macOS: Ensure latest OS version
  • Update Stori: Check for app updates
  • Check RAM: 16GB recommended minimum
  • Disk Space: Need 10GB+ free
  • Corrupted Project: Try opening different project
  • Report Issue: Help menu → Report Issue

❌ Memory Issues

  • Close Projects: Open fewer projects simultaneously
  • Clear Cache: Delete temp files
  • Quit Services: Stop AI services when not needed
  • Compress Audio: Use lower sample rates
  • Monitor RAM: Activity Monitor → Memory tab
  • Upgrade RAM: Consider 32GB for heavy projects

🎹 MIDI & Instrument Issues

❌ Virtual Keyboard Not Working

  • Track Selected? Click MIDI track first
  • Instrument Assigned? Choose from Library
  • Not in Text Field: Press Escape to exit text input
  • Volume Up: Check track and master faders
  • Synth Panel: Try opening Synthesizer (⌘⌥I)

❌ Piano Roll Won't Open

  • Select MIDI Region: Click MIDI region first
  • Right Track Type: Only works on MIDI tracks
  • Shortcut: Try ⌘⌥P
  • MIDI Menu: MIDI → Open Piano Roll
  • Restart Stori: If still not opening

❌ Instrument Won't Play

  • Instrument Loaded? Check Library panel assignment
  • SoundFont Available? Verify SoundFont installed
  • Track Armed? Try disarming and re-arming
  • MIDI Data Present? Notes visible in Piano Roll?
  • Synth On? Check synth panel enabled

❌ Step Sequencer Silent

  • Steps Active? Click pads to activate them
  • Transport Playing? Press Space to start
  • Volume: Check sequencer master volume
  • Drum Kit: Verify drum samples loaded
  • Export First: Sequencer for editing, export to hear in context

📁 Project & File Issues

❌ Project Won't Open

  • File Corrupted: Try backup copy
  • Permissions: Check file permissions
  • Wrong Version: Project from newer Stori version?
  • Bundle Incomplete: Missing audio files?
  • Move to Desktop: Try opening from simpler path
  • Create New: Import audio into fresh project

❌ Can't Save Project

  • Disk Full: Check available space
  • Permissions: Folder write permissions?
  • Read-Only: Project file locked?
  • Save As: Try saving to different location
  • Quit Apps: Close other apps using files
  • File Name: Avoid special characters

❌ Missing Audio Files

  • Project Bundle: All files in .stori folder?
  • Moved Project: Keep bundle together
  • Relink Files: Right-click region → Relink
  • Check Trash: Audio files deleted?
  • Backup: Restore from Time Machine

❌ Export Fails

  • Disk Space: Need space for export file
  • Permissions: Can write to destination?
  • File Name: Use valid filename
  • Format Support: WAV fully supported
  • Sample Rate: Match project settings
  • Try Desktop: Export to Desktop first

📊 Gathering System Information

When reporting issues, include this information:

  • • macOS Version: → About This Mac
  • • Stori Version: Shown in title bar and About window
  • • Mac Model: M1, M2, M3, M4 - About This Mac → Chip
  • • RAM Amount: About This Mac → Memory
  • • Available Storage: → About This Mac → Storage
  • • Service Status: Screenshot from ⌘⇧D diagnostics
  • • Error Messages: Copy exact text from alerts
  • • Console Logs: Console.app → search "Stori"