beStream

A cross-platform streaming application with a Netflix-style interface

Features • Platforms • Installation • Development • Building • Documentation

---

✨ Features

• 🎬 Stream Movies & TV Shows - Real-time streaming via WebTorrent
• 🎨 Netflix-Style UI - Beautiful, responsive dark theme interface
• 📱 Cross-Platform - Windows, macOS, Linux, and Android support
• 🔍 Smart Search - Search across multiple content providers
• 📺 TV Show Support - Browse seasons, episodes with auto-play
• 📥 Download Manager - Queue and manage downloads
• 📚 Watch History - Track your progress across devices
• ⭐ Watchlist - Save content for later
• 🎯 Quality Selection - Choose from 480p to 4K
• 🔗 Integrations - Connect with Radarr, Sonarr, and Lidarr
• 🌐 Subtitle Support - Load external subtitles (SRT)

---

🖥️ Platforms

Platform	Status	Technology
Windows	✅ Supported	Electron
macOS	✅ Supported	Electron
Linux	✅ Supported	Electron
Android	✅ Supported	Capacitor + NodeJS
iOS	🚧 Planned	Capacitor
Web	🔧 Dev Only	Vite

---

📦 Installation

Prerequisites

• Node.js 18.x or higher
• npm 9.x or higher
• Git

For Android builds:

• Android Studio with SDK 33+
• Java JDK 17+

Quick Start

# Clone the repository
git clone https://github.com/yourusername/bestream.git
cd bestream

# Install dependencies
npm install

# Install server dependencies
npm run server:install

# Start development server
npm run dev:all

The app will be available at http://localhost:5173 with the backend server at http://localhost:3001.

---

🛠️ Development

Available Scripts

Command	Description
npm run dev	Start Vite dev server (frontend only)
npm run dev:all	Start frontend + backend server
npm run server	Start backend server only
npm run build	Build frontend for production
npm run lint	Run ESLint
npm run electron:dev	Start Electron in dev mode

Project Structure

beStream/
├── src/                 # React frontend
│   ├── components/      # UI components
│   │   ├── layout/      # Header, Sidebar, Layout
│   │   ├── movie/       # Hero, MovieRow, MovieCard
│   │   ├── tv/          # TV show components
│   │   ├── player/      # Video player components
│   │   └── ui/          # Button, Modal, Skeleton, etc.
│   ├── pages/           # Route pages
│   ├── hooks/           # Custom React hooks
│   ├── services/        # API and business logic
│   │   ├── api/         # YTS, EZTV, TMDB clients
│   │   ├── streaming/   # Streaming service
│   │   └── server/      # Server management
│   ├── stores/          # Zustand state stores
│   ├── types/           # TypeScript definitions
│   └── utils/           # Utility functions
├── server/              # Node.js backend
│   └── src/
│       ├── routes/      # Express routes
│       │   ├── stream.js    # Streaming endpoints
│       │   └── proxy.js     # API proxy endpoints
│       └── services/    # Backend services
│           ├── torrentManager.js  # WebTorrent client
│           └── transcoder.js      # FFmpeg transcoding
├── electron/            # Electron main process
│   ├── main.ts          # Main process entry
│   └── preload.ts       # Preload scripts
├── android/             # Android native project
├── scripts/             # Build scripts
└── docs/                # Documentation

Tech Stack

Frontend:

• React 18 with TypeScript
• Vite for bundling
• Tailwind CSS for styling
• Zustand for state management
• Framer Motion for animations
• React Router for navigation
• HLS.js for adaptive streaming

Backend:

• Express.js web server
• WebTorrent for P2P streaming
• FFmpeg for HLS transcoding (desktop only)
• WebSocket for real-time updates

Desktop:

• Electron 33
• Custom frameless window
• System tray integration

Mobile:

• Capacitor 7
• capacitor-nodejs plugin
• Embedded Node.js runtime

---

🏗️ Building

Desktop (Electron)

# Windows
npm run build:win

# macOS
npm run build:mac

# Linux
npm run build:linux

Output: release/ directory

Built files:

• Windows: beStream Setup x.x.x.exe
• macOS: beStream-x.x.x.dmg
• Linux: beStream-x.x.x.AppImage

Android

# Debug APK
npm run build:android:apk

# Release APK (signed)
npm run build:android:release

Output: android/app/build/outputs/apk/

Build Process (Android)

The Android build process involves several steps:

1. Build Frontend (npm run build)

   • TypeScript compilation
   • Vite production build
   • Output: dist/

2. Bundle Server (npm run copy-server-to-android)

   • Bundle with esbuild into single file
   • Apply platform polyfills
   • Output: dist/nodejs-v3/index.js

