unified screen reader settings across images.
This commit is contained in:
Storm Dragon
@@ -1,153 +0,0 @@
|
|||||||
# CLAUDE.md
|
|
||||||
|
|
||||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
||||||
|
|
||||||
## Project Overview
|
|
||||||
|
|
||||||
This is the gaming-image-files repository for the Stormux gaming image - a specialized Linux distribution designed for blind and visually impaired gamers. The repository contains system configuration files, utilities, and scripts that are deployed to create a gaming-focused live USB/installable image.
|
|
||||||
|
|
||||||
## Repository Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
/
|
|
||||||
├── etc/ # System configuration files
|
|
||||||
│ ├── speech-dispatcher/ # Speech synthesis configuration
|
|
||||||
│ ├── sudoers.d/ # Sudo permissions
|
|
||||||
│ ├── systemd/ # System services
|
|
||||||
│ └── vconsole.conf # Virtual console configuration
|
|
||||||
├── home/stormux/ # User home directory files
|
|
||||||
│ └── Documents/ # User documentation
|
|
||||||
├── root/ # Root user scripts
|
|
||||||
│ ├── live-update.sh # Live system update script
|
|
||||||
│ └── sanitize.sh # Image preparation/cleanup script
|
|
||||||
└── usr/ # System utilities and applications
|
|
||||||
├── lib/systemd/ # System service files
|
|
||||||
├── local/bin/ # Custom utilities and launchers
|
|
||||||
└── share/ # Shared resources (sounds, keymaps)
|
|
||||||
```
|
|
||||||
|
|
||||||
## Key Applications and Architecture
|
|
||||||
|
|
||||||
### Game Launcher (`game_launcher.py`)
|
|
||||||
The main menu system for the gaming image. Built with:
|
|
||||||
- **curses** for terminal UI
|
|
||||||
- **speechd** for speech synthesis
|
|
||||||
- **configparser** for settings management
|
|
||||||
- **Section-based menu system** with dynamic service management
|
|
||||||
- **Sound effects** with simpleaudio
|
|
||||||
- **Terminal state management** for launching games
|
|
||||||
|
|
||||||
### Music Player (`music_player.py`)
|
|
||||||
Self-voiced music player with:
|
|
||||||
- **Artist/Album navigation** with folder structure support
|
|
||||||
- **MPV integration** for playback
|
|
||||||
- **Random/Sequential playback modes**
|
|
||||||
- **Nested menu navigation** with breadcrumb support
|
|
||||||
|
|
||||||
### ROM Launcher (`rom_launcher.py`)
|
|
||||||
Emulator ROM management system:
|
|
||||||
- **Auto-discovery** of ROM files from ~/Roms directory
|
|
||||||
- **Section-based organization** by emulator type
|
|
||||||
- **Dynamic menu generation** from filesystem structure
|
|
||||||
|
|
||||||
### Specialized Utilities
|
|
||||||
- **OCR system** (`ocr.py`) - Screen reading with Tesseract
|
|
||||||
- **Apple IIe launcher** (`apple_2e.py`) - Disk image management
|
|
||||||
- **Voice configuration** (`set-voice.py`) - Speech-dispatcher module selection
|
|
||||||
- **Speech rate control** (`speechd_rate.py`) - System-wide speech rate configuration
|
|
||||||
|
|
||||||
## Development Commands
|
|
||||||
|
|
||||||
### Image Preparation
|
|
||||||
```bash
|
|
||||||
# Clean system for image creation
|
|
||||||
./root/sanitize.sh
|
|
||||||
|
|
||||||
# Clean with zero-fill for better compression
|
|
||||||
./root/sanitize.sh -0
|
|
||||||
|
|
||||||
# Update live system from git
|
|
||||||
./root/live-update.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
### System Installation
|
|
||||||
```bash
|
|
||||||
# Install system to hard drive (x86_64 only)
|
|
||||||
./usr/local/bin/install_to_disk.sh
|
|
||||||
|
|
||||||
# Run system diagnostics
|
|
||||||
./usr/local/bin/diagnostics.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
### Common Python Application Pattern
|
|
||||||
Most Python applications follow this pattern:
|
|
||||||
1. **Speech initialization** with speechd
|
|
||||||
2. **Curses-based UI** with proper cleanup
|
|
||||||
3. **Configuration management** with configparser
|
|
||||||
4. **Graceful terminal handling** for game launches
|
|
||||||
5. **Sound feedback** for navigation
|
|
||||||
|
|
||||||
## Accessibility Architecture
|
|
||||||
|
|
||||||
### Speech Integration
|
|
||||||
- All applications use **speech-dispatcher** via Python speechd module
|
|
||||||
- **Configurable speech rates** with persistent settings
|
|
||||||
- **Interrupt-based speech** for responsive navigation
|
|
||||||
- **Module selection** system for different TTS engines
|
|
||||||
|
|
||||||
### Audio Feedback
|
|
||||||
- **Sound effects** for menu navigation (menu_move.wav, menu_select.wav, etc.)
|
|
||||||
- **Audio cues** for different menu sections
|
|
||||||
- **Volume control** integrated into applications
|
|
||||||
|
|
||||||
### Terminal Management
|
|
||||||
- **Proper curses cleanup** when launching external applications
|
|
||||||
- **Terminal state restoration** after game exits
|
|
||||||
- **Process group management** for signal handling
|
|
||||||
|
|
||||||
## File Organization Patterns
|
|
||||||
|
|
||||||
### Configuration Files
|
|
||||||
- User configs in `~/.config/stormux/`
|
|
||||||
- System configs follow standard Linux paths
|
|
||||||
- **Backup configurations** (e.g., speechd.conf.bak)
|
|
||||||
|
|
||||||
### Game Integration
|
|
||||||
- Games launched via `startx` with `GAME` environment variable
|
|
||||||
- **ROM organization** by emulator type in ~/Roms/
|
|
||||||
- **Music organization** by Artist/Album in ~/Music/
|
|
||||||
|
|
||||||
### System Services
|
|
||||||
- **Accessibility services** (Fenrir, Braille support)
|
|
||||||
- **Media services** (DLNA server)
|
|
||||||
- **Optional services** (SSH, Bluetooth) with toggle support
|
|
||||||
|
|
||||||
## Key Design Principles
|
|
||||||
|
|
||||||
1. **Accessibility First** - All interfaces must be fully navigable by speech
|
|
||||||
2. **Self-Voiced** - Applications provide their own speech feedback
|
|
||||||
3. **Consistent Navigation** - Arrow keys, Enter, Escape patterns across applications
|
|
||||||
4. **Graceful Degradation** - Applications handle speech failures gracefully
|
|
||||||
5. **Clean Exits** - Proper resource cleanup before launching games or exiting
|
|
||||||
|
|
||||||
## Security Considerations
|
|
||||||
|
|
||||||
- **Sudo integration** for system configuration changes
|
|
||||||
- **File path sanitization** in ROM/disk launchers
|
|
||||||
- **Secure temporary file handling** in utilities
|
|
||||||
- **Process isolation** for game launches
|
|
||||||
|
|
||||||
## Testing and Validation
|
|
||||||
|
|
||||||
- Test speech functionality with different TTS engines
|
|
||||||
- Verify terminal state restoration after game exits
|
|
||||||
- Test accessibility with screen readers (Fenrir)
|
|
||||||
- Validate file handling with special characters in filenames
|
|
||||||
- Test system service toggle functionality
|
|
||||||
|
|
||||||
## Known Limitations
|
|
||||||
|
|
||||||
- **Platform-specific features** (e.g., Steam on x86_64 only)
|
|
||||||
- **USB detection** for installer availability
|
|
||||||
- **Sudo requirements** for system configuration changes
|
|
||||||
- **Terminal dependency** for proper cleanup and restoration
|
|
||||||
Reference in New Issue
Block a user