Cine Pro (Cinestream)

Cross-platform client for the CinePro ecosystem — browse movies and TV shows via TMDB, resolve streams through your self-hosted CinePro Core (OMSS API), and play them in a native player. Built with Expo 54, React Native, and TypeScript.

Platform	Support
Android (phone & tablet)	Yes
Android TV	Yes (drawer navigation, D-pad focus)
iOS / iPad	Yes
Web	Experimental (`expo start --web`)

How it works

┌─────────────┐     metadata      ┌──────────────┐
│  Cine Pro   │ ────────────────► │  TMDB API    │
│  (this app) │                   └──────────────┘
└──────┬──────┘
       │ stream sources (OMSS)
       ▼
┌──────────────┐
│ CinePro Core │  ← your homelab / LAN URL (http/https)
└──────────────┘

TMDB — posters, titles, genres, search, and show/season metadata.
CinePro Core — OMSS-compliant backend that scrapes and returns playable sources per title or episode.
This app — discovery UI, library, and a full-screen player (react-native-video with HLS/DASH/SS).

You need a running Core instance and a free TMDB API v3 key. See CinePro docs for Core setup.

Prerequisites

Tool	Notes
Node.js	18+ recommended (LTS 20/22 works; repo tested on 22.x)
npm	Comes with Node
Git	Clone this repository

For native Android builds

Android Studio with Android SDK (API 34+ typical for RN 0.81)
JDK 17 (bundled with recent Android Studio)
ANDROID_HOME set, or SDK installed where Gradle can find it

For native iOS builds (macOS only)

Xcode and CocoaPods
Run npx expo prebuild then npm run ios

Optional (development)

Expo Go on a device — limited; video and some native modules work best in a development build (expo run:android / expo run:ios).

Quick start

1. Clone and install

git clone https://github.com/sostk/cinestream.git
cd cinestream
npm install

2. Generate native projects (first time)

The android/ and ios/ folders are not committed (see .gitignore). Generate them before native runs or release builds:

npx expo prebuild

Re-run after changing app.json plugins or native config.

3. Optional developer defaults (`.env`)

Copy the example file for local-only fallbacks. End users normally configure everything in the app (onboarding / Settings).

cp .env.example .env

Variable	Purpose
`EXPO_PUBLIC_TMDB_API_KEY`	TMDB API v3 key (optional dev default)
`EXPO_PUBLIC_CINEPRO_BASE_URL`	Core base URL, e.g. `http://localhost:3000`

On the Android emulator, use http://10.0.2.2:3000 instead of localhost to reach a Core server on your host machine.

Restart Metro after changing .env.

4. Start the dev server

npm start

Then press a (Android), i (iOS), or w (web) in the terminal, or scan the QR code with a dev client.

Build commands

Script	Description
`npm start`	Start Expo / Metro dev server
`npm run android`	Debug build and install on device/emulator
`npm run android:release`	Release variant via Expo (`expo run:android --variant release`)
`npm run ios`	Debug build on iOS simulator/device (macOS)
`npm run web`	Run in the browser
`npm run android:apk`	Release APK via Gradle (`android/gradlew.bat assembleRelease`)
`npm run android:apk:subst`	Same APK build via SUBST drive (Windows path-length fix)
`npm run android:bundle:subst`	Release AAB (`bundleRelease`) with SUBST drive

Android release APK (Windows)

Deep paths (e.g. under Desktop) can hit Windows’ ~260 character limit during native codegen. Use the SUBST helper:

npm run android:apk:subst

If drive R: is taken:

$env:ANDROID_SUBST_DRIVE = 'S'
npm run android:apk:subst

Output APK (typical path):

android/app/build/outputs/apk/release/app-release.apk

Android release (macOS / Linux)

cd android && ./gradlew assembleRelease

Or: npm run android:release after npx expo prebuild.

How to use the app

First launch — onboarding

Open the app after install.
Complete the short intro, then enter:
- TMDB API v3 key — create one at TMDB Settings → API (API key type “Developer”, v3 auth).
- CinePro Core URL — full URL with scheme, e.g. https://core.example.com or http://192.168.1.10:3000.
The app validates the TMDB key against /configuration before continuing.

Credentials are stored on device (AsyncStorage via Zustand persist), not sent to third parties except TMDB and your Core.

Main sections

