storm/ttyverse
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Presto, a wiki! Thanks Claud. Most information should be accurate, let me know if something is off.

Storm Dragon
2025-07-28 19:50:54 -04:00
parent c653211bb3
commit 8e18c502b7
11 changed files with 2861 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

369
Basic-Usage.md Normal file

@ -0,0 +1,369 @@
# Basic Usage
Essential workflows and everyday usage patterns for TTYverse. This guide assumes you've completed [Getting Started](Getting-Started) and have TTYverse configured.
## Daily Workflow
### Starting TTYverse
```bash
# Start TTYverse
./ttyverse.pl
# TTYverse loads and shows:
# - Current version and login status
# - Recent timeline posts
# - Direct messages (if any)
# - Ready prompt: TTYverse>
```
### Reading Your Timeline
When TTYverse starts, it automatically loads your home timeline:
```
a0> {,POST_ID} <username> (2h ago) via Web [Public]
Content of the post goes here with any links or hashtags
a1> {,POST_ID} <username> (1h ago) via TTYverse [Unlisted]
Another post with different visibility
```
**Understanding the format:**
- **a0**, **a1** - Menu codes for referencing posts
- **username** - Who posted it
- **(2h ago)** - How long ago it was posted
- **via Web** - What client was used
- **[Public]** - Visibility level
### Loading More Content
```bash
# See more posts from timeline
/again
# Refresh timeline for new posts
/refresh
# See posts from cache
/last 15
```
## Reading Different Timelines
### Home Timeline (Default)
Your personalized feed from accounts you follow:
```bash
/timeline # Show home timeline
```
### Local Timeline
Posts from your instance/server:
```bash
/timeline local # See what your community is posting
```
### Federated Timeline
Posts from across the fediverse:
```bash
/timeline federated # See the broader conversation
```
### Bookmarks
Posts you've saved:
```bash
/timeline bookmarks # Your saved posts
```
## Interacting with Posts
### Basic Interactions
```bash
# Like a post
/fav a3
# Share a post (boost/reblog)
/boost a3
# Save for later
/bookmark a3
# Reply to a post
/reply a3 Great point about accessibility!
```
### Opening Links
When posts contain URLs:
```bash
# Open the URL from post a3
/url a3
# TTYverse automatically detects your environment:
# - GUI environment: Opens in Firefox, Chrome, etc.
# - Terminal: Opens in w3m, elinks, or lynx
```
### Getting User Information
```bash
# Learn about a user
/whois storm@stormux.org
# Shows profile information, follower count, etc.
```
## Creating Content
### Simple Text Posts
```bash
# Create a public post
/post Just learned about TTYverse - loving the accessibility focus!
# TTYverse creates the post and shows confirmation
```
### Posts with Media
```bash
# Upload an image
/media ~/pictures/sunset.jpg
# TTYverse will prompt for:
# 1. Alt-text description (required for images)
# 2. Optional post message
```
**Alt-text example:**
```
Enter alt text for sunset.jpg: Orange and purple clouds over mountains during golden hour
Enter post message (optional): Beautiful evening hike in the local mountains
```
### Replying to Conversations
```bash
# Reply to someone's post
/reply a5 That's exactly what I was thinking! Have you tried the new media upload feature?
# Your reply appears in the conversation thread
```
## Managing Conversations
### Direct Messages
```bash
# Check for direct messages
/dms
# Shows recent DMs:
[DM da0][friend@instance.org] (1h ago)
Hey, saw your post about TTYverse - is it really that accessible?
# Reply to a DM
/reply da0 Yes! It's designed by a blind developer with accessibility as the top priority.
```
### Following Conversations
```bash
# Follow an interesting user
/follow @username@instance.com
# Their posts will appear in your home timeline
```
## Searching and Discovery
### Finding Content
```bash
# Search for hashtags
/search #accessibility
# Find users
/search storm@stormux.org
# Search post content
/search "command line fediverse"
```
### Exploring Communities
```bash
# See what your local instance is discussing
/timeline local
# Discover broader conversations
/timeline federated
# Find trending topics (if your server supports it)
/search #trending
```
## Voting in Polls
When you see a poll in your timeline, it appears with numbered options:
```
b3> {,POST_ID} <username> (30m ago) via Web [Public]
What's your favorite terminal editor?
Poll (ends in 2 days, 15 votes):
1. vim (8 votes - 53%)
2. emacs (4 votes - 27%)
3. nano (3 votes - 20%)
```
Vote using the menu code and option number:
```bash
# Vote for option 1 (vim)
/vote b3 1
# For multiple choice polls, vote for multiple options
/vote b3 1,3
```
## Managing Your Experience
### Adjusting Settings
```bash
# Change how often timeline refreshes (in seconds)
/set effpause 300 # Refresh every 5 minutes
# Set your preferred browsers
/set gui_browser firefox
/set cli_browser w3m
# Check current settings
/get effpause
```
### Getting Information
```bash
# See available commands
/help
# Check API rate limits
/rate
# See TTYverse version
/version
```
### Controlling Output
```bash
# Enable detailed output
/verbose
# Enable debug information (for troubleshooting)
/debug
```
## Sound Notifications
TTYverse includes audio feedback for different events:
- **New posts** - Gentle notification sound
- **Mentions** - Distinctive alert when someone mentions you
- **Direct messages** - Special sound for private messages
- **Your posts** - Confirmation when your posts appear
- **Boosts/favorites** - Feedback when others interact with your posts
Sound files are stored in `~/.local/share/ttyverse/sounds/default/`
## Common Workflows
### Morning Routine
```bash
# Start TTYverse and catch up
./ttyverse.pl # Shows recent timeline
/dms # Check direct messages
/timeline local # See community activity
```
### Active Participation
```bash
# Engage with interesting content
/fav a3 # Like interesting posts
/boost a5 # Share good content
/reply a7 Great insight! # Join conversations
/post Today I learned... # Share your thoughts
```
### Content Creation
```bash
# Share a photo with proper accessibility
/media ~/photo.jpg
# Alt-text: "Golden retriever playing in autumn leaves"
# Message: "Morning walk with the dog - beautiful fall colors!"
```
### Research and Discovery
```bash
# Explore topics
/search #photography # Find photography discussions
/timeline federated # See broader conversations
/search @expert # Find knowledgeable users
/follow @expert@domain # Follow interesting people
```
### End of Session
```bash
# Save interesting posts for later
/bookmark a3
/bookmark b7
# Exit cleanly
/quit
```
## Tips for Effective Usage
### Navigation Tips
1. **Use menu codes efficiently** - They're faster than scrolling
2. **Bookmark interesting posts** - Save them for later reference
3. **Follow local timeline** - Discover your community
4. **Use search regularly** - Find conversations on topics you care about
### Engagement Tips
1. **Always provide alt-text** - TTYverse enforces this for good reason
2. **Reply thoughtfully** - Add value to conversations
3. **Use appropriate visibility** - Consider who should see your posts
4. **Boost good content** - Help spread valuable information
### Accessibility Tips
1. **TTYverse is screen reader friendly** - All output is plain text
2. **Sound notifications help** - Audio cues for different events
3. **Consistent structure** - Posts always follow the same format
4. **Keyboard-only navigation** - No mouse required anywhere
### Performance Tips
1. **Adjust refresh rate** - Slower connections benefit from longer intervals
2. **Use /last command** - Access cached posts without network requests
3. **Bookmark instead of searching** - Faster access to interesting content
## Troubleshooting Common Issues
### Timeline Issues
```bash
# Timeline won't load
/refresh # Force refresh
# Check network: ping 8.8.8.8
# Old posts showing
/timeline # Reload home timeline
```
### Interaction Problems
```bash
# Menu codes not working
# Make sure you're using current codes (they change as new posts load)
# Can't reply or boost
# Check if post is still available: /url a3
```
### Media Upload Issues
```bash
# Image upload fails
# Ensure file exists: ls -la ~/path/to/image.jpg
# Check file size (8MB limit for images on most servers)
# Provide meaningful alt-text (required!)
```
---
**See also:** [Getting Started](Getting-Started) | [Commands Reference](Commands-Reference) | [Media Uploads](Media-Uploads)
*Last updated: 2025-07-28*

