gaming-image-files/home/stormux/Documents/managing_files.md

File Management

The Stormux Gaming Image includes both upload and download servers to help you transfer files between your gaming system and other devices on your network. Both servers use web browsers for easy file management.

Upload Server

The upload server allows you to transfer files from other devices to your Stormux Gaming Image.

Starting the Upload Server

1. Navigate to the Media menu in the main game launcher
2. Select Upload Files
3. The server will start and announce the IP address and port
4. Example: "Upload server running on 192.168.1.100 port 5000"
5. Press any key while the server is running to hear the address and port again

The server will continue running until you press Control+C to stop it, or until you restart the system.

Using the Upload Server

From Another Device

1. Make sure both devices are on the same network
2. Open a web browser on your phone, tablet, or computer
3. Go to the address announced by the server
4. Example: http://192.168.1.100:8000

Web Interface

The upload page provides several options for different file types:

Music Files

• Purpose: Add music to your ~/Music directory
• Best Practice: Upload artist folders containing album subdirectories
• Supported Formats: MP3, FLAC, OGG, Opus, and other common audio formats
• Organization: The music player works best with Artist/Album folder structure

ROM Files

• Purpose: Add game ROMs for emulators
• Destination: Files go to ~/Roms directory
• Organization: Create subdirectories by console type (e.g., nes, snes, gameboy)
• Supported Formats: Varies by emulator system

Voxin Voice Packages

• Purpose: Install additional TTS voices
• Format: Must follow the pattern voxin-language-name-quality-4version.tgz
• Installation: Automatic after upload
• Note: First voice uploaded becomes the default
• Recommendation: Only upload one voice package

Other Files

• Purpose: General file uploads
• Destination: Files are placed in ~/Downloads
• Manual Organization: You'll need to move files to appropriate directories manually
• Use Cases:
  • Game translation files (like dict.dat for Bokurano Daibouken 3)
  • Application installers
  • Documents and other files

File Upload Process

1. Select File Type: Choose the appropriate category for your file
2. Choose Files: Click "Choose Files" or "Browse" to select files from your device
3. Multiple Files: You can select multiple files at once if supported
4. Upload: Click the upload button to begin transfer
5. Progress: You'll see upload progress for each file
6. Completion: The server will confirm successful uploads

Supported File Operations

Music Upload

• Individual Files: Upload single songs
• Album Folders: Upload entire album directories
• Artist Folders: Upload artist folders with multiple albums (recommended)
• Automatic Organization: Files maintain their folder structure

ROM Upload

• Individual ROMs: Upload single game files

Voice Package Installation

• Automatic Detection: Server recognizes Voxin package format
• Automatic Installation: Extracts and configures voice without user intervention
• Voice Activation: New voice becomes active immediately
• Confirmation: You'll hear a message in the new voice if installation succeeds

Network Requirements

Same Network

Both your Stormux Gaming Image and the device you're uploading from must be connected to the same network:

• WiFi: Both devices on the same WiFi network
• Ethernet: Gaming image connected via Ethernet, other device on same router
• Mixed Connection: One device WiFi, one Ethernet, but same router

Internet Connection

• Not Required: The upload server works on local network only
• WiFi Setup: Use "Configure Internet" in System menu to connect to WiFi
• Network Tools: IP address information available in Accessories menu

Troubleshooting

Can't Access Upload Page

• Check Network: Ensure both devices are on the same network
• Verify Address: Press any key while server is running to hear the address again
• Firewall: Server may be blocked by network firewall
• Restart Server: Stop with Control+C and restart from System menu

Upload Fails

• File Size: Very large files may timeout
• Network Stability: Ensure stable network connection
• File Format: Some file types may not be supported
• Storage Space: Check available disk space on gaming image

Voxin Voice Not Working

• File Format: Ensure filename matches exact pattern required
• File Integrity: Re-download voice package if corrupted
• Multiple Voices: Only first uploaded voice becomes default
• Manual Configuration: Additional voices require manual setup

Files Not Appearing

• Music: Check ~/Music directory, may need to restart music player
• ROMs: Check ~/Roms directory and appropriate system subdirectory
• Other Files: Check ~/Downloads directory
• Permissions: Files should have correct user ownership automatically

File Organization Tips

Music Organization

~/Music/
├── Artist Name/
│   ├── Album 1/
│   │   ├── 01 - Song Title.mp3
│   │   └── 02 - Another Song.mp3
│   └── Album 2/
│       ├── 01 - Track One.mp3
│       └── 02 - Track Two.mp3

ROM Organization

~/Roms/
├── nes/
│   ├── Super Mario Bros.nes
│   └── Legend of Zelda.nes
├── snes/
│   ├── Super Metroid.sfc
│   └── Chrono Trigger.smc
└── gameboy/
    ├── Tetris.gb
    └── Pokemon Red.gb

Security Considerations

Local Network Only

• The upload server only accepts connections from the local network
• Files cannot be uploaded from the internet
• Server stops when you close it or restart the system

File Safety

