Sound Alerts

Two-Face can play sounds when specific text patterns match, providing audio alerts for important events.

Sound Basics

Add sounds to highlight patterns:

[[highlights]]
name = "whisper_alert"
pattern = "whispers to you"
fg = "#00FFFF"
sound = "~/.two-face/sounds/whisper.wav"

Supported Formats

Format	Extension	Notes
WAV	`.wav`	Best compatibility
MP3	`.mp3`	Requires codec
OGG	`.ogg`	Good compression

WAV is recommended for reliable playback.

Sound Configuration

Basic Sound

[[highlights]]
name = "my_alert"
pattern = "important event"
sound = "/path/to/sound.wav"

Volume Control

[[highlights]]
name = "quiet_alert"
pattern = "minor event"
sound = "/path/to/sound.wav"
volume = 0.5    # 0.0 to 1.0

Sound-Only (No Visual)

[[highlights]]
name = "audio_only"
pattern = "background event"
sound = "/path/to/sound.wav"
# No fg/bg colors - visual unchanged

Sound File Management

Directory Structure

~/.two-face/
└── sounds/
    ├── whisper.wav
    ├── attack.wav
    ├── death.wav
    ├── loot.wav
    └── custom/
        └── my_sounds.wav

Creating the Sounds Directory

mkdir -p ~/.two-face/sounds

Sound Sources

System sounds - Copy from OS sound themes
Online libraries - freesound.org, soundsnap.com
Create your own - Record with Audacity
Game packs - MUD sound packs

Common Alert Sounds

Combat Alerts

# Being attacked
[[highlights]]
name = "attack_received"
pattern = "(strikes|hits|bites|claws) you"
fg = "#FF4444"
sound = "~/.two-face/sounds/hit.wav"

# Near death
[[highlights]]
name = "low_health"
pattern = "You feel weak"
fg = "#FF0000"
bg = "#400000"
sound = "~/.two-face/sounds/warning.wav"
volume = 1.0

# Death
[[highlights]]
name = "death"
pattern = "You have died"
fg = "#FFFFFF"
bg = "#FF0000"
sound = "~/.two-face/sounds/death.wav"

# Whispers
[[highlights]]
name = "whisper"
pattern = "whispers,"
fg = "#00FFFF"
sound = "~/.two-face/sounds/whisper.wav"
volume = 0.7

# Your name mentioned
[[highlights]]
name = "name_mention"
pattern = "\\bYourCharacter\\b"
fg = "#FFFF00"
sound = "~/.two-face/sounds/mention.wav"

# Group invite
[[highlights]]
name = "group_invite"
pattern = "invites you to join"
fg = "#00FF00"
sound = "~/.two-face/sounds/invite.wav"

Loot Alerts

# Treasure found
[[highlights]]
name = "treasure"
pattern = "(?i)(gold|gems|treasure|chest)"
fg = "#FFD700"
sound = "~/.two-face/sounds/loot.wav"
volume = 0.5

# Rare item
[[highlights]]
name = "rare_item"
pattern = "(?i)(legendary|artifact|ancient)"
fg = "#FF00FF"
sound = "~/.two-face/sounds/rare.wav"

Status Alerts

# Stunned
[[highlights]]
name = "stunned"
pattern = "You are stunned"
fg = "#FFFF00"
sound = "~/.two-face/sounds/stun.wav"

# Poisoned
[[highlights]]
name = "poisoned"
pattern = "(?i)poison|venom"
fg = "#00FF00"
sound = "~/.two-face/sounds/poison.wav"

Global Sound Settings

In config.toml

[sound]
enabled = true           # Master switch
volume = 0.8             # Master volume (0.0-1.0)
concurrent_limit = 3     # Max simultaneous sounds

Disable All Sounds

[sound]
enabled = false

Sound Priority

When multiple patterns match:

[[highlights]]
name = "critical_alert"
pattern = "critical"
sound = "~/.two-face/sounds/critical.wav"
priority = 100          # Plays first

[[highlights]]
name = "minor_alert"
pattern = "hit"
sound = "~/.two-face/sounds/hit.wav"
priority = 50           # May be skipped if concurrent_limit reached

Rate Limiting

Prevent sound spam:

[[highlights]]
name = "combat_sound"
pattern = "You attack"
sound = "~/.two-face/sounds/attack.wav"
sound_cooldown = 500    # Milliseconds between plays

Platform Notes

Windows

WAV files play natively
No additional dependencies needed

Linux

Requires audio system:

# PulseAudio (most distros)
pactl list short sinks

# ALSA
aplay -l

macOS

WAV files play natively
Uses Core Audio

Troubleshooting

No Sound

Check [sound] enabled = true
Verify file path is correct
Test file with system player
Check volume settings

Delayed Sound

Use WAV instead of MP3
Reduce file size
Check system audio latency

Wrong Sound

Check pattern matching correctly
Verify highlight priority
Check for pattern conflicts

Creating Custom Sounds

Using Audacity

Open Audacity
Record or import audio
Trim to desired length (0.5-2 seconds recommended)
Export as WAV (16-bit PCM)
Save to ~/.two-face/sounds/

Sound Guidelines

Duration: 0.5-2 seconds
Format: WAV 16-bit PCM
Sample rate: 44100 Hz
Channels: Mono or Stereo
File size: Keep under 500KB

Two-Face Documentation