id-scanner-lib 1.6.7 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "id-scanner-lib",
-  "version": "1.6.7",
+  "version": "2.0.0",
   "description": "Browser-based ID card, QR code, and face recognition scanner with liveness detection",
   "main": "dist/id-scanner-lib.js",
   "module": "dist/id-scanner-lib.esm.js",

package/src/compat/index.ts

@@ -0,0 +1,7 @@
+/**
+ * @file Compat Index
+ * @description Compatibility layer for v1 API
+ * @module compat
+ */
+
+export {};

package/src/compat/v1-adapter.ts

@@ -0,0 +1,84 @@
+/**
+ * @file V1 Adapter (Compatibility Layer)
+ * @description Provides backward compatibility with v1 IDScanner API
+ * @module compat/v1-adapter
+ */
+
+import { Scanner, ScannerConfig } from '../core/scanner';
+import { EventEmitter } from '../core/event-emitter';
+
+/**
+ * V1 IDScanner configuration
+ */
+export interface IDScannerConfig {
+  /** Debug mode */
+  debug?: boolean;
+  /** Callback when faces are detected */
+  onFaceDetected?: (faces: any[]) => void;
+  /** Callback on error */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * IDScanner class - provides v1 API compatibility
+ * Wraps the new Scanner class with the old IDScanner interface
+ */
+export class IDScanner {
+  private _scanner: Scanner;
+  private _config: IDScannerConfig;
+  private _eventEmitter: EventEmitter;
+
+  /**
+   * Create a new IDScanner instance
+   * @param config Configuration
+   */
+  constructor(config: IDScannerConfig = {}) {
+    this._config = config;
+    this._scanner = new Scanner({ debug: config.debug });
+    this._eventEmitter = new EventEmitter();
+  }
+
+  /**
+   * Initialize the scanner
+   */
+  async initialize(): Promise<void> {
+    await this._scanner.initialize();
+  }
+
+  /**
+   * Start face recognition on a video element
+   * @param video Video element to process
+   */
+  async startFaceRecognition(video: HTMLVideoElement): Promise<void> {
+    const faces = await this._scanner.detectFace(video);
+    if (this._config.onFaceDetected) {
+      this._config.onFaceDetected(faces);
+    }
+    this._eventEmitter.emit('faceDetected', faces);
+  }
+
+  /**
+   * Stop the scanner and release resources
+   */
+  async stop(): Promise<void> {
+    await this._scanner.destroy();
+  }
+
+  /**
+   * Register an event handler
+   * @param event Event name
+   * @param handler Event handler
+   */
+  on(event: string, handler: (data?: any) => void): void {
+    this._eventEmitter.on(event, handler);
+  }
+
+  /**
+   * Unregister an event handler
+   * @param event Event name
+   * @param handler Event handler
+   */
+  off(event: string, handler: (data?: any) => void): void {
+    this._eventEmitter.off(event, handler);
+  }
+}

package/src/core/camera-manager.ts

@@ -10,6 +10,7 @@ import { ConfigManager } from './config';
 import { Result } from './result';
 import { CameraAccessError, DeviceError } from './errors';
 import { getMediaConstraints } from '../utils';
+import { CameraStreamManager, StreamState } from './camera-stream-manager';
 
 /**
  * 摄像头设备信息
@@ -108,8 +109,8 @@ export class CameraManager extends EventEmitter {
   private readonly config: ConfigManager;
   /** 视频元素 */
   private videoElement: HTMLVideoElement | null = null;
-  /** 媒体流 */
-  private mediaStream: MediaStream | null = null;
+  /** 摄像头流管理器 */
+  private streamManager: CameraStreamManager;
   /** 摄像头状态 */
   private status: CameraStatus = CameraStatus.NOT_INITIALIZED;
   /** 可用的摄像头设备列表 */
@@ -138,6 +139,18 @@ export class CameraManager extends EventEmitter {
     super();
     this.logger = Logger.getInstance();
     this.config = ConfigManager.getInstance();
+    this.streamManager = new CameraStreamManager();
+    
+    // 转发流管理器的轨道结束事件
+    this.streamManager.on('stream:track:ended', () => {
+      this.emit(CameraEvent.TRACK_ENDED);
+      this.stop();
+    });
+    
+    // 转发流管理器的分辨率变化事件
+    this.streamManager.on('stream:resolution:change', (data: any) => {
+      this.emit(CameraEvent.RESOLUTION_CHANGE, data);
+    });
   }
   
   /**
@@ -272,33 +285,20 @@ export class CameraManager extends EventEmitter {
         constraints = getMediaConstraints(width, height, facingMode, frameRate);
       }
       
-      // 获取媒体流
-      this.logger.debug('CameraManager', `Requesting camera access: ${JSON.stringify(constraints)}`);
-      const stream = await navigator.mediaDevices.getUserMedia(constraints);
-      
-      // 停止旧的媒体流
-      this.stopMediaStream();
-      
-      // 设置新的媒体流
-      this.mediaStream = stream;
+      // 使用流管理器启动摄像头
+      const stream = await this.streamManager.start(constraints, this.videoElement);
       
       // 获取实际选择的设备ID
       const videoTrack = stream.getVideoTracks()[0];
       if (videoTrack) {
         this.activeDeviceId = videoTrack.getSettings().deviceId || null;
-        
-        // 监听轨道结束事件
-        videoTrack.onended = this.handleTrackEnded.bind(this);
       }
       
-      // 将流连接到视频元素
+      // 创建视频准备就绪Promise
+      this.createVideoReadyPromise();
+      
+      // 开始播放
       if (this.videoElement) {
-        this.videoElement.srcObject = stream;
-        
-        // 创建视频准备就绪Promise
-        this.createVideoReadyPromise();
-        
-        // 开始播放
         const playPromise = this.videoElement.play();
         if (playPromise) {
           await playPromise;
@@ -342,9 +342,7 @@ export class CameraManager extends EventEmitter {
       return false;
     }
     
-    if (this.videoElement) {
-      this.videoElement.pause();
-    }
+    this.streamManager.pause();
     
     // 暂停帧处理
     this.stopFrameProcessing();
@@ -363,29 +361,18 @@ export class CameraManager extends EventEmitter {
       return false;
     }
     
-    if (this.videoElement && this.videoElement.paused && this.mediaStream) {
-      try {
-        await this.videoElement.play();
-        
-        // 恢复帧处理
-        if (this.frameProcessingEnabled) {
-          this.startFrameProcessing();
-        }
-        
-        this.status = CameraStatus.ACTIVE;
-        this.emit(CameraEvent.RESUME);
-        
-        return true;
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        this.logger.error('CameraManager', `Failed to resume camera: ${errorMessage}`, error instanceof Error ? error : new Error(errorMessage));
-        
-        this.emit(CameraEvent.ERROR, { 
-          error: new CameraAccessError(`Resume failed: ${errorMessage}`) 
-        });
-        
-        return false;
+    const resumed = await this.streamManager.resume();
+    
+    if (resumed) {
+      // 恢复帧处理
+      if (this.frameProcessingEnabled) {
+        this.startFrameProcessing();
       }
+      
+      this.status = CameraStatus.ACTIVE;
+      this.emit(CameraEvent.RESUME);
+      
+      return true;
     }
     
     return false;
@@ -408,8 +395,8 @@ export class CameraManager extends EventEmitter {
       this.videoElement.srcObject = null;
     }
     
-    // 停止媒体流
-    this.stopMediaStream();
+    // 停止流
+    this.streamManager.stop();
     
     this.status = CameraStatus.STOPPED;
     this.emit(CameraEvent.STOP);
@@ -464,7 +451,7 @@ export class CameraManager extends EventEmitter {
   async loadDevices(): Promise<CameraDevice[]> {
     try {
       // 请求媒体设备权限
-      if (!this.mediaStream) {
+      if (!this.streamManager.getStream()) {
         // 短暂获取摄像头权限以列出设备标签
         const tempStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: false });
         
@@ -545,7 +532,7 @@ export class CameraManager extends EventEmitter {
    * 获取当前媒体流
    */
   getMediaStream(): MediaStream | null {
-    return this.mediaStream;
+    return this.streamManager.getStream();
   }
   
   /**
@@ -567,9 +554,9 @@ export class CameraManager extends EventEmitter {
     this.videoElement.playsInline = true; // iOS需要
     this.videoElement.muted = true;
     
-    // 如果已有流，附加到视频元素
-    if (this.mediaStream && this.status === CameraStatus.ACTIVE) {
-      this.videoElement.srcObject = this.mediaStream;
+    // 如果流已活动，附加到视频元素
+    if (this.streamManager.getStream() && this.status === CameraStatus.ACTIVE) {
+      this.videoElement.srcObject = this.streamManager.getStream();
       this.videoElement.play().catch(error => {
         this.logger.error('CameraManager', `Failed to play video: ${error.message}`, error);
       });
@@ -671,8 +658,8 @@ export class CameraManager extends EventEmitter {
   dispose(): void {
     this.stop();
     
-    // 停止并释放媒体流
-    this.stopMediaStream();
+    // 释放流管理器资源
+    this.streamManager.dispose();
     
     if (this.canvas) {
       // 清空 canvas 内容
@@ -695,26 +682,6 @@ export class CameraManager extends EventEmitter {
     this.logger.debug('CameraManager', 'Camera resources disposed');
   }
   
-  /**
-   * 停止媒体流并释放轨道
-   */
-  private stopMediaStream(): void {
-    if (this.mediaStream) {
-      this.mediaStream.getTracks().forEach(track => track.stop());
-      this.mediaStream = null;
-    }
-  }
-  
-  /**
-   * 处理媒体流轨道结束事件
-   */
-  private handleTrackEnded(): void {
-    this.logger.debug('CameraManager', 'Camera track ended');
-    
-    this.emit(CameraEvent.TRACK_ENDED);
-    this.stop();
-  }
-  
   /**
    * 创建视频准备就绪的Promise
    */
@@ -810,4 +777,4 @@ export class CameraManager extends EventEmitter {
       this.logger.error('CameraManager', `Frame processing error: ${errorMessage}`, error instanceof Error ? error : new Error(errorMessage));
     }
   }
