# Streaming App Backend: Developer Pain Points Research

> Compiled May 15, 2026 — Based on real GitHub issues from Debrify, Lumera, Riven, Decypharr, NuvioTV, Stremio Community v5, Comet, Hound, ARVIO, and other debrid/streaming apps.

---

## 1. METADATA & CATALOG ISSUES (The #1 User-Facing Problem)

### 1.1 Metadata Fetch Failures
**From Lumera #12:** *"Error getting meta. please try again later"* — Users can play one movie fine, then every subsequent title fails with metadata errors.

**Root causes observed:**
- TMDB/TVDB API rate limiting (free tier: 20 req/min, 429 errors)
- No caching layer → every catalog scroll hits upstream APIs
- No retry/backoff logic → single timeout kills the entire catalog
- No stale-cache fallback → when upstream is down, app shows nothing

**From NuvioTV #468:** *"Library/Watchlist blank thumbnails"* — Thumbnails disappear after app restart, even after force-stop/clear-cache/reauth cycles.

**Root causes:**
- Poster URLs not persisted to local DB, only in memory
- No image caching strategy (disk cache, WebP conversion, resize)
- Trakt sync data not properly persisted across sessions

### 1.2 Catalog Update & Refresh
**From NuvioTV #575:** Users don't know how to manually refresh addons. They reinstall the app unnecessarily when catalogs don't update.

**From Comet #550:** Custom catalog URLs required server restart — no per-user dynamic configuration.

**From NuvioTV #1042:** *"Stream sources found only when select movie from Collection"* — Stream discovery is inconsistent depending on how the user navigates to content.

### 1.3 Anime & Specialized Content
**From Comet #560:** Anime mapping requires separate catalog indexing — standard TMDB/TVDB don't cover anime well.

**From AniBridge #119:** Catalog-dependent search returns 503 until local provider catalog index is ready — first startup requires bootstrap.

---

## 2. STREAMING & PLAYBACK ISSUES (The Core Experience)

### 2.1 Buffering & Seek Problems
**From NuvioTV #1121:** *"Skipping forward results in infinite buffering"* — Always reproducible, never worked since v0.4.x.

**From NuvioTV #1427:** *"Internal player unstable after ~5 minutes"* — Video/audio stuttering that gets progressively worse.

**Root causes:**
- HTTP range requests not properly handled for torrent streams
- No adaptive bitrate/chunk prefetching
- Player buffer management doesn't account for variable upstream speed
- No back-buffer pressure awareness

### 2.2 Codec & Format Compatibility
**From NuvioTV #387:** Dolby Vision Profile 7 → 8.1 conversion needed for Android TV compatibility.

**From NuvioTV #563:** DTS-HD MA 7.1 passthrough failures on limited Fire TV devices.

**From Hound #6:** AC3 audio won't play in web browsers — codec support varies wildly.

**From NuvioTV #1212:** ExoPlayer can't open some streams → users need libmpv fallback.

### 2.3 Multi-Debrid Stream Routing
**From Decypharr #288:** *"Streaming in a multi debrid setup"* — When same torrent exists in both RD and AD, app reinserts to AD even though it's already there. No dedup check.

**From Decypharr #285:** Debrid provider priority — users want to control which debrid service is tried first.

**From Hound #8:** *"Does Hound proxy debrid streams server-side, or does the client fetch directly from the debrid CDN?"* — Architecture decision affects IP safety and bandwidth.

### 2.4 Torrent Streaming
**From Decypharr #290:** *"Uncached AllDebrid downloads fail symlink creation"* — Creates 0 files at download completion, causing Arr blocklisting.

**From Decypharr #284:** *"Download Client Unavailable"* — Queue sits in "Pending" state instead of failing fast.

**From Decypharr #280:** *"Misc category folder not being cleaned"* — Orphaned folders accumulate after manual import + torrent delete.

---

## 3. USER ACCOUNT & AUTH ISSUES

