Captain Audio

Replace Valheim's music, ambient sounds, and sound effects with custom audio files embedded directly in the mod DLL.

Transform your Valheim experience with 64MB of custom music covering all biomes, bosses, time-based themes, and more. Captain Audio provides a complete audio replacement system with real-time controls and easy customization.

📖 About This Mod

Captain Audio is an enhanced and extended version of aedenthornCustomAudio, adding:

• 44 high-quality music tracks embedded directly in the DLL (64MB total)
• Pre-configured music for all biomes, bosses, and activities
• Ready to use out-of-the-box - no additional setup required
• Full compatibility with the original CustomAudio external file system

This mod builds upon aedenthornCustomAudio's flexible audio replacement framework while providing a complete curated soundtrack experience.

✨ Features

🎵 Music Replacement

• 44 embedded audio files covering:
  • 🐗 Boss battles (Eikthyr, Elder, Bonemass, Moder, Yagluth, The Queen)
  • 🌲 All biomes (Meadows, Black Forest, Swamp, Mountains, Plains, Mistlands, Ashlands)
  • 🌅 Time-based themes (Morning, Evening)
  • 🏠 Activities (Home, Sailing, Menu)
  • 🏰 Dungeons (Forest Crypt, Frost Caves)

🌊 Ambient Sound Replacement

• Environment sounds for each biome
• Ocean and wind sounds with special handling
• Day/night ambient variations

🔊 Sound Effects (SFX) Replacement

• Portal sounds
• Fireplace/torch sounds (5 types: ground torch, wall torch, bonfire, etc.)
• Customizable object sounds

⚙️ Real-time Controls

• Console commands for instant audio control
• Config file for persistent settings
• Volume controls that apply immediately
• Reset functionality to restore vanilla audio

🎵 Included Music Inventory

This mod includes 44 embedded audio files (64MB total) covering:

Biomes (23 tracks)

• Meadows: 3 tracks
• Black Forest: 3 tracks
• Swamp: 3 tracks + 1 rainy day variant
• Mountains: 3 tracks
• Plains: 3 tracks
• Mistlands: 3 tracks
• Ashlands: 2 tracks
• Forest Crypt (dungeon): 2 tracks
• Frost Caves (dungeon): 1 track

Boss Battles (10 tracks)

• Eikthyr: 1 track
• The Elder: 2 tracks
• Bonemass: 1 track
• Moder: 1 track
• Yagluth: 2 tracks
• The Queen: 1 track

Time & Activities (11 tracks)

• Morning: 2 tracks
• Evening: 1 track
• Home: 3 tracks
• Sailing: 3 tracks
• Menu: 1 track

📦 Installation

Method 1: r2modman (Recommended)

1. Install r2modman if you haven't already: r2modman Download
2. Select Valheim as your game
3. Search for "CaptainAudio" in the mod browser
4. Click "Download" and let r2modman handle everything
5. Launch the game through r2modman

Method 2: Manual Installation

