Core

OMSS Core is the official TypeScript runtime and plugin orchestrator for building OMSS-compliant media streaming services.

The core is intentionally minimal. Its sole responsibility is to manage the OMSS lifecycle, load plugins, and expose shared states between them. All additional functionality - HTTP transport, caching, resolvers, auth - is added via OMSS Plugins.

Note

The project is in beta. The API shown here is preliminary.

Table of Contents

• Install
• Quick Start
• Writing Providers & Resolvers
• Features
• Documentation
• Ecosystem
• ID Convention
• Contributing
• Support
• Team
• Acknowledgments
• License
• Dependencies

Install

npm install @omss/core

yarn add @omss/core

pnpm add @omss/core

Quick Start

import { OMSSServer } from '@omss/core'
import httpPlugin from '@omss/plugin-http'
import cachePlugin from '@omss/plugin-cache'

const server = new OMSSServer({
    name: 'My Media Server',
})

await server.plugins.register(httpPlugin, {
    port: 3000,
})
// and many other features.

Do you want to know more? Check out the documentation for a more in-depth guide.

Writing Providers & Resolvers

Resolvers convert an OMSS ID into the metadata a provider needs; providers use that metadata to fetch streaming sources. Both are plain objects - build them with defineResolver()/defineProvider() for full type inference:

import { defineResolver, defineProvider, OK } from '@omss/core'

const tmdbResolver = defineResolver({
    namespace: 'tmdb',
    name: 'TMDB Resolver',
    converter: new Map(),
    async resolve(id) {
        return OK({ title: `Movie #${id.values[0]}` })
    },
})

const myProvider = defineProvider({
    id: 'my-provider',
    name: 'My Provider',
    enabled: true,
    supportsId: (id) => id.namespace === 'tmdb',
    resolver: tmdbResolver,
    async getSources(request, result) {
        result.source({
            url: 'https://cdn.example.com/stream.m3u8',
            header: {},
            streamable: true,
            type: 'hls',
            quality: 'FHD',
            languages: ['English'],
        })
        return result.done()
    },
})

await server.providers.register(myProvider)

const result = await server.sources.getSources('tmdb:155')
if (result.ok) {
    console.log(result.value.sources)
}

See example/example.ts for a full tour of every feature - hooks, plugins, resolvers, providers, extractors, middleware, and source gathering.

Features

• Modular by design: The core ships with almost no functionality. Everything is a plugin.
• OMSS Lifecycle: Use hooks to get notified of OMSS lifecycle events.
• Fully typed: Built in TypeScript with full type exports for Everything (no any used!)
• Extensible: OMSS Core is fully extensible via its hooks, plugins, and decorators.
• Middleware support: Certain services expose middleware chains that plugins can extend (e.g., caching layers).
• Developer friendly: The framework is built to be very expressive and help developers in their daily use without sacrificing performance.
• Standards-compliant: Built with the OMSS Specification in mind.

Documentation (coming soon)

The documentation is currently under development. You can find the latest version at https://omss.mintlify.site.

Ecosystem

We are working on a comprehensive ecosystem of plugins that can be used to extend OMSS.

The current Open Media Streaming Specification can always be found at https://github.com/omss-spec/omss-spec.

Plugins

An official plugin registry is planned for the future.

Official Plugins (maintained by the OMSS team):

Note

These plugins are a WIP.

Plugin	Description
@omss/plugin-http	HTTP transport via Fastify
@omss/plugin-cache	Memory and Redis caching
@omss/plugin-auth	Basic authentication support

Resolvers

Resolvers are used to resolve OMSS IDs to media metadata.

Official Resolvers (maintained by the OMSS team):

Note

These resolvers are a WIP.

Resolver	Description
@omss/resolver-tmdb	TMDB resolver

ID Convention

IDs follow the format <namespace>:<value_1>:<value_2>:...:<value_n>. Values can contain any character - use URL encoding if your value includes : or whitespaces. Values are URL-decoded during parsing.

However, the following namespaces are reserved for the OMSS specification and must follow the rules below. More namespaces may be added in the future:

TMDB:

• Movie: tmdb:<movie_id> - e.g., tmdb:155
• TV Episode: tmdb:<show_id>:<season>:<episode> - e.g., tmdb:1396:3:7

Note

All values must be natural numbers (≥ 1), except season_number which may be 0 (specials).

IMDb (Movies and TV Episodes only - not series):

• Movie: imdb:tt<digits> - e.g., imdb:tt0468569
• TV Episode: imdb:tt<digits> - e.g., imdb:tt1480055

Note

Valid IMDb IDs consist of the prefix tt followed by exactly seven digits.

A full list of supported namespaces and their values can be found in the OMSS Specification and the docs (coming soon).

Contributing

Whether reporting bugs, discussing improvements, or writing code - contributions are welcome. Please read the CONTRIBUTING guidelines before opening a pull request.

Support

We are active on GitHub Discussions.

Team

OMSS Core (and its plugins) is the result of a great community (alphabetically sorted).

Lead Maintainers:

• @An0n-00, @An0n-01, https://www.npmjs.com/~an0n-000

Contributors:

• @anochj
• @autovalue
• @LorisRue, https://www.npmjs.com/~lorisrue

(Join us by contributing!)

Acknowledgments

This project (rather it's ecosystem/API) is inspired by Fastify.

License

Licensed under MIT.

Dependencies

This is a pure TypeScript project, meaning it has no production dependencies.