Skip to content

README_OLD.md

Latest commit

 

History

History
515 lines (408 loc) · 19.5 KB

README_OLD.md

File metadata and controls

515 lines (408 loc) · 19.5 KB

EZVIZ Flutter SDK

A comprehensive Flutter plugin for EZVIZ camera integration with support for device management, live streaming, PTZ control, audio/intercom, recording, Wi-Fi configuration, and more. This plugin provides both native Android/iOS SDK integration and HTTP API access.

pub package License

Looking for a example on how to use this,check out this repo which implements api auth,devvice list getting and display of camera stream https://github.com/akshaynexus/ezviz_flutter_example_app

Features

Native SDK Features (Android/iOS)

  • 🎥 Live Video Streaming - Real-time video playback with native performance
  • 🎮 PTZ Control - Pan, tilt, zoom camera control with circular touch panel
  • 📱 Device Management - Add, remove, and manage EZVIZ devices
  • 🔐 Authentication - Secure login and access token management
  • 📹 Video Playback - Replay recorded videos with enhanced controls
  • 🔧 Video Quality Control - Adjust streaming quality (smooth, balanced, HD, UHD)
  • 🌐 Network Device Support - Connect to local network cameras
  • 🎤 Audio & Intercom - Two-way audio communication (half/full-duplex)
  • 📸 Recording & Screenshots - Capture video recordings and screenshots
  • 📶 Wi-Fi Configuration - Configure device network settings (Wi-Fi, AP, Sound Wave)
  • 🎛️ Enhanced UI Controls - Professional video player interface with full-screen support

HTTP API Features

  • 🔑 Authentication - Login, logout, refresh tokens
  • 📋 Device Management - List, add, remove devices
  • 🎯 PTZ Control - Camera movement and zoom
  • 🚨 Alarm Management - Handle device alarms and notifications
  • ☁️ Cloud Storage - Manage cloud recordings
  • 👥 Sub-Account Management - RAM account operations
  • 🔍 Detector Management - Motion detection settings

Installation

Run this command in the root of your flutter project

flutter pub add ezviz_flutter

Platform Setup

Android Setup

  1. Add the following to your android/app/build.gradle:
android {
    compileSdkVersion 34
    
    defaultConfig {
        minSdkVersion 21
        targetSdkVersion 34
        ndk {
            abiFilters "armeabi-v7a", "arm64-v8a"
        }
    }

    sourceSets {
        main {
            jniLibs.srcDirs = ['libs']
        }
    }
}
  1. Add network permissions to android/app/src/main/AndroidManifest.xml:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WAKE_LOCK"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

iOS Setup

  1. Add the following to your ios/Runner/Info.plist:
<key>NSCameraUsageDescription</key>
<string>This app needs camera access to view EZVIZ cameras</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app needs microphone access for audio streaming and intercom</string>
<key>NSLocalNetworkUsageDescription</key>
<string>This app needs local network access to connect to EZVIZ cameras</string>
<key>NSPhotoLibraryAddUsageDescription</key>
<string>This app needs access to save screenshots and recordings</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs access to the photo library</string>
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>This app needs location access for Wi-Fi configuration</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>This app needs location access for Wi-Fi configuration</string>
  1. Set minimum iOS version to 12.0 in ios/Runner.xcodeproj/project.pbxproj:
IPHONEOS_DEPLOYMENT_TARGET = 12.0;
  1. In Xcode, add capabilities:
    • Access WiFi Information
    • Hotspot Configuration

📚 Examples & Documentation

All example code has been organized into comprehensive documentation. See the docs folder for detailed examples:

🎯 Quick Links to Examples

Feature Example Description
Simple Integration Simple Player Examples EzvizSimplePlayer - 3 lines to get started
Complete SDK Comprehensive SDK Integration Full device management with authentication
Multi-Region Global SDK Support Multi-region deployment and area selection
Advanced Playback Advanced Playback Controls Enhanced video playback with all features
Camera Control PTZ Control Examples Pan-Tilt-Zoom camera control
Audio/Intercom Audio & Intercom Examples Two-way audio communication
WiFi Setup WiFi Configuration Device network configuration
Recording Recording & Screenshots Video recording and image capture
Professional UI Enhanced Video Playback Professional video player interface
Live Streaming Live Streaming Examples Real-time streaming with controls