1. Install BepInEx if not already installed: BepInExPack Valheim
2. Download CaptainAudio.dll from this mod page
3. Navigate to BepInEx/plugins/ folder
4. Create folder CaptainAudio (if it doesn't exist)
5. Copy CaptainAudio.dll into the folder
6. Launch Valheim

Installation Path:

Valheim/
└── BepInEx/
    └── plugins/
        └── CaptainAudio/
            └── CaptainAudio.dll

🎮 Usage

Console Commands

Press F5 in-game to open the console, then use these commands:

Example:

F5 (open console)
> captainaudio music
Current Music: Meadows_Morning_01.ogg
Biome: Meadows
Time: Morning
Volume: 0.6

Configuration File

After first launch, edit the config file at:

BepInEx/config/captain.CaptainAudio.cfg

Available Settings:

Example Config:

[General]
Enabled = true
MusicVolume = 0.6
AmbientVolume = 0.3
LocationVolumeMultiplier = 5.0

[Advanced]
LoadRetryCount = 3
LoadRetryDelay = 0.5
LoadTimeout = 15
EnableFallback = true

Note: Config changes apply immediately in-game. Use captainaudio reset to reload if needed.

🎨 Music Customization Guide

Audio File Organization

Captain Audio automatically matches audio files based on folder and file names:

asset/Resources/
├── Music/
│   ├── Meadow/               ← Meadows biome music
│   │   ├── song1.ogg
│   │   └── song2.ogg
│   ├── BlackForest/          ← Black Forest music
│   ├── Boss_Eikthyr/         ← Eikthyr boss battle
│   ├── Morning/              ← Morning theme (all biomes)
│   └── Evening/              ← Evening theme
├── Ambient/
│   └── ocean_waves.wav
└── SFX/
    └── portal_sound.mp3

Naming Conventions

Music Files:

• Folder names should match game locations: Meadow, BlackForest, Swamp, Mountain, Plain
• Boss music: Boss_Eikthyr, Boss_TheElder, Boss_Bonemass, Boss_Moder, Boss_Yagluth, Boss_TheQueen
• Time-based: Morning, Evening
• Special: Home, Menu, Sailing

Supported Audio Formats:

• .ogg - Recommended (Vorbis compression, smaller file size)
• .wav - Uncompressed (high quality, larger files)
• .mp3 - MPEG compression (limited support)

Adding Your Own Music

Method 1: External Files (✅ Recommended)

1. Navigate to: BepInEx/plugins/CaptainAudio/ folder (create if it doesn't exist)
2. Create folders:

   BepInEx/plugins/CaptainAudio/
   ├── Music/       # Your custom music files
   ├── Ambient/     # Custom ambient sounds
   └── SFX/         # Custom sound effects
   

3. Add your audio files (.ogg, .wav, .mp3)
4. Organize by folders:
   • Root level: Individual tracks (e.g., Music/custom_song.ogg)
   • Subfolders: Biome/boss-specific music (e.g., Music/Meadows/meadow1.ogg, Music/Boss_Eikthyr/boss_track.ogg)
5. Restart Valheim to load new music

Supported Formats:

• .ogg - Recommended (Vorbis compression, best compatibility)
• .wav - Uncompressed (high quality, larger files)
• .mp3 - MPEG compression (limited support)

Note: Game restart required to detect new files. Files added during gameplay are not automatically loaded.

How Folder Matching Works

Captain Audio uses a 3-tier matching system:

1. Exact Folder Name (Priority 1)

   • Music/Meadows/ → Meadows biome music
   • Music/Boss_Eikthyr/ → Eikthyr boss battle music

2. Mapping Rules (Priority 2)

   • Music/Meadow/ → Also works for Meadows (mapped: "meadow" → "meadows")
   • Music/Forest/ → Black Forest music (mapped: "forest" → "blackforest")
   • Music/Menu/ or Music/MainMenu/ → Menu music (multiple aliases)

3. Individual Clip Replacement (Fallback)

   • Root-level files replace specific clips by filename

Recommended Folder Names:

• Biomes: Meadows, BlackForest, Swamp, Mountain, Plain, Mistland, Ashland
• Bosses: Boss_Eikthyr, Boss_TheElder, Boss_Bonemass, Boss_Moder, Boss_Yagluth, Boss_TheQueen
• Time/Activities: Morning, Evening, Home, Sailing, Menu
• Dungeons: forestcrypt, frostcaves

Multiple Files Per Folder: Each folder can contain multiple tracks. The game will randomly select from available tracks.

Example Structure:

BepInEx/plugins/CaptainAudio/Music/
├── Meadows/
│   ├── peaceful1.ogg
│   ├── peaceful2.ogg
│   └── peaceful3.ogg   # 3 tracks → random selection
├── Boss_Eikthyr/
│   └── epic_battle.ogg  # 1 track
└── Mountain/
    ├── mountain_theme1.ogg
    └── mountain_theme2.ogg  # 2 tracks → random selection

Method 2: Rebuild from Source (Advanced)

1. Clone/download the source code
2. Add your .ogg or .wav files to asset/Resources/Music/[Folder]/
3. Rebuild the project with dotnet build -c Release
4. The audio files will be embedded in the DLL

🔧 Troubleshooting

Music Not Playing

1. Check console (F5) for error messages
2. Verify BepInEx is installed correctly
3. Try captainaudio reset command
4. Check config file: Enabled = true, MusicVolume > 0.0

Volume Too Low/High

• Adjust MusicVolume and AmbientVolume in config file
• Use captainaudio reset to apply changes
• For location music, adjust LocationVolumeMultiplier

Audio Cuts Out or Stutters

• Check LoadRetryCount and LoadTimeout in Advanced config
• Ensure sufficient disk space
• Try reducing LocationVolumeMultiplier if location music overlaps

Config File Not Found

• Launch the game once to generate the config file
• Location: BepInEx/config/captain.CaptainAudio.cfg
• Default values will be created automatically

📋 Technical Details

• Framework: .NET Standard 2.1
• BepInEx Version: 5.4.2200+
• Total Audio: 64MB embedded (44 files)
• Audio Formats: OGG (primary), MP3, WAV
• Harmony Patches: 10 patches for comprehensive audio replacement
• Performance: Parallel loading, reflection caching, retry logic

🌐 Compatibility

• ✅ Singleplayer: Fully supported
• ✅ Multiplayer: Client-side only (other players won't hear your music)
• ✅ Dedicated Servers: No server-side installation needed
• ✅ Other Mods: Compatible with most mods (no known conflicts)

🤝 Support & Feedback

• Email: Send bug reports or suggestions to [email protected]
• Issues: Report bugs or request features on GitHub Issues
• Discord: Join the Valheim modding community
• Updates: Check Thunderstore for new versions

📝 Credits

• Mod Author: [Your Name]
• Based on: aedenthornCustomAudio by aedenthorn
• BepInEx: BepInEx team
• Harmony: pardeike
• Valheim: Iron Gate Studio

📄 License

This mod is provided as-is for personal use. Please respect the original audio creators' rights when using custom audio files.

Enjoy your personalized Valheim soundtrack! 🎵