Skip to content

Genetec Web Player Developer Guide

Jump to bottom
Andre Lafleur edited this page Dec 24, 2024 · 1 revision

Genetec Web Player Developer Guide

Overview

The Genetec Web Player (GWP) is a JavaScript/TypeScript library designed to embed live and playback video streams from Genetec Security Center™ into custom web applications. It offers advanced video streaming capabilities using WebSockets and Media Source Extensions, providing an easy-to-use API while abstracting the complexities of managing streams, codecs, and security.

This guide provides detailed instructions for integrating the GWP into your application, including setup, authentication, and usage examples for advanced features like PTZ control, timeline management, and diagnostics.

Features

  • Live and Playback Video Streaming: Access real-time and recorded video feeds.
  • Audio Support: Stream AAC audio where supported.
  • PTZ Camera Control: Low-latency Pan-Tilt-Zoom control.
  • Dynamic Stream Selection: Adaptive resolution and bitrate adjustment based on player size.
  • Digital Zoom: Enhance video regions for detailed views.
  • Fisheye Dewarping: Correct fisheye distortions for a traditional PTZ-like experience.
  • Timeline API: Access bookmarks and motion detection events.
  • Diagnostics: Tools for debugging and monitoring.

Prerequisites

  1. Media Gateway Role:

    • The Media Gateway Role must be configured in Security Center.
    • Open ports 80 and 443 for public access.
    • Ensure the Media Gateway and GWP library versions are compatible.

  2. Authentication:

    • Security Center user credentials or pre-generated tokens.

  3. Environment Requirements:

    • Supported Browsers: Chrome, Firefox, Edge, Safari, Internet Explorer 11.
    • Node.js (if using the provided sample server).

  4. Camera GUIDs: Unique identifiers for the cameras you wish to stream.

Installation

1. Add GWP to Your Project

The GWP library can be included in two ways:

Using a Script Tag

<script src="https://<MediaGatewayAddress>/v2/files/gwp.js"></script>

Using a CommonJS Module

const gwp = require('<MediaGatewayAddress>/v2/files/gwp');

2. Verify Version Compatibility

Ensure the GWP library version matches the Media Gateway version. To retrieve the version:

console.log(gwp.version);

Authentication

Token-Based Authentication

The GWP requires a token to establish secure communication with the Media Gateway. Tokens encapsulate user credentials, permissions, and session validity.

Obtaining a Token

Tokens can be obtained via the Media Gateway's /v2/token/{cameraId} endpoint.

API Endpoint:

POST /v2/token/{cameraId}

Headers:

  • Authorization: Basic <Base64(username;sdkCertificate:password)>

Example:

const getTokenFct = async (cameraId) => {
    const response = await fetch(`${mediaGatewayEndpoint}/v2/token/${cameraId}`, {
        credentials: 'include',
        headers: {
            'Authorization': `Basic ${btoa(username + ";" + sdkCertificate + ":" + password)}`
        }
    });

    if (!response.ok) {
        throw new Error(`Failed to fetch token: ${response.statusText}`);
    }

    return await response.text();
};

Important Notes

  • Do Not Hardcode Credentials: Use server-side logic to fetch tokens securely.
  • Token Expiration: Handle token renewal to avoid disconnections.
  • Public Streams: For publicly accessible cameras, you can embed tokens directly, though this is not recommended for sensitive streams.

Creating and Managing the Player

1. Instantiating the Player

Create a player instance by embedding it in a div element on your webpage:

const divContainer = document.getElementById('playerContainer');
const webPlayer = gwp.buildPlayer(divContainer);

2. Starting the Player

To connect the player to a camera:

await webPlayer.start(cameraGuid, mediaGatewayEndpoint, getTokenFct);

Parameters:

  • cameraGuid: The unique identifier of the camera.
  • mediaGatewayEndpoint: The Media Gateway’s public address.
  • getTokenFct: A callback function returning a token.

3. Playing a Live Stream

webPlayer.playLive();

4. Playback Controls

Seek to a Specific Time:

