beStream/README.md

beStream

A cross-platform movie streaming application with a Netflix-style UI, built with React and capable of running on Android, iOS, Windows, Linux, and macOS.

Features

• 🎬 Netflix-style UI - Beautiful, responsive interface with hero banners, horizontal scrolling rows, and smooth animations
• 🔍 Browse & Search - Filter movies by genre, quality, rating, and more with infinite scroll
• 📥 Real Torrent Streaming - Stream movies via backend server with WebTorrent + FFmpeg transcoding
• 🎥 HLS Playback - Adaptive streaming with HLS.js for smooth playback
• 💾 Offline Downloads - Download movies for offline viewing
• 📝 Watchlist - Save movies to watch later
• 📊 Watch History - Track viewing progress and resume playback
• 🌐 Multi-Platform - Single codebase for all platforms

Architecture

┌─────────────────┐     ┌─────────────────────────────────────┐
│   React App     │────▶│         Node.js Backend             │
│   (Frontend)    │     │                                     │
│   Port: 5173    │◀────│  WebTorrent ──▶ FFmpeg ──▶ HLS     │
└─────────────────┘     │         Port: 3001                  │
                        └─────────────────────────────────────┘

Tech Stack

Component	Technology
UI Framework	React 18 + TypeScript
Build Tool	Vite
Styling	TailwindCSS + Framer Motion
State Management	Zustand
Mobile	Capacitor (iOS/Android)
Desktop	Electron (Windows/Linux/macOS)
Torrent	WebTorrent
Storage	IndexedDB (Dexie.js)

Getting Started

Prerequisites

• Node.js 18+
• npm or yarn
• For iOS: Xcode 14+ (macOS only)
• For Android: Android Studio with SDK 24+
• For Desktop: No additional requirements

Prerequisites

• Node.js 18+
• FFmpeg - Required for video transcoding
  • Windows: winget install FFmpeg or download from https://ffmpeg.org
  • macOS: brew install ffmpeg
  • Linux: sudo apt install ffmpeg

Installation

# Clone the repository
git clone <repository-url>
cd bestream

# Install frontend dependencies
npm install

# Install server dependencies
npm run server:install

Development

# Start both frontend and streaming server
npm run dev:all

# Or start them separately:
npm run dev          # Frontend only (http://localhost:5173)
npm run server       # Backend only (http://localhost:3001)

# Start Electron development
npm run electron:dev

How Streaming Works

1. Click "Play" on any movie
2. Backend downloads torrent via WebTorrent
3. FFmpeg transcodes to HLS format in real-time
4. Frontend plays HLS stream with adaptive quality
5. Watch immediately while download continues in background

Building

# Build web version
npm run build

# Build for Android
npm run build:android

# Build for iOS
npm run build:ios

# Build for Windows
npm run build:win

# Build for macOS
npm run build:mac

# Build for Linux
npm run build:linux

Project Structure

bestream/
├── src/
│   ├── components/       # React components
│   │   ├── ui/           # Base UI components
│   │   ├── movie/        # Movie-related components
│   │   ├── player/       # Video player components
│   │   └── layout/       # Layout components
│   ├── pages/            # Route pages
│   ├── services/         # API and business logic
│   │   ├── api/          # YTS API client
│   │   ├── torrent/      # WebTorrent service
│   │   ├── subtitles/    # OpenSubtitles service
│   │   └── storage/      # IndexedDB service
│   ├── stores/           # Zustand state stores
│   ├── hooks/            # Custom React hooks
│   ├── utils/            # Helper utilities
│   └── types/            # TypeScript definitions
├── electron/             # Electron main process
├── public/               # Static assets
└── docs/                 # Documentation

API Reference

The app uses the YTS API for movie data:

• List Movies: GET /list_movies.json
• Movie Details: GET /movie_details.json
• Movie Suggestions: GET /movie_suggestions.json
• Parental Guides: GET /movie_parental_guides.json

See the YTS API Documentation for more details.

Platform-Specific Notes

Mobile (iOS/Android)

• Torrent streaming uses WebRTC-based WebTorrent
• Downloads are stored in app-specific storage
• Supports picture-in-picture playback

Desktop (Windows/Linux/macOS)

• Full WebTorrent support with DHT
• Downloads can be saved to any location
• System tray integration
• Native menu bar

Configuration

Environment Variables

Create a .env file in the root directory:

# Optional: OpenSubtitles API key for subtitle support
VITE_OPENSUBTITLES_API_KEY=your-api-key

Capacitor Configuration

Edit capacitor.config.ts to customize mobile settings.

Electron Configuration

Edit electron/main.ts to customize desktop settings.

Legal Notice

This application is provided for educational purposes only. It does not host any content and simply provides an interface to the YTS API. Users are responsible for complying with local laws regarding content streaming and downloading.

License

MIT License - See LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Support

For issues and feature requests, please use the GitHub issue tracker.