# OMSS Core
[](https://github.com/omss-spec/core/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@omss/core)
[](https://www.npmjs.com/package/@omss/core)
[](https://codecov.io/gh/omss-spec/core)
[](https://github.com/omss-spec/core/blob/main/SECURITY.md)
[](./LICENSE)
**OMSS Core** is the official TypeScript runtime and plugin orchestrator for building [OMSS-compliant](https://github.com/omss-spec/omss-spec) 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](#install)
- [Quick Start](#quick-start)
- [Features](#features)
- [Documentation](#documentation-_coming-soon_)
- [Ecosystem](#ecosystem)
- [ID Convention](#id-convention)
- [Contributing](#contributing)
- [Support](#support)
- [Team](#team)
- [Acknowledgments](#acknowledgments)
- [License](#license)
- [Dependencies](#dependencies)
## Install
```sh
npm install @omss/core
```
```sh
yarn add @omss/core
```
```sh
pnpm add @omss/core
```
## Quick Start
```ts
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](https://omss.mintlify.site) for a more in-depth guide.
## 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](https://github.com/omss-spec/omss-spec) in mind.
## Documentation _(coming soon)_
The documentation is currently under development. You can find the latest version at [https://omss.mintlify.site](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](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 `:::...:`. 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:` — e.g., `tmdb:155`
- TV Episode: `tmdb:::` — 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` — e.g., `imdb:tt0468569`
- TV Episode: `imdb:tt` — 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](https://github.com/omss-spec/omss-spec) and the [docs](https://omss.mintlify.site) (coming soon).
## Contributing
Whether reporting bugs, discussing improvements, or writing code — contributions are welcome. Please read the [CONTRIBUTING](./CONTRIBUTING.md) guidelines before opening a pull request.
## Support
We are active on [GitHub Discussions](https://github.com/orgs/omss-spec/discussions).
## Team
OMSS Core (and its plugins) is the result of a great community (alphabetically sorted).
**Lead Maintainers:**
- [**@An0n-00**](https://github.com/An0n-00), [**@An0n-01**](https://github.com/An0n-01), https://www.npmjs.com/~an0n-000
**Contributors:**
- [**@anochj**](https://github.com/anochj)
- [**@autovalue**](https://github.com/autovalue)
- [**@LorisRue**](https://github.com/lorisrue), https://www.npmjs.com/~lorisrue
_(Join us by contributing!)_
## Acknowledgments
This project (rather it's ecosystem/API) is inspired by [Fastify](https://github.com/fastify/fastify).
## License
Licensed under [MIT](./LICENSE).
## Dependencies
This is a pure TypeScript project, meaning it has no production dependencies.