# StormFM

A dialog-based file manager optimized for screen readers and terminal users.

## Description

StormFM is a lightweight, accessible file manager built with bash and dialog. It provides an intuitive interface for navigating directories, managing files, and performing common operations without leaving the terminal. Originally created in 2018 and updated in 2025 with modern improvements.

## Features

- **Accessible Design**: Single-pane layout optimized for screen readers
- **Smart File Handling**: 
  - Media playback with mpv (audio/video files)
  - PDF viewing via HTML conversion
  - Archive extraction (tar, zip, rar, 7z, etc.)
  - Text file viewing with configurable pager
- **File Operations**: Copy, move, rename, delete with confirmations
- **Modern Sharing**: Send files via Magic Wormhole
- **Configurable**: XDG-compliant configuration with sensible defaults
- **Keyboard Driven**: Navigate with arrow keys, no mouse required

## Installation

### Dependencies

**Required:**
- `dialog` - Terminal UI framework
- `bc` - Basic calculator for file size formatting

**Optional (for full functionality):**
- `mpv` - Media playback
- `w3m` - Text file viewing and PDF display
- `pdftohtml` - PDF to HTML conversion (poppler-utils package)
- `wormhole` - Secure file sharing
- Standard archive tools: `tar`, `unzip`, `unrar`, `7z`

### Install Dependencies

**Debian/Ubuntu:**
```bash
sudo apt install dialog bc mpv w3m poppler-utils magic-wormhole
```

**Arch Linux:**
```bash
sudo pacman -S dialog bc mpv w3m poppler magic-wormhole
```

**Fedora:**
```bash
sudo dnf install dialog bc mpv w3m poppler-utils magic-wormhole
```

### Install StormFM

1. Download the script:
```bash
wget https://git.stormux.org/storm/stormfm/raw/branch/main/stormfm
chmod +x stormfm
```

2. Install system-wide (optional):
```bash
sudo cp stormfm /usr/local/bin/
```

## Usage

### Basic Navigation
```bash
./stormfm              # Start in current directory
./stormfm /path/dir    # Start in specific directory
```

### Interface
- **Arrow Keys**: Navigate file list
- **Enter**: Open files/enter directories
- **Extra Button**: File actions menu (copy, move, rename, delete, extract, wormhole)
- **Help Button**: Show file properties
- **Escape/Cancel**: Go back or exit

### File Types
- **Directories**: Navigate by pressing Enter
- **Media Files**: Automatically play with mpv
- **PDF Files**: Convert to HTML and view in browser/pager
- **Text Files**: Open in configured pager (w3m by default)
- **Archives**: Extract via actions menu
- **Any File**: Send via Magic Wormhole from actions menu

## Configuration

StormFM creates a configuration file at `~/.config/stormux/stormfm/config` on first run.

### Available Settings

```bash
# Display options
showHidden=false          # Show hidden files (dotfiles)
showSizes=false           # Show file sizes in directory listings

# Applications (leave empty for defaults)
editorCmd=""              # Text editor (default: $EDITOR or nano)
pagerCmd=""               # File viewer (default: $PAGER or w3m)
mediaPlayerCmd=""         # Media player (default: mpv)

# Media player options
mediaPlayerFlags="--no-video --quiet"  # Flags for mpv
```

### Examples

```bash
# Use vim and less
editorCmd="vim"
pagerCmd="less"

# Show file sizes and hidden files
showSizes=true
showHidden=true

# Use VLC for media with custom flags
mediaPlayerCmd="vlc"
mediaPlayerFlags="--intf dummy --play-and-exit"
```

## Supported File Formats

### Media (Auto-playback)
**Audio**: mp3, flac, ogg, wav, aac, m4a, opus, and 30+ more  
**Video**: mp4, avi, mkv, mov, webm, and 40+ more  
**Playlists**: m3u, m3u8, pls, xspf, cue

### Archives (Extractable)
tar, gz, tgz, bz2, tbz2, xz, txz, zip, rar, 7z

### Documents
PDF (converted to HTML for accessibility)

## Magic Wormhole Integration

Send files securely between machines:

1. Select file → Extra → "Send via Magic Wormhole"
2. Share the generated code with recipient
3. Recipient runs: `wormhole receive <code>`

No accounts, servers, or configuration required!

## License

GPL v3 or later - See header in script file.

## Author

Storm Dragon <storm_dragon@stormux.org>

## Contributing

This project is hosted at https://git.stormux.org/storm/stormfm

Bug reports, feature requests, and patches welcome!