unifi-protect
Version:
A complete implementation of the UniFi Protect API.
105 lines (104 loc) • 5.84 kB
TypeScript
import { EventEmitter } from "node:events";
import type { Nullable } from "./protect-types.js";
import type { ProtectApi } from "./protect-api.js";
import type { ProtectLogging } from "./protect-logging.js";
import { Readable } from "node:stream";
/**
* Options for configuring a livestream session.
*
* @property lens - Optionally specify alternate cameras on a Protect device, such as a package camera.
* @property segmentLength - Optionally specify the segment length, in milliseconds, of each fMP4 segment. Defaults to 100ms.
* @property requestId - Optionally specify a request ID to the Protect controller. This is primarily used for logging purposes.
* @property useStream - If `true`, a Node.js Readable stream interface will be created for consuming raw fMP4 segments instead of using EventEmitter events.
* Defaults to false.
*/
export interface LivestreamOptions {
lens: number;
requestId: string;
segmentLength: number;
useStream: boolean;
}
/**
* This class provides a complete event-driven API to access the UniFi Protect Livestream API endpoint.
*
* 1. Create an instance of the {@link ProtectApi | UniFi Protect API} to connect to the Protect controller.
*
* 2. Create an instance of {@link ProtectLivestream | Protect Livestream} using the API instance above either directly, or through calling
* {@link ProtectApi.createLivestream | createLivestream} method on an instance of {@link ProtectApi} (preferred).
*
* 3. Start a livestream using {@link start}, stop it with {@link stop}, and listen for events.
*
* 3. Listen for `message` events emitted by {@link ProtectLivestream} which provides Buffers containing the raw fMP4 segment data as it's produced by Protect. You can
* alternatively listen individually for the initialization segment or regular fMP4 segments if you'd like to distinguish between the two types of segments.
*
* Those are the basics that gets us up and running.
*/
export declare class ProtectLivestream extends EventEmitter {
private _initSegment;
private _codec;
private _stream;
private api;
private dataHandler;
private errorHandler;
private heartbeat;
private isStopping;
private lastMessage;
private log;
private ws;
private wsStream;
constructor(api: ProtectApi, log: ProtectLogging);
/**
* Start an fMP4 livestream session from the Protect controller.
*
* @param cameraId - Protect camera device ID property from the camera's {@link ProtectTypes.ProtectCameraConfigInterface | ProtectCameraConfig}.
* @param channel - Camera channel to use, indexing the channels array in the camera's {@link ProtectTypes.ProtectCameraConfigInterface | ProtectCameraConfig}.
* @param options - Optional parameters to further customize the livestream session.
*
* @returns Returns `true` if the livestream has successfully started, `false` otherwise.
*
* @remarks Once a livestream session has started, the following events can be listened for (unless you've specified `useStream` in `options`, in which case only the
* `close` event is available):
*
* | Event | Description |
* |---------------|----------------------------------------------------------------------------------------------------------------------------------------------|
* | `close` | Livestream has been closed. |
* | `codec` | The codec and container format in use in the livestream. The codec information will be passed as an argument to any listeners. |
* | `initsegment` | An fMP4 initialization segment has been received. The segment will be passed as an argument to any listeners. |
* | `message` | An fMP4 segment has been received. No distinction is made between segment types. The segment will be passed as an argument to any listeners. |
* | `segment` | A non-initialization fMP4 segment has been received. The segment will be passed as an argument to any listeners. |
*/
start(cameraId: string, channel: number, options?: Partial<LivestreamOptions>): Promise<boolean>;
/**
* Stop an fMP4 livestream session from the Protect controller.
*/
stop(): void;
private launchLivestream;
private processLivestream;
/**
* Retrieve the initialization segment that must be at the start of every fMP4 stream.
*
* @returns Returns a promise that resolves once the initialization segment has been seen, or returning it immediately if it already has been.
*/
getInitSegment(): Promise<Buffer>;
/**
* The initialization segment that must be at the start of every fMP4 stream.
*
* @returns Returns the initialization segment if it exists, or `null` otherwise.
*/
get initSegment(): Nullable<Buffer>;
/**
* The codecs in use for this livestream session.
*
* @returns Returns a string containing the codec information,if it exists, or `null` otherwise.
*
* @remarks Codec information is provided as `codec,container` where codec is either `avc` (H.264) or `hev` (H.265). The container format is always `mp4`.
*
* @example `hev1.1.6.L150,mp4a.40.2`
*/
get codec(): string;
/**
* Retrieve a Node.js Readable stream if `useStream` was set to true (defaults to false) when starting the livestream.
* Otherwise, returns `null`.
*/
get stream(): Nullable<Readable>;
}