Skip to content
/ reolink-aio-ts Public

A modern, fully-typed TypeScript library for controlling Reolink cameras and NVRs (via Baichuan API)

8 stars 2 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

verheesj/reolink-aio-ts

BranchesTags

Repository files navigation

🎥 Reolink AIO TypeScript

TypeScript License: MIT Node.js Status: Pre-release

A modern, fully-typed TypeScript library for controlling Reolink cameras and NVRs

This project implements Reolink’s private Baichuan API — the same API used by the official Reolink iOS/Android apps and the Reolink CLI. The implementation is informed by and based on the excellent Python project reolink-aio.

Features • Installation • Quick Start • Examples • API • TODO

✨ Features

🎯 Core Functionality

  • ✅ Full TypeScript Support - Complete type safety and IntelliSense
  • ✅ HTTP API Client - Comprehensive REST API implementation
  • ✅ Baichuan API/Protocol - Implements Reolink’s Baichuan API (same as official apps/CLI); real-time push events via TCP
  • ✅ NVR & Camera Support - Works with both standalone cameras and NVR systems
  • ✅ VOD (Video on Demand) - Search, browse, and download recorded clips
  • ✅ Session Management - Automatic token refresh and connection handling
  • ✅ Optimization - Connection pooling, request batching, and response caching
  • ✅ Error Handling - Rich exception hierarchy for robust error management

🔔 Real-Time Events

  • ✅ Motion Detection - Real-time motion alerts via Baichuan
  • ✅ AI Detection - Person, vehicle, pet/animal, face, and package detection
  • ✅ Visitor Detection - Doorbell button press events
  • ✅ State Monitoring - Continuous monitoring of camera states
  • ✅ Event Subscription - Subscribe to push notifications

📹 Video & Media

  • ✅ VOD File Search - Find recordings by time range and event type
  • ✅ Video Download - Download MP4 clips from NVR/cameras
  • ✅ Multiple Streams - Support for main and sub streams
  • ✅ Stream URLs - Generate FLV, RTMP, and RTSP URLs
  • ✅ Snapshot Capture - Get still images from cameras

🎛️ Device Control

  • ✅ IR Lights - Control infrared illumination
  • ✅ Spotlight - Toggle camera spotlight with brightness control
  • ✅ Siren - Activate camera siren/audio alarm (fully working!)
  • ✅ Focus Control - Set camera focus position
  • ✅ Zoom Control - Set camera zoom position
  • ✅ PTZ Control - Pan/Tilt/Zoom operations with presets, patrols, guard positions, and auto-tracking

📊 Device Information

  • ✅ Device Discovery - Automatic NVR/camera detection
  • ✅ Channel Management - Multi-channel support for NVRs
  • ✅ Capability Detection - Automatic feature detection
  • ✅ Model Information - Device model, firmware, hardware version
  • ✅ Network Settings - Port configuration (RTSP, RTMP, ONVIF)

📦 Installation

npm install reolink-aio@next

Note: This package is currently a pre-release. Interfaces and behavior may change between versions. For stability, pin an exact version or wait for a 1.0.0 stable release.

🚀 Quick Start

Basic Connection

import { Host } from 'reolink-aio';

const host = new Host('192.168.1.100', 'admin', 'your-password');

// Connect and fetch device information
await host.getHostData();

console.log(`Connected to: ${host.nvrName}`);
console.log(`Channels: ${host.channelsValue.length}`);

Device Control

import { Host } from 'reolink-aio';

const host = new Host('192.168.1.100', 'admin', 'your-password');
await host.getHostData();

// Control IR lights (Auto mode enables IR, Off disables it)
await host.setIrLights(0, true);  // Enable IR lights
await host.setIrLights(0, false); // Disable IR lights

// Control spotlight/floodlight
await host.setSpotlight(0, true);      // Turn on at current brightness
await host.setSpotlight(0, true, 75);  // Turn on at 75% brightness
await host.setSpotlight(0, false);     // Turn off

// Control siren/audio alarm
await host.setSiren(0, true, 2);    // Sound siren for 2 seconds
await host.setSiren(0, false);      // Stop siren immediately

// Control zoom and focus (for cameras that support it)
await host.setZoom(0, 16);   // Set zoom position (0-33 typically)
await host.setFocus(0, 128); // Set focus position (0-255 typically)

// PTZ control (for cameras with Pan/Tilt/Zoom)
await host.ptzControl(0, 'Left', undefined, 32);  // Move left at speed 32
await host.gotoPreset(0, 'Home');                  // Go to preset position
await host.startPatrol(0);                         // Start auto patrol
await host.setPtzGuard(0, 'set');                  // Set current position as guard
await host.setAutoTracking(0, true);               // Enable auto-tracking

Real-Time Motion Detection

import { Host } from 'reolink-aio';

const host = new Host('192.168.1.100', 'admin', 'your-password');
await host.getHostData();

// Subscribe to events
await host.baichuan.subscribeEvents();