-} 
+}

package/src/core/camera-stream-manager.ts

@@ -0,0 +1,318 @@
+/**
+ * @file 摄像头流管理器
+ * @description 管理摄像头视频流的创建、销毁、暂停和恢复
+ * @module core/camera-stream-manager
+ */
+
+import { EventEmitter } from './event-emitter';
+import { Logger } from './logger';
+import { CameraAccessError } from './errors';
+import { Disposable } from '../utils/resource-manager';
+
+/**
+ * 摄像头流状态
+ */
+export enum StreamState {
+  /** 空闲 */
+  IDLE = 'idle',
+  /** 启动中 */
+  STARTING = 'starting',
+  /** 活动中 */
+  ACTIVE = 'active',
+  /** 已暂停 */
+  PAUSED = 'paused',
+  /** 已停止 */
+  STOPPED = 'stopped',
+  /** 错误 */
+  ERROR = 'error'
+}
+
+/**
+ * 摄像头流事件
+ */
+export enum CameraStreamEvent {
+  /** 流启动 */
+  START = 'stream:start',
+  /** 流停止 */
+  STOP = 'stream:stop',
+  /** 流暂停 */
+  PAUSE = 'stream:pause',
+  /** 流恢复 */
+  RESUME = 'stream:resume',
+  /** 流错误 */
+  ERROR = 'stream:error',
+  /** 轨道结束 */
+  TRACK_ENDED = 'stream:track:ended',
+  /** 分辨率变化 */
+  RESOLUTION_CHANGE = 'stream:resolution:change'
+}
+
+/**
+ * 摄像头流管理器接口
+ */
+export interface ICameraStreamManager {
+  /** 获取媒体流 */
+  getStream(): MediaStream | null;
+  /** 是否活动 */
+  isActive(): boolean;
+  /** 获取当前状态 */
+  getState(): StreamState;
+  /** 释放资源 */
+  dispose(): Promise<void>;
+}
+
+/**
+ * 摄像头流管理器
+ * 负责摄像头视频流的生命周期管理
+ */
+export class CameraStreamManager extends EventEmitter implements ICameraStreamManager, Disposable {
+  /** 日志记录器 */
+  private readonly logger: Logger;
+  /** 媒体流 */
+  private mediaStream: MediaStream | null = null;
+  /** 流状态 */
+  private state: StreamState = StreamState.IDLE;
+  /** 视频轨道 */
+  private videoTrack: MediaStreamTrack | null = null;
+  /** 音频轨道 */
+  private audioTrack: MediaStreamTrack | null = null;
+  /** 视频元素引用 */
+  private videoElement: HTMLVideoElement | null = null;
+  /** 是否已暂停（用于pause/resume） */
+  private isPaused: boolean = false;
+
+  /**
+   * 构造函数
+   */
+  constructor() {
+    super();
+    this.logger = Logger.getInstance();
+  }
+
+  /**
+   * 获取媒体流
+   */
+  getStream(): MediaStream | null {
+    return this.mediaStream;
+  }
+
+  /**
+   * 是否活动
+   */
+  isActive(): boolean {
+    return this.state === StreamState.ACTIVE && !this.isPaused;
+  }
+
+  /**
+   * 获取当前状态
+   */
+  getState(): StreamState {
+    return this.state;
+  }
+
+  /**
+   * 启动摄像头流
+   * @param constraints 媒体约束
+   * @param videoElement 可选的视频元素
+   */
+  async start(
+    constraints: MediaStreamConstraints,
+    videoElement?: HTMLVideoElement | null
+  ): Promise<MediaStream> {
+    if (this.state === StreamState.ACTIVE && this.mediaStream) {
+      this.logger.debug('CameraStreamManager', 'Stream already active');
+      return this.mediaStream;
+    }
+
+    this.state = StreamState.STARTING;
+    this.logger.debug('CameraStreamManager', `Requesting camera access: ${JSON.stringify(constraints)}`);
+
+    try {
+      // 停止旧流
+      this.stopStreamOnly();
+
+      // 获取新流
+      const stream = await navigator.mediaDevices.getUserMedia(constraints);
+      this.mediaStream = stream;
+
+      // 获取轨道
+      const tracks = stream.getTracks();
+      this.videoTrack = tracks.find(t => t.kind === 'video') || null;
+      this.audioTrack = tracks.find(t => t.kind === 'audio') || null;
+
+      // 监听轨道结束事件
+      if (this.videoTrack) {
+        this.videoTrack.onended = this.handleTrackEnded.bind(this);
+      }
+
+      // 保存视频元素引用
+      this.videoElement = videoElement || null;
+
+      // 将流连接到视频元素
+      if (this.videoElement) {
+        this.videoElement.srcObject = stream;
+      }
+
+      this.state = StreamState.ACTIVE;
+      this.isPaused = false;
+
+      this.emit(CameraStreamEvent.START, {
+        stream,
+        deviceId: this.videoTrack?.getSettings().deviceId,
+        settings: this.videoTrack?.getSettings()
+      });
+
+      return stream;
+    } catch (error) {
+      this.state = StreamState.ERROR;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      this.logger.error('CameraStreamManager', `Failed to start stream: ${errorMessage}`, error instanceof Error ? error : new Error(errorMessage));
+
+      const cameraError = new CameraAccessError(errorMessage);
+      this.emit(CameraStreamEvent.ERROR, { error: cameraError });
+      throw cameraError;
+    }
+  }
+
+  /**
+   * 停止摄像头流
+   */
+  stop(): void {
+    if (this.state !== StreamState.ACTIVE && this.state !== StreamState.PAUSED) {
+      return;
+    }
+
+    // 停止所有轨道
+    this.stopStreamOnly();
+
+    // 断开视频元素连接
+    if (this.videoElement) {
+      this.videoElement.pause();
+      this.videoElement.srcObject = null;
+      this.videoElement = null;
+    }
+
+    this.state = StreamState.STOPPED;
+    this.isPaused = false;
+
+    this.emit(CameraStreamEvent.STOP);
+  }
+
+  /**
+   * 暂停摄像头流
+   */
+  pause(): void {
+    if (this.state !== StreamState.ACTIVE || this.isPaused) {
+      return;
+    }
+
+    // 暂停视频元素
+    if (this.videoElement) {
+      this.videoElement.pause();
+    }
+
+    this.isPaused = true;
+    this.state = StreamState.PAUSED;
+
+    this.emit(CameraStreamEvent.PAUSE);
+  }
+
+  /**
+   * 恢复摄像头流
+   * @returns 是否成功恢复
+   */
+  async resume(): Promise<boolean> {
+    if (this.state !== StreamState.PAUSED || !this.isPaused) {
+      return false;
+    }
+
+    if (this.videoElement && this.videoElement.paused && this.mediaStream) {
+      try {
+        await this.videoElement.play();
+        this.isPaused = false;
+        this.state = StreamState.ACTIVE;
+
+        this.emit(CameraStreamEvent.RESUME);
+        return true;
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        this.logger.error('CameraStreamManager', `Failed to resume stream: ${errorMessage}`, error instanceof Error ? error : new Error(errorMessage));
+        return false;
+      }
+    }
+
+    return false;
+  }
+
+  /**
+   * 连接到视频元素
+   * @param videoElement 视频元素
+   */
+  attachToVideoElement(videoElement: HTMLVideoElement): void {
+    this.videoElement = videoElement;
+
+    if (this.mediaStream) {
+      videoElement.srcObject = this.mediaStream;
+    }
+  }
+
+  /**
+   * 断开视频元素连接
+   */
+  detachVideoElement(): void {
+    if (this.videoElement) {
+      this.videoElement.pause();
+      this.videoElement.srcObject = null;
+      this.videoElement = null;
+    }
+  }
+
+  /**
+   * 获取视频轨道设置
+   */
+  getVideoSettings(): MediaTrackSettings | null {
+    return this.videoTrack?.getSettings() || null;
+  }
+
+  /**
+   * 获取视频轨道
+   */
+  getVideoTrack(): MediaStreamTrack | null {
+    return this.videoTrack;
+  }
+
+  /**
+   * 释放资源
+   */
+  async dispose(): Promise<void> {
+    this.stop();
+
+    this.videoTrack = null;
+    this.audioTrack = null;
+    this.mediaStream = null;
+    this.state = StreamState.IDLE;
+
+    this.logger.debug('CameraStreamManager', 'CameraStreamManager resources disposed');
+  }
+
+  /**
+   * 停止媒体流（仅停止轨道不断开视频元素）
+   */
+  private stopStreamOnly(): void {
+    if (this.mediaStream) {
+      this.mediaStream.getTracks().forEach(track => track.stop());
+      this.mediaStream = null;
+    }
+
+    this.videoTrack = null;
+    this.audioTrack = null;
+  }
+
+  /**
+   * 处理轨道结束事件
+   */
+  private handleTrackEnded(): void {
+    this.logger.debug('CameraStreamManager', 'Camera track ended');
+    this.emit(CameraStreamEvent.TRACK_ENDED);
+  }
+}