📄 Complete README.md — Professional & User-Friendly

🔊 Faah On Fail

Build fail hua? FAAAAAH! 💥

A VS Code extension that plays a dramatic sound when your build fails, tests break, or errors appear. Never miss a failure again — even when you're not looking at the screen!

🎬 What Does It Do?

Ever run a build, switch to browsing memes, and forget to check if it passed? Not anymore!

Faah On Fail monitors your:

• ✅ Build tasks (npm run build, webpack, tsc, etc.)
• ✅ Test commands (npm test, jest, mocha, etc.)
• ✅ Terminal commands (any command with non-zero exit code)
• ✅ Compilation errors (TypeScript, ESLint, etc.)

When something fails → 🔊 FAAAAAH! (or your custom sound)

✨ Features

📦 Installation

Method 1: VS Code Marketplace (Recommended)

1. Open VS Code
2. Press Ctrl+Shift+X (Windows/Linux) or Cmd+Shift+X (Mac)
3. Search for "Faah On Fail"
4. Click Install
5. Done! Extension is now active 🎉

Method 2: Command Line

code --install-extension YOUR-PUBLISHER-ID.faah-on-fail

Method 3: VSIX File

1. Download the .vsix file from Releases
2. Open VS Code
3. Press Ctrl+Shift+P → Type: Extensions: Install from VSIX...
4. Select the downloaded .vsix file

🚀 Quick Start

Step 1: Verify Installation

After installation, you should see 🔊 FAAH in the bottom-right status bar.

┌─────────────────────────────────────────────────────────┐
│  VS Code                                                │
│                                                         │
│                                                         │
│                                                         │
├─────────────────────────────────────────────────────────┤
│  main ●  Ln 42, Col 15   UTF-8   LF   TypeScript  🔊 FAAH │
└─────────────────────────────────────────────────────────┘
                                                      ↑
                                              Click to toggle!

Step 2: Test the Sound

Press: Ctrl+Shift+P (or Cmd+Shift+P on Mac)
Type:  Faah On Fail: Test Current Sound
Press: Enter

🔊 You should hear the FAAH sound!

Step 3: Trigger a Real Failure

Open your terminal in VS Code and run:

# This will fail and trigger the sound
exit 1

Or if you have a project with npm:

# Add this to package.json scripts: "fail": "exit 1"
npm run fail

Step 4: Upload Your Own Sound (Optional)

Press: Ctrl+Shift+P
Type:  Faah On Fail: Upload Custom Sound File
Select: Any MP3, WAV, OGG, or AAC file from your computer

🎮 Commands

Access all commands via Ctrl+Shift+P (or Cmd+Shift+P on Mac):

⚙️ Settings

Customize the extension via File → Preferences → Settings and search for "Faah On Fail":

Default Error Messages

[
  "💥 FAAH! Build FAILED!",
  "🔥 Arre yaar! Error aa gaya!",
  "💀 Toot gaya code!",
  "😱 FAAAAAH! Fix karo!",
  "🤯 Kya kar diya bhai!"
]

You can customize these in settings!

🔊 Supported Audio Formats

Note: WAV files play the fastest. The extension can optionally convert other formats to WAV if FFmpeg is installed.

🖥️ Platform-Specific Notes

Windows

Works out of the box! Uses PowerShell for audio playback.

macOS

Works out of the box! Uses afplay (pre-installed on all Macs).

Linux

For WAV files: Uses aplay (usually pre-installed).

For MP3/OGG/other formats: Install one of these players:

# Option 1: mpv (Recommended)
sudo apt install mpv

# Option 2: FFmpeg (for ffplay)
sudo apt install ffmpeg

# Option 3: PulseAudio
sudo apt install pulseaudio-utils

🎯 Use Cases

1. Long Build Times

Start a 5-minute webpack build
Go make coffee ☕
Build fails?
→ FAAAAAH! 🔊 (you hear it from the kitchen)

2. Test-Driven Development

Write test → Run tests → Tests fail
→ FAAAAAH! 🔊
Fix code → Run tests → Tests pass
→ Silence (sweet success!)

3. CI/CD Local Testing

Run your CI pipeline locally
Go check Twitter
Pipeline fails?
→ FAAAAAH! 🔊

4. Learning to Code

Writing TypeScript for the first time
Make a type error
→ FAAAAAH! 🔊
Learn from mistakes faster!

🔧 Troubleshooting

Sound Not Playing?

1. Check if enabled: Look for 🔊 FAAH in status bar (not 🔇 FAAH)

2. Test the sound manually:

   Ctrl+Shift+P → "Faah On Fail: Test Current Sound"
   

3. Check system volume: Make sure your speakers aren't muted!

4. Windows users: PowerShell should be available (it's pre-installed)

5. Linux users: Install mpv for MP3 support:

   sudo apt install mpv
   

Sound Playing Too Often?

Increase the cooldown in settings:

{
  "faahOnFail.cooldownMs": 5000
}

Sound Playing on Every Keystroke?

This happens when diagnostic errors trigger rapidly. Increase the debounce delay:

{
  "faahOnFail.diagnosticDelay": 3000
}

Custom Sound Not Working?

1. Make sure the file path is correct
2. Try a different audio format (WAV works best)
3. Check file permissions

Want to Disable Temporarily?

Click 🔊 FAAH in the status bar → It will show 🔇 FAAH (disabled)

🎵 Custom Sound Ideas

Make your coding sessions fun with custom sounds!

Free sound effect websites:

• FreeSound.org
• ZapSplat
• Pixabay

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Development Setup

# Clone the repo
git clone https://github.com/YOUR-USERNAME/faah-on-fail.git
cd faah-on-fail

# Install dependencies
npm install

# Generate default sound
npm run generate-sound

# Compile
npm run compile

# Test in VS Code
# Press F5 to launch Extension Development Host

📝 Changelog

[1.0.0] - 2025-01-XX

Added

• 🔊 Sound alert on build/task failure
• 🔊 Sound alert on test failure
• 🔊 Sound alert on new compilation errors
• 🔊 Terminal exit code monitoring
• 🎵 Custom sound file upload (MP3/WAV/OGG/AAC)
• 🎵 Auto-generated default FAAH sound
• ⚡ Run Command feature with presets
• 🎛️ Configurable volume, cooldown, debounce
• 📊 Status bar toggle
• 🔔 Optional popup notifications
• 🎲 Random fun error messages
• 🔄 FFmpeg integration for audio conversion (optional)

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2025 Your Name

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software.

🙏 Acknowledgments

• Inspired by the frustration of missing failed builds
• Thanks to all the developers who suggested features
• Built with ❤️ and lots of FAAH sounds

📬 Support

• Issues: GitHub Issues
• Feature Requests: GitHub Discussions
• Email: your.email@example.com