// Monitor motion states
setInterval(async () => {
  await host.getStates();
  
  for (const channel of host.channelsValue) {
    if (host.motionDetected(channel)) {
      console.log(`⚠️  Motion on ${host.cameraName(channel)}!`);
    }
    
    if (host.aiDetected(channel, 'person')) {
      console.log(`👤 Person detected!`);
    }
  }
}, 2000);

Download Video Clips

import { Host } from 'reolink-aio';
import * as fs from 'fs';

const host = new Host('192.168.1.100', 'admin', 'your-password');
await host.getHostData();

// Search for recordings
const startTime = new Date(Date.now() - 3600000); // 1 hour ago
const endTime = new Date();

const clips = await host.requestVodFiles(0, startTime, endTime, true);

// Download the first clip
if (clips.length > 0) {
  const result = await host.downloadVod(
    0,
    clips[0].startTime,
    clips[0].endTime,
    'sub'
  );
  
  fs.writeFileSync('recording.mp4', new Uint8Array(result.data));
  console.log(`Downloaded: ${(result.data.byteLength / 1024 / 1024).toFixed(2)} MB`);
}

📚 Examples

The examples/ directory contains complete, working examples:

Example Description Difficulty
01-basic-connection.ts Connect to camera and display info 🟢 Beginner
02-get-video-clips.ts Search and list VOD recordings 🟢 Beginner
03-motion-monitor.ts Real-time motion/AI detection 🟡 Intermediate
04-download-clips.ts Download MP4 clips from NVR 🟡 Intermediate
05-event-webhook.ts Webhook event receiver 🔴 Advanced
06-scheduled-backup.ts Automated backup system 🔴 Advanced
07-device-control.ts Control IR, spotlight, siren, zoom 🟢 Beginner
08-ptz-control.ts PTZ movement, presets, patrols, tracking 🟡 Intermediate
09-live-streaming.ts Live stream URLs, snapshots, encoding 🟢 Beginner
10-optimization.ts Performance optimization features 🟢 Beginner

Running Examples

# Update credentials in the example file first
npx tsx examples/01-basic-connection.ts

# Enable debug logging
REOLINK_AIO_DEBUG=1 npx tsx examples/03-motion-monitor.ts

🔌 API Reference

Host Class

The main class for interacting with Reolink devices.

Constructor

new Host(
  host: string,           // IP address or hostname
  username: string,       // Username
  password: string,       // Password
  port?: number,          // HTTP port (default: 80 or 443)
  useHttps?: boolean,     // Use HTTPS (default: auto-detect)
  protocol?: string,      // Stream protocol (default: 'rtmp')
  stream?: string,        // Stream quality (default: 'sub')
  timeout?: number        // Request timeout in seconds (default: 60)
)

Core Methods

  • getHostData() - Fetch and cache device information
  • getStates() - Update current states (motion, AI detection, etc.)
  • login() - Manually login (usually automatic)
  • logout() - Logout and end session

State Detection

  • motionDetected(channel) - Check if motion detected
  • aiDetected(channel, objectType) - Check AI detection
    • Supported types: 'person', 'vehicle', 'dog_cat', 'face', 'package'
  • visitorDetected(channel) - Check if doorbell pressed
  • irEnabled(channel) - Check if IR lights enabled

Control Methods

  • setIrLights(channel, enabled) - Control IR illumination
  • setSpotlight(channel, enabled, brightness?) - Control spotlight/floodlight
  • setSiren(channel, enabled, duration?) - Activate siren/audio alarm
  • setFocus(channel, position) - Set focus position (0-255)
  • setZoom(channel, position) - Set zoom position (0-33 typically)

PTZ Methods

  • ptzControl(channel, command?, preset?, speed?, patrol?) - Manual PTZ control
  • gotoPreset(channel, preset) - Move to preset position
  • getPtzPresets(channel) - Get available presets
  • getPtzPatrols(channel) - Get available patrols
  • startPatrol(channel) - Start auto patrol
  • stopPatrol(channel) - Stop auto patrol
  • getPtzPanPosition(channel) - Get current pan position
  • getPtzTiltPosition(channel) - Get current tilt position
  • isPtzGuardEnabled(channel) - Check if guard enabled
  • getPtzGuardTime(channel) - Get guard return time
  • setPtzGuard(channel, command?, enable?, time?) - Configure guard position
  • ptzCalibrate(channel) - Calibrate PTZ
  • isAutoTrackingEnabled(channel) - Check if auto-tracking enabled
  • setAutoTracking(channel, enable?, disappearTime?, stopTime?, method?) - Configure auto-tracking
  • getAutoTrackMethod(channel) - Get tracking method
  • getAutoTrackLimitLeft(channel) - Get left limit
  • getAutoTrackLimitRight(channel) - Get right limit
  • setAutoTrackLimit(channel, left?, right?) - Set tracking limits

