🎯 What is OMSS?

OMSS is an open standard for streaming media aggregation. It provides a unified API for fetching movie and TV show streaming sources from multiple providers, with built-in proxy support, subtitle handling, and quality selection.

🔍 What is the @omss/framework?

The @omss/framework is the official TypeScript/Node.js implementation framework that makes building OMSS-compliant backends effortless. Instead of manually implementing the specification from scratch, developers can focus solely on writing provider scraping logic while the framework handles all the boilerplate — routing, validation, proxy management, caching, error handling, and response formatting.

$3

- ✅ Standardized API: Consistent response format across all providers
- ✅ Multi-Provider Support: Aggregate sources from multiple streaming providers
- ✅ Built-in Proxy: Automatic URL proxying with header forwarding
- ✅ TMDB Integration: Validation against The Movie Database
- ✅ Caching Layer: Redis or in-memory caching for performance
- ✅ Type Safety: Full TypeScript support
- ✅ Provider Management: Easy enable/disable, automatic discovery
- ✅ Health Checks: Monitor provider availability
- ✅ Refresh API: Force cache invalidation when needed

📋 Table of Contents

- Installation
- Quick Start
- Configuration
- Creating Custom Providers
- API Endpoints
- Environment Variables
- Architecture
- OMSS Compliance
- License

🚀 Installation

There is a template which you can use to easily create your own streaming backend. Check it out here! This is the easiest way to create your own OMSS backend.

$3

- Node.js 18.x or higher
- npm or yarn
- TMDB API Key (Get one here)
- (Optional) Redis server for caching

$3

``bash

npm

npm install @omss/framework

yarn

yarn add @omss/framework

pnpm

pnpm add @omss/framework
`

🚀 Quick start

Minimal example using the built‑in provider and in‑memory cache:

`ts
// src/server.ts
import { OMSSServer } from '@omss/framework';
import { ExampleProvider } from './src/providers/implementations/example-provider';

// Create server instance
const server = new OMSSServer({
name: 'My OMSS Backend',
version: '1.0.0',
host: 'localhost',
port: 3000,
cache: {
type: 'memory',
ttl: {
sources: 7200,
subtitles: 7200,
},
},
tmdb: {
apiKey: process.env.TMDB_API_KEY,
cacheTTL: 86400,
},
});

// Register providers
const registry = server.getRegistry();
registry.register(new ExampleProvider());

// or use the very cool auto-discovery feature
// registry.discoverProviders('./path/to/providerfolder');
// Note: this is relative to where you start the server.

// Start server
await server.start();
`

.env:

`env
TMDB_API_KEY=your_tmdb_key_here
HOST=localhost
PORT=3000
NODE_ENV=development
`

Run in dev:

`bash
npx tsx src/server.ts
`

And then it should work!

⚙️ Configuration

$3

`typescript
interface OMSSConfig {
// Required: Server identification
name: string; // Your server name
version: string; // OMSS Spec version

// Optional: Network settings
host?: string; // Default: 'localhost'
port?: number; // Default: 3000
publicUrl?: string; // For reverse proxy setups

// Optional: Cache configuration
cache?: {
type: 'memory' | 'redis';
ttl: {
sources: number;
subtitles: number;
};
redis?: {
host: string;
port: number;
password?: string;
};
};

// Required: TMDB configuration
tmdb?: {
apiKey?: string; // Can also use TMDB_API_KEY env var
cacheTTL?: number; // Default: 86400 (24 hours)
};
}
`

$3

#### Development

`typescript
const server = new OMSSServer({
name: 'OMSS Dev Server',
version: '1.0.0',
host: 'localhost',
port: 3000,
cache: {
type: 'memory',
ttl: {
sources: 7200,
subtitles: 7200,
},
},
tmdb: {
apiKey: process.env.TMDB_API_KEY,
cacheTTL: 86400,
},
});
`

#### Production with Redis

`typescript
const server = new OMSSServer({
name: 'OMSS Production',
version: '1.0.0',
host: '0.0.0.0',
port: 3000,
publicUrl: 'https://api.mystream.com',
cache: {
type: 'redis',
ttl: {
sources: 7200,
subtitles: 7200,
},
redis: {
host: process.env.REDIS_HOST || 'localhost',
port: parseInt(process.env.REDIS_PORT || '6379'),
password: process.env.REDIS_PASSWORD,
},
},
tmdb: {
apiKey: process.env.TMDB_API_KEY,
cacheTTL: 86400,
},
});
`

#### Behind Reverse Proxy

`typescript
const server = new OMSSServer({
name: 'OMSS API',
version: '1.0.0',
host: '0.0.0.0',
port: 3000,
// This is the public URL clients will use
publicUrl: 'https://myapp.com/api',
cache: {
type: 'redis',
redis: {
host: 'redis.internal',
port: 6379,
},
},
tmdb: {
apiKey: process.env.TMDB_API_KEY,
cacheTTL: 86400,
},
});
`

🔌 Creating Custom Providers

See the detailed Provider Creation Guide for a complete walkthrough.

$3

The easiest way to add a new provider:

1. Create a directory for all of your provider files

`bash
touch src/providers/implementations/my-provider.ts
`

2. Implement the BaseProvider class (see example below) in each file.

3. In the Setup, use the discoverProviders method of the ProviderRegistry to load all providers from that directory:

`typescript
const registry = server.getRegistry();
registry.discoverProviders('./src/providers/implementations'); // relative to where you start the server from
`

4. That's it! The provider will be automatically discovered and registered when you start the server!

No imports, no manual registration needed!

$3

`typescript
import { BaseProvider } from './src/providers/base-provider';
import { ProviderCapabilities, ProviderMediaObject, ProviderResult } from './src/core/types';

