Problem & Challenge
Delivering high-definition video across varied regional broadband and mobile cellular networks presents steep challenges: network bandwidth is volatile, monolithic video formats (such as raw MP4) cause start-up latency, and unoptimized seek operations consume unnecessary bandwidth.
ZePlay was engineered to solve these bottlenecks by implementing an adaptive streaming pipeline. The platform transcodes raw video uploads asynchronously into multi-quality HLS streams (1080p, 720p, 480p), dynamically adjusts playback resolutions in real time based on client buffer health, and synchronizes watch positions reliably across multi-user profiles secured by custom PIN locks.
Technical Approach & Architecture
The system is architected around an asynchronous ingestion pipeline paired with an event-driven playback state machine:
- Frontend Player Engine: Built with React and TypeScript using custom HLS.js controllers. Features adaptive quality switching without playback interruption, custom gesture controls, and low-latency buffer management.
- Asynchronous Ingestion Service: An automated FFmpeg worker queue that splits incoming master videos into segmented
.tsmedia files, generates synchronized multi-bitrate.m3u8manifest playlists, and extracts automated poster thumbnails. - FastAPI Core & Redis Caching: Handles playback session heartbeats, caches manifest lookups in-memory, and provides low-latency user watch history lookups.
- PostgreSQL Database: Stores relational catalog data, user profiles, PIN credentials, and historical telemetry.
Engineering Challenges & Solutions
1. Quality switches without playback stalls
Switching quality tiers mid-playback causes pauses when renditions do not share segment boundaries.
Solution: FFmpeg encodes every rendition with a fixed keyframe interval and scene-cut detection disabled, so 1080p, 720p and 480p segments line up and HLS.js can switch tiers at the same boundary.
2. Throughput under concurrent load
The first 500-user benchmark reached only 84.2 requests per second with a P95 latency of 8.3 seconds.
Solution: Redis caching for frequently requested data, GZip responses and multiple Uvicorn workers. Each step was measured with k6; together they raised throughput 7.7× to 650.2 requests per second with 0% failures.
3. Slow deep pagination
OFFSET pagination makes PostgreSQL read and discard every earlier row, so deep pages of a 100,017-title catalogue got slower the further a user scrolled.
Solution: keyset (cursor) pagination. In the measured deep-page case, SQL execution fell from about 295 ms to 0.27 ms.
Performance Results
Measured with k6 on a local WSL/Linux benchmark environment, 500 virtual users, cached workload. These are benchmark results, not a production capacity claim.
| Stage | Requests/s | Median | P95 | Failures |
|---|---|---|---|---|
| Baseline | 84.2 | 4,162 ms | 8,281 ms | 0.00% |
| + Redis | 233.0 | 357 ms | 6,680 ms | 0.00% |
| + GZip | 298.2 | 300 ms | 6,256 ms | 0.00% |
| Optimised, 1 worker | 359.5 | 410 ms | 5,863 ms | 0.00% |
| Optimised, 4 workers | 650.2 | 527 ms | 1,684 ms | 0.00% |
A separate database-bound test (no Redis cache hits) ran to 1,000 virtual users as a saturation test: requests still completed with 0% failures, but P95 latency exceeded 12 seconds. The backend test suite passes 59 of 59 tests.
Key Features & Capabilities
- Adaptive Multi-Quality Streaming: Dynamic playback selection across 1080p Full HD, 720p HD, and 480p SD tiers.
- Multi-Profile Architecture: Independent watch histories, continue-watching carousels, and PIN-protected profile security.
- Automated Ingestion Pipeline: Playlist verification and repair scripts that detect missing or corrupted segments.
- Responsive UI: Keyboard shortcuts and fullscreen mobile gestures.