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:

   chmod +x StreamFlow-*.AppImage
   

3. Run the application:

   ./StreamFlow-*.AppImage
   

Optional: Desktop Integration

To integrate with your desktop environment:

# 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:

   cd desktop-app
   

3. Install dependencies:

   npm install
   

4. Run in development mode:

   npm run dev
   

Building AppImage

To build the AppImage for distribution:

# Build for current architecture
npm run build:appimage

# The AppImage will be created in the dist/ directory

To build for multiple architectures:

# 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"

# Make sure it's executable
chmod +x StreamFlow-*.AppImage

Error: "FUSE not installed"

# Install FUSE
sudo apt install fuse libfuse2  # Ubuntu/Debian
sudo dnf install fuse fuse-libs  # Fedora

Or extract and run manually:

./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:

   timedatectl status
   

2. If time is off, sync it:

   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