287
Commands-Reference.md Normal file

@ -0,0 +1,287 @@
# Commands Reference
Complete reference for all TTYverse commands. Commands are entered at the `TTYverse>` prompt and always start with `/`.
## Timeline & Navigation Commands
### `/timeline [type]`
Display timeline content.
**Usage:**
- `/timeline` - Show home timeline (default)
- `/timeline local` - Show local instance timeline
- `/timeline federated` - Show federated timeline
- `/timeline bookmarks` - Show bookmarked posts
**Examples:**
```bash
/timeline # Home timeline
/timeline local # Local posts
/timeline federated # All federated posts
/timeline bookmarks # Your bookmarks
```
### `/again`
Show more posts from the current timeline.
### `/refresh`
Refresh the current timeline and fetch new posts.
### `/last [number]`
Show the last N posts from cache.
**Example:**
```bash
/last 10 # Show last 10 posts
```
## Posting Commands
### `/post <message>`
Create a new public post.
**Usage:**
```bash
/post Hello fediverse!
/post This is a longer post with multiple words
```
**Note:** Posts default to public visibility.
### `/reply <code> <message>`
Reply to a specific post using its menu code.
**Usage:**
```bash
/reply a3 Thanks for sharing!
/reply b1 Great point about accessibility
```
### `/media <filepath> [message]`
Upload media (image, audio, video) with optional post text.
**Usage:**
```bash
/media /path/to/image.jpg # Upload image only
/media /path/to/audio.mp3 Great song! # Upload with message
```
**Accessibility:** Images require alt-text descriptions. TTYverse will prompt for alt-text and cancel uploads without descriptions.
**Supported formats:**
- **Images:** JPEG, PNG, GIF, WebP
- **Audio:** MP3, OGG, WAV, FLAC, M4A
- **Video:** MP4, WebM, MOV
## Interaction Commands
### `/boost <code>`
Boost (reblog) a post.
**Usage:**
```bash
/boost a3 # Boost post a3
/boost b7 # Boost post b7
```
### `/unboost <code>`
Remove boost from a post.
### `/fav <code>` / `/favorite <code>`
Favorite (like) a post.
**Usage:**
```bash
/fav a3 # Favorite post a3
/favorite b1 # Same as /fav
```
### `/unfav <code>`
Remove favorite from a post.
### `/bookmark <code>`
Bookmark a post for later.
### `/unbookmark <code>`
Remove bookmark from a post.
### `/vote <code> <choices>`
Vote in a poll.
**Usage:**
```bash
/vote a3 1 # Vote for option 1
/vote b2 2,3 # Vote for options 2 and 3 (multiple choice)
/vote c1 1-3 # Vote for options 1 through 3
```
## Direct Messages
### `/dms`
Show recent direct messages.
### `/reply <dm_code> <message>`
Reply to a direct message.
**Usage:**
```bash
/reply da1 Thanks for the message!
```
## Search Commands
### `/search <query>`
Search for posts, hashtags, or accounts.
**Usage:**
```bash
/search #accessibility # Search hashtag
/search @username@instance.com # Search user
/search "climate change" # Search text
/search technology # Search term
```
### `/whois <username>`
Get information about a user.
**Usage:**
```bash
/whois storm@stormux.org
/whois @localuser
```
## Account & Profile Commands
### `/follow <username>`
Follow a user.
**Usage:**
```bash
/follow storm@stormux.org
/follow @localuser
```
### `/unfollow <username>`
Unfollow a user.
### `/block <username>`
Block a user.
### `/unblock <username>`
Unblock a user.
### `/mute <username>`
Mute a user.
### `/unmute <username>`
Unmute a user.
## URL & Link Commands
### `/url <code>`
Open URL from a post in your browser.
**Usage:**
```bash
/url a3 # Open URL from post a3
```
TTYverse automatically detects your environment and uses:
- **GUI browsers:** Firefox, Chrome, etc. (if DISPLAY is set)
- **CLI browsers:** w3m, elinks, lynx (in terminal)
**Configuration:**
- Set `gui_browser` in config for GUI preference
- Set `cli_browser` in config for CLI preference
## Information Commands
### `/help`
Show available commands.
### `/version`
Show TTYverse version information.
### `/about`
Show information about TTYverse.
### `/rate`
Show current API rate limit status.
## Configuration Commands
### `/set <option> <value>`
Change configuration options.
**Common options:**
```bash
/set effpause 60 # Set refresh interval (seconds)
/set gui_browser firefox # Set GUI browser
/set cli_browser w3m # Set CLI browser
```
### `/get <option>`
Show current value of configuration option.
## System Commands
### `/quit` / `/exit`
Exit TTYverse.
### `/restart`
Restart TTYverse (reload configuration).
## Debug Commands
### `/verbose`
Toggle verbose output for debugging.
### `/debug`
Toggle debug output for troubleshooting.
## Menu Codes
TTYverse assigns menu codes to posts for easy reference:
- **Posts:** `a0`, `a1`, `a2`, ... `a9`, `b0`, `b1`, etc.
- **DMs:** `da0`, `da1`, `da2`, etc.
Codes are assigned in chronological order, with newer posts getting later codes.
## Visibility Levels
When posting, content visibility is shown:
- **[Public]** - Visible to everyone, appears in timelines
- **[Unlisted]** - Public but not in local/federated timelines
- **[Followers]** - Only followers can see
- **[Direct]** - Only mentioned users can see
## Command Aliases
Some commands have shorter aliases:
- `/fav` = `/favorite`
- `/boost` = `/rt` = `/reblog`
- `/dms` = `/dm`
- `/quit` = `/exit` = `/q`
## Tips
1. **Tab completion:** Most commands support tab completion
2. **Command history:** Use up/down arrows for command history
3. **Multiple words:** Wrap multi-word arguments in quotes if needed
4. **Case sensitivity:** Commands are case-insensitive
5. **Menu codes:** Always use current menu codes (they change as new posts load)
## Error Handling
Common error messages:
- "Invalid menu code" - Post code doesn't exist or is old
- "Rate limit exceeded" - API calls too frequent, wait a moment
- "Not found" - User or post doesn't exist
- "Unauthorized" - Authentication problem, check OAuth setup
---
**See also:** [Getting Started](Getting-Started) | [Basic Usage](Basic-Usage) | [Advanced Features](Advanced-Features)
*Last updated: 2025-07-28*

322
Configuration.md Normal file

