Updated README.

README.md

@@ -115,12 +115,177 @@ yay -S python-plyer
 - Accessible names and descriptions for all controls
 - Thread expansion/collapse with audio feedback
 
+## Sound Pack Creation and Installation
+
+### Creating Custom Sound Packs
+
+Sound packs in Bifrost allow you to customize the audio feedback for different events. Each sound pack consists of a directory containing audio files and a configuration file.
+
+#### Sound Pack Structure
+
+A sound pack must contain:
+1. **pack.json** - Configuration file with metadata and sound mappings
+2. **Audio files** - WAV or OGG files for each sound event
+
+#### Required Sound Events
+
+Your sound pack should include audio files for these events:
+- `private_message` - Direct message received
+- `mention` - User mentioned in post
+- `boost` - Post boosted/reblogged
+- `reply` - Reply to user's post
+- `post_sent` - User successfully posted
+- `timeline_update` - New posts in timeline
+- `notification` - General notification
+- `startup` - Application started (optional)
+- `shutdown` - Application closing (optional)
+- `expand` - Thread expanded (optional)
+- `collapse` - Thread collapsed (optional)
+- `success` - General success feedback (optional)
+- `error` - Error occurred (optional)
+
+#### Creating pack.json
+
+Create a `pack.json` file with this format:
+
+```json
+{
+  "name": "My Custom Pack",
+  "description": "A description of your sound pack",
+  "author": "Your Name",
+  "version": "1.0",
+  "sounds": {
+    "private_message": "dm.wav",
+    "mention": "mention.ogg",
+    "boost": "boost.wav",
+    "reply": "reply.wav",
+    "post_sent": "sent.wav",
+    "timeline_update": "update.wav",
+    "notification": "notification.wav",
+    "startup": "startup.wav",
+    "shutdown": "shutdown.wav",
+    "expand": "expand.wav",
+    "collapse": "collapse.wav",
+    "success": "success.wav",
+    "error": "error.wav"
+  }
+}
+```
+
+#### Audio File Requirements
+
+- **Formats**: WAV or OGG Vorbis only
+- **Size**: Maximum 10MB per file
+- **Duration**: Keep sounds short (1-3 seconds recommended)
+- **Quality**: 44.1kHz, 16-bit recommended for WAV files
+
+#### Example Directory Structure
+
+```
+MyPack/
+├── pack.json
+├── dm.wav
+├── mention.ogg
+├── boost.wav
+├── reply.wav
+├── sent.wav
+├── update.wav
+├── notification.wav
+├── startup.wav
+├── shutdown.wav
+├── expand.wav
+├── collapse.wav
+├── success.wav
+└── error.wav
+```
+
+### Installing Sound Packs
+
+#### Method 1: Manual Installation
+
+1. Create your sound pack directory structure as shown above
+2. Copy the directory to `~/.local/share/bifrost/sounds/`
+3. Restart Bifrost or go to Settings → Audio to select the new pack
+
+#### Method 2: ZIP Installation
+
+1. **Create ZIP file correctly**: 
+   - Navigate to your sound pack directory
+   - Select ALL files (pack.json and audio files)
+   - Create a ZIP file containing just the files, NOT the folder
+   - **Important**: The ZIP should contain `pack.json` at the root, not `MyPack/pack.json`
+
+2. **Install via Soundpack Manager**:
+   - Open Bifrost
+   - Press **Ctrl+Alt+S** to open Soundpack Manager
+   - Click "Install from ZIP file"
+   - Select your ZIP file
+   - The soundpack will be validated and installed automatically
+
+#### Method 3: Repository Installation
+
+If you have access to a soundpack repository:
+
+1. Open Soundpack Manager (**Ctrl+Alt+S**)
+2. Browse available soundpacks from configured repositories  
+3. Click "Install" next to the desired soundpack
+4. The soundpack will download and install automatically
+
+### ZIP File Creation Tips
+
+**Correct ZIP structure:**
+```
+soundpack.zip
+├── pack.json
+├── dm.wav
+├── mention.ogg
+└── other_audio_files...
+```
+
+**Incorrect ZIP structure (will fail):**
+```
+soundpack.zip
+└── MyPack/
+    ├── pack.json
+    ├── dm.wav
+    └── other_files...
+```
+
+### Common Commands for ZIP Creation
+
+**Linux/macOS:**
+```bash
+cd MyPack
+zip -r ../MyPack.zip *
+```
+
+**Windows (PowerShell):**
+```powershell
+cd MyPack
+Compress-Archive -Path * -DestinationPath ..\MyPack.zip
+```
+
+### Troubleshooting
+
+- **"Invalid filename in archive"**: Ensure filenames only contain letters, numbers, dots, dashes, and underscores
+- **"No valid audio files found"**: Check that you have WAV or OGG files and they're properly formatted
+- **"Invalid pack.json format"**: Verify your JSON syntax and required fields (name, sounds)
+- **Installation fails**: Make sure you zipped the files themselves, not the containing folder
+
+### Sound Pack Security
+
+Bifrost's soundpack system includes security measures:
+- Maximum file sizes (10MB per file, 50MB total download)
+- File type validation (only WAV/OGG audio files allowed)
+- Path sanitization (prevents directory traversal attacks)  
+- Repository validation (HTTPS required for remote repositories)
+
 ## Contributing
 
 This is a vibe coding project where AI handles implementation. Human contributors can:
 - Test accessibility with different screen readers
 - Suggest features and improvements
-- Create new sound packs
+- Create new sound packs (see Sound Pack Creation section above)
 - Report bugs and usability issues
 
 ## License