{"id":14990290,"url":"https://github.com/stemplayer-js/stemplayer-js","last_synced_at":"2025-04-12T02:11:05.562Z","repository":{"id":164565829,"uuid":"640031062","full_name":"stemplayer-js/stemplayer-js","owner":"stemplayer-js","description":"A streaming, low latency Stem Player Web-Component","archived":false,"fork":false,"pushed_at":"2024-05-22T15:58:53.000Z","size":6638,"stargazers_count":5,"open_issues_count":1,"forks_count":5,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-05-22T17:03:07.155Z","etag":null,"topics":["audio","stemplayer","web-component"],"latest_commit_sha":null,"homepage":"https://stemplayer-js.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stemplayer-js.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-05-12T20:06:30.000Z","updated_at":"2024-05-31T19:51:27.592Z","dependencies_parsed_at":"2023-11-14T22:22:41.817Z","dependency_job_id":"0cb0b4bd-4e0d-4df7-b5dc-c084095f5762","html_url":"https://github.com/stemplayer-js/stemplayer-js","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stemplayer-js%2Fstemplayer-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stemplayer-js%2Fstemplayer-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stemplayer-js%2Fstemplayer-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stemplayer-js%2Fstemplayer-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stemplayer-js","download_url":"https://codeload.github.com/stemplayer-js/stemplayer-js/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248505929,"owners_count":21115354,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["audio","stemplayer","web-component"],"created_at":"2024-09-24T14:19:50.005Z","updated_at":"2025-04-12T02:11:05.538Z","avatar_url":"https://github.com/stemplayer-js.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# \\\u003cstemplayer-js\u003e\n\nA streaming, low latency Stem Player Web-Component\n\n![A Stem Player](./assets/stem-player.png 'Stem Player')\n\n[See this live example of our stem player](https://stemplayer-js.com)\n\nThis webcomponent follows the [open-wc](https://github.com/open-wc/open-wc) recommendation.\n\n## Contributing\n\n\u003e This repo is a subtree split of [our monorepo](https://github.com/firstcoders/stemplayer-js-monorepo). Using a monorepo greatly simplifies development of many packages with dependencies. If you'd like to contribute to the development of stemplayer-js, please create a pull-request there.\n\n## Installation\n\n```bash\nnpm i @stemplayer-js/stemplayer-js\n```\n\n## Usage\n\n```html\n\u003cscript type=\"module\"\u003e\n  import '@stemplayer-js/stemplayer-js/element.js';\n\u003c/script\u003e\n\n\u003cstemplayer-js\u003e\n  \u003cstemplayer-js-controls label=\"A label\"\u003e\u003c/stemplayer-js-controls\u003e\n  \u003cstemplayer-js-stem\n    label=\"Drums A\"\n    src=\"https://your-cdn-com/drums.m3u8\"\n    waveform=\"https://your-cdn-com/drums.json\"\n    volume=\"0.1\"\n  \u003e\n  \u003c/stemplayer-js-stem\u003e\n  \u003cstemplayer-js-stem\n    label=\"Vocals\"\n    src=\"https://your-cdn-com/vocals.m3u8\"\n    waveform=\"https://your-cdn-com/vocals.json\"\n    muted=\"true\"\n    volume=\"0.2\"\n  \u003e\u003c/stemplayer-js-stem\u003e\n\u003c/stemplayer-js\u003e\n```\n\nSee [here for further options, events and CSS variables](./docs/stemplayer-js.md)\n\n# Browser Support\n\nThe Player works in [browsers supporting the Web Audio API](https://caniuse.com/#feat=audio-api). This includes most modern browsers.\n\nThe stem player is built as a [web-component](https://caniuse.com/?search=web%20components) which is supported natively by most modern browsers.\n\nFor targeting older browsers, you can utilise your own build system.\n\n[Polyfills for web-components](https://www.jsdelivr.com/package/npm/@webcomponents/webcomponentsjs) exist for support for older browsers.\n\n# Audio\n\nThe player consumes m3u8 playlist files known from the [HLS protocol](https://en.wikipedia.org/wiki/HTTP_Live_Streaming).\n\nThe audio is split up into chunks and served (over simple HTTP) separately.\n\n**Why HLS and not just download whole files?**\nDownloading and decoding, for example, 10 5minute audio files will consume bandwith and bloat memory: each minute of every audio file worth of mp3 data is decoded into 44k PCM data and will consume roughly 100mb. By using live streaming we not only speed up playback, we also reduce the memory footprint.\n\n**Why not progressive download?**\nWe need to use the web audio API to achieve precise synchronized playback.\n\nSee also\n\n- [https://ffmpeg.org/ffmpeg-formats.html#toc-hls-1](https://ffmpeg.org/ffmpeg-formats.html#toc-hls-1)\n- [https://ffmpeg.org/ffmpeg-formats.html#toc-segment_002c-stream_005fsegment_002c-ssegment](https://ffmpeg.org/ffmpeg-formats.html#toc-segment_002c-stream_005fsegment_002c-ssegment)\n\nSee also this [Docker image](https://github.com/sound-ws/docker-segment-audio) to help you segment your audio.\n\nIf you have an AWS environment, we have also created [a Serverless Backend](https://github.com/stemplayer-js/api) that will do this for you.\n\n# Waveforms\n\nBecause we don't download the entire audio file, we cannot analyse the audio so that we can display a nice waveform. So unfortunately these also need to be pre-generated. Although inconvenient, it is probably good practice anyway as a waveform in json format is very small in size; there is no need to re-compute it time and time again.\n\n[See here for info on how to generate compatible waveforms](https://github.com/bbc/audiowaveform). Make sure you limit the `--pixels-per-second` to around `20`, since by default the library will output that contains too much detail.\n\nThe output will have to be normalized so the waveform will be represented by an array of numbers that is between -1 and +1.\n\nSee here for a [Docker image](https://github.com/sound-ws/docker-generate-waveforms) which should (hopefully) help.\n\nIf you have an AWS environment, we have also created [a Serverless Backend](https://github.com/stemplayer-js/api) that will do this for you.\n\n## Linting and formatting\n\nTo scan the project for linting and formatting errors, run\n\n```bash\nnpm run lint\n```\n\nTo automatically fix linting and formatting errors, run\n\n```bash\nnpm run format\n```\n\n## Testing with Web Test Runner\n\nTo execute a single test run:\n\n```bash\nnpm run test\n```\n\nTo run the tests in interactive watch mode run:\n\n```bash\nnpm run test:watch\n```\n\n## Tooling configs\n\nFor most of the tools, the configuration is in the `package.json` to minimize the amount of files in your project.\n\nIf you customize the configuration a lot, you can consider moving them to individual files.\n\n## Local Demo with `web-dev-server`\n\n```bash\nnpm start\n```\n\nTo run a local development server that serves the basic demo located in `demo/index.html`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstemplayer-js%2Fstemplayer-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstemplayer-js%2Fstemplayer-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstemplayer-js%2Fstemplayer-js/lists"}