An extensible, plugin-oriented, HTML5-first media player for the web
# Clappr
An extensible, plugin-oriented, HTML5-first media player for the web.
It provides a modular architecture to build powerful playback experiences with ease.
## Getting Started
Install via npm or yarn:
```bash
yarn add @clappr/player
```
## Breaking changes (playback peers)
Recent majors stopped embedding their streaming libraries — you must provide the peer:
| Package | Major | Change |
| ------- | ----- | ------ |
| [`@clappr/hlsjs-playback`](packages/hlsjs-playback/README.md) | 3.0.0 | `hls.js` no longer bundled |
| [`dash-shaka-playback`](packages/dash-shaka-playback/README.md) | 5.0.0 | `shaka-player` no longer bundled |
## Project Structure
This repository uses a monorepo layout:
| Directory | Description |
| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| [`/apps`](/apps/) | Applications such as [clappr.io](http://clappr.io/) and documentation site |
| [`/packages`](/packages/) | Core packages (e.g. `@clappr/player`, plugins, utilities) |
| [`/packages/player`](/packages/player) | The main **Clappr Player** package. Exposes the public API and serves as the entry point for embedding the player in web apps. |
| [`/packages/clappr-core`](/packages/clappr-core) | Contains the **core architecture** of the player — including components such as `Core`, `Container`, and `Playback` abstractions. |
| [`/packages/clappr-plugins`](/packages/clappr-plugins) | Official **plugin collection**, providing ready-to-use extensions (e.g., UI features, analytics integrations). |
| [`/packages/clappr-zepto`](/packages/clappr-zepto) | Lightweight **DOM utility layer**, a modernized fork of Zepto tailored for Clappr’s internal UI rendering. |
| [`/packages/hlsjs-playback`](/packages/hlsjs-playback) | Playback module that adds support for **HLS streams** using [hls.js](https://github.com/video-dev/hls.js). |
| [`/packages/dash-shaka-playback`](/packages/dash-shaka-playback) | Playback module that enables **MPEG-DASH** streaming via [Shaka Player](https://github.com/google/shaka-player). |
| [`/packages/html5-tvs-playback`](/packages/html5-tvs-playback) | Playback module for **HbbTV smart TVs**, supporting VoD/Live and DRM via the OIPF DRM agent. |
## Documentation
For the latest guides, examples, and architecture overviews, visit the resources below:
- [**Getting Started**](./apps/clappr.io/docs/getting_started.md): quick setup and integration examples.
- [**Architecture Overview**](./apps/clappr.io/docs/architecture.md): explains how the player, core, containers, and plugins interact.
- [**Plugin Development Guide**](./apps/clappr.io/docs/guides/how_to_build_plugins.md): how to create and register custom plugins.
- [**Player API Reference**](./apps/clappr.io/docs/api.md): complete reference of all available Player methods and properties.
- [**Frequently Asked Questions**](./apps/clappr.io/docs/faq.md): answers to commonly asked questions about setup, configuration, and troubleshooting.
- [**Changelog**](https://github.com/clappr/clappr/releases): highlights of each version and breaking changes.
## Local Development
Requires **Node.js ≥ 24**. The repo pins the major version in [`.nvmrc`](.nvmrc); with [nvm](https://github.com/nvm-sh/nvm), run `nvm install` then `nvm use` in the project root before any yarn command. Yarn 1 aborts every yarn command when the engine check fails.
Clone the repository and run:
```bash
# Install dependencies
yarn install
# Start the development environment
yarn dev
# Open in your browser
http://localhost:8080
```
## Contributing
We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to report bugs, propose features, and submit pull requests. Please follow our [Code of Conduct](CODE_OF_CONDUCT.md).
## Contributors
Thanks to all our amazing contributors!