diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index c8af673..0000000 --- a/CLAUDE.md +++ /dev/null @@ -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 \ No newline at end of file