Clone
2
Media Uploads
Storm Dragon edited this page 2025-07-30 15:30:36 -04:00
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
/media /path/to/file.jpg Optional post message here
Upload Media Only
/media /path/to/file.mp3
TTYverse will:
- Detect the file type automatically
- Prompt for alt-text (images only)
- Upload the media to your server
- 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:
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:
/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
-
File Detection
-- Detected file type: image/jpeg -
Alt-Text Prompt (images only)
-- Images require alt-text for accessibility Enter alt text for filename.jpg: [your description] -
Post Message (optional)
Enter post message (optional): [your message] -
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:
- Check OAuth setup:
ls ~/.config/ttyverse/ - Verify token:
/refreshto test API access - Re-authenticate if needed:
rm ~/.config/ttyverse/*and restart
File permission issues:
- Check file exists:
ls -la /path/to/file - Verify read permissions:
cat /path/to/file > /dev/null - Use absolute paths when possible
Server limits:
- Check file size:
ls -lh /path/to/file - Try smaller files to test limits
- 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
/media ~/photos/garden.jpg Tomatoes are finally ripening!
# Alt-text: "Red and green tomatoes growing on vines in a garden"
Audio with Description
/media ~/recordings/bird-song.mp3 Recorded this morning in the park
Video with Context
/media ~/videos/demo.mp4 Quick demo of the new feature working
Technical Screenshot
/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 | Advanced Features | Basic Usage