export class MyProvider extends BaseProvider {
// Required: Provider identification
readonly id = 'my-provider';
readonly name = 'My Provider';
readonly enabled = true;

// Required: Base URL and headers
readonly BASE_URL = 'https://provider.example.com';
readonly HEADERS = {
'User-Agent': 'Mozilla/5.0',
Referer: 'https://provider.example.com',
};

// Required: Declare what this provider supports
readonly capabilities: ProviderCapabilities = {
supportedContentTypes: ['movies', 'tv'],
};

// Implement movie scraping
async getMovieSources(media: ProviderMediaObject): Promise {
this.console.log('Fetching movie sources', media);

try {
// Your scraping logic here
const streamUrl = await this.scrapeMovieUrl(media.tmdbId); // this is just some example function

return {
sources: [
{
url: this.createProxyUrl(streamUrl, this.HEADERS),
type: 'hls',
quality: '1080p',
audioTracks: [
{
language: 'en',
label: 'English',
},
],
provider: {
id: this.id,
name: this.name,
},
},
],
subtitles: [],
diagnostics: [],
};
} catch (error) {
this.console.error('Failed to fetch sources', error, media);

return {
sources: [],
subtitles: [],
diagnostics: [
{
code: 'PROVIDER_ERROR',
message: ${this.name} failed,
field: '',
severity: 'error',
},
],
};
}
}

// Implement TV scraping
async getTVSources(media: ProviderMediaObject): Promise {
// Similar to getMovieSources but for TV
return { sources: [], subtitles: [], diagnostics: [] };
}

// Optional: Custom health check
async healthCheck(): Promise {
try {
const response = await fetch(this.BASE_URL);
return response.ok;
} catch {
return false;
}
}
}
`

$3

See the detailed Provider Creation Guide for a complete walkthrough.

📡 API Endpoints

$3

Fetch streaming sources for a movie.

Parameters:

- tmdbId (path): TMDB movie ID

Response:

`json
{
"responseId": "uuid-v4",
"expiresAt": "2026-01-18T20:00:00.000Z",
"sources": [
{
"url": "/v1/proxy?data=...",
"type": "hls",
"quality": "1080p",
"audioTracks": [
{
"language": "en",
"label": "English"
}
],
"provider": {
"id": "vixsrc",
"name": "VixSrc"
}
}
],
"subtitles": [],
"diagnostics": []
}
`

$3

Fetch streaming sources for a TV episode.

Parameters:

- tmdbId (path): TMDB series ID
- season (path): Season number (0-99)
- episode (path): Episode number (1-9999)

Response: Same structure as movies endpoint

$3

Proxy streaming URLs with custom headers.

Query Parameters:

- data (required): URL-encoded JSON containing:
`json
{
"url": "https://stream.example.com/video.m3u8",
"headers": {
"Referer": "https://provider.example.com"
}
}
`

$3

Force refresh cached sources.

Parameters:

- responseId (path): Response ID from previous request

$3

Health check endpoint.

Response:

`json
{
"status": "healthy",
"version": "1.0.0",
"providers": {
"total": 1,
"enabled": 1
}
}
`

🌍 Environment Variables

`env

Server Configuration

PORT=3000 # Port number for the server
HOST=0.0.0.0 # Use 'localhost' to restrict to local access
NODE_ENV=development # 'development' | 'production'

TMDB Configuration

TMDB_API_KEY=your_tmdb_api_key_here
TMDB_CACHE_TTL=86400

Cache Configuration

CACHE_TYPE=memory # 'memory' | 'redis'

Redis Configuration (if using Redis cache)

REDIS_HOST=localhost # default Redis host
REDIS_PORT=6379 # default Redis port
REDIS_PASSWORD= # Redis password if required
`

🏗️ Architecture

`
┌─────────────────────────────────────────────────────────────┐
│ OMSS Server │
├─────────────────────────────────────────────────────────────┤
│ Controllers │
│ ├── ContentController (Movies/TV endpoints) │
│ ├── ProxyController (Streaming proxy) │
│ └── HealthController (Health checks) │
├─────────────────────────────────────────────────────────────┤
│ Services │
│ ├── SourceService (Aggregates provider results) │
│ ├── TMDBService (Validates against TMDB) │
│ └── ProxyService (Handles URL proxying) │
├─────────────────────────────────────────────────────────────┤
│ Provider Registry │
│ └── Manages all registered providers │
├─────────────────────────────────────────────────────────────┤
│ Providers (Implement BaseProvider) │
│ ├── YourCustomProvider │
│ └── ... │
├─────────────────────────────────────────────────────────────┤
│ Cache Layer │
│ ├── MemoryCache (Development) │
│ └── RedisCache (Production) │
└─────────────────────────────────────────────────────────────┘
``

✅ OMSS Compliance

This implementation follows the OMSS Specification:

- ✅ Standardized Response Format: All responses follow OMSS schema
- ✅ TMDB Validation: All requests validated against TMDB
- ✅ Proxy Support: Required for all streaming URLs
- ✅ Error Handling: OMSS-compliant error responses
- ✅ Source Identification: Unique IDs for all sources
- ✅ Audio Track Support: Multiple audio tracks per source
- ✅ Subtitle Support: VTT/SRT subtitle formats
- ✅ Quality Indicators: Resolution-based quality tags
- ✅ Provider Attribution: Source provider identification
- ✅ Diagnostics: Detailed error/warning information

📚 Additional Resources

- OMSS Specification
- Basic Server Example
- Provider Example
- TMDB API Documentation

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

- All maintainers
- OMSS specification contributors