# 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