📖 Complete Documentation

  • Documentation Index - Complete overview of all examples and guides
  • Implementation Levels - From 3-line simple integration to professional implementations
  • Best Practices - Error handling, performance optimization, and resource management
  • Troubleshooting - Common issues and solutions for each feature

Quick Start

🚀 Three Integration Levels

Level 1: Simple Integration (3 lines of code)

Perfect for getting started quickly:

EzvizSimplePlayer(
  deviceSerial: 'YOUR_DEVICE_SERIAL',
  channelNo: 1,
  config: EzvizPlayerConfig(
    appKey: 'YOUR_APP_KEY',
    appSecret: 'YOUR_APP_SECRET',
    accessToken: 'YOUR_ACCESS_TOKEN',
  ),
)

🎯 View Complete Simple Player Examples →

Level 2: Standard Integration

Full-featured implementation with state management:

EzvizSimplePlayer(
  deviceSerial: 'YOUR_DEVICE_SERIAL',
  channelNo: 1,
  config: EzvizPlayerConfig(/* full config */),
  onStateChanged: (state) => handleStateChange(state),
  onError: (error) => handleError(error),
  onPasswordRequired: () => showPasswordDialog(),
)

🎯 View Comprehensive SDK Integration →

Level 3: Advanced Integration

Professional implementations with custom UI and advanced features:

🎯 View All Advanced Examples →

🎯 Choose Your Starting Point

✨ Key Features Available

  • EzvizSimplePlayer: Auto-handles SDK initialization, authentication, and streaming
  • Native SDK Integration: Complete device lifecycle management
  • Multi-Region Support: Global deployment with area selection
  • Advanced Controls: PTZ, audio, recording, WiFi configuration
  • Professional UI: Enhanced player controls and fullscreen support

Configuration

Region/Base URL Configuration

The EZVIZ API endpoints vary by region. Configure the region using the convenient enum-based approach:

Method 1: Global Configuration (Affects all instances)

import 'package:ezviz_flutter/ezviz_flutter.dart';

void main() {
  // Set region globally at app startup
  EzvizConstants.setRegion(EzvizRegion.europe);
  
  // Or use a custom URL for private deployments
  EzvizConstants.setBaseUrl('https://custom.ezvizlife.com');
  
  runApp(MyApp());
}

Method 2: Per-Instance Configuration

For EzvizClient (HTTP API):
// Using region enum (recommended)
final client = EzvizClient(
  appKey: 'YOUR_APP_KEY',
  appSecret: 'YOUR_APP_SECRET',
  region: EzvizRegion.usa,
);

// Or using custom URL
final client = EzvizClient(
  appKey: 'YOUR_APP_KEY',
  appSecret: 'YOUR_APP_SECRET',
  baseUrl: 'https://custom.ezvizlife.com',
);
For EzvizSimplePlayer:
EzvizSimplePlayer(
  deviceSerial: 'YOUR_DEVICE_SERIAL',
  channelNo: 1,
  config: EzvizPlayerConfig(
    appKey: 'YOUR_APP_KEY',
    appSecret: 'YOUR_APP_SECRET',
    region: EzvizRegion.europe,  // Simply specify the region
    // or use baseUrl for custom endpoints
  ),
)

Available Regions (Official EZVIZ Domains)

Region Enum Value Base URL Coverage
India EzvizRegion.india https://iindiaopen.ezvizlife.com India, South Asia
China EzvizRegion.china https://open.ys7.com Mainland China
Europe EzvizRegion.europe https://open.ezvizlife.com European regions
USA/North America EzvizRegion.usa https://apius.ezvizlife.com United States, Canada
Singapore EzvizRegion.singapore https://apiisgp.ezvizlife.com Singapore, Southeast Asia
Americas General EzvizRegion.americas https://isgpopen.ezviz.com General Americas coverage
Russia EzvizRegion.russia https://iruopen.ezvizlife.com Russia, CIS (legacy)
Custom EzvizRegion.custom Use with baseUrl parameter Private deployments

Note: If no region is configured, the library defaults to the Global region endpoint.

Complete API Components

Core Native SDK Integration

EzvizAuthManager

