Skip to content
TssHackPublic

About

Vispar: movie and series app for Android, iOS, Web, Android TV and desktop

Topics

Resources

Security policy

Stars

57 stars

Watchers

0 watching

Forks

Repository files navigation

Vispar

Movies and series, on every screen you own.
One codebase for Android, iOS, the web, Android TV, Windows, macOS and Linux.

CI Latest release Expo SDK 58 React Native 0.88 TypeScript RTL

Open the web app · فارسی · Download · Developer

Vispar on phone: splash, home, catalog, details and the iOS install guide


Why Vispar

Vispar is a Persian-first (right-to-left) streaming client. It is built to feel native on a phone, comfortable with a TV remote, and at home in a desktop window, without maintaining three apps.

  • One codebase, seven targets. Expo + React Native with react-native-web, wrapped in Electron for desktop.
  • Designed for the room it is in. Bottom tabs on phones, a top bar on wide screens, and a labelled side rail with D-pad focus on TV.
  • Fast to start, honest when offline. A splash that actually tests the connection instead of spinning forever.

Highlights

Splash with a connection test The logo draws itself while two real checks run: the internet, then the content server. If either fails you get a clear page with Retry and Continue offline (your library still works). A banner appears if the connection drops later and clears itself when it returns.
A real player Subtitles (embedded tracks and .srt/.vtt files, Persian-first, with sync and styling), seek bar, ±10/15/30 s skip, double-tap to seek, playback speed, in-player quality switch, fit/fill/stretch, resume where you left off, autoplay next episode, background playback and picture-in-picture.
External players and downloaders VLC, MX Player, mpv, Just Player, Kodi, KMPlayer, XPlayer, nPlayer, Infuse, Outplayer; ADM, 1DM, FDM, system download manager. Installed apps are detected on Android. On the web an .m3u playlist is generated.
Discovery Home slider, continue watching, my list, top rated, genre rails, multi-filter (genre, decade, country, IMDb, quality), sorting, search and similar titles.
Library My list, continue watching and full history, stored on the device.
Personal System/light/dark theme, five accent colors, poster size, Persian or Latin digits, reduced motion, choose which home sections you see, default quality and player.
Notifications Opt in to local alerts when new movies or series appear, and when a series in your list gets new episodes. No push server involved.
Installable web app A PWA with offline shell. On iPhone and iPad a step-by-step Add to Home Screen guide appears; on Chrome and Edge the native install prompt is used.
Updates from GitHub Releases Android and the desktop apps check Releases, show the notes, and download the right installer for your platform. JS-only changes can ship over the air.

Screenshots

Phone

Splash Home Catalog Details Settings

Splash states

Checking connection    Offline    iOS install guide

Desktop and web

Desktop home

Desktop catalog Desktop details

Web footer

Android TV

Android TV home with side rail

Preview the TV layout in any browser with ?tv=1, the iOS install guide with ?ios=1, and the splash states with ?splash=hold or ?splash=offline, and the iOS container rules (MKV hand-off to external players) with ?platform=ios.

Platforms

Platform How you get it
Android Vispar-*-android.apk from Releases, or npm run android
Android TV Vispar-*-android-tv.apk from Releases (leanback launcher, banner and D-pad focus). Built with the react-native-tvos fork
iOS Simulator: Vispar-*-ios-simulator.zip. iPhone / iPad: Vispar-*-ios-unsigned.ipa (unsigned, see below). Or open the web app in Safari and follow the in-app Add to Home Screen guide
Web / PWA vispar.ehsanfazli.ir, or npm run build:web and host the dist/ folder (vercel.json is included)
Windows Vispar-*-win-*.exe (installer) or the portable build
macOS Vispar-*-mac-*.dmg
Linux Vispar-*-linux-*.AppImage or .deb

Both APKs are built on GitHub's runners by the Android builds workflow (.github/workflows/android.yml, no EAS account needed). They are signed with the standard debug key, so they install directly but are not meant for the Play Store. Install the TV APK from a USB drive or with adb install. For emulators and Chromebooks there are smaller -x86_64 APKs (Vispar-*-android-x86_64.apk, Vispar-*-android-tv-x86_64.apk).

iOS builds

The iOS builds workflow (.github/workflows/ios.yml) produces two files on a macOS runner, with no secrets needed:

  • Vispar-*-ios-simulator.zip: the app for the iOS Simulator (arm64 and Intel). Unzip it and drag Vispar.app onto a running Simulator, or run xcrun simctl install booted Vispar.app and xcrun simctl launch booted com.fazli.vispar.
  • Vispar-*-ios-unsigned.ipa: iPhone and iPad build. It is not signed, because Apple only installs signed apps. Re-sign and install it with AltStore, Sideloadly (free Apple ID, valid 7 days) or your own certificate and provisioning profile. On Linux, see docs/ios-install-linux.md (xtool). It is not a TestFlight or App Store build.

The desktop builds are produced by the Desktop builds workflow (.github/workflows/desktop.yml). Push a v* tag and the installers are attached to the release automatically.

macOS and Windows builds are not code-signed yet, so the OS will show a warning on first launch.

TV and remote control

  • Every control has a visible focus state (ring, glow and a slight lift on posters).
  • A labelled side rail replaces the tab bar and remembers where you are.
  • In the player the controls auto-hide. With them hidden: ← / → seek, OK play or pause, ↑ / ↓ bring the controls back. Play/Pause, Rewind and Fast-forward media keys work, and Back closes a menu first, then the controls, then the player.
  • Content is kept inside a TV-safe margin and sized for 10-foot viewing.

Getting started