• Only upload files from trusted sources
• Be cautious with executable files
• Scan files for malware on the source device before uploading

Network Safety

• Only run the upload server on trusted networks
• Stop the server when not actively uploading files
• Be aware that anyone on your network can access the upload page while it's running

Alternative File Transfer Methods

Magic Wormhole

• Available on the system for secure file transfers
• Use from terminal (TTY2) for direct device-to-device transfer
• More secure than upload server for sensitive files

USB Storage

• Files can be copied directly via USB drives
• Mount USB drives manually from terminal if needed
• Good for large file transfers or offline situations

Download Server

The download server allows you to retrieve files from your Stormux Gaming Image to other devices on your network.

Starting the Download Server

1. Navigate to the System menu in the main game launcher
2. Select Download Files
3. The server will start and announce the IP address and port
4. Example: "Download server running on 192.168.1.100 port 8000"
5. Press any key while the server is running to hear the address and port again
6. Press 'q' to quit the server cleanly

The server serves files from your home directory (/home/stormux) and all its subdirectories.

Using the Download Server

From Another Device

1. Make sure both devices are on the same network
2. Open a web browser on your phone, tablet, or computer
3. Go to the address announced by the server
4. Example: http://192.168.1.100:8000

Browsing Files

The download server provides a simple directory listing interface:

• Navigate Directories: Click on folder names to browse subdirectories
• Download Files: Click on file names to download them
• Parent Directory: Use "Parent Directory" links to go back up
• File Information: See file sizes and modification dates

Accessible Directories

From the download server, you can access:

• Music/: Your music collection organized by artist/album
• Roms/: Game ROM files organized by console system
• Downloads/: General downloaded files and utilities
• Documents/: Text files, documentation, and guides
• Desktop/: Desktop files and shortcuts
• .local/: Local application data and configurations
• And more: Any directory, subdirectory, or file in your home folder

File Downloads

What Gets Announced

The download server will speak announcements for actual file downloads only:

• Music Files: MP3, OGG, FLAC, WAV files
• ROM Files: NES, SNES, disk images, etc.
• Documents: PDF, text files
• Archives: ZIP, TGZ, TAR files
• Other Content: Any files with recognizable extensions

What Stays Quiet

To avoid being too chatty, the server won't announce:

• Directory Browsing: Simply navigating folders
• Web Assets: Favicon, CSS, JavaScript files
• Multiple Requests: Repeated access to the same files

Common Use Cases

Save Game Backup

• Browse to game-specific directories
• Download save files to backup on other devices
• Useful before system updates or changes

Music Collection Access

• Browse your ~/Music directory
• Download specific songs or albums
• Share music with other devices on your network

ROM File Sharing

• Access your game collection from other devices
• Download ROMs to play on other systems
• Backup rare or hard-to-find ROM files

Configuration Backup

• Download configuration files from .config directories
• Backup custom game settings
• Save important system configurations

Network Requirements

Same Network Connection

Both your Stormux Gaming Image and the downloading device must be on the same network:

• Local Network Only: Server only accepts local network connections
• WiFi or Ethernet: Either connection type works
• Router-Based: Both devices connected through the same router

No Internet Required

• The download server works entirely on your local network
• No internet connection needed for file transfers
• Files never leave your local network

Security Considerations

Access Control

• Local Network Only: Server rejects external internet requests
• No Authentication: Anyone on your local network can access files
• Read-Only Access: Files can only be downloaded, not modified
• Temporary Access: Server stops when you quit it

Best Practices

• Run When Needed: Only start the server when actively downloading files
• Trusted Networks: Only use on home or trusted networks
• Monitor Access: Server announces file downloads so you know what's being accessed
• Clean Shutdown: Always use 'q' to quit cleanly

Troubleshooting

Can't Access Download Server

• Check Network: Ensure both devices are on same network
• Verify Address: Press any key while server is running to hear address again
• Port Conflicts: If port 8000 is busy, server will announce the error
• Firewall: Network firewall may block access

Downloads Fail or Stop

• Large Files: Very large files may take time or timeout
• Network Stability: Ensure stable network connection
• Browser Limits: Some browsers limit download sizes
• Storage Space: Check available space on downloading device

Server Won't Start

• Port In Use: Another service may be using port 8000
• Network Problems: Check that system has network connectivity

Speech Issues

• No Announcements: Check that speech-dispatcher is running
• Wrong Information: Press any key to hear current server information
• Too Many Announcements: Server now only announces actual file downloads

Alternative File Sharing Methods

Magic Wormhole

• Available for secure file transfers
• Use from terminal for device-to-device transfer
• More secure for sensitive files

USB Storage

• Copy files directly to USB drives
• Good for large transfers or offline situations
• Mount USB drives from terminal if needed

Network File Sharing

• DLNA server available for media sharing
• Can serve files to other network devices
• One-way sharing from gaming image to other devices

The download server complements the upload server perfectly - upload files when you want to add content to your gaming system, and download files when you need to retrieve content from it. Both servers make file management easy and accessible from any device on your network.