npm package: @gsuriya/keyboard-sound-profiles
Description: 11 high-quality keyboard sound profiles for web applications with TypeScript support
Author: gsuriya
Latest version: 1.1.0

# 🎹 Keyboard Sounds SDK

Professional mechanical keyboard sound profiles for React applications with Shopify Shop Minis support.

## Features

- 🎵 **10+ Premium Sound Profiles** - Holy Pandas, Cherry MX switches, Tealios, and more
- 🚀 **Optimized for Shopify** - Compatible with Shop Minis and Shopify ecosystem
- 📱 **iOS Compatible** - Automatic audio unlock and format detection
- 🎯 **TypeScript Support** - Full type definitions included
- 🔧 **Flexible Architecture** - CDN or local asset loading
- ⚡ **Performance Focused** - Lazy loading and efficient caching

## Installation

```bash
npm install @your-username/keyboard-sound-profiles
```

## Quick Start

```tsx
import { useKeyboardSound } from '@your-username/keyboard-sound-profiles';

function App() {
  const { 
    playSound, 
    initializeAudio, 
    audioInitialized, 
    setProfile,
    availableProfiles 
  } = useKeyboardSound('holy-pandas');

  const handleClick = () => {
    if (!audioInitialized) {
      initializeAudio();
    } else {
      playSound('a');
    }
  };

  return (
    <div>
      <button onClick={handleClick}>
        {audioInitialized ? 'Play Sound' : 'Initialize Audio'}
      </button>
      
      <select onChange={(e) => setProfile(e.target.value)}>
        {availableProfiles.map(profile => (
          <option key={profile.id} value={profile.id}>
            {profile.name}
          </option>
        ))}
      </select>
    </div>
  );
}
```

## Available Sound Profiles

| Profile | Type | Description |
|---------|------|-------------|
| `holy-pandas` | Multi-press Release | Tactile switches with distinct "thock" sound |
| `cherry-mx-blue` | Single Sprite | Classic clicky switches with audible click |
| `cherry-mx-brown` | Single Sprite | Tactile switches with bump but no click |
| `cherry-mx-red` | Single Sprite | Linear switches with smooth keystroke |
| `tealios` | Multi-press | Premium linear switches |
| `banana-split` | Multi-press | Smooth, deep tactile switches |
| `steelseries` | Multi-press | Mechanical gaming switches |
| And more... | | |

## API Reference

### `useKeyboardSound(profileId?, options?)`

Main React hook for keyboard sounds.

```tsx
const {
  playSound,           // (key: string) => Promise<void>
  setProfile,          // (profileId: string) => void
  currentProfile,      // SoundProfile | null
  audioInitialized,    // boolean
  initializeAudio,     // () => Promise<void>
  availableProfiles    // SoundProfile[]
} = useKeyboardSound('holy-pandas', {
  assetsUrl: 'https://your-cdn.com',  // Custom CDN URL
  volume: 0.8,                        // Audio volume (0-1)
  lazy: true,                         // Lazy load audio files
  iosUnlock: true                     // Auto unlock iOS audio
});
```

### Configuration Options

```tsx
interface KeyboardSoundOptions {
  assetsUrl?: string;    // Default: 'https://cdn.keyboard-sounds.dev'
  lazy?: boolean;        // Default: true
  volume?: number;       // Default: 0.8
  preload?: boolean;     // Default: false
  iosUnlock?: boolean;   // Default: true
}
```

## Shopify Shop Minis Integration

This package is optimized for Shopify Shop Minis:

```tsx
// shop-mini/src/App.tsx
import { useKeyboardSound } from '@your-username/keyboard-sound-profiles';

export default function ShopMini() {
  const { playSound, initializeAudio, audioInitialized } = useKeyboardSound();
  
  return (
    <div className="shop-mini">
      <button 
        onClick={() => audioInitialized ? playSound('click') : initializeAudio()}
        className="keyboard-button"
      >
        Test Keyboard Sound
      </button>
    </div>
  );
}
```

## CDN vs Local Assets

By default, audio files are loaded from our CDN for optimal performance:

```tsx
// CDN Loading (recommended)
useKeyboardSound('holy-pandas');  // Uses CDN automatically

// Local Assets
useKeyboardSound('holy-pandas', { 
  assetsUrl: '/audio'  // Load from your app's public folder
});
```

## TypeScript Support

Full TypeScript definitions included:

```tsx
import type { 
  SoundProfile, 
  KeyboardSoundOptions,
  UseKeyboardSoundReturn 
} from '@your-username/keyboard-sound-profiles';
```

## Browser Compatibility

- ✅ Chrome 80+
- ✅ Firefox 75+
- ✅ Safari 13.1+
- ✅ iOS Safari 13.4+
- ✅ Edge 80+

## License

MIT License - see LICENSE file for details.

## Contributing

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

## Support

- 📧 Email: support@keyboard-sounds.dev
- 🐛 Issues: [GitHub Issues](https://github.com/yourusername/keyboard-sounds-sdk/issues)
- 📖 Docs: [Full Documentation](https://keyboard-sounds.dev/docs)