git clone https://github.com/TssHack/vispar.git
cd vispar
npm install
cp .env.example .env     # set EXPO_PUBLIC_API_BASE
npm run web              # or: npm run android
Command What it does
npm run web / android / ios Start the dev server
npm run start:tv Dev server in TV mode
npm run typecheck TypeScript, strict
npm test Unit tests (Vitest)
npm run build:web Export the web app with PWA tags into dist/
npm run brand:icons / brand:pwa Regenerate app and PWA icons from the logo

Backend

Out of the box the app uses the hosted proxy at https://cdnd.ehsanfazli.ir/api. It keeps the upstream API key on the server, adds CORS for the web build, and only forwards the four read-only routes the app needs. Its source is private. To use your own, set EXPO_PUBLIC_API_BASE in .env. Direct mode (EXPO_PUBLIC_API_KEY) works on native builds but embeds the key in the app, so avoid it for public releases.

Desktop and web

Desktop home

Desktop catalog Desktop details

Web footer

Android TV

Android TV home with side rail

Preview the TV layout in any browser with ?tv=1, the iOS install guide with ?ios=1, and the splash states with ?splash=hold or ?splash=offline, and the iOS container rules (MKV hand-off to external players) with ?platform=ios.

Platforms

Platform How you get it
Android Vispar-*-android.apk from Releases, or npm run android
Android TV Vispar-*-android-tv.apk from Releases (leanback launcher, banner and D-pad focus). Built with the react-native-tvos fork
iOS Simulator: Vispar-*-ios-simulator.zip. iPhone / iPad: Vispar-*-ios-unsigned.ipa (unsigned, see below). Or open the web app in Safari and follow the in-app Add to Home Screen guide
Web / PWA vispar.ehsanfazli.ir, or npm run build:web and host the dist/ folder (vercel.json is included)
Windows Vispar-*-win-*.exe (installer) or the portable build
macOS Vispar-*-mac-*.dmg
Linux Vispar-*-linux-*.AppImage or .deb

Both APKs are built on GitHub's runners by the Android builds workflow (.github/workflows/android.yml, no EAS account needed). They are signed with the standard debug key, so they install directly but are not meant for the Play Store. Install the TV APK from a USB drive or with adb install. For emulators and Chromebooks there are smaller -x86_64 APKs (Vispar-*-android-x86_64.apk, Vispar-*-android-tv-x86_64.apk).

The desktop builds are produced by the Desktop builds workflow (.github/workflows/desktop.yml). Push a v* tag and the installers are attached to the release automatically.

macOS and Windows builds are not code-signed yet, so the OS will show a warning on first launch.

TV and remote control

  • Every control has a visible focus state (ring, glow and a slight lift on posters).
  • A labelled side rail replaces the tab bar and remembers where you are.
  • In the player the controls auto-hide. With them hidden: ← / → seek, OK play or pause, ↑ / ↓ bring the controls back. Play/Pause, Rewind and Fast-forward media keys work, and Back closes a menu first, then the controls, then the player.
  • Content is kept inside a TV-safe margin and sized for 10-foot viewing.

Getting started

git clone https://github.com/TssHack/vispar.git
cd vispar
npm install
cp .env.example .env     # set EXPO_PUBLIC_API_BASE
npm run web              # or: npm run android
Command What it does
npm run web / android / ios Start the dev server
npm run start:tv Dev server in TV mode
npm run typecheck TypeScript, strict
npm test Unit tests (Vitest)
npm run build:web Export the web app with PWA tags into dist/
npm run brand:icons / brand:pwa Regenerate app and PWA icons from the logo

Backend

The app talks to a catalog API through a single base URL. The proxy that keeps the API key on a server and adds CORS is not part of this repository. Point EXPO_PUBLIC_API_BASE at your own proxy. Direct mode (EXPO_PUBLIC_API_KEY) works on native builds, but it embeds the key in the app, so avoid it for public releases.

Desktop

npm run build:web
cd desktop && npm install && npx electron-builder

The Electron shell serves the exported web app from a private app:// origin, opens external links in your browser, and supports F11 for full screen.

Releases and updates

  1. Bump version in app.json and desktop/package.json.
  2. Push a tag such as v2.1.0. CI builds Windows, macOS and Linux installers and attaches them.
  3. The Android builds workflow attaches the phone and TV APKs on the same tag. Write the notes in the release body. That text is what users see in the update sheet.

Installed apps check at most every 12 hours, or on demand from Settings → Check for updates.

Project structure

src/app/            screens (expo-router)
src/api/            client, tolerant parsers, react-query hooks
src/components/     UI building blocks, splash, footer, focus handling
src/net/            connection probe (internet, then API)
src/pwa/            install flow and the iOS guide
src/notifications/  local notifications and the new-content watcher
src/update/         GitHub release check, platform asset picking, OTA
src/player/         seek bar and playback context
src/external/       external players and downloaders
src/filters/        filtering and sorting
src/library/        my list, continue watching, history
src/settings/       persisted preferences
src/theme/          tokens, fonts, theme provider
desktop/            Electron shell for Windows, macOS, Linux
public/             web manifest and service worker
plugins/            Expo config plugin (installed-app detection on Android)
tests/              Vitest suites

Tech

Expo SDK 58 · React Native 0.88 · expo-router · TanStack Query · expo-video · react-native-svg · Electron · Vitest · TypeScript (strict). Typeface: Arad under the SIL OFL 1.1.

Credits

Designed and developed by Ehsan Fazli.

About

Vispar: movie and series app for Android, iOS, Web, Android TV and desktop

Topics

Resources

Security policy

Stars

57 stars

Watchers

0 watching

Forks

Releases

Contributors

Languages