### 3.1 OAuth Flow Failures
**From Riven #1399:** Trakt OAuth callback returns 500 — `TypeError: Session.request() got unexpected keyword argument 'additional_headers'`. Blocks entire auth flow.

**Root cause:** Divergent code between released Docker image and main branch — wrapper function passes wrong kwargs.

### 3.2 Session & State Management
**From Lumera #5:** *"Addons being wiped"* — After exiting the app, all addons are disconnected. V0.1.8.

**From Debrify #12:** *"Reorganize movies in Home (android TV)"* — Home screen layout doesn't persist user preferences.

### 3.3 Watch Progress & History
**From NuvioTV #918:** *"Episode disappeared from continue watching"* — Watch history not properly persisted.

**From ARVIO:** Watch position saved every 10s to Supabase — but what if the connection drops mid-save?

---

## 4. PERFORMANCE & RESOURCE ISSUES

### 4.1 Memory Leaks & OOM
**From Decypharr #282:** *"OOM Issues"* — Container memory grows continuously until OOM killer fires. User set 16GB cap, then 32GB cap, both tripped.

**Root cause:** Workers=150 config + no memory trimming + download link caching not bounded.

**From Comet #332:** Redis caching was added specifically to address memory pressure from unbounded in-memory caches.

### 4.2 API Rate Limiting
**From Stremio AI Search #170:** *"Gemini free tier limit"* — 429 Too Many Requests on free tier (20 req/min). No rate limiting at app level.

**From Stremio AI Search #157:** *"API Usage Error"* — Paid tier also exceeded. No request queuing or shared caching.

**From Stremio Community v5 #204:** SubMaker addon hammers Gemini API because Community v5 calls ALL returned subtitles at once, not lazily.

### 4.3 Database Performance
**From Riven #1397:** `/api/v1/items/reindex` endpoint missing `session.commit()` — silently returns success but nothing persisted.

**From Riven #1398:** TVDB episodes never discovered for shows with paused seasons — state machine bug.

**From Comet #560:** Database schema refactoring required — migrations, column renames, JSON-backed caching/TTL changes.

---

## 5. ARCHITECTURE DECISIONS THAT CAUSE PAIN