Comprehensive authentication and global SDK management:

  • EzvizAuthManager.getAccessToken() - Get current access token
  • EzvizAuthManager.openLoginPage() - Open native login page
  • EzvizAuthManager.logout() - Logout and clear tokens
  • EzvizAuthManager.getAreaList() - Get available global regions/areas
  • EzvizAuthManager.initGlobalSDK() - Initialize global SDK with area

EzvizDeviceManager

Complete device lifecycle management:

  • EzvizDeviceManager.getDeviceList() - Get paginated device list
  • EzvizDeviceManager.addDevice() - Add device by serial number
  • EzvizDeviceManager.deleteDevice() - Remove device from account
  • EzvizDeviceManager.probeDeviceInfo() - Check if device exists and status
  • EzvizDeviceManager.searchCloudRecordFiles() - Search cloud recordings
  • EzvizDeviceManager.searchDeviceRecordFiles() - Search device recordings
  • EzvizDeviceManager.getDeviceInfo() - Get detailed device information

EzvizPlaybackController

Enhanced playback control with extensions:

  • controller.pausePlayback() - Pause recorded video playback
  • controller.resumePlayback() - Resume paused playback
  • controller.seekPlayback() - Seek to specific time
  • controller.getOSDTime() - Get current playback time
  • controller.setPlaySpeed() - Set playback speed (0.25x to 4x)
  • controller.startLocalRecord() - Start local recording
  • controller.stopLocalRecord() - Stop local recording
  • controller.captureImage() - Capture current frame
  • controller.scalePlayWindow() - Scale playback window

EzvizPlaybackUtils

Playback utilities and helpers:

  • EzvizPlaybackUtils.formatPlaybackTime() - Format time display
  • EzvizPlaybackUtils.calculateProgress() - Calculate progress percentage
  • EzvizPlaybackUtils.progressToTime() - Convert progress to time
  • EzvizPlaybackUtils.getPlaybackSpeeds() - Get available speed options

Enhanced Audio & Intercom

EzvizAudio

Audio and intercom functionality:

  • EzvizAudio.openSound() - Enable audio
  • EzvizAudio.closeSound() - Disable audio
  • EzvizAudio.startVoiceTalk() - Start intercom (half/full-duplex)
  • EzvizAudio.stopVoiceTalk() - Stop intercom

Recording & Media Capture

EzvizRecording

Recording and screenshot features:

  • EzvizRecording.startRecording() - Start video recording
  • EzvizRecording.stopRecording() - Stop video recording
  • EzvizRecording.capturePicture() - Take screenshot
  • EzvizRecording.isRecording() - Check recording status

Network Configuration

EzvizWifiConfig

Wi-Fi configuration management:

  • EzvizWifiConfig.startWifiConfig() - Wi-Fi configuration
  • EzvizWifiConfig.startAPConfig() - AP mode configuration
  • EzvizWifiConfig.stopConfig() - Stop configuration
  • EzvizWifiConfig.setConfigEventHandler() - Handle configuration events

Data Models

Device Information

  • EzvizDeviceInfo - Complete device information
  • EzvizProbeDeviceInfo - Device probe result
  • EzvizCameraInfo - Camera channel information

Authentication & Areas

  • EzvizAccessToken - Access token with expiration
  • EzvizAreaInfo - Global region/area information

Recording & Playback

  • EzvizCloudRecordFile - Cloud recording file information
  • EzvizDeviceRecordFile - Device recording file information
  • PlaybackSpeed - Playback speed option
  • RecordingType - Recording type enumeration (All, Timing, Alarm, Manual)

UI Components

EzvizSimplePlayer

The easiest way to integrate EZVIZ cameras with automatic handling of all functionality:

EzvizSimplePlayer(
  deviceSerial: 'DEVICE_SERIAL',
  channelNo: 1,
  config: EzvizPlayerConfig(
    appKey: 'APP_KEY',
    appSecret: 'APP_SECRET',
    accessToken: 'ACCESS_TOKEN',
    autoPlay: true,
    enableAudio: true,
    enableEncryptionDialog: true,
  ),
  onStateChanged: (state) => print('State: $state'),
  onError: (error) => print('Error: $error'),
)

PTZControlPanel

Circular touch control panel for intuitive PTZ control:

