GTA
/
training-academy
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases 2 Wiki Activity
training-academy/DIRECTORY_SCANNING.md

3.7 KiB
Raw Blame History

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