Configuration Management

  • getOsdSettings(channel) - Get OSD (On-Screen Display) settings
  • setOsd(channel, namePos?, datePos?, enableWaterMark?) - Set OSD parameters
  • getRecordingSettings(channel) - Get recording settings
  • setRecording(channel, enable) - Enable/disable recording
  • getMdAlarmSettings(channel) - Get motion detection settings
  • setMotionDetection(channel, enable) - Enable/disable motion detection
  • setMdSensitivity(channel, value) - Set motion detection sensitivity (1-50)
  • getAiAlarmSettings(channel, aiType?) - Get AI detection settings
  • setAiSensitivity(channel, value, aiType) - Set AI detection sensitivity (0-100)
  • setAiDelay(channel, value, aiType) - Set AI detection delay (0-8 seconds)
  • getFtpSettings(channel) - Get FTP settings
  • setFtp(channel, enable) - Enable/disable FTP upload
  • getEmailSettings(channel) - Get email settings
  • setEmail(channel, enable) - Enable/disable email notifications
  • getPushSettings(channel) - Get push notification settings
  • setPush(channel, enable) - Enable/disable push notifications
  • getBuzzerSettings(channel) - Get buzzer alarm settings
  • setBuzzer(channel, enable) - Enable/disable buzzer alarm
  • getNetworkSettings() - Get network port settings

Streaming Methods

  • getStreamSource(channel, stream?, check?) - Get live stream URL (auto-selects protocol)
  • getRtspStreamSource(channel, stream?, check?) - Get RTSP stream URL
  • getRtmpStreamSource(channel, stream?) - Get RTMP stream URL
  • getFlvStreamSource(channel, stream?) - Get FLV stream URL
  • getSnapshot(channel, stream?) - Capture still image/snapshot
  • getEncoding(channel, stream?) - Get video encoding (h264/h265)
  • encoding(channel, stream?) - Get cached encoding

Device Information

  • nvrName - Device name
  • isNvrValue - Is NVR?
  • channelsValue - Active channels
  • cameraName(channel) - Get camera name
  • cameraModel(channel) - Get camera model

📋 TODO & Roadmap

High Priority

  • Device Control Commands

    • setIrLights() - Control IR illumination
    • setSpotlight() - Toggle spotlight
    • setSiren() - Activate siren (fully working!)
    • setFocus() - Focus control
    • setZoom() - Digital zoom

  • PTZ (Pan/Tilt/Zoom)

    • ptzControl() - Manual PTZ movement
    • getPtzPresets() - List presets
    • gotoPreset() - Move to preset
    • startPatrol() / stopPatrol() - Auto patrol
    • setPtzGuard() - Guard position control
    • setAutoTracking() - Auto-tracking configuration
    • Position getters and patrol management

  • Video Streaming

    • getStreamSource() - Get live stream URL
    • getRtspStreamSource() - RTSP URLs
    • getRtmpStreamSource() - RTMP URLs
    • getFlvStreamSource() - FLV URLs
    • getSnapshot() - Still image capture
    • getEncoding() - Detect video encoding
    • Stream quality switching
    • Multi-stream support

Medium Priority

  • Advanced Features

    • subscribe() - Webhook subscriptions
    • Privacy mode detection
    • Audio support (two-way)

  • Configuration Management

    • Get/Set OSD settings
    • Get/Set recording schedules
    • Get/Set motion detection settings and sensitivity
    • Get/Set AI detection settings, sensitivity, and delay
    • Get/Set FTP configuration
    • Get/Set email notifications
    • Get/Set push notifications
    • Get/Set buzzer alarm
    • Get network configuration

Low Priority

  • Optimization

    • Connection pooling
    • Request batching
    • Caching layer

  • Testing

    • Integration tests
    • Mock device server
    • Code coverage > 80%

  • Documentation

    • API docs site
    • Video tutorials
    • Migration guide

Completed ✅

  • Basic HTTP API client
  • Baichuan event protocol
  • Device information retrieval
  • Motion/AI detection monitoring
  • VOD file search and listing
  • VOD file download (NVR)
  • Stream URL generation
  • Session management
  • TypeScript types
  • Working examples
  • NVR detection
  • Multi-channel support
  • Device control commands (IR, spotlight, siren, focus, zoom)
  • PTZ control (movement, presets, patrols, guard, auto-tracking)
  • Live streaming (RTSP, RTMP, FLV URLs)
  • Snapshot capture
  • Video encoding detection
  • Baichuan TCP protocol fixes (XML formatting, future cleanup)

📄 License

MIT © starkillerOG

🙏 Acknowledgments

  • Based on the Python reolink_aio library
  • Thanks to the Reolink developer community

About

A modern, fully-typed TypeScript library for controlling Reolink cameras and NVRs (via Baichuan API)

Resources

Readme
Activity

Stars

8 stars

Watchers

0 watching

Forks

2 forks
Report repository

Releases

2 tags

Packages

No packages published

Contributors 2

  •  
  •  

Languages