Tab / drawer	What you can do
Home	Trending and curated rows, hero carousel, genre shortcuts
Search	Find movies and TV shows
Library	Watchlist, favorites, continue watching
Settings	Core URL, TMDB key, Core health check, theme, playback options

Watching content

Open a movie or TV show from Home, Search, or Library.
For TV, pick season / episode in the episode browser.
Tap Play — the app requests sources from Core (/v1/movies/{id} or /v1/tv/.../episodes/...).
The player supports quality selection, playback speed, autoplay next episode, and orientation control.

Settings worth knowing

Core health — polls /v1/health when a URL is saved.
Re-run setup — clears onboarding and walks through TMDB + Core again.
Playback — auto quality, default speed, autoplay next episode, resize/aspect modes (Android).
Theme — light / dark.

Android TV

On Android TV (Platform.isTV), navigation uses a permanent drawer instead of bottom tabs, with focus-friendly controls (FocusSurface). Pair with a Core URL reachable on your LAN; cleartext HTTP is enabled for local Core (usesCleartextTraffic).

Project structure

cinestream/
├── index.ts              # App entry (registers src/App)
├── app.json              # Expo config (name: Cine Pro, package: com.cinepro.app)
├── src/
│   ├── App.tsx           # Providers, splash, onboarding gate
│   ├── api/              # TMDB + OMSS (CinePro Core) clients
│   ├── components/       # UI building blocks
│   ├── navigation/       # Stack, tabs (phone), drawer (TV)
│   ├── player/           # Playback, sources, HUD
│   ├── screens/          # Home, Search, Library, Player, etc.
│   ├── store/            # Settings & library persistence
│   └── theme/            # Theming (NativeWind + custom colors)
├── plugins/              # Expo config plugins (e.g. cleartext HTTP)
├── scripts/              # Windows Android release helper
└── assets/               # Icons, splash, logos

Path alias: @/* → src/* (see tsconfig.json).

Tech stack

Expo SDK 54 · React Native 0.81 · React 19
React Navigation (native stack, bottom tabs, drawer)
TanStack Query — server state / caching
Zustand + AsyncStorage — settings & library
NativeWind 4 + Tailwind CSS — styling
react-native-video — HLS, DASH, Smooth Streaming, RTSP (Android ExoPlayer extensions)

Troubleshooting

Issue	What to try
“Configure your CinePro Core URL”	Set Core URL in Settings or complete onboarding
TMDB errors	Verify v3 API key; check network
Core unreachable on emulator	Use `10.0.2.2` instead of `localhost` for host machine
Invalid URL `l192.168...`	Remove stray character before IP in Settings
Android blocks `http://` Core	Cleartext is enabled in config; ensure URL is correct
Windows build path too long	`npm run android:apk:subst`
No `android/` folder after clone	`npx expo prebuild`
Metro env vars not applied	Stop server, edit `.env`, run `npm start` again

License

See repository license file if present; otherwise check with the maintainer.

Name		Name	Last commit message	Last commit date
Latest commit History 23 Commits
assets		assets
plugins		plugins
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
app.json		app.json
babel.config.js		babel.config.js
global.css		global.css
index.ts		index.ts
metro.config.js		metro.config.js
nativewind-env.d.ts		nativewind-env.d.ts
package-lock.json		package-lock.json
package.json		package.json
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Cine Pro (Cinestream)

How it works

Prerequisites

Quick start

1. Clone and install

2. Generate native projects (first time)

3. Optional developer defaults (`.env`)

4. Start the dev server

Build commands

Android release APK (Windows)

Android release (macOS / Linux)

How to use the app

First launch — onboarding

Main sections

Watching content

Settings worth knowing

Android TV

Project structure

Tech stack

Troubleshooting

Related links

License

About

Uh oh!

Releases 1

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Cine Pro (Cinestream)

How it works

Prerequisites

Quick start

1. Clone and install

2. Generate native projects (first time)

3. Optional developer defaults (.env)

4. Start the dev server

Build commands

Android release APK (Windows)

Android release (macOS / Linux)

How to use the app

First launch — onboarding

Main sections

Watching content

Settings worth knowing

Android TV

Project structure

Tech stack

Troubleshooting

Related links

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Uh oh!

Contributors

Uh oh!

Languages

3. Optional developer defaults (`.env`)