# camstreamerlib

> Helper library for CamStreamer ACAP applications.

Latest version **5.0.1** (published 2026-11-19) · ISC license · 0 weekly downloads

## Install

```sh
npm install camstreamerlib
pnpm add camstreamerlib
yarn add camstreamerlib
bun add camstreamerlib
```

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 5.0.1 |
| Published | 2026-11-19 |
| First published | 2020-02-07 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18 |
| Dependencies | 7 |
| Unpacked size | 2.2 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 6 |
| Author | CamStreamer s.r.o |
| Maintainers | camstreamer |
| Keywords | CamStreamer, CamOverlay, CamScripter, Camera, Axis |

## Links

- npm: https://www.npmjs.com/package/camstreamerlib
- Repository: https://github.com/CamStreamer/CamStreamerLib
- Homepage: https://github.com/CamStreamer/CamStreamerLib#readme
- Issues: https://github.com/CamStreamer/CamStreamerLib/issues
- npm.io page: https://npm.io/package/camstreamerlib

## Dependencies (7)

- [ws](https://npm.io/package/ws.md) ^8.18.0
- [zod](https://npm.io/package/zod.md) ^4.6.7
- [undici](https://npm.io/package/undici.md) ^6.28.1
- [adm-zip](https://npm.io/package/adm-zip.md) ^0.6.0
- [type-fest](https://npm.io/package/type-fest.md) ^5.10.0
- [eventemitter2](https://npm.io/package/eventemitter2.md) ^6.4.9
- [fast-xml-parser](https://npm.io/package/fast-xml-parser.md) ^5.3.6

## Alternatives

- [byte-size](https://npm.io/package/byte-size.md) — 2.1M weekly downloads
- [speed-limiter](https://npm.io/package/speed-limiter.md) — 16.0K weekly downloads
- [@powersync/node](https://npm.io/package/@powersync/node.md) — 10.9K weekly downloads
- [@ledgerhq/coin-cardano](https://npm.io/package/@ledgerhq/coin-cardano.md) — 1.0K weekly downloads
- [@jayesol/jayeson.lib.streamfinder](https://npm.io/package/@jayesol/jayeson.lib.streamfinder.md) — 1.0K weekly downloads

## Recent versions

- 5.0.1 (latest) — 2026-11-19
- 5.0.1-5ff3947 (dev-pejchaj) — 2026-11-18
- 5.0.1-5fad3e0 (dev-tichavskyj) — 2026-11-12
- 5.0.0-9647f54 (dev-simekd) — 2026-11-03
- 5.0.0-20ab5c4 (dev-beranovah) — 2026-10-27
- 4.0.33-018c17e (dev-zimmermannj) — 2026-10-07
- 4.0.22-80666b5 (dev-pr) — 2026-06-25
- 4.0.18-431108e7 (pejchaj) — 2026-06-15
- 4.0.17-dev-milestone.3 (dev-milestone) — 2026-06-15
- 4.0.18-dev.4 (dev) — 2026-06-12
- 4.0.0-beta.158 (beta) — 2026-04-07
- 5.0.0-4d910ae — 2026-11-13
- 5.0.0-54e362c — 2026-10-27
- 5.0.0-5bbcf7f — 2026-10-26
- 4.0.37 — 2026-10-23
- … 307 more at https://npm.io/package/camstreamerlib/versions

## README

# CamStreamerLib

Web and Node.js helper library for CamStreamer ACAP applications.

The library is primarily developed for ACAP applications running directly in Axis cameras.

## Installation

```
npm install camstreamerlib
```

## Documentation for ACAP and Camera API

| API                                                | Description                                                                                                            |
| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [VapixAPI](doc/VapixAPI.md)                        | Module to access Axis camera VAPIX interface.                                                                          |
| [CamStreamerAPI](doc/CamStreamerAPI.md)            | Module for easy control of video streaming in the CamStreamer ACAP application (RTMP, HLS, SRT and MPEG-TS protocols). |
| [CamOverlayAPI](doc/CamOverlayAPI.md)              | Module to access CamOverlay API.                                                                                       |
| [CamScripterAPI](doc/CamScripterAPI.md)            | Module to access CamScripter API.                                                                                      |
| [CamSwitcherAPI](doc/CamSwitcherAPI.md)            | Module to access CamSwitcher API.                                                                                      |
| [PlaneTrackerAPI](doc/PlaneTrackerAPI.md)          | Module to access PlaneTracker API.                                                                                     |
| [CamStreamerEvents](doc/ws/CamStreamerEvents.md)   | Module which allows receiving events from CamStreamer ACAP application.                                                |
| [CamOverlayEvents](doc/ws/CamOverlayEvents.md)     | Module which allows receiving events from CamOverlay ACAP application.                                                 |
| [CamSwitcherEvents](doc/ws/CamSwitcherEvents.md)   | Module which allows receiving events from CamSwitcher ACAP application.                                                |
| [PlaneTrackerEvents](doc/ws/PlaneTrackerEvents.md) | Module which allows receiving events from PlaneTracker ACAP application.                                               |

## Documentation for Node.js modules

| Module                                                                            | Description                                                                                                                                                                                                                                                       |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [HttpServer](doc/HttpServer.md)                                                   | Module for processing HTTP requests in your scripts. It also automatically serves up the content from html directory or you can register paths which you can process by your own (e.g. `http://$CAMERA_IP/local/camscripter/proxy/$MY_PACKAGE_NAME/control.cgi`). |
| [VapixEvents](doc/ws/VapixEvents.md)                                              | Module which allows receiving camera events from the VAPIX API.                                                                                                                                                                                                   |
| [CamOverlayDrawingAPI](doc/CamOverlayDrawingAPI.md)                               | Module for easy control of CamOverlay drawing API. For more details on supported video overlay drawing functions see https://camstreamer.com/camoverlay-api1                                                                                                      |
| [CamOverlayPainter](doc/CamOverlayPainter.md)                                     | Contains three modules which makes easier to use CamOverlayDrawingAPI.                                                                                                                                                                                            |
| [CamScripterAPICameraEventsGenerator](doc/CamScripterAPICameraEventsGenerator.md) | Module which allows generating events on an Axis camera. These events can be used for triggers in the Axis camera rule engine (events/actions). It is also an easy way how to integrate events and metadata in VMS systems which support Axis camera events.      |
| [GenetecAgent](doc/GenetecAgent.md)                                               | Module which allows receiving and sending data to Genetec VMS.                                                                                                                                                                                                    |
| [TimeZoneDaemon](doc/TimeZoneDaemon.md)                                           | Module for periodically checking and updating the Node.js process timezone to match the system timezone.                                                                                                                                                          |

</br>

# Examples

| Example                                                                                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                           | Open in browser                                                                        |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| [CamSwitcherEvents](examples/camswitcher-events.html) ([source](https://github.com/CamStreamer/CamStreamerLib/blob/master/examples/camswitcher-events.html))    | Logs every CamSwitcher event. `DeviceConnectClient` (HTTP) backs [CamSwitcherAPI](doc/CamSwitcherAPI.md) to obtain the websocket authorization token, `DeviceConnectWsClient` (websocket) backs [CamSwitcherEvents](doc/ws/CamSwitcherEvents.md), which validates and dispatches the events. Connection state is taken from the `authorization` event.                                                                | [open](https://camstreamer.github.io/CamStreamerLib/examples/camswitcher-events.html)  |
| [PlaneTrackerEvents](examples/planetracker-events.html) ([source](https://github.com/CamStreamer/CamStreamerLib/blob/master/examples/planetracker-events.html)) | Logs every PlaneTracker event. PlaneTracker needs no authorization token — [PlaneTrackerEvents](doc/ws/PlaneTrackerEvents.md) announces the connecting user (`userId` / `userName` / `userPriority`, editable in the form) as the init message instead, so only the websocket client is needed. The continuous `CAMERA_POSITION` and `FLIGHT_LIST` events only update the summary line unless the checkbox is ticked. | [open](https://camstreamer.github.io/CamStreamerLib/examples/planetracker-events.html) |

</br>

# Breaking Changes

<details open>

<summary>from version 4.\*.\* to 5.\*.\* (latest)</summary>

### Breaking changes when moving from version 4.\*.\* to 5.\*.\* (latest)

<hr/>

### Zod Upgraded to v4

The library now depends on `zod` v4 (`^4.6.7`) instead of v3 (fixes [GHSA-mrhx-c7xc-m3w5](https://github.com/advisories/GHSA-mrhx-c7xc-m3w5)). All exported schemas are zod v4 schemas.

-   If your project uses the exported schemas together with its own `zod` (e.g. `z.array(domainIdSchema)`, `schema.extend(...)`, `z.infer<typeof schema>`, form resolvers), upgrade your `zod` to v4 as well. Mixing zod v3 and v4 schemas does not work.
-   Object keys declared as `z.unknown()` / `z.any()` are now required in the inferred types (e.g. `TGuardTour` fields, `postJsonBody` in PlaneTracker events).
-   See the [zod v4 migration guide](https://zod.dev/v4/changelog) for changes in your own schemas.

<hr/>

### TypeScript 5.9 or Newer Required

Exported types (e.g. the camelCase/snake_case types in `CamSwitcherAPI` and `VapixAPI`) are built on `type-fest` v5, which requires TypeScript `>=5.9` with `strict: true` in your `tsconfig.json`.

<hr/>

### VapixEvents Upgraded to eventemitter2 v6

`VapixEvents` now extends `EventEmitter2` from `eventemitter2` v6. Its typings are stricter, e.g. `eventNames()` returns `(string | symbol | event[])[]` instead of `string[]`, so code relying on the old types may need to narrow the values.

<hr/>

### Node.js 18 or Newer Required

`package.json` now declares `"engines": { "node": ">=18" }`.

<hr/>
</details>

<details>

<summary>from version 3.\*.\* to 4.\*.\*</summary>

### Breaking changes when moving from version 3.\*.\* to 4.\*.\*

<hr/>

### ACAP API Class Constructors Updated

All ACAP API classes now **require a client instance to be passed into their constructors** instead of `options` object.

-   This change improves flexibility by allowing you to use either the Node or Web client, depending on your environment.

**Example (before → now)**:

```typescript
// Before
const coApi = new CamOverlayAPI({
    ip?: string;
    port?: number;
    user?: string;
    pass?: string;
    tls?: boolean;
    tlsInsecure?: boolean;
    keepAlive?: boolean
});

// Now
import { DefaultClient } from 'camstreamerlib/web';
import { CamOverlayAPI } from 'camstreamerlib';

// Use DefaultClient in constructor
const coApi = new CamOverlayAPI(
    new DefaultClient()
);

// Or adjust DefaultClient default values with your own
const coApi = new CamOverlayAPI(
    new DefaultClient({
        tls: false,
        tlsInsecure: false,
        host: '127.0.0.1',
        port: 80,
        user: '',
        pass: '',
    })
);
```

### Imports Simplified

Importing from the camstreamerlib is now much easier -> all exports are now re-exported from the root index.js.
You no longer need to import from subpaths.

Example:

```typescript
// Before
import { CamScripterAPI } from 'camstreamerlib/CamScripterAPI';
import { Painter } from 'camstreamerlib/CamOverlayPainter/Painter';
import { DefaultAgent } from 'camstreamerlib/DefaultAgent';

// Now
import { CamScripterAPI } from 'camstreamerlib';
import { Painter } from 'camstreamerlib/node';
import { DefaultClient } from 'camstreamerlib/web';
```

> :information_source: Note: To ensure compatibility, set the module resolution in your web projects tsconfig.json to `"moduleResolution": "bundler"`.

### Classes and Methods Refactored

-   **CameraVapix API** has been renamed to [**VapixAPI**](doc/VapixAPI.md).
-   **DefaultAgent** has been refactored into two separate classes - one for node, one for web as [**DefaultClient**](doc/Client.md)
-   Several method names and parameter names across the library have been updated for consistency and clarity.
-   New API modules and endpoints have been introduced, providing extended functionality and better coverage of the underlying service.

### Stream List Migration

-   `CamStreamerAPI.getStreamList()` and `getStream()` now throw a **`MigrationError`** when old-format (v3) stream data is detected on the camera.
-   `MigrationError` provides four arrays to help you handle the transition: `.valid`, `.old`, `.invalid`, and `.unknown`.

```typescript
import { MigrationError } from 'camstreamerlib';

try {
    const streams = await csApi.getStreamList();
} catch (e) {
    if (e instanceof MigrationError) {
        console.log('Valid streams:', e.valid);
        console.log('Old-format streams needing migration:', e.old);
    }
}
```

### CreatePackage Script Path Changed

-   The path to the `CreatePackage` script changed from `camstreamerlib/CreatePackage.js` to `camstreamerlib/bin/CreatePackage.js`.
-   Update any `package.json` scripts accordingly:

```json
"scripts": {
    "create-package": "node node_modules/camstreamerlib/bin/CreatePackage.js"
}
```

<hr/>
</details>

<details>

<summary>from version 2.\*.\* to 3.\*.\*</summary>

### Breaking changes when moving from version 2.\*.\* to 3.\*.\*

-   CamStreamerlib requiers Node.js version 18 or higher.
-   CamOverlayDrawingAPI tries to reconnect when the websocket is closed. You don't have to do it manually.

    > However, events `open` and `close` are still emitted in case you need to react to them.

-   Files `common.ts`, `Digest.ts`, `HttpRequest.ts` and `WsClient.ts` moved to a folder internal.
-   Removed function `httpRequest()`. Use `sendRequest()` instead. It uses the same interface except for the "noWaitForData" parameter.

> It returns (Response object)[https://developer.mozilla.org/en-US/docs/Web/API/Response] which doesn't contain data by default.
> If you need to wait for data, you can call for example the function `await res.text()`.
> This change affects the function `vapixGet` from (CameraVapix)[doc/CameraVapix.md] too.

<hr/>
</details>

<details>

<summary>from version 1.\*.\* to 2.\*.\**</summary>

### Breaking changes when moving from version 1.\*.\* to 2.\*.\*

-   Renamed file HTTPRequest.ts to HttpRequest.ts
-   Removed deprecated protocol attribute from all options objects (use tls instead).
-   Removed RTSP

    > Previously CameraVapix.ts supported both WebSocket and RTSP.
    > Starting with version 2.0.0, it supports WebSocket only.

-   ServiceID shouldn't be passed to CamOverlayAPI by the options object. Pass it as a parameter.
-   Renamed CamOverlayDrawingAPI event msg to message.
-   Drawing services extracted from CamOverlayAPI.ts to a separate file.

> Please read [CamOverlayAPI](doc/CamOverlayAPI.md) and [CamOverlayDrawingAPI](doc/CamOverlayDrawingAPI.md) for more information.

</details>
</br>

# For Developers

### Publishing to npm repository

Run `npm run publishPackage`.

It will:

-   Require npm user `camstreamer` (prompts login if needed).
-   Run `lint`, `pretty:check`, and `build`.
-   Publish from `master` as `latest`.
-   Publish from other branches as `dev-*` (or `dev`).
-   Refuse `latest` publish if the same version is already on npm or if `package.json` version is not committed.

### Preparing a package to upload to CamScripter

If you want to create your own package and upload it to CamScripter App, you can use the script CreatePackage. It creates a zip file which contains all required files and directories in your package folder. The script accepts source code written either in JavaScript or TypeScript if the package has the correct structure (more information in https://github.com/CamStreamer/CamScripterApp_examples/#readme). To include this script in your package add the following lines in the file package.json:

```json
"scripts": {
    "create-package": "node node_modules/camstreamerlib/bin/CreatePackage.js"
  }
```

By default, the zipped package does not contain node_modules directory. If you want to include it (required when uploading to CamScripter App on Axis camera), add `-includeNodeModules` or `-i` parameter.

If you need to exclude a file or directory add `-exlude=` or `-e=` parameter with comma separated list.

The zip package is created in the current directory. You can choose different location with the `-where=` or `-w=` option.

```json
"scripts": {
    "create-package": "node node_modules/camstreamerlib/bin/CreatePackage.js -i -e=react"
}
```

> :warning: Path to `CreatePackage` script has changed from `camstreamerlib/CreatePackage.js` to `camstreamerlib/bin/CreatePackage.js` (from v.4.0.0)

---
_Source: https://npm.io/package/camstreamerlib · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
