Minecraft Sound Effects Browser

A simple, fast, and beautiful web application for searching, playing, and favoriting Minecraft sound effects across multiple game versions.

Features

• Version Selector: Browse sounds from Minecraft 1.19, 1.20, 1.21, and 1.21.11
• Smart Fuzzy Search: Find sounds with partial matches and typo tolerance
• Category Filters: Filter by sound categories (ambient, block, entity, music, etc.)
• Favorites System: Save your favorite sounds with localStorage persistence
• Audio Playback: Play .ogg sound files directly in the browser
• Export/Import: Share your favorites with JSON export/import
• Responsive Design: Works seamlessly on desktop and mobile devices
• Clean UI: Rounded buttons with smooth shadow animations

Tech Stack

• Pure Vanilla JavaScript - No build tools required
• HTML5 & CSS3 - Modern, semantic markup
• Fuse.js - Fuzzy search library (via CDN)
• mcasset.cloud API - Minecraft assets CDN

File Structure

minecraftsfx/
├── index.html              # Main HTML entry point
├── css/
│   └── styles.css          # All styling
├── js/
│   ├── config.js           # Configuration constants
│   ├── soundManager.js     # Data fetching and audio playback
│   ├── searchEngine.js     # Fuzzy search with Fuse.js
│   ├── filterManager.js    # Category filtering logic
│   ├── favoritesManager.js # localStorage favorites system
│   ├── uiController.js     # UI rendering and updates
│   └── app.js              # Main application orchestrator
└── README.md               # This file

Local Development

Prerequisites

• A modern web browser (Chrome, Firefox, Edge, Safari)
• A local web server (optional but recommended)

Running Locally

Option 1: Simple HTTP Server (Recommended)

Using Python:

# Python 3
python -m http.server 8000

# Python 2
python -m SimpleHTTPServer 8000

Using Node.js:

npx serve

Then open your browser to http://localhost:8000

Option 2: Direct File Access

You can also open index.html directly in your browser, but some browsers may have CORS restrictions for local files.

Deployment to Cloudflare Pages

Prerequisites

• A GitHub account
• A Cloudflare account

Deployment Steps

1. Create a GitHub Repository

   git init
   git add .
   git commit -m "Initial commit: Minecraft Sound Effects Browser"
   git branch -M main
   git remote add origin <your-repo-url>
   git push -u origin main

2. Connect to Cloudflare Pages

   • Log in to Cloudflare Dashboard
   • Go to "Pages" in the sidebar
   • Click "Create a project"
   • Click "Connect to Git"
   • Select your GitHub repository

3. Configure Build Settings

   • Framework preset: None
   • Build command: (leave empty)
   • Build output directory: /
   • Root directory: /

4. Deploy

   • Click "Save and Deploy"
   • Your site will be live at https://<your-project>.pages.dev

Automatic Deployments

Cloudflare Pages will automatically deploy your site whenever you push to the main branch.

Browser Compatibility

• Chrome/Edge: Fully supported ✅
• Firefox: Fully supported ✅
• Safari: Fully supported ✅ (macOS 10.15+, iOS 13+)
• Opera: Fully supported ✅

Requirements

• JavaScript enabled
• localStorage support (for favorites)
• HTML5 Audio support (.ogg files)

API Usage

This application uses the mcasset.cloud CDN to fetch Minecraft sound data:

• Sounds Index: https://assets.mcasset.cloud/<version>/assets/minecraft/sounds.json
• Sound Files: https://assets.mcasset.cloud/<version>/assets/minecraft/sounds/<path>.ogg

Example:

https://assets.mcasset.cloud/1.21.11/assets/minecraft/sounds/ambient/cave/cave1.ogg

Features Overview

Search

• Fuzzy matching: Handles typos and partial matches
• Multi-field search: Searches sound keys, categories, and subtitles
• Debounced input: Optimized for performance (300ms delay)

Category Filters

• Multi-select: Select multiple categories at once
• Dynamic badges: Shows category icons and names
• Count display: See how many sounds per category

Favorites

• Persistent storage: Saved in browser localStorage
• Per-version: Each Minecraft version has separate favorites
• Export as JSON: Download your favorites
• Import from JSON: Share favorites with others
• Show only favorites: Filter view to favorites only

Audio Playback

• Single audio element: Optimized performance
• Auto-stop: Previous sound stops when new one plays
• Volume control: Respects Minecraft's sound volume metadata
• Visual feedback: Playing button shows pause icon

Configuration

Edit js/config.js to customize:

const CONFIG = {
    VERSIONS: ['1.21.11', '1.21', '1.20', '1.19'], // Available versions
    DEFAULT_VERSION: '1.21.11',                     // Default on load
    SEARCH_DEBOUNCE: 300,                           // Search delay (ms)
    TOAST_DURATION: 3000,                           // Notification duration (ms)
    MAX_RETRIES: 3,                                 // API retry attempts
    // ... more options
};

Troubleshooting

Sounds Not Loading

• Check browser console for errors
• Verify network connection
• Try a different Minecraft version
• Check if mcasset.cloud is accessible

Audio Not Playing

• Ensure browser supports .ogg audio
• Check browser autoplay policies
• Verify volume is not muted
• Try clicking play button again

Favorites Not Saving

• Check if localStorage is enabled
• Verify browser is not in private/incognito mode
• Check browser storage quota

Performance Tips

• Large datasets: Filtering helps reduce render time
• Search optimization: Debouncing prevents excessive re-renders
• Memory usage: Clear favorites periodically if needed

Future Enhancements

Possible features to add:

• Sound waveform visualization
• Playlist creation
• Sound comparison tool
• Download sounds locally
• Share sound links
• Dark mode toggle
• Custom category groups

Contributing

Feel free to fork this project and submit pull requests for improvements!

License

This project is open source and available for personal and commercial use.

Credits

• Minecraft sounds: © Mojang Studios
• Asset CDN: mcasset.cloud
• Fuzzy search: Fuse.js

Support

For issues or questions:

• Check browser console for errors
• Verify mcasset.cloud API is accessible
• Ensure JavaScript is enabled

---

Enjoy exploring Minecraft sounds! 🎵🎮