streamflow/desktop-app/README.md

# StreamFlow Desktop Application

Linux AppImage application for StreamFlow IPTV streaming platform.

## Features

- 🔐 Secure server connection with credential management
- 🔑 Full 2FA (Two-Factor Authentication) support
- 🌍 Multi-language support (English, Romanian)
- 🎬 Native media codec support for smooth playback
- 🔄 Automatic feature parity with web application
- 💾 Encrypted credential storage
- 🎨 Native desktop experience
- 🔔 System tray integration with quick actions
- ⬆️ Auto-update functionality with progress tracking
- 📺 Picture-in-Picture mode for multitasking
- 📡 Offline mode with content caching
- 📱 Chromecast support for streaming to TV

## Installation

### Prerequisites

- Linux distribution (Ubuntu 18.04+, Debian 10+, Fedora 30+, etc.)
- GLIBC 2.28 or newer
- X11 or Wayland display server

### Install from AppImage

1. Download the latest `.AppImage` file from releases
2. Make it executable:
   ```bash
   chmod +x StreamFlow-*.AppImage
   ```
3. Run the application:
   ```bash
   ./StreamFlow-*.AppImage
   ```

### Optional: Desktop Integration

To integrate with your desktop environment:

```bash
# Using AppImageLauncher (recommended)
sudo apt install appimagelauncher  # Ubuntu/Debian
# Then run the AppImage - it will be automatically integrated

# Or manually
./StreamFlow-*.AppImage --appimage-extract
sudo mv squashfs-root /opt/streamflow
sudo ln -s /opt/streamflow/AppRun /usr/local/bin/streamflow
```

## Building from Source

### Development Setup

1. Install Node.js 18+ and npm
2. Navigate to the desktop-app directory:
   ```bash
   cd desktop-app
   ```
3. Install dependencies:
   ```bash
   npm install
   ```
4. Run in development mode:
   ```bash
   npm run dev
   ```

### Building AppImage

To build the AppImage for distribution:

```bash
# Build for current architecture
npm run build:appimage

# The AppImage will be created in the dist/ directory
```

To build for multiple architectures:

```bash
# Build for x64
npm run build:linux -- --x64

# Build for arm64
npm run build:linux -- --arm64
```

## Usage

### First Launch

1. Launch the application
2. Enter your StreamFlow server URL (e.g., `https://your-server.com`)
3. Click "Test Connection" to verify server accessibility
4. Enter your username and password
5. (Optional) Check "Remember credentials" for automatic login
6. Click "Connect"

### 2FA Authentication

If you have 2FA enabled on your account:

1. Complete the standard login (username/password)
2. You'll be automatically prompted for your 2FA code
3. Enter your 6-digit authenticator code
4. Or use one of your 8-character backup codes

### Changing Server

To connect to a different server:

1. Go to **File** → **Change Server** in the menu
2. Enter the new server URL
3. Test connection and enter credentials

### System Tray

The application minimizes to the system tray instead of closing:

- **Show/Hide**: Click tray icon or use menu to toggle window visibility
- **Picture-in-Picture**: Open floating PiP window from tray menu
- **Check for Updates**: Manually check for app updates
- **Quit**: Completely exit the application

### Auto-Updates

StreamFlow Desktop checks for updates automatically:

- Update checks run on startup (after 5-second delay)
- Manual check: **Help** → **Check for Updates**
- Download progress shown with percentage
- User prompted to restart after download completes

### Picture-in-Picture Mode

Watch content in a floating window while working:

1. **Open PiP**: **View** → **Picture-in-Picture** (or from tray menu)
2. PiP window stays on top of other windows
3. **Close PiP**: Click close button on PiP window or use **View** → **Close Picture-in-Picture**

### Offline Mode

Cache content for offline playback:

- **Toggle Offline Mode**: **File** → **Toggle Offline Mode**
- Cached content expires after 24 hours (configurable)
- Clear cache: **File** → **Clear Offline Cache**
- Cache stored in: `~/.config/streamflow-desktop/offline-cache.json`

### Chromecast

Stream to Chromecast devices on your network:

1. **Discover Devices**: **Playback** → **Discover Chromecast Devices**
2. Available devices shown in notification
3. Cast media from web interface when Chromecast detected
4. 5-second scan timeout for device discovery

## Codec Support

The AppImage includes native codec support for:

- **Video Codecs**: H.264, H.265 (HEVC), VP8, VP9, AV1
- **Audio Codecs**: AAC, MP3, Opus, Vorbis, AC3, E-AC3
- **Containers**: MP4, MKV, WebM, TS, M3U8 (HLS)

Hardware acceleration is automatically enabled when available:

- **Intel**: VA-API (Quick Sync)
- **AMD**: VA-API
- **NVIDIA**: NVDEC (if proprietary drivers installed)

## Troubleshooting

### AppImage won't run

**Error: "cannot execute binary file"**
```bash
# Make sure it's executable
chmod +x StreamFlow-*.AppImage
```

**Error: "FUSE not installed"**
```bash
# Install FUSE
sudo apt install fuse libfuse2  # Ubuntu/Debian
sudo dnf install fuse fuse-libs  # Fedora
```

**Or extract and run manually:**
```bash
./StreamFlow-*.AppImage --appimage-extract
cd squashfs-root
./AppRun
```

### Connection Issues

1. Verify server URL is correct (must include `http://` or `https://`)
2. Check firewall settings allow connection to server
3. Ensure server is running and accessible
4. Try accessing server URL in a web browser first

### Video Playback Issues

**Choppy playback:**
- Enable hardware acceleration in your desktop settings
- Close other applications using GPU resources
- Check server encoding settings

**No video/audio:**
- Verify codec support: `ffmpeg -codecs`
- Check audio output device in system settings
- Ensure server stream format is compatible

### 2FA Not Working

1. Ensure time synchronization is correct:
   ```bash
   timedatectl status
   ```
2. If time is off, sync it:
   ```bash
   sudo timedatectl set-ntp true
   ```
3. Try using a backup code instead

## Security

- Credentials are encrypted using electron-store
- All communication with server uses HTTPS (recommended)
- Session tokens expire after 7 days
- Automatic logout on window close (if credentials not saved)

## Language Support

Supported languages:
- English (en)
- Romanian (ro)

To change language:
- Use the language selector in the connection window
- Or in the web interface settings

## System Requirements

### Minimum
- **CPU**: Dual-core 1.6 GHz
- **RAM**: 2 GB
- **Disk**: 200 MB for app + storage for recordings
- **Display**: 1024x768

### Recommended
- **CPU**: Quad-core 2.0 GHz+ with hardware video decode
- **RAM**: 4 GB+
- **Disk**: 500 MB + storage for recordings
- **Display**: 1920x1080
- **GPU**: Hardware acceleration support (VA-API, NVDEC)

## Known Issues

- Some older GPUs may not support hardware acceleration for H.265
- Wayland may have issues with screen sharing/recording features
- Some distributions require manual FUSE installation

## Contributing

Found a bug or want to contribute? Please open an issue or pull request in the main repository.

## License

MIT License - See LICENSE file for details

## Support

For support:
1. Check the documentation at `/docs`
2. Open an issue on GitHub
3. Contact your server administrator

## Version History

### 1.0.0 (2024-12-12)
- Initial release
- Server connection management
- 2FA support
- Multi-language support (EN, RO)
- Native codec support
- Credential encryption