@ -0,0 +1,322 @@
# Configuration
TTYverse stores configuration in XDG-compliant directories and supports extensive customization through configuration files and runtime settings.
## Configuration Locations
### XDG Base Directory Support
TTYverse follows the XDG Base Directory Specification:
- **Config files:** `$XDG_CONFIG_HOME/ttyverse/` or `~/.config/ttyverse/`
- **Data files:** `$XDG_DATA_HOME/ttyverse/` or `~/.local/share/ttyverse/`
- **Cache files:** `$XDG_CACHE_HOME/ttyverse/` or `~/.cache/ttyverse/`
### Key Files
```
~/.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:
```perl
# 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)
1. Uses `gui_browser` setting if configured
2. Falls back to `xdg-open`
3. Tries common browsers: firefox, chrome, chromium
### CLI Environment (no DISPLAY)
1. Uses `cli_browser` setting if configured
2. Tries CLI browsers: w3m, elinks, lynx
### Manual Configuration
```bash
# 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:
1. Creating directory: `~/.local/share/ttyverse/sounds/mysounds/`
2. Adding OGG files for each notification type
3. 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
```bash
# 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:
```perl
# 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
```bash
# View current setting
/get effpause
# Change setting
/set effpause 60
# View all settings
/verbose
```
### Common Runtime Changes
```bash
# 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:
```bash
# 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:
```bash
# Use different keyfile for second account
./ttyverse.pl -keyfile work_account
# This creates ~/.config/ttyverse/work_account_rc
```
## Performance Tuning
### Memory Usage
```perl
# Reduce cached posts for lower memory usage
timeline_cache=100
# Reduce fetch count for slower connections
timeline_count=15
```
### Network Settings
```perl
# Increase refresh interval for slower connections
effpause=300
# Reduce concurrent connections
max_connections=2
```
### Accessibility Settings
```perl
# 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
```bash
# 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
1. Copy config directory to new system
2. Update file paths if needed
3. Re-authenticate if moving between different systems
4. Install required dependencies (curl, perl modules)
## Troubleshooting Configuration
### Common Issues
```bash
# 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
```bash
# Run with verbose output to see config loading
./ttyverse.pl -verbose
# Check which config file is being used
./ttyverse.pl -debug
```
### Reset to Defaults
```bash
# 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](Getting-Started) | [Extensions](Extensions) | [Troubleshooting](Troubleshooting)
*Last updated: 2025-07-28*

98
Extensions.md Normal file

@ -0,0 +1,98 @@
# Extensions
TTYverse supports extensions that add functionality like sound notifications, text-to-speech, and desktop integration. Extensions are Perl scripts that integrate with TTYverse's multi-process architecture.
## Available Extensions
TTYverse includes several extensions that enhance the user experience:
- **Sound Pack** - Audio notifications for different types of posts and events
- **Text-to-Speech** - Speak posts and notifications aloud
- **Desktop Notifications** - Visual notification bubbles
- **Timestamp Enhancement** - Enhanced timestamp display options
Extensions are included with TTYverse but not enabled by default.
## Extension Installation
### Extension Availability
TTYverse includes core extensions in the installation:
```bash
** attempting to load extensions
** loading /home/user/.local/share/ttyverse/extensions/extensionname.pl
** loaded extensions: extensionname
```
### Extension Location
Extensions are stored in:
```
~/.local/share/ttyverse/extensions/
```
## Configuration
Extensions are configured through TTYverse settings:
```bash
# View extension-related settings
/get sound_enabled
/get tts_enabled
# Enable/disable extensions
/set sound_enabled 1
/set extension_name 0
```
Configuration can also be edited directly in:
```
~/.config/ttyverse/ttyverse_rc
```
## Extension Dependencies
Some extensions may require additional system packages. Check the documentation for your specific distribution to install:
- **Audio support** - PulseAudio or similar audio system
- **Text-to-speech** - TTS engines like espeak or festival
- **Desktop notifications** - libnotify and related Perl modules
## Custom Extensions
### Creating Extensions
Extensions are Perl scripts that follow TTYverse conventions. They can:
- Hook into post processing
- React to different notification types
- Add new commands
- Integrate with system features
### Extension Development
See the existing extensions in `~/.local/share/ttyverse/extensions/` for examples of how to create custom functionality.
## Troubleshooting
### Extension Issues
```bash
# Check if extensions are loading
./ttyverse.pl -verbose
# Test extension files manually
perl ~/.local/share/ttyverse/extensions/extensionname.pl
# Fix permissions if needed
chmod +x ~/.local/share/ttyverse/extensions/*.pl
```
### Common Problems
- **Permission denied** - Make extension files executable
- **Missing dependencies** - Install required system packages
- **Configuration errors** - Check settings in ttyverse_rc
For specific extension issues, check the [Troubleshooting](Troubleshooting) guide.
---
**See also:** [Configuration](Configuration) | [Troubleshooting](Troubleshooting) | [Installation](Installation)
*Last updated: 2025-07-28*

230
FAQ.md Normal file

@ -0,0 +1,230 @@
# Frequently Asked Questions (FAQ)
Common questions about TTYverse. For technical issues, see [Troubleshooting](Troubleshooting).
## General Questions
### What is TTYverse?
TTYverse is a command-line client for the fediverse (Mastodon, GoToSocial, etc.). It's designed for terminal users who want a powerful, accessible way to interact with ActivityPub servers.
### How is TTYverse different from other fediverse clients?
- **Accessibility-first design** - Built by and for screen reader users
- **Terminal-native** - No GUI dependencies, works over SSH
- **Single-file architecture** - Just one Perl script
- **Sound notifications** - Audio feedback for different post types
- **Enforced alt-text** - Images require descriptions for accessibility
### What servers does TTYverse support?
- **Mastodon** - Full support
- **GoToSocial** - Full support
- **Pleroma** - Basic support
- **Misskey** - Limited support
- **Any ActivityPub server** - Basic federation features
### Is TTYverse free?
Yes, TTYverse is free software under the Floodgap Free Software License. You can use, modify, and distribute it freely.
## Installation and Setup
### Do I need to install anything besides TTYverse?
You need Perl and curl, which are available on most Unix-like systems. Optional dependencies improve the experience:
- **Term::ReadLine::Gnu** - Better command line editing
- **PulseAudio** - Sound notifications
- **w3m/elinks/lynx** - Opening links in terminal
### Can I run TTYverse on Windows?
Not directly. TTYverse is designed for Unix-like systems. You could try:
- **WSL (Windows Subsystem for Linux)** - Run Linux environment on Windows
- **Cygwin** - Unix-like environment for Windows
- **Virtual machine** - Run Linux in a VM
### How do I update TTYverse?
Download the latest version and replace your current script:
```bash
wget -O ttyverse.pl https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
chmod +x ttyverse.pl
```
## Usage Questions
### How do I see older posts?
Use `/again` to load more posts from your timeline, or `/last 20` to see the last 20 cached posts.
### Can I use TTYverse over SSH?
Yes! TTYverse works perfectly over SSH connections. Sound notifications won't work over SSH, but all other features do.
### How do I open links from posts?
Use `/url <post_code>` (e.g., `/url a3`). TTYverse will automatically detect your environment and use appropriate browsers.
### Why does TTYverse require alt-text for images?
TTYverse enforces accessibility standards. The maintainer is blind, and the philosophy is: "If you're going to use a client maintained by a blind guy, you can damn well describe your images!"
### Can I post without media upload?
Yes, use `/post Your message here` for text-only posts.
## Technical Questions
### Where does TTYverse store its configuration?
TTYverse follows XDG Base Directory specification:
- **Config:** `~/.config/ttyverse/`
- **Data:** `~/.local/share/ttyverse/`
- **Cache:** `~/.cache/ttyverse/`
### How does the multi-process architecture work?
TTYverse runs two processes:
- **Foreground process** - User interface and commands
- **Background process** - Timeline monitoring and data management
They communicate via IPC (pipes and signals).
### Can I run multiple instances?
Yes, use different keyfiles:
```bash
./ttyverse.pl -keyfile work_account
./ttyverse.pl -keyfile personal_account
```
### How do I backup my configuration?
```bash
tar -czf ttyverse-backup.tar.gz ~/.config/ttyverse/
```
## Features and Functionality
### What timeline types are supported?
- **Home timeline** - Posts from accounts you follow
- **Local timeline** - Posts from your instance
- **Federated timeline** - Posts from the broader fediverse
- **Bookmarks** - Posts you've bookmarked
### Does TTYverse support direct messages?
Yes, use `/dms` to view direct messages and `/reply da1 message` to reply.
### Can I boost and favorite posts?
Yes:
- `/boost a3` - Boost post a3
- `/fav a3` - Favorite post a3
- `/bookmark a3` - Bookmark post a3
### What about search functionality?
Use `/search` for:
- `/search #hashtag` - Search hashtags
- `/search @username` - Find users
- `/search "text"` - Search post content
## Accessibility Features
### What accessibility features does TTYverse have?
- **Screen reader friendly** - All output is text-based
- **Sound notifications** - Audio feedback for events
- **Alt-text enforcement** - Images must have descriptions
- **Keyboard navigation** - No mouse required
- **Terminal compatibility** - Works with any terminal
### Can I disable sound notifications?
Yes, edit `~/.config/ttyverse/ttyverse_rc` and set `sound_enabled=0`
### Does TTYverse work with screen readers?
Yes, TTYverse is designed specifically for screen reader users. All output is plain text and follows screen reader conventions.
## Customization
### Can I change the sound notifications?
Yes, replace sound files in `~/.local/share/ttyverse/sounds/default/` or create custom sound packs.
### How do I change the browser TTYverse uses?
```bash
/set gui_browser firefox
/set cli_browser w3m
```
### Can I adjust the timeline refresh rate?
```bash
/set effpause 300 # Refresh every 5 minutes
```
### Are there extensions available?
Yes, TTYverse includes several extensions:
- **soundpack.pl** - Sound notifications
- **tts.pl** - Text-to-speech
- **libnotify.pl** - Desktop notifications
## Troubleshooting
### TTYverse won't start, what should I check?
1. Perl is installed: `perl --version`
2. curl is available: `curl --version`
3. Script is executable: `chmod +x ttyverse.pl`
4. Config directory exists: `mkdir -p ~/.config/ttyverse/`
### I'm getting "connection failed" errors
1. Check internet connection: `ping 8.8.8.8`
2. Verify server URL in config
3. Test server manually: `curl https://your-instance.com/api/v1/instance`
4. Check firewall/proxy settings
### OAuth setup isn't working
1. Try manual OAuth - copy URL to browser manually
2. Check browser configuration
3. Verify server supports OAuth 2.0
4. Clear old credentials and start fresh
### Media uploads aren't working
1. Check file size limits (8MB for images, 40MB for video on Mastodon)
2. Verify file format is supported
3. Test with smaller files
4. Check server error messages
## Development and Contributing
### Can I contribute to TTYverse?
Yes! Contributions are welcome:
- Report bugs at https://git.stormux.org/storm/ttyverse/issues
- Submit patches via email or git
- Improve documentation
- Create extensions
### How is TTYverse developed?
TTYverse is written in Perl as a single script. It's forked from TTYtter but completely rewritten for the fediverse.
### Can I create extensions?
Yes, extensions are Perl scripts in `~/.local/share/ttyverse/extensions/`. See existing extensions for examples.
## Privacy and Security
### What data does TTYverse store locally?
- **OAuth tokens** - For server authentication
- **Timeline cache** - Recent posts for faster display
- **DM seen status** - To track read direct messages
- **Configuration** - Your settings and preferences
### How secure is TTYverse?
- Uses OAuth 2.0 for authentication
- Stores tokens locally with restricted permissions
- No data sent to third parties
- All communication is HTTPS
### Can I run TTYverse without saving credentials?
OAuth tokens must be saved for TTYverse to function. Tokens are stored with restricted file permissions (600).
## Getting Help
### Where can I get support?
- **Built-in help:** `/help` command in TTYverse
- **Documentation:** This wiki
- **Issues:** https://git.stormux.org/storm/ttyverse/issues
- **Community:** Fediverse community support
### How do I report bugs?
Report bugs at https://git.stormux.org/storm/ttyverse/issues with:
- TTYverse version
- System information
- Steps to reproduce
- Error messages
- Debug output (if applicable)
---
**See also:** [Getting Started](Getting-Started) | [Troubleshooting](Troubleshooting) | [Commands Reference](Commands-Reference)
*Last updated: 2025-07-28*

232
Getting-Started.md Normal file

@ -0,0 +1,232 @@
# Getting Started with TTYverse
TTYverse is a command-line fediverse client that lets you interact with Mastodon, GoToSocial, and other ActivityPub servers from your terminal. This guide will get you up and running quickly.
## Prerequisites
- **Perl 5.x** - TTYverse is written in Perl
- **curl** - For API communication
- **Terminal emulator** - Any Unix/Linux terminal
- **Fediverse account** - On Mastodon, GoToSocial, or compatible server
## Installation
### Quick Install
```bash
# Download the latest release
wget https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
# Make executable
chmod +x ttyverse.pl
# Run TTYverse
./ttyverse.pl
```
For detailed installation options, see the [Installation](Installation) guide.
## First-Time Setup
### 1. Initial Launch
When you first run TTYverse, it will guide you through OAuth setup:
```bash
./ttyverse.pl
```
### 2. Server Configuration
TTYverse will ask for your fediverse server. Enter your instance URL:
```
Enter your fediverse instance (e.g., mastodon.social): your-instance.com
```
### 3. OAuth Authorization
TTYverse will:
1. Open your browser to authorize the application
2. Generate an access token
3. Save credentials to `~/.config/ttyverse/`
### 4. First Login
After setup, you'll see the TTYverse prompt:
```
TTYverse 2025.07.28 (c)2025 Storm Dragon
fediverse client for Mastodon/GoToSocial/etc
when ready, hit RETURN/ENTER for a prompt.
type /help for commands or /quit to quit.
TTYverse>
```
## Essential Commands
### Viewing Content
```bash
# Show your home timeline
/timeline
# Show local timeline
/timeline local
# Show federated timeline
/timeline federated
# Show bookmarks
/timeline bookmarks
# Show direct messages
/dms
```
### Creating Content
```bash
# Post a message
/post Hello fediverse!
# Reply to a post (using menu code)
/reply a3 Thanks for the interesting post!
# Post with media
/media /path/to/image.jpg
```
### Interacting
```bash
# Boost a post
/boost a3
# Favorite a post
/fav a3
# Vote in a poll
/vote a3 2
# Search
/search #hashtag
/search @username
/search "search terms"
```
### Navigation
```bash
# Show more posts
/again
# Refresh timeline
/refresh
# Get help
/help
# Quit
/quit
```
## Understanding Post Codes
TTYverse assigns menu codes to posts for easy reference:
```
a0> {,POST_ID} <username> (2h ago) via TTYverse [Public]
This is a post with menu code 'a0'
a1> {,POST_ID} <username> (1h ago) via Web [Unlisted]
This post has menu code 'a1'
```
Use these codes with commands:
- `/reply a0 Great post!`
- `/boost a1`
- `/fav a0`
## Understanding Visibility Indicators
Posts show visibility levels:
- **[Public]** - Visible to everyone, appears in public timelines
- **[Unlisted]** - Public but doesn't appear in local/federated timelines
- **[Followers]** - Only visible to your followers
- **[Direct]** - Direct message, only visible to mentioned users
## Media Uploads
TTYverse enforces accessibility for images:
```bash
# Upload an image (will prompt for alt-text)
/media /path/to/photo.jpg
# Upload audio/video (no alt-text required)
/media /path/to/audio.mp3
```
**Note:** Images require alt-text descriptions. TTYverse will cancel uploads without descriptions to enforce accessibility.
## Sound Notifications
TTYverse includes sound notifications for different events:
- New posts
- Mentions
- Direct messages
- Boosts and favorites
Sounds are stored in `~/.local/share/ttyverse/sounds/`
## Configuration Files
TTYverse stores configuration in XDG-compliant locations:
- **Config:** `~/.config/ttyverse/`
- **Extensions:** `~/.local/share/ttyverse/extensions/`
- **Sounds:** `~/.local/share/ttyverse/sounds/`
## Next Steps
Once you're comfortable with basic usage:
1. **[Configuration](Configuration)** - Customize TTYverse settings
2. **[Advanced Features](Advanced-Features)** - Power user features
3. **[Extensions](Extensions)** - Add sound packs and TTS
4. **[Commands Reference](Commands-Reference)** - Complete command documentation
## Common Issues
### Connection Problems
```bash
# Test your connection
/refresh
# Check your OAuth setup
cat ~/.config/ttyverse/ttyverse_rc
```
### Sound Issues
```bash
# Check if sound files exist
ls ~/.local/share/ttyverse/sounds/default/
# Test audio playback
paplay ~/.local/share/ttyverse/sounds/default/default.ogg
```
### Permission Issues
```bash
# Ensure config directory is writable
ls -la ~/.config/ttyverse/
# Check file permissions
chmod 600 ~/.config/ttyverse/*
```
## Getting Help
- **In TTYverse:** Type `/help` for command list
- **Troubleshooting:** See [Troubleshooting](Troubleshooting) guide
- **FAQ:** Check [FAQ](FAQ) for common questions
- **Issues:** Report bugs at https://git.stormux.org/storm/ttyverse/issues
---
**Next:** [Basic Usage](Basic-Usage) | [Commands Reference](Commands-Reference)
*Last updated: 2025-07-28*

103
Home.md

@ -1 +1,102 @@
This is the central repository of knowledge about using TTYverse. # TTYverse Wiki
**TTYverse** is a command-line fediverse client for Mastodon, GoToSocial, and other ActivityPub servers. Originally forked from TTYtter, it's been completely rebuilt for the fediverse era with accessibility and usability as core principles.
## Quick Start
**New to TTYverse?** → [Getting Started](Getting-Started) | [Installation](Installation)
**Need help with a command?** → [Commands Reference](Commands-Reference) | [Quick Command List](Quick-Commands)
**Having issues?** → [Troubleshooting](Troubleshooting) | [FAQ](FAQ)
## Navigation
### 📚 User Guides
- **[Getting Started](Getting-Started)** - First-time setup and basic usage
- **[Installation](Installation)** - Download, install, and initial configuration
- **[Basic Usage](Basic-Usage)** - Essential commands and workflows
- **[Advanced Features](Advanced-Features)** - Power user features and customization
### 📖 Reference Documentation
- **[Commands Reference](Commands-Reference)** - Complete command documentation
- **[Configuration](Configuration)** - Settings, options, and customization
- **[Keyboard Shortcuts](Keyboard-Shortcuts)** - Terminal navigation and hotkeys
- **[File Locations](File-Locations)** - Config files, logs, and data storage
### 🔧 Technical Documentation
- **[Extensions](Extensions)** - Sound packs, TTS, and custom extensions
- **[OAuth Setup](OAuth-Setup)** - Server authentication and key management
- **[API Integration](API-Integration)** - Mastodon API usage and limitations
- **[Architecture](Architecture)** - Multi-process design and IPC
### 🆘 Support & Troubleshooting
- **[Troubleshooting](Troubleshooting)** - Common issues and solutions
- **[FAQ](FAQ)** - Frequently asked questions
- **[Error Messages](Error-Messages)** - What error messages mean and how to fix them
- **[Performance](Performance)** - Optimizing TTYverse for your system
### 🎯 Feature Guides
- **[Timeline Navigation](Timeline-Navigation)** - Reading posts, filtering, and browsing
- **[Posting](Posting)** - Creating posts, replies, and using visibility settings
- **[Media Uploads](Media-Uploads)** - Images, audio, video, and accessibility
- **[Direct Messages](Direct-Messages)** - Private messaging and conversations
- **[Polls](Polls)** - Creating and voting on polls
- **[Search](Search)** - Finding posts, people, and hashtags
### 🌐 Fediverse Integration
- **[Server Compatibility](Server-Compatibility)** - Mastodon, GoToSocial, Pleroma support
- **[Instance Features](Instance-Features)** - Feature differences across servers
- **[Cross-Instance](Cross-Instance)** - Following and interacting across servers
### 🔨 Development
- **[Contributing](Contributing)** - How to contribute to TTYverse
- **[Development Setup](Development-Setup)** - Setting up a development environment
- **[Extension Development](Extension-Development)** - Creating custom extensions
- **[Testing](Testing)** - Running tests and validation
## Quick Reference
### Essential Commands
- `/help` - Show available commands
- `/timeline` - Show timeline (home, local, federated, bookmarks)
- `/post message` - Create a new post
- `/reply a3 message` - Reply to post a3
- `/boost a3` - Boost post a3
- `/fav a3` - Favorite post a3
- `/dms` - Show direct messages
- `/media /path/file` - Upload media with post
- `/search term` - Search posts and accounts
- `/quit` - Exit TTYverse
### Key Features
- **🎵 Sound Notifications** - Audio feedback for different post types
- **♿ Accessibility First** - Alt-text enforcement and screen reader friendly
- **🔐 OAuth 2.0** - Secure authentication with any fediverse server
- **⚡ Real-time Updates** - Background monitoring and notifications
- **🎨 Extensions** - Sound packs, TTS, notifications, and more
- **📱 Multi-format** - Text, images, audio, video, and polls
## About TTYverse
**Current Version:** 2025.07.28
**License:** Floodgap Free Software License
**Original:** Forked from TTYtter by Cameron Kaiser
**Maintainer:** Storm Dragon
**Repository:** https://git.stormux.org/storm/ttyverse
### Philosophy
> "If you're going to use a client maintained by a blind guy, you can damn well describe your images!"
TTYverse prioritizes accessibility, usability, and the principles of the open fediverse. Every feature is designed with screen reader users and keyboard navigation in mind, while remaining powerful for all users.
## Getting Help
- **Commands:** Type `/help` in TTYverse for command list
- **Issues:** Report bugs at https://git.stormux.org/storm/ttyverse/issues
- **Wiki:** This wiki for comprehensive documentation
- **Community:** Find support in the fediverse community
---
*Last updated: 2025-07-28*

346
Installation.md Normal file

@ -0,0 +1,346 @@
# Installation
TTYverse is a single Perl script that works on any Unix-like system with Perl and curl. This guide covers installation methods for different systems.
## System Requirements
### Required
- **Perl 5.x** - TTYverse is written in Perl
- **curl** - For API communication with fediverse servers
- **Terminal emulator** - Any Unix/Linux terminal
### Recommended
- **Term::ReadLine::Gnu** - Enhanced command line editing
- **PulseAudio** - For sound notifications
- **GUI browser** - For opening links (Firefox, Chrome, etc.)
- **CLI browser** - For terminal link opening (w3m, elinks, lynx)
### Optional
- **Desktop notification system** - For desktop alerts
- **Text-to-speech** - For TTS extensions
## Installation Methods
### Method 1: Direct Download (Recommended)
```bash
# Download latest release
wget https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
# Make executable
chmod +x ttyverse.pl
# Run TTYverse
./ttyverse.pl
```
### Method 2: Git Clone
```bash
# Clone repository
git clone https://git.stormux.org/storm/ttyverse.git
cd ttyverse
# Run TTYverse
perl ttyverse.pl
```
### Method 3: System Package (Future)
*System packages are planned for future releases*
## Dependency Installation
### Debian/Ubuntu
```bash
# Basic dependencies
sudo apt update
sudo apt install perl curl
# Enhanced readline support
sudo apt install libterm-readline-gnu-perl
# Sound support
sudo apt install pulseaudio-utils
# Browser options
sudo apt install firefox w3m
# Optional: Desktop notifications
sudo apt install libdesktop-notify-perl
```
### Arch Linux
```bash
# Basic dependencies
sudo pacman -S perl curl
# Enhanced readline support
sudo pacman -S perl-term-readline-gnu
# Sound support
sudo pacman -S pulseaudio
# Browser options
sudo pacman -S firefox w3m
# Optional: AUR packages for additional features
yay -S perl-desktop-notify
```
### Fedora/RHEL/CentOS
```bash
# Basic dependencies
sudo dnf install perl curl
# Enhanced readline support
sudo dnf install perl-Term-ReadLine-Gnu
# Sound support
sudo dnf install pulseaudio-utils
# Browser options
sudo dnf install firefox w3m
```
### macOS
```bash
# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install dependencies
brew install perl curl
# Install optional dependencies
brew install w3m
# Note: macOS includes curl by default
```
### FreeBSD
```bash
# Install from ports
sudo pkg install perl5 curl w3m
# Or compile from ports
cd /usr/ports/lang/perl5.32 && sudo make install clean
cd /usr/ports/ftp/curl && sudo make install clean
```
## Installation Locations
### Portable Installation
TTYverse can run from any directory:
```bash
# Download to home directory
cd ~
wget https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
chmod +x ttyverse.pl
./ttyverse.pl
```
### System-wide Installation
```bash
# Install to /usr/local/bin for all users
sudo wget -O /usr/local/bin/ttyverse https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
sudo chmod +x /usr/local/bin/ttyverse
# Now any user can run
ttyverse
```
### Personal Binary Directory
```bash
# Install to personal bin directory
mkdir -p ~/bin
wget -O ~/bin/ttyverse https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
chmod +x ~/bin/ttyverse
# Add to PATH if needed
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
# Run from anywhere
ttyverse
```
## Verification
### Test Installation
```bash
# Check TTYverse version
./ttyverse.pl -version
# Expected output:
# TTYverse 2025.07.28 (c)2025 Storm Dragon
```
### Test Dependencies
```bash
# Check Perl
perl --version
# Check curl
curl --version
# Check optional readline
perl -MArray::ReadLine::Gnu -e 'print "ReadLine::Gnu available\n"' 2>/dev/null || echo "ReadLine::Gnu not available"
# Check sound support
paplay --version 2>/dev/null || echo "PulseAudio not available"
```
## First Run Setup
### Initial Configuration
When you first run TTYverse, it will:
1. **Create config directories:**
```
~/.config/ttyverse/
~/.local/share/ttyverse/
```
2. **Download extensions:**
- Sound pack extension
- TTS extension (if available)
- Notification extensions
3. **OAuth setup:**
- Prompt for fediverse server
- Open browser for authorization
- Save authentication tokens
### Manual Extension Setup
```bash
# Create extension directory
mkdir -p ~/.local/share/ttyverse/extensions/
# Download extensions manually if needed
cd ~/.local/share/ttyverse/extensions/
wget https://git.stormux.org/storm/ttyverse/raw/branch/master/extensions/soundpack.pl
wget https://git.stormux.org/storm/ttyverse/raw/branch/master/extensions/tts.pl
chmod +x *.pl
```
## Troubleshooting Installation
### Permission Issues
```bash
# Make sure you can execute the script
ls -la ttyverse.pl
chmod +x ttyverse.pl
# Check directory permissions
ls -la ~/.config/
mkdir -p ~/.config/ttyverse/
chmod 700 ~/.config/ttyverse/
```
### Missing Dependencies
```bash
# Test if Perl modules are available
perl -MHTml::Entities -e 'print "HTML::Entities available\n"'
perl -MArray::JSON -e 'print "JSON available\n"'
# Install missing Perl modules
cpan HTML::Entities
cpan JSON
```
### Network Issues
```bash
# Test network connectivity
ping 8.8.8.8
curl -I https://git.stormux.org/
# Test SSL certificates
curl https://mastodon.social/api/v1/instance
```
## Development Installation
### For Contributors
```bash
# Clone development repository
git clone https://git.stormux.org/storm/ttyverse.git
cd ttyverse
# Install development dependencies
# (Add any dev-specific requirements here)
# Run from source
perl ttyverse.pl -verbose
```
### Building from Source
```bash
# TTYverse is a single script, no build process needed
# Just ensure you have the latest version:
cd ttyverse
git pull origin master
perl ttyverse.pl
```
## Uninstallation
### Remove TTYverse
```bash
# Remove script
rm ttyverse.pl
# or
sudo rm /usr/local/bin/ttyverse
# Remove configuration (optional - saves your settings)
rm -rf ~/.config/ttyverse/
rm -rf ~/.local/share/ttyverse/
rm -rf ~/.cache/ttyverse/
```
### Keep Configuration
If you want to reinstall later, keep the config directories:
```bash
# Only remove the script
rm ttyverse.pl
# Configuration in ~/.config/ttyverse/ will be reused
```
## Updating
### Manual Update
```bash
# Download new version
wget -O ttyverse.pl.new https://git.stormux.org/storm/ttyverse/releases/latest/download/ttyverse.pl
# Backup old version
mv ttyverse.pl ttyverse.pl.backup
# Install new version
mv ttyverse.pl.new ttyverse.pl
chmod +x ttyverse.pl
# Test new version
./ttyverse.pl -version
```
### Git Update
```bash
# If installed via git
cd ttyverse
git pull origin master
```
### Version Check
TTYverse checks for updates automatically:
```
-- checking TTYverse version...
-- your version of TTYverse is up to date (2025.07.28)
```
---
**Next:** [Getting Started](Getting-Started) | [Configuration](Configuration)
*Last updated: 2025-07-28*

244
Media-Uploads.md Normal file

@ -0,0 +1,244 @@
# Media Uploads
TTYverse supports uploading images, audio, and video files to your fediverse posts with a strong focus on accessibility.
## Basic Usage
### Upload Media with Post
```bash
/media /path/to/file.jpg Optional post message here
```
### Upload Media Only
```bash
/media /path/to/file.mp3
```
TTYverse will:
1. Detect the file type automatically
2. Prompt for alt-text (images only)
3. Upload the media to your server
4. Create a post with the media attached
## Supported File Types
### Images
- **JPEG** (`.jpg`, `.jpeg`)
- **PNG** (`.png`)
- **GIF** (`.gif`)
- **WebP** (`.webp`)
### Audio
- **MP3** (`.mp3`)
- **OGG** (`.ogg`)
- **WAV** (`.wav`)
- **FLAC** (`.flac`)
- **M4A** (`.m4a`)
### Video
- **MP4** (`.mp4`)
- **WebM** (`.webm`)
- **MOV** (`.mov`)
## Accessibility Requirements
### Image Alt-Text (Required)
TTYverse enforces alt-text for all images to ensure accessibility:
```bash
TTYverse> /media /home/user/photo.jpg
-- Detected file type: image/jpeg
-- Images require alt-text for accessibility
Enter alt text for photo.jpg: A sunset over mountains with orange and purple clouds
Enter post message (optional): Beautiful evening hike!
-- Uploading media file...
-- Media uploaded successfully
-- Post created successfully!
```
### Alt-Text Guidelines
**Good alt-text examples:**
- "A golden retriever playing fetch in a park"
- "Screenshot of terminal showing TTYverse timeline"
- "Graph showing temperature increase over time"
- "Person wearing red jacket standing on snowy mountain"
**Avoid:**
- Empty alt-text (upload will be cancelled)
- Redundant phrases like "image of" or "picture showing"
- File names or technical details
- Vague descriptions like "thing" or "stuff"
### Enforcement Message
If you try to upload an image without alt-text:
```
-- Upload cancelled: Alt-text is required for images
-- If you're going to use a client maintained by a blind guy, you can damn well describe your images!
```
This enforcement ensures TTYverse maintains its accessibility-first philosophy.
## Audio and Video
Audio and video files don't require alt-text, but you can still add descriptive post text:
```bash
/media /path/to/song.mp3 My latest recording - feedback welcome!
/media /path/to/video.mp4 Time-lapse of sunset from my backyard
```
## File Size Limits
Media upload limits depend on your fediverse server:
- **Mastodon default:** 8MB for images, 40MB for video/audio
- **GoToSocial:** Configurable by admin
- **Other servers:** Check your instance's upload limits
TTYverse will show server error messages if files are too large.
## Upload Process
### Step-by-Step Flow
1. **File Detection**
```
-- Detected file type: image/jpeg
```
2. **Alt-Text Prompt** (images only)
```
-- Images require alt-text for accessibility
Enter alt text for filename.jpg: [your description]
```
3. **Post Message** (optional)
```
Enter post message (optional): [your message]
```
4. **Upload and Post**
```
-- Uploading media file...
-- Media uploaded successfully (ID: xxxxxxxxx)
-- Creating post with media attachment...
-- Post created successfully!
```
### Background Processing
TTYverse uploads happen in the foreground process while background monitoring continues. The multi-process architecture ensures:
- Timeline updates don't interrupt uploads
- Media uploads don't block timeline refresh
- User can continue using TTYverse after posting
## Error Handling
### Common Upload Errors
**File not found:**
```
-- ERROR: File not found: /path/to/missing.jpg
```
**Unsupported file type:**
```
-- ERROR: Unsupported file type: application/pdf
-- Supported types: image/*, audio/*, video/*
```
**Server upload failure:**
```
-- ERROR: Media upload failed
-- Response: {"error":"File too large"}
```
**Authentication errors:**
```
-- ERROR: No media ID in response
-- Response: {"error":"Unauthorized: token not supplied"}
```
### Troubleshooting
**Authentication issues:**
1. Check OAuth setup: `ls ~/.config/ttyverse/`
2. Verify token: `/refresh` to test API access
3. Re-authenticate if needed: `rm ~/.config/ttyverse/*` and restart
**File permission issues:**
1. Check file exists: `ls -la /path/to/file`
2. Verify read permissions: `cat /path/to/file > /dev/null`
3. Use absolute paths when possible
**Server limits:**
1. Check file size: `ls -lh /path/to/file`
2. Try smaller files to test limits
3. Check server documentation for upload limits
## Best Practices
### Alt-Text Writing
- **Be concise but descriptive**
- **Include relevant context** for the post
- **Describe the important elements** that sighted users would notice
- **Use natural language** as if describing to a friend
### File Management
- **Use descriptive filenames** for organization
- **Keep files organized** in logical directories
- **Check file sizes** before uploading
- **Test uploads** with small files first
### Accessibility Considerations
- **Always provide meaningful alt-text** for images
- **Include transcripts** in post text for audio content
- **Describe video content** in post text when relevant
- **Consider screen reader users** in all media posts
## Examples
### Image Post with Context
```bash
/media ~/photos/garden.jpg Tomatoes are finally ripening!
# Alt-text: "Red and green tomatoes growing on vines in a garden"
```
### Audio with Description
```bash
/media ~/recordings/bird-song.mp3 Recorded this morning in the park
```
### Video with Context
```bash
/media ~/videos/demo.mp4 Quick demo of the new feature working
```
### Technical Screenshot
```bash
/media ~/screenshots/terminal.png
# Alt-text: "Terminal window showing TTYverse commands and timeline with several posts visible"
```
## Integration with Fediverse
### Server Compatibility
- **Mastodon:** Full support for all media types
- **GoToSocial:** Full support, admin-configurable limits
- **Pleroma:** Basic support, check instance features
- **Other servers:** Media support varies by implementation
### Cross-Instance Media
- Media uploads work with any compatible fediverse server
- Alt-text is preserved when posts are viewed on other instances
- Media appears in boosts and replies across the fediverse
---
**See also:** [Commands Reference](Commands-Reference) | [Accessibility](Accessibility) | [Server Compatibility](Server-Compatibility)
*Last updated: 2025-07-28*

152
Quick-Commands.md Normal file

@ -0,0 +1,152 @@
# Quick Commands Reference
Essential TTYverse commands for quick reference. For complete documentation, see [Commands Reference](Commands-Reference).
## Essential Commands
### Getting Started
```bash
/help # Show all available commands
/timeline # Show your home timeline
/refresh # Refresh timeline
/quit # Exit TTYverse
```
### Posting and Interaction
```bash
/post Hello world! # Create a public post
/reply a3 Great point! # Reply to post a3
/boost a3 # Boost post a3
/fav a3 # Favorite post a3
/bookmark a3 # Bookmark post a3
```
### Media and Content
```bash
/media /path/image.jpg # Upload image (requires alt-text)
/media /path/audio.mp3 # Upload audio file
/url a3 # Open URL from post a3
```
### Navigation
```bash
/timeline # Home timeline
/timeline local # Local instance timeline
/timeline federated # Federated timeline
/timeline bookmarks # Your bookmarks
/again # Load more posts
/last 10 # Show last 10 cached posts
```
### Direct Messages
```bash
/dms # Show direct messages
/reply da1 Thanks! # Reply to DM da1
```
### Search and Discovery
```bash
/search #hashtag # Search hashtag
/search @username # Find user
/search "search text" # Search posts
/whois @username # Get user info
```
### Account Management
```bash
/follow @user # Follow a user
/unfollow @user # Unfollow a user
/block @user # Block a user
/mute @user # Mute a user
```
### Poll Interaction
```bash
/vote a3 1 # Vote for option 1 in poll a3
/vote b2 2,3 # Vote for options 2 and 3
```
### Configuration
```bash
/set effpause 300 # Set refresh interval (5 minutes)
/set gui_browser firefox # Set GUI browser
/set cli_browser w3m # Set CLI browser
/get effpause # Show current refresh interval
```
### Information
```bash
/version # Show TTYverse version
/rate # Show API rate limit status
/verbose # Toggle verbose output
/debug # Toggle debug output
```
## Post Menu Codes
TTYverse assigns codes to posts for easy reference:
- **Timeline posts:** `a0`, `a1`, `a2`... `a9`, `b0`, `b1`, etc.
- **Direct messages:** `da0`, `da1`, `da2`, etc.
Use these codes with interaction commands:
```bash
/boost a3 # Boost post a3
/reply b7 Nice post! # Reply to post b7
/url c2 # Open URL from post c2
```
## Visibility Indicators
Posts show their visibility level:
- **[Public]** - Visible to everyone
- **[Unlisted]** - Public but not in timelines
- **[Followers]** - Only followers can see
- **[Direct]** - Only mentioned users can see
## Quick Tips
1. **Use tab completion** - Start typing commands and press Tab
2. **Command history** - Use up/down arrows for previous commands
3. **Help anytime** - Type `/help` to see all commands
4. **Menu codes change** - Always use current codes as new posts load
5. **Alt-text required** - Images must have descriptions
6. **Multiple timelines** - Switch between different timeline views
## Common Workflows
### Reading Timeline
```bash
/timeline # Load home timeline
/again # See more posts
/url a3 # Open interesting link
/boost a5 # Share good post
```
### Posting with Media
```bash
/media ~/photo.jpg # Upload image
# Enter alt-text when prompted
# Enter optional post message
```
### Engaging with Posts
```bash
/fav a3 # Like the post
/boost a3 # Share it
/reply a3 Great point! # Add your thoughts
/bookmark a3 # Save for later
```
### Managing Timeline
```bash
/timeline bookmarks # See saved posts
/timeline local # See local community
/search #topic # Find specific content
/refresh # Get latest posts
```
---
**See also:** [Commands Reference](Commands-Reference) | [Getting Started](Getting-Started) | [Basic Usage](Basic-Usage)
*Last updated: 2025-07-28*

479
Troubleshooting.md Normal file

@ -0,0 +1,479 @@
# Troubleshooting
Common issues and solutions for TTYverse. If you don't find your issue here, check the [FAQ](FAQ) or report it at https://git.stormux.org/storm/ttyverse/issues.
## Connection Issues
### "Connection failed" or "Cannot connect to server"
**Symptoms:**
```
-- ERROR: Connection failed
-- Unable to fetch timeline
```
**Solutions:**
1. **Check internet connection:**
```bash
ping 8.8.8.8
curl -I https://google.com
```
2. **Verify server URL:**
```bash
# Check your configured server
grep apibase ~/.config/ttyverse/ttyverse_rc
# Test server manually
curl https://your-instance.com/api/v1/instance
```
3. **Check server status:**
- Visit your server's web interface
- Check server status pages
- Try different DNS servers
4. **Firewall/proxy issues:**
```bash
# Test if curl works
curl https://your-instance.com/api/v1/instance
# Check proxy settings
echo $HTTP_PROXY
echo $HTTPS_PROXY
```
### SSL/TLS Certificate Issues
**Symptoms:**
```
-- SSL certificate problem
-- unable to get local issuer certificate
```
**Solutions:**
1. **Update CA certificates:**
```bash
# Debian/Ubuntu
sudo apt update && sudo apt install ca-certificates
# Arch Linux
sudo pacman -S ca-certificates
```
2. **Check system time:**
```bash
date
# Ensure system time is correct
```
3. **Test SSL manually:**
```bash
openssl s_client -connect your-instance.com:443 -servername your-instance.com
```
## Authentication Issues
### "Unauthorized" or "Token not supplied"
**Symptoms:**
```
-- ERROR: Unauthorized: token not supplied
-- Authentication failed
```
**Solutions:**
1. **Check OAuth credentials:**
```bash
# Verify token exists
cat ~/.config/ttyverse/ttyverse_rc | grep tokenkey
# Check file permissions
ls -la ~/.config/ttyverse/
```
2. **Re-authenticate:**
```bash
# Remove old credentials
rm ~/.config/ttyverse/oauth_credentials
rm ~/.config/ttyverse/ttyverse_rc
# Restart TTYverse for fresh setup
./ttyverse.pl
```
3. **Check token validity:**
```bash
# Test token manually
TOKEN=$(grep tokenkey ~/.config/ttyverse/ttyverse_rc | cut -d= -f2)
curl -H "Authorization: Bearer $TOKEN" https://your-instance.com/api/v1/accounts/verify_credentials
```
### OAuth Setup Fails
**Symptoms:**
- Browser doesn't open during setup
- "Failed to get authorization code"
- OAuth redirect fails
**Solutions:**
1. **Manual OAuth setup:**
- Copy the authorization URL from TTYverse
- Open in browser manually
- Copy authorization code back to TTYverse
2. **Check browser setup:**
```bash
# Test browser detection
echo $DISPLAY
which xdg-open firefox chrome
```
3. **Alternative authentication:**
- Use different device for OAuth
- Try text-based browser
- Check server's OAuth settings
## Performance Issues
### Slow Timeline Loading
**Symptoms:**
- Long delays fetching posts
- Timeouts during refresh
**Solutions:**
1. **Adjust refresh settings:**
```bash
# Increase refresh interval
/set effpause 300
# Reduce post count
/set timeline_count 15
```
2. **Check network speed:**
```bash
# Test connection speed to server
time curl -I https://your-instance.com/
```
3. **Server performance:**
- Try different instance
- Check server status
- Use smaller media uploads
### High Memory Usage
**Symptoms:**
- TTYverse consuming excessive RAM
- System becoming unresponsive
**Solutions:**
1. **Reduce cache size:**
```bash
# Edit config to reduce cached posts
echo "timeline_cache=50" >> ~/.config/ttyverse/ttyverse_rc
```
2. **Restart periodically:**
```bash
# Exit and restart TTYverse
/quit
./ttyverse.pl
```
3. **Monitor memory:**
```bash
# Check TTYverse memory usage
ps aux | grep ttyverse
top -p $(pgrep ttyverse)
```
## Media Upload Issues
### Media Upload Fails
**Symptoms:**
```
-- ERROR: Media upload failed
-- Response: {"error":"File too large"}
```
**Solutions:**
1. **Check file size:**
```bash
# Check file size
ls -lh /path/to/file
# Common limits:
# Images: 8MB on Mastodon
# Video/Audio: 40MB on Mastodon
```
2. **Verify file format:**
```bash
# Check MIME type
file --mime-type /path/to/file
# Supported: image/*, audio/*, video/*
```
3. **Test with smaller file:**
```bash
# Create test image
convert -size 100x100 xc:red test.jpg
/media test.jpg
```
### Alt-text Issues
**Symptoms:**
- Upload cancelled for images
- Alt-text prompt not appearing
**Solutions:**
1. **Provide alt-text:**
- Always describe images meaningfully
- Don't leave alt-text empty
- Use descriptive, concise language
2. **Check file type detection:**
```bash
# Verify file is detected as image
file --mime-type /path/to/image.jpg
# Should show: image/jpeg
```
## Sound and Extension Issues
### No Sound Notifications
**Symptoms:**
- Sound notifications not playing
- Silent operation
**Solutions:**
1. **Check sound files:**
```bash
# Verify sound files exist
ls ~/.local/share/ttyverse/sounds/default/
# Test sound playback
paplay ~/.local/share/ttyverse/sounds/default/default.ogg
```
2. **Check audio system:**
```bash
# Test system audio
speaker-test -c 2 -t wav
# Check PulseAudio
pulseaudio --check
```
3. **Install sound dependencies:**
```bash
# Install PulseAudio utils
sudo apt install pulseaudio-utils # Debian/Ubuntu
sudo pacman -S pulseaudio # Arch Linux
```
### Extension Loading Fails
**Symptoms:**
```
** ERROR: Failed to load extension soundpack.pl
```
**Solutions:**
1. **Check extension files:**
```bash
# Verify extensions exist
ls ~/.local/share/ttyverse/extensions/
# Check file permissions
chmod +x ~/.local/share/ttyverse/extensions/*.pl
```
2. **Install Perl dependencies:**
```bash
# Common Perl modules needed
cpan Audio::Play::Simple
cpan Desktop::Notify
```
3. **Manual extension loading:**
```bash
# Test extension manually
perl ~/.local/share/ttyverse/extensions/soundpack.pl
```
## Display and Terminal Issues
### Readline Problems
**Symptoms:**
- No command history
- No tab completion
- Broken line editing
**Solutions:**
1. **Install Perl readline:**
```bash
# Install Term::ReadLine::Gnu
sudo apt install libterm-readline-gnu-perl # Debian/Ubuntu
cpan Term::ReadLine::Gnu # Manual install
```
2. **Check terminal compatibility:**
```bash
# Verify terminal type
echo $TERM
# Test readline
perl -MArray::ReadLine::Gnu -e 'print "Readline available\n"'
```
3. **Alternative terminals:**
- Try different terminal emulator
- Use screen or tmux
- Check terminal settings
### Character Encoding Issues
**Symptoms:**
- Garbled text
- Unicode characters display incorrectly
- Emoji problems
**Solutions:**
1. **Check locale settings:**
```bash
# Verify UTF-8 locale
locale
echo $LANG
# Set UTF-8 if needed
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
```
2. **Terminal encoding:**
- Ensure terminal supports UTF-8
- Check terminal preferences
- Try different terminal emulator
## Configuration Issues
### Config File Not Found
**Symptoms:**
```
-- Config file not found
-- Using defaults
```
**Solutions:**
1. **Create config directory:**
```bash
mkdir -p ~/.config/ttyverse/
chmod 700 ~/.config/ttyverse/
```
2. **Check XDG variables:**
```bash
echo $XDG_CONFIG_HOME
echo $HOME
```
3. **Manual config creation:**
```bash
# Create basic config
cat > ~/.config/ttyverse/ttyverse_rc << EOF
effpause=120
verbose=1
readline=1
EOF
```
### Permission Denied Errors
**Symptoms:**
```
-- ERROR: Permission denied writing to config
```
**Solutions:**
1. **Fix permissions:**
```bash
# Set correct permissions
chmod 700 ~/.config/ttyverse/
chmod 600 ~/.config/ttyverse/*
```
2. **Check ownership:**
```bash
# Verify you own the files
ls -la ~/.config/ttyverse/
# Fix ownership if needed
chown -R $USER:$USER ~/.config/ttyverse/
```
## Getting Debug Information
### Enable Debug Output
```bash
# Run with verbose output
./ttyverse.pl -verbose
# Enable debug in session
/debug
/verbose
```
### Collect System Information
```bash
# System info
uname -a
perl --version
curl --version
# TTYverse info
./ttyverse.pl -version
# Config info
ls -la ~/.config/ttyverse/
cat ~/.config/ttyverse/ttyverse_rc | grep -v tokenkey
```
### Log Analysis
```bash
# Check for error patterns
grep -i error debug.log
grep -i failed debug.log
grep -i timeout debug.log
# Timeline of events
tail -f debug.log
```
## Reporting Issues
When reporting bugs, include:
1. **TTYverse version:** `./ttyverse.pl -version`
2. **System info:** `uname -a` and `perl --version`
3. **Error messages:** Copy exact error text
4. **Steps to reproduce:** What you were doing when it failed
5. **Debug output:** Run with `-verbose` and include relevant logs
6. **Configuration:** Sanitized config (remove tokens!)
**Report at:** https://git.stormux.org/storm/ttyverse/issues
---
**See also:** [FAQ](FAQ) | [Configuration](Configuration) | [Getting Started](Getting-Started)
*Last updated: 2025-07-28*