113 lines
3.7 KiB
Markdown
113 lines
3.7 KiB
Markdown
# Audio Directory Scanning Feature
|
|
|
|
## Overview
|
|
The directory scanning feature automatically discovers audio files that are already present in your app's audio directory structure and adds them to your audio library.
|
|
|
|
## How It Works
|
|
|
|
### Automatic Scanning
|
|
- **On Startup**: The app automatically scans for audio files when it launches (desktop mode only)
|
|
- **Manual Scanning**: Use the "🔍 Scan Directories" button in the "Manage Audio" menu
|
|
|
|
### Scanned Directories
|
|
The scanner looks for audio files in these directories:
|
|
```
|
|
audio/
|
|
├── background/
|
|
└── ambient/
|
|
```
|
|
|
|
### Supported Audio Formats
|
|
- **MP3** (most common)
|
|
- **WAV** (high quality)
|
|
- **OGG** (open source)
|
|
- **M4A** (Apple format)
|
|
- **AAC** (compressed)
|
|
- **FLAC** (lossless)
|
|
|
|
## Using Directory Scanning
|
|
|
|
### Desktop Mode (Recommended)
|
|
1. **Place Files**: Copy your audio files into the appropriate audio subdirectories
|
|
2. **Scan**: Click "🔍 Scan Directories" in the "Manage Audio" menu
|
|
3. **Auto-Use**: Scanned files are automatically added to your library and enabled
|
|
|
|
### File Organization
|
|
- **Background Music** → `audio/background/`
|
|
- **Ambient Sounds** → `audio/ambient/`
|
|
|
|
## Category Mapping
|
|
Due to the simplified audio system, all scanned files are categorized as follows:
|
|
- Files from `audio/ambient/` → **Ambient** category
|
|
- Files from `audio/background/` → **Background** category
|
|
|
|
## Benefits
|
|
|
|
### Easy Bulk Import
|
|
- Add many files at once by copying them to directories
|
|
- No need to import files one-by-one through the UI
|
|
- Perfect for organizing large audio collections
|
|
|
|
### Automatic Discovery
|
|
- New files are found automatically on app restart
|
|
- Manual scan button for immediate discovery
|
|
- No configuration required
|
|
|
|
### File Management
|
|
- Files stay in organized directory structure
|
|
- Easy to add/remove files outside the app
|
|
- Clear organization by purpose/category
|
|
|
|
## Troubleshooting
|
|
|
|
### No Files Found
|
|
- **Check Directories**: Ensure audio files are in the correct subdirectories
|
|
- **File Formats**: Verify files are in supported formats (MP3, WAV, OGG, M4A, AAC, FLAC)
|
|
- **Permissions**: Make sure the app has read access to the audio directories
|
|
- **File Names**: Avoid special characters in file names
|
|
|
|
### Duplicate Files
|
|
- The scanner checks for existing files before adding
|
|
- Files already in your library won't be duplicated
|
|
- If you see duplicates, use the "🧹 Cleanup" button
|
|
|
|
### Web Mode Limitations
|
|
- Directory scanning only works in desktop mode (Electron)
|
|
- Web browsers can't access file system directories
|
|
- Use the Import buttons for manual file upload in web mode
|
|
|
|
## Tips
|
|
|
|
### Organizing Your Audio
|
|
1. **Create Themed Folders**: Group similar audio files together
|
|
2. **Descriptive Names**: Use clear, descriptive file names
|
|
3. **Test Files**: Place a few test files first, then scan to verify
|
|
|
|
### Performance
|
|
- Scanning is fast for hundreds of files
|
|
- Large files (>100MB) may take longer to process
|
|
- The app shows progress messages during scanning
|
|
|
|
### Backup Strategy
|
|
- Keep original files in the audio directories
|
|
- The app creates references, not copies
|
|
- Easy to backup/restore entire audio collection
|
|
|
|
## Integration
|
|
|
|
### With Dynamic Audio System
|
|
- Scanned files integrate seamlessly with the dynamic audio system
|
|
- All audio management features work with scanned files
|
|
- Enable/disable scanned files individually
|
|
|
|
### With Existing Audio
|
|
- Scanned files are added to existing audio library
|
|
- No conflicts with manually imported files
|
|
- Use both methods together for maximum flexibility
|
|
|
|
## Next Steps
|
|
|
|
1. **Organize Files**: Place your audio files in the appropriate directories
|
|
2. **Scan**: Use the "🔍 Scan Directories" button
|
|
3. **Test**: Try playing audio during a game session
|
|
4. **Manage**: Use the audio management UI to enable/disable specific files |