chore!: combine into single media-stream-library package

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.

.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/[email protected]
-        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/[email protected]
-        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/[email protected]
-        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" $workspace/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/

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.

example-overlay-react/App.tsx → example-overlay-react/App.jsx

@@ -1,29 +1,26 @@
-import React, { FC, useState } from 'react'
+import React, { useState } from 'react'
 
 import styled from 'styled-components'
 
 import {
-  Area,
-  Coord,
-  CoordArray,
   Foundation,
   Liner,
-} from 'media-overlay-library'
+} from 'media-stream-library/overlay'
 
 import {
   Circle,
   DraggableCircle,
   FastDraggableCircle,
-} from './components/Circle'
-import { Polygon } from './components/Polygon'
-import { Text } from './components/Text'
+} from './Circle'
+import { Polygon } from './Polygon'
+import { Text } from './Text'
 
-const USER_BASIS: Area = [
+const USER_BASIS = [
   [-1, 1], // top left coordinate
   [1, -1], // bottom right coordinate
 ]
 
-const MIDDLE_AREA: Area = [
+const MIDDLE_AREA = [
   [-0.5, 0.5], // top left coordinate
   [0.5, -0.5], // bottom right coordinate
 ]
@@ -35,24 +32,24 @@ const Layers = styled.div`
   border: 1px solid deepskyblue;
 `
 
-const App: FC = () => {
-  const [textPos1, setTextPos1] = useState<Coord>([-1, 0.8])
-  const [textPos2, setTextPos2] = useState<Coord>([-0.4, -0.5])
-  const [textPos3, setTextPos3] = useState<Coord>([-0.5, 0])
-  const [polygonPos, setPolygonPos] = useState<CoordArray>([
+const App = () => {
+  const [textPos1, setTextPos1] = useState([-1, 0.8])
+  const [textPos2, setTextPos2] = useState([-0.4, -0.5])
+  const [textPos3, setTextPos3] = useState([-0.5, 0])
+  const [polygonPos, setPolygonPos] = useState([
     [0.6, 0.1],
     [0.8, 0.2],
     [0.7, 0.5],
     [0.3, 0.2],
   ])
-  const [circle1Pos] = useState<Coord>([-0.3333, 0.3333])
-  const [circle2Pos, setCircle2Pos] = useState<Coord>([0.2, -0.5])
-  const [circle3Pos, setCircle3Pos] = useState<Coord>([-0.5, -0.3001])
+  const [circle1Pos] = useState([-0.3333, 0.3333])
+  const [circle2Pos, setCircle2Pos] = useState([0.2, -0.5])
+  const [circle3Pos, setCircle3Pos] = useState([-0.5, -0.3001])
 
   return (
     <div className="main">
       <header>
-        <h1>Welcome to media-overlay-library</h1>
+        <h1>MSL Overlay Playground</h1>
       </header>
       <p>
         To get started, edit <code>src/App.tsx</code> and save to reload.