3. Sync Capacitor (npx cap sync android)

   • Copy web assets to Android
   • Update native plugins

4. Build APK (gradlew assembleDebug)

   • Compile Android project
   • Package native + web resources

---

📚 Documentation

Detailed documentation is available in the docs/ directory:

Document	Description
DOCUMENTATION.md	Full technical documentation
GETTING_API_KEYS.md	Setup external API keys
OPENING_PORTS.md	Network configuration guide

---

🔧 Configuration

Environment Variables

Copy the example environment file and configure as needed:

cp .env.example .env

Key environment variables:

Variable	Required	Description
VITE_API_URL	No	Backend server URL (default: http://localhost:3001)
VITE_OPENSUBTITLES_API_KEY	For subtitles	Get free key at opensubtitles.com
VITE_EZTV_USERNAME	No	EZTV authentication (if required)
VITE_EZTV_PASSWORD	No	EZTV authentication (if required)

See .env.example for all available options.

App Settings

Settings are stored locally and persist across sessions:

Setting	Default	Description
Preferred Quality	1080p	Default streaming quality
Language	en	Preferred content language
Auto Play	true	Auto-play next episode
Theme	dark	UI theme (dark/light)
Max Downloads	3	Concurrent download limit

Integration Settings

Connect to media managers for enhanced features:

• Radarr - Movie collection management
• Sonarr - TV show collection management
• Lidarr - Music collection management

Configure in Settings → Integrations.

---

🔌 API Endpoints

Backend Server (Port 3001)

Endpoint	Method	Description
/health	GET	Server health check
/api/stream/start	POST	Start streaming session
/api/stream/:id/status	GET	Get session status
/api/stream/:id/video	GET	Stream video
/api/stream/:id/hls	POST	Start HLS transcoding
/api/eztv/*	GET	EZTV API proxy
/api/yts/*	GET	YTS API proxy
/api/tmdb/*	GET	TMDB API proxy

WebSocket (Port 3001/ws)

Real-time streaming progress updates:

// Connect
const ws = new WebSocket('ws://localhost:3001/ws');

// Subscribe to session
ws.send(JSON.stringify({ type: 'subscribe', sessionId: 'xxx' }));

// Receive updates
ws.onmessage = (e) => {
  const { type, progress, downloadSpeed, peers } = JSON.parse(e.data);
};

---

📱 Android Notes

Requirements

• Android 7.0 (API 24) or higher
• ~100MB storage space
• Internet connection

Limitations

Due to platform constraints, the Android version has some limitations:

Feature	Desktop	Android
HLS Transcoding	✅	❌
uTP Protocol	✅	❌
File Downloads	✅	Limited
FFmpeg Processing	✅	❌

Debugging

# View app logs
adb logcat | grep com.bestream.app

# View Node.js server logs
adb logcat | grep -E "(NodeJS|beStream Server)"

# Install debug build
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

# Uninstall and reinstall
adb uninstall com.bestream.app
adb install android/app/build/outputs/apk/debug/app-debug.apk

---

🐛 Troubleshooting

Common Issues

Server not starting:

# Check if port is in use
netstat -an | grep 3001

# Kill process on port
npx kill-port 3001

Android build fails:

# Clean and rebuild
cd android
./gradlew clean
cd ..
npm run build:android:apk

Video not playing:

• Check server health: curl http://localhost:3001/health
• Verify torrent has seeders
• Try different quality option
• Check browser console for errors

CORS errors in development:

• Ensure Vite proxy is configured
• Check that backend is running on port 3001

---

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

Guidelines

• Write TypeScript for all new code
• Follow existing code style (ESLint + Prettier)
• Use functional components with hooks
• Add tests for new features
• Update documentation as needed

---

⚠️ Disclaimer

This application is intended for educational and personal use only. Users are solely responsible for ensuring they have the legal right to stream or download any content. The developers:

• Do not host any content
• Do not provide torrents or links to copyrighted material
• Are not responsible for user actions
• Encourage compliance with local laws and regulations

---

📄 License

This project is private and proprietary. Unauthorized copying, modification, distribution, or use of this software is strictly prohibited without explicit permission.

---

🙏 Acknowledgments

Special thanks to these amazing projects:

• WebTorrent - Streaming torrent library
• Electron - Desktop application framework
• Capacitor - Cross-platform native runtime
• React - UI library
• Tailwind CSS - Utility-first CSS
• YTS - Movie data provider
• EZTV - TV show data provider
• TMDB - Movie and TV metadata

---

_{Built with ❤️ by the beStream Team}

_{Version 2.4.0 • Last Updated: January 2026}