### 5.1 Server-Side Proxy vs Direct Client Fetch
**The Hound question (#8):** Should the backend proxy streams, or should clients fetch directly from debrid CDN?

| Approach | Pros | Cons |
|----------|------|------|
| Server-side proxy | IP safety (debrid only sees your IP), bandwidth control, URL masking | Bandwidth cost, single point of failure, scaling complexity |
| Direct client fetch | No proxy bandwidth, scales infinitely | User IP exposed to debrid (single-IP rule), URL masking harder |

**Best practice from Riven:** Server-side VFS for torrent streams (Real-Debrid only sees home IP), but direct fetch for direct links.

### 5.2 Caching Strategy
**From Comet #332:** Redis L1 + Database L2 hybrid caching was the solution.

**From Latanime Addon #60:** Dual-layer caching — in-memory L1 + Cloudflare KV L2.

**Key insight:** All metadata responses should be cached. Stream URLs should NOT be cached (they expire). Torrent status should be cached with short TTL (5-10 min).

### 5.3 Addon vs Built-in Architecture
**From NuvioTV #1279:** *"This couldn't be built as an addon"* — AI subtitle translation requires intercepting subtitles frame-by-frame at player level. Addons can't do this.

**Key insight:** Some features MUST be built into the app core. Addons are great for catalog sources and stream providers, but not for player-level features.

### 5.4 Multi-Platform Data Sync
**From ARVIO:** Shared Supabase project between Android TV and Web apps — same auth, same watchlist, same progress.

**Key insight:** If you plan cross-platform, design the data model from day 1 with multi-device sync in mind. Don't bolt it on later.

---

## 6. SUBTITLE & ACCESSIBILITY ISSUES

### 6.1 Subtitle Problems
**From Debrify #11:** *"Subtitles don't work"* — User selects Spanish but gets English subtitles.

**From Hound #7:** *"External Subtitle Support"* — No integration with online subtitle sources (Wyzie, OpenSubtitles).

**From Stremio Community v5 #10:** Subtitle outline color setting doesn't apply, blank screen when trying to change it.

### 6.2 AI Translation (The New Frontier)
**From NuvioTV #1279:** Live AI subtitle translation via Gemini/Groq — intercepts subtitle cues at render time, translates on-the-fly.

**Key insight:** This is a differentiator. Most streaming apps only have English subtitles. AI translation is a premium feature that solves a real pain point.

---

## 7. DEPLOYMENT & OPERATIONAL ISSUES

### 7.1 Docker & Container Issues
**From Stremio Jellyfin #1:** Docker run fails with ECONNREFUSED — networking between containers not properly configured.

**From Riven:** Docker Compose deployment is the standard, but image updates sometimes break (Riven #1399 — released image diverges from main).

### 7.2 Configuration Management
**From Comet #550:** Per-user configuration stored in base64 URL-encoded config — works but is fragile.

**From Decypharr #286:** *"Cannot remove debrid provider"* — UI error: `document.querySelector(...) is null`. No server-side error logged.

### 7.3 Monitoring & Observability
**From Riven:** Prometheus metrics included but no alerting.
**From Torrent VPN Stack:** Prometheus + Grafana optional profile — not everyone sets it up.

---

## 8. WHAT USERS ACTUALLY WANT (From Issue Titles)

1. **"Great app, but needs an update!"** (Lumera #11) — Active development matters more than features
2. **"Add Profile PIN"** (Lumera #9) — Kids/family features
3. **"Cast to TV"** (Debrify #3) — Chromecast/AirPlay support
4. **"Different icon"** (Stremio Community #71) — Branding/personalization
5. **"Feature suggestion, Player specific"** (Stremio Community #37) — Player controls
6. **"PreMiD extension"** (Stremio Community #28) — Now Playing integration
7. **"Addon Refresh Button"** (NuvioTV #575) — Self-service troubleshooting
8. **"A Second Player"** (NuvioTV #347) — Picture-in-picture, split screen
9. **"Demo service"** (Hound #5) — Try before you install
10. **"unRAID template"** (Hound #10) — Easy NAS deployment

---

## 9. RECOMMENDATIONS FOR YOUR APP

### Must-Have from Day 1:
1. **Redis caching layer** — Metadata cached for 10-60 min, torrent status 5 min
2. **Graceful degradation** — When TMDB/TVDB is down, show cached data with "last updated" timestamp
3. **Retry with exponential backoff** — Never fail on first API error
4. **Stale-while-revalidate** — Show cached data while fetching fresh data in background
5. **Per-user debrid provider priority** — Let users choose which debrid to try first
6. **Server-side stream proxy** — IP safety for torrent streams
7. **Watch progress with offline queue** — Save progress locally, sync when online
8. **Subtitle support** — OpenSubtitles integration + AI translation (premium)
9. **Addon refresh button** — Self-service troubleshooting
10. **Memory-bounded workers** — No OOM from unbounded caches

### Nice-to-Have (Phase 2):
- Trakt scrobbling with offline queue
- Chromecast/AirPlay support
- Kids profile with PIN
- Picture-in-picture player
- Cross-platform watchlist sync
- Custom catalog addon support
- AI-powered recommendations

### Architecture Decisions:
- **Backend:** Python FastAPI (solo dev friendly)
- **Cache:** Redis (L1) + PostgreSQL (L2)
- **Search:** Meilisearch (lightweight, fast)
- **Streaming proxy:** Python async (FastAPI + aiohttp)
- **Database migrations:** Alembic (Python)
- **Deployment:** Docker Compose (single machine)