webPlayer.seek(new Date('2023-12-24T10:00:00Z'));

Pause and Resume:

webPlayer.pause();
webPlayer.resume();

Adjust Playback Speed:

webPlayer.setPlaySpeed(2); // Fast-forward at 2x speed

5. Stopping and Disposing the Player

Stop the Stream:

webPlayer.stop();

Dispose the Player:

webPlayer.dispose();

This frees up resources and removes the player from the DOM.

Advanced Features

PTZ Control: Real-World Use Case

Consider a large retail store using PTZ cameras to monitor different sections. A user can program the PTZ to focus on high-traffic areas during peak hours and adjust manually when suspicious activity is detected:

// Move the camera to monitor entrance
const ptz = webPlayer.ptzControl;
ptz.goToPreset(1); // Preset 1 is configured for the main entrance

// Follow a suspicious individual
ptz.startPanTilt(0.3, -0.2); // Pan right and tilt down
setTimeout(() => ptz.stopPanTilt(), 5000); // Stop after 5 seconds

// Zoom in for a closer look
ptz.startZoom(0.5); // Slowly zoom in
setTimeout(() => ptz.stopZoom(), 3000); // Stop after 3 seconds

Timeline API: Real-World Use Case

A security operator in a corporate setting may want to review past events, such as motion detection in restricted areas:

// Set a timeline range to view activity during the night shift
webPlayer.setTimelineRange(new Date('2023-12-23T22:00:00Z'), new Date('2023-12-24T06:00:00Z'));

// Display bookmarks and motion detection events
webPlayer.onTimelineContentUpdated.register(({ events }) => {
    events.forEach(event => {
        if (event.kind === 1) { // Bookmark
            console.log(`Bookmark: ${event.details} at ${event.time}`);
        } else if (event.kind === 0) { // Recording sequence
            console.log(`Motion detected: starts at ${event.time} for ${event.duration}s`);
        }
    });
});

PTZ Control

The GWP supports Pan-Tilt-Zoom (PTZ) control for compatible cameras.

const ptz = webPlayer.ptzControl;
ptz.startPanTilt(0.5, 0.3);  // Start panning and tilting
ptz.stopPanTilt();          // Stop movement
ptz.startZoom(1);           // Zoom in
ptz.stopZoom();             // Stop zooming
ptz.goToPreset(1);          // Move to a preset position

Timeline API

The Timeline API allows you to manage and display playback metadata, such as bookmarks and motion events.

Set Timeline Range:

webPlayer.setTimelineRange(new Date('2023-12-24T00:00:00Z'), new Date('2023-12-25T00:00:00Z'));

Handle Timeline Updates:

webPlayer.onTimelineContentUpdated.register(({ events }) => {
    console.log('Timeline updated:', events);
});

Digital Zoom

Enable and control digital zoom:

const zoom = webPlayer.digitalZoomControl;
zoom.goTo(0.5, 0.5, 2);  // Zoom to the center at 2x
zoom.zoom(3);            // Increase zoom factor
zoom.stop();             // Reset to the full image

Diagnostic Overlay

Toggle diagnostic overlay for troubleshooting:

webPlayer.showDebugOverlay();

Enable GWP logs:

gwp.enableLogs();

Limitations

  1. Audio: Only AAC is supported.
  2. Reverse Playback: Only smooth for MJPEG streams.
  3. Digital Zoom and Dewarping: Limited by camera capabilities and configuration.
  4. CORS: Ensure the Media Gateway is configured to accept the web page’s origin.
  5. Token Expiration: Tokens must be renewed periodically.

Debugging Tips

  • Use Logs: Enable GWP logs to gather detailed information:

    gwp.enableLogs();

  • Check Network Accessibility: Ensure the Media Gateway is reachable from your network.

  • Validate Configuration: Confirm the Media Gateway role and permissions are properly configured in Security Center.

Support

For detailed support, include the following in your request:

  • GWP library version.
  • Security Center version.
  • Relevant logs or error messages.

Contact the Development Acceleration Program (DAP) at [email protected] for assistance.

Clone this wiki locally