chore!: combine into single media-stream-library package (#1085)

Moves the overlay, player, and streams modules into the media-stream-library
package, but as separate exports. This simplifies package management and
moves the two smaller related packages into the main package.

Improves to the way releases work:
- Always have the package version changed when any changes are made
  to the source, and add a verification for this (housekeeping job).
- Release using a workflow trigger, takes the package as it is and
  creates both a GitHub release and publishes to NPM, using the version
  already contained in the source.
- Keep the minified bundle that includes the dependencies outside of
  the dist folder (thereby excluding it from the NPM package). Since
  that bundle is only needed outside of a package system, and then
  we don't need to export it separately.

BREAKING CHANGES:
- `media-overlay-library` and `media-stream-player` packages are no longer
  provided, they are now available from `media-stream-library/overlay` and
  `media-stream-library/player` respectively.
- The format of the minified bundles is changed from IIFE to ES module,
  since this now has baseline support across all modern browsers.

Together these changes allow for simple release flow, where we can
just pick latest main for releases, where the correct version is
already part of source control.

Author: steabert

.github/workflows/publish.yml

@@ -1,26 +1,33 @@
-# Publishes a GitHub release and NPM package for
-# any tag that is pushed to the repository.
-# Tags should be generated automatically by
-# manually running the "release" workflow.
+# Publishes a GitHub release and NPM package for the provided package.
+# Tags are generated automatically on release.
+# The release/publish steps can be skipped (in case of a re-release attempt).
 name: Publish
 
 on:
-  push:
-    branches:
-      - main
-      - 13-stable
+  workflow_dispatch:
+    inputs:
+      gh-release:
+        description: 'Create a github release?'
+        required: true
+        type: boolean
+        default: true
+      npm-publish:
+        description: 'Publish to NPM?'
+        required: true
+        type: boolean
+        default: true
 
 jobs:
   publish:
-    if: ${{ startsWith(github.event.head_commit.message, 'release:') }}
     runs-on: ubuntu-latest
     steps:
       - uses: extractions/setup-just@v1
       - uses: actions/checkout@v4
 
       - name: Extract version number
         id: vars
-        run: echo ::set-output name=version::v$(jq -r .version package.json)
+        run: |
+          echo "version=$(jq -r .version package.json)" >> $GITHUB_OUTPUT
 
       - name: Setup node
         uses: actions/setup-node@v4
@@ -36,54 +43,25 @@ jobs:
           just install
           just build
 
-      - name: Release
+      - name: Create GitHub release
+        if: ${{ inputs.gh-release }}
         id: release
-        uses: actions/create-release@v1
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # provided by Actions
-        with:
-          tag_name: ${{ steps.vars.outputs.version }}
-          release_name: Release ${{ steps.vars.outputs.version }}
-          body_path: CHANGELOG.md
-          draft: false
-          prerelease: false
-
-      - name: Upload media-stream-library
-        uses: actions/upload-release-asset@v1.0.1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ steps.release.outputs.upload_url }}
-          asset_path: streams/dist/media-stream-library.min.js
-          asset_name: media-stream-library.min.js
-          asset_content_type: application/javascript
-
-      - name: Upload media-stream-player
-        uses: actions/upload-release-asset@v1.0.1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ steps.release.outputs.upload_url }}
-          asset_path: player/dist/media-stream-player.min.js
-          asset_name: media-stream-player.min.js
-          asset_content_type: application/javascript
-
-      - name: Upload media-overlay-library
-        uses: actions/upload-release-asset@v1.0.1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        with:
-          upload_url: ${{ steps.release.outputs.upload_url }}
-          asset_path: overlay/dist/media-overlay-library.min.js
-          asset_name: media-overlay-library.min.js
-          asset_content_type: application/javascript
+        run: |
+          yarn pack
+          gh release create v${{ steps.vars.outputs.version }} \
+            --target ${{ github.ref }} \
+            -F CHANGELOG.md \
+            -t "Release v${{ steps.vars.outputs.version }}" \
+            package.tgz overlay/*.min.js* player/*.min.js* streams/*.min.js*
 
-      - name: Deploy NPM packages
+      - name: Deploy to NPM registry
         env:
           NPM_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}
         run: |
-          if [[ $GITHUB_REF =~ alpha|beta ]]; then
-              yarn workspaces foreach --no-private npm publish --tag next
+          if [[ "${{ steps.vars.output.version }}" =~ alpha|beta ]]; then
+              yarn npm publish --tag next
           else
-              yarn workspaces foreach --no-private npm publish --tag latest
+              yarn npm publish --tag latest
           fi

.github/workflows/verify.yml

@@ -109,3 +109,36 @@ jobs:
         run: just build
       - name: Test basic video functionality
         run: scripts/ci-video-test.sh edge
+
+  housekeeping:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Checkout repository@main
+        uses: actions/checkout@v4
+        with:
+          ref: main
+          path: __ref-main
+
+      - name: Check if package.json version was updated
+        run: |
+          this_version=$(jq -r '.version' package.json)
+          if [[ "$this_version" == "null" ]]; then
+            continue
+          fi
+          if [[ ! -f "__ref-main/package.json" ]]; then
+            main_version=""
+          else
+            main_version=$(jq -r '.version' __ref-main/package.json)
+          fi
+          if [[ "$main_version" == "$this_version" ]]; then
+            echo "::error:: package.json version ($main_version) was not updated"
+            exit 1
+          elif ! grep -q "^## $this_version" CHANGELOG.md; then
+            echo "::error:: CHANGELOG.md was not updated with latest version"
+            exit 1
+          else
+            echo "::notice:: package.json updated: $main_version => $this_version"
+          fi

.gitignore

@@ -1,14 +1,12 @@
 # Logs
 *.log
 
-# Coverage directory (tests with coverage)
+# Build/Test
+*.min.js*
 build/
 coverage/
-
-# Bundles
 dist/
-tsconfig.tsbuildinfo
-*.min.js*
+*.tsbuildinfo
 
 # Cypress
 cypress/videos/

CHANGELOG.md

@@ -1,42 +1,19 @@
-## [13.2.0](https://github.com/AxisCommunications/media-stream-library-js/compare/db30d3bda424de8011f46ed5f2d7c79fb8ad69e4..0ff93c1f6edead9ff7fccc5eac21e87b2600e964) (2025-01-07T16:48:02.968Z)
-
-### 🚧 Maintenance
-
-  - **deps**: bump the dependencies group across 1 directory with 3 updates (#1000) ([6997451](https://github.com/AxisCommunications/media-stream-library-js/commit/6997451619516e8311efbe37cce7073534a0b149))
-  - **deps-dev**: bump c8 from 9.1.0 to 10.1.2 (#995) ([b7db610](https://github.com/AxisCommunications/media-stream-library-js/commit/b7db6100dfa535bc0d28598398385db521c29ba2))
-  - **deps-dev**: bump the dev-dependencies group across 1 directory with 8 updates (#1006) ([6e07315](https://github.com/AxisCommunications/media-stream-library-js/commit/6e073153aa747beacf3623fc9abbb02ea06ca865))
-  - **deps-dev**: bump the dev-dependencies group across 1 directory with 15 updates (#989) ([76017bb](https://github.com/AxisCommunications/media-stream-library-js/commit/76017bbff22dfcd3dbdc8551ae448176907ba9fe))
-  - **deps**: bump ws from 8.16.0 to 8.17.1 in the npm_and_yarn group (#981) ([49eaa51](https://github.com/AxisCommunications/media-stream-library-js/commit/49eaa5190ae8469e36556ff971c51549ef018a6c))
-  - **deps-dev**: bump the dev-dependencies group with 5 updates (#938) ([6351e77](https://github.com/AxisCommunications/media-stream-library-js/commit/6351e77108e62e1898a0f3ddf4f6f1ef7a4e0e6b))
-  - update code owners (#934) ([c5db120](https://github.com/AxisCommunications/media-stream-library-js/commit/c5db12049fc2179e294a015628c908ffed4769f6))
-  - **deps**: upgrade to Node.js v20 (#933) ([18c26c4](https://github.com/AxisCommunications/media-stream-library-js/commit/18c26c4ebbc28333ba369da6ff5a08606eae8441))
-  - **deps**: upgrade minor/patch (#932) ([2c2d7a3](https://github.com/AxisCommunications/media-stream-library-js/commit/2c2d7a338c47293ad352a14f0b10b94035cc6e0f))
-  - **deps-dev**: bump jsdom from 23.2.0 to 24.0.0 (#931) ([f8939c9](https://github.com/AxisCommunications/media-stream-library-js/commit/f8939c9ed55b7e648f605ab55913f23e8a53c760))
-  - **deps-dev**: bump the dev-dependencies group with 10 updates (#930) ([c07bfa4](https://github.com/AxisCommunications/media-stream-library-js/commit/c07bfa4b839066b5fb7f4f0bf538b06f37bce180))
-  - allow hoisting to the root level ([49c266f](https://github.com/AxisCommunications/media-stream-library-js/commit/49c266fc0d8a366103e10c54a513a6d1e23729ef))
-  - update workflows ([f461338](https://github.com/AxisCommunications/media-stream-library-js/commit/f461338abc899ff5cf052046f0facbfc43771fd8))
-  - remove eslint-disable comments ([59f0613](https://github.com/AxisCommunications/media-stream-library-js/commit/59f06132ad3d77126f97b7356a6f021bc5104674))
-  - satisfy biome checks ([4e9e041](https://github.com/AxisCommunications/media-stream-library-js/commit/4e9e0410c484465badcd579d0c559325894750a1))
-  - biome import sorting ([0210ee1](https://github.com/AxisCommunications/media-stream-library-js/commit/0210ee17f3976f0b1f066e53e5250606bd0bd91d))
-  - biome formatting ([51318dc](https://github.com/AxisCommunications/media-stream-library-js/commit/51318dc52d5576920f97abbe6600ad7259eb62f6))
-  - use yarn and replace dprint/eslint with biome ([00abee0](https://github.com/AxisCommunications/media-stream-library-js/commit/00abee002c293f0f811fee171013ce5633a33509))
-  - remove git LFS ([5c48be4](https://github.com/AxisCommunications/media-stream-library-js/commit/5c48be4bda7a12f4c430208d0162e88f6971368f))
-  - **deps-dev**: bump the dev-dependencies group with 11 updates (#914) ([8488fae](https://github.com/AxisCommunications/media-stream-library-js/commit/8488fae4b74aa714432996b13fd30c8db05db390))
-  - **deps-dev**: bump jsdom from 22.1.0 to 23.2.0 (#892) ([9f230db](https://github.com/AxisCommunications/media-stream-library-js/commit/9f230db4ce70ef4da727d442ce6a313ccbc71075))
-  - **deps-dev**: bump follow-redirects from 1.15.3 to 1.15.5 (#889) ([c4f72ea](https://github.com/AxisCommunications/media-stream-library-js/commit/c4f72ea8c32a73955549d8f34e7486794d597b43))
-  - **deps-dev**: bump c8 from 8.0.1 to 9.1.0 (#890) ([63e08ac](https://github.com/AxisCommunications/media-stream-library-js/commit/63e08ac687720edd50d78d5df93c73b6b3a4f7ee))
-  - **deps-dev**: bump stylelint from 15.11.0 to 16.1.0 (#891) ([f4efbe7](https://github.com/AxisCommunications/media-stream-library-js/commit/f4efbe7198423768c131be18a2d34c148a48b852))
-  - support merge queues (#893) ([d263395](https://github.com/AxisCommunications/media-stream-library-js/commit/d26339547d42f68c1297af4653c2966169c21322))
-
-### 📝 Documentation
-
-  - add quick install steps for example (#1029) ([998d5e2](https://github.com/AxisCommunications/media-stream-library-js/commit/998d5e2b3c22711d91c566f949d52ad2ca503fcc))
-
-### 🐛 Bug fixes
-
-  - replace npm with yarn for upgrades/releases ([0ff93c1](https://github.com/AxisCommunications/media-stream-library-js/commit/0ff93c1f6edead9ff7fccc5eac21e87b2600e964))
-  - force negative frame durations to zero (#769) ([e6773e7](https://github.com/AxisCommunications/media-stream-library-js/commit/e6773e7ccccec782e655af4dab5c79e51eb67e45))
-
-### 🧪 Test
-
-  - add build verification for Node.js v22 (#1028) ([06968d7](https://github.com/AxisCommunications/media-stream-library-js/commit/06968d7be1d540ae357ba187a1c333465c70217d))
+## 14.0.0-beta.0
+
+- Switched to workflow-based releases with version as part of source.
+  This means that each PR has to have an update of the package.json version
+  number and update the CHANGELOG.md file.
+- **BREAKING**: Move `player` and `overlay` packages into the `media-stream-library` package.
+  These can be imported as `media-stream-library/player` and `media-stream-library/overlay`.
+- **BREAKING**: Only export ES modules (including minified bundles with external dependencies).
+- **BREAKING**: Replaced Node.js Buffer with Uint8Array.
+- **BREAKING**: Replaced Node.js Stream module with Web Streams API.
+  Components and pipelines are redesigned completely, check the source
+  and examples for details on how to migrate.
+- **BREAKING**: Replaced `debug` package with internal log module.
+  Set `msl-streams-debug`, `msl-player-debug`, and `msl-overlay-debug`
+  `localStorage` keys to `"true"` instead for logging.
+- **BREAKING**: Removed CommonJS support and separation of Node.js
+  and Browser exports.
+- Added AAC test audio to the default RTSP H.264 test video.
+ 

LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2018-2023 Axis Communications AB
+Copyright (c) 2018-2025 Axis Communications AB
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,11 +1,89 @@
-# Media streams and overlay
+# Media Stream Library JS
 
-This repository hosts 3 different libraries used for playback
-of video streams and enabling simpler SVG overlays.
+[![CI][ci-image]][ci-url]
+[![NPM][npm-image]][npm-url]
+
+[ci-image]: https://github.com/AxisCommunications/media-stream-library-js/actions/workflows/verify.yml/badge.svg?branch=main
+[ci-url]: https://github.com/AxisCommunications/media-stream-library-js/actions/workflows/verify.yml
+[npm-image]: https://img.shields.io/npm/v/media-stream-library.svg
+[npm-url]: https://www.npmjs.com/package/media-stream-library
+
+## Installation
+
+Make sure you have Node installed on your machine.
+Then, to install the library:
+
+```sh
+npm install media-stream-library
+```
+
+or
+
+```sh
+yarn add media-stream-library
+```
+
+## Usage
+
+- [streams](streams/README.md)
+- [player](player/README.md)
+- [overlay](overlay/README.md)
+
+## Contributing
 
 For development, you'll need a local installation of [Node.js](https://nodejs.org/),
 and [yarn](https://v3.yarnpkg.com/) to install dependencies.
 To run commands, you need [just](https://just.systems/), which can be installed using
 [prebuilt binaries](https://just.systems/man/en/chapter_5.html#pre-built-binaries) or
 [yarn](https://just.systems/man/en/chapter_8.html#nodejs-installation), e.g.
 `yarn global add just-install`.
+
+Please read our [contributing guidelines](CONTRIBUTING.md) before making pull
+requests.
+
+## FAQ
+
+**Will it work with this library if it works with VLC?**
+
+Not necessarily. We only support a particular subset of the protocol useful for
+basic streaming from IP cameras. With RTSP that is H.264+AAC or JPEG, and only
+some simple profiles/levels are supported. For MP4, it depends entirely on your
+browser if the media can be played.
+
+**Do I need to use RTSP for live (or low-latency) video?**
+
+Since this library only supports RTSP through some form of TCP connection, it's
+going to have similar latency as streaming MP4 over HTTP. For true low-latency
+real-time usage, you should either use a stand-alone player that can handle RTP over UDP,
+or use WebRTC in the browser.
+
+You should expect in-browser latency of several frames. When using Firefox, you
+might need to set the duration of the MediaSource to `0` to force live behaviour
+with lower latency (see one of the browser examples).
+The exact latency is controlled by the browser itself, and the data inside the
+media stream can affect this (e.g. if audio is present or not).
+
+**Does this library support audio?**
+
+Yes, yes it does. With a few caveats though.
+
+- Make sure your AXIS camera actually supports audio
+- Make sure the audio is enabled on the camera.
+- It only works with H.264 and only after user interaction with the volume slider
+
+**How do I autoplay video?**
+
+Browsers will only allow to autoplay a video if it's muted. If the video is
+not muted, then it will only play if the `play` method was called from inside
+a handler of a user-initiated event. Note that different browsers can have
+different behaviours. Read https://developer.chrome.com/blog/autoplay for more
+details.
+
+## Acknowledgements
+
+The icons used are from https://github.com/google/material-design-icons/, which
+are available under the Apache 2.0 license, more information can be found on:
+http://google.github.io/material-design-icons
+
+The spinner is from https://github.com/SamHerbert/SVG-Loaders, available under
+the MIT license.