PTZControlPanel(
  size: 250,
  onDirectionStart: (direction) => print('Start $direction'),
  onDirectionStop: (direction) => print('Stop $direction'),
  onCenterTap: () => print('Center tapped'),
)

EnhancedPlayerControls

Professional video player controls:

EnhancedPlayerControls(
  isPlaying: true,
  isRecording: false,
  soundEnabled: true,
  onPlayPause: () => print('Play/Pause'),
  onRecord: () => print('Record'),
  onScreenshot: () => print('Screenshot'),
)

Feature Comparison

Feature HTTP API Native SDK
Device Management ✅ ✅
Live Streaming 🔗 URLs only ✅ Native player
PTZ Control ✅ ✅ Enhanced
Video Playback 🔗 URLs only ✅ Native player
Audio/Intercom ❌ ✅
Recording ❌ ✅
Screenshots ❌ ✅
Wi-Fi Config ❌ ✅
Real-time Events ❌ ✅

Migration from v1.0.2

The new features are fully backward compatible. To use enhanced features:

  1. Update your pubspec.yaml to version ^1.0.4
  2. Import new components: import 'package:ezviz_flutter/ezviz_flutter.dart';
  3. Use new widgets and APIs as needed

Troubleshooting & FAQ

For common issues, troubleshooting steps, and frequently asked questions, see our comprehensive FAQ & Troubleshooting Guide.

Quick Help

Common Error Codes

  • 10001, 10002 → Authentication/Token issues
  • 20008 → Device offline
  • 20020-20023 → Device add/verification issues
  • 30001, 30003 → Network/Server issues

👉 View Complete FAQ & Troubleshooting Guide

Credits and Acknowledgments

This library integrates and builds upon code from several sources:

Native SDK Integration

  • flutter_ezviz: Native Android and iOS SDK implementation for EZVIZ cameras
    • Original native SDK wrapper and player components
    • Device management and PTZ control functionality
    • Core platform channel communication

Enhanced Features

  • ezviz_flutter_cam by thanhdang198
    • Audio and intercom functionality
    • Recording and screenshot capabilities
    • Wi-Fi configuration features
    • Enhanced UI components and controls
    • Advanced playback controls (pause/resume)

We extend our gratitude to the original authors and contributors of these repositories for their excellent work in EZVIZ SDK integration. This library combines the best features from both implementations to provide a comprehensive Flutter plugin for EZVIZ camera integration.

Original Repositories

  • 🔗 ezviz_flutter_cam - Enhanced camera features and UI components
  • 📁 flutter_ezviz - Core native SDK implementation (local source)

API Reference

Core Classes

  • EzvizManager - Main SDK manager (singleton)
  • EzvizAuthManager - Authentication and global SDK management ⭐
  • EzvizDeviceManager - Complete device lifecycle management ⭐
  • EzvizPlayer - Low-level video player widget
  • EzvizSimplePlayer - High-level easy-to-use player widget ⭐
  • EzvizPlayerController - Enhanced player control interface with extensions ⭐
  • EzvizPlaybackUtils - Playback utilities and helpers ⭐
  • EzvizAudio - Audio and intercom management
  • EzvizRecording - Recording and screenshot features
  • EzvizWifiConfig - Wi-Fi configuration management

UI Widgets

  • EzvizSimplePlayer - Complete player solution with auto-handling ⭐
  • PTZControlPanel - Circular PTZ control interface
  • EnhancedPlayerControls - Advanced video player controls

Models & Data Types

Core Models

  • EzvizDeviceInfo - Complete device information with status, capabilities, and camera details
  • EzvizAccessToken - Authentication token with expiration tracking
  • EzvizAreaInfo - Global region/area information for multi-region support
  • EzvizProbeDeviceInfo - Device probe result with availability status
  • EzvizCameraInfo - Individual camera channel information

Recording & Playback

  • EzvizCloudRecordFile - Cloud recording file with metadata
  • EzvizDeviceRecordFile - Device storage recording file
  • PlaybackSpeed - Playback speed option (0.25x to 4x)
  • RecordingType - Enumeration: All, Timing, Alarm, Manual

Configuration

  • EzvizWifiConfigResult - Wi-Fi configuration result with status
  • EzvizWifiConfigMode - Configuration mode: wifi, wave, AP

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Changelog

See CHANGELOG.md for a detailed list of changes.
⚡