### CONTRIBUTING # Contributing to Clappr Thanks for your interest in Clappr. This guide covers how to report issues, propose changes, and submit pull requests. Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md). ## Did you find a bug? - **Search first** on [Issues](https://github.com/clappr/clappr/issues) to see if it was already reported. - If not, open a new issue via [New issue](https://github.com/clappr/clappr/issues/new/choose) and choose **Bug Report**. - Include as much detail as you can: player version, browser, OS, configuration, and steps to reproduce. ## Do you have a question? - Check the [FAQ](./apps/clappr.io/docs/faq.md) first. - If you still need help, open [New issue](https://github.com/clappr/clappr/issues/new/choose) and choose **Question**. ## Do you want a new feature? - Open [New issue](https://github.com/clappr/clappr/issues/new/choose) and choose **Feature Request** before starting large work. - Describe the problem and the solution you have in mind so maintainers can discuss scope early. - We may decline changes that significantly increase bundle size or hurt streaming performance. ## Did you write a patch? 1. Fork the repository and create a branch from `main`. 2. Make your changes and keep the pull request focused. 3. Open a pull request with a clear description of the problem and solution. 4. Link the related issue when applicable. Before submitting, make sure CI checks pass locally: ```bash yarn test yarn lint yarn format:check yarn build:dist && yarn test:smoke ``` ## Development setup Requires **Node.js ≥ 24** (see [`.nvmrc`](.nvmrc); with nvm, run `nvm install` then `nvm use` before any yarn command). Yarn 1 enforces the root `engines` field and aborts every yarn command on older Node versions — including `yarn lint`, `yarn test`, and `yarn format:check` above. Shared tooling (Babel, ESLint, browserslist, and any dependency used by 2+ packages) lives at the workspace root — see [Dependencies and shared config](AGENTS.md#dependencies-and-shared-config) in `AGENTS.md` before adding or bumping a tool. See the [README](README.md) for: - [Local Development](README.md#local-development) - [Project Structure](README.md#project-structure) - [Documentation](README.md#documentation) ## Commit messages Use [Conventional Commits](https://www.conventionalcommits.org/): ``` type(scope): description ``` Examples: `fix(core): restore volume after unmute`, `docs(player): clarify autoplay options`. Commit messages are validated by commitlint via Husky. ## Coding expectations - Follow ESLint and Prettier (run `yarn lint` and `yarn format:check`). - Test behavior, not implementation details. - Clean up timers, listeners, observers, connections, media elements, and Blob URLs. - Do not commit secrets, tokens, or `.env` files. - Ask maintainers before adding new dependencies — bundle size and maintenance matter in a media player. - Sourcemaps: an artifact in `dist/` gets a map iff it is a package/`exports` entry, a documented consumer entry point, or minified — see [Releasing → Sourcemaps](./.github/RELEASING.md#sourcemaps). ## Documentation and plugins Documentation lives under [`apps/clappr.io/docs/`](./apps/clappr.io/docs/). See the README [Documentation](README.md#documentation) section for the full index. To build a plugin, start with the [Plugin Development Guide](./apps/clappr.io/docs/guides/how_to_build_plugins.md). ## License By contributing, you agree that your contributions will be licensed under the [BSD 3-Clause License](LICENSE). --- ### README # Clappr An extensible, plugin-oriented, HTML5-first media player for the web. It provides a modular architecture to build powerful playback experiences with ease. [](https://github.com/clappr/clappr/actions/workflows/ci.yml) [](https://raw.githubusercontent.com/clappr/clappr/main/packages/player/package.json) [](https://github.com/clappr/clappr/blob/main/LICENSE) [](https://bundlephobia.com/package/@clappr/player) [](https://www.jsdelivr.com/package/npm/@clappr/player) ## 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! 🎉
towerz
towerz 		flavioribeiro
flavioribeiro 		leandromoreira
leandromoreira 		joaopaulovieira
joaopaulovieira 		tjenkinson
tjenkinson 		jhonatangcavalcanti
jhonatangcavalcanti
leaofelipe
leaofelipe 		tchakabam
tchakabam 		kslimani
kslimani 		thiagopnts
thiagopnts 		dayvson
dayvson 		pedrochamberlain
pedrochamberlain
bikegriffith
bikegriffith 		vagnervjs
vagnervjs 		barbosa
barbosa 		felipecesr
felipecesr 		fecampi
fecampi 		ronag
ronag
andrefilimono
andrefilimono 		paluh
paluh 		davidjb
davidjb 		NicholasAsimov
NicholasAsimov 		gamtiq
gamtiq 		afonsocdaniel
afonsocdaniel
leftees
leftees 		hounvs
hounvs 		ariselseng
ariselseng 		guilhermebruzzi
guilhermebruzzi 		stanogurnik
stanogurnik 		amanda-bmelo
amanda-bmelo
michaelcunningham19
michaelcunningham19 		rheber
rheber 		luanraithz
luanraithz 		mrlika
mrlika 		breim
breim 		sjlu
sjlu
raphamorim
raphamorim 		avreg
avreg 		alvynmcq
alvynmcq 		argoilves
argoilves 		svanscho
svanscho 		leonardocardoso
leonardocardoso
me-vlad
me-vlad 		wahajdar
wahajdar 		leticiafernandes
leticiafernandes 		lucasrodcosta
lucasrodcosta 		RussCoder
RussCoder 		paulocesarjr
paulocesarjr
luzeduardo
luzeduardo 		otmjka
otmjka 		hexray-newbee
hexray-newbee 		derrod
derrod 		gitter-badger
gitter-badger 		seanhussey
seanhussey
rolandstarke
rolandstarke 		rcmachado
rcmachado 		Niko78
Niko78 		MartinKolarik
MartinKolarik 		MTRNord
MTRNord 		jussike
jussike
kad3nce
kad3nce 		jlmcdonald
jlmcdonald 		revolter
revolter 		gbarrostv
gbarrostv 		emilepommier
emilepommier 		3dd13
3dd13
bent0b0x
bent0b0x 		wijloc
wijloc 		mainadapter
mainadapter 		lucasbraganca-tw
lucasbraganca-tw 		liamsegura
liamsegura 		shaharmor
shaharmor
PNixx
PNixx 		kolpax
kolpax 		arielfurtado
arielfurtado 		chooh
chooh 		ogunkarakus
ogunkarakus 		nicolaswalcker
nicolaswalcker
ahmadmayahi
ahmadmayahi 		celiolatorraca
celiolatorraca 		chriswiggins
chriswiggins 		diegosperes
diegosperes 		skrater
skrater 		medeeiros
medeeiros
jfairley
jfairley 		markx
markx 		KingHorse2015
KingHorse2015 		moni33
moni33 		LiShiSangZi
LiShiSangZi 		CommanderRoot
CommanderRoot
timgates42
timgates42 		rpadovani
rpadovani 		Rakesh9100
Rakesh9100 		nemesisqp
nemesisqp 		Bugadinho
Bugadinho 		Lucbm99
Lucbm99
hugocm99
hugocm99 		giselylucas-tw
giselylucas-tw 		fabiohcnobre
fabiohcnobre 		Snoopynha
Snoopynha 		Bubblesphere
Bubblesphere 		brinobruno
brinobruno
brunacm-dev
brunacm-dev 		poshe
poshe 		Ronkiro
Ronkiro 		Abubakrce19
Abubakrce19 		ahu
ahu
See the full list on our [contributors page](https://github.com/clappr/clappr/graphs/contributors). ## Security Found a vulnerability? Please do not open a public issue — see our [Security Policy](SECURITY.md) for how to report it privately and what falls in scope. ## License [BSD-3-Clause](LICENSE) © Globo.com --- ### SECURITY # Security Policy ## Supported Versions Clappr packages are versioned independently. Security fixes ship in the latest published minor of each package (`@clappr/player`, `@clappr/core`, `@clappr/plugins`, the playback packages, `@clappr/telemetry`, `@clappr/zepto`). Older releases are not backported — the recommended remediation is to upgrade. ## Reporting a Vulnerability Please do not open a public issue, pull request, or discussion for security reports. Public reports expose users who have not yet had a chance to upgrade. Report privately through GitHub Security Advisories: **[Report a vulnerability](https://github.com/clappr/clappr/security/advisories/new)** Include the affected package and version, the impact, and steps to reproduce — a minimal HTML page or CodeSandbox is ideal. Clappr is maintained by volunteers. We aim to acknowledge reports within a week and will keep you posted in the advisory thread, including if we conclude the report is not a vulnerability. We ask for up to 90 days before public disclosure; when a fix ships we publish a GitHub Security Advisory and credit you as the reporter unless you prefer otherwise. ## Scope Clappr is a client-side media player library. It runs in the browser, inside the page of whoever embeds it, and has no server component of its own. **In scope:** XSS or script injection reachable through player options, media metadata, or subtitle and caption tracks; prototype pollution in `@clappr/core` or `@clappr/zepto`; bypass of same-origin or CORS expectations caused by player code. **Out of scope:** - **Content protection and DRM.** Clappr is a library, not a content manager. It does not hold keys, issue or validate licenses, or enforce playback rights — those belong to the platform CDM, the device, and the license server operated by whoever embeds the player. Report those to the CDM vendor or to the service distributing the content. - **Upstream dependencies.** Report to [hls.js](https://github.com/video-dev/hls.js) or [shaka-player](https://github.com/shaka-project/shaka-player) directly. Tell us anyway if Clappr's usage makes the impact worse. - Issues that require the embedder to pass attacker-controlled HTML into a documented HTML-accepting option. - Missing security headers, TLS configuration, or other infrastructure findings on clappr.io and the documentation site. - Automated scanner output without a demonstrated impact. ---