🎹 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

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

Quick Start

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.

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

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:

// 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:

// 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:

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: [email protected]
• 🐛 Issues: GitHub Issues
• 📖 Docs: Full Documentation