Our Architecture
How Vyla Home, SDK, and Stream API relate, and where each responsibility belongs.
The Vyla stack
Vyla separates local application management, provider resolution, and client-facing delivery. That separation lets each layer be used on its own while keeping the integration points clear.
Vyla Home
Home is responsible for a desktop session: local configuration, encrypted local credentials, update coordination, managed processes, and the embedded interface. It is the right layer for launching and supervising a local experience.
Vyla SDK
The SDK contains the provider-facing work: source configuration, stream resolution, subtitle retrieval, download lookup, and health probes. It is the right layer when your Node.js application needs to decide how requests are authorized, cached, selected, and returned.
Stream API
Stream API wraps the SDK in a self-hosted HTTP service. Its movie and TV endpoints use Server-Sent Events so metadata can arrive first and usable sources can be delivered progressively. It also provides subtitle, download, health, test, and optional debug routes.
Common deployment patterns
| Pattern | Best for | Key decision |
|---|---|---|
| Home only | a managed local desktop experience | Home owns the lifecycle of bundled local services |
| App + SDK | a Node.js backend with a custom product API | your app owns authentication, policy, and response design |
| Player + Stream API | browser or mobile clients that need a stable HTTP contract | deploy Stream API and place it behind TLS when exposed remotely |
| Home + Stream API | a local player backed by a local service | keep the service bound and access-controlled for the local environment |
Data flow for playback
- A client provides a TMDB media ID (plus season and episode for TV).
- Stream API, or your own SDK-based backend, asks active providers for candidates.
- Candidates are checked and successful sources are returned progressively.
- The player begins with the first compatible candidate and keeps later candidates as fallbacks.
- Subtitle and download lookups are separate operations; neither should block first playback.
Provider availability varies by source and network environment. Build the player experience around fallbacks and empty-result states, as described in Error handling.