~/.config/ttyverse/
├── ttyverse_rc          # Main configuration file
├── oauth_credentials    # OAuth tokens (keep secure!)
└── dm_seen_status       # Direct message tracking

~/.local/share/ttyverse/
├── extensions/          # Extension scripts
│   ├── soundpack.pl     # Sound notifications
│   ├── tts.pl          # Text-to-speech
│   └── libnotify.pl    # Desktop notifications
└── sounds/             # Sound notification files
    └── default/        # Default sound pack
        ├── default.ogg
        ├── mention.ogg
        ├── dm.ogg
        └── ...

Main Configuration File

ttyverse_rc Format

The main config file (~/.config/ttyverse/ttyverse_rc) uses a simple key=value format:

# TTYverse Configuration File
# Generated by TTYverse setup

# Server and authentication
apibase=https://your-instance.com/api/v1
tokenkey=your_oauth_token_here

# Display and behavior settings  
effpause=120
verbose=1
readline=1

# Browser settings
gui_browser=firefox
cli_browser=w3m

# Extension settings
extension_notify=default,mention,dm

Key Configuration Options

Core Settings

apibase - Your fediverse server's API base URL
tokenkey - OAuth authentication token (keep private!)
effpause - Timeline refresh interval in seconds (default: 120)
verbose - Enable verbose output (0/1)
readline - Enable advanced readline support (0/1)

Browser Configuration

gui_browser - Preferred GUI browser (firefox, chrome, etc.)
cli_browser - Preferred CLI browser (w3m, elinks, lynx)

Timeline Settings

timeline_count - Number of posts to fetch (default: 30)
timeline_cache - Maximum cached posts (default: 200)

Notification Settings

extension_notify - Comma-separated list of notification types
sound_enabled - Enable sound notifications (0/1)

Browser Configuration

TTYverse automatically detects your environment and chooses appropriate browsers:

GUI Environment (DISPLAY set)

Uses gui_browser setting if configured
Falls back to xdg-open
Tries common browsers: firefox, chrome, chromium

CLI Environment (no DISPLAY)

Uses cli_browser setting if configured
Tries CLI browsers: w3m, elinks, lynx

Manual Configuration

# Set browsers in TTYverse
/set gui_browser firefox
/set cli_browser w3m

# Or edit config file directly
echo "gui_browser=firefox" >> ~/.config/ttyverse/ttyverse_rc
echo "cli_browser=w3m" >> ~/.config/ttyverse/ttyverse_rc

Sound Configuration

Sound Pack Structure

~/.local/share/ttyverse/sounds/default/
├── default.ogg      # General notifications
├── mention.ogg      # When mentioned
├── dm.ogg           # Direct messages  
├── me.ogg          # Your own posts
├── search.ogg       # Search results
├── follow.ogg       # New followers
├── boost.ogg        # When boosted
├── favourite.ogg    # When favorited
├── poll.ogg         # Poll notifications
├── edit.ogg         # Edited posts
└── announcement.ogg # Server announcements

Sound Types

TTYverse supports these notification types:

default - General notifications
mention - When someone mentions you
dm - Direct messages
me - Your own posts appearing in timeline
search - Search results
follow - New followers
boost - When someone boosts your post
favourite - When someone favorites your post
poll - Poll-related notifications
edit - When posts are edited
announcement - Server announcements

Custom Sound Packs

Create custom sound packs by:

Creating directory: ~/.local/share/ttyverse/sounds/mysounds/
Adding OGG files for each notification type
Activating: /set sound_pack mysounds

Extension Configuration

Available Extensions

soundpack.pl - Sound notifications
tts.pl - Text-to-speech support
libnotify.pl - Desktop notifications
timestamp.pl - Enhanced timestamp display

Extension Management

# List loaded extensions
ls ~/.local/share/ttyverse/extensions/

# Check loaded extensions in TTYverse
/verbose
# Shows: ** loaded extensions: soundpack, tts

Extension Settings

Extensions can be configured through the main config file:

# Sound pack settings
sound_enabled=1
sound_pack=default

# TTS settings  
tts_enabled=1
tts_voice=espeak

# Notification settings
notify_desktop=1
notify_sound=1

Runtime Configuration

Setting Options During Session

# View current setting
/get effpause

# Change setting
/set effpause 60

# View all settings
/verbose

Common Runtime Changes

# Adjust refresh rate
/set effpause 300        # 5 minutes

# Change browser  
/set gui_browser chrome

# Toggle verbose output
/verbose

# Toggle debug output
/debug

OAuth Configuration

OAuth Credential Files

TTYverse stores OAuth credentials securely in:

oauth_credentials - Token and server information
ttyverse_rc - Main config with tokenkey

Re-authenticating

If OAuth fails:

# Remove old credentials
rm ~/.config/ttyverse/oauth_credentials
rm ~/.config/ttyverse/ttyverse_rc

# Restart TTYverse for fresh OAuth setup
./ttyverse.pl

Multiple Accounts

TTYverse supports multiple accounts through keyfiles:

# Use different keyfile for second account
./ttyverse.pl -keyfile work_account

# This creates ~/.config/ttyverse/work_account_rc

Performance Tuning

Memory Usage

# Reduce cached posts for lower memory usage
timeline_cache=100

# Reduce fetch count for slower connections
timeline_count=15

Network Settings

# Increase refresh interval for slower connections
effpause=300

# Reduce concurrent connections
max_connections=2

Accessibility Settings

# Force screen reader compatibility
readline=1
verbose=1

# Enable all accessibility features
sound_enabled=1
alt_text_required=1

Backup and Migration

Backing Up Configuration

# Backup entire config directory
tar -czf ttyverse-config-backup.tar.gz ~/.config/ttyverse/

# Backup just the main config
cp ~/.config/ttyverse/ttyverse_rc ~/ttyverse_rc.backup

Migration Between Systems

Copy config directory to new system
Update file paths if needed
Re-authenticate if moving between different systems
Install required dependencies (curl, perl modules)

Troubleshooting Configuration

Common Issues

# Config file not found
ls -la ~/.config/ttyverse/
# Create directory if missing: mkdir -p ~/.config/ttyverse/

# Permission issues
chmod 700 ~/.config/ttyverse/
chmod 600 ~/.config/ttyverse/*

# OAuth token issues
# Check if token exists and is not empty
cat ~/.config/ttyverse/ttyverse_rc | grep tokenkey

Debug Configuration Loading

# Run with verbose output to see config loading
./ttyverse.pl -verbose

# Check which config file is being used
./ttyverse.pl -debug

Reset to Defaults

# Remove all configuration (will prompt for fresh setup)
rm -rf ~/.config/ttyverse/
rm -rf ~/.local/share/ttyverse/
rm -rf ~/.cache/ttyverse/

# Restart TTYverse
./ttyverse.pl

See also: Getting Started | Extensions | Troubleshooting

Last updated: 2025-07-28